From d8d080a76913af5d192c5ef627b8453c05d0e2c8 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Fri, 8 Jun 2012 15:56:58 -0400 Subject: [PATCH] Add some `Sphinx` related version informations paragraph-level markups, such as ``.. versionaddedd::``, ``.. versionchanged::`` and ``.. deprecated::``. --- doc/build/core/connections.rst | 2 +- doc/build/core/event.rst | 8 +++++--- doc/build/core/events.rst | 12 +++++++----- doc/build/core/interfaces.rst | 7 ++++--- doc/build/core/schema.rst | 6 +++++- doc/build/core/tutorial.rst | 4 +--- doc/build/orm/events.rst | 7 +++++-- doc/build/orm/extensions/associationproxy.rst | 13 ++++++++++--- doc/build/orm/inheritance.rst | 14 +++++++++----- doc/build/orm/interfaces.rst | 7 ++++--- doc/build/orm/loading.rst | 5 ++--- doc/build/orm/mapper_config.rst | 14 ++++++++++---- doc/build/orm/relationships.rst | 5 ++++- 13 files changed, 67 insertions(+), 37 deletions(-) diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst index 647accd845..cf0625b53f 100644 --- a/doc/build/core/connections.rst +++ b/doc/build/core/connections.rst @@ -411,7 +411,7 @@ the need for separate installation. Use the ``register()`` function as follows The above will respond to ``create_engine("mysql+foodialect://")`` and load the ``MyMySQLDialect`` class from the ``myapp.dialect`` module. -The ``register()`` function is new in SQLAlchemy 0.8. +.. versionadded:: 0.8 Connection / Engine API ======================= diff --git a/doc/build/core/event.rst b/doc/build/core/event.rst index 68d4802bc5..f3433876c2 100644 --- a/doc/build/core/event.rst +++ b/doc/build/core/event.rst @@ -4,9 +4,11 @@ Events ====== SQLAlchemy includes an event API which publishes a wide variety of hooks into -the internals of both SQLAlchemy Core and ORM. The system is all new -as of version 0.7 and supercedes the previous system of "extension", "proxy", -and "listener" classes. +the internals of both SQLAlchemy Core and ORM. + +.. versionadded:: 0.7 + The system supercedes the previous system of "extension", "proxy", + and "listener" classes. Event Registration ------------------ diff --git a/doc/build/core/events.rst b/doc/build/core/events.rst index fe8a45de51..fab7356c46 100644 --- a/doc/build/core/events.rst +++ b/doc/build/core/events.rst @@ -4,11 +4,13 @@ Core Events ============ This section describes the event interfaces provided in -SQLAlchemy Core. The event system in 0.7 is all new and -supercedes the previous system of "extension", "listener", and -"proxy" classes. For an introduction to the event listening API, -see :ref:`event_toplevel`. ORM events are described in -:ref:`orm_event_toplevel`. +SQLAlchemy Core. +For an introduction to the event listening API, see :ref:`event_toplevel`. +ORM events are described in :ref:`orm_event_toplevel`. + +.. versionadded:: 0.7 + The event system supercedes the previous system of "extension", "listener", + and "proxy" classes. Connection Pool Events ----------------------- diff --git a/doc/build/core/interfaces.rst b/doc/build/core/interfaces.rst index fac26018ce..7e76127f4d 100644 --- a/doc/build/core/interfaces.rst +++ b/doc/build/core/interfaces.rst @@ -8,9 +8,10 @@ Deprecated Event Interfaces This section describes the class-based core event interface introduced in SQLAlchemy 0.5. The ORM analogue is described at :ref:`dep_interfaces_orm_toplevel`. -As of SQLAlchemy 0.7, the new event system described in -:ref:`event_toplevel` replaces the extension/proxy/listener system, providing -a consistent interface to all events without the need for subclassing. +.. deprecated:: 0.7 + The new event system described in :ref:`event_toplevel` replaces + the extension/proxy/listener system, providing a consistent interface + to all events without the need for subclassing. Execution, Connection and Cursor Events --------------------------------------- diff --git a/doc/build/core/schema.rst b/doc/build/core/schema.rst index d1e2c2d78b..ccaa89d0a6 100644 --- a/doc/build/core/schema.rst +++ b/doc/build/core/schema.rst @@ -1180,7 +1180,7 @@ INDEX" is issued right after the create statements for the table: Note in the example above, the :class:`.Index` construct is created externally to the table which it corresponds, using :class:`.Column` -objects directly. As of SQLAlchemy 0.7, :class:`.Index` also supports +objects directly. :class:`.Index` also supports "inline" definition inside the :class:`.Table`, using string names to identify columns:: @@ -1200,6 +1200,10 @@ identify columns:: Index('idx_col34', 'col3', 'col4', unique=True) ) +.. versionadded:: 0.7 + Support of "inline" definition inside the :class:`.Table` + for :class:`.Index`\ . + The :class:`~sqlalchemy.schema.Index` object also supports its own ``create()`` method: .. sourcecode:: python+sql diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst index cbee2cf880..652a2b2dbc 100644 --- a/doc/build/core/tutorial.rst +++ b/doc/build/core/tutorial.rst @@ -1513,9 +1513,7 @@ table, or the same table: Multiple Table Updates ---------------------- -.. note:: - - This feature is new as of version 0.7.4. +.. versionadded:: 0.7.4 The Postgresql, Microsoft SQL Server, and MySQL backends all support UPDATE statements that refer to multiple tables. For PG and MSSQL, this is the "UPDATE FROM" syntax, diff --git a/doc/build/orm/events.rst b/doc/build/orm/events.rst index 45c947ae0e..38cecf689d 100644 --- a/doc/build/orm/events.rst +++ b/doc/build/orm/events.rst @@ -3,8 +3,11 @@ ORM Events ========== -The ORM includes a wide variety of hooks available for subscription. The event -system in 0.7 is all new and supercedes the previous system of "extension" classes. +The ORM includes a wide variety of hooks available for subscription. + +.. versionadded:: 0.7 + The event supercedes the previous system of "extension" classes. + For an introduction to the event API, see :ref:`event_toplevel`. Non-ORM events such as those regarding connections and low-level statement execution are described in :ref:`core_event_toplevel`. diff --git a/doc/build/orm/extensions/associationproxy.rst b/doc/build/orm/extensions/associationproxy.rst index 6db9fe1351..fac1aa429e 100644 --- a/doc/build/orm/extensions/associationproxy.rst +++ b/doc/build/orm/extensions/associationproxy.rst @@ -479,13 +479,16 @@ and ``.contains()`` is available for a proxy to a scalar collection:: AND keyword.keyword = :keyword_1) :class:`.AssociationProxy` can be used with :meth:`.Query.join` somewhat manually -using the :attr:`~.AssociationProxy.attr` attribute in a star-args context (new in 0.7.3):: +using the :attr:`~.AssociationProxy.attr` attribute in a star-args context:: q = session.query(User).join(*User.keywords) +.. versionadded:: 0.7.3 + :attr:`~.AssociationProxy.attr` attribute in a star-args context. + :attr:`~.AssociationProxy.attr` is composed of :attr:`.AssociationProxy.local_attr` and :attr:`.AssociationProxy.remote_attr`, which are just synonyms for the actual proxied attributes, and can also -be used for querying (also new in 0.7.3):: +be used for querying:: uka = aliased(UserKeyword) ka = aliased(Keyword) @@ -493,6 +496,10 @@ be used for querying (also new in 0.7.3):: join(uka, User.keywords.local_attr).\ join(ka, User.keywords.remote_attr) +.. versionadded:: 0.7.3 + :attr:`.AssociationProxy.local_attr` and :attr:`.AssociationProxy.remote_attr`, + synonyms for the actual proxied attributes, and usable for querying. + API Documentation ----------------- @@ -500,4 +507,4 @@ API Documentation .. autoclass:: AssociationProxy :members: - :undoc-members: \ No newline at end of file + :undoc-members: diff --git a/doc/build/orm/inheritance.rst b/doc/build/orm/inheritance.rst index fbddc65794..ba0745065d 100644 --- a/doc/build/orm/inheritance.rst +++ b/doc/build/orm/inheritance.rst @@ -250,9 +250,8 @@ Note that if you only need to load a single subtype, such as just the ``Engineer`` objects, :func:`.orm.with_polymorphic` is not needed since you would query against the ``Engineer`` class directly. -:func:`.orm.with_polymorphic` is new in 0.8 and is an improved -version of the existing :meth:`.Query.with_polymorphic` method. -:meth:`.Query.with_polymorphic` has the same purpose, except is not as +:meth:`.Query.with_polymorphic` has the same purpose +as :func:`.orm.with_polymorphic`, except is not as flexible in its usage patterns in that it only applies to the first full mapping, which then impacts all occurrences of that class or the target subclasses within the :class:`.Query`. For simple cases it might be @@ -261,6 +260,10 @@ considered to be more succinct:: session.query(Employee).with_polymorphic([Engineer, Manager]).\ filter(or_(Engineer.engineer_info=='w', Manager.manager_data=='q')) +.. versionadded:: 0.8 + :func:`.orm.with_polymorphic`, an improved version of + :meth:`.Query.with_polymorphic` method. + The mapper also accepts ``with_polymorphic`` as a configurational argument so that the joined-style load will be issued automatically. This argument may be the string ``'*'``, a list of classes, or a tuple consisting of either, @@ -589,8 +592,9 @@ Upon select, the polymorphic union produces a query like this: Concrete Inheritance with Declarative ++++++++++++++++++++++++++++++++++++++ -As of 0.7.3, the :ref:`declarative_toplevel` module includes helpers for concrete inheritance. -See :ref:`declarative_concrete_helpers` for more information. +.. versionadded:: 0.7.3 + The :ref:`declarative_toplevel` module includes helpers for concrete + inheritance. See :ref:`declarative_concrete_helpers` for more information. Using Relationships with Inheritance ------------------------------------ diff --git a/doc/build/orm/interfaces.rst b/doc/build/orm/interfaces.rst index 0df54cfdac..9430597470 100644 --- a/doc/build/orm/interfaces.rst +++ b/doc/build/orm/interfaces.rst @@ -9,9 +9,10 @@ This section describes the class-based ORM event interface which first existed in SQLAlchemy 0.1, which progressed with more kinds of events up until SQLAlchemy 0.5. The non-ORM analogue is described at :ref:`dep_interfaces_core_toplevel`. -As of SQLAlchemy 0.7, the new event system described in -:ref:`event_toplevel` replaces the extension/proxy/listener system, providing -a consistent interface to all events without the need for subclassing. +.. deprecated:: 0.7 + As of SQLAlchemy 0.7, the new event system described in + :ref:`event_toplevel` replaces the extension/proxy/listener system, providing + a consistent interface to all events without the need for subclassing. Mapper Events ----------------- diff --git a/doc/build/orm/loading.rst b/doc/build/orm/loading.rst index f8daa371e8..7c9001afdd 100644 --- a/doc/build/orm/loading.rst +++ b/doc/build/orm/loading.rst @@ -159,9 +159,8 @@ loading**; these are described in :ref:`largecollections`. Default Loading Strategies -------------------------- -.. note:: - - Default loader strategies are a new feature as of version 0.7.5. +.. versionadded:: 0.7.5 + Default loader strategies as a new feature. Each of :func:`.joinedload`, :func:`.subqueryload`, :func:`.lazyload`, and :func:`.noload` can be used to set the default style of diff --git a/doc/build/orm/mapper_config.rst b/doc/build/orm/mapper_config.rst index a88219af1d..7dc882d21e 100644 --- a/doc/build/orm/mapper_config.rst +++ b/doc/build/orm/mapper_config.rst @@ -703,7 +703,10 @@ Synonyms -------- Synonyms are a mapper-level construct that applies expression behavior to a descriptor -based attribute. The functionality of synonym is superceded as of 0.7 by hybrid attributes. +based attribute. + +.. versionchanged:: 0.7 + The functionality of synonym is superceded as of 0.7 by hybrid attributes. .. autofunction:: synonym @@ -770,8 +773,8 @@ Sets of columns can be associated with a single user-defined datatype. The ORM provides a single attribute which represents the group of columns using the class you provide. -.. note:: - As of SQLAlchemy 0.7, composites have been simplified such that +.. versionchanged:: 0.7 + Composites have been simplified such that they no longer "conceal" the underlying column based attributes. Additionally, in-place mutation is no longer automatic; see the section below on enabling mutability to support tracking of in-place changes. @@ -864,13 +867,16 @@ using the ``.start`` and ``.end`` attributes against ad-hoc ``Point`` instances: Tracking In-Place Mutations on Composites ----------------------------------------- -As of SQLAlchemy 0.7, in-place changes to an existing composite value are +In-place changes to an existing composite value are not tracked automatically. Instead, the composite class needs to provide events to its parent object explicitly. This task is largely automated via the usage of the :class:`.MutableComposite` mixin, which uses events to associate each user-defined composite object with all parent associations. Please see the example in :ref:`mutable_composites`. +.. versionchanged:: 0.7 + No automatic tracking of in-place changes to an existing composite value. + Redefining Comparison Operations for Composites ----------------------------------------------- diff --git a/doc/build/orm/relationships.rst b/doc/build/orm/relationships.rst index a68dad11ee..4dedff3944 100644 --- a/doc/build/orm/relationships.rst +++ b/doc/build/orm/relationships.rst @@ -1179,10 +1179,13 @@ as illustrated below:: The above mapping features a composite :class:`.ForeignKeyConstraint` bridging the ``widget_id`` and ``favorite_entry_id`` columns. To ensure that ``Widget.widget_id`` remains an "autoincrementing" column we specify -``autoincrement='ignore_fk'`` on :class:`.Column` (new in 0.7.4), and additionally on each +``autoincrement='ignore_fk'`` on :class:`.Column`, and additionally on each :func:`.relationship` we must limit those columns considered as part of the foreign key for the purposes of joining and cross-population. +.. versionadded:: 0.7.4 + ``autoincrement='ignore_fk'`` on :class:`.Column`\ . + .. _passive_updates: Mutable Primary Keys / Update Cascades -- 2.47.3