From 38cb8b367bfb8b6b4e70503a91af6c63c7e39b1a Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Fri, 8 Jun 2012 16:00:03 -0400 Subject: [PATCH] Add some `Sphinx` paragraph level versions informations markups, such as ``.. versionadded::``, ``.. versionchanged::`` and ``.. deprecated::``. --- lib/sqlalchemy/dialects/oracle/base.py | 10 +++--- lib/sqlalchemy/dialects/oracle/cx_oracle.py | 14 +++++--- lib/sqlalchemy/dialects/postgresql/base.py | 4 ++- lib/sqlalchemy/engine/base.py | 4 +-- lib/sqlalchemy/ext/declarative.py | 15 ++++---- lib/sqlalchemy/ext/sqlsoup.py | 24 +++++++++---- lib/sqlalchemy/orm/__init__.py | 38 +++++++++++---------- lib/sqlalchemy/orm/interfaces.py | 9 ++--- lib/sqlalchemy/orm/query.py | 14 ++++---- lib/sqlalchemy/orm/session.py | 6 ++-- lib/sqlalchemy/orm/util.py | 11 +++--- lib/sqlalchemy/schema.py | 3 +- 12 files changed, 91 insertions(+), 61 deletions(-) diff --git a/lib/sqlalchemy/dialects/oracle/base.py b/lib/sqlalchemy/dialects/oracle/base.py index a35925f83a..d5234a2844 100644 --- a/lib/sqlalchemy/dialects/oracle/base.py +++ b/lib/sqlalchemy/dialects/oracle/base.py @@ -63,10 +63,12 @@ used on the SQLAlchemy side. Unicode ------- -SQLAlchemy 0.6 uses the "native unicode" mode provided as of cx_oracle 5. cx_oracle 5.0.2 -or greater is recommended for support of NCLOB. If not using cx_oracle 5, the NLS_LANG -environment variable needs to be set in order for the oracle client library to use -proper encoding, such as "AMERICAN_AMERICA.UTF8". +.. versionadded:: 0.6 + SQLAlchemy 0.6 uses the "native unicode" mode provided as of cx_oracle 5. + cx_oracle 5.0.2 or greater is recommended for support of NCLOB. + If not using cx_oracle 5, the NLS_LANG environment variable needs to be + set in order for the oracle client library to use + proper encoding, such as "AMERICAN_AMERICA.UTF8". Also note that Oracle supports unicode data through the NVARCHAR and NCLOB data types. When using the SQLAlchemy Unicode and UnicodeText types, these DDL types will be used diff --git a/lib/sqlalchemy/dialects/oracle/cx_oracle.py b/lib/sqlalchemy/dialects/oracle/cx_oracle.py index eac3ac7b95..c04c72194f 100644 --- a/lib/sqlalchemy/dialects/oracle/cx_oracle.py +++ b/lib/sqlalchemy/dialects/oracle/cx_oracle.py @@ -54,6 +54,9 @@ handler so that all string based result values are returned as unicode as well. Note that this behavior is disabled when Oracle 8 is detected, as it has been observed that issues remain when passing Python unicodes to cx_oracle with Oracle 8. +.. versionchanged:: 0.6 + Use of native unicode mode provided as of cx_oracle 5. + LOB Objects ----------- @@ -111,10 +114,13 @@ environment variable. Upon first connection, the dialect runs a test to determine the current "decimal" character, which can be a comma "," for european locales. From that point forward the outputtypehandler uses that character to represent a decimal -point (this behavior is new in version 0.6.6). Note that -cx_oracle 5.0.3 or greater is required when dealing with -numerics with locale settings that don't use a period "." as the -decimal character. +point. Note that cx_oracle 5.0.3 or greater is required +when dealing with numerics with locale settings that don't use +a period "." as the decimal character. + +.. versionchanged:: 0.6.6 + The outputtypehandler uses a comma "," character to represent + a decimal point. .. _OCI: http://www.oracle.com/technetwork/database/features/oci/index.html diff --git a/lib/sqlalchemy/dialects/postgresql/base.py b/lib/sqlalchemy/dialects/postgresql/base.py index bbb270f763..8336654e89 100644 --- a/lib/sqlalchemy/dialects/postgresql/base.py +++ b/lib/sqlalchemy/dialects/postgresql/base.py @@ -281,7 +281,9 @@ class ARRAY(sqltypes.MutableType, sqltypes.Concatenable, sqltypes.TypeEngine): :param as_tuple=False: Specify whether return results should be converted to tuples from lists. DBAPIs such as psycopg2 return lists by default. When tuples are returned, the results are hashable. This flag can only - be set to ``True`` when ``mutable`` is set to ``False``. (new in 0.6.5) + be set to ``True`` when ``mutable`` is set to ``False``. + + .. versionadded:: 0.6.5 """ if isinstance(item_type, ARRAY): diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index ebe21235ce..c1be4f237b 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -2330,7 +2330,7 @@ class ResultProxy(object): :meth:`~.ResultProxy.fetchmany` :meth:`~.ResultProxy.fetchall`. - New in 0.6.7. + .. versionadded:: 0.6.7 """ return self._metadata is not None @@ -2346,7 +2346,7 @@ class ResultProxy(object): assuming the statement did not include a user defined "returning" construct. - New in 0.6.7. + .. versionadded:: 0.6.7 """ return self.context.isinsert diff --git a/lib/sqlalchemy/ext/declarative.py b/lib/sqlalchemy/ext/declarative.py index c75d229277..05c626a812 100755 --- a/lib/sqlalchemy/ext/declarative.py +++ b/lib/sqlalchemy/ext/declarative.py @@ -595,8 +595,7 @@ keys, as a :class:`ForeignKey` itself contains references to columns which can't be properly recreated at this level. For columns that have foreign keys, as well as for the variety of mapper-level constructs that require destination-explicit context, the -:func:`~.declared_attr` decorator (renamed from ``sqlalchemy.util.classproperty`` in 0.6.5) -is provided so that +:func:`~.declared_attr` decorator is provided so that patterns common to many classes can be defined as callables:: from sqlalchemy.ext.declarative import declared_attr @@ -615,6 +614,9 @@ point at which the ``User`` class is constructed, and the declarative extension can use the resulting :class:`Column` object as returned by the method without the need to copy it. +.. versionchanged:: > 0.6.5 + Rename 0.6.5 ``sqlalchemy.util.classproperty`` into :func:`~.declared_attr`. + Columns generated by :func:`~.declared_attr` can also be referenced by ``__mapper_args__`` to a limited degree, currently by ``polymorphic_on`` and ``version_id_col``, by specifying the @@ -1306,11 +1308,10 @@ class declared_attr(property): """Mark a class-level method as representing the definition of a mapped property or special declarative member name. - .. note:: - - @declared_attr is available as - ``sqlalchemy.util.classproperty`` for SQLAlchemy versions - 0.6.2, 0.6.3, 0.6.4. + .. versionchanged:: 0.6.{2,3,4} + ``@declared_attr`` is available as + ``sqlalchemy.util.classproperty`` for SQLAlchemy versions + 0.6.2, 0.6.3, 0.6.4. @declared_attr turns the attribute into a scalar-like property that can be invoked from the uninstantiated class. diff --git a/lib/sqlalchemy/ext/sqlsoup.py b/lib/sqlalchemy/ext/sqlsoup.py index b22e26e080..5cff143455 100644 --- a/lib/sqlalchemy/ext/sqlsoup.py +++ b/lib/sqlalchemy/ext/sqlsoup.py @@ -5,6 +5,13 @@ # the MIT License: http://www.opensource.org/licenses/mit-license.php """ +.. 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 ============ @@ -625,7 +632,7 @@ class SqlSoup(object): This is the "master" method that can be used to create any configuration. - (new in 0.6.6) + .. versionadded:: 0.6.6 :param attrname: String attribute name which will be established as an attribute on this :class:.`.SqlSoup` @@ -706,8 +713,9 @@ class SqlSoup(object): def map(self, selectable, base=None, **mapper_args): """Map a selectable directly. - The class and its mapping are not cached and will - be discarded once dereferenced (as of 0.6.6). + .. versionchanged:: 0.6.6 + The class and its mapping are not cached and will + be discarded once dereferenced. :param selectable: an :func:`.expression.select` construct. :param base: a Python class which will be used as the @@ -732,8 +740,9 @@ class SqlSoup(object): """Map a selectable directly, wrapping the selectable in a subquery with labels. - The class and its mapping are not cached and will - be discarded once dereferenced (as of 0.6.6). + .. versionchanged:: 0.6.6 + The class and its mapping are not cached and will + be discarded once dereferenced. :param selectable: an :func:`.expression.select` construct. :param base: a Python class which will be used as the @@ -756,8 +765,9 @@ class SqlSoup(object): base=None, **mapper_args): """Create an :func:`.expression.join` and map to it. - The class and its mapping are not cached and will - be discarded once dereferenced (as of 0.6.6). + .. versionchanged:: 0.6.6 + The class and its mapping are not cached and will + be discarded once dereferenced. :param left: a mapped class or table object. :param right: a mapped class or table object. diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py index 3a837e1821..854f9c2f05 100644 --- a/lib/sqlalchemy/orm/__init__.py +++ b/lib/sqlalchemy/orm/__init__.py @@ -182,10 +182,8 @@ def create_session(bind=None, **kwargs): def relationship(argument, secondary=None, **kwargs): """Provide a relationship of a primary Mapper to a secondary Mapper. - .. note:: - - :func:`relationship` is historically known as - :func:`relation` prior to version 0.6. + .. versionchanged:: 0.6 + :func:`relationship` is historically known as :func:`relation`. This corresponds to a parent-child or associative table relationship. The constructed class is an instance of :class:`RelationshipProperty`. @@ -216,7 +214,9 @@ def relationship(argument, secondary=None, **kwargs): value in order to perform a flush. This flag is available for applications that make use of :func:`.attributes.get_history` which also need to know - the "previous" value of the attribute. (New in 0.6.6) + the "previous" value of the attribute. + + .. versionadded:: 0.6.6 :param backref: indicates the string name of a property to be placed on the related @@ -295,7 +295,7 @@ def relationship(argument, secondary=None, **kwargs): ) }) - ``cascade_backrefs`` is new in 0.6.5. + .. versionadded:: 0.6.5 :param collection_class: a class or callable that returns a new list-holding object. will @@ -369,7 +369,9 @@ def relationship(argument, secondary=None, **kwargs): * ``immediate`` - items should be loaded as the parents are loaded, using a separate SELECT statement, or identity map fetch for - simple many-to-one references. (new as of 0.6.5) + simple many-to-one references. + + .. versionadded:: 0.6.5 * ``joined`` - items should be loaded "eagerly" in the same query as that of the parent, using a JOIN or LEFT OUTER JOIN. Whether @@ -623,7 +625,9 @@ def column_property(*args, **kwargs): aware of the "new" value in order to perform a flush. This flag is available for applications that make use of :func:`.attributes.get_history` which also need to know - the "previous" value of the attribute. (new in 0.6.6) + the "previous" value of the attribute. + + .. versionadded:: 0.6.6 :param comparator_factory: a class which extends :class:`.ColumnProperty.Comparator` which provides custom SQL clause @@ -1057,12 +1061,11 @@ def joinedload(*keys, **kw): """Return a ``MapperOption`` that will convert the property of the given name into an joined eager load. - .. note:: - - This function is known as :func:`eagerload` in all versions - of SQLAlchemy prior to version 0.6beta3, including the 0.5 and 0.4 - series. :func:`eagerload` will remain available for the foreseeable - future in order to enable cross-compatibility. + .. versionchanged:: 0.6beta3 + This function is known as :func:`eagerload` in all versions + of SQLAlchemy prior to version 0.6beta3, including the 0.5 and 0.4 + series. :func:`eagerload` will remain available for the foreseeable + future in order to enable cross-compatibility. Used with :meth:`~sqlalchemy.orm.query.Query.options`. @@ -1114,8 +1117,7 @@ def joinedload_all(*keys, **kw): """Return a ``MapperOption`` that will convert all properties along the given dot-separated path into an joined eager load. - .. note:: - + .. versionchanged:: 0.6beta3 This function is known as :func:`eagerload_all` in all versions of SQLAlchemy prior to version 0.6beta3, including the 0.5 and 0.4 series. :func:`eagerload_all` will remain available for the @@ -1236,7 +1238,7 @@ def immediateload(*keys): See also: :func:`lazyload`, :func:`eagerload`, :func:`subqueryload` - New as of verison 0.6.5. + .. versionadded:: 0.6.5 """ return strategies.EagerLazyOption(keys, lazy='immediate') @@ -1325,4 +1327,4 @@ def undefer_group(name): return strategies.UndeferGroupOption(name) from sqlalchemy import util as _sa_util -_sa_util.importlater.resolve_all() \ No newline at end of file +_sa_util.importlater.resolve_all() diff --git a/lib/sqlalchemy/orm/interfaces.py b/lib/sqlalchemy/orm/interfaces.py index 646e69a897..b247f793a2 100644 --- a/lib/sqlalchemy/orm/interfaces.py +++ b/lib/sqlalchemy/orm/interfaces.py @@ -206,10 +206,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/query.py b/lib/sqlalchemy/orm/query.py index 57bffcaaa1..1dccc2bcb7 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -462,7 +462,7 @@ class Query(object): Analogous to :meth:`sqlalchemy.sql._SelectBaseMixin.label`. - New in 0.6.5. + .. versionadded:: 0.6.5 """ @@ -475,7 +475,7 @@ class Query(object): Analogous to :meth:`sqlalchemy.sql._SelectBaseMixin.as_scalar`. - New in 0.6.5. + .. versionadded:: 0.6.5 """ @@ -878,7 +878,7 @@ class Query(object): q = q.join((subq, subq.c.email < Address.email)).\\ limit(1) - New in 0.6.5. + .. versionadded:: 0.6.5 """ self._set_entities(entities) @@ -1725,9 +1725,11 @@ class Query(object): unique entity or entities - this is a successful result for one(). Calling ``one()`` results in an execution of the underlying query. - As of 0.6, ``one()`` fully fetches all results instead of applying - any kind of limit, so that the "unique"-ing of entities does not - conceal multiple object identities. + + .. versionchanged:: 0.6 + ``one()`` fully fetches all results instead of applying + any kind of limit, so that the "unique"-ing of entities does not + conceal multiple object identities. """ ret = list(self) diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index 2b2062834b..14a3a936d8 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -199,8 +199,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/orm/util.py b/lib/sqlalchemy/orm/util.py index ce0e923a3d..419426e832 100644 --- a/lib/sqlalchemy/orm/util.py +++ b/lib/sqlalchemy/orm/util.py @@ -491,11 +491,12 @@ def with_parent(instance, prop): Python without the need to render joins to the parent table in the rendered statement. - As of 0.6.4, this method accepts parent instances in all - persistence states, including transient, persistent, and detached. - Only the requisite primary key/foreign key attributes need to - be populated. Previous versions didn't work with transient - instances. + .. versionchanged:: 0.6.4 + This method accepts parent instances in all + persistence states, including transient, persistent, and detached. + Only the requisite primary key/foreign key attributes need to + be populated. Previous versions didn't work with transient + instances. :param instance: An instance which has some :func:`.relationship`. diff --git a/lib/sqlalchemy/schema.py b/lib/sqlalchemy/schema.py index cdbaff83fa..6bcf4205be 100644 --- a/lib/sqlalchemy/schema.py +++ b/lib/sqlalchemy/schema.py @@ -1529,7 +1529,8 @@ class DefaultClause(FetchedValue): class PassiveDefault(DefaultClause): """A DDL-specified DEFAULT column value. - .. deprecated:: 0.6 :class:`.PassiveDefault` is deprecated. + .. deprecated:: 0.6 + :class:`.PassiveDefault` is deprecated. Use :class:`.DefaultClause`. """ @util.deprecated("0.6", -- 2.47.3