Diff
Modified: branches/5.0.x/docs/contents/pg/adaptation.rst (961 => 962)
--- branches/5.0.x/docs/contents/pg/adaptation.rst 2019-01-04 19:43:23 UTC (rev 961)
+++ branches/5.0.x/docs/contents/pg/adaptation.rst 2019-01-04 22:32:04 UTC (rev 962)
@@ -64,7 +64,7 @@
the scenes. You only need to consider this issue when creating SQL commands
manually and sending them to the database using the :meth:`DB.query` method.
-Imagine you have created a user login form that stores the login name as
+Imagine you have created a user login form that stores the login name as
*login* and the password as *passwd* and you now want to get the user
data for that user. You may be tempted to execute a query like this::
Modified: branches/5.0.x/docs/contents/pg/connection.rst (961 => 962)
--- branches/5.0.x/docs/contents/pg/connection.rst 2019-01-04 19:43:23 UTC (rev 961)
+++ branches/5.0.x/docs/contents/pg/connection.rst 2019-01-04 22:32:04 UTC (rev 962)
@@ -241,7 +241,7 @@
.. warning::
This method doesn't type check the fields according to the table definition;
- it just look whether or not it knows how to handle such types.
+ it just looks whether or not it knows how to handle such types.
get/set_notice_receiver -- custom notice receiver
-------------------------------------------------
Modified: branches/5.0.x/docs/contents/pg/db_wrapper.rst (961 => 962)
--- branches/5.0.x/docs/contents/pg/db_wrapper.rst 2019-01-04 19:43:23 UTC (rev 961)
+++ branches/5.0.x/docs/contents/pg/db_wrapper.rst 2019-01-04 22:32:04 UTC (rev 962)
@@ -314,7 +314,7 @@
Otherwise, the row must be a single value or a tuple of values
corresponding to the passed *keyname* or primary key. The fetched row
from the table will be returned as a new dictionary or used to replace
-the existing values when row was passed as aa dictionary.
+the existing values when row was passed as a dictionary.
The OID is also put into the dictionary if the table has one, but
in order to allow the caller to work with multiple tables, it is
@@ -775,7 +775,7 @@
to be decoded, then you can cast ``json`` or ``jsonb`` columns to ``text``
in PostgreSQL or you can set the decoding function to *None* or a different
function using :func:`pg.set_jsondecode`. By default this is the same as
-the :func:`json.dumps` function from the standard library.
+the :func:`json.loads` function from the standard library.
.. versionadded:: 5.0
Modified: branches/5.0.x/docs/contents/pg/query.rst (961 => 962)
--- branches/5.0.x/docs/contents/pg/query.rst 2019-01-04 19:43:23 UTC (rev 961)
+++ branches/5.0.x/docs/contents/pg/query.rst 2019-01-04 22:32:04 UTC (rev 962)
@@ -42,7 +42,7 @@
:raises MemoryError: internal memory error
This method returns the list of the values returned by the query
-with each tuple returned as a dictionary with the field names
+with each row returned as a dictionary with the field names
used as the dictionary index.
Note that since PyGreSQL 5.0 this will return the values of array type
Modified: branches/5.0.x/docs/contents/postgres/advanced.rst (961 => 962)
--- branches/5.0.x/docs/contents/postgres/advanced.rst 2019-01-04 19:43:23 UTC (rev 961)
+++ branches/5.0.x/docs/contents/postgres/advanced.rst 2019-01-04 22:32:04 UTC (rev 962)
@@ -11,7 +11,7 @@
>>> from pg import DB
>>> db = DB()
- >>> query = query
+ >>> query = db.query
Inheritance
-----------
Modified: branches/5.0.x/docs/contents/postgres/func.rst (961 => 962)
--- branches/5.0.x/docs/contents/postgres/func.rst 2019-01-04 19:43:23 UTC (rev 961)
+++ branches/5.0.x/docs/contents/postgres/func.rst 2019-01-04 22:32:04 UTC (rev 962)
@@ -22,7 +22,7 @@
>>> query("""CREATE FUNCTION one() RETURNS int4
... AS 'SELECT 1 as ONE' LANGUAGE SQL""")
-Functions can be used in any expressions (eg. in the target"list or
+Functions can be used in any expressions (eg. in the target list or
qualifications)::
>>> print(db.query("SELECT one() AS answer"))
Modified: branches/5.0.x/docs/contents/postgres/syscat.rst (961 => 962)
--- branches/5.0.x/docs/contents/postgres/syscat.rst 2019-01-04 19:43:23 UTC (rev 961)
+++ branches/5.0.x/docs/contents/postgres/syscat.rst 2019-01-04 22:32:04 UTC (rev 962)
@@ -19,8 +19,9 @@
>>> from pg import DB
>>> db = DB()
- >>> query = query
+ >>> query = db.query
+
Lists indices
-------------
@@ -49,6 +50,7 @@
AND NOT a.attisdropped
ORDER BY relname, attname"""))
+
List user defined base types
----------------------------
@@ -62,8 +64,8 @@
ORDER BY rolname, typname"""))
-List operators
----------------
+List operators
+--------------
This query lists all right-unary operators::
@@ -121,6 +123,7 @@
and p.proargtypes[0] = t.oid
ORDER BY proname, typname"""))
+
List operator families
----------------------
Modified: trunk/docs/contents/general.rst (961 => 962)
--- trunk/docs/contents/general.rst 2019-01-04 19:43:23 UTC (rev 961)
+++ trunk/docs/contents/general.rst 2019-01-04 22:32:04 UTC (rev 962)
@@ -19,9 +19,8 @@
from Python that has been developed by the Python DB-SIG in 1999.
The authoritative programming information for the DB-API is :pep:`0249`.
-Both Python modules utilize the same lower level C extension module that
-serves as a wrapper for the C API to PostgreSQL that is available in form
-of the so-called "libpq" library.
+Both Python modules utilize the same low-level C extension, which
+serves as a wrapper for the "libpq" library, the C API to PostgreSQL.
This means you must have the libpq library installed as a shared library
on your client computer, in a version that is supported by PyGreSQL.
Modified: trunk/docs/contents/install.rst (961 => 962)
--- trunk/docs/contents/install.rst 2019-01-04 19:43:23 UTC (rev 961)
+++ trunk/docs/contents/install.rst 2019-01-04 22:32:04 UTC (rev 962)
@@ -4,32 +4,33 @@
General
-------
-You must first have installed Python and PostgreSQL on your system.
-If you want to access remote database only, you don't need to install
-the full PostgreSQL server, but only the C interface (libpq). If you
-are on Windows, make sure that the directory with libpq.dll is in your
-``PATH`` environment variable.
+You must first install Python and PostgreSQL on your system.
+If you want to access remote databases only, you don't need to install
+the full PostgreSQL server, but only the libpq C-interface library.
+If you are on Windows, make sure that the directory that contains
+libpq.dll is part of your ``PATH`` environment variable.
The current version of PyGreSQL has been tested with Python versions
2.6, 2.7 and 3.3 to 3.7, and PostgreSQL versions 9.0 to 9.6 and 10 or 11.
-PyGreSQL will be installed as three modules, a dynamic module called
-_pg.pyd, and two pure Python wrapper modules called pg.py and pgdb.py.
+PyGreSQL will be installed as three modules, a shared library called
+_pg.so (on Linux) or a DLL called _pg.pyd (on Windows), and two pure
+Python wrapper modules called pg.py and pgdb.py.
All three files will be installed directly into the Python site-packages
-directory. To uninstall PyGreSQL, simply remove these three files again.
+directory. To uninstall PyGreSQL, simply remove these three files.
Installing with Pip
-------------------
-This is the most easy way to install PyGreSQL if you have "pip" installed
-on your computer. Just run the following command in your terminal::
+This is the most easy way to install PyGreSQL if you have "pip" installed.
+Just run the following command in your terminal::
pip install PyGreSQL
This will automatically try to find and download a distribution on the
`Python Package Index <https://pypi.python.org/>`_ that matches your operating
-system and Python version and install it on your computer.
+system and Python version and install it.
Installing from a Binary Distribution
@@ -40,7 +41,7 @@
and install a distribution.
When you download the source distribution, you will need to compile the
-C extensions, for which you need a C compiler installed on your computer.
+C extension, for which you need a C compiler installed.
If you don't want to install a C compiler or avoid possible problems
with the compilation, you can search for a pre-compiled binary distribution
of PyGreSQL on the Python Package Index or the PyGreSQL homepage.
@@ -86,7 +87,7 @@
Compiling Manually
~~~~~~~~~~~~~~~~~~
-The source file for compiling the dynamic module is called pgmodule.c.
+The source file for compiling the C extension module is pgmodule.c.
You have two options. You can compile PyGreSQL as a stand-alone module
or you can build it into the Python interpreter.
Modified: trunk/docs/contents/pg/adaptation.rst (961 => 962)
--- trunk/docs/contents/pg/adaptation.rst 2019-01-04 19:43:23 UTC (rev 961)
+++ trunk/docs/contents/pg/adaptation.rst 2019-01-04 22:32:04 UTC (rev 962)
@@ -61,28 +61,28 @@
When you use the higher level methods of the classic :mod:`pg` module like
:meth:`DB.insert()` or :meth:`DB.update()`, you don't need to care about
adaptation of parameters, since all of this is happening automatically behind
-the scenes. You only need to consider this issue when creating SQL commands
-manually and sending them to the database using the :meth:`DB.query` method.
-
-Imagine you have created a user login form that stores the login name as
-*login* and the password as *passwd* and you now want to get the user
-data for that user. You may be tempted to execute a query like this::
-
+the scenes. You only need to consider this issue when creating SQL commands
+manually and sending them to the database using the :meth:`DB.query` method.
+
+Imagine you have created a user login form that stores the login name as
+*login* and the password as *passwd* and you now want to get the user
+data for that user. You may be tempted to execute a query like this::
+
>>> db = pg.DB(...)
>>> sql = "SELECT * FROM user_table WHERE login = '%s' AND passwd = '%s'"
>>> db.query(sql % (login, passwd)).getresult()[0]
-
-This seems to work at a first glance, but you will notice an error as soon as
-you try to use a login name containing a single quote. Even worse, this error
-can be exploited through a so called "SQL injection", where an attacker inserts
-malicious SQL statements into the query that you never intended to be executed.
-For instance, with a login name something like ``' OR ''='`` the user could
-easily log in and see the user data of another user in the database.
-
-One solution for this problem would be to clean your input from "dangerous"
-characters like the single quote, but this is tedious and it is likely that
-you overlook something or break the application e.g. for users with names
-like "D'Arcy". A better solution is to use the escaping functions provided
+
+This seems to work at a first glance, but you will notice an error as soon as
+you try to use a login name containing a single quote. Even worse, this error
+can be exploited through so-called "SQL injection", where an attacker inserts
+malicious SQL statements into the query that you never intended to be executed.
+For instance, with a login name something like ``' OR ''='`` the attacker could
+easily log in and see the user data of another user in the database.
+
+One solution for this problem would be to cleanse your input of "dangerous"
+characters like the single quote, but this is tedious and it is likely that
+you overlook something or break the application e.g. for users with names
+like "D'Arcy". A better solution is to use the escaping functions provided
by PostgreSQL which are available as methods on the :class:`DB` object::
>>> login = "D'Arcy"
@@ -161,13 +161,13 @@
>>> db.query_formatted(sql, (login,), inline=False).getresult()[0]
In real world examples you will rarely have to cast your parameters like that,
-since in an INSERT statement or a WHERE clause comparing the parameter to a
-table column the data type will be clear from the context.
-
-When binding the parameters to a query, PyGreSQL does not only adapt the basic
-types like ``int``, ``float``, ``bool`` and ``str``, but also tries to make
-sense of Python lists and tuples.
-
+since in an INSERT statement or a WHERE clause comparing the parameter to a
+table column the data type will be clear from the context.
+
+When binding the parameters to a query, PyGreSQL not only adapts the basic
+types like ``int``, ``float``, ``bool`` and ``str``, but also tries to make
+sense of Python lists and tuples.
+
Lists are adapted as PostgreSQL arrays::
>>> params = dict(array=[[1, 2],[3, 4]])
@@ -219,14 +219,14 @@
>>> row = dict(item=inventory_item('fuzzy dice', 42, 1.99), count=1000)
>>> db.insert('on_hand', row)
- {'count': 1000, 'item': inventory_item(name='fuzzy dice',
- supplier_id=42, price=Decimal('1.99'))}
-
-However, we may not want to use named tuples, but custom Python classes
-to hold our values, like this one::
-
- >>> class InventoryItem:
- ...
+ {'count': 1000, 'item': inventory_item(name='fuzzy dice',
+ supplier_id=42, price=Decimal('1.99'))}
+
+Perhaps we want to use custom Python classes instead of named tuples to hold
+our values::
+
+ >>> class InventoryItem:
+ ...
... def __init__(self, name, supplier_id, price):
... self.name = name
... self.supplier_id = supplier_id
Modified: trunk/docs/contents/pg/connection.rst (961 => 962)
--- trunk/docs/contents/pg/connection.rst 2019-01-04 19:43:23 UTC (rev 961)
+++ trunk/docs/contents/pg/connection.rst 2019-01-04 22:32:04 UTC (rev 962)
@@ -43,13 +43,14 @@
:raises pg.InternalError: error during query processing
This method simply sends a SQL query to the database. If the query is an
-insert statement that inserted exactly one row into a table that has OIDs, the
-return value is the OID of the newly inserted row. If the query is an update
-or delete statement, or an insert statement that did not insert exactly one
-row in a table with OIDs, then the number of rows affected is returned as a
-string. If it is a statement that returns rows as a result (usually a select
-statement, but maybe also an ``"insert/update ... returning"`` statement),
-this method returns a :class:`Query` that can be accessed via the
+insert statement that inserted exactly one row into a table that has OIDs,
+the return value is the OID of the newly inserted row as an integer.
+If the query is an update or delete statement, or an insert statement that
+did not insert exactly one row, or on a table without OIDs, then the number
+of rows affected is returned as a string. If it is a statement that returns
+rows as a result (usually a select statement, but maybe also an
+``"insert/update ... returning"`` statement), this method returns
+a :class:`Query` that can be accessed via the
:meth:`Query.getresult`, :meth:`Query.dictresult` or
:meth:`Query.namedresult` methods or simply printed.
Otherwise, it returns ``None``.
@@ -56,7 +57,7 @@
The SQL command may optionally contain positional parameters of the form
``$1``, ``$2``, etc instead of literal data, in which case the values
-have to be supplied separately as a tuple. The values are substituted by
+must be supplied separately as a tuple. The values are substituted by
the database in such a way that they don't need to be escaped, making this
an effective way to pass arbitrary or unknown data without worrying about
SQL injection or syntax errors.
@@ -91,9 +92,9 @@
This method works exactly like :meth:`Connection.query` except that instead
of passing the command itself, you pass the name of a prepared statement.
-An empty name corresponds to the unnamed statement. You must have created
-the corresponding named or unnamed statement with :meth:`Connection.prepare`
-before, or an :exc:`pg.OperationalError` will be raised.
+An empty name corresponds to the unnamed statement. You must have previously
+created the corresponding named or unnamed statement with
+:meth:`Connection.prepare`, or an :exc:`pg.OperationalError` will be raised.
.. versionadded:: 5.1
@@ -111,8 +112,8 @@
:raises TypeError: invalid connection
:raises pg.ProgrammingError: error in query or duplicate query
-This method creates a prepared statement for the given command with the
-given name for later execution with the :meth:`Connection.query_prepared`
+This method creates a prepared statement with the specified name for the
+given command for later execution with the :meth:`Connection.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
@@ -317,7 +318,7 @@
.. warning::
This method doesn't type check the fields according to the table definition;
- it just look whether or not it knows how to handle such types.
+ it just looks whether or not it knows how to handle such types.
get/set_notice_receiver -- custom notice receiver
-------------------------------------------------
@@ -451,8 +452,8 @@
:raises TypeError: invalid connection, bad parameter type, or too many parameters
:raises ValueError: bad OID value (0 is invalid_oid)
-This method allows to reuse a formerly created large object through the
-:class:`LargeObject` interface, providing the user have its OID.
+This method allows reusing a previously created large object through the
+:class:`LargeObject` interface, provided the user has its OID.
loimport -- import a file to a large object [LO]
------------------------------------------------
Modified: trunk/docs/contents/pg/db_types.rst (961 => 962)
--- trunk/docs/contents/pg/db_types.rst 2019-01-04 19:43:23 UTC (rev 961)
+++ trunk/docs/contents/pg/db_types.rst 2019-01-04 22:32:04 UTC (rev 962)
@@ -89,6 +89,6 @@
objects of the running connections.
Also note that the typecasting for all of the basic types happens already
- in the C extension module. The typecast functions that can be set with
- the above methods are only called for the types that are not already
- supported by the C extension module.
+ in the C low-level extension module. The typecast functions that can be
+ set with the above methods are only called for the types that are not
+ already supported by the C extension.
Modified: trunk/docs/contents/pg/db_wrapper.rst (961 => 962)
--- trunk/docs/contents/pg/db_wrapper.rst 2019-01-04 19:43:23 UTC (rev 961)
+++ trunk/docs/contents/pg/db_wrapper.rst 2019-01-04 22:32:04 UTC (rev 962)
@@ -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 after enabling this by calling the
+You can get the regular types instead, if you enable this by calling the
:meth:`DB.use_regtypes` method.
has_table_privilege -- check table privilege
@@ -182,8 +182,8 @@
of all existing configuration parameters.
Note that you can request most of the important parameters also using
-:meth:`Connection.parameter()` which does not involve a database query
-like it is the case for :meth:`DB.get_parameter` and :meth:`DB.set_parameter`.
+:meth:`Connection.parameter()` which does not involve a database query,
+unlike :meth:`DB.get_parameter` and :meth:`DB.set_parameter`.
.. versionadded:: 4.2
@@ -314,7 +314,7 @@
Otherwise, the row must be a single value or a tuple of values
corresponding to the passed *keyname* or primary key. The fetched row
from the table will be returned as a new dictionary or used to replace
-the existing values when row was passed as aa dictionary.
+the existing values if the row was passed as a dictionary.
The OID is also put into the dictionary if the table has one, but
in order to allow the caller to work with multiple tables, it is
@@ -346,7 +346,7 @@
to pick up values modified by rules, triggers, etc.
Note that since PyGreSQL 5.0 it is possible to insert a value for an
-array type column by passing it as Python list.
+array type column by passing it as a Python list.
update -- update a row in a database table
------------------------------------------
@@ -372,10 +372,11 @@
update due to triggers, rules, default values, etc.
Like insert, the dictionary is optional and updates will be performed
-on the fields in the keywords. There must be an OID or primary key
-either in the dictionary where the OID must be munged, or in the keywords
-where it can be simply the string ``'oid'``.
+on the fields in the keywords. There must be an OID or primary key either
+specified using the ``'oid'`` keyword or in the dictionary, in which case the
+OID must be munged.
+
upsert -- insert a row with conflict resolution
-----------------------------------------------
@@ -391,8 +392,8 @@
:raises pg.ProgrammingError: table has no primary key or missing privilege
This method inserts a row into a table, but instead of raising a
-ProgrammingError exception in case a row with the same primary key already
-exists, an update will be executed instead. This will be performed as a
+ProgrammingError exception in case of violating a constraint or unique index,
+an update will be executed instead. This will be performed as a
single atomic operation on the database, so race conditions can be avoided.
Like the insert method, the first parameter is the name of the table and the
@@ -524,12 +525,12 @@
: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 a prepared statement. If you
-pass an empty name, the unnamed statement will be executed.
+passing the SQL command, you pass the name of an prepared statement that you
+have created previously using the :meth:`DB.prepare` method.
-You must have created the corresponding named or unnamed statement with
-the :meth:`DB.prepare` method before, otherwise an :exc:`pg.OperationalError`
-will be raised.
+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`).
.. versionadded:: 5.1
@@ -547,8 +548,8 @@
:raises TypeError: invalid connection
:raises pg.ProgrammingError: error in query or duplicate query
-This method creates a prepared statement for the given command with the
-given name for later execution with the :meth:`DB.query_prepared` method.
+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
@@ -806,9 +807,9 @@
This method escapes a string for use as an SQL identifier, such as a table,
column, or function name. This is useful when a user-supplied identifier
-might contain special characters that would otherwise not be interpreted
-as part of the identifier by the SQL parser, or when the identifier might
-contain upper case characters whose case should be preserved.
+might contain special characters that would otherwise be misinterpreted
+by the SQL parser, or when the identifier might contain upper case characters
+whose case should be preserved.
.. versionadded:: 4.1
@@ -890,7 +891,7 @@
to be decoded, then you can cast ``json`` or ``jsonb`` columns to ``text``
in PostgreSQL or you can set the decoding function to *None* or a different
function using :func:`pg.set_jsondecode`. By default this is the same as
-the :func:`json.dumps` function from the standard library.
+the :func:`json.loads` function from the standard library.
.. versionadded:: 5.0
@@ -909,7 +910,7 @@
of type names is used can be changed by calling :meth:`DB.get_regtypes`.
If you pass a boolean, it sets whether regular type names shall be used.
The method can also be used to check through its return value whether
-currently regular type names are used.
+regular type names are currently used.
.. versionadded:: 4.1
Modified: trunk/docs/contents/pg/query.rst (961 => 962)
--- trunk/docs/contents/pg/query.rst 2019-01-04 19:43:23 UTC (rev 961)
+++ trunk/docs/contents/pg/query.rst 2019-01-04 22:32:04 UTC (rev 962)
@@ -21,7 +21,7 @@
:raises TypeError: too many (any) parameters
:raises MemoryError: internal memory error
-This method returns the list of the values returned by the query.
+This method returns query results as a list of tuples.
More information about this result may be accessed using
:meth:`Query.listfields`, :meth:`Query.fieldname`
and :meth:`Query.fieldnum` methods.
@@ -41,9 +41,8 @@
:raises TypeError: too many (any) parameters
:raises MemoryError: internal memory error
-This method returns the list of the values returned by the query
-with each tuple returned as a dictionary with the field names
-used as the dictionary index.
+This method returns query results as a list of dictionaries which have
+the field names as keys.
Note that since PyGreSQL 5.0 this will return the values of array type
columns as Python lists.
@@ -61,8 +60,8 @@
:raises TypeError: named tuples not supported
:raises MemoryError: internal memory error
-This method returns the list of the values returned by the query
-with each row returned as a named tuple with proper field names.
+This method returns query results as a list of named tuples with
+proper field names.
Column names in the database that are not valid as field names for
named tuples (particularly, names starting with an underscore) are
@@ -84,7 +83,7 @@
:rtype: list
:raises TypeError: too many parameters
-This method returns the list of names of the fields defined for the
+This method returns the list of field names defined for the
query result. The fields are in the same order as the result values.
fieldname, fieldnum -- field name/number conversion
@@ -114,10 +113,10 @@
:raises TypeError: invalid connection, bad parameter type, or too many parameters
:raises ValueError: unknown field name
-This method returns a field number from its name. It can be used to
+This method returns a field number given its name. It can be used to
build a function that converts result list strings to their correct
type, using a hardcoded table definition. The number returned is the
-field rank in the result values list.
+field rank in the query result.
ntuples -- return number of tuples in query object
--------------------------------------------------
Modified: trunk/docs/contents/postgres/advanced.rst (961 => 962)
--- trunk/docs/contents/postgres/advanced.rst 2019-01-04 19:43:23 UTC (rev 961)
+++ trunk/docs/contents/postgres/advanced.rst 2019-01-04 22:32:04 UTC (rev 962)
@@ -8,14 +8,14 @@
We assume that you have already created a connection to the PostgreSQL
database, as explained in the :doc:`basic`::
+
+ >>> from pg import DB
+ >>> db = DB()
+ >>> query = db.query
+
+Inheritance
+-----------
- >>> from pg import DB
- >>> db = DB()
- >>> query = query
-
-Inheritance
------------
-
A table can inherit from zero or more tables. A query can reference either
all rows of a table or all rows of a table plus all of its descendants.
Modified: trunk/docs/contents/postgres/basic.rst (961 => 962)
--- trunk/docs/contents/postgres/basic.rst 2019-01-04 19:43:23 UTC (rev 961)
+++ trunk/docs/contents/postgres/basic.rst 2019-01-04 22:32:04 UTC (rev 962)
@@ -71,9 +71,9 @@
>>> db.query("""INSERT INTO cities
... VALUES ('San Francisco', '(-194.0, 53.0)')""")
-You can also specify what column the values correspond to. The columns can
+You can also specify the columns to which the values correspond. The columns can
be specified in any order. You may also omit any number of columns,
-unknown precipitation below::
+such as with unknown precipitation, below::
>>> db.query("""INSERT INTO weather (date, city, temp_hi, temp_lo)
... VALUES ('11/29/1994', 'Hayward', 54, 37)""")
@@ -267,8 +267,8 @@
Hayward| 37| 54|San Francisco| 46| 50
(1 row)
-Now let's join two tables. The following joins the "weather" table and the
-"cities" table::
+Now let's join two different tables. The following joins the "weather" table
+and the "cities" table::
>>> print(db.query("""SELECT city, location, prcp, date
... FROM weather, cities
Modified: trunk/docs/contents/postgres/func.rst (961 => 962)
--- trunk/docs/contents/postgres/func.rst 2019-01-04 19:43:23 UTC (rev 961)
+++ trunk/docs/contents/postgres/func.rst 2019-01-04 22:32:04 UTC (rev 962)
@@ -19,13 +19,13 @@
Let's create a simple SQL function that takes no arguments and returns 1::
- >>> query("""CREATE FUNCTION one() RETURNS int4
- ... AS 'SELECT 1 as ONE' LANGUAGE SQL""")
-
-Functions can be used in any expressions (eg. in the target"list or
-qualifications)::
-
- >>> print(db.query("SELECT one() AS answer"))
+ >>> query("""CREATE FUNCTION one() RETURNS int4
+ ... AS 'SELECT 1 as ONE' LANGUAGE SQL""")
+
+Functions can be used in any expressions (eg. in the target list or
+qualifications)::
+
+ >>> print(db.query("SELECT one() AS answer"))
answer
------
1
@@ -86,13 +86,13 @@
... SELECT 'None'::text AS name,
... 1000 AS salary,
... 25 AS age,
- ... 'None'::varchar(16) AS dept
- ... $$ LANGUAGE SQL""")
-
-You can then project a column out of resulting the tuple by using the
-"function notation" for projection columns (i.e. ``bar(foo)`` is equivalent
-to ``foo.bar``). Note that ``new_emp().name`` isn't supported::
-
+ ... 'None'::varchar(16) AS dept
+ ... $$ LANGUAGE SQL""")
+
+You can then extract a column out of the resulting tuple by using the
+"function notation" for projection columns (i.e. ``bar(foo)`` is equivalent
+to ``foo.bar``). Note that ``new_emp().name`` isn't supported::
+
>>> print(query("SELECT name(new_emp()) AS nobody"))
nobody
------
@@ -128,13 +128,13 @@
Claire| 5000| 32|shoe
Andy | -1000| 2|candy
Bill | 4200| 36|shoe
- Ginger| 4800| 30|candy
- (5 rows)
- >>> query("""CREATE FUNCTION clean_EMP () RETURNS int4 AS
- ... 'DELETE FROM EMP WHERE EMP.salary <= 0;
- ... SELECT 1 AS ignore_this'
- ... LANGUAGE SQL""")
- >>> query("SELECT clean_EMP()")
+ Ginger| 4800| 30|candy
+ (5 rows)
+ >>> query("""CREATE FUNCTION clean_EMP () RETURNS int4 AS
+ ... 'DELETE FROM EMP WHERE EMP.salary < 0;
+ ... SELECT 1 AS ignore_this'
+ ... LANGUAGE SQL""")
+ >>> query("SELECT clean_EMP()")
clean_emp
---------
1
Modified: trunk/docs/contents/postgres/syscat.rst (961 => 962)
--- trunk/docs/contents/postgres/syscat.rst 2019-01-04 19:43:23 UTC (rev 961)
+++ trunk/docs/contents/postgres/syscat.rst 2019-01-04 22:32:04 UTC (rev 962)
@@ -7,9 +7,9 @@
such as information about tables and columns, and internal bookkeeping
information. You can drop and recreate the tables, add columns, insert and
update values, and severely mess up your system that way. Normally, one
-should not change the system catalogs by hand, there are always SQL commands
-to do that. For example, CREATE DATABASE inserts a row into the *pg_database*
-catalog — and actually creates the database on disk.
+should not change the system catalogs by hand: there are SQL commands
+to make all supported changes. For example, CREATE DATABASE inserts a row
+into the *pg_database* catalog — and actually creates the database on disk.
It this section we want to show examples for how to parse some of the system
catalogs, making queries with the classic PyGreSQL interface.
@@ -19,8 +19,9 @@
>>> from pg import DB
>>> db = DB()
- >>> query = query
+ >>> query = db.query
+
Lists indices
-------------
@@ -31,7 +32,7 @@
FROM pg_class bc, pg_class ic, pg_index i, pg_attribute a
WHERE i.indrelid = bc.oid AND i.indexrelid = ic.oid
AND i.indkey[0] = a.attnum AND a.attrelid = bc.oid
- AND NOT a.attisdropped
+ AND NOT a.attisdropped AND a.attnum>0
ORDER BY class_name, index_name, attname"""))
@@ -38,17 +39,20 @@
List user defined attributes
----------------------------
-This query lists all user defined attributes and their type
-in user-defined classes::
+This query lists all user-defined attributes and their types
+in user-defined tables::
- print(query("""SELECT c.relname, a.attname, t.typname
- FROM pg_class c, pg_attribute a, pg_type t
- WHERE c.relkind = 'r' and c.relname !~ '^pg_'
- AND c.relname !~ '^Inv' and a.attnum > 0
- AND a.attrelid = c.oid and a.atttypid = t.oid
+ print(query("""SELECT c.relname, a.attname,
+ format_type(a.atttypid, a.atttypmod)
+ FROM pg_class c, pg_attribute a
+ WHERE c.relkind = 'r' AND c.relnamespace!=ALL(ARRAY[
+ 'pg_catalog','pg_toast', 'information_schema']::regnamespace[])
+ AND a.attnum > 0
+ AND a.attrelid = c.oid
AND NOT a.attisdropped
ORDER BY relname, attname"""))
+
List user defined base types
----------------------------
@@ -62,8 +66,8 @@
ORDER BY rolname, typname"""))
-List operators
----------------
+List operators
+--------------
This query lists all right-unary operators::
@@ -121,6 +125,7 @@
and p.proargtypes[0] = t.oid
ORDER BY proname, typname"""))
+
List operator families
----------------------
Modified: trunk/docs/contents/tutorial.rst (961 => 962)
--- trunk/docs/contents/tutorial.rst 2019-01-04 19:43:23 UTC (rev 961)
+++ trunk/docs/contents/tutorial.rst 2019-01-04 22:32:04 UTC (rev 962)
@@ -13,8 +13,7 @@
.. py:currentmodule:: pg
-The first thing you need to do anything with your PostgreSQL database is
-to create a database connection.
+Before doing anything else, it's necessary to create a database connection.
To do this, simply import the :class:`DB` wrapper class and create an
instance of it, passing the necessary connection parameters, like this::
@@ -194,7 +193,7 @@
>>> con = connect(database='testdb', host='pgserver:5432',
... user='scott', password='tiger')
-Note that like in the classic interface, you can omit parameters if they
+As in the classic interface, you can omit parameters if they
are the default values used by PostgreSQL.
To do anything with the connection, you need to request a cursor object
@@ -203,14 +202,13 @@
>>> cursor = con.cursor()
-The cursor now has a method that lets you execute database queries::
+The cursor has a method that lets you execute database queries::
>>> cursor.execute("create table fruits("
... "id serial primary key, name varchar)")
+You can also use this method to insert data into the table::
-To insert data into the table, also can also use this method::
-
>>> cursor.execute("insert into fruits (name) values ('apple')")
You can pass parameters in a safe way::
@@ -217,7 +215,7 @@
>>> cursor.execute("insert into fruits (name) values (%s)", ('banana',))
-For inserting multiple rows at once, you can use the following method::
+To insert multiple rows at once, you can use the following method::
>>> more_fruits = 'cherimaya durian eggfruit fig grapefruit'.split()
>>> parameters = [(name,) for name in more_fruits]
@@ -231,15 +229,15 @@
Also note that the DB API 2.0 interface does not have an autocommit as you
may be used from PostgreSQL. So in order to make these inserts permanent,
-you need to commit them to the database first::
+you need to commit them to the database::
>>> con.commit()
If you end the program without calling the commit method of the connection,
-or if you call the rollback method of the connection, then all the changes
+or if you call the rollback method of the connection, then the changes
will be discarded.
-In a similar way, you can also update or delete rows in the database,
+In a similar way, you can update or delete rows in the database,
executing UPDATE or DELETE statements instead of INSERT statements.
To fetch rows from the database, execute a SELECT statement first. Then
@@ -251,8 +249,8 @@
Row(id=1, name='apple')
The result is a named tuple. This means you can access its elements either
-using an index number like in an ordinary tuple, or using the column name
-like you access object attributes.
+using an index number as for an ordinary tuple, or using the column name
+as for access to object attributes.
To fetch all rows of the query, use this method instead::
@@ -274,4 +272,4 @@
>>> cur.close()
>>> con.close()
-For more advanced features and details, see the reference: :doc:`pgdb/index`
\ No newline at end of file
+For more advanced features and details, see the reference: :doc:`pgdb/index`
