Changeset 770 for trunk/docs


Ignore:
Timestamp:
Jan 20, 2016, 1:19:45 PM (4 years ago)
Author:
cito
Message:

Add methods for getting a table as a list or dict

Also added documentation and 100% test coverage.

The get_attnames() method now always returns a read-only ordered dictionary,
even under Python 2.6 or 3.0. So you can sure the columns will be returned
in the right order if you iterate over it, and that you don't accidentally
modify the dictionary (since it is cached).

Location:
trunk/docs/contents
Files:
2 edited

Legend:

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

    r765 r770  
    4343  DB wrapper methods has been reduced and security has been improved by
    4444  passing the values to libpq separately as parameters instead of inline.
     45- The classic interface got two new methods get_as_list() and get_as_dict()
     46  returning a database table as a Python list or dict. The amount of data
     47  returned can be controlled with various parameters.
    4548
    4649Version 4.2
  • trunk/docs/contents/pg/db_wrapper.rst

    r769 r770  
    120120
    121121    :param str table: name of table
    122     :returns: a dictionary mapping attribute names to type names
     122    :returns: an ordered dictionary mapping attribute names to type names
    123123
    124124Given the name of a table, digs out the set of attribute names.
    125125
    126 Returns a dictionary of attribute names (the names are the keys,
    127 the values are the names of the attributes' types).
    128 
    129 If your Python version supports this, the dictionary will be an
    130 OrderedDictionary with the column names in the right order.
     126Returns a read-only dictionary of attribute names (the names are the keys,
     127the values are the names of the attributes' types) with the column names
     128in the proper order if you iterate over it.
    131129
    132130By default, only a limited number of simple types will be returned.
     
    162160    :rtype: str, list or dict
    163161    :raises TypeError: Invalid parameter type(s)
    164     :raises ProgrammingError: Invalid parameter name(s)
     162    :raises pg.ProgrammingError: Invalid parameter name(s)
    165163
    166164If the parameter is a string, the return value will also be a string
     
    180178.. versionadded:: 4.2
    181179
    182 .. method:: DB.set_parameter(self, parameter, [value], [local])
     180.. method:: DB.set_parameter(parameter, [value], [local])
    183181
    184182    Set the value of run-time parameters
     
    190188    :raises TypeError: Invalid parameter type(s)
    191189    :raises ValueError: Invalid value argument(s)
    192     :raises ProgrammingError: Invalid parameter name(s) or values
     190    :raises pg.ProgrammingError: Invalid parameter name(s) or values
    193191
    194192If the parameter and the value are strings, the run-time parameter
     
    295293    :returns: A dictionary - the keys are the attribute names,
    296294      the values are the row values.
    297     :raises ProgrammingError: table has no primary key or missing privilege
     295    :raises pg.ProgrammingError: table has no primary key or missing privilege
    298296    :raises KeyError: missing key value for the row
    299297
     
    325323    :returns: the inserted values in the database
    326324    :rtype: dict
    327     :raises ProgrammingError: missing privilege or conflict
     325    :raises pg.ProgrammingError: missing privilege or conflict
    328326
    329327This method inserts a row into a table.  If the optional dictionary is
     
    347345    :returns: the new row in the database
    348346    :rtype: dict
    349     :raises ProgrammingError: table has no primary key or missing privilege
     347    :raises pg.ProgrammingError: table has no primary key or missing privilege
    350348    :raises KeyError: missing key value for the row
    351349
     
    374372    :returns: the new row in the database
    375373    :rtype: dict
    376     :raises ProgrammingError: table has no primary key or missing privilege
     374    :raises pg.ProgrammingError: table has no primary key or missing privilege
    377375
    378376This method inserts a row into a table, but instead of raising a
     
    480478    :param col: optional keyword arguments for updating the dictionary
    481479    :rtype: None
    482     :raises ProgrammingError: table has no primary key,
     480    :raises pg.ProgrammingError: table has no primary key,
    483481        row is still referenced or missing privilege
    484482    :raises KeyError: missing key value for the row
     
    494492by another table, this method will raise a ProgrammingError.
    495493
    496 truncate -- Quickly empty database tables
     494truncate -- quickly empty database tables
    497495-----------------------------------------
    498496
    499 .. method:: DB.truncate(self, table, [restart], [cascade], [only]):
     497.. method:: DB.truncate(table, [restart], [cascade], [only])
    500498
    501499    Empty a table or set of tables
     
    525523.. versionadded:: 4.2
    526524
     525get_as_list/dict -- read a table as a list or dictionary
     526--------------------------------------------------------
     527
     528.. method:: DB.get_as_list(table, [what], [where], [order], [limit], [offset], [scalar])
     529
     530    Get a table as a list
     531
     532    :param str table: the name of the table (the FROM clause)
     533    :param what: column(s) to be returned (the SELECT clause)
     534    :type what: str, list, tuple or None
     535    :param where: conditions(s) to be fulfilled (the WHERE clause)
     536    :type where: str, list, tuple or None
     537    :param order: column(s) to sort by (the ORDER BY clause)
     538    :type order: str, list, tuple, False or None
     539    :param int limit: maximum number of rows returned (the LIMIT clause)
     540    :param int offset: number of rows to be skipped (the OFFSET clause)
     541    :param bool scalar: whether only the first column shall be returned
     542    :returns: the content of the table as a list
     543    :rtype: list
     544    :raises TypeError: the table name has not been specified
     545
     546This gets a convenient representation of the table as a list of named tuples
     547in Python.  You only need to pass the name of the table (or any other SQL
     548expression returning rows).  Note that by default this will return the full
     549content of the table which can be huge and overflow your memory.  However, you
     550can control the amount of data returned using the other optional parameters.
     551
     552The parameter *what* can restrict the query to only return a subset of the
     553table columns.  The parameter *where* can restrict the query to only return a
     554subset of the table rows.  The specified SQL expressions all need to be
     555fulfilled for a row to get into the result.  The parameter *order* specifies
     556the ordering of the rows.  If no ordering is specified, the result will be
     557ordered by the primary key(s) or all columns if no primary key exists.
     558You can set *order* to *False* if you don't care about the ordering.
     559The parameters *limit* and *offset* specify the maximum number of rows
     560returned and a number of rows skipped over.
     561
     562If you set the *scalar* option to *True*, then instead of the named tuples
     563you will get the first items of these tuples.  This is useful if the result
     564has only one column anyway.
     565
     566.. method:: DB.get_as_dict(table, [keyname], [what], [where], [order], [limit], [offset], [scalar])
     567
     568    Get a table as a dictionary
     569
     570    :param str table: the name of the table (the FROM clause)
     571    :param keyname: column(s) to be used as key(s) of the dictionary
     572    :type keyname: str, list, tuple or None
     573    :param what: column(s) to be returned (the SELECT clause)
     574    :type what: str, list, tuple or None
     575    :param where: conditions(s) to be fulfilled (the WHERE clause)
     576    :type where: str, list, tuple or None
     577    :param order: column(s) to sort by (the ORDER BY clause)
     578    :type order: str, list, tuple, False or None
     579    :param int limit: maximum number of rows returned (the LIMIT clause)
     580    :param int offset: number of rows to be skipped (the OFFSET clause)
     581    :param bool scalar: whether only the first column shall be returned
     582    :returns: the content of the table as a list
     583    :rtype: dict or OrderedDict
     584    :raises TypeError: the table name has not been specified
     585    :raises KeyError: keyname(s) are invalid or not part of the result
     586    :raises pg.ProgrammingError: no keyname(s) and table has no primary key
     587
     588This method is similar to :meth:`DB.get_as_list`, but returns the table as
     589a Python dict instead of a Python list, which can be even more convenient.
     590The primary key column(s) of the table will be used as the keys of the
     591dictionary, while the other column(s) will be the corresponding values.
     592The keys will be named tuples if the table has a composite primary key.
     593The rows will be also named tuples unless the *scalar* option has been set
     594to *True*.  With the optional parameter *keyname* you can specify a different
     595set of columns to be used as the keys of the dictionary.
     596
     597If the Python version supports it, the dictionary will be an *OrderedDict*
     598using the order specified with the *order* parameter or the key column(s)
     599if not specified.  You can set *order* to *False* if you don't care about the
     600ordering.  In this case the returned dictionary will be an ordinary one.
     601
    527602escape_literal -- escape a literal string for use within SQL
    528603------------------------------------------------------------
Note: See TracChangeset for help on using the changeset viewer.