From 2290b95e6e92a062978bbb2468b3c8ed16323a77 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Sun, 27 Mar 2011 20:38:50 -0400 Subject: [PATCH] - Documented SQLite DATE/TIME/DATETIME types. [ticket:2029] - add "currentmodule" directive to all the dialect type docs to ensure users import from the dialect package, not the "base" module --- CHANGES | 5 +- doc/build/dialects/mssql.rst | 2 + doc/build/dialects/mysql.rst | 2 + doc/build/dialects/oracle.rst | 2 + doc/build/dialects/postgresql.rst | 2 + doc/build/dialects/sqlite.rst | 8 ++ lib/sqlalchemy/dialects/sqlite/base.py | 102 ++++++++++++++++++++++++- 7 files changed, 121 insertions(+), 2 deletions(-) diff --git a/CHANGES b/CHANGES index 53ef46ef53..f1eee3d721 100644 --- a/CHANGES +++ b/CHANGES @@ -133,8 +133,11 @@ CHANGES aren't mistaken for always-hashable, possibly-column arguments. [ticket:2091] -- examples +- documentation + - Documented SQLite DATE/TIME/DATETIME types. + [ticket:2029] +- examples - The Beaker caching example allows a "query_cls" argument to the query_callable() function. [ticket:2090] diff --git a/doc/build/dialects/mssql.rst b/doc/build/dialects/mssql.rst index 658ca8988f..3b67606021 100644 --- a/doc/build/dialects/mssql.rst +++ b/doc/build/dialects/mssql.rst @@ -20,6 +20,8 @@ they originate from :mod:`sqlalchemy.types` or from the local dialect:: Types which are specific to SQL Server, or have SQL Server-specific construction arguments, are as follows: +.. currentmodule:: sqlalchemy.dialects.mssql + .. autoclass:: BIT :members: __init__ :show-inheritance: diff --git a/doc/build/dialects/mysql.rst b/doc/build/dialects/mysql.rst index 8796adb3e3..7c7f8dd3be 100644 --- a/doc/build/dialects/mysql.rst +++ b/doc/build/dialects/mysql.rst @@ -19,6 +19,8 @@ valid with MySQL are importable from the top level dialect:: Types which are specific to MySQL, or have MySQL-specific construction arguments, are as follows: +.. currentmodule:: sqlalchemy.dialects.mysql + .. autoclass:: BIGINT :members: __init__ :show-inheritance: diff --git a/doc/build/dialects/oracle.rst b/doc/build/dialects/oracle.rst index 363cebffd4..d5cd969ea4 100644 --- a/doc/build/dialects/oracle.rst +++ b/doc/build/dialects/oracle.rst @@ -19,6 +19,8 @@ they originate from :mod:`sqlalchemy.types` or from the local dialect:: Types which are specific to Oracle, or have Oracle-specific construction arguments, are as follows: +.. currentmodule:: sqlalchemy.dialects.oracle + .. autoclass:: BFILE :members: __init__ :show-inheritance: diff --git a/doc/build/dialects/postgresql.rst b/doc/build/dialects/postgresql.rst index fe1fcb2f7f..e56c327654 100644 --- a/doc/build/dialects/postgresql.rst +++ b/doc/build/dialects/postgresql.rst @@ -19,6 +19,8 @@ they originate from :mod:`sqlalchemy.types` or from the local dialect:: Types which are specific to PostgreSQL, or have PostgreSQL-specific construction arguments, are as follows: +.. currentmodule:: sqlalchemy.dialects.postgresql + .. autoclass:: ARRAY :members: __init__ :show-inheritance: diff --git a/doc/build/dialects/sqlite.rst b/doc/build/dialects/sqlite.rst index a4e87e1b05..f0810cec2f 100644 --- a/doc/build/dialects/sqlite.rst +++ b/doc/build/dialects/sqlite.rst @@ -15,6 +15,14 @@ they originate from :mod:`sqlalchemy.types` or from the local dialect:: INTEGER, NUMERIC, SMALLINT, TEXT, TIME, TIMESTAMP, \ VARCHAR +.. module:: sqlalchemy.dialects.sqlite + +.. autoclass:: DATETIME + +.. autoclass:: DATE + +.. autoclass:: TIME + Pysqlite -------- diff --git a/lib/sqlalchemy/dialects/sqlite/base.py b/lib/sqlalchemy/dialects/sqlite/base.py index 2597a2e19c..01e9d25be3 100644 --- a/lib/sqlalchemy/dialects/sqlite/base.py +++ b/lib/sqlalchemy/dialects/sqlite/base.py @@ -69,7 +69,6 @@ from sqlalchemy.types import BLOB, BOOLEAN, CHAR, DATE, DATETIME, DECIMAL,\ FLOAT, INTEGER, NUMERIC, SMALLINT, TEXT, TIME,\ TIMESTAMP, VARCHAR - class _DateTimeMixin(object): _reg = None _storage_format = None @@ -81,6 +80,41 @@ class _DateTimeMixin(object): self._storage_format = storage_format class DATETIME(_DateTimeMixin, sqltypes.DateTime): + """Represent a Python datetime object in SQLite using a string. + + The default string storage format is:: + + "%04d-%02d-%02d %02d:%02d:%02d.%06d" % (value.year, + value.month, value.day, + value.hour, value.minute, + value.second, value.microsecond) + + e.g.:: + + 2011-03-15 12:05:57.10558 + + The storage format can be customized to some degree using the + ``storage_format`` and ``regexp`` parameters, such as:: + + import re + from sqlalchemy.dialects.sqlite import DATETIME + + dt = DATETIME( + storage_format="%04d/%02d/%02d %02d-%02d-%02d-%06d", + regexp=re.compile("(\d+)/(\d+)/(\d+) (\d+)-(\d+)-(\d+)(?:-(\d+))?") + ) + + :param storage_format: format string which will be appled to the + tuple ``(value.year, value.month, value.day, value.hour, + value.minute, value.second, value.microsecond)``, given a + Python datetime.datetime() object. + + :param regexp: regular expression which will be applied to + incoming result rows. The resulting match object is appled to + the Python datetime() constructor via ``*map(int, + match_obj.groups(0))``. + """ + _storage_format = "%04d-%02d-%02d %02d:%02d:%02d.%06d" def bind_processor(self, dialect): @@ -110,6 +144,38 @@ class DATETIME(_DateTimeMixin, sqltypes.DateTime): return processors.str_to_datetime class DATE(_DateTimeMixin, sqltypes.Date): + """Represent a Python date object in SQLite using a string. + + The default string storage format is:: + + "%04d-%02d-%02d" % (value.year, value.month, value.day) + + e.g.:: + + 2011-03-15 + + The storage format can be customized to some degree using the + ``storage_format`` and ``regexp`` parameters, such as:: + + import re + from sqlalchemy.dialects.sqlite import DATE + + d = DATE( + storage_format="%02d/%02d/%02d", + regexp=re.compile("(\d+)/(\d+)/(\d+)") + ) + + :param storage_format: format string which will be appled to the + tuple ``(value.year, value.month, value.day)``, + given a Python datetime.date() object. + + :param regexp: regular expression which will be applied to + incoming result rows. The resulting match object is appled to + the Python date() constructor via ``*map(int, + match_obj.groups(0))``. + + """ + _storage_format = "%04d-%02d-%02d" def bind_processor(self, dialect): @@ -133,6 +199,40 @@ class DATE(_DateTimeMixin, sqltypes.Date): return processors.str_to_date class TIME(_DateTimeMixin, sqltypes.Time): + """Represent a Python time object in SQLite using a string. + + The default string storage format is:: + + "%02d:%02d:%02d.%06d" % (value.hour, value.minute, + value.second, + value.microsecond) + + e.g.:: + + 12:05:57.10558 + + The storage format can be customized to some degree using the + ``storage_format`` and ``regexp`` parameters, such as:: + + import re + from sqlalchemy.dialects.sqlite import TIME + + t = TIME( + storage_format="%02d-%02d-%02d-%06d", + regexp=re.compile("(\d+)-(\d+)-(\d+)-(?:-(\d+))?") + ) + + :param storage_format: format string which will be appled + to the tuple ``(value.hour, value.minute, value.second, + value.microsecond)``, given a Python datetime.time() object. + + :param regexp: regular expression which will be applied to + incoming result rows. The resulting match object is appled to + the Python time() constructor via ``*map(int, + match_obj.groups(0))``. + + """ + _storage_format = "%02d:%02d:%02d.%06d" def bind_processor(self, dialect): -- 2.47.3