Changeset 967 for trunk


Ignore:
Timestamp:
Jan 5, 2019, 4:11:05 PM (9 months ago)
Author:
cito
Message:

Some more improvements to the docs by Justin Pryzby

Location:
trunk/docs/contents/pg
Files:
2 edited

Legend:

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

    r962 r967  
    135135
    136136By default, only a limited number of simple types will be returned.
    137 You can get the regular types instead, if you enable this by calling the
     137You can get the regular types instead, if enabled by calling the
    138138:meth:`DB.use_regtypes` method.
    139139
     
    246246    Commit a transaction
    247247
    248     This commits the current transaction. All changes made by the
    249     transaction become visible to others and are guaranteed to be
    250     durable if a crash occurs.
     248    This commits the current transaction.
     249
     250All changes made by the transaction become visible to others.
     251=> Don't say this, since it's not true eg. in repeatable_read xtn
     252After returning, the changes are guaranteed to be durable, even if a crash occurs.
     253=> Don't say this since it's postgres job to document DB behavior,
     254kernel and library folks job to do their part, and DBA+sysadmin job to
     255implement it on site, not pygres or the developer's job
     256(with my developer's hat off and sysadmin hat on).
    251257
    252258.. method:: DB.end()
     
    262268    :param str name: optionally, roll back to the specified savepoint
    263269
    264     This rolls back the current transaction and causes all the updates
    265     made by the transaction to be discarded.
     270    This rolls back the current transaction, discarding all its changes.
    266271
    267272.. method:: DB.abort()
     
    526531
    527532This methods works like the :meth:`DB.query` method, except that instead of
    528 passing the SQL command, you pass the name of an prepared statement that you
    529 have created previously using the :meth:`DB.prepare` method.
     533passing the SQL command, you pass the name of a prepared statement
     534created previously using the :meth:`DB.prepare` method.
    530535
    531536Passing an empty string or *None* as the name will execute the unnamed
    532537statement (see warning about the limited lifetime of the unnamed statement
    533538in :meth:`DB.prepare`).
     539
     540The functionality of this method is equivalent to that of the SQL ``EXECUTE``
     541command.  Note that calling EXECUTE would require parameters to be sent
     542inline, and be properly sanitized (escaped, quoted).
    534543
    535544.. versionadded:: 5.1
     
    549558    :raises pg.ProgrammingError: error in query or duplicate query
    550559
    551 This method creates a prepared statement with the given name for the given
    552 command for later execution with the :meth:`DB.query_prepared` method.
    553 The name can be empty to create an unnamed statement, in which case any
    554 pre-existing unnamed statement is automatically replaced; otherwise a
    555 :exc:`pg.ProgrammingError` is raised if the statement name is already
    556 defined in the current database session.
     560This method creates a prepared statement with the specified name for later
     561execution of the given command with the :meth:`DB.query_prepared` method.
     562
     563If the name is empty or *None*, the unnamed prepared statement is used,
     564in which case any pre-existing unnamed statement is replaced.
     565
     566Otherwise, if a prepared statement with the specified name is already defined
     567in the current database session, a :exc:`pg.ProgrammingError` is raised.
    557568
    558569The SQL command may optionally contain positional parameters of the form
    559570``$1``, ``$2``, etc instead of literal data.  The corresponding values
    560 must then later be passed to the :meth:`Connection.query_prepared` method
     571must then be passed to the :meth:`Connection.query_prepared` method
    561572as positional arguments.
    562573
     574The functionality of this method is equivalent to that of the SQL ``PREPARE``
     575command.
     576
    563577Example::
    564578
    565579    db.prepare('change phone',
    566         "update employees set phone=$2 where ein=$1",
     580        "update employees set phone=$2 where ein=$1")
    567581    while True:
    568582        ein = input("Employee ID? ")
     
    616630This method deallocates a previously prepared SQL statement with the given
    617631name, or deallocates all prepared statements if you do not specify a name.
    618 Note that prepared statements are also deallocated automatically when the
     632Note that prepared statements are always deallocated automatically when the
    619633current session ends.
    620634
  • trunk/docs/contents/pg/query.rst

    r962 r967  
    130130    :raises TypeError: Too many arguments.
    131131
    132 This method returns the number of tuples found in a query.
     132This method returns the number of tuples in the query result.
Note: See TracChangeset for help on using the changeset viewer.