Changeset 738 for trunk/docs


Ignore:
Timestamp:
Jan 13, 2016, 5:57:29 PM (4 years ago)
Author:
cito
Message:

Renamed some parameters to clarify their meaning

This is uncritical, because these are not keyword parameters. Also, we don't
change much in the 4.x branch in order to stay compatible.

Also, avoided the old terminology "class" for a table or table-like object in PostgreSQL,
because it may confuse people. The word "table" is so much clearer.

File:
1 edited

Legend:

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

    r735 r738  
    209209----------------------------------------------
    210210
    211 .. method:: DB.get(table, arg, [keyname])
     211.. method:: DB.get(table, row, [keyname])
    212212
    213213    Get a row from a database table or view
    214214
    215     :param str table:  name of table or view
    216     :param arg: either a dictionary or the value to be looked up
     215    :param str table: name of table or view
     216    :param row: either a dictionary or the value to be looked up
    217217    :param str keyname: name of field to use as key (optional)
    218218    :returns: A dictionary - the keys are the attribute names,
     
    222222This method is the basic mechanism to get a single row. It assumes
    223223that the key specifies a unique row. If *keyname* is not specified,
    224 then the primary key for the table is used. If *arg* is a dictionary
     224then the primary key for the table is used. If *row* is a dictionary
    225225then the value for the key is taken from it and it is modified to
    226226include the new values, replacing existing values where necessary.
     
    233233--------------------------------------------
    234234
    235 .. method:: DB.insert(table, [d], [col=val, ...])
     235.. method:: DB.insert(table, [row], [col=val, ...])
    236236
    237237    Insert a row into a database table
    238238
    239239    :param str table: name of table
    240     :param dict d: optional dictionary of values
     240    :param dict row: optional dictionary of values
     241    :param col: optional keyword arguments for updating the dictionary
    241242    :returns: the inserted values in the database
    242243    :rtype: dict
     
    257258------------------------------------------
    258259
    259 .. method:: DB.update(table, [d], [col=val, ...])
     260.. method:: DB.update(table, [row], [col=val, ...])
    260261
    261262    Update a row in a database table
    262263
    263264    :param str table: name of table
    264     :param dict d: optional dictionary of values
     265    :param dict row: optional dictionary of values
     266    :param col: optional keyword arguments for updating the dictionary
    265267    :returns: the new row in the database
    266268    :rtype: dict
     
    280282-----------------------------------------------
    281283
    282 .. method:: DB.upsert(table, [d], [col=val, ...])
     284.. method:: DB.upsert(table, [row], [col=val, ...])
    283285
    284286    Insert a row into a database table with conflict resolution
    285287
    286288    :param str table: name of table
    287     :param dict d: optional dictionary of values
     289    :param dict row: optional dictionary of values
     290    :param col: optional keyword arguments for specifying the update
    288291    :returns: the new row in the database
    289292    :rtype: dict
     
    310313
    311314So if in the case of a conflict you want to update every column that has been
    312 passed in the dictionary `d` , you would call ``upsert(cl, d)``. If you don't
    313 want to do anything in case of a conflict, i.e. leave the existing row as it
    314 is, call ``upsert(cl, d, **dict.fromkeys(d))``.
     315passed in the dictionary `d` , you would call ``upsert(table, d)``.  If you
     316don't want to do anything in case of a conflict, i.e. leave the existing row
     317as it is, call ``upsert(table, d, **dict.fromkeys(d))``.
    315318
    316319If you need more fine-grained control of what gets updated, you can also pass
     
    366369-----------------------------------
    367370
    368 .. method:: DB.clear(table, [a])
     371.. method:: DB.clear(table, [row])
    369372
    370373    Clear row values in memory
    371374
    372375    :param str table: name of table
    373     :param dict a: optional dictionary of values
     376    :param dict row: optional dictionary of values
    374377    :returns: an empty row
    375378    :rtype: dict
    376379
    377380This method clears all the attributes to values determined by the types.
    378 Numeric types are set to 0, Booleans are set to ``'f'``, dates are set
    379 to ``'now()'`` and everything else is set to the empty string.
    380 If the array argument is present, it is used as the array and any entries
    381 matching attribute names are cleared with everything else left unchanged.
     381Numeric types are set to 0, Booleans are set to ``'f'``, and everything
     382else is set to the empty string.  If the row argument is present, it is
     383used as the row dictionary and any entries matching attribute names are
     384cleared with everything else left unchanged.
    382385
    383386If the dictionary is not supplied a new one is created.
     
    386389--------------------------------------------
    387390
    388 .. method:: DB.delete(table, [d,] [key = val, ...])
     391.. method:: DB.delete(table, [row], [col=val, ...])
    389392
    390393    Delete a row from a database table
     
    392395    :param str table: name of table
    393396    :param dict d: optional dictionary of values
     397    :param col: optional keyword arguments for updating the dictionary
    394398    :rtype: None
    395399
Note: See TracChangeset for help on using the changeset viewer.