diff --git a/doc/src/advanced.rst b/doc/src/advanced.rst index 40360648..2801a2df 100644 --- a/doc/src/advanced.rst +++ b/doc/src/advanced.rst @@ -149,7 +149,7 @@ column of the `cursor.description`: >>> point_oid 600 -or by querying the system catalogs for the type name and namespace (the +or by querying the system catalog for the type name and namespace (the namespace for system objects is :sql:`pg_catalog`): >>> cur.execute(""" @@ -163,7 +163,7 @@ namespace for system objects is :sql:`pg_catalog`): >>> point_oid 600 -After you know the object OID, you must can and register the new type: +After you know the object OID, you can create and register the new type: >>> POINT = psycopg2.extensions.new_type((point_oid,), "POINT", cast_point) >>> psycopg2.extensions.register_type(POINT) diff --git a/doc/src/cursor.rst b/doc/src/cursor.rst index ffdce6f2..b31f2e79 100644 --- a/doc/src/cursor.rst +++ b/doc/src/cursor.rst @@ -198,6 +198,8 @@ The ``cursor`` class The following methods are used to read data from the database after an `~cursor.execute()` call. + .. _cursor-iterable: + .. note:: `cursor` objects are iterable, so, instead of calling diff --git a/doc/src/extensions.rst b/doc/src/extensions.rst index e2e68664..c4dfd665 100644 --- a/doc/src/extensions.rst +++ b/doc/src/extensions.rst @@ -104,7 +104,7 @@ deal with Python objects adaptation: .. function:: adapt(obj) - Return the SQL representation of `obj` as a string. Raise a + Return the SQL representation of *obj* as a string. Raise a `~psycopg2.ProgrammingError` if how to adapt the object is unknown. In order to allow new objects to be adapted, register a new adapter for it using the `register_adapter()` function. @@ -115,9 +115,9 @@ deal with Python objects adaptation: .. function:: register_adapter(class, adapter) - Register a new adapter for the objects of class `class`. + Register a new adapter for the objects of class *class*. - `adapter` should be a function taking a single argument (the object + *adapter* should be a function taking a single argument (the object to adapt) and returning an object conforming the `ISQLQuote` protocol (e.g. exposing a `!getquoted()` method). The `AsIs` is often useful for this task. @@ -236,19 +236,20 @@ details. The object OID can be read from the `cursor.description` attribute or by querying from the PostgreSQL catalog. - `adapter` should have signature :samp:`fun({value}, {cur})` where - :samp:`{value}` is the string representation returned by PostgreSQL and - :samp:`{cur}` is the cursor from which data are read. In case of - :sql:`NULL`, :samp:`{value}` is ``None``. The adapter should return the + *adapter* should have signature :samp:`fun({value}, {cur})` where + *value* is the string representation returned by PostgreSQL and + *cur* is the cursor from which data are read. In case of + :sql:`NULL`, *value* will be ``None``. The adapter should return the converted object. See :ref:`type-casting-from-sql-to-python` for an usage example. + .. function:: register_type(obj [, scope]) Register a type caster created using `new_type()`. - If `scope` is specified, it should be a `connection` or a + If *scope* is specified, it should be a `connection` or a `cursor`: the type caster will be effective only limited to the specified object. Otherwise it will be globally registered. @@ -330,9 +331,9 @@ set to one of the following constants: .. data:: ISOLATION_LEVEL_READ_UNCOMMITTED - The :sql:`READ UNCOMMITTED` isolation level is defined in the SQL standard but not available in - the |MVCC| model of PostgreSQL: it is replaced by the stricter :sql:`READ - COMMITTED`. + The :sql:`READ UNCOMMITTED` isolation level is defined in the SQL standard + but not available in the |MVCC| model of PostgreSQL: it is replaced by the + stricter :sql:`READ COMMITTED`. .. data:: ISOLATION_LEVEL_READ_COMMITTED diff --git a/doc/src/module.rst b/doc/src/module.rst index 76a8f58c..df067037 100644 --- a/doc/src/module.rst +++ b/doc/src/module.rst @@ -90,7 +90,7 @@ available through the following exceptions: Exception that is the base class of all other error exceptions. You can use this to catch all errors with one single ``except`` statement. Warnings - are not considered errors and thus should not use this class as base. It + are not considered errors and thus not use this class as base. It is a subclass of the Python |StandardError|_. .. attribute:: pgerror diff --git a/doc/src/usage.rst b/doc/src/usage.rst index 5662c7c4..09e6b723 100644 --- a/doc/src/usage.rst +++ b/doc/src/usage.rst @@ -57,8 +57,8 @@ The main entry point of Psycopg are: - send commands to the database using methods such as `~cursor.execute()` and `~cursor.executemany()`, - - retrieve data from the database using methods such as - `~cursor.fetchone()`, `~cursor.fetchmany()`, + - retrieve data from the database :ref:`by iteration ` or + using methods such as `~cursor.fetchone()`, `~cursor.fetchmany()`, `~cursor.fetchall()`. @@ -305,7 +305,7 @@ Unicode handling Psycopg can exchange Unicode data with a PostgreSQL database. Python `!unicode` objects are automatically *encoded* in the client encoding defined on the database connection (the `PostgreSQL encoding`__, available in -`connection.encoding`, is translated into a `Python codec`__ using an +`connection.encoding`, is translated into a `Python codec`__ using the `~psycopg2.extensions.encodings` mapping):: >>> print u, type(u) @@ -427,7 +427,7 @@ Psycopg wraps the database server side cursor in *named cursors*. A named cursor is created using the `~connection.cursor()` method specifying the `name` parameter. Such cursor will behave mostly like a regular cursor, allowing the user to move in the dataset using the `~cursor.scroll()` -methog and to read the data using `~cursor.fetchone()` and +method and to read the data using `~cursor.fetchone()` and `~cursor.fetchmany()` methods. .. |DECLARE| replace:: :sql:`DECLARE` @@ -443,7 +443,7 @@ Thread safety ------------- The Psycopg module is *thread-safe*: threads can access the same database -using separate session (by creating a `connection` per thread) or using +using separate sessions (by creating a `connection` per thread) or using the same session (accessing to the same connection and creating separate `cursor`\ s). In |DBAPI|_ parlance, Psycopg is *level 2 thread safe*.