docs: add literal strings examples

Move the PEP 675 section to the typing page.

docs: mention LiteralString and related changes in docs

fix: clean internal use of LiteralString

Tested one-off using pyre 0.9.13; however it gives too many differences
compared to mypy to use it at the moment.

The pyre run doesn't currently find LiteralString-related problems,
except the todo at psycopg/sql.py:251, because string.Formatter.parse()
doesn't return a LiteralString upon LiteralString input.

refactor: restrict Query alias to use Composed or SQL instead of Composable

Other Composable subclasses (Identifier, Literal, Placeholder...) don't
make sense as a complete query.

feat: use LiteralString for Query and SQL aliases

Current mypy version probably doesn't do anything with it at the moment.

Merge branch 'async-dns'

test: use the flakey marker in random weight test, instead of a comment

refactor: drop dnspython implementation of resolve_hostaddr_async

Expose the asyncio function in the _dns module, but mark it deprecated,
because the connection perform async resolution on its own.

docs: add documentation about async DNS resolution

Close #259.

test: drop ipaddress lazy load test

The module is now used by psycopg.

feat: don't block on address resolution in async connections

Use the same algorithm implemented in the `_dns` module, but based on
asyncio getaddrinfo: this avoids the need of the external dns package
and works correctly with the /etc/hosts file.

There were problems of resource leaking in Python 3.6, but as psycopg
3.1 is 3.7+ only, let's go for it!

fix; drop check for libpq < 10 to use hostaddr

Hostaddr has been always available (seen in 7.2 documentation...).

fix: drop "char" - character alias

"char", with quotes, is not an alias for character, bpchar is.
Don't rely on regtype to get its alias.

chore: bump version to release 3.0.15

Merge branch 'manylinux2014'

test: test wheel packages using PostgreSQL 14

Now all built packages support SCRAM authentication.

test: verify that we distribute the libpq we want to build

build: cache libpq build

build: build libpq 14 for musllinux packages

Currently Alpine ships with libpq 12, which wouldn't allow to use the
pipeline mode.

Use the system packages for the other libraries, for the moment.

build: build manylinux2014 packages

manylinux_2_24 is soon EOL and 2_28 will be incompatible with many
distributions to come. See <https://github.com/pypa/manylinux/issues/1332>.

Close #124

build: build the libpq from source when building wheels on centos platform

build: set expected sysconfdir in libpq shipped with the binary package

This affects where the pg_service.conf file is looked for.

See https://github.com/psycopg/psycopg2/issues/1365

chore: upgrade libraries to build binary packages

build: add script to build the libpq

Added as it currently is in the psycopg2 project.

chore: upgrade cibuildwheel to 2.6.1

refactor: drop unused variable

test: skip flakey test on package build

Still can't find the reason why this test keeps on failing.

fix: sync pipeline before rollback()

We were syncing it already, but only if we had received a "pipeline
aborted" already. This might be not the case, as probably the tests
test_errors_raised_on_commit which has been failing in CI randomly for
weeks has been trying to say. Other similar branches (e.g. on commit)
don't have the same check for aborted state.

docs: fix a typo in infinity date adaptation section

Merge branch 'fix-315'

fix: raise DataError instead of OverflowError loading intervals too large

This happened only for the binary format, not the text format.

docs: mention different infinity date adaptation in psycopg2 differences pages

See #315

fix: produce consistent error messages on timestamp overflow

- State if the date is too small or too large, not just "not supported".
- Use similar messages in text and binary format.

See #315

fix: produce consistent error messages on date overflow

- State if the date is too small or too large, not just "not supported".
- Use similar messages in text and binary format.
- Avoid an overflow error with the infinity date in Python.

See #315

test: move date-related tests to the date tests class

refactor: rename the no_pqexec param to force_extended

This refers to using the extended query protocol even in cases where the
singe query protocol might have been chosen instead (e.g. because we
don't have parameters to send).

The negative in the param name is confusing, and the reference to the
PQexec function is wrong, because we never use that function (which is
blocking), but rather we choose PQsendQueryParams instead of
PQsendQuery.

Merge branch 'message-0x33'

fix: don't use PQsendQuery in pipeline mode

There is no reason to use it: the only reason to not use
PQsendQueryParams is to send multiple statements, but this is not
possible in pipeline mode anyway.

Using PQsendQuery seems to produce a spurious Close message, which the
libpq is surprised to receive. Issue reported to pgsql-bugs.

https://www.postgresql.org/message-id/CA%2Bmi_8bvD0_CW3sumgwPvWdNzXY32itoG_16tDYRu_1S2gV2iw%40mail.gmail.com

Close #314

test: print notifications received in pipeline demo

Investigating on the conditions causing the messages reported in #314.

fix: use a generic return type to return self

Standardize the var name to _Self, waiting for PEP 0673.

Merge branch 'fix-stream'

test: add test to verify stream+close interaction

fix: restore the connection in usable state after an error in stream()

fix: shorter tracebacks on stream() error

test: add test to reveal unexpected message received

The test fails because we receive a notification:

    message type 0x33 arrived from server while idle

See issue #314.

Merge branch 'fix-copy-escape'

fix(copy): correctly escape non-printable chars

Postgres was doing the right thing with them, but the format was wrong.

perf(copy): avoid to call _write with empty buffer

There is a call per row we can avoid if the formatter is buffering the
data produced.

test: drop unneeded Cursor Row type variable from typing tests

Follow up 2f6e7669f0b32e7a99dd6db0ef41a18af119909f.

doc: fix a typo in pipeline examples

Merge remote-tracking branch 'dlax/pipeline-sync-upon-entering-nested'

test: fix str(Transaction) test relying on a broken behaviour

It was relying on the need of an extra sync fixed in #309.

fix: sync nested pipeline with pending commands upon enter

When entering a nested pipeline and the outer one has pending commands,
we now sync the pipeline. This is probably less surprising at it makes
the implicit transaction from a nested pipeline isolated from the outer
one.

With this, the explicit Sync when entering a transaction is no longer
needed.

Fix #309.

test: add test to show lack of generic connect typing info

See #308.

fix: fix ambiguous query to fetch enum details

The previous query happened to work, but was relying on a joined table
to maintain the order, which is not a documented behaviour.

fix: don't add a cast to text literals

Normally cast is not added to unknown literals, and the text oid is not
usually used. However, when it is, it causes problems. Often Postgres
wants just a literal, not a cast type; for instance, this is not valid:

    NOTIFY foo: 'bar'::text;

test: fix binary timedelta dumping text

We were testing text twice.

test: define the eur unicode char only once

fix: don't emit a comma dumping timedelta objects

The format '-1 day, 23:59:59' is understood OK by PostgreSQL but it's
not documented so it seems unwise to rely on it.

fix: shorter traceback even on COPY statement error

The previous commit only addressed errors raised during transferring
data, not the initial COPY statement.

fix: shorter traceback on COPY error

fix: raise a shorter trackeback on interrupted notify connection

Test: fix mypy 0.941 run

This seems a mypy shortcoming fixed in 0.950 as the CI didn't complain.
The row factory definition was exotic but arguably correct. Not worth
bumping up the min version for it anyway.

Merge remote-tracking branch 'dlax/row-covariant'

fix: only use covariant Row type variable

The real variance of Row type variable is covariant, per definition of
RowMaker (RowMaker[B] is a subtype of RowMaker[A] if B is a subtype of
A; similar to the Box type in [mypy documentation][]).

By dropping the Row type variable from Cursor argument in RowFactory, we
are now able to only use the covariant Row variable (previously Row_co,
now Row). Indeed, RowFactory does not actually depend on Cursor on being
parametrized on Row; rather it's the other way around (Cursor's Row type
variable comes from its row factory).

[mypy documentation]: https://mypy.readthedocs.io/en/latest/generics.html#variance-of-generic-types

fix: use a more generic connection type in {Client,Server}Cursor

This makes them similar to plain Cursor class, i.e. being parametrized
on sync or async connection type, not the row type (which is handled
through the second type variable).

refactor: streamline 'type: ignore' in *Cursor.stream()

Make AsyncCursor code similar to Cursor one.

fix: sync pipeline after tpc_prepare()

This is to get the NotSupported raised directly when calling
tpc_prepare() as expected in test_tpc_disabled().

style: import PipelineStatus members in the module like for other pq enums

perf: micro optimise attribute access to PollingStatus

perf: micro optimise attribute access to ConnStatus

perf: micro optimise attribute access to TransactionStatus

perf: micro optimise attribute access to ExecStatus

perf: micro optimise attribute access to Format

refactor: while 1 -> while True

Brain legacy of ancient Python versions where the latter required a
global lookup.

test: fix for Python 3.11

The f-string expansion of str enums has changed. All the tests in the
maint-3.0 branch were already fixed; this changeset only fixes the new
ones.

Merge branch 'fix-304'

fix: add C Float4 binary dumper

This should hopefully work around issue #304, at least when C is used.
When Python is used we raise an error instead.

Close #304

fix: raise an exception if the struct package is affected by issue #304

Cowardly refuse to transform ones in zeros.

test: Fix implicit f-string conversion to value

Behaviour changed in Python 3.11.

fix: Don't rely on f-string converting str enums in their values

The behaviour seems changed in Python 3.11: now f"%{PyFormat.AUTO}" is
evaluated as `%PyFormat.AUTO` instead of `%s`, for the general hilarity.

fix: fix typo: ingeger

chore: bump version to release 3.0.14

fix: don't barf on errors with blank sqlstate

Such messages are not entirely valid (sqlstate is documented to be
always present), however we receive them after a SHOW HELP in the
PgBouncer admin database.

The SHOW HELP actually does generate a sqlstate `00000` but the message
is somehow parsed incorrectly by the libpq, which goes on to report an
error:

    message contents do not agree with length in message type "N"

See #303. PgBouncer issue reported upstream in
https://github.com/pgbouncer/pgbouncer/issues/718

docs: drop stray reference to psycopg3

Merge branch 'client-side-cursor'

docs: Subtly suggest to use the psycopg.sql module rather than ClientCursor

docs: add documentation for client-side binding cursors

test: test multi-statement parametric queries with client-side binding

fix: set ClientCursor class module to psycopg

feat: add params to Cursor.copy()

test: disable tests throwing copy to executemany in client-side cursors

The async one sometimes gets in an allocation loop. On my laptop it gets
OOM'd quickly. On Github Actions it might be the cause of test taking an
unusually long time.

fix: don't forbid all PQexec queries in client-side cursors

We can still use PQexecParams with an empty list of parameters. This has
advantages, such as the possibility of implementing stream(), and less
faffing with differences between Cursor and ClientCursor.

feat: add ClientCursor.mogrify()

feat: add ClientCursor and AsyncClientCursor classes

test: skip testing random multirange arrays with empty last elements

Previously we were skipping the ones with an empty first element,
because of a known shortcoming in finding the right OID. Now that we
scan the whole array to find all the elements' classes, it's the last
entry which might break dumping.

Merge branch 'fix-301'

fix: allow dumping mixed types list, as long as they use the same dumper

Necessary to dump a mix of ipv4/ipv6 addresses, which result in the same
Postgres type, so it's a legit array.

fix: Raise DataError dumping lists of mixed types

This requires more checking dumping lists, but the alternative is to
guard every single dumper, which is painful as well, and more brittle.

fix: raise DataError if IntDumper tries to dump another type

Allow to dump int subclasses, but not other numeric type, which can lead
to truncation. As seen in #301, the Python implementation truncates; the
c implementation is reporting failing with a TypeError, but on Python
3.8 it raises a deprecation warning instead.

The condition largely happens dumping array of mixed types. However we
should probably test with array of mixed class in a more generic way.

Close #301.