From 202c002c5c55e3cb046e062d5227b79cad1c6e84 Mon Sep 17 00:00:00 2001 From: Daniele Varrazzo Date: Thu, 12 Jan 2006 18:36:57 +0000 Subject: [PATCH] * Docstrings added/fixed * Added __all__ attributes to Python modules to explicit the package API --- lib/__init__.py | 14 +++++++- lib/extensions.py | 2 ++ psycopg/adapter_binary.h | 3 +- psycopg/adapter_datetime.h | 24 +++++++++---- psycopg/connection_type.c | 38 ++++++++++++-------- psycopg/cursor_type.c | 2 +- psycopg/psycopg.h | 31 ++++++++++++++++ psycopg/psycopgmodule.c | 74 +++++++++++++++++++++++++------------- 8 files changed, 140 insertions(+), 48 deletions(-) diff --git a/lib/__init__.py b/lib/__init__.py index c8da54ff..e40caa3a 100644 --- a/lib/__init__.py +++ b/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('_') ] diff --git a/lib/extensions.py b/lib/extensions.py index c369c931..b4ade2ca 100644 --- a/lib/extensions.py +++ b/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('_') ] diff --git a/psycopg/adapter_binary.h b/psycopg/adapter_binary.h index 4cbd12ab..2ce04164 100644 --- a/psycopg/adapter_binary.h +++ b/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 } diff --git a/psycopg/adapter_datetime.h b/psycopg/adapter_datetime.h index 9fbed3d3..a32bb8df 100644 --- a/psycopg/adapter_datetime.h +++ b/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 */ diff --git a/psycopg/connection_type.c b/psycopg/connection_type.c index d38be30d..195e6ec7 100644 --- a/psycopg/connection_type.c +++ b/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) diff --git a/psycopg/cursor_type.c b/psycopg/cursor_type.c index d6776d9d..82ce82f4 100644 --- a/psycopg/cursor_type.c +++ b/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) diff --git a/psycopg/psycopg.h b/psycopg/psycopg.h index 7a7a202b..a689ea45 100644 --- a/psycopg/psycopg.h +++ b/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 diff --git a/psycopg/psycopgmodule.c b/psycopg/psycopgmodule.c index 58a57f99..4e4c546a 100644 --- a/psycopg/psycopgmodule.c +++ b/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