fix: lock the connection during a 'notifies()' call

With the previous implementation, it was possible to sneak an execute()
while the generator is consumed. This gives the false impression that
it's possible to use the connection while listening (see #756), which is
false for reason better explored in #757.

Therefore, lock the connection while listening to notifications. If
someone wants to mix commands with listening on the same connection,
they should do it collaboratively with an adequately short notifies()
timeout.

chore: drop pq enums aliases on connection and cursor

Unused in the codebase, and not documented. Only used in the test suite.

Merge pull request #794 from dlax/cursor-stream-chunks

feat: add a size parameter to Cursor.stream()

This triggers results retrieval by chunks from the server, if > 1,
leveraging the "chunked rows mode" from libpq 17.

A new has_stream_chunked() capability is added.

Merge pull request #834 from psycopg/cancel-conn-encoding

fix: typo

Co-authored-by: Denis Laxalde <denis.laxalde@dalibo.com>

feat: add get_error_message() methods

The method is available on PGconn, PGconnCancel, PGresult.

The generic function error_message() is retained only because it was
documented so we don't want to drop it. Internally only the
get_error_message() method is used.

refactor: make PGcancelConn.error_message return bytes

This is more consistent with PGconn and PGresult.

There doesn't seem to be the need of extending pq.misc.error_message as
we never pass it a PGcancelConn object.

Close #781

fix: fix PQclosePortal not supported error message

refactor(tests/crdb): generate sync from async

Merge branch 'pyupgrade'

refactor: remove more types as strings

I.e. all those suggested by pyupgrade --py38-plus.

refactor: use set literals

As suggested by pyupgrade --py38-plus.

chore: upgrade usage lru_cache decorator for Python 3.8+

Merge pull request #832 from psycopg/uniform-annotations

Upgrade annotation syntax to Python 3.8

fix: fix type annotation for Python 3.8

refactor: avoid using types as strings where possible

chore: drop unused import

refactor: drop use of typing.Set

refactor: drop use of typing.Tuple

refactor: drop use of typing.Type

refactor: drop use of typing.Dict

refactor: drop use of typing.List

refactor: drop use of typing.Union

refactor: drop use of typing.Optional

chore: drop vim syntax marker for interface files

Merge pull request #642 from psycopg/none-returning-dumper

Allow dumpers to return None

docs: add documentation about none-returning dumpers

docs: add news entry about none support in dumpers

fix(c): allow dumpers to return none in copy

test: verify that dumpers returning None are used correctly in copy

fix: manage dumpers returning None in nested dumpers

test: verify that dumpers returning None are used correctly in queries

fix: annotate every dumper to return Optional[Buffer]

Even if these classes never return None, this allows to create
subclasses returning None without making Mypy unhappy.

Similarly, annotate quote() methods as returning Buffer to allow
subclasses to return other types.

fix: manage None as return value of Dumper.dump()

These are only the changes suggested by Mypy; no test added to verify
that the code paths actually work.

Only Python test fixed, no C yet.

feat: extend signature of Dumper.dump() to allow returning None

docs: extend on the type info note

feat: add libpq interface to change a password

See https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=a7be2a6c262d5352756d909b29c419ea5e5fa1d9:
> drivers built on top of libpq should expose this function and its
> use should be generally encouraged over doing ALTER USER directly for
> password changes.

The test case assumes that the role connected to postgres has CREATEROLE
rights. If this is not true, the test is skipped.

fix(copy): fix count of chars to escape

We missed to reset the number of chars to escape at every field. As a
consequence, we end up resizing and scanning all the fields after the
first one requiring an escape and allocating a bit more memory than
needed.

chore(deps): bump pypa/cibuildwheel in the actions group

Bumps the actions group with 1 update: [pypa/cibuildwheel](https://github.com/pypa/cibuildwheel).

Updates `pypa/cibuildwheel` from 2.17.0 to 2.18.1
- [Release notes](https://github.com/pypa/cibuildwheel/releases)
- [Changelog](https://github.com/pypa/cibuildwheel/blob/main/docs/changelog.md)
- [Commits](https://github.com/pypa/cibuildwheel/compare/v2.17.0...v2.18.1)

---
updated-dependencies:
- dependency-name: pypa/cibuildwheel
  dependency-type: direct:production
  update-type: version-update:semver-minor
  dependency-group: actions
...

Signed-off-by: dependabot[bot] <support@github.com>

Merge pull request #824

Updates action versions and add dependabot to check monthly for updates

ci: merge all produced artifacts into a single artifact for ease of downloading

ci: updates action versions and add dependabot to check monthly for updates

chore: fix typo in comment

docs: improve docs about query protocols and PgBouncer

fix: use the simple query protocol to execute BEGIN/COMMIT out of pipeline

We started using the extended protocol in e5079184 to fix #350, but,
probably to keep symmetry, we also changed the behaviour out of the
pipeline.

This turns out to be a problem for people connecting to the PgBouncer
admin console. They can use the `ClientCursor`, which tries to use the
simple protocol as much as it can, but they currently have to use
autocommit. With this changeset autocommit shouldn't be needed anymore.
See #808.

Merge pull request #811 from psycopg/refactor-typeinfo

Remove type modifier decoding from Column object

test: adapt type representation tests to crdb and postgres < 15

feat: add Column.type_display

fix: fix representation of bit/varbit columns

fix: improve column type display

Make sure that what displayed is the same displayed by postgres for all
supported types.

refactor(column): remove ColumnData internal object

refactor: dispatch type modifier parsing to type-specific objects

This changeset is enough to pass the current test suite, but probably it
might require some cleanup.

Close #450

style(typeinfo): more modern type annotations

Add instructions for pgbouncer simple query protocol

docs: add README to build the docs

Close #821.

chore: bump psycopg_pool package version to 3.2.2

chore: bump psycopg package version to 3.1.19

ci(macos): test and build macOS packages on M1 runners

Separate macos runners because:

The macos-14 runner can build amd64 images, but doesn't have Python <
3.10.

The macos-12 runner can only build x86_64 images.

Run Postgres from CI rather than from cibuildwheel, as cibw won't use a
docker image on macOS anyway. It makes it more uniform w.r.t. other
runners and doesn't require a "before" script.

Merge pull request #791

Replace SELECT 1 with an empty query

docs(pool): mention running an empty query on check in news file

refactor(pool): replace --ping with empty string

perf(pool): replace SELECT 1 with an empty query

Merge pull request #746 from ankane/copy-performance

Improve performance of copy

perf(copy): only flush at every row on copy on macOS

With some benchmark, it seems that on Linux and Windows performances are worse.
See #746 for details.

test(copy): add minimal copy benchmark framework

Improve performance of copy

fix(pool): avoid possible deadlock (until timeout) on pool closing

With the previous change to avoid finding open connections in the pool
(#784), stopping the worker was moved into the critical section. This
can create a deadlock in case a worker is in the process of obtaining a
new connection, because putting it to the pool requires the lock. The
deadlock only last for the default 5s timeout passed to _stop_workers().

Solve the problem by guarding _add_to_pool() to avoid it to try to add
the connection if the pool is closed.

However, refactor the pool closing sequence too and close the workers
and other resources that now out of the state outside the critical
section to keep the operation running under lock to a minimum.

test: fix running pool tests using Psycopg 3.1

Avoid using Capabilities at import time in the test suite.

Merge branch 'fix-734'

fix(c): solve undefined behaviour caused by unaligned access

Close #734

ci: add test to check for misaligned memory access

fix: fix handling of floating point values for connect_timeout

Merge pull request #780 from dlax/cancel-safe-timeout

feat: add a timeout parameter to Connection.cancel_safe()

refactor: set the meaningful timeout for _try_cancel() as a default

fix: avoid to swallow exceptions in public cancel methods

Only ignore errors in every internal usage, in order to cancel as a best
effort and don't clobber a likely more meaningful exception.

docs: adjust cancel_safe() docstring

docs: reword notes on cancellation

test: more uniform treatment of timeout approx check

refactor: check if cancel safe is implemented via capabilities

test(proxy): use 127.0.0.1 rather than localhost

Try to fix the flakiness shown by deaf_listen() in CI. Maybe there is a
race condition in listen()/connect() but I have also seen problems
related with localhost in the /etc/hosts file and ipv6, so let's first
try this.

feat: add a timeout parameter to Connection.cancel_safe()

This will only work for PGcancelConn, i.e. libpq >= 17, or thanks to
added waiting logic in AsyncConnection's implementation; so we add a
note about the limitation in Connection's documentation.

feat: add libpq interface for retrieving results in chunks

https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=4643a2b265e967cc5f13ffa0c7c6912dbb3466d0

fix(c): fix the goto label in the HAVE_POLL branch of wait_c_impl()

This resolves the following warning when building the extension module:

    $ python psycopg_c/setup.py build_ext -i
    [...]
    building 'psycopg_c._psycopg' extension
    x86_64-linux-gnu-gcc -Wsign-compare -DNDEBUG -g -fwrapv -O2 -Wall -g -fstack-protector-strong -Wformat -Werror=format-security -g -fwrapv -O2 -fPIC -I/home/denis/.local/pgsql/include -I/home/denis/src/psycopg3/.venv/include -I/usr/include/python3.11 -c psycopg_c/_psycopg.c -o build/temp.linux-x86_64-cpython-311/psycopg_c/_psycopg.o
    psycopg_c/_psycopg.c: In function ‘wait_c_impl’:
    psycopg_c/_psycopg.c:1649:1: warning: label ‘error’ defined but not used [-Wunused-label]
     1649 |
          | ^

Merge branch 'cancel-exceptions-swallow'

fix: avoid explicit str() call when logging exception

This was done as paranoia check for Sentry which might uses the repr of
the exception even if we asked for `%s` and therefore might leak
secrets, but frankly it's not our responsibility.

https://github.com/getsentry/sentry-python/issues/2417

refactor: clearer cancel_safe implementation

Avoid catching NotSupported, just check for the libpq version.

Also avoid the half exception handler in `_cancel_gen()`: as in the
legacy branch, warn and ignore any error happening in the outermost
method, without adding an ignore exception policy in an implementation
method.

Close #778.

refactor: drop _try_cancel internal method.

This method was useful before introducing cancel_safe, which is now the
function of choice for internal cancelling.

Also refactor the exception handling to account for possible errors in
`PGcancel.cancel()`, not only in `PGconn.get_cancel()`, to make sure to
not clobber an exception bubbling up with ours, whatever happens to the
underlying connection.

Merge branch 'capabilities'

refactor(capabilities): add caching to capabilities check

refactor(pipeline): use Capabilities to implement is_supported

docs: add capabilities documentation

feat: add psycopg.capability

Close #772

refactor: use consistently the version_pretty() function

feat: add pq.version_pretty() function

Merge branch 'async-to-sync-refactor'

refactor(async-to-sync): rename --convert-all option to --all

chore(async-to-sync): drop --all argument

Working on all inputs is a meaningful default.

refactor(async-to-sync): use pattern matching for more compact tests

refactor(async-to-sync): simpler pattern to convert string literals