Changeset 775 for branches/4.x


Ignore:
Timestamp:
Jan 21, 2016, 2:07:16 PM (4 years ago)
Author:
cito
Message:

Backport some minor doc fixes to the 4.x branch

Location:
branches/4.x
Files:
5 edited

Legend:

Unmodified
Added
Removed
  • branches/4.x/docs/contents/pg/db_wrapper.rst

    r771 r775  
    452452.. versionadded:: 4.2
    453453
    454 escape_literal -- escape a literal string for use within SQL
    455 ------------------------------------------------------------
     454escape_literal/identifier/string/bytea -- escape for SQL
     455--------------------------------------------------------
     456
     457The following methods escape text or binary strings so that they can be
     458inserted directly into an SQL command.  Except for :meth:`DB.escape_byte`,
     459you don't need to call these methods for the strings passed as parameters
     460to :meth:`DB.query`.  You also don't need to call any of these methods
     461when storing data using :meth:`DB.insert` and similar.
    456462
    457463.. method:: DB.escape_literal(string)
     
    469475
    470476.. versionadded:: 4.1
    471 
    472 escape_identifier -- escape an identifier string for use within SQL
    473 -------------------------------------------------------------------
    474477
    475478.. method:: DB.escape_identifier(string)
     
    489492.. versionadded:: 4.1
    490493
    491 escape_bytea -- escape binary data for use within SQL
    492 -----------------------------------------------------
    493 
    494494.. method:: DB.escape_bytea(datastring)
    495495
     
    500500    :rtype: str
    501501
    502 Similar to the module function with the same name, but the
    503 behavior of this method is adjusted depending on the connection properties
    504 (in particular, whether standard-conforming strings are enabled).
    505 
    506 unescape_bytea -- unescape data that has been retrieved as text
    507 ---------------------------------------------------------------
     502Similar to the module function :func:`pg.escape_string` with the same name,
     503but the behavior of this method is adjusted depending on the connection
     504properties (such as character encoding).
     505
     506unescape_bytea -- unescape data retrieved from the database
     507-----------------------------------------------------------
    508508
    509509.. method:: DB.unescape_bytea(string)
     
    515515    :rtype: str
    516516
    517 See the module function with the same name.
     517See the module function :func:`pg.unescape_bytea` with the same name.
    518518
    519519use_regtypes -- determine use of regular type names
  • branches/4.x/docs/contents/pg/module.rst

    r708 r775  
    446446    Get the function that converts to named tuples
    447447
    448 This function returns the function used by PyGreSQL to construct the
    449 result of the :meth:`pgqueryobject.namedresult` method.
     448This returns the function used by PyGreSQL to construct the result of the
     449:meth:`pgqueryobject.namedresult` method.
     450
     451.. versionadded:: 4.1
    450452
    451453.. function:: set_namedresult(func)
     
    455457    :param func: the function to be used to convert results to named tuples
    456458
    457 You can use this if you want to create different kinds of named tuples
    458 returned by the :meth:`pgqueryobject.namedresult` method.
     459You can use this if you want to create different kinds of named tuples returned
     460by the :meth:`pgqueryobject.namedresult` method.  If you set this function to
     461*None*, then it will become equal to :meth:`pgqueryobject.getresult`.
     462
     463.. versionadded:: 4.1
    459464
    460465
  • branches/4.x/docs/contents/pgdb/types.rst

    r708 r775  
    44.. py:currentmodule:: pgdb
    55
    6 .. class:: pgdbType
     6Type constructors
     7-----------------
    78
    8 The :attr:`pgdbCursor.description` attribute returns information about each
    9 of the result columns of a query. The *type_code* must compare equal to one
    10 of the :class:`pgdbType` objects defined below. Type objects can be equal to
    11 more than one type code (e.g. :class:`DATETIME` is equal to the type codes
    12 for date, time and timestamp columns).
     9For binding to an operation's input parameters, PostgreSQL needs to have
     10the input in a particular format.  However, from the parameters to the
     11:meth:`pgdbCursor.execute` and :meth:`pgdbCursor.executemany` methods it
     12is not always obvious as which PostgreSQL data types they shall be bound.
     13For instance, a Python string could be bound as a simple ``char`` value,
     14or also as a ``date`` or a ``time``.  To make the intention clear in such
     15cases, you can wrap the parameters in type helper objects.  PyGreSQL provides
     16the constructors defined below to create such objects that can hold special
     17values.  When passed to the cursor methods, PyGreSQL can then detect the
     18proper type of the input parameter and bind it accordingly.
    1319
    14 The :mod:`pgdb` module exports the following constructors and singletons:
     20The :mod:`pgdb` module exports the following type constructors as part of
     21the DB-API 2 standard:
    1522
    1623.. function:: Date(year, month, day)
     
    4249    Construct an object capable of holding a (long) binary string value
    4350
    44 .. class:: STRING
     51.. note::
     52
     53    SQL ``NULL`` values are always represented by the Python *None* singleton
     54    on input and output.
     55
     56Type objects
     57------------
     58
     59.. class:: pgdbType
     60
     61The :attr:`pgdbCursor.description` attribute returns information about each
     62of the result columns of a query.  The *type_code* must compare equal to one
     63of the :class:`pgdbType` objects defined below.  Type objects can be equal to
     64more than one type code (e.g. :class:`DATETIME` is equal to the type codes
     65for date, time and timestamp columns).
     66
     67The pgdb module exports the following :class:`Type` objects as part of the
     68DB-API 2 standard:
     69
     70.. object:: STRING
    4571
    4672    Used to describe columns that are string-based (e.g. ``char``, ``varchar``, ``text``)
    4773
    48 .. class:: BINARY type
     74.. object:: BINARY
    4975
    5076    Used to describe (long) binary columns (``bytea``)
    5177
    52 .. class:: NUMBER
     78.. object:: NUMBER
    5379
    5480    Used to describe numeric columns (e.g. ``int``, ``float``, ``numeric``, ``money``)
    5581
    56 .. class:: DATETIME
     82.. object:: DATETIME
    5783
    5884    Used to describe date/time columns (e.g. ``date``, ``time``, ``timestamp``, ``interval``)
    5985
    60 .. class:: ROWID
     86.. object:: ROWID
    6187
    6288    Used to describe the ``oid`` column of PostgreSQL database tables
     
    6490.. note::
    6591
    66     The following more specific types are not part of the DB-API 2 standard.
     92  The following more specific type objects are not part of the DB-API 2 standard.
    6793
    68 .. class:: BOOL
     94.. object:: BOOL
    6995
    7096    Used to describe ``boolean`` columns
    7197
    72 .. class:: SMALLINT
     98.. object:: SMALLINT
    7399
    74100    Used to describe ``smallint`` columns
    75101
    76 .. class:: INTEGER
     102.. object:: INTEGER
    77103
    78104    Used to describe ``integer`` columns
    79105
    80 .. class:: LONG
     106.. object:: LONG
    81107
    82108    Used to describe ``bigint`` columns
    83109
    84 .. class:: FLOAT
     110.. object:: FLOAT
    85111
    86112    Used to describe ``float`` columns
    87113
    88 .. class:: NUMERIC
     114.. object:: NUMERIC
    89115
    90116    Used to describe ``numeric`` columns
    91117
    92 .. class:: MONEY
     118.. object:: MONEY
    93119
    94120    Used to describe ``money`` columns
    95121
    96 .. class:: DATE
     122.. object:: DATE
    97123
    98124    Used to describe ``date`` columns
    99125
    100 .. class:: TIME
     126.. object:: TIME
    101127
    102128    Used to describe ``time`` columns
    103129
    104 .. class:: TIMESTAMP
     130.. object:: TIMESTAMP
    105131
    106132    Used to describe ``timestamp`` columns
    107133
    108 .. class:: INTERVAL
     134.. object:: INTERVAL
    109135
    110136    Used to describe date and time ``interval`` columns
     137
  • branches/4.x/pg.py

    r771 r775  
    140140    return _db_error(msg, ProgrammingError)
    141141
     142
     143# The notification handler
    142144
    143145class NotificationHandler(object):
  • branches/4.x/pgdb.py

    r773 r775  
    672672
    673673def Timestamp(year, month, day, hour=0, minute=0, second=0, microsecond=0):
    674     """construct an object holding a time stamp value."""
     674    """Construct an object holding a time stamp value."""
    675675    return datetime(year, month, day, hour, minute, second, microsecond)
    676676
     
    682682
    683683def TimeFromTicks(ticks):
    684     """construct an object holding a time value from the given ticks value."""
     684    """Construct an object holding a time value from the given ticks value."""
    685685    return Time(*localtime(ticks)[3:6])
    686686
    687687
    688688def TimestampFromTicks(ticks):
    689     """construct an object holding a time stamp from the given ticks value."""
     689    """Construct an object holding a time stamp from the given ticks value."""
    690690    return Timestamp(*localtime(ticks)[:6])
    691691
    692692
    693693class Binary(str):
    694     """construct an object capable of holding a binary (long) string value."""
     694    """Construct an object capable of holding a binary (long) string value."""
    695695
    696696
Note: See TracChangeset for help on using the changeset viewer.