Changeset 802 for trunk/docs


Ignore:
Timestamp:
Jan 31, 2016, 4:18:28 PM (3 years ago)
Author:
cito
Message:

Make the unescaping of bytea configurable

By default, bytea is returned unescaped in 5.0, but the old
behavior can now be restored with set_escaped_bytea().

Location:
trunk/docs/contents
Files:
2 edited

Legend:

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

    r800 r802  
    88- PostgreSQL is supported in all versions from 9.0 to 9.5.
    99- Changes in the DB-API 2 module (pgdb):
    10   - The DB-API 2 module now always returns result rows as named tuples
    11     instead of simply lists as before. The documentation explains how
    12     you can restore the old behavior or use custom row objects instead.
    13   - The names of the various classes used by the classic and DB-API 2
    14     modules have been renamed to become simpler, more intuitive and in
    15     line with the names used in the DB-API 2 documentation.
    16     Since the API provides only objects of these types through constructor
    17     functions, this should not cause any incompatibilities.
    18   - The DB-API 2 module now supports the callproc() cursor method. Note
    19     that output parameters are currently not replaced in the return value.
    20   - The DB-API 2 module now supports copy operations between data streams
    21     on the client and database tables via the COPY command of PostgreSQL.
    22     The cursor method copy_from() can be used to copy data from the database
    23     to the client, and the cursor method copy_to() can be used to copy data
    24     from the client to the database.
    25   - The 7-tuples returned by the description attribute of a pgdb cursor
    26     are now named tuples, i.e. their elements can be also accessed by name.
    27     The column names and types can now also be requested through the
    28     colnames and coltypes attributes, which are not part of DB-API 2 though.
    29     The type_code provided by the description attribute is still equal to
    30     the PostgreSQL internal type name, but now carries some more information
    31     in additional attributes. The size, precision and scale information that
    32     is part of the description is now properly set for numeric types.
    33   - If you pass a Python list as one of the parameters to a DB-API 2 cursor,
    34     it is now automatically bound using an ARRAY constructor. If you pass a
    35     Python tuple, it is bound using a ROW constructor. This is useful for
    36     passing records as well as making use of the IN syntax.
    37   - Inversely, when a fetch method of a DB-API 2 cursor returns a PostgreSQL
    38     array, it is passed to Python as a list, and when it returns a PostgreSQL
    39     composite type, it is passed to Python as a named tuple. PyGreSQL uses
    40     a new fast built-in parser to achieve this. Anonymous composite types are
    41     also supported, but yield only an ordinary tuple containing text strings.
     10    - The DB-API 2 module now always returns result rows as named tuples
     11      instead of simply lists as before. The documentation explains how
     12      you can restore the old behavior or use custom row objects instead.
     13    - The names of the various classes used by the classic and DB-API 2
     14      modules have been renamed to become simpler, more intuitive and in
     15      line with the names used in the DB-API 2 documentation.
     16      Since the API provides only objects of these types through constructor
     17      functions, this should not cause any incompatibilities.
     18    - The DB-API 2 module now supports the callproc() cursor method. Note
     19      that output parameters are currently not replaced in the return value.
     20    - The DB-API 2 module now supports copy operations between data streams
     21      on the client and database tables via the COPY command of PostgreSQL.
     22      The cursor method copy_from() can be used to copy data from the database
     23      to the client, and the cursor method copy_to() can be used to copy data
     24      from the client to the database.
     25    - The 7-tuples returned by the description attribute of a pgdb cursor
     26      are now named tuples, i.e. their elements can be also accessed by name.
     27      The column names and types can now also be requested through the
     28      colnames and coltypes attributes, which are not part of DB-API 2 though.
     29      The type_code provided by the description attribute is still equal to
     30      the PostgreSQL internal type name, but now carries some more information
     31      in additional attributes. The size, precision and scale information that
     32      is part of the description is now properly set for numeric types.
     33    - If you pass a Python list as one of the parameters to a DB-API 2 cursor,
     34      it is now automatically bound using an ARRAY constructor. If you pass a
     35      Python tuple, it is bound using a ROW constructor. This is useful for
     36      passing records as well as making use of the IN syntax.
     37    - Inversely, when a fetch method of a DB-API 2 cursor returns a PostgreSQL
     38      array, it is passed to Python as a list, and when it returns a PostgreSQL
     39      composite type, it is passed to Python as a named tuple. PyGreSQL uses
     40      a new fast built-in parser to achieve this. Anonymous composite types are
     41      also supported, but yield only an ordinary tuple containing text strings.
    4242- Changes in the classic PyGreSQL module (pg):
    43   - The classic interface got two new methods get_as_list() and get_as_dict()
    44     returning a database table as a Python list or dict. The amount of data
    45     returned can be controlled with various parameters.
    46   - A method upsert() has been added to the DB wrapper class that utilitses
    47     the "upsert" feature that is new in PostgreSQL 9.5. The new method nicely
    48     complements the existing get/insert/update/delete() methods.
    49   - When using insert/update/upsert(), you can now pass PostgreSQL arrays as
    50     lists and PostgreSQL records as tuples in the classic module.
    51   - Conversely, when the query method returns a PostgreSQL array, it is passed
    52     to Python as a list. PostgreSQL records are converted to named tuples as
    53     well, but only if you use one of the get/insert/update/delete() methods.
    54     PyGreSQL uses a new fast built-in parser to achieve this.
    55   - The pkey() method of the classic interface now returns tuples instead
    56     of frozenset. The order of the tuples is like in the primary key index.
    57   - Like the DB-API 2 module, the classic module now also returns bytea columns
    58     fetched from the database as byte strings, so you don't need to call
    59     unescape_bytea() any more.
    60   - A method set_jsondecode() has been added for changing or removing the
    61     function that automatically decodes JSON data coming from the database.
    62     By default, decoding JSON is now enabled and uses the decoder function
    63     in the standard library with its default parameters.
    64   - The table name that is affixed to the name of the OID column returned
    65     by the get() method of the classic interface will not automatically
    66     be fully qualified any more. This reduces overhead from the interface,
    67     but it means you must always write the table name in the same way when
    68     you call the methods using it and you are using tables with OIDs.
    69     Also, OIDs are now only used when access via primary key is not possible.
    70     Note that OIDs are considered deprecated anyway, and they are not created
    71     by default any more in PostgreSQL 8.1 and later.
    72   - The internal caching and automatic quoting of class names in the classic
    73     interface has been simplified and improved, it should now perform better
    74     and use less memory. Also, overhead for quoting values in the DB wrapper
    75     methods has been reduced and security has been improved by passing the
    76     values to libpq separately as parameters instead of inline.
    77   - It is now possible to use regular type names instead of the simpler
    78     type names that are used by default in PyGreSQL, without breaking any
    79     of the mechanisms for quoting and typecasting, which rely on the type
    80     information. This is achieved while maintaining simplicity and backward
    81     compatibility by augmenting the type name string objects with all the
    82     necessary information under the cover. To switch regular type names on
    83     or off (this is the default), call the DB wrapper method use_regtypes().
    84   - A new method query_formatted() has been added to the DB wrapper class that
    85     allows using the format specifications from Python.  A flag "inline"
    86     can be set to specify whether parameters should be sent to the database
    87     separately or formatted into the SQL.
    88   - The methods for adapting and typecasting values pertaining to PostgreSQL
    89     types have been refactored and swapped out to separate classes.
     43    - The classic interface got two new methods get_as_list() and get_as_dict()
     44      returning a database table as a Python list or dict. The amount of data
     45      returned can be controlled with various parameters.
     46    - A method upsert() has been added to the DB wrapper class that utilitses
     47      the "upsert" feature that is new in PostgreSQL 9.5. The new method nicely
     48      complements the existing get/insert/update/delete() methods.
     49    - When using insert/update/upsert(), you can now pass PostgreSQL arrays as
     50      lists and PostgreSQL records as tuples in the classic module.
     51    - Conversely, when the query method returns a PostgreSQL array, it is passed
     52      to Python as a list. PostgreSQL records are converted to named tuples as
     53      well, but only if you use one of the get/insert/update/delete() methods.
     54      PyGreSQL uses a new fast built-in parser to achieve this.
     55    - The pkey() method of the classic interface now returns tuples instead
     56      of frozenset. The order of the tuples is like in the primary key index.
     57    - Like the DB-API 2 module, the classic module now also returns bytea
     58      columns fetched from the database as byte strings, so you don't need to
     59      call unescape_bytea() any more.  This has been made configurable though,
     60      and you can restore the old behavior by calling set_bytea_escaped(True).
     61    - A method set_jsondecode() has been added for changing or removing the
     62      function that automatically decodes JSON data coming from the database.
     63      By default, decoding JSON is now enabled and uses the decoder function
     64      in the standard library with its default parameters.
     65    - The table name that is affixed to the name of the OID column returned
     66      by the get() method of the classic interface will not automatically
     67      be fully qualified any more. This reduces overhead from the interface,
     68      but it means you must always write the table name in the same way when
     69      you call the methods using it and you are using tables with OIDs.
     70      Also, OIDs are now only used when access via primary key is not possible.
     71      Note that OIDs are considered deprecated anyway, and they are not created
     72      by default any more in PostgreSQL 8.1 and later.
     73    - The internal caching and automatic quoting of class names in the classic
     74      interface has been simplified and improved, it should now perform better
     75      and use less memory. Also, overhead for quoting values in the DB wrapper
     76      methods has been reduced and security has been improved by passing the
     77      values to libpq separately as parameters instead of inline.
     78    - It is now possible to use regular type names instead of the simpler
     79      type names that are used by default in PyGreSQL, without breaking any
     80      of the mechanisms for quoting and typecasting, which rely on the type
     81      information. This is achieved while maintaining simplicity and backward
     82      compatibility by augmenting the type name string objects with all the
     83      necessary information under the cover. To switch regular type names on
     84      or off (this is the default), call the DB wrapper method use_regtypes().
     85    - A new method query_formatted() has been added to the DB wrapper class
     86      that allows using the format specifications from Python.  A flag "inline"
     87      can be set to specify whether parameters should be sent to the database
     88      separately or formatted into the SQL.
     89    - The methods for adapting and typecasting values pertaining to PostgreSQL
     90      types have been refactored and swapped out to separate classes.
    9091- Changes concerning both modules:
    91   - The modules now provide get_typecast() and set_typecast() methods
    92     allowing to control the typecasting on the global level.  The connection
    93     objects have got type caches with the same methods which give control
    94     over the typecasting on the level of the current connection.
    95     See the documentation on details about the type cache and the typecast
    96     mechanisms provided by PyGreSQL.
    97   - PyGreSQL now supports the JSON and JSONB data types, converting such
    98     columns automatically to and from Python objects. If you want to insert
    99     Python objects as JSON data using DB-API 2, you should wrap them in the
    100     new Json() type constructor as a hint to PyGreSQL.
    101   - New type helpers Literal(), Json() and Bytea() have been added.
    102   - Fast parsers for the input and output syntax for PostgreSQL arrays and
    103     composite types have been added to the C module. Note that you can also
    104     use multi-dimensional arrays with PyGreSQL.
    105   - The tty parameter and attribute of database connections has been
    106     removed since it is not supported any more since PostgreSQL 7.4.
     92    - The modules now provide get_typecast() and set_typecast() methods
     93      allowing to control the typecasting on the global level.  The connection
     94      objects have got type caches with the same methods which give control
     95      over the typecasting on the level of the current connection.
     96      See the documentation on details about the type cache and the typecast
     97      mechanisms provided by PyGreSQL.
     98    - PyGreSQL now supports the JSON and JSONB data types, converting such
     99      columns automatically to and from Python objects. If you want to insert
     100      Python objects as JSON data using DB-API 2, you should wrap them in the
     101      new Json() type constructor as a hint to PyGreSQL.
     102    - New type helpers Literal(), Json() and Bytea() have been added.
     103    - Fast parsers for the input and output syntax for PostgreSQL arrays and
     104      composite types have been added to the C module. Note that you can also
     105      use multi-dimensional arrays with PyGreSQL.
     106    - The tty parameter and attribute of database connections has been
     107      removed since it is not supported any more since PostgreSQL 7.4.
    107108
    108109Version 4.2 (2016-01-21)
  • trunk/docs/contents/pg/module.rst

    r801 r802  
    405405.. versionadded:: 4.2
    406406
     407get/set_bytea_escaped -- whether bytea values are returned escaped
     408------------------------------------------------------------------
     409
     410.. function:: get_bytea_escaped()
     411
     412    Check whether bytea values are returned as escaped strings
     413
     414    :returns: whether or not bytea objects will be returned escaped
     415    :rtype: bool
     416
     417This function checks whether PyGreSQL returns PostgreSQL ``bytea`` values in
     418escaped form or in unescaped from as byte strings.  By default, bytea values
     419will be returned unescaped as byte strings, but you can change this with the
     420``set_bytea_escaped()`` method.
     421
     422.. versionadded:: 5.0
     423
     424.. function:: set_bytea_escaped(on)
     425
     426    Set whether bytea values are returned as escaped strings
     427
     428    :param on: whether or not bytea objects shall be returned escaped
     429
     430This function can be used to specify whether PyGreSQL shall return
     431PostgreSQL ``bytea`` values in escaped form or in unescaped from as byte
     432strings.  By default, bytea values will be returned unescaped as byte
     433strings, but you can change this by calling ``set_bytea_escaped(True)``.
     434
     435.. versionadded:: 5.0
     436
     437.. versionchanged:: 5.0
     438   Bytea values had been returned in escaped form in earlier versions.
     439
    407440get/set_namedresult -- conversion to named tuples
    408441-------------------------------------------------
Note: See TracChangeset for help on using the changeset viewer.