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.

File:
1 copied

Legend:

Unmodified
Added
Removed
  • 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.
Note: See TracChangeset for help on using the changeset viewer.