Use the present tense in PoolClosed error messages

Thank you John Aldis! https://twitter.com/johnaldis/status/1478016200634425348

Report if the pool was closed, or never opened, in getconn() error message

Add API docs for pool open method/param.

AsyncConnectionPool.open() made async.

This makes it symmetrical with close(). However it doesn't really do any
async work as it's awkward to call it from init. Something we might do,
if that will be needed, could be to start the scheduler only and use it
to schedule immediately a call to an async _open().

In the future, an anyio-based pool might instead disallow open=True on
init.

See https://github.com/psycopg/psycopg/pull/151 for some discussion
about the topic.

Add open param to pool init

Disallow pool re-opening

There seems to be no use case for re-opening a closed pool, so disable
this now (until we find a real use-case).

Factor out a _stop_workers() method on connection pool classes

The method is symmetrical with open().
In particular, we take advantage of this method in
ConnectionPool.__del__() to remove some duplication.

Reset workers state in *ConnectionPool.close()

This way, the pools may be re-opened after a close, even if we'll
disallow this later on.

Add an open() method to connection pool classes

This method is responsible for setting the '_closed' attribute, which
hence now defaults to True in the base class, along with the
_sched_runner attribute, which is reset to None in close().

Remove occurrences of "thread" term in pool_async

There is no threading involved here, only async tasks. Adjust comments
and docstrings to avoid confusion.

Separate pool packages building into a different workflow

Psycopg and pool releases are separate.

Bump pool minor version to start adding features

Hopefully more robust test to identify a closed connection

Merge branch 'executemany-returning'

Add returning parameter on executemany()

Keep results from all queries run through executemany()

Instead of overwriting cursor's results at each execution in
executemany() we now accumulate the results of all queries on cursor
state by turning _set_results() into _extend_results(). This way, each
result remains accessible and one can use nextset() to move from one
result to another.

Drop unneeded method signatures in docs

Rename a couple of internal cursor methods for clarity

Refactor cur._raise_from_results() into _raise_for_result()

The case of raising with different statuses doesn't practically happen.

Drop Cursor._set_results()

Split it into a _check_results() and leave the caller manage the cursor state.

Shorten traceback on executemany

Fix typo in comment

Fix test suite to run on database in locales different from English

Note in news file that 3.0.8 is still unreleased

Fix spurious warning about variable referenced before assignment

Add flake8 configuration in other package dirs

Vim ALE is confused otherwise. I don't really get how is that it picks
the package directory as the starting one (maybe it finds the setup.py)?

Change type of `wait` in `pool_async.py`

Will become an incompatible type in assignment with the release of
https://github.com/python/typeshed/pull/6783

Fix py_codecs data type

It doesn't contain str anymore since 3.0.4.

A stricter definition revealed a couple of wrong usages of the mapping.
Use more consistently the higher level `conninfo_encoding()` function
instead of directly the mapping.

Use conninfo encoding to encode errors on connection

PostgreSQL returns connection errors in the encoding specified in
lc_messages (e.g. EUC-JP for a server with `lc_messages=ja_JP.EUC-JP`).
However, because we don't have a connection, the message was decoded in
the fallback utf-8.

If the client has specified a client_encoding, use it to decode the
error message. Be more lenient than usual to look up the encoding
(because it is not normalised by the server and we don't care about
performance as this only happens on error handling). As for any other
error messages, still use an error=replace policy to avoid exploding
reporting an error in the wrong encoding.

Close #194.

Fix typo: a raw data -> raw data

Fix doc link to transactions management

Also, "transactions", not "transaction".

Add note about installing libpq via psql

Merge branch 'dependencies-bounds'

Add constraint file to test dependencies minimum version

Specify test/dev dependencies only at minor level

Where possible. pytest 6.2.5 is required by Python 3.10.

Specify lower bound for required backport packages

Remove upper bound from dependencies

Giving upper bounds to libraries creates problems if there are
transitive dependencies.

Our dependencies are only on dev/test time, but I'd rather get the
habit.

Schedule a daily test run and a weekly package run

This should help detecting breakages due to new depending packages. In
the future we may extend the tests to run on Python/Postgres master
branch too.

The intention is to remove the top bound from dependency packages,
because the practice is widely documented to be problematic. Thankfully
we have only dev/test dependencies, but I'd rather get the habit for
good.

This commit will be merged on master as it is because otherwise Github
won't pick the change.

Fix typos and grammar in documentation.

Avoid mypy version 0.930

The release is affected by the issues:

- https://github.com/python/mypy/issues/11820
- https://github.com/python/typeshed/issues/6661

already acknowledged as bugs.

Use mypy 0.920

One 'type: ignore' is no longer needed, it seems.

Reuse fixture across test module

The fixture is duplicated. Funnily enough, the dupe in async is less
efficient than the one in the sync test module, but it allowed to spot
the bug at the previous commit, after using it more than the prepared
threshold.

Ungratefully dropping it.

Fix prepared statements clearing

In the conditions illustrated by the test, i.e. with some statements
already prepared and a multiple statements query containing a DROP, the
check for multiple statements wouldn't have been triggered, and the
query would have eventually been asked for preparation, failing because
containing multiple statements.

Bump version to release 3.0.7

Fix Cursor.rowcount after an executemany hitting no result

Close #178

Fix executemany crash with empty input sequence

Close #179.

Reduce the work done on the cursor by executemany

Certain functions were executed once per query (e.g. _make_row_maker(),
_tx.set_pgresult()) but we can run them only once.

Finalise version 3.0.6 for release

Don't run Mypy tests on Windows/macOS

These tests are kinda slow and these platforms are the slowest to run.
Testing Mypy on Linux covers other platforms too.

A sample GitHub tests run (with no other concurrent job) went down from
22m to 18m.

Merge branch 'fix-177'

Detect out-of-order transactions exit when they have the same name too.

Detect out-of-order transactions exit when they have the same name too

Close #177

Don't try to execute transaction finalization with the connection closed

Refactor Transaction queries generation into internal methods

Refactor Transaction adding an internal push method

Nice and symmetric w.r.t. the pop method recently introduced.

Add tests to verify out-of-order detections without threads

Merge branch 'transaction-concurrency'

Raise ProgrammingError on out-of-order exit from transactions

Previously it would have failed an assert.

Further back in time, the condition was checked and reported as
ProgrammingError already. The check was dropped when
`conn.transaction()` started to return an entered transaction, so the
possibility of calling enter/exit manually was taken out of the public
API. However, we didn't consider the possibility of concurrent
threads operating on transaction independently.

Also fix the Transaction representation, which wouldn't have reported
`(terminated)` exiting on rollback, but only on commit.

Close #176.

Make the test to detect out-of-order transaction exiting reliable

Test transactions with concurrence [skip ci]

Fix docs typo

Improve Dumper, Loader documentation

Reword the types package description with more links to relevant docs

Fix duplicate docs for Cursor.description

Add ConnStatus.CHECK_STANDBY enum value

Added in PostgreSQL 14, only visible during connection, if at all.

Reword PyFormat docs

Fix a couple of typos in pool docs

Merge pull request #167 from dlax/trace

Add bindings for PQ tracing functions

Mention addition of trace function in news file

Report that trace is *currently* only supported on linux in errors

We will add support for other platforms, if others care.

Add a --pq-tracefile pytest option

When specified, we'd enable tracing of the client/server communication
to a file. The file is opened for the whole test session and we set a
title section before each test run.

Add bindings for PQ tracing functions

Since we cannot pass a file descriptor as a FILE value, as expected by
PQtrace(), PGconn.trace() method accepts a 'fileno: int' value. This is
then used to build an stdio's FILE value through fdopen(). The latter
also needs a binding in ctypes. This only works on Linux platform.

In _pq_ctypes.pyi, fdopen() and PQtrace() are not autogenerated because
of the needed '# type: ignore' (similar to existing ones).

PQsetTraceFlags() is new from libpq 14, so we declare it conditionally.

Flag the bugfix version unreleased in the docs news

Don't raise an exception using cur.description with closed connection

Close #172.

Raise OperationalError on Connection.cursor() if closed

Drop unneeded sort() in test

Fix whitespace excess

Reported as error by new black version.

Don't raise exceptions on ServerError.close() if the connection is closed

Close #173.

Drop a few unused imports in pgconn.pyx

Add _PQencryptPasswordConn() in _pq_ctypes.pyi

Running the generation script produces this diff.

test: run tests against PostgreSQL 14 on macOS

brew gives an error installing v. 13.

Merge branch 'preparing-refactor'

Remove prepared statement maintenance command out of the normal loop

Accumulate the maintenance commands in the state of the prepared
processor manager and decide when to process them.

Split the internal state of prepared statements into names and counts

Refactor away internal prepared statements manager function

Drop PrepareManger.maintain()

reimplement PrepareManager.maintain() calling other public methods

This makes clearer that, in pipeline mode, we call them in two different
moments, whereas in non-pipeline we call them in a single place.

Rename prepare manager methods

Underscore the methods that are only called internally.

Change some of the public names. However this is just temporary, to
reason about who calls what.

Use the clear() method in PrepareManager.maintain()

Add handle() and validate() methods to PrepareManager

These essentially perform the same steps as maintain() but with only
query information first, and then once results become available.

Add a rotate() method to PrepareManager

Add a check_results() method to PrepareManager

Add a setdefault() method to PrepareManager

Add a should_discard() method to PrepareManager

Add a key() method to PrepareManager

Peg version of the docs theme package

Install the pool in the docs environment in editable mode

Add sphinx link to docs footer, drop page source link

Merge branch 'two-phase-commit'

Close connections in TPC tests to avoid warnings in tests

Add documentation for two-phase commit support