diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/_static/psycopg.css | 4 | ||||
| -rw-r--r-- | doc/src/conf.py | 2 | ||||
| -rw-r--r-- | doc/src/connection.rst | 4 | ||||
| -rw-r--r-- | doc/src/cursor.rst | 17 | ||||
| -rw-r--r-- | doc/src/extensions.rst | 2 | ||||
| -rw-r--r-- | doc/src/extras.rst | 57 | ||||
| -rw-r--r-- | doc/src/install.rst | 4 | ||||
| -rw-r--r-- | doc/src/module.rst | 6 |
8 files changed, 85 insertions, 11 deletions
diff --git a/doc/src/_static/psycopg.css b/doc/src/_static/psycopg.css index a5d5b3a..8f6567b 100644 --- a/doc/src/_static/psycopg.css +++ b/doc/src/_static/psycopg.css @@ -1,4 +1,4 @@ -@import url("default.css"); +@import url("classic.css"); blockquote { font-style: italic; @@ -14,11 +14,13 @@ div.dbapi-extension { border: 1px solid #aaf; } +code.sql, tt.sql { font-size: 1em; background-color: transparent; } +a > code.sql:hover, a > tt.sql:hover { text-decoration: underline; } diff --git a/doc/src/conf.py b/doc/src/conf.py index a918c08..9e73308 100644 --- a/doc/src/conf.py +++ b/doc/src/conf.py @@ -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 c99c8bd..0bc584c 100644 --- a/doc/src/connection.rst +++ b/doc/src/connection.rst @@ -706,9 +706,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 aee6b46..4161f2a 100644 --- a/doc/src/cursor.rst +++ b/doc/src/cursor.rst @@ -172,33 +172,38 @@ The ``cursor`` class .. method:: execute(operation [, parameters]) - + Prepare and 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`. - + 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. Overloaded procedures are supported. Named parameters can be diff --git a/doc/src/extensions.rst b/doc/src/extensions.rst index 9c5a853..8d70ba3 100644 --- a/doc/src/extensions.rst +++ b/doc/src/extensions.rst @@ -29,6 +29,8 @@ introspection etc. 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) diff --git a/doc/src/extras.rst b/doc/src/extras.rst index d33b8ee..5ef4223 100644 --- a/doc/src/extras.rst +++ b/doc/src/extras.rst @@ -974,6 +974,63 @@ converted into lists of strings. future versions. + +.. _fast-exec: + +Fast execution helpers +---------------------- + +The current implementation of `~cursor.executemany()` is (using an extremely +charitable understatement) not particularly performing. These functions can +be used to speed up the repeated execution of a statement againts a set of +parameters. By reducing the number of server roundtrips the performance can be +`orders of magnitude better`__ than using `!executemany()`. + +.. __: https://github.com/psycopg/psycopg2/issues/491#issuecomment-276551038 + + +.. autofunction:: execute_batch + + .. versionadded:: 2.7 + +.. note:: + + `!execute_batch()` can be also used in conjunction with PostgreSQL + prepared statements using |PREPARE|_, |EXECUTE|_, |DEALLOCATE|_. + Instead of executing:: + + execute_batch(cur, + "big and complex SQL with %s %s params", + params_list) + + it is possible to execute something like:: + + cur.execute("PREPARE stmt AS big and complex SQL with $1 $2 params") + execute_batch(cur, "EXECUTE stmt (%s, %s)", params_list) + cur.execute("DEALLOCATE stmt") + + which may bring further performance benefits: if the operation to perform + is complex, every single execution will be faster as the query plan is + already cached; furthermore the amount of data to send on the server will + be lesser (one |EXECUTE| per param set instead of the whole, likely + longer, statement). + + .. |PREPARE| replace:: :sql:`PREPARE` + .. _PREPARE: https://www.postgresql.org/docs/current/static/sql-prepare.html + + .. |EXECUTE| replace:: :sql:`EXECUTE` + .. _EXECUTE: https://www.postgresql.org/docs/current/static/sql-execute.html + + .. |DEALLOCATE| replace:: :sql:`DEALLOCATE` + .. _DEALLOCATE: https://www.postgresql.org/docs/current/static/sql-deallocate.html + + +.. autofunction:: execute_values + + .. versionadded:: 2.7 + + + .. index:: single: Time zones; Fractional diff --git a/doc/src/install.rst b/doc/src/install.rst index 4611537..b364551 100644 --- a/doc/src/install.rst +++ b/doc/src/install.rst @@ -18,8 +18,8 @@ The current `!psycopg2` implementation supports: NOTE: keep consistent with setup.py and the /features/ page. - Python 2 versions from 2.6 to 2.7 -- Python 3 versions from 3.1 to 3.5 -- PostgreSQL server versions from 7.4 to 9.5 +- Python 3 versions from 3.1 to 3.6 +- PostgreSQL server versions from 7.4 to 9.6 - PostgreSQL client library version from 9.1 .. _PostgreSQL: http://www.postgresql.org/ diff --git a/doc/src/module.rst b/doc/src/module.rst index 97fbdf1..2bd259e 100644 --- a/doc/src/module.rst +++ b/doc/src/module.rst @@ -64,7 +64,8 @@ The module interface respects the standard defined in the |DBAPI|_. cursors you can use this parameter instead of subclassing a connection. Using *async*\=\ `!True` an asynchronous connection will be created: see - :ref:`async-support` to know about advantages and limitations. + :ref:`async-support` to know about advantages and limitations. *async_* is + a valid alias for the Python version where ``async`` is a keyword. .. versionchanged:: 2.4.3 any keyword argument is passed to the connection. Previously only the @@ -76,6 +77,9 @@ The module interface respects the standard defined in the |DBAPI|_. .. versionchanged:: 2.7 both *dsn* and keyword arguments can be specified. + .. versionchanged:: 2.7 + added *async_* alias. + .. seealso:: - `~psycopg2.extensions.parse_dsn` |