From 29feed31b618444a03fc4d28a2729048c1dc961d Mon Sep 17 00:00:00 2001 From: Daniele Varrazzo Date: Thu, 18 Feb 2010 01:08:44 +0000 Subject: [PATCH] Cleaned up parameters style from the docs. --- doc/src/connection.rst | 10 ++++----- doc/src/cursor.rst | 46 +++++++++++++++++++++--------------------- doc/src/extensions.rst | 20 +++++++++--------- doc/src/extras.rst | 2 +- doc/src/module.rst | 20 +++++++++--------- doc/src/tz.rst | 2 +- doc/src/usage.rst | 2 +- 7 files changed, 51 insertions(+), 51 deletions(-) diff --git a/doc/src/connection.rst b/doc/src/connection.rst index fdfcc8b3..08d463a4 100644 --- a/doc/src/connection.rst +++ b/doc/src/connection.rst @@ -25,18 +25,18 @@ The ``connection`` class Return a new :class:`cursor` object using the connection. - If :obj:`!name` is specified, the returned cursor will be a *server + If `name` is specified, the returned cursor will be a *server side* (or *named*) cursor. Otherwise the cursor will be *client side*. See :ref:`server-side-cursors` for further details. - The :obj:`!cursor_factory` argument can be used to create non-standard + The `cursor_factory` argument can be used to create non-standard cursors. The class returned should be a subclass of :class:`psycopg2.extensions.cursor`. See :ref:`subclassing-cursor` for details. .. extension:: - The :obj:`!name` and :obj:`!cursor_factory` parameters are Psycopg + The `name` and `cursor_factory` parameters are Psycopg extensions to the |DBAPI|. @@ -137,7 +137,7 @@ The ``connection`` class The default level is :sql:`READ COMMITTED`: in this level a transaction is automatically started every time a database command is executed. If you want an *autocommit* mode, switch to - :obj:`~psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT` + :const:`~psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT` before executing any command:: >>> conn.set_isolation_level(psycopg2.extensions.ISOLATION_LEVEL_AUTOCOMMIT) @@ -307,7 +307,7 @@ The ``connection`` class (using the |lo_import|_ function) :param lobject_factory: Subclass of :class:`~psycopg2.extensions.lobject` to be instantiated. - :rtype: :obj:`~psycopg2.extensions.lobject` + :rtype: :class:`~psycopg2.extensions.lobject` .. |lo_import| replace:: :func:`!lo_import` .. _lo_import: http://www.postgresql.org/docs/8.4/static/lo-interfaces.html#AEN36307 diff --git a/doc/src/cursor.rst b/doc/src/cursor.rst index 55cef3b7..dcb6c22b 100644 --- a/doc/src/cursor.rst +++ b/doc/src/cursor.rst @@ -31,7 +31,7 @@ The ``cursor`` class :meth:`~connection.commit` methods. Cursors are *not* thread safe: a multithread application can create - many cursors from the same same connection and should use each cursor from + many cursors from the same connection and should use each cursor from a single thread. See :ref:`thread-safety` for details. @@ -121,7 +121,7 @@ The ``cursor`` class The method returns `None`. If a query was executed, the returned values can be retrieved using |fetch*|_ methods. - If :obj:`!async` is ``True``, query execution will be asynchronous: + If `async` is ``True``, query execution will be asynchronous: the function returns immediately while the query is executed by the backend. Use the :meth:`~cursor.isready` method to see if the data is ready for return via |fetch*|_ methods. See @@ -129,7 +129,7 @@ The ``cursor`` class .. extension:: - The :obj:`async` parameter is a Psycopg extension to the |DBAPI|. + The `async` parameter is a Psycopg extension to the |DBAPI|. .. method:: mogrify(operation [, parameters]) @@ -150,7 +150,7 @@ The ``cursor`` class Prepare a database operation (query or command) and then execute it against all parameter tuples or mappings found in the sequence - :obj:`!seq_of_parameters`. + `seq_of_parameters`. The function is mostly useful for commands that update the database: any result set returned by the query is discarded. @@ -170,7 +170,7 @@ The ``cursor`` class The procedure may also provide a result set as output. This must then be made available through the standard |fetch*|_ methods. - If :obj:`!async` is ``True``, procedure execution will be asynchronous: + If `async` is ``True``, procedure execution will be asynchronous: the function returns immediately while the procedure is executed by the backend. Use the :meth:`~cursor.isready` method to see if the data is ready for return via |fetch*|_ methods. See @@ -178,7 +178,7 @@ The ``cursor`` class .. extension:: - The :obj:`async` parameter is a Psycopg extension to the |DBAPI|. + The `async` parameter is a Psycopg extension to the |DBAPI|. .. method:: setinputsizes(sizes) @@ -276,7 +276,7 @@ The ``cursor`` class Scroll the cursor in the result set to a new position according to mode. - If :obj:`!mode` is ``relative`` (default), value is taken as offset to + If `mode` is ``relative`` (default), value is taken as offset to the current position in the result set, if set to ``absolute``, value states an absolute target position. @@ -347,7 +347,7 @@ The ``cursor`` class PostgreSQL currently advices to not create OIDs on the tables and the default for |CREATE-TABLE|__ is to not support them. The |INSERT-RETURNING|__ syntax available from PostgreSQL 8.3 allows more - flexibility: + flexibility. .. |CREATE-TABLE| replace:: :sql:`CREATE TABLE` .. __: http://www.postgresql.org/docs/8.4/static/sql-createtable.html @@ -441,15 +441,15 @@ The ``cursor`` class .. method:: copy_from(file, table, sep='\\t', null='\\N', columns=None) - Read data *from* the file-like object :obj:`!file` appending them to - the table named :obj:`!table`. :obj:`!file` must have both + Read data *from* the file-like object `file` appending them to + the table named `table`. `file` must have both :meth:`!read` and :meth:`!readline` method. See :ref:`copy` for an overview. - The optional argument :obj:`!sep` is the columns separator and - :obj:`!null` represents :sql:`NULL` values in the file. + The optional argument `sep` is the columns separator and + `null` represents :sql:`NULL` values in the file. - The :obj:`!columns` argument is a sequence containing the name of the + The `columns` argument is a sequence containing the name of the fields where the read data will be entered. Its length and column type should match the content of the read file. If not specifies, it is assumed that the entire table matches the file structure. @@ -461,19 +461,19 @@ The ``cursor`` class [(6, 42, 'foo'), (7, 74, 'bar')] .. versionchanged:: 2.0.6 - added the :obj:`columns` parameter. + added the `columns` parameter. .. method:: copy_to(file, table, sep='\\t', null='\\N', columns=None) - Write the content of the table named :obj:`!table` *to* the file-like - object :obj:`!file`. :obj:`!file` must have a :meth:`!write` method. + Write the content of the table named `table` *to* the file-like + object `file`. `file` must have a :meth:`!write` method. See :ref:`copy` for an overview. - The optional argument :obj:`!sep` is the columns separator and - :obj:`!null` represents :sql:`NULL` values in the file. + The optional argument `sep` is the columns separator and + `null` represents :sql:`NULL` values in the file. - The :obj:`!columns` argument is a sequence of field names: if not + The `columns` argument is a sequence of field names: if not ``None`` only the specified fields will be included in the dump. >>> cur.copy_to(sys.stdout, 'test', sep="|") @@ -482,7 +482,7 @@ The ``cursor`` class ... .. versionchanged:: 2.0.6 - added the :obj:`columns` parameter. + added the `columns` parameter. .. method:: copy_expert(sql, file [, size]) @@ -491,10 +491,10 @@ The ``cursor`` class handle all the parameters that PostgreSQL makes available (see |COPY|__ command documentation). - :obj:`!file` must be an open, readable file for :sql:`COPY FROM` or an - open, writeable file for :sql:`COPY TO`. The optional :obj:`!size` + `file` must be an open, readable file for :sql:`COPY FROM` or an + open, writeable file for :sql:`COPY TO`. The optional `size` argument, when specified for a :sql:`COPY FROM` statement, will be - passed to :obj:`!file`\ 's read method to control the read buffer + passed to `file`\ 's read method to control the read buffer size. >>> cur.copy_expert("COPY test TO STDOUT WITH CSV HEADER", sys.stdout) diff --git a/doc/src/extensions.rst b/doc/src/extensions.rst index ea1c52e4..99479018 100644 --- a/doc/src/extensions.rst +++ b/doc/src/extensions.rst @@ -18,7 +18,7 @@ functionalities defined by the |DBAPI|_. Is the class usually returned by the :func:`~psycopg2.connect` function. It is exposed by the :mod:`extensions` module in order to allow subclassing to extend its behaviour: the subclass should be passed to the - :func:`!connect` function using the :obj:`!connection_factory` parameter. + :func:`!connect` function using the `connection_factory` parameter. See also :ref:`subclassing-connection`. For a complete description of the class, see :class:`connection`. @@ -28,7 +28,7 @@ functionalities defined by the |DBAPI|_. It is the class usually returnded by the :meth:`connection.cursor` method. It is exposed by the :mod:`extensions` module in order to allow subclassing to extend its behaviour: the subclass should be passed to the - :meth:`!cursor` method using the :obj:`!cursor_factory` parameter. See + :meth:`!cursor` method using the `cursor_factory` parameter. See also :ref:`subclassing-cursor`. For a complete description of the class, see :class:`cursor`. @@ -104,7 +104,7 @@ deal with Python objects adaptation: .. function:: adapt(obj) - Return the SQL representation of :obj:`obj` as a string. Raise a + Return the SQL representation of `obj` as a string. Raise a :exc:`~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 :func:`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 :data:`class`. + Register a new adapter for the objects of class `class`. - :data:`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 :class:`ISQLQuote` protocol (e.g. exposing a :meth:`!getquoted` method). The :class:`AsIs` is often useful for this task. @@ -233,10 +233,10 @@ details. :param name: the name of the new type adapter. :param adapter: the adaptation function. - The object OID can be read from the :data:`cursor.description` attribute + The object OID can be read from the :attr:`cursor.description` attribute or by querying from the PostgreSQL catalog. - :data:`adapter` should have signature :samp:`fun({value}, {cur})` where + `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 @@ -248,7 +248,7 @@ details. Register a type caster created using :func:`new_type`. - If :obj:`!scope` is specified, it should be a :class:`connection` or a + If `scope` is specified, it should be a :class:`connection` or a :class:`cursor`: the type caster will be effective only limited to the specified object. Otherwise it will be globally registered. @@ -399,7 +399,7 @@ Connection status constants --------------------------- These values represent the possible status of a connection: the current value -can be read from the :data:`~connection.status` attribute. +can be read from the :attr:`~connection.status` attribute. .. data:: STATUS_SETUP @@ -415,7 +415,7 @@ can be read from the :data:`~connection.status` attribute. .. data:: STATUS_IN_TRANSACTION - An alias for :data:`STATUS_BEGIN` + An alias for :const:`STATUS_BEGIN` .. data:: STATUS_SYNC diff --git a/doc/src/extras.rst b/doc/src/extras.rst index de8dcce8..3184669f 100644 --- a/doc/src/extras.rst +++ b/doc/src/extras.rst @@ -26,7 +26,7 @@ Dictionary-like cursor The dict cursors allow to access to the retrieved records using an iterface similar to the Python dictionaries instead of the tuples. You can use it -either passing :class:`DictConnection` as :obj:`!connection_factory` argument +either passing :class:`DictConnection` as `connection_factory` argument to the :func:`~psycopg2.connect` function or passing :class:`DictCursor` as the :class:`!cursor_factory` argument to the :meth:`~connection.cursor` method of a regular :class:`connection`. diff --git a/doc/src/module.rst b/doc/src/module.rst index 3bb7559f..f4ef27b2 100644 --- a/doc/src/module.rst +++ b/doc/src/module.rst @@ -30,24 +30,24 @@ The module interface respects the standard defined in the |DBAPI|_. The full list of available parameters is: - - :obj:`!dbname` -- the database name (only in dsn string) - - :obj:`!database` -- the database name (only as keyword argument) - - :obj:`!user` -- user name used to authenticate - - :obj:`!password` -- password used to authenticate - - :obj:`!host` -- database host address (defaults to UNIX socket if not provided) - - :obj:`!port` -- connection port number (defaults to 5432 if not provided) - - :obj:`!sslmode` -- `SSL TCP/IP negotiation`__ mode + - `dbname` -- the database name (only in dsn string) + - `database` -- the database name (only as keyword argument) + - `user` -- user name used to authenticate + - `password` -- password used to authenticate + - `host` -- database host address (defaults to UNIX socket if not provided) + - `port` -- connection port number (defaults to 5432 if not provided) + - `sslmode` -- `SSL TCP/IP negotiation`__ mode .. __: http://www.postgresql.org/docs/8.4/static/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS - Using the :obj:`!connection_factory` parameter a different class or + Using the `connection_factory` parameter a different class or connections factory can be specified. It should be a callable object - taking a :obj:`!dsn` argument. See :ref:`subclassing-connection` for + taking a `dsn` argument. See :ref:`subclassing-connection` for details. .. extension:: - The :obj:`connection_factory` parameter is a Psycopg extension to the + The `connection_factory` parameter is a Psycopg extension to the |DBAPI|. diff --git a/doc/src/tz.rst b/doc/src/tz.rst index 3cac88c1..86d26996 100644 --- a/doc/src/tz.rst +++ b/doc/src/tz.rst @@ -6,7 +6,7 @@ .. module:: psycopg2.tz This module holds two different tzinfo implementations that can be used as the -:obj:`tzinfo` argument to datetime constructors, directly passed to Psycopg +`tzinfo` argument to datetime constructors, directly passed to Psycopg functions or used to set the :attr:`cursor.tzinfo_factory` attribute in cursors. diff --git a/doc/src/usage.rst b/doc/src/usage.rst index fa756f80..413580e6 100644 --- a/doc/src/usage.rst +++ b/doc/src/usage.rst @@ -425,7 +425,7 @@ subsequently handled using :sql:`MOVE`, :sql:`FETCH` and :sql:`CLOSE` commands. Psycopg wraps the database server side cursor in *named cursors*. A named cursor is created using the :meth:`~connection.cursor` method specifying the -:obj:`!name` parameter. Such cursor will behave mostly like a regular cursor, +`name` parameter. Such cursor will behave mostly like a regular cursor, allowing the user to move in the dataset using the :meth:`~cursor.scroll` methog and to read the data using :meth:`~cursor.fetchone` and :meth:`~cursor.fetchmany` methods.