Changeset 798 for trunk/docs


Ignore:
Timestamp:
Jan 30, 2016, 2:55:18 PM (4 years ago)
Author:
cito
Message:

Port type cache and typecasting from pgdb to pg

So far, the typecasting in the classic module was been only done by
the C extension module and was not extensible through typecasting
functions in Python. This has now been made extensible by adding
a cast hook to the C extension module which has been hooked up to
a new type cache object that holds information on the types and the
associated typecast functions. All of this works very similar to the
pgdb module now, except that the basic types are still handled by
the C extension module and the Python typecast functions are only
called via the hook for types which are not supported internally.

Also added tests and a chapter on the type cache in the documentation,
and cleaned up the error messages in the C extension module.

Location:
trunk/docs/contents
Files:
7 edited
1 copied

Legend:

Unmodified
Added
Removed
  • trunk/docs/contents/changelog.rst

    r796 r798  
    8585    types have been refactored and swapped out to separate classes.
    8686- Changes concerning both modules:
     87  - The modules now provide get_typecast() and set_typecast() methods
     88    allowing to control the typecasting on the global level.  The connection
     89    objects have got type caches with the same methods which give control
     90    over the typecasting on the level of the current connection.
     91    See the documentation on details about the type cache and the typecast
     92    mechanisms provided by PyGreSQL.
    8793  - PyGreSQL now supports the JSON and JSONB data types, converting such
    8894    columns automatically to and from Python objects. If you want to insert
  • trunk/docs/contents/pg/connection.rst

    r751 r798  
    191191.. versionadded:: 4.1
    192192
    193 .. method:: Connection.set_notice_receiver(proc)
     193.. method:: Connection.set_notice_receiver(func)
    194194
    195195    Set a custom notice receiver
    196196
    197     :param proc: the custom notice receiver callback function
     197    :param func: the custom notice receiver callback function
    198198    :rtype: None
    199199    :raises TypeError: the specified notice receiver is not callable
  • trunk/docs/contents/pg/db_types.rst

    r797 r798  
    1 TypeCache -- The internal cache for database types
    2 ==================================================
     1DbTypes -- The internal cache for database types
     2================================================
    33
    4 .. py:currentmodule:: pgdb
     4.. py:currentmodule:: pg
    55
    6 .. class:: TypeCache
     6.. class:: DbTypes
    77
    88.. versionadded:: 5.0
    99
    10 The internal :class:`TypeCache` of PyGreSQL is not part of the DB-API 2
    11 standard, but is documented here in case you need full control and
    12 understanding of the internal handling of database types.
     10The :class:`DbTypes` object is essentially a dictionary mapping PostgreSQL
     11internal type names and type OIDs to PyGreSQL "type names" (which are also
     12returned by :meth:`DB.get_attnames` as dictionary values).
    1313
    14 The TypeCache is essentially a dictionary mapping PostgreSQL internal
    15 type names and type OIDs to DB-API 2 "type codes" (which are also returned
    16 as the *type_code* field of the :attr:`Cursor.description` attribute).
    17 
    18 These type codes are strings which are equal to the PostgreSQL internal
    19 type name, but they are also carrying additional information about the
     14These type names are strings which are equal to the simple PyGreSQL name or
     15to regular type names if these have been enabled with :meth:`DB.use_regtypes`.
     16Besides being strings, they are also carrying additional information about the
    2017associated PostgreSQL type in the following attributes:
    2118
    22         - *oid* -- the OID of the type
    23         - *len*  -- the internal size
    24         - *type*  -- ``'b'`` = base, ``'c'`` = composite, ...
    25         - *category*  -- ``'A'`` = Array, ``'B'`` = Boolean, ...
    26         - *delim*  -- delimiter to be used when parsing arrays
    27         - *relid*  -- the table OID for composite types
     19        - *oid* -- the PostgreSQL type OID
     20        - *pgtype* -- the PostgreSQL type name
     21        - *regtype* -- the regular type name
     22        - *simple* -- the simple PyGreSQL type name
     23        - *typtype* -- `b` = base type, `c` = composite type etc.
     24        - *category* -- `A` = Array, `b` =Boolean, `C` = Composite etc.
     25        - *delim* -- delimiter for array types
     26        - *relid* -- corresponding table for composite types
     27        - *attnames* -- attributes for composite types
    2828
    2929For details, see the PostgreSQL documentation on `pg_type
    3030<http://www.postgresql.org/docs/current/static/catalog-pg-type.html>`_.
    3131
    32 In addition to the dictionary methods, the :class:`TypeCache` provides
    33 the following methods:
     32In addition to the dictionary methods, the :class:`DbTypes` class also
     33provides the following methods:
    3434
    35 .. method:: TypeCache.get_fields(typ)
     35.. method:: DbTypes.get_attnames(typ)
    3636
    3737    Get the names and types of the fields of composite types
     
    3939    :param typ: PostgreSQL type name or OID of a composite type
    4040    :type typ: str or int
    41     :returns: a list of pairs of field names and types
    42     :rtype: list
     41    :returns: an ordered dictionary mapping field names to type names
    4342
    44 .. method:: TypeCache.get_typecast(typ)
     43.. method:: DbTypes.get_typecast(typ)
    4544
    4645    Get the cast function for the given database type
    4746
    48     :param str typ: PostgreSQL type name or type code
     47    :param str typ: PostgreSQL type name
    4948    :returns: the typecast function for the specified type
    5049    :rtype: function or None
    5150
    52 .. method:: TypeCache.set_typecast(typ, cast)
     51.. method:: DbTypes.set_typecast(typ, cast)
    5352
    5453    Set a typecast function for the given database type(s)
    5554
    56     :param typ: PostgreSQL type name or type code, or list of such
     55    :param typ: PostgreSQL type name or list of type names
    5756    :type typ: str or list
    5857    :param cast: the typecast function to be set for the specified type(s)
    5958    :type typ: str or int
    6059
    61 .. method:: TypeCache.reset_typecast([typ])
     60.. method:: DbTypes.reset_typecast([typ])
    6261
    6362    Reset the typecasts for the specified (or all) type(s) to their defaults
    6463
    65     :param str typ: PostgreSQL type name or type code, or list of such,
     64    :param str typ: PostgreSQL type name or list of type names,
    6665        or None to reset all typecast functions
    6766    :type typ: str, list or None
    6867
    69 .. method:: TypeCache.typecast(typ, value)
     68.. method:: DbTypes.typecast(value, typ)
    7069
    7170    Cast the given value according to the given database type
     
    7473    :returns: the casted value
    7574
    76 
    7775.. note::
    7876
    79     Note that the :class:`TypeCache` is always bound to a database connection.
    80     You can also get, set and reset typecast functions on a global level using
    81     the functions :func:`pgdb.get_typecast`, :func:`pgdb.set_typecast` and
    82     :func:`pgdb.reset_typecast`.  If you do this, the current database
    83     connections will continue to use their already cached typecast functions
    84     unless you call the :meth:`TypeCache.reset_typecast` method on the
    85     :attr:`Connection.type_cache` of the running connections.
     77    Note that :class:`DbTypes` object is always bound to a database connection.
     78    You can also get and set and reset typecast functions on a global level
     79    using the functions :func:`pg.get_typecast` and :func:`pg.set_typecast`.
     80    If you do this, the current database connections will continue to use their
     81    already cached typecast functions unless you reset the typecast functions
     82    by calling the :meth:`DbTypes.reset_typecast` method on :attr:`DB.dbtypes`
     83    objects of the running connections.
     84
     85    Also note that the typecasting for all of the basic types happens already
     86    in the C extension module.  The typecast functions that can be set with
     87    the above methods are only called for the types that are not already
     88    supported by the C extension module.
  • trunk/docs/contents/pg/db_wrapper.rst

    r781 r798  
    765765
    766766.. versionadded:: 4.1.1
     767
     768Attributes of the DB wrapper class
     769----------------------------------
     770
     771.. attribute:: DB.db
     772
     773    The wrapped :class:`Connection` object
     774
     775You normally don't need this, since all of the members can be accessed
     776from the :class:`DB` wrapper class as well.
     777
     778.. attribute:: DB.dbname
     779
     780    The name of the database that the connection is using
     781
     782
     783.. attribute:: DB.dbtypes
     784
     785    A dictionary with the various type names for the PostgreSQL types
     786
     787This can be used for getting more information on the PostgreSQL database
     788types or changing the typecast functions used for the connection.  See the
     789description of the :class:`DbTypes` class for details.
     790
     791.. versionadded:: 5.0
  • trunk/docs/contents/pg/index.rst

    r762 r798  
    1616    large_objects
    1717    notification
     18    db_types
  • trunk/docs/contents/pg/module.rst

    r781 r798  
    453453.. versionadded:: 5.0
    454454
     455get/set_typecast -- custom typecasting
     456--------------------------------------
     457
     458PyGreSQL uses typecast functions to cast the raw data coming from the
     459database to Python objects suitable for the particular database type.
     460These functions take a single string argument that represents the data
     461to be casted and must return the casted value.
     462
     463PyGreSQL provides through its C extension module basic typecast functions
     464for the common database types, but if you want to add more typecast functions,
     465you can set these using the following functions.
     466
     467.. method:: get_typecast(typ)
     468
     469    Get the global cast function for the given database type
     470
     471    :param str typ: PostgreSQL type name
     472    :returns: the typecast function for the specified type
     473    :rtype: function or None
     474
     475.. versionadded:: 5.0
     476
     477.. method:: set_typecast(typ, cast)
     478
     479    Set a global typecast function for the given database type(s)
     480
     481    :param typ: PostgreSQL type name or list of type names
     482    :type typ: str or list
     483    :param cast: the typecast function to be set for the specified type(s)
     484    :type typ: str or int
     485
     486.. versionadded:: 5.0
     487
     488Note that database connections cache types and their cast functions using
     489connection specific :class:`DbTypes` objects.  You can also get, set and
     490reset typecast functions on the connection level using the methods
     491:meth:`DbTypes.get_typecast`, :meth:`DbTypes.set_typecast` and
     492:meth:`DbTypes.reset_typecast` of the :attr:`DB.dbtypes` object.  This will
     493not affect other connections or future connections.  In order to be sure
     494a global change is picked up by a running connection, you must reopen it or
     495call :meth:`DbTypes.reset_typecast` on the :attr:`DB.dbtypes` object.
     496
     497Also note that the typecasting for all of the basic types happens already
     498in the C extension module.  The typecast functions that can be set with
     499the above methods are only called for the types that are not already
     500supported by the C extension module.
     501
    455502
    456503Module constants
  • trunk/docs/contents/pgdb/module.rst

    r797 r798  
    4747
    4848PyGreSQL provides built-in typecast functions for the common database types,
    49 but if you want to change these or add more typecast functions, you can use
    50 the following functions.
     49but if you want to change these or add more typecast functions, you can set
     50these up using the following functions.
    5151
    5252.. note::
     
    9090:meth:`TypeCache.get_typecast`, :meth:`TypeCache.set_typecast` and
    9191:meth:`TypeCache.reset_typecast` of the :attr:`Connection.type_cache`.  This
    92 will not affect other connections or future connections. In order to be sure
     92will not affect other connections or future connections.  In order to be sure
    9393a global change is picked up by a running connection, you must reopen it or
    9494call :meth:`TypeCache.reset_typecast` on the :attr:`Connection.type_cache`.
  • trunk/docs/contents/pgdb/typecache.rst

    r797 r798  
    6767    :type typ: str, list or None
    6868
    69 .. method:: TypeCache.typecast(typ, value)
     69.. method:: TypeCache.typecast(value, typ)
    7070
    7171    Cast the given value according to the given database type
     
    7373    :param str typ: PostgreSQL type name or type code
    7474    :returns: the casted value
    75 
    7675
    7776.. note::
     
    8281    :func:`pgdb.reset_typecast`.  If you do this, the current database
    8382    connections will continue to use their already cached typecast functions
    84     unless you call the :meth:`TypeCache.reset_typecast` method on the
    85     :attr:`Connection.type_cache` of the running connections.
     83    unless call the :meth:`TypeCache.reset_typecast` method on the
     84    :attr:`Connection.type_cache` objects of the running connections.
Note: See TracChangeset for help on using the changeset viewer.