* Docstrings added/fixed

* Added __all__ attributes to Python modules to explicit the package API

lib/__init__.py

@@ -1,10 +1,20 @@
 """A Python driver for PostgreSQL
 
-psycopg is a PostgreSQL database adapter for the Python programming
+psycopg is a PostgreSQL_ database adapter for the Python_ programming
 language. This is version 2, a complete rewrite of the original code to
 provide new-style classes for connection and cursor objects and other sweet
 candies. Like the original, psycopg 2 was written with the aim of being very
 small and fast, and stable as a rock.
+
+Homepage: http://initd.org/projects/psycopg2
+
+.. _PostgreSQL: http://www.postgresql.org/
+.. _Python: http://www.python.org/
+
+:Groups:
+  * `Connections creation`: connect
+  * `Value objects constructors`: Binary, Date, DateFromTicks, Time,
+    TimeFromTicks, Timestamp, TimestampFromTicks
 """
 # psycopg/__init__.py - initialization of the psycopg module
 #
@@ -58,3 +68,5 @@ from _psycopg import NotSupportedError, OperationalError
 
 from _psycopg import connect, apilevel, threadsafety, paramstyle
 from _psycopg import __version__
+
+__all__ = [ k for k in locals().keys() if not k.startswith('_') ]

lib/extensions.py

@@ -55,3 +55,5 @@ ISOLATION_LEVEL_READ_UNCOMMITTED = ISOLATION_LEVEL_READ_COMMITTED
 def register_adapter(typ, callable):
     """Register 'callable' as an ISQLQuote adapter for type 'typ'."""
     adapters[(typ, ISQLQuote)] = callable
+
+__all__ = [ k for k in locals().keys() if not k.startswith('_') ]

psycopg/adapter_binary.h

@@ -43,7 +43,8 @@ typedef struct {
     
 extern PyObject *psyco_Binary(PyObject *module, PyObject *args);
 #define psyco_Binary_doc \
-    "Binary(buffer) -> new binary object"
+    "Binary(buffer) -> new binary object\n\n" \
+    "Build an object capable to hold a bynary string value."
 
 #ifdef __cplusplus
 }

psycopg/adapter_datetime.h

@@ -48,27 +48,39 @@ typedef struct {
     
 extern PyObject *psyco_Date(PyObject *module, PyObject *args);
 #define psyco_Date_doc \
-    "Date(year, month, day) -> new date"
+    "Date(year, month, day) -> new date\n\n" \
+    "Build an object holding a date value."
 
 extern PyObject *psyco_Time(PyObject *module, PyObject *args);
 #define psyco_Time_doc \
-    "Time(hour, minutes, seconds, tzinfo=None) -> new time"
+    "Time(hour, minutes, seconds, tzinfo=None) -> new time\n\n" \
+    "Build an object holding a time value."
 
 extern PyObject *psyco_Timestamp(PyObject *module, PyObject *args);
 #define psyco_Timestamp_doc \
-    "Timestamp(year, month, day, hour, minutes, seconds, tzinfo=None) -> new timestamp"
+    "Timestamp(year, month, day, hour, minutes, seconds, tzinfo=None) -> new timestamp\n\n" \
+    "Build an object holding a timestamp value."
 
 extern PyObject *psyco_DateFromTicks(PyObject *module, PyObject *args);
 #define psyco_DateFromTicks_doc \
-    "DateFromTicks(ticks) -> new date"
+    "DateFromTicks(ticks) -> new date\n\n" \
+    "Build an object holding a date value from the given ticks value.\n\n" \
+    "Ticks are the number of seconds since the epoch; see the documentation " \
+    "of the standard Python time module for details)."
 
 extern PyObject *psyco_TimeFromTicks(PyObject *module, PyObject *args);
 #define psyco_TimeFromTicks_doc \
-    "TimeFromTicks(ticks) -> new time"
+    "TimeFromTicks(ticks) -> new time\n\n" \
+    "Build an object holding a time value from the given ticks value.\n\n" \
+    "Ticks are the number of seconds since the epoch; see the documentation " \
+    "of the standard Python time module for details)."
 
 extern PyObject *psyco_TimestampFromTicks(PyObject *module, PyObject *args);
 #define psyco_TimestampFromTicks_doc \
-    "TimestampFromTicks(ticks) -> new timestamp"
+    "TimestampFromTicks(ticks) -> new timestamp\n\n" \
+    "Build an object holding a timestamp value from the given ticks value.\n\n" \
+    "Ticks are the number of seconds since the epoch; see the documentation " \
+    "of the standard Python time module for details)."
 
 #endif /* PSYCOPG_DEFAULT_PYDATETIME */
 

psycopg/connection_type.c

@@ -37,11 +37,12 @@
 /* cursor method - allocate a new cursor */
 
 #define psyco_conn_cursor_doc \
-"cursor(cursor_factory=psycopg2.extensions.cursor) -> new cursor\n\n"       \
+"cursor(cursor_factory=extensions.cursor) -- new cursor\n\n"                \
 "Return a new cursor.\n\nThe ``cursor_factory`` argument can be used to\n"  \
 "create non-standard cursors by passing a class different from the\n"       \
 "default. Note that the new class *should* be a sub-class of\n"             \
-"``psycopg2.extensions.cursor``."
+"`extensions.cursor`.\n\n"                                                  \
+":rtype: `extensions.cursor`"
 
 static PyObject *
 psyco_conn_cursor(connectionObject *self, PyObject *args, PyObject *keywds)
@@ -222,24 +223,31 @@ static struct PyMethodDef connectionObject_methods[] = {
 
 static struct PyMemberDef connectionObject_members[] = {
     /* DBAPI-2.0 extensions (exception objects) */
-    {"Error", T_OBJECT, offsetof(connectionObject, exc_Error), RO},
-    {"Warning", T_OBJECT, offsetof(connectionObject, exc_Warning), RO},
+    {"Error", T_OBJECT, 
+        offsetof(connectionObject, exc_Error), RO, Error_doc},
+    {"Warning", 
+        T_OBJECT, offsetof(connectionObject, exc_Warning), RO, Warning_doc},
     {"InterfaceError", T_OBJECT,
-        offsetof(connectionObject, exc_InterfaceError), RO},
+        offsetof(connectionObject, exc_InterfaceError), RO,
+        InterfaceError_doc},
     {"DatabaseError", T_OBJECT,
-        offsetof(connectionObject, exc_DatabaseError), RO},
+        offsetof(connectionObject, exc_DatabaseError), RO, DatabaseError_doc},
     {"InternalError", T_OBJECT,
-        offsetof(connectionObject, exc_InternalError), RO},
+        offsetof(connectionObject, exc_InternalError), RO, InternalError_doc},
     {"OperationalError", T_OBJECT,
-        offsetof(connectionObject, exc_OperationalError), RO},
+        offsetof(connectionObject, exc_OperationalError), RO,
+        OperationalError_doc},
     {"ProgrammingError", T_OBJECT,
-        offsetof(connectionObject, exc_ProgrammingError), RO},
+        offsetof(connectionObject, exc_ProgrammingError), RO,
+        ProgrammingError_doc},
     {"IntegrityError", T_OBJECT,
-        offsetof(connectionObject, exc_IntegrityError), RO},
+        offsetof(connectionObject, exc_IntegrityError), RO,
+        IntegrityError_doc},
     {"DataError", T_OBJECT,
-        offsetof(connectionObject, exc_DataError), RO},
+        offsetof(connectionObject, exc_DataError), RO, DataError_doc},
     {"NotSupportedError", T_OBJECT,
-     offsetof(connectionObject, exc_NotSupportedError), RO},
+        offsetof(connectionObject, exc_NotSupportedError), RO,
+        NotSupportedError_doc},
 #ifdef PSYCOPG_EXTENSIONS    
     {"closed", T_LONG, offsetof(connectionObject, closed), RO,
         "True if the connection is closed."},
@@ -347,9 +355,9 @@ connection_repr(connectionObject *self)
 #define connectionType_doc \
 "connection(dsn, ...) -> new connection object\n\n" \
 ":Groups:\n" \
-"  * `DBAPI-2.0 errors`: `Error`, `Warning`, `InterfaceError`,\n" \
-"    `DatabaseError`, `InternalError`, `OperationalError`,\n" \
-"    `ProgrammingError`, `IntegrityError`, `DataError`, `NotSupportedError`"
+"  * `DBAPI-2.0 errors`: Error, Warning, InterfaceError,\n" \
+"    DatabaseError, InternalError, OperationalError,\n" \
+"    ProgrammingError, IntegrityError, DataError, NotSupportedError"
 
 PyTypeObject connectionType = {
     PyObject_HEAD_INIT(NULL)

psycopg/cursor_type.c

@@ -1443,7 +1443,7 @@ cursor_repr(cursorObject *self)
 /* object type */
 
 #define cursorType_doc \
-"cursor(conn) -> new cursor object"
+"A database cursor."
 
 PyTypeObject cursorType = {
     PyObject_HEAD_INIT(NULL)

psycopg/psycopg.h

@@ -104,6 +104,37 @@ extern PyObject *decimalType;
 extern void psyco_set_error(PyObject *exc, PyObject *curs,  char *msg, 
                              char *pgerror, char *pgcode);
                                   
+/* Exceptions docstrings */
+#define Error_doc \
+"Base class for error exceptions."
+
+#define Warning_doc \
+"A database warning."
+
+#define InterfaceError_doc \
+"Error related to the database interface."
+
+#define DatabaseError_doc \
+"Error related to the database engine."
+
+#define InternalError_doc \
+"The database encountered an internal error."
+
+#define OperationalError_doc \
+"Error related to database operation (disconnect, memory allocation etc)."
+
+#define ProgrammingError_doc \
+"Error related to database programming (SQL error, table not found etc)."
+
+#define IntegrityError_doc \
+"Error related to database integrity."
+
+#define DataError_doc \
+"Error related to problems with the processed data."
+
+#define NotSupportedError_doc \
+"A not supported datbase API was called."
+
 #ifdef __cplusplus
 }
 #endif

psycopg/psycopgmodule.c

@@ -65,7 +65,7 @@ PyObject *decimalType = NULL;
 
 /** connect module-level function **/
 #define psyco_connect_doc \
-"connect(dsn, ...) -> new connection object -- Create a new database connection.\n\n" \
+"connect(dsn, ...) -- Create a new database connection.\n\n"               \
 "This function supports two different but equivalent sets of arguments.\n" \
 "A single data source name or ``dsn`` string can be used to specify the\n" \
 "connection parameters, as follows::\n\n"                                  \
@@ -82,9 +82,11 @@ PyObject *decimalType = NULL;
 "- ``password`` -- password used to authenticate\n"                        \
 "- ``sslmode`` -- SSL mode (see PostgreSQL documentation)\n\n"             \
 "If the ``connection_factory`` keyword argument is not provided this\n"    \
-"function always return an instance of the ``connection`` class.\n"        \
-"Else the given sub-class of ``connection`` will be used to\n"             \
-"instantiate the connection object.\n" 
+"function always return an instance of the `connection` class.\n"          \
+"Else the given sub-class of `extensions.connection` will be used to\n"    \
+"instantiate the connection object.\n\n"                                   \
+":return: New database connection\n"                                         \
+":rtype: `extensions.connection`"
 
 static int
 _psyco_connect_fill_dsn(char *dsn, char *kw, char *v, int i)
@@ -307,6 +309,30 @@ PyObject *Error, *Warning, *InterfaceError, *DatabaseError,
     *InternalError, *OperationalError, *ProgrammingError,
     *IntegrityError, *DataError, *NotSupportedError;
 
+/* mapping between exception names and their PyObject */
+static struct {
+    char *name;
+    PyObject **exc;
+    PyObject **base;
+    char *docstr;
+} exctable[] = {
+    { "psycopg2.Error", &Error, 0, Error_doc },
+    { "psycopg2.Warning", &Warning, 0, Warning_doc },
+    { "psycopg2.InterfaceError", &InterfaceError, &Error, InterfaceError_doc },
+    { "psycopg2.DatabaseError", &DatabaseError, &Error, DatabaseError_doc },
+    { "psycopg2.InternalError", &InternalError, &DatabaseError, InternalError_doc },
+    { "psycopg2.OperationalError", &OperationalError, &DatabaseError, 
+        OperationalError_doc },
+    { "psycopg2.ProgrammingError", &ProgrammingError, &DatabaseError, 
+        ProgrammingError_doc },
+    { "psycopg2.IntegrityError", &IntegrityError, &DatabaseError, 
+        IntegrityError_doc },
+    { "psycopg2.DataError", &DataError, &DatabaseError, DataError_doc },
+    { "psycopg2.NotSupportedError", &NotSupportedError, &DatabaseError, 
+        NotSupportedError_doc },
+    {NULL}  /* Sentinel */
+};
+
 static void
 psyco_errors_init(void)
 {
@@ -314,26 +340,26 @@ psyco_errors_init(void)
        psycopg2 module and not the fact the the original error objects
        live in _psycopg */
        
-    Error = PyErr_NewException("psycopg2.Error", PyExc_StandardError, NULL);
-    
-    Warning = PyErr_NewException("psycopg2.Warning",
-        PyExc_StandardError,NULL);
-    InterfaceError = PyErr_NewException("psycopg2.InterfaceError",
-        Error, NULL);
-    DatabaseError = PyErr_NewException("psycopg2.DatabaseError",
-        Error, NULL);
-    InternalError = PyErr_NewException("psycopg2.InternalError",
-        DatabaseError, NULL);
-    OperationalError = PyErr_NewException("psycopg2.OperationalError",
-        DatabaseError, NULL);
-    ProgrammingError = PyErr_NewException("psycopg2.ProgrammingError",
-        DatabaseError, NULL);
-    IntegrityError = PyErr_NewException("psycopg2.IntegrityError",
-        DatabaseError,NULL);
-    DataError = PyErr_NewException("psycopg2.DataError",
-        DatabaseError, NULL);
-    NotSupportedError = PyErr_NewException("psycopg2.NotSupportedError",
-        DatabaseError, NULL);
+    int i;
+    PyObject *dict;
+    PyObject *base;
+    PyObject *str;
+
+    for (i=0; exctable[i].name; i++) {
+        dict = PyDict_New();
+
+        if (exctable[i].docstr) {
+            str = PyString_FromString(exctable[i].docstr);
+            PyDict_SetItemString(dict, "__doc__", str);
+        }
+
+        if (exctable[i].base == 0)
+            base = PyExc_StandardError;
+        else
+            base = *exctable[i].base;
+
+        *exctable[i].exc = PyErr_NewException(exctable[i].name, base, dict);
+    }
 }
 
 void