Author: cito
Date: Thu Jan 21 14:07:16 2016
New Revision: 775
Log:
Backport some minor doc fixes to the 4.x branch
Modified:
branches/4.x/docs/contents/pg/db_wrapper.rst
branches/4.x/docs/contents/pg/module.rst
branches/4.x/docs/contents/pgdb/types.rst
branches/4.x/pg.py
branches/4.x/pgdb.py
trunk/docs/contents/pgdb/types.rst
Modified: branches/4.x/docs/contents/pg/db_wrapper.rst
==============================================================================
--- branches/4.x/docs/contents/pg/db_wrapper.rst Thu Jan 21 13:49:28
2016 (r774)
+++ branches/4.x/docs/contents/pg/db_wrapper.rst Thu Jan 21 14:07:16
2016 (r775)
@@ -451,8 +451,14 @@
.. versionadded:: 4.2
-escape_literal -- escape a literal string for use within SQL
-------------------------------------------------------------
+escape_literal/identifier/string/bytea -- escape for SQL
+--------------------------------------------------------
+
+The following methods escape text or binary strings so that they can be
+inserted directly into an SQL command. Except for :meth:`DB.escape_byte`,
+you don't need to call these methods for the strings passed as parameters
+to :meth:`DB.query`. You also don't need to call any of these methods
+when storing data using :meth:`DB.insert` and similar.
.. method:: DB.escape_literal(string)
@@ -469,9 +475,6 @@
.. versionadded:: 4.1
-escape_identifier -- escape an identifier string for use within SQL
--------------------------------------------------------------------
-
.. method:: DB.escape_identifier(string)
Escape a string for use within SQL as an identifier
@@ -488,9 +491,6 @@
.. versionadded:: 4.1
-escape_bytea -- escape binary data for use within SQL
------------------------------------------------------
-
.. method:: DB.escape_bytea(datastring)
Escape binary data for use within SQL as type ``bytea``
@@ -499,12 +499,12 @@
:returns: the escaped string
:rtype: str
-Similar to the module function with the same name, but the
-behavior of this method is adjusted depending on the connection properties
-(in particular, whether standard-conforming strings are enabled).
+Similar to the module function :func:`pg.escape_string` with the same name,
+but the behavior of this method is adjusted depending on the connection
+properties (such as character encoding).
-unescape_bytea -- unescape data that has been retrieved as text
----------------------------------------------------------------
+unescape_bytea -- unescape data retrieved from the database
+-----------------------------------------------------------
.. method:: DB.unescape_bytea(string)
@@ -514,7 +514,7 @@
:returns: byte string containing the binary data
:rtype: str
-See the module function with the same name.
+See the module function :func:`pg.unescape_bytea` with the same name.
use_regtypes -- determine use of regular type names
---------------------------------------------------
Modified: branches/4.x/docs/contents/pg/module.rst
==============================================================================
--- branches/4.x/docs/contents/pg/module.rst Thu Jan 21 13:49:28 2016
(r774)
+++ branches/4.x/docs/contents/pg/module.rst Thu Jan 21 14:07:16 2016
(r775)
@@ -445,8 +445,10 @@
Get the function that converts to named tuples
-This function returns the function used by PyGreSQL to construct the
-result of the :meth:`pgqueryobject.namedresult` method.
+This returns the function used by PyGreSQL to construct the result of the
+:meth:`pgqueryobject.namedresult` method.
+
+.. versionadded:: 4.1
.. function:: set_namedresult(func)
@@ -454,8 +456,11 @@
:param func: the function to be used to convert results to named tuples
-You can use this if you want to create different kinds of named tuples
-returned by the :meth:`pgqueryobject.namedresult` method.
+You can use this if you want to create different kinds of named tuples returned
+by the :meth:`pgqueryobject.namedresult` method. If you set this function to
+*None*, then it will become equal to :meth:`pgqueryobject.getresult`.
+
+.. versionadded:: 4.1
Module constants
Modified: branches/4.x/docs/contents/pgdb/types.rst
==============================================================================
--- branches/4.x/docs/contents/pgdb/types.rst Thu Jan 21 13:49:28 2016
(r774)
+++ branches/4.x/docs/contents/pgdb/types.rst Thu Jan 21 14:07:16 2016
(r775)
@@ -3,15 +3,22 @@
.. py:currentmodule:: pgdb
-.. class:: pgdbType
+Type constructors
+-----------------
-The :attr:`pgdbCursor.description` attribute returns information about each
-of the result columns of a query. The *type_code* must compare equal to one
-of the :class:`pgdbType` objects defined below. Type objects can be equal to
-more than one type code (e.g. :class:`DATETIME` is equal to the type codes
-for date, time and timestamp columns).
+For binding to an operation's input parameters, PostgreSQL needs to have
+the input in a particular format. However, from the parameters to the
+:meth:`pgdbCursor.execute` and :meth:`pgdbCursor.executemany` methods it
+is not always obvious as which PostgreSQL data types they shall be bound.
+For instance, a Python string could be bound as a simple ``char`` value,
+or also as a ``date`` or a ``time``. To make the intention clear in such
+cases, you can wrap the parameters in type helper objects. PyGreSQL provides
+the constructors defined below to create such objects that can hold special
+values. When passed to the cursor methods, PyGreSQL can then detect the
+proper type of the input parameter and bind it accordingly.
-The :mod:`pgdb` module exports the following constructors and singletons:
+The :mod:`pgdb` module exports the following type constructors as part of
+the DB-API 2 standard:
.. function:: Date(year, month, day)
@@ -41,70 +48,90 @@
Construct an object capable of holding a (long) binary string value
-.. class:: STRING
+.. note::
+
+ SQL ``NULL`` values are always represented by the Python *None* singleton
+ on input and output.
+
+Type objects
+------------
+
+.. class:: pgdbType
+
+The :attr:`pgdbCursor.description` attribute returns information about each
+of the result columns of a query. The *type_code* must compare equal to one
+of the :class:`pgdbType` objects defined below. Type objects can be equal to
+more than one type code (e.g. :class:`DATETIME` is equal to the type codes
+for date, time and timestamp columns).
+
+The pgdb module exports the following :class:`Type` objects as part of the
+DB-API 2 standard:
+
+.. object:: STRING
Used to describe columns that are string-based (e.g. ``char``,
``varchar``, ``text``)
-.. class:: BINARY type
+.. object:: BINARY
Used to describe (long) binary columns (``bytea``)
-.. class:: NUMBER
+.. object:: NUMBER
Used to describe numeric columns (e.g. ``int``, ``float``, ``numeric``,
``money``)
-.. class:: DATETIME
+.. object:: DATETIME
Used to describe date/time columns (e.g. ``date``, ``time``,
``timestamp``, ``interval``)
-.. class:: ROWID
+.. object:: ROWID
Used to describe the ``oid`` column of PostgreSQL database tables
.. note::
- The following more specific types are not part of the DB-API 2 standard.
+ The following more specific type objects are not part of the DB-API 2
standard.
-.. class:: BOOL
+.. object:: BOOL
Used to describe ``boolean`` columns
-.. class:: SMALLINT
+.. object:: SMALLINT
Used to describe ``smallint`` columns
-.. class:: INTEGER
+.. object:: INTEGER
Used to describe ``integer`` columns
-.. class:: LONG
+.. object:: LONG
Used to describe ``bigint`` columns
-.. class:: FLOAT
+.. object:: FLOAT
Used to describe ``float`` columns
-.. class:: NUMERIC
+.. object:: NUMERIC
Used to describe ``numeric`` columns
-.. class:: MONEY
+.. object:: MONEY
Used to describe ``money`` columns
-.. class:: DATE
+.. object:: DATE
Used to describe ``date`` columns
-.. class:: TIME
+.. object:: TIME
Used to describe ``time`` columns
-.. class:: TIMESTAMP
+.. object:: TIMESTAMP
Used to describe ``timestamp`` columns
-.. class:: INTERVAL
+.. object:: INTERVAL
Used to describe date and time ``interval`` columns
+
Modified: branches/4.x/pg.py
==============================================================================
--- branches/4.x/pg.py Thu Jan 21 13:49:28 2016 (r774)
+++ branches/4.x/pg.py Thu Jan 21 14:07:16 2016 (r775)
@@ -140,6 +140,8 @@
return _db_error(msg, ProgrammingError)
+# The notification handler
+
class NotificationHandler(object):
"""A PostgreSQL client-side asynchronous notification handler."""
Modified: branches/4.x/pgdb.py
==============================================================================
--- branches/4.x/pgdb.py Thu Jan 21 13:49:28 2016 (r774)
+++ branches/4.x/pgdb.py Thu Jan 21 14:07:16 2016 (r775)
@@ -671,7 +671,7 @@
def Timestamp(year, month, day, hour=0, minute=0, second=0, microsecond=0):
- """construct an object holding a time stamp value."""
+ """Construct an object holding a time stamp value."""
return datetime(year, month, day, hour, minute, second, microsecond)
@@ -681,17 +681,17 @@
def TimeFromTicks(ticks):
- """construct an object holding a time value from the given ticks value."""
+ """Construct an object holding a time value from the given ticks value."""
return Time(*localtime(ticks)[3:6])
def TimestampFromTicks(ticks):
- """construct an object holding a time stamp from the given ticks value."""
+ """Construct an object holding a time stamp from the given ticks value."""
return Timestamp(*localtime(ticks)[:6])
class Binary(str):
- """construct an object capable of holding a binary (long) string value."""
+ """Construct an object capable of holding a binary (long) string value."""
# If run as script, print some information:
Modified: trunk/docs/contents/pgdb/types.rst
==============================================================================
--- trunk/docs/contents/pgdb/types.rst Thu Jan 21 13:49:28 2016 (r774)
+++ trunk/docs/contents/pgdb/types.rst Thu Jan 21 14:07:16 2016 (r775)
@@ -18,7 +18,7 @@
When passed to the cursor methods, PyGreSQL can then detect the proper type
of the input parameter and bind it accordingly.
-The :mod:`pgdb` module exports the following constructors that as part of
+The :mod:`pgdb` module exports the following type constructors as part of
the DB-API 2 standard:
.. function:: Date(year, month, day)
@@ -67,7 +67,7 @@
.. note::
- SQL NULL values are always represented by the Python *None* singleton
+ SQL ``NULL`` values are always represented by the Python *None* singleton
on input and output.
Type objects
@@ -76,7 +76,7 @@
.. class:: Type
The :attr:`Cursor.description` attribute returns information about each
-of the result columns of a query. The *type_code* must compare equal to one
+of the result columns of a query. The *type_code* must compare equal to one
of the :class:`Type` objects defined below. Type objects can be equal to
more than one type code (e.g. :class:`DATETIME` is equal to the type codes
for ``date``, ``time`` and ``timestamp`` columns).
@@ -106,7 +106,7 @@
.. note::
- The following more specific types are not part of the DB-API 2 standard.
+ The following more specific type objects are not part of the DB-API 2
standard.
.. object:: BOOL
_______________________________________________
PyGreSQL mailing list
[email protected]
https://mail.vex.net/mailman/listinfo.cgi/pygresql
