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

fix(pool): make sure there are no connection in the pool after close()

The case has been reported in #784. While not easy to reproduce, it
seems that it might be caused by the pool being closed while a worker is
still trying to create a connection, which will be put in the _pool
state after supposedly no other operation should have been performed.

Stop the workers and then empty the pool only after they have stopped to
run.

Also refactor the cleanup of the pool and waiting queue, moving them
to close(). There is no reason why a method called "stop workers" should
empty them, and there is no other code path that use such feature.

Close #784.

test: replace deaf_port fixture with deaf_listen method on proxy

This allows to replace the listening proxy port with a port that blocks
connection and to write more easily cancel timeout tests (as in #780).

tests: fix allow to skip running the pool tests again

`pytest -m not pool` should allow to skip the pool test. However,
because of the attribute access at import time to define the test
marker, import failed as well.

Convert the marker to strings which will be used in a getattr by the
fixture. Extend async-to-sync to convert the pool classes names from the
string too.

test: add missing prepared async tests

Sync and async sides diverged because the async-to-sync check in CI was
pretty much disabled by the lack of the -B.

ci: restore async-to-sync check to check all the files

test(pool): more lenient timeout in reconnect test timings

chore: ignore spelling in html files

These files are generated by cython to display the C code generated...
and are a mess.

Merge pull request #763 from dlax/pg17/non-blocking-pqcancel

Add encrypted and non-blocking cancellation

fix: fix type signature of to_thread() compat

docs: shorten news entry about Connection.cancel_safe()

docs: improve cancel_safe documentation

feat: use non-blocking cancellation upon Copy termination

The logic of Copy termination, in finish(), is reworked so that
connection cancellation is invoked from there directly instead of from
_end_copy_out_gen() as we cannot call async code from the generator.

feat: fall back to cancel() in cancel_safe() for libpq < 17

We run this in a thread executor in the AsyncConnection.
As asyncio's to_thread() is not available in Python 3.8, so we add a
compat layer.

feat: add encrypted and non-blocking cancellation

We introduce Connection.cancel_safe() which uses the encrypted and
non-blocking libpq cancellation API available with PostgreSQL 17. As a
non-blocking entry point, cancel_safe() delegates to a generator function,
namely _cancel_gen(). If the libpq version is too old, the method raises
a NotSupportedError.

CTRL+C handling (in Connection.wait() or Cursor.stream()) also uses the
non-blocking cancellation but falls back to old method if the former is
not supported.

The behavior of cancel() method (either on Connection or
AsyncConnection) is kept unchanged to use the old cancellation API.

feat: add generators.cancel()

This is a PQGenConn generator as the socket for the PGcancelConn needs
to be retrieved after (at least) the first poll() call.

Merge pull request #773 from psycopg/pgbouncer-prepare

Make prepared statements compatible with PgBouncer

feat(prepare): allow setting connection.prepare_max to None

docs(prepare): add note about PgBouncer max prepared statements setting

docs(prepare): add notes about the PgBouncer and prepared statements

feat(prepare): send Close messages to deallocate when possible

This allows for compatibility with PgBouncer, but requires libpq v17 at
least.

refactor(prepare): queue statement names, not SQL commands

refactor(prepare): make maintenance operation a PQGen generator

This will allow us to replace the SQL commands with protocol messages.

docs(readme): fix hyperlink in bullet list

The problem was reported in #775, but the file is not wrong, and
rst2html renders correctly without warnings.

The problem is that the Github reST implementation doesn't get the
hyperlinks indented at bullet list level right.

My preference is to move the links out of the list rather than inserting
the URLs in the flow of the text and get awkward newlines or long lines.

docs: drop spurious word in readme

Close #775

test: fix test suite import on master with Python 3.1

test: fix cancel connection status test on Unix socket connection

Merge branch 'libpq-cancel-nonblocking'