On Fri, Jan 04, 2019 at 11:44:47PM +0100, Christoph Zwerschke wrote:
> I kept the term "C extension" for the shared library since it has a
> well-known meaning in the Python world, but made it clearer that it's
> low-level (I guess that was your reasoning to not use the term).
Right, my thinking was that "extension" makes it sounds like an optional thing
rather than the foundation of the entire project.
There's a few remaining chunks which I think are improvements. Please review
and apply your best judgement and standards :)
(And by "apply" I mean review and conditionally discard).
Justin
Index: docs/contents/pg/db_wrapper.rst
===================================================================
--- docs/contents/pg/db_wrapper.rst (revision 962)
+++ docs/contents/pg/db_wrapper.rst (working copy)
@@ -134,7 +134,7 @@
in the proper order if you iterate over it.
By default, only a limited number of simple types will be returned.
-You can get the regular types instead, if you enable this by calling the
+You can get the regular types instead, if enabled by calling the
:meth:`DB.use_regtypes` method.
has_table_privilege -- check table privilege
@@ -245,10 +245,16 @@
Commit a transaction
- This commits the current transaction. All changes made by the
- transaction become visible to others and are guaranteed to be
- durable if a crash occurs.
+ This commits the current transaction.
+All changes made by the transaction become visible to others.
+=> Don't say this, since it's not true eg. in repeatable_read xtn
+After returning, the changes are guaranteed to be durable, even if a crash occurs.
+=> Don't say this since it's postgres job to document DB behavior,
+kernel and library folks job to do their part, and DBA+sysadmin job to
+implement it on site, not pygres or the developer's job
+(with my developer's hat off and sysadmin hat on).
+
.. method:: DB.end()
This is the same as the :meth:`DB.commit` method.
@@ -261,8 +267,8 @@
:param str name: optionally, roll back to the specified savepoint
- This rolls back the current transaction and causes all the updates
- made by the transaction to be discarded.
+ Rolling back the current transaction causes all its changes to be
+ discarded.
.. method:: DB.abort()
@@ -525,13 +531,20 @@
:raises pg.OperationalError: prepared statement does not exist
This methods works like the :meth:`DB.query` method, except that instead of
-passing the SQL command, you pass the name of an prepared statement that you
-have created previously using the :meth:`DB.prepare` method.
+passing the SQL command, you pass the name of a prepared statement
+created previously using the :meth:`DB.prepare` method.
+# XXX: or SQL PREPARE AS
-Passing an empty string or *None* as the name will execute the unnamed
-statement (see warning about the limited lifetime of the unnamed statement
-in :meth:`DB.prepare`).
+-Passing an empty string or *None* as the name will execute the unnamed
+-statement (see warning about the limited lifetime of the unnamed statement
+-in :meth:`DB.prepare`).
++passing the SQL command, you pass the name of a prepared statement. If
++name is the empty string, the unnamed statement will be executed
+This functionality of this method is equivalent to that of the SQL ``EXECUTE``
+command. Note that calling EXECUTE would requires parameters to be sent
+inline, and be properly sanitized/escaped/quoted.
+
.. versionadded:: 5.1
prepare -- create a prepared statement
@@ -548,16 +561,21 @@
:raises TypeError: invalid connection
:raises pg.ProgrammingError: error in query or duplicate query
-This method creates a prepared statement with the given name for the given
-command for later execution with the :meth:`DB.query_prepared` method.
-The name can be empty to create an unnamed statement, in which case any
-pre-existing unnamed statement is automatically replaced; otherwise a
-:exc:`pg.ProgrammingError` is raised if the statement name is already
-defined in the current database session.
+This method creates a prepared statement ``name`` for later execution of the
+given command with the :meth:`DB.query_prepared` method.
+If a prepared statement with the specified name is already defined in the
+current database session, :exc:`pg.ProgrammingError` is raised.
+
+If name is empty, the unnamed prepared statement is used, in which case any
+pre-existing unnamed statement is replaced.
+
+This functionality of this method is equivalent to that of the SQL ``PREPARE``
+command.
+
The SQL command may optionally contain positional parameters of the form
``$1``, ``$2``, etc instead of literal data. The corresponding values
-must then later be passed to the :meth:`Connection.query_prepared` method
+must then be passed to the :meth:`Connection.query_prepared` method
as positional arguments.
Example::
@@ -577,6 +595,13 @@
limited lifetime and can be automatically replaced or destroyed by
various operations on the database.
+ We recommend avoiding use of the unnamed prepared statement, because it
+ is silently replaced when other query methods are used, causing future
+ attempts to execute the prepared statement to fail or misbehave.
+ In particular, the DB wrapper class issues queries behind the scenes
+ (for instance to find unknown database types) which can cause the users'
+ unnamed prepared statement to be replaced with an internal query.
+
.. versionadded:: 5.1
describe_prepared -- describe a prepared statement
@@ -615,7 +640,7 @@
This method deallocates a previously prepared SQL statement with the given
name, or deallocates all prepared statements if you do not specify a name.
-Note that prepared statements are also deallocated automatically when the
+Note that prepared statements are deallocated automatically when the
current session ends.
.. versionadded:: 5.1
Index: docs/contents/pg/query.rst
===================================================================
--- docs/contents/pg/query.rst (revision 962)
+++ docs/contents/pg/query.rst (working copy)
@@ -129,4 +129,4 @@
:rtype: int
:raises TypeError: Too many arguments.
-This method returns the number of tuples found in a query.
+This method returns the number of tuples in the query result.
_______________________________________________
PyGreSQL mailing list
PyGreSQL@Vex.Net
https://mail.vex.net/mailman/listinfo/pygresql
