From ee7c5bf159e7a0650ec2b1b6c8d7d8d0434b27a9 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Fri, 8 Jun 2012 16:00:17 -0400 Subject: [PATCH] Add some `Sphinx` paragraph level versions informations markups, such as ``.. versionadded::``, ``.. versionchanged::`` and ``.. deprecated::``. --- .../databases/information_schema.py | 3 ++- lib/sqlalchemy/databases/oracle.py | 21 ++++++++++++------- lib/sqlalchemy/engine/__init__.py | 4 +++- lib/sqlalchemy/ext/compiler.py | 5 ++++- lib/sqlalchemy/ext/sqlsoup.py | 7 +++++++ lib/sqlalchemy/orm/__init__.py | 6 ++++-- lib/sqlalchemy/orm/interfaces.py | 9 ++++---- lib/sqlalchemy/orm/session.py | 6 ++++-- lib/sqlalchemy/sql/expression.py | 6 ++++-- 9 files changed, 47 insertions(+), 20 deletions(-) diff --git a/lib/sqlalchemy/databases/information_schema.py b/lib/sqlalchemy/databases/information_schema.py index a7d4101cdb..8cad7cb24a 100644 --- a/lib/sqlalchemy/databases/information_schema.py +++ b/lib/sqlalchemy/databases/information_schema.py @@ -1,7 +1,8 @@ """ information schema implementation. -This module is deprecated and will not be present in this form in SQLAlchemy 0.6. +.. deprecated:: + This module is deprecated and will not be present in this form in SQLAlchemy 0.6. """ from sqlalchemy import util diff --git a/lib/sqlalchemy/databases/oracle.py b/lib/sqlalchemy/databases/oracle.py index 86c19aca42..a5ca663810 100644 --- a/lib/sqlalchemy/databases/oracle.py +++ b/lib/sqlalchemy/databases/oracle.py @@ -92,13 +92,20 @@ of LOB objects, can be disabled using auto_convert_lobs=False. LIMIT/OFFSET Support -------------------- -Oracle has no support for the LIMIT or OFFSET keywords. Whereas previous versions of SQLAlchemy -used the "ROW NUMBER OVER..." construct to simulate LIMIT/OFFSET, SQLAlchemy 0.5 now uses -a wrapped subquery approach in conjunction with ROWNUM. The exact methodology is taken from -http://www.oracle.com/technology/oramag/oracle/06-sep/o56asktom.html . Note that the -"FIRST ROWS()" optimization keyword mentioned is not used by default, as the user community felt -this was stepping into the bounds of optimization that is better left on the DBA side, but this -prefix can be added by enabling the optimize_limits=True flag on create_engine(). +Oracle has no support for the LIMIT or OFFSET keywords. + +.. versionchanged:: 0.5 + Whereas previous versions of SQLAlchemy used the "ROW NUMBER OVER..." + construct to simulate LIMIT/OFFSET, SQLAlchemy 0.5 now uses + a wrapped subquery approach in conjunction with ROWNUM. + The exact methodology is taken from + http://www.oracle.com/technology/oramag/oracle/06-sep/o56asktom.html . + Note that the + "FIRST ROWS()" optimization keyword mentioned is not used by default, + as the user community felt this was stepping into the bounds + of optimization that is better left on the DBA side, but this + prefix can be added by enabling the optimize_limits=True flag + on create_engine(). Two Phase Transaction Support ----------------------------- diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py index bb2b1b5be4..c601ef6caa 100644 --- a/lib/sqlalchemy/engine/__init__.py +++ b/lib/sqlalchemy/engine/__init__.py @@ -124,7 +124,9 @@ def create_engine(*args, **kwargs): parameters are instances of ``unicode``, otherwise raises an error. Only takes effect when ``convert_unicode==True``. This flag is also available on the ``String`` type and its - descendants. New in 0.4.2. + descendants. + + .. versionadded:: 0.4.2 :param connect_args: a dictionary of options which will be passed directly to the DBAPI's ``connect()`` method as diff --git a/lib/sqlalchemy/ext/compiler.py b/lib/sqlalchemy/ext/compiler.py index 9fb7fd7120..5e9a17fcbc 100644 --- a/lib/sqlalchemy/ext/compiler.py +++ b/lib/sqlalchemy/ext/compiler.py @@ -60,7 +60,7 @@ Compiling sub-elements of a custom expression construct The ``compiler`` argument is the :class:`~sqlalchemy.engine.base.Compiled` object in use. This object can be inspected for any information about the in-progress compilation, including ``compiler.dialect``, ``compiler.statement`` etc. -The :class:`~sqlalchemy.sql.compiler.SQLCompiler` and :class:`~sqlalchemy.sql.compiler.DDLCompiler` (DDLCompiler is 0.6. only) +The :class:`~sqlalchemy.sql.compiler.SQLCompiler` and :class:`~sqlalchemy.sql.compiler.DDLCompiler` both include a ``process()`` method which can be used for compilation of embedded attributes:: class InsertFromSelect(ClauseElement): @@ -82,6 +82,9 @@ Produces:: "INSERT INTO mytable (SELECT mytable.x, mytable.y, mytable.z FROM mytable WHERE mytable.x > :x_1)" +.. versionadded:: 0.6 + :class:`~sqlalchemy.sql.compiler.DDLCompiler`\ . + Changing the default compilation of existing constructs ======================================================= diff --git a/lib/sqlalchemy/ext/sqlsoup.py b/lib/sqlalchemy/ext/sqlsoup.py index b3f2de743e..1ed3ce459a 100644 --- a/lib/sqlalchemy/ext/sqlsoup.py +++ b/lib/sqlalchemy/ext/sqlsoup.py @@ -1,4 +1,11 @@ """ +.. versionchanged:: 0.8 + SQLSoup is now its own project. Documentation + and project status are available at: + http://pypi.python.org/pypi/sqlsoup and + http://readthedocs.org/docs/sqlsoup\ . + SQLSoup will no longer be included with SQLAlchemy. + Introduction ============ diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py index 357859b546..96ae9364bf 100644 --- a/lib/sqlalchemy/orm/__init__.py +++ b/lib/sqlalchemy/orm/__init__.py @@ -398,8 +398,10 @@ def relation(argument, secondary=None, **kwargs): This is used for many-to-one or many-to-many relationships that should be treated either as one-to-one or one-to-many. Its usage is optional unless delete-orphan cascade is also - set on this relation(), in which case its required (new in 0.5.2). - + set on this relation(), in which case its required. + + .. versionadded:: 0.5.2 + :param uselist=(True|False): a boolean that indicates if this property should be loaded as a list or a scalar. In most cases, this value is determined diff --git a/lib/sqlalchemy/orm/interfaces.py b/lib/sqlalchemy/orm/interfaces.py index a145c865dc..366ff8353b 100644 --- a/lib/sqlalchemy/orm/interfaces.py +++ b/lib/sqlalchemy/orm/interfaces.py @@ -154,10 +154,11 @@ class MapperExtension(object): instance population will not proceed, giving this extension an opportunity to populate the instance itself, if desired. - As of 0.5, most usages of this hook are obsolete. For a - generic "object has been newly created from a row" hook, use - ``reconstruct_instance()``, or the ``@orm.reconstructor`` - decorator. + .. deprecated:: 0.5 + As of 0.5, most usages of this hook are obsolete. For a + generic "object has been newly created from a row" hook, use + ``reconstruct_instance()``, or the ``@orm.reconstructor`` + decorator. """ return EXT_CONTINUE diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index be0821e3b8..7403ad2fc1 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -211,8 +211,10 @@ class SessionTransaction(object): instances behind the scenes, with one ``Transaction`` per ``Engine`` in use. - Direct usage of ``SessionTransaction`` is not necessary as of SQLAlchemy - 0.4; use the ``begin()`` and ``commit()`` methods on ``Session`` itself. + .. versionchanged:: 0.4 + Direct usage of ``SessionTransaction`` is not + necessary; use the ``begin()`` and ``commit()`` + methods on ``Session`` itself. The ``SessionTransaction`` object is **not** thread-safe. diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py index 5a47c4e1eb..d5428d9cc1 100644 --- a/lib/sqlalchemy/sql/expression.py +++ b/lib/sqlalchemy/sql/expression.py @@ -2565,8 +2565,10 @@ class Join(FromClause): select, for columns that are calculated to be "equivalent" based on the join criterion of this :class:`Join`. This will recursively apply to any joins directly nested by this one - as well. This flag is specific to a particular use case - by the ORM and will be deprecated in 0.6. + as well. + + .. deprecated:: 0.6 + This flag is specific to a particular use case by the ORM. :param \**kwargs: all other kwargs are sent to the underlying :func:`select()` function. -- 2.47.2