fix: shorter traceback on COPY error

fix: raise a shorter trackeback on interrupted notify connection

Test: fix mypy 0.941 run

This seems a mypy shortcoming fixed in 0.950 as the CI didn't complain.
The row factory definition was exotic but arguably correct. Not worth
bumping up the min version for it anyway.

Merge remote-tracking branch 'dlax/row-covariant'

fix: only use covariant Row type variable

The real variance of Row type variable is covariant, per definition of
RowMaker (RowMaker[B] is a subtype of RowMaker[A] if B is a subtype of
A; similar to the Box type in [mypy documentation][]).

By dropping the Row type variable from Cursor argument in RowFactory, we
are now able to only use the covariant Row variable (previously Row_co,
now Row). Indeed, RowFactory does not actually depend on Cursor on being
parametrized on Row; rather it's the other way around (Cursor's Row type
variable comes from its row factory).

[mypy documentation]: https://mypy.readthedocs.io/en/latest/generics.html#variance-of-generic-types

fix: use a more generic connection type in {Client,Server}Cursor

This makes them similar to plain Cursor class, i.e. being parametrized
on sync or async connection type, not the row type (which is handled
through the second type variable).

refactor: streamline 'type: ignore' in *Cursor.stream()

Make AsyncCursor code similar to Cursor one.

fix: sync pipeline after tpc_prepare()

This is to get the NotSupported raised directly when calling
tpc_prepare() as expected in test_tpc_disabled().

style: import PipelineStatus members in the module like for other pq enums

perf: micro optimise attribute access to PollingStatus

perf: micro optimise attribute access to ConnStatus

perf: micro optimise attribute access to TransactionStatus

perf: micro optimise attribute access to ExecStatus

perf: micro optimise attribute access to Format

refactor: while 1 -> while True

Brain legacy of ancient Python versions where the latter required a
global lookup.

test: fix for Python 3.11

The f-string expansion of str enums has changed. All the tests in the
maint-3.0 branch were already fixed; this changeset only fixes the new
ones.

Merge branch 'fix-304'

fix: add C Float4 binary dumper

This should hopefully work around issue #304, at least when C is used.
When Python is used we raise an error instead.

Close #304

fix: raise an exception if the struct package is affected by issue #304

Cowardly refuse to transform ones in zeros.

test: Fix implicit f-string conversion to value

Behaviour changed in Python 3.11.

fix: Don't rely on f-string converting str enums in their values

The behaviour seems changed in Python 3.11: now f"%{PyFormat.AUTO}" is
evaluated as `%PyFormat.AUTO` instead of `%s`, for the general hilarity.

fix: fix typo: ingeger

chore: bump version to release 3.0.14

fix: don't barf on errors with blank sqlstate

Such messages are not entirely valid (sqlstate is documented to be
always present), however we receive them after a SHOW HELP in the
PgBouncer admin database.

The SHOW HELP actually does generate a sqlstate `00000` but the message
is somehow parsed incorrectly by the libpq, which goes on to report an
error:

    message contents do not agree with length in message type "N"

See #303. PgBouncer issue reported upstream in
https://github.com/pgbouncer/pgbouncer/issues/718

docs: drop stray reference to psycopg3

Merge branch 'client-side-cursor'

docs: Subtly suggest to use the psycopg.sql module rather than ClientCursor

docs: add documentation for client-side binding cursors

test: test multi-statement parametric queries with client-side binding

fix: set ClientCursor class module to psycopg

feat: add params to Cursor.copy()

test: disable tests throwing copy to executemany in client-side cursors

The async one sometimes gets in an allocation loop. On my laptop it gets
OOM'd quickly. On Github Actions it might be the cause of test taking an
unusually long time.

fix: don't forbid all PQexec queries in client-side cursors

We can still use PQexecParams with an empty list of parameters. This has
advantages, such as the possibility of implementing stream(), and less
faffing with differences between Cursor and ClientCursor.

feat: add ClientCursor.mogrify()

feat: add ClientCursor and AsyncClientCursor classes

test: skip testing random multirange arrays with empty last elements

Previously we were skipping the ones with an empty first element,
because of a known shortcoming in finding the right OID. Now that we
scan the whole array to find all the elements' classes, it's the last
entry which might break dumping.

Merge branch 'fix-301'

fix: allow dumping mixed types list, as long as they use the same dumper

Necessary to dump a mix of ipv4/ipv6 addresses, which result in the same
Postgres type, so it's a legit array.

fix: Raise DataError dumping lists of mixed types

This requires more checking dumping lists, but the alternative is to
guard every single dumper, which is painful as well, and more brittle.

fix: raise DataError if IntDumper tries to dump another type

Allow to dump int subclasses, but not other numeric type, which can lead
to truncation. As seen in #301, the Python implementation truncates; the
c implementation is reporting failing with a TypeError, but on Python
3.8 it raises a deprecation warning instead.

The condition largely happens dumping array of mixed types. However we
should probably test with array of mixed class in a more generic way.

Close #301.

test: fix number of columns in generated faker schema

test: fix formats testing in number wrapper array test

docs: Python enum labels -> members

docs: drop docsting for AsyncPipeline.sync

It was out of date and, for Sync/Async objects, Async docs don't
reiterate what's on the Sync side, they only show the different
signature.

feat: add cursor_factory parameter to `connect()`.

This makes easier to use ClientCursor and port more easily code running
on psycopg2 dong more DDL operations and caring less about performance.

refactor: implement ServerCursor with a mixin rather than an helper

This was the original intention, but some older Mypy limitation was
stopping us from doing so. Or I wasn't good enough at it.

feat: make Cursor constructor public

This allows a more natural creation of cursors subclasses, without the
need of tweaking the connection's cursor_factory and allowing to pass
arbitrary init arguments to the cursor.

Merge branch 'typed-literal'

fix(sql): prefer names without space to cast builtins

Certain types have a regtype with spaces, such as "timestamp with time
zone". Prefer the type short name, in this case ("timestamptz").

feat: add `Transformer.as_literal()` to convert literals to sql

This allows to keep a cache oid -> representation that will be
invalidated automatically if encoding or oid mapping changes, as well as
optimising the function in C.

fix(sql): represent array literals correctly

refactor: `TypeInfo.alt_name` renamed to `regtype`

This has now acquired a precise meaning: it is the name of the type as
SQL snippet (it may contain invalid names, which get quoted, or a schema
name). It can be included literally in a query to make a valid cast.

The previous name wasn't documented and wasn't part of any public API so
we can probably rename it without much problem.

test(cursor): make sure Column.name is right for invalid names too

fix(sql): fetch correct type names in TypeInfo subclasses

Needed to fix `Literal.as_string()` of types using a `TypeInfo` subclass
to fetch info (composite, range, multirange).

fix(sql): fix `sql.Literal` with invalid type names

Make sure that `TypeInfo.alt_name` is always populated, even if with a
copy of `name`.

fix(composite): fix fetching composite info with invalid name or field names

refactor: add _as_python_identifier() function

The function takes a PostgreSQL "invalid" name (such as `a-b` or '0' or an
unicode string) and makes a valid Python name.

Currently used to make valid namedtuples from `nametuple_row()` but can
be used to make other valid Python names.

perf: use `b"'"[0]` as const value to represent `ord("'")`

The value is expanded at compile time::

    >>> dis.dis('b"\'"[0]')
      1           0 LOAD_CONST               0 (39)
                  2 RETURN_VALUE

feat(sql): add explicit type cast to Literal output

feat: add `Transformer.encoding` attribute

feat: add Transformer.from_context() method

Allow to reuse the same transformer in nested context, instead of
creating new ones. Even if transformer copies are shallow, we may end up
creating several in certain places.

Merge branch 'pipeline-more-tests'

fix: make transaction status check account for pipeline mode

We turn _check_intrans() into a generator _check_intrans_gen() in order
to call _pipeline._sync_gen() if the connection is in pipeline mode so
as to retrieve an accurate connection status.

This makes the safety guard about 'autocommit' when inside a transaction
work in pipeline mode, thus removing the xfail in transaction tests.

In test_autocommit_unknown, we now catch OperationalError which is
raised by conn.wait() rather than ProgrammingError previously which is
no longer reached.

fix: wrap transaction in an outer pipeline if the connection has one

Before entering a transaction on a connection in pipeline mode, we open an
outer pipeline to ensure that a Sync is after the transaction exists;
similarly to the inner pipeline, this is to ensure that the connection
state is restored at transaction exit similarly to the non-pipeline
case. The inner pipeline is not enough because we need to account for
the exit transaction statement (COMMIT or ROLLBACK) and then sync its
result.

This fixes transactions tests failing in previous commit.

test: parametrize transaction tests with pipeline on/off

The 'conn' fixture is overloaded in transaction tests, pulling the
'pipeline' fixture to have them run with or without a pipeline.

When checking for connection's transaction state, just after entering
the transaction() block (e.g. in test_basic), we need to sync the
pipeline in order to get the state right. This is just for tests as the
exact transaction state, in pipeline mode, is not deterministic since
query results are not fetched directly.

The following tests fail:

  tests/test_transaction.py::test_basic[pipeline=on]
  tests/test_transaction.py::test_begins_on_enter[pipeline=on]
  tests/test_transaction.py::test_commit_on_successful_exit[pipeline=on]
  tests/test_transaction.py::test_rollback_on_exception_exit[pipeline=on]
  tests/test_transaction.py::test_autocommit_off_but_no_tx_started_successful_exit[pipeline=on]
  tests/test_transaction.py::test_autocommit_off_but_no_tx_started_exception_exit[pipeline=on]
  tests/test_transaction.py::test_nested_all_changes_persisted_on_successful_exit[pipeline=on]
  tests/test_transaction.py::test_nested_all_changes_discarded_on_outer_exception[pipeline=on]
  tests/test_transaction.py::test_nested_all_changes_discarded_on_inner_exception[pipeline=on]
  tests/test_transaction.py::test_nested_inner_scope_exception_handled_in_outer_scope[pipeline=on]
  tests/test_transaction.py::test_nested_three_levels_successful_exit[pipeline=on]
  tests/test_transaction.py::test_named_savepoints_successful_exit[pipeline=on]
  tests/test_transaction.py::test_explicit_rollback_of_enclosing_tx_outer_tx_unaffected[pipeline=on]
  tests/test_transaction.py::test_str[pipeline=on]

This is because the connection state is not correct at the end of
transaction, we'll fix this in next commit.

Some others were adjusted as follows:

* when entering the transaction() block, e.g. in test_begins_on_enter,
  we eventually call pipeline.sync() in order to get the state right
  (this is just for tests as the exact transaction state, in pipeline
  mode, is not deterministic since query results are not fetched
  directly);

* test_context_inerror_rollback_no_clobber[pipeline=on] is skipped, as
  explained in comment inline;

* test_prohibits_use_of_commit_rollback_autocommit[pipeline=on] is
  xfail, because Connection._check_intrans() does not check for pipeline
  mode (see TODO inline about a possible solution);

* test_str now checks for [<txstatus>, pipeline=ON] in str(Transaction).

test: add fixtures to toggle pipeline mode

Also add a pytest mark so that one can run 'pytest -m pipeline' to
select all pipeline-mode tests.

feat: display the pipeline status in the objects repr

chore: bump version to release 3.0.13

Merge branch 'fix-296'

docs: suggest to use commit to maintain atomic sanity in pipeline mode

fix: fix integration between pipelines and nested transaction

Refactor to remove all the knowledge about pipelines from the
transaction object. Replaced by just syncing before entering the
transaction.

Had to drop the pipeline exit, which will now fetch results whatever the
level. If not doing so, a final sync should have been forced to exit
with a clean state from an inner transaction block.

test: fix test of pipeline mode and nested transaction

This test fails in the current implementation.

test: drop TODO points and emergency rollbacks from pipeline tests

The previous changeset restored some sanity. The behaviour in
`test_errors_raised_on_commit` is not inconsistent with the non-pipeline
mode because the two are not comparable: in non-pipeline mode the
exception is raised by `execute()`, not by `commit()`. If an exception
is raised in `commit()` itself, it is already handled consistently, as
`test_error_on_commit` shows.

fix: wrap transaction in pipelines if the connection has one

When entering a transaction on a connection in pipeline mode, we open an
inner pipeline to ensure that a Sync is emitted at the end of
transaction thus restoring the connection in its expected state (i.e.
the same as in non-pipeline mode).

test: add test to verify the behaviour of failed commits

The exception is raised where expected; the transaction is left in IDLE
state. This is unlike what happens in pipeline mode.

fix: fix Transaction commit in pipeline mode

Make sure we receive the commit message, so we can raise an immediate
exception, as we do for connection-handled transactions.

Highlight, in the test, a behaviour difference between commit in
pipeline and non-pipeline mode. In the latter, after a failed commit,
the connection is left IDLE; in pipeline mode it is left INERROR so we
need a further rollback to keep on using it. Will look if this can be
made consistent.

fix: fix nested transaction entering in pipeline mode

If the connection is idle, it might be that we are missing results.
Receive them to align the connection state to what the transaction
object expects, otherwise the assert in _push_savepoint() will fail.

fix: sync the pipeline on commit()

This maintains the expectation that, after commit(), the operation is
really persisted. As per postgres pipeline docs:

    The client must not assume that work is committed when it sends a
    COMMIT — only when the corresponding result is received to confirm the
    commit is complete.

With this change we are effectively receiving the result of the commit,
eventually throwing an exception if it happened.

Close #296

fix: fetch results on Pipeline.sync().

This allows a sync() call to establish an high level synchronization
point between the application and the server. If there were errors in
the processing so far, sync will throw the exception.

See #296.

docs: add warning about error messages raised randomly in pipeline mode

Close #266

fix: raise a clean error on pipeline() on a closed connection

chore: update cibuildwheel to 2.5.0

Merge branch 'fix-293'

Fix array oid dumping lists of integer

The problem was only in the list text dumper, which was trying to do more
than what needed. The list binary dumper worked alright.

Drop mixed array test, which don't really represent anything Postgres
can work with.

Close #293

test: add test to verify the wrong array oid with numbers

The array binary dumper does the right thing; the text one picks
numeric[] unconditionally. It was clearly made on purpose, but #293
shows that it's a bad idea.

docs: wordsmith pipeline docs

docs: drop repeated sentence

Merge branch 'pipeline-docs'

docs: typo fixed

Thank you @dlax!

docs: add examples and messages details in pipeline mode

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