docs: NOTIFY command in uppercase

Merge branch 'copy-writer'

docs(copy): add documentation for COPY Writer objects

refactor: unify code paths to set the rowcount

feat(copy): add 'binary' param to copy object

This allows to write binary format even when the query has executed no
COPY operation.

Notice that now we have introduced tests that convert sample_records
into sample_binary: because small numbers would be dumped to int2, use
values large enough to require int4.

refactor(cursor): rename _set_current_result -> _select_current_result

feat(copy): add FileWriter to write copy data to a file-like object

refactor(copy): rename QueueWriter to QueuedLibpqWriter

perf(copy): use non-thread/task copy writers by default

Further benchmarks show no performance improvement using a writer
thread, and a slight slowdown using a writer async task. If that's the
case we can keep it simpler.

docs: fix docstrings for copy objects

refactor(copy): rename ConnectionWriter to LibpqWriter

The class takes a cursor as input so the previous name was misleading.

refactor(copy): make the writer entirely responsible of the libpq copy state

This way we can create a writer which is entirely independent from the
libpq and the connection, which is useful, for instance, to format a
file with copy data.

feat(copy): add writer param AsyncCursor.copy()

Add async copy writers similar to the sync ones.

feat(copy): add ConnectionWriter

This writer allows direct writing to the libpw, without buffering queue,
and provides the interface for a writer using a libpq connection to
write.

feat(copy): add 'writer' parameter to Cursor.copy()

refactor(copy): add Writer object

This separation of responsibility will allow to:

- create writers that e.g. produce a file rather than writing to a
connection;

- create writers that write directly instead of using a queue (see
https://github.com/psycopg/psycopg/discussions/111 for an example of users
unhappy about that. I still don't see their nervousness justified, but
I'm ok to provide them an escape hatch if it's easy to implement).

refactor(copy) use already looked-up pgconn instead of the connection one

Left out of previous refactoring.

Merge branch 'docs-no-external-modules'

docs: allow to read the libpq definitions from a local file

For the poor souls which don't have external access building the docs.
See #337.

docs: upgrade sphinx version to build docs

The version of furo used is not compatible with the newly available
Sphinx.

docs: fix build with sphinx 5.0

The `no_docstring` argument to `Documenter.add_content()` has been
deprecated in Sphinx 3.4.0 and removed in Sphinx 5.0.

This will not break compatibility with earlier versions, since the
`no_docstring` argument always carried a default value.

https://github.com/sphinx-doc/sphinx/blob/v4.2.0/sphinx/ext/autodoc/__init__.py#L601
https://github.com/sphinx-doc/sphinx/blob/v4.5.0/sphinx/ext/autodoc/__init__.py#L596

docs: move documentation from shapely module docstrings to docs

This avoids the dependency on shapely to build the docs.

docs: move documentation from _dns module docstrings to docs

Allow to build the _dns documentation without importing the module,
which requires external dependencies.

docs: add skip-list to avoid importing external module

In sandboxed environments dnspython doesn't work because it cannot read
`/etc/resolv.conf`/

See #337 for details.

test: fix proxy-based tests confused by the PGHOST env var

test: fix dsn manipulation tests confused by the env vars

Add fixture to clean up the PG* vars from the env and replace them with
the values to test.

docs: fix install instruction in docker to test the pool too

Merge branch 'crdb'

test(crdb): test severity_nonlocalized on CRDB versions supporting it

test(crdb): tweak server-side cursors test to run on CRDB

Server-side cursors are well supported starting from CRDB 22.1.3.

docs: add note to test readme about testing with CRDB

docs(crdb): docs refinements

docs(crdb): add sentence to relate crdb adapters to pg ones

test: fix version check using proper PostgreSQL version schema

Previously to specify "libpq 14.2" it was needed to use 14.0.2.

test(crdb): add tests to expose canceled copy problem

See https://github.com/cockroachdb/cockroach/issues/81559

test(crdb): mark a few tests slow

test(crdb): add random copy test

Tests are currently skipped because of
https://github.com/cockroachdb/cockroach/issues/82792

test(crdb): don't use pg_backend_pid in pool tests

You can express the same test using info.backend_pid, which is supported
from CRDB 22.1.

test(crdb): add "suicide" tests

test(crdb): enable tests depending on backend_pid on CRDB 22.1

docs(crdb): include changes in CRDB 22.1

test(crdb): tag better the skip reason for server-side tests

Still skip all the other DECLARE tests; waiting for a couple of issues
being fixed in CRDB.

test(crdb): add tests related to session termination

test(crdb): use the crdb_skip marker

Enable cancel-based tests on CRDB 22.

test(crdb): accout for backend_pid supported since CRDB 22

test(crdb): add crdb_skip marker

test: allow to mark tests to run only or skip on certain version ranges

docs(crdb): add crdb module docs

fix(crdb): raise NotSupportedError on two-phase commit methods

test(crdb): add tests to test CHANGEFEED together with stream()

refactor(crdb): drop crdb_version; use server_version instead

The server_version returned by CRDB is a misleading dummy. The version
tested is reported as 13.0 but certain features are more akin to
different versions (e.g. lack of range support and different behaviour
w.r.t. unknown/text adaptation).

refactor(crdb) split crdb module into a package

test(crdb): get connection class from fixture to make sure to test CRDB objects

refactor(crdb): don't mix pg and crdb json configuration

fix(crdb): base context transaction tests on DML rather than DDL

On CRDB we may incur in problems caused by the table being dropped.

test(crdb): skip tests with arrays of json[b]

Not supported by CRDB: https://github.com/cockroachdb/cockroach/issues/23468

test: add json[b] arrays dump/load tests

Also refactor tests a bit to unify the json/jsonb in a parametric
format.

test(crdb): skip tests based on missing features

With this changeset, all tests pass or are skipped on CRDB 21.2.10 \o/

test(crdb): fix random tests

- Keep into account the different supported interval range
- Allow for float representation rounding (pre-PG 12 behaviour)
- Run leak tests in transactions to allow to recreate the tables

test(crdb): skip tests where CRDB seems to misread binary numeric values

Reported upstream at https://github.com/cockroachdb/cockroach/issues/82492

test(crdb): adapt text tests

With this changeset, all fast tests pass on CRDB.

fix(crdb): keep into account duplicate oids iterating types in registry

In crdb there are a few aliases (e.g. json -> jsonb oid) which are not
adequately captured by the type's regtype.

fix(crdb): drop spurious quotes from multi-words regtypes

test(crdb): adapt numeric tests

test(crdb): adapt array tests

fix(crdb): pq tests adapted

test(crdb): skip tests relying on pg_backend_pid()

test(crdb): skip transaction tests, deadlocking on CRDB

I guess is it something related to rows locks and rollback. Will ask
upstream.

refactor: add NoneType to abc module

test(crdb): adapt or skip more tests to CRDB

fix(crdb): allow None roundtrip

Specify the TEXT oid for None, otherwise dumping with no context will
fail.

perf: add Transformer.__slots__

feat: allow to customize the oid to dump None

On Postgres >= 10, INVALID_OID is ok, because it has a fallback text
cast. CRDB doesn't have such cast, but can convert implicitly from text
to other types, so TEXT_OID is a better choice.

test(crdb): adapt pipeline tests

Transaction-related tests currently fail.

test(crdb): adapt cursor and error tests to CRDB

test(crdb): fix conninfo tests with crdb

fix(crdb): add generic records dumper/loader

test(crdb): make prepared statements tests portable between PG and CRDB

test: fix skipping versions in parametrized tests

In the previous implementation, all the tests were skipped, because
annotations were added to the function and ended up affecting all
generated tests, not the marked ones only.

fix(crdb): fix type info of CrdbConnection.connect()

It requires specifying entirely the connect() signature because of by #308.

feat(crdb): add psycopg.crdb.connect() function

test(crdb): skip tests for unsupported types

feat(crdb): add CrdbConnection class

Drop the automatic detection of crdb. It seems dangerous to change the
program types based on external factors such as the database connected
to.

Generate and use a crdb-specific types oids map, on which to build the
adapters map.

fix(crdb): fix json adaptation

The function set_json_dumps() now adapts the currently registered
adapter, not the default one, to be able to customize the Json dumper on
CRDB, without resetting its oid to the PostgreSQL standard one, which
CRDB doesn't know.

fix(crdb): configure dumpers to deal correctly with Enum types

test(crdb): adapt datetime tests

test(crdb): add async copy tests

test(crdb): add copy tests

Skip tests from psycopg, because there is no support for copy out and
copy in syntax is different. Data types are different too (int/serial
mean int8) so the binary data samples don't match the format.

test(crdb): skip connection tests which cannot run on CockroachDB

test(crdb): fix most cursor tests to run with CockroachDB

Move some common test markers to the fix_crdb module.

Remaining cursor failing test may require some tweak:

- something with binary parameters
- something with ::text cast added by crdb dumper

test: refactor skipping tests by server version

fix(crdb): allow non-normalized encoding name from the database

CockroachDB returns what stored: "utf_8", "utf-8" etc.

All ConnectionInfo tests pass on crdb.

feat(crdb): cusomize CockroachDB connection

- Add ConnectionInfo.vendor
- Add ConnectionInfo subclassing
- Add CrdbConnectionInfo subclass with crdb_version attribute
- Add 'psycopg.crdb' module with adapters
- Dump strings using the text oid by default on CockroachDB

The latter change might have wider consequences, however crdb casts
strings to other types more easily than what Postgres does. At a glance
it might work; porting the rest of the test suite will tell.

test_adapt tests ported. Tests showing a difference moved to
crdb/test_adapt.

test(crdb): skip TPC tests

test(crdb): add fixture to support CockroachDB test/skip

Merge branch 'codespell-all'

chore: fix typos on previously missed files

ci: run codespell on the entire repo

test: register the pipeline marker consistently with the others

docs: fix a typo in literal string examples