From: Mike Bayer Date: Tue, 13 Jan 2009 18:00:28 +0000 (+0000) Subject: our likely approach towards documentation of generic driver + dbapi driver X-Git-Tag: rel_0_6_6~344 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=19c1c44a40303f68a895d1f17676377dd83f01e8;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git our likely approach towards documentation of generic driver + dbapi driver --- diff --git a/doc/build/reference/dialects/postgres.rst b/doc/build/reference/dialects/postgres.rst index 7cf072383e..892db0a863 100644 --- a/doc/build/reference/dialects/postgres.rst +++ b/doc/build/reference/dialects/postgres.rst @@ -1,4 +1,9 @@ PostgreSQL ========== -.. automodule:: sqlalchemy.databases.postgres +.. automodule:: sqlalchemy.dialects.postgres.base + +psycopg2 Notes +-------------- + +.. automodule:: sqlalchemy.dialects.postgres.psycopg2 diff --git a/doc/build/reference/dialects/sqlite.rst b/doc/build/reference/dialects/sqlite.rst index 118c239b1d..8361876c38 100644 --- a/doc/build/reference/dialects/sqlite.rst +++ b/doc/build/reference/dialects/sqlite.rst @@ -1,5 +1,9 @@ SQLite ====== -.. automodule:: sqlalchemy.databases.sqlite +.. automodule:: sqlalchemy.dialects.sqlite.base +Pysqlite +-------- + +.. automodule:: sqlalchemy.dialects.sqlite.pysqlite \ No newline at end of file diff --git a/doc/build/reference/sqlalchemy/connections.rst b/doc/build/reference/sqlalchemy/connections.rst index 2f861816c3..394fa864ce 100644 --- a/doc/build/reference/sqlalchemy/connections.rst +++ b/doc/build/reference/sqlalchemy/connections.rst @@ -65,7 +65,3 @@ Internals .. autoclass:: ExecutionContext :members: -.. autoclass:: SchemaIterator - :members: - :show-inheritance: - diff --git a/lib/sqlalchemy/dialects/postgres/base.py b/lib/sqlalchemy/dialects/postgres/base.py index d33a6db935..e9672eddf7 100644 --- a/lib/sqlalchemy/dialects/postgres/base.py +++ b/lib/sqlalchemy/dialects/postgres/base.py @@ -4,6 +4,65 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php +"""Support for the PostgreSQL database. + +For information on connecting using specific drivers, see the documentation section +regarding that driver. + +Sequences/SERIAL +---------------- + +Postgres supports sequences, and SQLAlchemy uses these as the default means of creating +new primary key values for integer-based primary key columns. When creating tables, +SQLAlchemy will issue the ``SERIAL`` datatype for integer-based primary key columns, +which generates a sequence corresponding to the column and associated with it based on +a naming convention. + +To specify a specific named sequence to be used for primary key generation, use the +:func:`~sqlalchemy.schema.Sequence` construct:: + + Table('sometable', metadata, + Column('id', Integer, Sequence('some_id_seq'), primary_key=True) + ) + +Currently, when SQLAlchemy issues a single insert statement, to fulfill the contract of +having the "last insert identifier" available, the sequence is executed independently +beforehand and the new value is retrieved, to be used in the subsequent insert. Note +that when an :func:`~sqlalchemy.sql.expression.insert()` construct is executed using +"executemany" semantics, the sequence is not pre-executed and normal PG SERIAL behavior +is used. + +Postgres 8.3 supports an ``INSERT...RETURNING`` syntax which SQLAlchemy supports +as well. A future release of SQLA will use this feature by default in lieu of +sequence pre-execution in order to retrieve new primary key values, when available. + +INSERT/UPDATE...RETURNING +------------------------- + +The dialect supports PG 8.3's ``INSERT..RETURNING`` and ``UPDATE..RETURNING`` syntaxes, +but must be explicitly enabled on a per-statement basis:: + + # INSERT..RETURNING + result = table.insert(postgres_returning=[table.c.col1, table.c.col2]).\\ + values(name='foo') + print result.fetchall() + + # UPDATE..RETURNING + result = table.update(postgres_returning=[table.c.col1, table.c.col2]).\\ + where(table.c.name=='foo').values(name='bar') + print result.fetchall() + +Indexes +------- + +PostgreSQL supports partial indexes. To create them pass a postgres_where +option to the Index constructor:: + + Index('my_index', my_table.c.id, postgres_where=tbl.c.value > 10) + + + +""" import decimal, random, re, string diff --git a/lib/sqlalchemy/dialects/postgres/psycopg2.py b/lib/sqlalchemy/dialects/postgres/psycopg2.py index 5cda71bb55..bd0815a3f3 100644 --- a/lib/sqlalchemy/dialects/postgres/psycopg2.py +++ b/lib/sqlalchemy/dialects/postgres/psycopg2.py @@ -24,57 +24,6 @@ psycopg2-specific keyword arguments which are accepted by :func:`~sqlalchemy.cre uses special row-buffering behavior when this feature is enabled, such that groups of 100 rows at a time are fetched over the wire to reduce conversational overhead. -Sequences/SERIAL ----------------- - -Postgres supports sequences, and SQLAlchemy uses these as the default means of creating -new primary key values for integer-based primary key columns. When creating tables, -SQLAlchemy will issue the ``SERIAL`` datatype for integer-based primary key columns, -which generates a sequence corresponding to the column and associated with it based on -a naming convention. - -To specify a specific named sequence to be used for primary key generation, use the -:func:`~sqlalchemy.schema.Sequence` construct:: - - Table('sometable', metadata, - Column('id', Integer, Sequence('some_id_seq'), primary_key=True) - ) - -Currently, when SQLAlchemy issues a single insert statement, to fulfill the contract of -having the "last insert identifier" available, the sequence is executed independently -beforehand and the new value is retrieved, to be used in the subsequent insert. Note -that when an :func:`~sqlalchemy.sql.expression.insert()` construct is executed using -"executemany" semantics, the sequence is not pre-executed and normal PG SERIAL behavior -is used. - -Postgres 8.3 supports an ``INSERT...RETURNING`` syntax which SQLAlchemy supports -as well. A future release of SQLA will use this feature by default in lieu of -sequence pre-execution in order to retrieve new primary key values, when available. - -INSERT/UPDATE...RETURNING -------------------------- - -The dialect supports PG 8.3's ``INSERT..RETURNING`` and ``UPDATE..RETURNING`` syntaxes, -but must be explicitly enabled on a per-statement basis:: - - # INSERT..RETURNING - result = table.insert(postgres_returning=[table.c.col1, table.c.col2]).\\ - values(name='foo') - print result.fetchall() - - # UPDATE..RETURNING - result = table.update(postgres_returning=[table.c.col1, table.c.col2]).\\ - where(table.c.name=='foo').values(name='bar') - print result.fetchall() - -Indexes -------- - -PostgreSQL supports partial indexes. To create them pass a postgres_where -option to the Index constructor:: - - Index('my_index', my_table.c.id, postgres_where=tbl.c.value > 10) - Transactions ------------ diff --git a/lib/sqlalchemy/dialects/sqlite/base.py b/lib/sqlalchemy/dialects/sqlite/base.py index a080b94ec0..d716a58ec4 100644 --- a/lib/sqlalchemy/dialects/sqlite/base.py +++ b/lib/sqlalchemy/dialects/sqlite/base.py @@ -3,6 +3,25 @@ # # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php +"""Support for the SQLite database. + +For information on connecting using a specific driver, see the documentation +section regarding that driver. + +Date and Time Types +------------------- + +SQLite does not have built-in DATE, TIME, or DATETIME types, and pysqlite does not provide +out of the box functionality for translating values between Python `datetime` objects +and a SQLite-supported format. SQLAlchemy's own :class:`~sqlalchemy.types.DateTime` +and related types provide date formatting and parsing functionality when SQlite is used. +The implementation classes are :class:`SLDateTime`, :class:`SLDate` and :class:`SLTime`. +These types represent dates and times as ISO formatted strings, which also nicely +support ordering. There's no reliance on typical "libc" internals for these functions +so historical dates are fully supported. + + +""" import datetime, re, time diff --git a/lib/sqlalchemy/dialects/sqlite/pysqlite.py b/lib/sqlalchemy/dialects/sqlite/pysqlite.py index 55ac8bd27b..b00f9e7a00 100644 --- a/lib/sqlalchemy/dialects/sqlite/pysqlite.py +++ b/lib/sqlalchemy/dialects/sqlite/pysqlite.py @@ -1,5 +1,8 @@ """Support for the SQLite database via pysqlite. +Note that pysqlite is the same driver as the ``sqlite3`` +module included with the Python distribution. + Driver ------ @@ -86,18 +89,6 @@ Two optional pool implementations that may be appropriate for particular SQLite of :class:`SingletonThreadPool`. NullPool will of course render a ``:memory:`` connection useless since the database would be lost as soon as the connection is "returned" to the pool. -Date and Time Types -------------------- - -SQLite does not have built-in DATE, TIME, or DATETIME types, and pysqlite does not provide -out of the box functionality for translating values between Python `datetime` objects -and a SQLite-supported format. SQLAlchemy's own :class:`~sqlalchemy.types.DateTime` -and related types provide date formatting and parsing functionality when SQlite is used. -The implementation classes are :class:`SLDateTime`, :class:`SLDate` and :class:`SLTime`. -These types represent dates and times as ISO formatted strings, which also nicely -support ordering. There's no reliance on typical "libc" internals for these functions -so historical dates are fully supported. - Unicode -------