feat: add ConnectionInfo.pipeline_status

docs: clean up a couple of sentences

- New version scheme is "starting from PG 10", not "after PG 10" (also,
  chunky bit moved from docstring to docs as for most other docs).
- The transaction status is of the session, not the server.

Merge branch 'executemany-pipeline'

feat: add PipelineAborted exception

It is a condition that likely will have to be managed, so let's not
clobber it with other OperationalError.

fix: don't fail assert if fetching without result in pipeline mode

The error can be triggered easily by the user. The condition is handled
just naturally by all the methods calling _fetch_pipeline().

fix: consistent sync/exit and error management in pipeline contexts

Don't clobber an exception on exit of the nested block too. In order to
simplify the code, make the pipeline count the number of time it is
entered, and call _exit() only the last time it exits.

Drop assert that we have left pipeline mode leaving the block. If we get
in unrecoverable state, we will have not. By now we should probably just
close the connection; however, leaving it this way is a better
indication that the connection is broken because of something about
pipeline mode; closing it would hide it, and even if we raised a
warning, it would be much easier to miss it than to miss the exceptions
raised in broken state.

fix: forbid COPY in pipeline mode

COPY is not supported. Attempting it puts the connection in
unrecoverable state, with pipeline sync failing and pipeline exit
complaining that there are still results. So let's try to not get in
that state.

fix: restore sending a Sync on block exit but not on executemany end

It was removed a few commits ago, but as Denis suggests, it makes sense
to keep it. Reintroduce it (and test for it), but make sure executemany
doesn't send extra sync.

test: add test to verify the number of roundtrips in pipelined executemany

Add fixture to access the trace data as Python object. I think it's cute <3

test: add fixture to write tests based on libpq trace data

fix: make no-tuple results available after executemany returning

There could be useful info there, if the user asks for it. Now this
doesn't slow down the happy execute path, because the default of
returning is False.

fix: only flush the pipeline after executemany if returning

This has the side effect of breaking rowcount, as before, but can send
many executemany in the same pipeline.

`rowcount` is correct if `returning=True` is set instead, which is a
thing we can at least document, and makes sense: "if you want a result,
you flush the pipeline, dude".

refactor: rename pipeline.communicate() -> sync()

This has the async/sync interface, is is more apt to expose it as public
interface to say "call this to restore the state" (as the changed tests
does).

Expose the try/finally logic behind sync() as the _sync_gen() method,
which can be useful to call if sync has to be performed inside a lock.

fix: keep Cursor._execmany_returning set until reset

Cursor's _execmany_returning attribute is now initialized at _reset()
and set during _executemany_gen_pipeline(). This way, the attribute is
kept for further results fetch that may occur outside executemany()
context: namely, this is needed because _execmany_returning is used by
_set_results_from_pipeline() which would be called by fetch*() methods.

As a consequence, in _fetch_pipeline(), actual fetch is skipped when
coming from executemany(..., returning=False) as the pgresult would
never be set. This ensures a consistent behavior by raising "no result
available" when calling fetch*() from a non-returning executemany().

fix: sync and fetch nested pipelines when they exit

When running a nested pipeline, typically in executemany(), we now call
Pipeline.communicate() at exit similarly to a single (unnested) pipeline
but still keep the surrounding pipeline open (in contrast with unnested
one).

This resolves the issue around rowcount with returning executemany().
Accordingly, we check that rowcount is correct in test_executemany()
pipeline tests and drop the previous xfailed test.

refactor: move final pipeline steps into a communicate() method

test: add missing returning=True to executemany() in pipeline tests

Query in test_executemany() has a returning clause and we fetch results
from cursor after execution, so it seems the returning option to
executemany() is needed. These tests probably do not fail because of the
TODO in Cursor._set_results_from_pipeline().

docs: add news entry about executemany() speedup

test: add xfailing test for rowcount in pipelined executemany

fix: drop unneeded flush after executemany

As per @dlax analysis, it is not needed. It was part of an attempt to
fix the problem of rowcount broken when executemany is called from within
a pipeline block, but that doesn't work anyway.

fix: fix 'executemany()' when pipeline mode is not available

perf: base executemany on pipeline

This changeset also fix several glitches of executemany() run in
pipeline mode, around the management of returned value and rowcount.
These glitches still appear if executemany() is run in an explicit
pipeline() block, because certain events only happen at (outermost)
pipeline block exit.

Related to: #145.

Merge branch 'pipeline4'

fix: don't clobber exceptions exiting the pipeline block

Problem found thanks to random failures in unrelated tests, e.g.
https://github.com/psycopg/psycopg/actions/runs/2048536089

feat: add pretty repr to Pipeline objects

feat: add 'Pipeline.is_supported()'

This makes easier to write conditional code depending on whether we
support pipeline mode or not.

test: do not catch OperationalError in test_pipeline_errors_processed_at_exit

Co-authored-by: Daniele Varrazzo <daniele.varrazzo@gmail.com>

fix: better error on exit of a pipeline with broken connection

Raise an OperationalError with a message "the connection is closed" rather
than "connection pointer is NULL". The exception class was right already.

refactor: move pipeline finalisation code to Pipeline.__exit__

This code has more internal knowledge of the Pipeline object than the
Connection object.

For some reason I don't understand, had to declare 'command_queue' and
'result_queue' types explicitly to the class definition. Leaving just the
definitions in '__init__()' causes mypy (0.940) to complain in 'cursor.py'.

test: add support for using executemany() in pipeline demo

feat: let Connection.pipeline() return the Pipeline object

In tests, add a type annotation on 'conn'/'aconn' fixture so that mypy
understands that pipeline() yields a Pipeline object.

fix: guard connection._pipeline using the connection lock

fix: allow re-entering pipeline mode

refactor: add and use `Cursor._set_results_from_pipeline()`

This is a cleaner interface between the cursor and the pipeline.

refactor: Pipeline classes moved to their module

test: add support for trace file to pipeline demo

Add support for pipeline mode in execute()/fetch*()

When activated on the connection, a pipeline active pipeline handles
a queue of commands to send and a queue of results to process.

The command queue simply contains Callable[[], None], which are built
from partial applications of pgconn.send_*() methods et al.

The queue of results to process either contains a None, when respective
command returns no tuple, or a tuple with respective cursor and query
information needed to maintain automatic prepared statement.

Everywhere we run the execute() generator in non-pipeline mode, we now
enqueue items in the pipeline queues. Then we run
pipeline_communicate(), through the _communicate_gen() method of
BasePipeline, in BaseCursor._execute(many)_gen().

Since pipeline_communicate() may not fetch all results, we need a
dedicated fetch (forced) step upon call to cursor.fetch*(); this is done
by Cursor._fetch_pipeline() called in fetch*() methods. This calls
PQsendFlushRequest() in order to avoid blocking on PQgetResult().

At exit of pipeline mode, we unconditionally emit a PQpipelineSync()
call in order to restore the connection in a usable state in case of
error and we force results fetch after sending any pending commands
(e.g. commands not emitted through an execute() call).

The pipeline-demo.py test script is updated to include examples using
the high-level API. This only works with the 'python' of libpq bindings
because we monkeypatch the pgconn attribute of the connection.

Avoid multiple commands in transaction code

In pipeline mode, command strings containing multiple SQL commands are
disallowed so we remove all such usages from transaction code.

Accordingly, all generator methods in transaction classes now do not
return anything (the result was not used previously anyways).

In tests, the 'commands' list defined in patch_exec() is now filled by
appending instead of inserting so that we keep the natural order of
commands in assertions.

Simplify query preparation cases

Eliminate on 'if' in order to only emit a single
self._send_query_prepared() call.

Return PIPELINE_SYNC result alone in generators.fetch_many()

Handle pipeline-mode errors when checking results

In BaseCursor._check_result(), we now handle FATAL_ERROR and (the
pipeline-mode specific error) PIPELINE_ABORTED in preparation for
supporting the pipeline mode where we'd check results upon fetch*()
instead of upon execute() currently.

Similarly, BaseCursor._raise_for_result() handles PIPELINE_ABORTED
result status.

Raise NotSupportedError when using a server-side cursor in pipeline mode

Raise a ProgrammingError when using cursor.stream() in pipeline mode

As suggested at [1], stream() and pipeline mode are different use cases.

[1]: https://github.com/psycopg/psycopg/pull/93#discussion_r722666980

Add Connection.pipeline() context manager and Pipeline object

On the connection, we store the pipeline object as _pipeline attribute
when in pipeline mode or None otherwise.

Add pipeline_communicate() generator

This generator will be used as the send operations during execute()
step when the connection is in pipeline mode. It can consume results or
send queries depending on socket read/write ready state. Queries to be
sent are in a queue of Callable[[], None] which are built from partial
application of pgconn.send_query() and similar functions.

We add a couple of unit tests, in test_generators.py along with a test
script is taken from PostgreSQL sources. It demonstrates the use of
pipeline mode where query-send and results-fetch steps are interleaved
without any sync point emitted. (In this test, this works because the
output buffer gets full.) The test writes data to logs. Typically, we'd
get:

    enter pipeline
    sent BEGIN TRANSACTION
    sent DROP TABLE IF EXISTS pq_pipeline_demo
    sent CREATE UNLOGGED TABLE pq_pipeline_demo( id serial primary key, itemno integer, int8filler int8)
    prepare INSERT INTO pq_pipeline_demo(itemno, int8filler) VALUES ($1, $2) as 'prepare'
    sent prepared 'prepare' with [b'10000', b'4611686018427387904']
    sent prepared 'prepare' with [b'9999', b'4611686018427387904']
    sent prepared 'prepare' with [b'9998', b'4611686018427387904']
    sent prepared 'prepare' with [b'9997', b'4611686018427387904']
    sent prepared 'prepare' with [b'9996', b'4611686018427387904']
    sent prepared 'prepare' with [b'9995', b'4611686018427387904']
    sent prepared 'prepare' with [b'9994', b'4611686018427387904']
    sent prepared 'prepare' with [b'9993', b'4611686018427387904']
    sent prepared 'prepare' with [b'9992', b'4611686018427387904']
    ...
    sent prepared 'prepare' with [b'9690', b'4611686018427387904']
    sent prepared 'prepare' with [b'9689', b'4611686018427387904']
    sent prepared 'prepare' with [b'9688', b'4611686018427387904']
    got COMMAND_OK results
    got COMMAND_OK results
    got COMMAND_OK results
    got COMMAND_OK results
    got COMMAND_OK results
    got COMMAND_OK results
    got COMMAND_OK results
    got COMMAND_OK results
    got COMMAND_OK results
    ...
    got COMMAND_OK results
    got COMMAND_OK results
    sent prepared 'prepare' with [b'9687', b'4611686018427387904']
    sent prepared 'prepare' with [b'9686', b'4611686018427387904']
    sent prepared 'prepare' with [b'9685', b'4611686018427387904']
    sent prepared 'prepare' with [b'9684', b'4611686018427387904']
    sent prepared 'prepare' with [b'9683', b'4611686018427387904']
    ...
    sent prepared 'prepare' with [b'2', b'4611686018427387904']
    sent prepared 'prepare' with [b'1', b'4611686018427387904']
    sent COMMIT
    pipeline sync sent
    got COMMAND_OK results
    got COMMAND_OK results
    got COMMAND_OK results
    got COMMAND_OK results
    ...
    got COMMAND_OK results
    got COMMAND_OK results
    got PIPELINE_SYNC results
    exit pipeline

We can see that commands are sent, until the output buffer is full (the
connection is then Read-ready only), then results are fetched, until
more commands can be sent, and the cycle repeat.

docs: add ConnectionTimeout documentation

docs: add page with misc objects documentation

Sorry that I broke some links, but the connection page was becoming
unwieldy.

ci: print versions of depending packages on psycopg-binary build

Only on manylinux and musllinux images for the moment.

See #262

chore: upgrade cibuildwheel to 2.3.1

build: upgrade system packages before building psycopg-binary

See #262

chore: bump version number to 3.0.11

ci: upgrade black

This version is not affected by https://github.com/psf/black/issues/2964
and doesn't require pinning click.

fix: default executemany to not fetching results

This is a change from before, but the feature has not been released yet,
so we are still in time to change it.

The change addresses some uneasy feeling about unexpected increased
memory usage (see #164) and may prove a win in combination with the
optimization happening in pipeline mode.

So, if the user is not asking for it, let's not provide it.

ci: pin click dependency to fix black

See https://github.com/psf/black/issues/2964

docs: use monotype style for parameter names

The convention of using italic is more a math thing. In the currently
rendered docs, ``param`` also get rendered in bold rather than italic,
so there is just no connection to anything else on the page.

A :param:`name` role would be nice. Maybe rendered in
monospace+italic...

test: display the version of the server tests are run against

docs: fix grammar, to allow to connect -> connecting

Fixed by @xenups. Proposed together with a bunch of unrelated changes
probably suggested by some useless AI tool; singling this out.

Close #250.

feat(copy): allow bytearray/memoryview as copy.write() input

The C implementation can deal with these types efficiently and it may
save a memcopy if that's what the user has available.

Close #254

refactor: use TypeAlias

Upgrade mypy min requirements to 0.940, which is the first supporting
TypeAlias after a few broken releases.

docs: add back lost comment and extend it with new knowledge

perf: release the GIL in copy-related libpq functions

Tests have shown that these functions may do a considerable amount of
work, although purely CPU.

Merge branch 'fix-255'

fix(copy): chunk large buffers before queuing, not after

This is conceptually a better place to do it, because the queue has the
function of applying backpressure on the data generator. Splitting large
buffers later would flood the libpq without effectively slowing down the
producer.

Also, reduce the size of the chunks appended to the libpq from 1Mb to
128K. This makes an *immense* difference: the too large chunk probably
triggers some quadraticity in the libpq. The test script found in #255,
piped in `ts -s`, shows that pushing a block of data of about 1Gb size
(which will fail in Postgres anyway), with the smaller size, will take
about 9s. With the larger size, it takes 4.10m to get to waiting for
PQputCopyEnd, and other almost 6 minutes to receive the error message
from the server.

    00:00:47 putting 1048576 (or less) bytes in queue size 1023
    00:00:47 writing copy end
    00:00:47 got 1048576 bytes from queue size 1023
    ...
    00:01:25 got 1048576 bytes from queue size 640
    ...
    00:01:54 got 1048576 bytes from queue size 512
    ...
    00:03:00 got 1048576 bytes from queue size 256
    ...
    00:04:12 got 0 bytes from queue size 0
    00:04:12 wait for copy end
    00:09:59 Traceback (most recent call last):
    ...

Adding a few prints (see #255 for details) also shows that the time
spent in PQputCopyData increases, going from ~15 entries/sec processed
when the writer has just finished pushing data in the queue, down to ~4
items/sec towards the end.

Considering that a reduction of 10-20% of the input size causes a
decrease of the processing time of about 50%, there is definitely
something quadratic going on there. It might be possible to improve the
libpq, but for the moment it's better to try and coexist nicely with the
current state.

fix(copy): split large buffers before sending them to PQputCopyData

Sending excessively large data doesn't allow the libpq to flush its
content to the server, ending up in an infinite loop.

Close #255

fix(copy): propagate errors raised in the worker thread

Previously, an error in the worker thread was printed to stderr, but
processing continued, for no result but no exception.

Problem found in #255, but unrelated to it.

docs: drop outdated docstring description

build(docs): don't exit with success if building html docs failed

Responsible of 2020-03-19 docs downtime. See #252.

This commit is expected to fail linting if committed before
17f9703380ed4aed3ce88ba1e9f68a46b911dede and to succeed when rebased
after it.

...it doesn't: can't quite trigger a failure in Github Actions, although,
locally, "it fails correctly". Merging anyway.

fix: fix loading of text arrays with dimension information

The dimension information is a prefix such as ``[0:2]=`` in front of the
array. We just discard it when loading to lists, because for Python they
are always 0-based.

https://www.postgresql.org/docs/14/arrays.html#ARRAYS-IO

Close #253.

fix: install typing_extensions on Python < 3.10

For some reasons tests pass, but it's necessary.

Close #252.

Merge branch 'pgconn-in-exception'

docs: document PGconn needs_password and used_password attributes

This improves the documentation of Error class, which refers to those
in the new pgconn attribute documentation.

docs: specify that ANY() is available in psycopg2 too

doc: give more context to disconnection detection recipe

docs: add docs for `Error.pgconn` and `Error.pgresult`

feat: add `Error.pgresult` property

It might be useful for the same reason `pgconn` is.

For symmetry convert `pgconn` to a read-only attribute too.

feat: add `Error.pgconn` attribute

Might be useful to investigate errors such as bad/missing password. See #242
for details.

doc: fix duplications in class exceptions table titles

fix(c): fix portable endian aliases on different BSD flavours

See the commit at:
https://github.com/linux-sunxi/sunxi-tools/commit/384ff6473455da1a24b5037b358591f44f3bbf57

Close #241

chore: bump version number to 3.0.10

doc: fix typo in comment

fix: don't raise error accessing Cursor.description after COPY_OUT

COPY_OUT result advertises the number of columns but not their names (or
types). Use a surrogate name for description (which is more useful than
returning `None`, because at lest it tells how many columns were
emitted).

Close #235.

Merge branch 'fix-231'

test(win32): skip Ctrl-C test on Windows

As much as I've tried, haven't been able to send a Ctrl-C. Tests fail on
"ctrl-c not received".

fix: Cancel query on Ctrl-C

On KeyboardInterrupt, send a cancel to the server and keep waiting for
the result of the cancel, which is expected to raise a QueryCanceled,
then re-raise KeyboardInterrupt.

Before this, the connection was left in ACTIVE state, so it couldn't be rolled
back.

Only fixed on sync connections. Left a failing test for async
connections; the test fails with an output from the script such as:

    error ignored in rollback on <psycopg.AsyncConnection [ACTIVE] ...>:
    sending query failed: another command is already in progress
    Traceback (most recent call last):
      File "<string>", line 27, in <module>
      File "/usr/lib/python3.8/asyncio/runners.py", line 44, in run
        return loop.run_until_complete(main)
      File "/usr/lib/python3.8/asyncio/base_events.py", line 603, in run_until_complete
        self.run_forever()
      File "/usr/lib/python3.8/asyncio/base_events.py", line 570, in run_forever
        self._run_once()
      File "/usr/lib/python3.8/asyncio/base_events.py", line 1823, in _run_once
        event_list = self._selector.select(timeout)
      File "/usr/lib/python3.8/selectors.py", line 468, in select
        fd_event_list = self._selector.poll(timeout, max_ev)
    KeyboardInterrupt

And the except branch in `AsyncConnection.wait()` is not reached.

See #231

chore(pool): bump to next rev release

docs: declare psycopg 3.0.9 released

chore(pool):  Bump pool version to 3.1.1

refactor(pool): update some debug logging

Drop debug logging on `MaintenanceTask.init()`, which is not
particularly useful. Add debug entries on tasks `run()` early bailout,
which is a more interesting condition to follow (and would have allowed
to spot #230 more easily).

Merge branch 'fix-230'

Close #230.

fix(pool): set the open flag before starting the maintenance tasks

Failing to do so we might trigger the test in `MaintenanceTask.run()`
and find the pool closed, so discard the operation. It usually doesn't
happen, but with a few combination of IO operation it does happen: see
https://github.com/psycopg/psycopg/issues/230 for details.

test(pool): add test to show deadlock on logging

This deadlock seems reproducible at least on Python 3.8 and 3.10 on
Linux. It is caused by the logging statement in
``MaintenanceTask.__init__``: even just a ``print()`` there causes the lock.

See https://github.com/psycopg/psycopg/issues/230 for more details.

chore(pool): bump to next pool version

More regular and compact auto-generated exceptions

Also drop unneeded flake8 config file.

Set up the sqlstate-exception mapping using init_subclass

Merge branch 'fix-225'

Add doc section to refer to the exceptions list

Also clarify Error.sqlstate and further errors doc cleanup.

Set Error.sqlcode when unknown codes are received

Close #225.

Make the tzdata package a dependency on Windows

The package replaces the missing system tz database and allows to avoid
the warning and return timestamps in the client timezone instead of in
UTC.

Close #223

Set workflows to cancel jobs on the same branch

Docs at https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#concurrency

Merge pull request #224 from The-One-And-Only-H/asyncio-fix

Fix failures caused by the pytest-asyncio now raising a warning when a sync
function is marked asyncio.