Changeset 808 for trunk


Ignore:
Timestamp:
Feb 1, 2016, 4:28:34 AM (4 years ago)
Author:
cito
Message:

Add documentation for cast_array and cast_record

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/docs/contents/pg/module.rst

    r806 r808  
    433433
    434434get/set_array -- whether arrays are returned as list objects
    435 -------------------------------------------------------------
     435------------------------------------------------------------
    436436
    437437.. function:: get_array()
     
    595595supported by the C extension module.
    596596
     597cast_array/record -- fast parsers for arrays and records
     598--------------------------------------------------------
     599
     600PosgreSQL returns arrays and records (composite types) using a special output
     601syntax with several quirks that cannot easily and quickly be parsed in Python.
     602Therefore the C extension module provides two fast parsers that allow quickly
     603turning these text representations into Python objects: Arrays will be
     604converted to Python lists, and records to Python tuples.  These fast parsers
     605are used automatically by PyGreSQL in order to return arrays and records from
     606database queries as lists and tuples, so you normally don't need to call them
     607directly.  You may only need them for typecasting arrays of data types that
     608are not supported by default in PostgreSQL.
     609
     610.. function::  cast_array(string, [cast], [delim])
     611
     612    Cast a string representing a PostgreSQL array to a Python list
     613
     614    :param str string: the string with the text representation of the array
     615    :param cast: a typecast function for the elements of the array
     616    :type cast: callable or None
     617    :param delim: delimiter character between adjacent elements
     618    :type str: byte string with a single character
     619    :returns: a list representing the PostgreSQL array in Python
     620    :rtype: list
     621    :raises TypeError: invalid argument types
     622    :raises ValueError: error in the syntax of the given array
     623
     624This function takes a *string* containing the text representation of a
     625PostgreSQL array (which may look like ``'{{1,2}{3,4}}'`` for a two-dimensional
     626array), a typecast function *cast* that is called for every element, and
     627an optional delimiter character *delim* (usually a comma), and returns a
     628Python list representing the array (which may be nested like
     629``[[1, 2], [3, 4]]`` in this example).  The cast function must take a single
     630argument which will be the text representation of the element and must output
     631the corresponding Python object that shall be put into the list.  If you don't
     632pass a cast function or set it to *None*, then unprocessed text strings will
     633be returned as elements of the array.  If you don't pass a delimiter character,
     634then a comma will be used by default.
     635
     636.. versionadded:: 5.0
     637
     638.. function::  cast_record(string, [cast], [delim])
     639
     640    Cast a string representing a PostgreSQL record to a Python list
     641
     642    :param str string: the string with the text representation of the record
     643    :param cast: typecast function(s) for the elements of the record
     644    :type cast: callable, list or tuple of callables, or None
     645    :param delim: delimiter character between adjacent elements
     646    :type str: byte string with a single character
     647    :returns: a tuple representing the PostgreSQL record in Python
     648    :rtype: tuple
     649    :raises TypeError: invalid argument types
     650    :raises ValueError: error in the syntax of the given array
     651
     652This function takes a *string* containing the text representation of a
     653PostgreSQL record (which may look like ``'(1,a,2,b)'`` for a record composed
     654of four fields), a typecast function *cast* that is called for every element,
     655or a list or tuple of such functions corresponding to the individual fields
     656of the record, and an optional delimiter character *delim* (usually a comma),
     657and returns a Python tuple representing the record (which may be inhomogeneous
     658like ``(1, 'a', 2, 'b')`` in this example).  The cast function(s) must take a
     659single argument which will be the text representation of the element and must
     660output the corresponding Python object that shall be put into the tuple.  If
     661you don't pass cast function(s) or pass *None* instead, then unprocessed text
     662strings will be returned as elements of the tuple.  If you don't pass a
     663delimiter character, then a comma will be used by default.
     664
     665.. versionadded:: 5.0
     666
     667Note that besides using parentheses instead of braces, there are other subtle
     668differences in escaping special characters and NULL values between the syntax
     669used for arrays and the one used for composite types, which these functions
     670take into account.
     671
    597672Type helpers
    598673------------
Note: See TracChangeset for help on using the changeset viewer.