Documentation dir reordered.

1 files changed, 308 insertions, 0 deletions

diff --git a/doc/src/module.rst b/doc/src/module.rst
new file mode 100644
index 0000000..3bb7559
--- /dev/null
+++ b/doc/src/module.rst
@@ -0,0 +1,308 @@
+The :mod:`psycopg2` module content
+==================================
+
+.. sectionauthor:: Daniele Varrazzo <daniele.varrazzo@gmail.com>
+
+.. module:: psycopg2
+
+The module interface respects the standard defined in the |DBAPI|_.
+
+.. index:: 
+    single: Connection string
+    double: Connection; Parameters
+    single: Username; Connection
+    single: Password; Connection
+    single: Host; Connection
+    single: Port; Connection
+    single: DSN (Database Source Name)
+
+.. function:: connect(dsn or params[, connection_factory])
+
+    Create a new database session and return a new :class:`connection` object.
+
+    You can specify the connection parameters either as a string::
+
+        conn = psycopg2.connect("dbname=test user=postgres password=secret")
+
+    or using a set of keyword arguments::
+
+        conn = psycopg2.connect(database="test", user="postgres", password="secret")
+
+    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
+
+    .. __: 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
+    connections factory can be specified. It should be a callable object
+    taking a :obj:`!dsn` argument. See :ref:`subclassing-connection` for
+    details.
+
+    .. extension::
+
+        The :obj:`connection_factory` parameter is a Psycopg extension to the
+        |DBAPI|.
+
+
+.. data:: apilevel
+
+    String constant stating the supported DB API level.  For :mod:`psycopg2` is
+    ``2.0``.
+
+.. data:: threadsafety
+
+    Integer constant stating the level of thread safety the interface
+    supports.  For :mod:`psycopg2` is ``2``, i.e. threads can share the module
+    and the connection. See :ref:`thread-safety` for details.
+
+.. data:: paramstyle
+
+    String constant stating the type of parameter marker formatting expected
+    by the interface.  For :mod:`psycopg2` is ``pyformat``.  See also
+    :ref:`query-parameters`.
+
+
+
+.. index:: 
+    single: Exceptions; DB API
+
+.. _dbapi-exceptions:
+
+Exceptions
+----------
+
+In compliance with the |DBAPI|_, the module makes informations about errors
+available through the following exceptions:
+
+.. exception:: Warning 
+            
+    Exception raised for important warnings like data truncations while
+    inserting, etc. It is a subclass of the Python |StandardError|_.
+            
+.. exception:: Error 
+
+    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
+    is a subclass of the Python |StandardError|_.
+
+    .. attribute:: pgerror
+
+        String representing the error message returned by the backend,
+        ``None`` if not available.
+
+    .. attribute:: pgcode
+
+        String representing the error code returned by the backend, ``None``
+        if not available.  The :mod:`~psycopg2.errorcodes` module contains
+        symbolic constants representing PostgreSQL error codes.
+
+    .. extension::
+
+        The :attr:`~Error.pgerror` and :attr:`~Error.pgcode` attributes are
+        Psycopg extensions.
+
+        .. doctest::
+            :options: +NORMALIZE_WHITESPACE
+
+            >>> try:
+            ...     cur.execute("SELECT * FROM barf")
+            ... except Exception, e:
+            ...     pass
+
+            >>> e.pgcode
+            '42P01'
+            >>> print e.pgerror
+            ERROR:  relation "barf" does not exist
+            LINE 1: SELECT * FROM barf
+                                  ^
+
+    .. versionchanged:: 2.0.7 added :attr:`Error.pgerror` and
+        :attr:`Error.pgcode` attributes.
+
+
+    
+.. exception:: InterfaceError
+
+    Exception raised for errors that are related to the database interface
+    rather than the database itself.  It is a subclass of :exc:`Error`.
+
+.. exception:: DatabaseError
+
+    Exception raised for errors that are related to the database.  It is a
+    subclass of :exc:`Error`.
+    
+.. exception:: DataError
+  
+    Exception raised for errors that are due to problems with the processed
+    data like division by zero, numeric value out of range, etc. It is a
+    subclass of :exc:`DatabaseError`.
+    
+.. exception:: OperationalError
+  
+    Exception raised for errors that are related to the database's operation
+    and not necessarily under the control of the programmer, e.g. an
+    unexpected disconnect occurs, the data source name is not found, a
+    transaction could not be processed, a memory allocation error occurred
+    during processing, etc.  It is a subclass of :exc:`DatabaseError`.
+    
+.. exception:: IntegrityError             
+  
+    Exception raised when the relational integrity of the database is
+    affected, e.g. a foreign key check fails.  It is a subclass of
+    :exc:`DatabaseError`.
+    
+.. exception:: InternalError 
+              
+    Exception raised when the database encounters an internal error, e.g. the
+    cursor is not valid anymore, the transaction is out of sync, etc.  It is a
+    subclass of :exc:`DatabaseError`.
+    
+.. exception:: ProgrammingError
+  
+    Exception raised for programming errors, e.g. table not found or already
+    exists, syntax error in the SQL statement, wrong number of parameters
+    specified, etc.  It is a subclass of :exc:`DatabaseError`.
+    
+.. exception:: NotSupportedError
+  
+    Exception raised in case a method or database API was used which is not
+    supported by the database, e.g. requesting a :meth:`!rollback` on a
+    connection that does not support transaction or has transactions turned
+    off.  It is a subclass of :exc:`DatabaseError`.
+
+
+.. extension::
+
+    Psycopg may raise a few other, more specialized, exceptions: currently
+    :exc:`~psycopg2.extensions.QueryCanceledError` and
+    :exc:`~psycopg2.extensions.TransactionRollbackError` are defined. These
+    exceptions are not exposed by the main :mod:`!psycopg2` module but are
+    made available by the :mod:`~psycopg2.extensions` module.  All the
+    additional exceptions are subclasses of standard |DBAPI| exceptions, so
+    trapping them specifically is not required.
+
+
+This is the exception inheritance layout:
+
+.. parsed-literal::
+
+    |StandardError|
+    \|__ :exc:`Warning`
+    \|__ :exc:`Error`
+        \|__ :exc:`InterfaceError`
+        \|__ :exc:`DatabaseError`
+            \|__ :exc:`DataError`
+            \|__ :exc:`OperationalError`
+            \|   \|__ :exc:`psycopg2.extensions.QueryCanceledError`
+            \|   \|__ :exc:`psycopg2.extensions.TransactionRollbackError`
+            \|__ :exc:`IntegrityError`
+            \|__ :exc:`InternalError`
+            \|__ :exc:`ProgrammingError`
+            \|__ :exc:`NotSupportedError`
+
+
+.. |StandardError| replace:: :exc:`!StandardError`
+.. _StandardError: http://docs.python.org/library/exceptions.html#exceptions.StandardError
+
+
+.. _type-objects-and-constructors:
+
+Type Objects and Constructors
+-----------------------------
+
+.. note:: This section is mostly copied verbatim from the |DBAPI|_
+    specification.  While these objects are exposed in compliance to the
+    DB API, Psycopg offers very accurate tools to convert data between Python
+    and PostgreSQL formats.  See :ref:`adapting-new-types` and
+    :ref:`type-casting-from-sql-to-python`
+
+Many databases need to have the input in a particular format for
+binding to an operation's input parameters.  For example, if an
+input is destined for a DATE column, then it must be bound to the
+database in a particular string format.  Similar problems exist
+for "Row ID" columns or large binary items (e.g. blobs or RAW
+columns).  This presents problems for Python since the parameters
+to the .execute*() method are untyped.  When the database module
+sees a Python string object, it doesn't know if it should be bound
+as a simple CHAR column, as a raw BINARY item, or as a DATE.
+
+To overcome this problem, a module must provide the constructors
+defined below to create objects that can hold special values.
+When passed to the cursor methods, the module can then detect the
+proper type of the input parameter and bind it accordingly.
+
+A Cursor Object's description attribute returns information about
+each of the result columns of a query.  The type_code must compare
+equal to one of Type Objects defined below. Type Objects may be
+equal to more than one type code (e.g. DATETIME could be equal to
+the type codes for date, time and timestamp columns; see the
+Implementation Hints below for details).
+
+The module exports the following constructors and singletons:
+    
+.. function:: Date(year,month,day)
+
+    This function constructs an object holding a date value.
+        
+.. function:: Time(hour,minute,second)
+
+    This function constructs an object holding a time value.
+            
+.. function:: Timestamp(year,month,day,hour,minute,second)
+
+    This function constructs an object holding a time stamp value.
+
+.. function:: DateFromTicks(ticks)
+
+    This function constructs an object holding a date value from the given
+    ticks value (number of seconds since the epoch; see the documentation of
+    the standard Python time module for details).
+
+.. function:: TimeFromTicks(ticks)
+  
+    This function constructs an object holding a time value from the given
+    ticks value (number of seconds since the epoch; see the documentation of
+    the standard Python time module for details).
+    
+.. function:: TimestampFromTicks(ticks)
+
+    This function constructs an object holding a time stamp value from the
+    given ticks value (number of seconds since the epoch; see the
+    documentation of the standard Python time module for details).
+
+.. function:: Binary(string)
+  
+    This function constructs an object capable of holding a binary (long)
+    string value.
+    
+
+.. data:: STRING
+
+    This type object is used to describe columns in a database that are
+    string-based (e.g. CHAR).
+
+.. data:: BINARY
+
+    This type object is used to describe (long) binary columns in a database
+    (e.g. LONG, RAW, BLOBs).
+    
+.. data:: NUMBER
+
+    This type object is used to describe numeric columns in a database.
+
+.. data:: DATETIME
+  
+    This type object is used to describe date/time columns in a database.
+    
+.. data:: ROWID
+  
+    This type object is used to describe the "Row ID" column in a database.
+