docs: mention that conn.pipeline() yields a Pipeline object

While reading the section, it is otherwise not obvious to understand
where to get the Pipeline object from.

docs: add note about implicit transactions and sync in pipeline mode

docs: split/reshuffle pipeline docs

- Postgres concept
- Psycopg usage
- detail about sync points
- disclaimer - don't call the semver police.

docs: document that now rollback issues a sync point

docs: add warning disclaimer about pipeline mode

docs: clarify flush and sync pipeline operations

docs: fix pipeline docs typos

docs: add note about features not supported in pipeline mode

docs: add first cut of pipeline mode docs

fix: sync pipeline state on rollback

Merge branch 'pipeline-sync-no-fetch'

feat: only Sync nested pipelines at exit

It's not needed to force a results fetch when exiting a nested pipeline
as this would naturally happen either later in the outer pipeline or
eventually at the end of the outermost one. Rather, just do a Sync, as
it allows outer pipeline to resume normal execution in case the inner
one got into aborted state.

fix: only request a pipeline flush in returning executemany()

A full Sync is not needed as we're only interested in getting results
when returning=True.

fix: do not fetch in Pipeline.sync()

During previous refactorings, we made Pipeline.sync() also fetch results
from the server. But this somehow breaks the semantics of the
synchronization point as defined by Postgres because the user might be
interested in emitting Sync message as a way to solely close the current
series of queries in the pipeline: i.e., flush queries from client to
server and reset the pipeline error state. In this respect, the 'fetch'
step should be explicit.

BasePipeline._sync_gen() is changed to only emit a Sync and a new
_exit_gen() method is introduced doing what _sync_gen() previously did.
Accordingly, the warning emitted when calling this _exit_gen() at
pipeline exit is adjusted to say "terminating" instead of "syncing".

fix: shorten tracebacks on pipeline sync and exit

The details shown are only the communication bowels. So we go from:

    Traceback (most recent call last):
      File "trace.py", line 301, in <module>
        conn.execute("select pg_sleep(0.2)")
      File "/usr/lib/python3.8/contextlib.py", line 120, in __exit__
        next(self.gen)
      File "/home/piro/dev/psycopg3/psycopg/psycopg/connection.py", line 881, in pipeline
        yield pipeline
      File "/home/piro/dev/psycopg3/psycopg/psycopg/_pipeline.py", line 197, in __exit__
        self.sync()
      File "/home/piro/dev/psycopg3/psycopg/psycopg/_pipeline.py", line 183, in sync
        self._conn.wait(self._sync_gen())
      File "/home/piro/dev/psycopg3/psycopg/psycopg/connection.py", line 896, in wait
        return waiting.wait(gen, self.pgconn.socket, timeout=timeout)
      File "/home/piro/dev/psycopg3/psycopg/psycopg/waiting.py", line 237, in wait_epoll
        s = gen.send(ready)
      File "/home/piro/dev/psycopg3/psycopg/psycopg/_pipeline.py", line 92, in _sync_gen
        yield from self._communicate_gen()
      File "/home/piro/dev/psycopg3/psycopg/psycopg/_pipeline.py", line 105, in _communicate_gen
        self._process_results(queued, results)
      File "/home/piro/dev/psycopg3/psycopg/psycopg/_pipeline.py", line 149, in _process_results
        raise e.error_from_result(result, encoding=pgconn_encoding(self.pgconn))
    psycopg.errors.UndefinedColumn: column "foo" does not exist
    LINE 1: select foo
                   ^

to:

    Traceback (most recent call last):
      File "trace.py", line 301, in <module>
        conn.execute("select pg_sleep(0.2)")
      File "/usr/lib/python3.8/contextlib.py", line 120, in __exit__
        next(self.gen)
      File "/home/piro/dev/psycopg3/psycopg/psycopg/connection.py", line 881, in pipeline
        yield pipeline
      File "/home/piro/dev/psycopg3/psycopg/psycopg/_pipeline.py", line 205, in __exit__
        raise exc2.with_traceback(None)
    psycopg.errors.UndefinedColumn: column "foo" does not exist
    LINE 1: select foo
                   ^

which shows much more clearly that the traceback was raised at pipeline
block exit.

fix: allow to use cancel() on a closed connection

docs: add hint about using add_signal_handler() to interrupt async queries

Courtesy @gjcarneiro, thank you!

Merge branch 'fix-286'

perf: avoid unnecessary recvfrom() in cursor.stream()

Call PQisBusy() before PQconsumeInput() on fetching results. If not
busy, don't call PQconsumeInput() at all but just go to fetching results
and notifications.

This is especially useful in single-row mode because most of the times
the libpq can produce several results after a single network fetch.
Previously we were calling PQconsumeInput() also when results were
already on the client and there was nothing new to read, which forced
the libpq to run a select() to tell apart a lack of data from an EOF,
see `the grumble`_, and caused the overhead reported in #286.

Close #286.

.. _the grumble: https://github.com/postgres/postgres/blob/ed57cac84d1c5642737dab1e4c4b8cb4f0c4305f/src/interfaces/libpq/fe-misc.c#L681

test: add cursor.stream() test for empty result sets

Also add a missing async test for results with no column.

refactor: replace an assert with a type: ignore

It's not like we give away opcodes for free here.

refactor: send only once per stream

No need to do it at every row, probably entirely wrong. However this is
not the cause of the slowness reported in #286.

refactor: only clean up the wait() timeout if needed

Often we terminate the iteration at the first item, so no need to select
at all.

Re-export from psycopg._cmodule

test: fix variable scope in ctrl-c test

test: verify ctrl-c in async mode using get_event_loop

test: drop test guard for unsupported Python version

docs: document psycopg 3.0.12 released

docs: improvements to the copy docs

docs: add example of table copy across server

See #285 for a conversation.

docs: document that ticket #254 is fixed in 3.0.12

We can consider this just a bug, not a change of interface. It is
particularly bad because it doesn't allow to pipe a COPY FROM into a
COPY TO.

See https://github.com/psycopg/psycopg/discussions/285#discussioncomment-2663192
for details.

test: add tests to verify copy across tables works

docs: cleanup in types/enums docs

typo fix

Merge branch 'enum'

docs(enum): typo-fix and rephrase

docs(enum): restyle news entry

feat(enum): add mapping override to `register_enum()`

test(enum): drop several hundreds of redundant tests

No need to exhaustively test encodings on ascii data or array properties
tested elsewhere.

refactor(enum): introduce an explicit dump/load mapping

This will allow mapping customization; it is also slightly faster
because it doesn't require data encoding/decoding.

fix(enum): raise DataError in case of labels mismatch on load

A DataError subclass is already raised on mismatch on dump. Be
consistent.

fix(enum): move `enum` arg of register_enum() as third item

This is more consistent with the other register_*() functions and allow
a more natural order of arguments if others must be added (e.g.
mapping).

test(enum): refactor in order to write enum-specific type

They all get created, tests can choose to use only some of them.

test(enum): drop unneeded cursor creation

docs(enum): document the behaviour of unregistered and registered enums

test(enum): add tests to verify the behaviour of unregistered enums

refactor(enum): rename python_type -> enum, enum_labels -> labels on EnumInfo

The previous name were lifted from the composite adapters. However, that
class would have had a more ambiguous "type" attribute, and "types" for
the fields, hence the decision of using "python_" and "fields_" prefix
to disambiguate.

In the enum adapters context, enum is not ambiguous, so a more natural
name seems preferred.

feat(enum): dump enums by keys instead of values

This removes the need for enums to be str-based. It also removes the
asymmetry whereby automatically generated enums were *not* string based,
but pure enums.

refactor: add conn_encoding function

Simplifies the chore of obtaining an encoding from the connection,
defaulting to utf-8 if not available.

test(enum): add test to verify enums work with sql_ascii connections

test(enum): typo fixed

test(enum): more idiomatic sql composition

test(enum): disable Enum random testing

test(enum): added async tests from enums

refactor(enum): removed redundant `EnumDumper.dump` method override

fix(enum): code review fixes

* moved documentation to `docs/basic/adapt.rst`;
* use encoding in `EnumLoader`;
* oid-based dumpers;
* rewritten tests;
* minor fixes.

test(enum): add failing tests to illustrate enum needed improvements

feat: add enum support

fix: fix dumping int enums in text mode, python implementation

The error was hidden by a broken test, failing to test the text mode.

docs: a few clarifications about composite adaptation

fix: drop debug logging left over

doc: add PipelineStatus to 'pq' page

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.