Fix row factory docs examples

Make the row_factory attribute non-nullable

Added a `tuple_row()` factory for completeness. Note that it returns None, not
a callable, and the row_maker on the Transformer hasn't changed. The
signature of RowFactory now allows that.

This
makes simpler to specify the row_factory option on `conn.cursor()`: None
means default (the connection `row_factory`), specifying `tuple_row()`
overrides it to the normal tuplish behaviour.

Drop row_factory param from Connection.execute()

The method is not present on cursor.execute: either it's on both or on
none. Erring on the side of a less complex interface for the moment...

Add namedtuple_row row factory

Implementation for namedtuple class cache and fields name sanitizing is
taken from psycogp2.

Document row factories

We document the row_factory argument of *Connection.execute() as well as
the row_factory attribute on Connection.

We add a new page in advanced section explaining the concepts of row
factories, providing examples and documenting built-in row factories.

Start a 'psycopg3.rows' module with dict_row()

Add row_factory as connection attribute and connect argument

When passing 'row_factory' to connect(), respective attribute will be
set on the connection instance. This will be used as default at cursor
creation and can be overridden with conn.cursor(row_factory=...) or
conn.execute(row_factory=...).

We use a '_null_row_factory' marker to handle None-value passed to
.cursor() or .execute() for disabling the default row factory.

Let Transformer.make_row property's setter accept None

Set up row maker and loaders only once in a server-side cursor lifetime

It wasn't happening once per movement, as I was fearing, but it was happening
exactly twice: once on DECLARE, once on describe_portal(). We actually
don't care about the DECLARE result: it was being set on the cursor only
to detect errors, so now that's done manually.

Fix setting row maker on nextset()

The test was broken and didn't test that the row_factory function was
really called.

Merge branch 'master' into row-factory

Merge branch 'tx-no-auto-loaders'

Don't recalculate loaders when not needed

The case it's not needed is when the new result is guaranteed to have
the same fields as the previous one. This happens querying in single-row
mode and on server-side cursors fetch.

Dropped Transformer.pgresult setter, use set_result

Can pass a boolean to tell it to skip setting row loaders

Fix fetch*() return type annotation on server-side cursors

Add tests to verify row_factory works with server-side cursors too

Merge branch 'master' into row-factory

Merge branch 'server-side-cursors'

Test server-side cursor hold

Default server-side cursor scrollable to not defined

Add documentation for the server-side cursors

Add tests for cursor's row_factory with nextset()

Add row_factory argument to connection.execute()

Move the row maker as a Transformer attribute

Instead of carrying the row maker (_make_row attribute) on the cursor
and possibly calling it to transform each row in cursor methods, we
define a 'make_row' attribute on Transformer that is possibly used in
load_row() and load_rows().

In the Python implementation of Transformer.load_rows(), we use tuple as
as make_row() when the attribute is unset.

In the Cython implementation, we make 'make_row' a plain property with a
'_make_row' attribute under the hood. We finally transform individual or
list of records using self.make_row().

Add constraints to the Row type variable

We constrain Row to be either a Tuple[Any, ...] (for the case no row
factory is in use) or Any (otherwise).

This avoids the artificial cast() in cursor code and will make changes
in followup commits much easier.

Use no row factory in TypeInfo.fetch*()

TypeInfo.fetch() and TypeInfo.fetch_async() delegate results processing
to TypeInfo._fetch() which only handle results as tuples. Therefore, we
build the cursor with no row factory to guarantee this. Still we need to
add a type hint on 'recs' variable because this cannot be inferred (this
fixes the mypy error introduced in previous commits).

Make sue ServerCursor.execute() can be used more than once

Don't clobber error leaving a ServerCursor block with a broken connection

Make row factory optional

We change the default value of row_factory argument in
connection.cursor() to None and thus use a keyword argument.

On cursor side, we only set the '_make_row' attribute if a 'row_factory'
got passed and we guard all possible calls to _make_row() by an
'if self._make_row' to avoid a Python call per row. Note that, on the
other hand, we now need to cast 'row' values to the 'Row' type in order
to satisfy type checking.

The default_row_factory() is now useless and thus dropped.

Add name to the ServerCursor repr()

Of of fixing typos

NamedCursor renamed to ServerCursor

In psycopg2 they are not a separate class as they are in psycopg3.

They still need a mandatory name, but having a name is not their
defining trait.

Specify keyword-only args on Connection and Cursor execute()

Typo fix

Add test for all the documented NamedCursor interface

Fix docs after AsyncConnection.cursor() made non-async

Introduce row_factory option in connection.cursor()

We add a row_factory keyword argument in connection.cursor() and cursor
classes that will be used to produce individual rows of the result set.

A RowFactory can be implemented as a class with a __call__ method
accepting raw values and initialized with a cursor instance; the
RowFactory instance is created when results are available. Type
definitions for RowFactory (and its respective RowMaker) are defined as
callback protocols so as to allow user to define a row factory without
the need for writing a class.

The default row factory returns values unchanged.

AsyncConnection.cursor() is no more async

Even after implementing server-side cursors there is not really a reason
for it to be.

Close correctly named cursors in corner cases

Make sure you can use a named cursor to "steal" a portal

Add docs for Cursor.scroll()

Add scrollable tests

Add named cursor scroll

Add cursor.scroll()

Fix rownumber during iteration in named cursors

Add fetch methods to named cursors

Add Cursor.rownumber attribute

Delete the Postgres cursor when closing a named cursor

Added classes for named cursors

Only execute implemented, with a describe roundtrip to get the
portal description.

Added pgconn.send_describe_prepared, send_describe_portal

You don't want a psycoGP, no

Added set_jsonb_loads/dumps functions to customise JSON adaptation

Dropped dumps function from the Json/Jsonb wrappers.

Added JSON documentation.

Add some docs on TypeInfo and adaptation docs corrections

Expose TypeInfo objects from the `psycopg3.types` package

Register arrays using the TypeInfo object

TypeInfo and subclasses implementations moved together to a dedicated module,
sharing more uniform interface and implementation.

Allow mypy to run from root dir

Added @healthchecks, @ferpection, @abegerho to the backers file

Thank you very much :)

Detect the range oid from the subtype for non-builtins too

Add AdaptersMap.types map

Use the map from the adapters when it's needed to look up for a type
info.

Probably there are other places where to make use of it.

Add py.typed marker file to installed package

Proud to have @yougov backing us!

Fixed comment

Fixed dumping of integer ranges

Dump time and timestamp naive and tz-aware with the respective oids

Using the tz version of the data types is ok enough for most uses,
because Postgres can downgrade the type to naive, but ranges don't have
an implicit cast and the exact type of the range subtype is necessary.

Have a single Range class, not one per subtype

There are two problems here, so this doesn't work. One, which will be
solved, is to have a registry of types attached to an adaptation
context: a TODO in already several places, so this will be solved.
Before that we don't really have a way to find back e.g. the oid of a
custom range on strings starting from Range('a', 'b').

The second problem, more serious, is that Postgres doesn't cast
int4range <-> int8range and tsrange <-> tstzrange. The latter pair can
be solved with a two steps dumper choosing between tz aware and not. The
first I don't have in mind how to solve it: Given Range(1,2) I wouldn't
know if int4 or int8 should be used, and Postgres doesn't seem very
forgiving. Probably we should go unknown.

Added docs for AsyncCursor.stream()

Mypy version bumped to 0.800

Added Cursor.stream() to support fetch in single-row mode

Added a few docstrings on types registry

Run black on the builtin oids

Array dumper ligtened up

Don't fetch a string dumper on init, dropped sub_oid attribute.

Added two-steps dumpers implementation in C too

Don't require a Transformer roundtrip to choose the specific int dumper

They are static object, they require no customisation with the
connection. I don't expect anyone wanting to subclass them; if they
do they will deal with the whole 5 objects.

Added test to verify queries failing if int is dumped as int8 or numeric

I wanted these so badly.

Adapt the dumper used to the value of the objects

Added a second dispatch to allow a dumper to upgrade to a specialised
version. Currently used to dump int to the smallest Postgres type
holding that value and to dump lists of object into typed arrays.

This change allows to write queries more naturally as no ``::int`` cast
should be needed anymore e.g. in date + int or jsonb ->> int.

Only Python implementation; C version to be implemented yet.

Use prepared statements machinery for executemany

Don't use the anonymous prepared statement anymore, as it doesn't allow
to manage different types.

Copyright year bumped

egg-info dirs ignored from the root gitignore file to help ag to skpt
them.

Command used:

    ag -l copyright | xargs sed -i "s/\(.*copyright[^0-9]*\)\([0-9]\+\)\(-[0-9]\+\)\?\(.*Psycopg.*\)/\1\2-$(date +%Y)\4/I"

More uniform names for internal objects

Added tests to detect leaks on copy from

Added leak test for async cursor

Leak and correctness tests separated.

Added random tests for data copy

Declare all loaders to receive an object supporting the buffer interface

There isn't in mypy such an object, so just use `Union[bytes, bytearray,
memoryview]`

Avoid a memory copy passing data from the Transformer to the loaders.

I had started exercising this code path by adding copy tests, but after
dropping the extra copy the same path is now exercised by any select, so
I've stopped doing that.

Allow passing a list of names to copy.set_types()

Also improved TypeRegistry by recognising a type name even if includes
the array marker '[]' and added get_oid() function.

No test for this object as it's considered internal and leveraged by
several other tests, but I'm sure I will regret it.

Don't clobber the exception on rollback error in connection exit

Better integration between C copy functions and C transformer

Added copy Format helpers to handle text/binary differences

Added parallel worker to COPY FROM

Have a background writer to push data down the connection while the main
thread is CPU-bound to encode data.

Use a thread to implement the sync worker, a task to implement the
asyncio one.

End-of-copy logic moved from exit to finish gen

Added some docs about binary parameters/values.

Dropped format argument to cursor: use binary= instead

This should make pretty unneeded to import the Format object in client
code.

Define MAXINT8LEN as a constant

Dropped intermediate dumpers cache in C transformer too

Dropped intermediate C Transformer cache creating loaders

Keep in the instance cache the RowLoader instance.

Less work to create a C Transformer

Don't create a new transformer if the query is repeated on a cursor

Added reference leak test for other fetch methods

Fixed fake string creation: never create \x00 byte

Choose automatically text or binary format using %s placeholders

A format can be enforced using %b or %t placeholders.

Use binary formats dumpers if available, otherwise use text dumpers.
Python str are an exception: prefer text dumper, because it will dump
with format 0, so Postgres can cast the value to any format.

Special-case empty lists to be always dumped as textual unknown '{}' so
that Postgres can cast them into whatever array it fancies.

Transformer.dump_sequence returns a list of formats too

Added xfail to a binary empty array test

Fixing it requires reconsidering how to deal with parameters formats.

Also fixed xpass to make sure to spot the tests to fix after fixing the
above.