Changeset 765 for trunk/docs


Ignore:
Timestamp:
Jan 18, 2016, 6:21:44 PM (4 years ago)
Author:
cito
Message:

Improve support for access by primary key

Composite primary keys are now returned as tuples instead of frozensets,
where the ordering of the tuple reflects the primary key index.

Primary keys now takes precedence if both OID and primary key are available
(this was solved the other way around in 4.x). Use of OIDs is thus slightly
more discouraged, though it still works as before for tables with OIDs where
no primary key is available.

This changeset also clarifies some docstrings, makes the code a bit clearer,
handles and tests some more edge cases (pg module still has 100% coverage).

Location:
trunk/docs/contents
Files:
2 edited

Legend:

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

    r762 r765  
    2828- The tty parameter and attribute of database connections has been
    2929  removed since it is not supported any more since PostgreSQL 7.4.
     30- The pkey() method of the classic interface now returns tuples instead
     31  of frozenset. The order of the tuples is like in the primary key index.
    3032- The table name that is affixed to the name of the OID column returned
    3133  by the get() method of the classic interface will not automatically
     
    3335  but it means you must always write the table name in the same way when
    3436  you call the methods using it and you are using tables with OIDs.
     37  Also, OIDs are now only used when access via primary key is not possible.
    3538  Note that OIDs are considered deprecated anyway, and they are not created
    3639  by default any more in PostgreSQL 8.1 and later.
  • trunk/docs/contents/pg/db_wrapper.rst

    r763 r765  
    6666    :raises KeyError: the table does not have a primary key
    6767
    68 This method returns the primary key of a table. For composite primary
    69 keys, the return value will be a frozenset. Note that this raises a
    70 KeyError if the table does not have a primary key.
     68This method returns the primary key of a table.  Single primary keys are
     69returned as strings unless you set the composite flag.  Composite primary
     70keys are always represented as tuples.  Note that this raises a KeyError
     71if the table does not have a primary key.
    7172
    7273get_databases -- get list of databases in the system
     
    296297    :returns: A dictionary - the keys are the attribute names,
    297298      the values are the row values.
    298     :raises ProgrammingError: no primary key or missing privilege
    299 
    300 This method is the basic mechanism to get a single row. It assumes
    301 that the key specifies a unique row. If *keyname* is not specified,
    302 then the primary key for the table is used. If *row* is a dictionary
    303 then the value for the key is taken from it and it is modified to
    304 include the new values, replacing existing values where necessary.
    305 For a composite key, *keyname* can also be a sequence of key names.
    306 The OID is also put into the dictionary if the table has one, but in
    307 order to allow the caller to work with multiple tables, it is munged
    308 as ``oid(table)``.
     299    :raises ProgrammingError: table has no primary key or missing privilege
     300    :raises KeyError: missing key value for the row
     301
     302This method is the basic mechanism to get a single row.  It assumes
     303that the *keyname* specifies a unique row.  It must be the name of a
     304single column or a tuple of column names.  If *keyname* is not specified,
     305then the primary key for the table is used.
     306
     307If *row* is a dictionary, then the value for the key is taken from it.
     308Otherwise, the row must be a single value or a tuple of values
     309corresponding to the passed *keyname* or primary key.  The fetched row
     310from the table will be returned as a new dictionary or used to replace
     311the existing values when row was passed as aa dictionary.
     312
     313The OID is also put into the dictionary if the table has one, but
     314in order to allow the caller to work with multiple tables, it is
     315munged as ``oid(table)`` using the actual name of the table.
    309316
    310317insert -- insert a row into a database table
     
    345352    :returns: the new row in the database
    346353    :rtype: dict
    347     :raises ProgrammingError: no primary key or missing privilege
    348 
    349 Similar to insert but updates an existing row.  The update is based on the
    350 OID value as munged by get or passed as keyword, or on the primary key of
    351 the table.  The dictionary is modified to reflect any changes caused by the
     354    :raises ProgrammingError: table has no primary key or missing privilege
     355    :raises KeyError: missing key value for the row
     356
     357Similar to insert but updates an existing row.  The update is based on
     358the primary key of the table or the OID value as munged by :meth:`DB.get`
     359or passed as keyword.
     360
     361The dictionary is then modified to reflect any changes caused by the
    352362update due to triggers, rules, default values, etc.
    353363
     
    355365on the fields in the keywords.  There must be an OID or primary key
    356366either in the dictionary where the OID must be munged, or in the keywords
    357 where it can be simply the string 'oid'.
     367where it can be simply the string ``'oid'``.
    358368
    359369upsert -- insert a row with conflict resolution
     
    369379    :returns: the new row in the database
    370380    :rtype: dict
    371     :raises ProgrammingError: no primary key or missing privilege
     381    :raises ProgrammingError: table has no primary key or missing privilege
    372382
    373383This method inserts a row into a table, but instead of raising a
     
    475485    :param col: optional keyword arguments for updating the dictionary
    476486    :rtype: None
    477 
    478 This method deletes the row from a table.  It deletes based on the OID value
    479 as munged by get or passed as keyword, or on the primary key of the table.
     487    :raises ProgrammingError: table has no primary key,
     488        row is still referenced or missing privilege
     489    :raises KeyError: missing key value for the row
     490
     491This method deletes the row from a table.  It deletes based on the
     492primary key of the table or the OID value as munged by :meth:`DB.get`
     493or passed as keyword.
     494
    480495The return value is the number of deleted rows (i.e. 0 if the row did not
    481496exist and 1 if the row was deleted).
     497
     498Note that if the row cannot be deleted because e.g. it is still referenced
     499by another table, this method will raise a ProgrammingError.
    482500
    483501truncate -- Quickly empty database tables
Note: See TracChangeset for help on using the changeset viewer.