From c8e847811fcff2beb0244ec33016898da0e0ec89 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Fri, 8 Jun 2012 15:59:27 -0400 Subject: [PATCH] Add some `Sphinx` related version informations paragraph-level markups, such as ``.. versionaddedd::``, ``.. versionchanged::`` and ``.. deprecated::``. --- 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 | 5 +++-- 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 ++++- 12 files changed, 60 insertions(+), 33 deletions(-) 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 49029e67ff..7c991888f7 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 4713f32890..97e99502d0 100644 --- a/doc/build/orm/inheritance.rst +++ b/doc/build/orm/inheritance.rst @@ -535,8 +535,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 c2ab62487f..c70871668e 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.2