[Python-modules-commits] [psycopg2] 04/08: Imported Upstream version 2.7.1
Scott Kitterman
kitterman at moszumanska.debian.org
Mon Jun 12 12:20:03 UTC 2017
This is an automated email from the git hooks/post-receive script.
kitterman pushed a commit to branch master
in repository psycopg2.
commit d8e724867f531070a26a0dd7c30c09b06f49869e
Author: Scott Kitterman <scott at kitterman.com>
Date: Sun Jun 11 10:03:45 2017 -0400
Imported Upstream version 2.7.1
---
NEWS | 83 ++-
PKG-INFO | 32 +-
README.rst | 25 +-
doc/src/_static/psycopg.css | 9 +-
doc/src/advanced.rst | 93 +++-
doc/src/conf.py | 6 +-
doc/src/connection.rst | 145 +++++-
doc/src/cursor.rst | 46 +-
doc/src/extensions.rst | 143 ++++-
doc/src/extras.rst | 455 +++++++++++++++-
doc/src/faq.rst | 22 +-
doc/src/index.rst | 5 +-
doc/src/install.rst | 252 ++++-----
doc/src/module.rst | 43 +-
doc/src/sql.rst | 89 ++++
doc/src/usage.rst | 21 +-
lib/__init__.py | 88 +---
lib/_ipaddress.py | 89 ++++
lib/_json.py | 14 +-
lib/_range.py | 64 ++-
lib/errorcodes.py | 1 +
lib/extensions.py | 148 ++++--
lib/extras.py | 404 +++++++++++++--
lib/pool.py | 38 +-
lib/psycopg1.py | 19 +-
lib/sql.py | 424 +++++++++++++++
lib/tz.py | 12 +-
psycopg/adapter_binary.c | 2 -
psycopg/adapter_qstring.c | 43 +-
psycopg/config.h | 11 +
psycopg/connection.h | 35 +-
psycopg/connection_int.c | 692 ++++++++++++++-----------
psycopg/connection_type.c | 389 ++++++++++----
psycopg/cursor.h | 1 +
psycopg/cursor_type.c | 249 ++++++---
psycopg/diagnostics_type.c | 2 +-
psycopg/error.h | 2 +-
psycopg/error_type.c | 15 +-
psycopg/libpq_support.c | 104 ++++
psycopg/{error.h => libpq_support.h} | 35 +-
psycopg/lobject_int.c | 10 +-
psycopg/lobject_type.c | 13 +-
psycopg/microprotocols.c | 24 +-
psycopg/pqpath.c | 388 +++++++++++++-
psycopg/pqpath.h | 9 +
psycopg/psycopg.h | 13 +-
psycopg/psycopgmodule.c | 140 ++++-
psycopg/python.h | 4 +-
psycopg/{error.h => replication_connection.h} | 42 +-
psycopg/replication_connection_type.c | 221 ++++++++
psycopg/replication_cursor.h | 59 +++
psycopg/replication_cursor_type.c | 315 +++++++++++
psycopg/{error.h => replication_message.h} | 42 +-
psycopg/replication_message_type.c | 191 +++++++
psycopg/typecast.c | 15 +-
psycopg/typecast_basic.c | 6 +-
psycopg/typecast_builtins.c | 6 +
psycopg/typecast_datetime.c | 81 +--
psycopg/utils.c | 141 ++++-
psycopg/win32_support.c | 89 ++++
psycopg/{error.h => win32_support.h} | 35 +-
psycopg2.egg-info/PKG-INFO | 32 +-
psycopg2.egg-info/SOURCES.txt | 22 +-
scripts/buildtypes.py | 17 +-
scripts/fix_b.py | 20 -
scripts/make_errorcodes.py | 23 +-
scripts/refcounter.py | 7 +-
scripts/travis_prepare.sh | 131 +++++
scripts/travis_test.sh | 72 +++
scripts/upload-release.sh | 54 --
setup.cfg | 4 +
setup.py | 110 ++--
tests/__init__.py | 27 +-
tests/test_async.py | 62 +--
tests/test_async_keyword.py | 221 ++++++++
tests/test_bugX000.py | 14 +-
tests/test_bug_gc.py | 3 +
tests/test_cancel.py | 14 +-
tests/test_connection.py | 716 ++++++++++++++++++++------
tests/test_copy.py | 48 +-
tests/test_cursor.py | 136 +++--
tests/test_dates.py | 138 +++--
tests/test_errcodes.py | 10 +-
tests/test_extras_dictcursor.py | 15 +-
tests/test_fast_executemany.py | 242 +++++++++
tests/test_green.py | 7 +-
tests/test_ipaddress.py | 136 +++++
tests/test_lobject.py | 61 ++-
tests/test_module.py | 76 +--
tests/test_notify.py | 42 +-
tests/test_psycopg2_dbapi20.py | 25 +
tests/test_quote.py | 51 +-
tests/test_replication.py | 232 +++++++++
tests/test_sql.py | 376 ++++++++++++++
tests/test_transaction.py | 11 +-
tests/test_types_basic.py | 139 +++--
tests/test_types_extras.py | 223 ++++----
tests/test_with.py | 10 +-
tests/testconfig.py | 10 +-
tests/testutils.py | 149 +++++-
100 files changed, 7988 insertions(+), 1892 deletions(-)
diff --git a/NEWS b/NEWS
index 415411c..88689f6 100644
--- a/NEWS
+++ b/NEWS
@@ -1,11 +1,87 @@
Current release
---------------
+What's new in psycopg 2.7.1
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Ignore `!None` arguments passed to `~psycopg2.connect()` and
+ `~psycopg2.extensions.make_dsn()` (:ticket:`#517`).
+- OpenSSL upgraded from major version 0.9.8 to 1.0.2 in the Linux wheel
+ packages (:ticket:`#518`).
+- Fixed build with libpq versions < 9.3 (:ticket:`#520`).
+
+
+What's new in psycopg 2.7
+-------------------------
+
+New features:
+
+- Added `~psycopg2.sql` module to generate SQL dynamically (:ticket:`#308`).
+- Added :ref:`replication-support` (:ticket:`#322`). Main authors are
+ Oleksandr Shulgin and Craig Ringer, who deserve a huge thank you.
+- Added `~psycopg2.extensions.parse_dsn()` and
+ `~psycopg2.extensions.make_dsn()` functions (:tickets:`#321, #363`).
+ `~psycopg2.connect()` now can take both *dsn* and keyword arguments, merging
+ them together.
+- Added `~psycopg2.__libpq_version__` and
+ `~psycopg2.extensions.libpq_version()` to inspect the version of the
+ ``libpq`` library the module was compiled/loaded with
+ (:tickets:`#35, #323`).
+- The attributes `~connection.notices` and `~connection.notifies` can be
+ customized replacing them with any object exposing an `!append()` method
+ (:ticket:`#326`).
+- Adapt network types to `ipaddress` objects when available. When not
+ enabled, convert arrays of network types to lists by default. The old `!Inet`
+ adapter is deprecated (:tickets:`#317, #343, #387`).
+- Added `~psycopg2.extensions.quote_ident()` function (:ticket:`#359`).
+- Added `~connection.get_dsn_parameters()` connection method (:ticket:`#364`).
+- `~cursor.callproc()` now accepts a dictionary of parameters (:ticket:`#381`).
+- Give precedence to `!__conform__()` over superclasses to choose an object
+ adapter (:ticket:`#456`).
+- Using Python C API decoding functions and codecs caching for faster
+ unicode encoding/decoding (:ticket:`#473`).
+- `~cursor.executemany()` slowness addressed by
+ `~psycopg2.extras.execute_batch()` and `~psycopg2.extras.execute_values()`
+ (:ticket:`#491`).
+- Added ``async_`` as an alias for ``async`` to support Python 3.7 where
+ ``async`` will become a keyword (:ticket:`#495`).
+- Unless in autocommit, do not use :sql:`default_transaction_*` settings to
+ control the session characteristics as it may create problems with external
+ connection pools such as pgbouncer; use :sql:`BEGIN` options instead
+ (:ticket:`#503`).
+- `~connection.isolation_level` is now writable and entirely separated from
+ `~connection.autocommit`; added `~connection.readonly`,
+ `~connection.deferrable` writable attributes.
+
+Bug fixes:
+
+- Fixed error caused by missing decoding `~psycopg2.extras.LoggingConnection`
+ (:ticket:`#483`).
+- Fixed integer overflow in :sql:`interval` seconds (:ticket:`#512`).
+
+Other changes:
+
+- Dropped support for Python 2.5 and 3.1.
+- Dropped support for client library older than PostgreSQL 9.1 (but older
+ server versions are still supported).
+- `~connection.isolation_level` doesn't read from the database but will return
+ `~psycopg2.extensions.ISOLATION_LEVEL_DEFAULT` if no value was set on the
+ connection.
+- Empty arrays no more converted into lists if they don't have a type attached
+ (:ticket:`#506`)
+
+
+What's new in psycopg 2.6.3
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Throw an exception trying to pass ``NULL`` chars as parameters
+ (:ticket:`#420`).
+- Make `~psycopg2.extras.Range` objects picklable (:ticket:`#462`).
+
+
What's new in psycopg 2.6.2
^^^^^^^^^^^^^^^^^^^^^^^^^^^
-- Fixed inconsistent state in externally closed connections
- (:tickets:`#263, #311, #443`).
- Report the server response status on errors (such as :ticket:`#281`).
- Raise `!NotSupportedError` on unhandled server response status
(:ticket:`#352`).
@@ -15,8 +91,7 @@ What's new in psycopg 2.6.2
(:ticket:`#333`).
- Fixed `!PersistentConnectionPool` on Python 3 (:ticket:`#348`).
- Fixed segfault on `repr()` of an unitialized connection (:ticket:`#361`).
-- Allow adapting bytes using `~psycopg2.extensions.QuotedString` on Python 3
- (:ticket:`#365`).
+- Allow adapting bytes using QuotedString on Python 3 too (:ticket:`#365`).
- Added support for setuptools/wheel (:ticket:`#370`).
- Fix build on Windows with Python 3.5, VS 2015 (:ticket:`#380`).
- Fixed `!errorcodes.lookup` initialization thread-safety (:ticket:`#382`).
diff --git a/PKG-INFO b/PKG-INFO
index ca22902..9a7352a 100644
--- a/PKG-INFO
+++ b/PKG-INFO
@@ -1,12 +1,12 @@
Metadata-Version: 1.1
Name: psycopg2
-Version: 2.6.2
+Version: 2.7.1
Summary: psycopg2 - Python-PostgreSQL Database Adapter
Home-page: http://initd.org/psycopg/
Author: Federico Di Gregorio
Author-email: fog at initd.org
License: LGPL with exceptions or ZPL
-Download-URL: http://initd.org/psycopg/tarballs/PSYCOPG-2-6/psycopg2-2.6.2.tar.gz
+Download-URL: http://initd.org/psycopg/tarballs/PSYCOPG-2-7/psycopg2-2.7.1.tar.gz
Description: Psycopg is the most popular PostgreSQL database adapter for the Python
programming language. Its main features are the complete implementation of
the Python DB API 2.0 specification and the thread safety (several threads can
@@ -35,8 +35,14 @@ Description: Psycopg is the most popular PostgreSQL database adapter for the Pyt
Installation
------------
- If all the dependencies are met (i.e. you have the Python and libpq
- development packages installed in your system) the standard::
+ If your ``pip`` version supports wheel_ packages it should be possible to
+ install a binary version of Psycopg including all the dependencies. Just run::
+
+ pip install psycopg2
+
+ If you want to build Psycopg from source you will need some prerequisite (a C
+ compiler, Python and libpq development packages). If you have what you need
+ the standard::
python setup.py build
sudo python setup.py install
@@ -44,28 +50,40 @@ Description: Psycopg is the most popular PostgreSQL database adapter for the Pyt
should work no problem. In case you have any problem check the 'install' and
the 'faq' documents in the docs or online__.
- .. __: http://initd.org/psycopg/docs/install.html
+ .. _wheel: http://pythonwheels.com/
+ .. __: http://initd.org/psycopg/docs/install.html#install-from-source
For any other resource (source code repository, bug tracker, mailing list)
please check the `project homepage`__.
.. __: http://initd.org/psycopg/
+
+ :Linux/OSX: |travis|
+ :Windows: |appveyor|
+
+ .. |travis| image:: https://travis-ci.org/psycopg/psycopg2.svg?branch=master
+ :target: https://travis-ci.org/psycopg/psycopg2
+ :alt: Linux and OSX build status
+
+ .. |appveyor| image:: https://ci.appveyor.com/api/projects/status/github/psycopg/psycopg2?branch=master&svg=true
+ :target: https://ci.appveyor.com/project/psycopg/psycopg2
+ :alt: Windows build status
+
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 2.5
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.1
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
+Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: C
Classifier: Programming Language :: SQL
Classifier: Topic :: Database
diff --git a/README.rst b/README.rst
index 51d2d6b..efbe38e 100644
--- a/README.rst
+++ b/README.rst
@@ -29,8 +29,14 @@ Documentation is included in the 'doc' directory and is `available online`__.
Installation
------------
-If all the dependencies are met (i.e. you have the Python and libpq
-development packages installed in your system) the standard::
+If your ``pip`` version supports wheel_ packages it should be possible to
+install a binary version of Psycopg including all the dependencies. Just run::
+
+ pip install psycopg2
+
+If you want to build Psycopg from source you will need some prerequisite (a C
+compiler, Python and libpq development packages). If you have what you need
+the standard::
python setup.py build
sudo python setup.py install
@@ -38,9 +44,22 @@ development packages installed in your system) the standard::
should work no problem. In case you have any problem check the 'install' and
the 'faq' documents in the docs or online__.
-.. __: http://initd.org/psycopg/docs/install.html
+.. _wheel: http://pythonwheels.com/
+.. __: http://initd.org/psycopg/docs/install.html#install-from-source
For any other resource (source code repository, bug tracker, mailing list)
please check the `project homepage`__.
.. __: http://initd.org/psycopg/
+
+
+:Linux/OSX: |travis|
+:Windows: |appveyor|
+
+.. |travis| image:: https://travis-ci.org/psycopg/psycopg2.svg?branch=master
+ :target: https://travis-ci.org/psycopg/psycopg2
+ :alt: Linux and OSX build status
+
+.. |appveyor| image:: https://ci.appveyor.com/api/projects/status/github/psycopg/psycopg2?branch=master&svg=true
+ :target: https://ci.appveyor.com/project/psycopg/psycopg2
+ :alt: Windows build status
diff --git a/doc/src/_static/psycopg.css b/doc/src/_static/psycopg.css
index a5d5b3a..f2fd1c1 100644
--- a/doc/src/_static/psycopg.css
+++ b/doc/src/_static/psycopg.css
@@ -1,4 +1,4 @@
- at import url("default.css");
+ at import url("classic.css");
blockquote {
font-style: italic;
@@ -14,11 +14,18 @@ div.dbapi-extension {
border: 1px solid #aaf;
}
+code.sql,
tt.sql {
font-size: 1em;
background-color: transparent;
}
+a > code.sql,
+a > tt.sql {
+ font-weight: normal;
+}
+
+a > code.sql:hover,
a > tt.sql:hover {
text-decoration: underline;
}
diff --git a/doc/src/advanced.rst b/doc/src/advanced.rst
index 507a0ee..5b5fb35 100644
--- a/doc/src/advanced.rst
+++ b/doc/src/advanced.rst
@@ -312,6 +312,10 @@ received from a previous version server will have the
Added `~psycopg2.extensions.Notify` object and handling notification
payload.
+.. versionchanged:: 2.7
+ The `~connection.notifies` attribute is writable: it is possible to
+ replace it with any object exposing an `!append()` method. An useful
+ example would be to use a `~collections.deque` object.
.. index::
@@ -419,7 +423,7 @@ this will be probably implemented in a future release.
Support for coroutine libraries
-------------------------------
-.. versionadded:: 2.2.0
+.. versionadded:: 2.2
Psycopg can be used together with coroutine_\-based libraries and participate
in cooperative multithreading.
@@ -505,3 +509,90 @@ resources about the topic.
conn.commit()
cur.close()
conn.close()
+
+
+
+.. index::
+ single: Replication
+
+.. _replication-support:
+
+Replication protocol support
+----------------------------
+
+.. versionadded:: 2.7
+
+Modern PostgreSQL servers (version 9.0 and above) support replication. The
+replication protocol is built on top of the client-server protocol and can be
+operated using ``libpq``, as such it can be also operated by ``psycopg2``.
+The replication protocol can be operated on both synchronous and
+:ref:`asynchronous <async-support>` connections.
+
+Server version 9.4 adds a new feature called *Logical Replication*.
+
+.. seealso::
+
+ - PostgreSQL `Streaming Replication Protocol`__
+
+ .. __: http://www.postgresql.org/docs/current/static/protocol-replication.html
+
+
+Logical replication Quick-Start
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You must be using PostgreSQL server version 9.4 or above to run this quick
+start.
+
+Make sure that replication connections are permitted for user ``postgres`` in
+``pg_hba.conf`` and reload the server configuration. You also need to set
+``wal_level=logical`` and ``max_wal_senders``, ``max_replication_slots`` to
+value greater than zero in ``postgresql.conf`` (these changes require a server
+restart). Create a database ``psycopg2_test``.
+
+Then run the following code to quickly try the replication support out. This
+is not production code -- it has no error handling, it sends feedback too
+often, etc. -- and it's only intended as a simple demo of logical
+replication::
+
+ from __future__ import print_function
+ import sys
+ import psycopg2
+ import psycopg2.extras
+
+ conn = psycopg2.connect('dbname=psycopg2_test user=postgres',
+ connection_factory=psycopg2.extras.LogicalReplicationConnection)
+ cur = conn.cursor()
+ try:
+ # test_decoding produces textual output
+ cur.start_replication(slot_name='pytest', decode=True)
+ except psycopg2.ProgrammingError:
+ cur.create_replication_slot('pytest', output_plugin='test_decoding')
+ cur.start_replication(slot_name='pytest', decode=True)
+
+ class DemoConsumer(object):
+ def __call__(self, msg):
+ print(msg.payload)
+ msg.cursor.send_feedback(flush_lsn=msg.data_start)
+
+ democonsumer = DemoConsumer()
+
+ print("Starting streaming, press Control-C to end...", file=sys.stderr)
+ try:
+ cur.consume_stream(democonsumer)
+ except KeyboardInterrupt:
+ cur.close()
+ conn.close()
+ print("The slot 'pytest' still exists. Drop it with "
+ "SELECT pg_drop_replication_slot('pytest'); if no longer needed.",
+ file=sys.stderr)
+ print("WARNING: Transaction logs will accumulate in pg_xlog "
+ "until the slot is dropped.", file=sys.stderr)
+
+
+You can now make changes to the ``psycopg2_test`` database using a normal
+psycopg2 session, ``psql``, etc. and see the logical decoding stream printed
+by this demo client.
+
+This will continue running until terminated with ``Control-C``.
+
+For the details see :ref:`replication-objects`.
diff --git a/doc/src/conf.py b/doc/src/conf.py
index 94ffa34..9e73308 100644
--- a/doc/src/conf.py
+++ b/doc/src/conf.py
@@ -61,8 +61,8 @@ except ImportError:
release = version
intersphinx_mapping = {
- 'py': ('http://docs.python.org/', None),
- 'py3': ('http://docs.python.org/3.2', None),
+ 'py': ('http://docs.python.org/2', None),
+ 'py3': ('http://docs.python.org/3', None),
}
# Pattern to generate links to the bug tracker
@@ -127,7 +127,7 @@ rst_epilog = """
# The theme to use for HTML and HTML Help pages. Major themes that come with
# Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'default'
+html_theme = 'classic'
# The stylesheet to use with HTML output: this will include the original one
# adding a few classes.
diff --git a/doc/src/connection.rst b/doc/src/connection.rst
index 92178f3..53f908f 100644
--- a/doc/src/connection.rst
+++ b/doc/src/connection.rst
@@ -386,12 +386,6 @@ The ``connection`` class
The function must be invoked with no transaction in progress.
- .. note::
-
- There is currently no builtin method to read the current value for
- the parameters: use :sql:`SHOW default_transaction_...` to read
- the values from the backend.
-
.. seealso:: |SET TRANSACTION|_ for further details about the behaviour
of the transaction parameters in the server.
@@ -400,6 +394,32 @@ The ``connection`` class
.. versionadded:: 2.4.2
+ .. versionchanged:: 2.7
+ Before this version, the function would have set
+ :sql:`default_transaction_*` attribute in the current session;
+ this implementation has the problem of not playing well with
+ external connection pooling working at transaction level and not
+ resetting the state of the session: changing the default
+ transaction would pollute the connections in the pool and create
+ problems to other applications using the same pool.
+
+ Starting from 2.7, if the connection is not autocommit, the
+ transaction characteristics are issued together with :sql:`BEGIN`
+ and will leave the :sql:`default_transaction_*` settings untouched.
+ For example::
+
+ conn.set_session(readonly=True)
+
+ will not change :sql:`default_transaction_read_only`, but
+ following transaction will start with a :sql:`BEGIN READ ONLY`.
+ Conversely, using::
+
+ conn.set_session(readonly=True, autocommit=True)
+
+ will set :sql:`default_transaction_read_only` to :sql:`on` and
+ rely on the server to apply the read only state to whatever
+ transaction, implicit or explicit, is executed in the connection.
+
.. attribute:: autocommit
@@ -429,31 +449,83 @@ The ``connection`` class
.. attribute:: isolation_level
+
+ Return or set the `transaction isolation level`_ for the current
+ session. The value is one of the :ref:`isolation-level-constants`
+ defined in the `psycopg2.extensions` module. On set it is also
+ possible to use one of the literal values ``READ UNCOMMITTED``, ``READ
+ COMMITTED``, ``REPEATABLE READ``, ``SERIALIZABLE``, ``DEFAULT``.
+
+ .. versionchanged:: 2.7
+
+ the property is writable.
+
+ .. versionchanged:: 2.7
+
+ the default value for `!isolation_level` is
+ `~psycopg2.extensions.ISOLATION_LEVEL_DEFAULT`; previously the
+ property would have queried the server and returned the real value
+ applied. To know this value you can run a query such as :sql:`show
+ transaction_isolation`. Usually the default value is `READ
+ COMMITTED`, but this may be changed in the server configuration.
+
+ This value is now entirely separate from the `autocommit`
+ property: in previous version, if `!autocommit` was set to `!True`
+ this property would have returned
+ `~psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT`; it will now
+ return the server isolation level.
+
+
+ .. attribute:: readonly
+
+ Return or set the read-only status for the current session. Available
+ values are `!True` (new transactions will be in read-only mode),
+ `!False` (new transactions will be writable), `!None` (use the default
+ configured for the server by :sql:`default_transaction_read_only`).
+
+ .. versionadded:: 2.7
+
+
+ .. attribute:: deferrable
+
+ Return or set the `deferrable status`__ for the current session.
+ Available values are `!True` (new transactions will be in deferrable
+ mode), `!False` (new transactions will be in non deferrable mode),
+ `!None` (use the default configured for the server by
+ :sql:`default_transaction_deferrable`).
+
+ .. __: `SET TRANSACTION`_
+
+ .. versionadded:: 2.7
+
+
.. method:: set_isolation_level(level)
.. note::
- From version 2.4.2, `set_session()` and `autocommit`, offer
- finer control on the transaction characteristics.
+ This is a legacy method mixing `~conn.isolation_level` and
+ `~conn.autocommit`. Using the respective properties is a better
+ option.
- Read or set the `transaction isolation level`_ for the current session.
+ Set the `transaction isolation level`_ for the current session.
The level defines the different phenomena that can happen in the
database between concurrent transactions.
- The value set or read is an integer: symbolic constants are defined in
+ The value set is an integer: symbolic constants are defined in
the module `psycopg2.extensions`: see
:ref:`isolation-level-constants` for the available values.
- The default level is :sql:`READ COMMITTED`: at this level a
- transaction is automatically started the first time a database command
- is executed. If you want an *autocommit* mode, switch to
- `~psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT` before
+ The default level is `~psycopg2.extensions.ISOLATION_LEVEL_DEFAULT`:
+ at this level a transaction is automatically started the first time a
+ database command is executed. If you want an *autocommit* mode,
+ switch to `~psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT` before
executing any command::
>>> conn.set_isolation_level(psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT)
See also :ref:`transactions-control`.
+
.. index::
pair: Client; Encoding
@@ -483,13 +555,21 @@ The ``connection`` class
['NOTICE: CREATE TABLE / PRIMARY KEY will create implicit index "foo_pkey" for table "foo"\n',
'NOTICE: CREATE TABLE will create implicit sequence "foo_id_seq" for serial column "foo.id"\n']
+ .. versionchanged:: 2.7
+ The `!notices` attribute is writable: the user may replace it
+ with any Python object exposing an `!append()` method. If
+ appending raises an exception the notice is silently
+ dropped.
+
To avoid a leak in case excessive notices are generated, only the last
- 50 messages are kept.
+ 50 messages are kept. This check is only in place if the `!notices`
+ attribute is a list: if any other object is used it will be up to the
+ user to guard from leakage.
You can configure what messages to receive using `PostgreSQL logging
configuration parameters`__ such as ``log_statement``,
``client_min_messages``, ``log_min_duration_statement`` etc.
-
+
.. __: http://www.postgresql.org/docs/current/static/runtime-config-logging.html
@@ -506,6 +586,12 @@ The ``connection`` class
the payload was not accessible. To keep backward compatibility,
`!Notify` objects can still be accessed as 2 items tuples.
+ .. versionchanged:: 2.7
+ The `!notifies` attribute is writable: the user may replace it
+ with any Python object exposing an `!append()` method. If
+ appending raises an exception the notification is silently
+ dropped.
+
.. attribute:: cursor_factory
@@ -555,6 +641,29 @@ The ``connection`` class
.. index::
+ pair: Connection; Parameters
+
+ .. method:: get_dsn_parameters()
+
+ Get the effective dsn parameters for the connection as a dictionary.
+
+ The *password* parameter is removed from the result.
+
+ Example::
+
+ >>> conn.get_dsn_parameters()
+ {'dbname': 'test', 'user': 'postgres', 'port': '5432', 'sslmode': 'prefer'}
+
+ Requires libpq >= 9.3.
+
+ .. seealso:: libpq docs for `PQconninfo()`__ for details.
+
+ .. __: http://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-PQCONNINFO
+
+ .. versionadded:: 2.7
+
+
+ .. index::
pair: Transaction; Status
.. method:: get_transaction_status()
@@ -669,9 +778,13 @@ The ``connection`` class
.. attribute:: async
+ async_
Read only attribute: 1 if the connection is asynchronous, 0 otherwise.
+ .. versionchanged:: 2.7 added the `!async_` alias for Python versions
+ where `!async` is a keyword.
+
.. method:: poll()
diff --git a/doc/src/cursor.rst b/doc/src/cursor.rst
index 45e6278..c03cea8 100644
--- a/doc/src/cursor.rst
+++ b/doc/src/cursor.rst
@@ -171,43 +171,53 @@ The ``cursor`` class
.. rubric:: Commands execution methods
- .. method:: execute(operation [, parameters])
-
- Prepare and execute a database operation (query or command).
+ .. method:: execute(query, vars=None)
+
+ Execute a database operation (query or command).
Parameters may be provided as sequence or mapping and will be bound to
variables in the operation. Variables are specified either with
positional (``%s``) or named (:samp:`%({name})s`) placeholders. See
:ref:`query-parameters`.
-
+
The method returns `!None`. If a query was executed, the returned
values can be retrieved using |fetch*|_ methods.
- .. method:: executemany(operation, seq_of_parameters)
-
- Prepare a database operation (query or command) and then execute it
- against all parameter tuples or mappings found in the sequence
- `seq_of_parameters`.
-
+ .. method:: executemany(query, vars_list)
+
+ Execute a database operation (query or command) against all parameter
+ tuples or mappings found in the sequence *vars_list*.
+
The function is mostly useful for commands that update the database:
any result set returned by the query is discarded.
-
+
Parameters are bounded to the query using the same rules described in
the `~cursor.execute()` method.
+ .. warning::
+ In its current implementation this method is not faster than
+ executing `~cursor.execute()` in a loop. For better performance
+ you can use the functions described in :ref:`fast-exec`.
+
.. method:: callproc(procname [, parameters])
-
+
Call a stored database procedure with the given name. The sequence of
parameters must contain one entry for each argument that the procedure
- expects. The result of the call is returned as modified copy of the
- input sequence. Input parameters are left untouched, output and
- input/output parameters replaced with possibly new values.
-
- The procedure may also provide a result set as output. This must then
- be made available through the standard |fetch*|_ methods.
+ expects. Overloaded procedures are supported. Named parameters can be
+ used by supplying the parameters as a dictionary.
+
+ This function is, at present, not DBAPI-compliant. The return value is
+ supposed to consist of the sequence of parameters with modified output
+ and input/output parameters. In future versions, the DBAPI-compliant
+ return value may be implemented, but for now the function returns None.
+
+ The procedure may provide a result set as output. This is then made
+ available through the standard |fetch*|_ methods.
+ .. versionchanged:: 2.7
+ added support for named arguments.
.. method:: mogrify(operation [, parameters])
diff --git a/doc/src/extensions.rst b/doc/src/extensions.rst
index dea1041..ae40b72 100644
--- a/doc/src/extensions.rst
+++ b/doc/src/extensions.rst
@@ -12,6 +12,12 @@
The module contains a few objects and function extending the minimum set of
functionalities defined by the |DBAPI|_.
+Classes definitions
+-------------------
+
+Instances of these classes are usually returned by factory functions or
+attributes. Their definitions are exposed here to allow subclassing,
+introspection etc.
.. class:: connection(dsn, async=False)
@@ -23,6 +29,9 @@ functionalities defined by the |DBAPI|_.
For a complete description of the class, see `connection`.
+ .. versionchanged:: 2.7
+ *async_* can be used as alias for *async*.
+
.. class:: cursor(conn, name=None)
It is the class usually returned by the `connection.cursor()`
@@ -33,6 +42,7 @@ functionalities defined by the |DBAPI|_.
For a complete description of the class, see `cursor`.
+
.. class:: lobject(conn [, oid [, mode [, new_oid [, new_file ]]]])
Wrapper for a PostgreSQL large object. See :ref:`large-objects` for an
@@ -189,14 +199,6 @@ functionalities defined by the |DBAPI|_.
server versions.
-.. autofunction:: set_wait_callback(f)
-
- .. versionadded:: 2.2.0
-
-.. autofunction:: get_wait_callback()
-
- .. versionadded:: 2.2.0
-
.. _sql-adaptation-objects:
@@ -417,7 +419,7 @@ details.
.. data:: encodings
- Mapping from `PostgreSQL encoding`__ names to `Python codec`__ names.
+ Mapping from `PostgreSQL encoding`__ to `Python encoding`__ names.
Used by Psycopg when adapting or casting unicode strings. See
:ref:`unicode-handling`.
@@ -456,6 +458,106 @@ The module exports a few exceptions in addition to the :ref:`standard ones
+.. _coroutines-functions:
+
+Coroutines support functions
+----------------------------
+
+These functions are used to set and retrieve the callback function for
+:ref:`cooperation with coroutine libraries <green-support>`.
+
+.. versionadded:: 2.2.0
+
+.. autofunction:: set_wait_callback(f)
+
+.. autofunction:: get_wait_callback()
+
+
+
+Other functions
+---------------
+
+.. function:: libpq_version()
+
+ Return the version number of the ``libpq`` dynamic library loaded as an
+ integer, in the same format of `~connection.server_version`.
+
+ Raise `~psycopg2.NotSupportedError` if the ``psycopg2`` module was
+ compiled with a ``libpq`` version lesser than 9.1 (which can be detected
+ by the `~psycopg2.__libpq_version__` constant).
+
+ .. versionadded:: 2.7
+
+ .. seealso:: libpq docs for `PQlibVersion()`__.
+
+ .. __: http://www.postgresql.org/docs/current/static/libpq-misc.html#LIBPQ-PQLIBVERSION
+
+
+.. function:: make_dsn(dsn=None, \*\*kwargs)
+
+ Create a valid connection string from arguments.
+
+ Put together the arguments in *kwargs* into a connection string. If *dsn*
+ is specified too, merge the arguments coming from both the sources. If the
+ same argument name is specified in both the sources, the *kwargs* value
+ overrides the *dsn* value.
+
+ The input arguments are validated: the output should always be a valid
+ connection string (as far as `parse_dsn()` is concerned). If not raise
+ `~psycopg2.ProgrammingError`.
+
+ Example::
+
+ >>> from psycopg2.extensions import make_dsn
+ >>> make_dsn('dbname=foo host=example.com', password="s3cr3t")
+ 'host=example.com password=s3cr3t dbname=foo'
+
+ .. versionadded:: 2.7
+
+
+.. function:: parse_dsn(dsn)
+
+ Parse connection string into a dictionary of keywords and values.
+
+ Parsing is delegated to the libpq: different versions of the client
+ library may support different formats or parameters (for example,
+ `connection URIs`__ are only supported from libpq 9.2). Raise
+ `~psycopg2.ProgrammingError` if the *dsn* is not valid.
+
+ .. __: http://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-CONNSTRING
+
+ Example::
+
+ >>> from psycopg2.extensions import parse_dsn
+ >>> parse_dsn('dbname=test user=postgres password=secret')
+ {'password': 'secret', 'user': 'postgres', 'dbname': 'test'}
+ >>> parse_dsn("postgresql://someone@example.com/somedb?connect_timeout=10")
+ {'host': 'example.com', 'user': 'someone', 'dbname': 'somedb', 'connect_timeout': '10'}
+
+ .. versionadded:: 2.7
+
+ .. seealso:: libpq docs for `PQconninfoParse()`__.
+
+ .. __: http://www.postgresql.org/docs/current/static/libpq-connect.html#LIBPQ-PQCONNINFOPARSE
+
+
+.. function:: quote_ident(str, scope)
+
+ Return quoted identifier according to PostgreSQL quoting rules.
+
+ The *scope* must be a `connection` or a `cursor`, the underlying
+ connection encoding is used for any necessary character conversion.
+
+ Requires libpq >= 9.0.
+
+ .. versionadded:: 2.7
+
+ .. seealso:: libpq docs for `PQescapeIdentifier()`__
+
+ .. __: http://www.postgresql.org/docs/current/static/libpq-exec.html#LIBPQ-PQESCAPEIDENTIFIER
+
+
+
.. index::
pair: Isolation level; Constants
@@ -465,15 +567,16 @@ Isolation level constants
-------------------------
Psycopg2 `connection` objects hold informations about the PostgreSQL
-`transaction isolation level`_. The current transaction level can be read
-from the `~connection.isolation_level` attribute. The default isolation
-level is :sql:`READ COMMITTED`. A different isolation level con be set
-through the `~connection.set_isolation_level()` method. The level can be
-set to one of the following constants:
+`transaction isolation level`_. By default Psycopg doesn't change the default
+configuration of the server (`ISOLATION_LEVEL_DEFAULT`); the default for
+PostgreSQL servers is typically :sql:`READ COMMITTED`, but this may be changed
+in the server configuration files. A different isolation level can be set
+through the `~connection.set_isolation_level()` or `~connection.set_session()`
+methods. The level can be set to one of the following constants:
.. data:: ISOLATION_LEVEL_AUTOCOMMIT
- No transaction is started when command are issued and no
+ No transaction is started when commands are executed and no
`~connection.commit()` or `~connection.rollback()` is required.
Some PostgreSQL command such as :sql:`CREATE DATABASE` or :sql:`VACUUM`
can't run into a transaction: to run such command use::
@@ -549,6 +652,16 @@ set to one of the following constants:
.. __: http://www.postgresql.org/docs/current/static/transaction-iso.html#XACT-SERIALIZABLE
+.. data:: ISOLATION_LEVEL_DEFAULT
+
+ A new transaction is started at the first `~cursor.execute()` command, but
... 14908 lines suppressed ...
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/packages/psycopg2.git
More information about the Python-modules-commits
mailing list