diff options
Diffstat (limited to 'doc/build')
22 files changed, 111 insertions, 224 deletions
diff --git a/doc/build/changelog/changelog_08.rst b/doc/build/changelog/changelog_08.rst index 4b6b42ec7..f65006100 100644 --- a/doc/build/changelog/changelog_08.rst +++ b/doc/build/changelog/changelog_08.rst @@ -1896,7 +1896,7 @@ de-associated from any of its orphan-enabled parents. Previously, the pending object would be expunged only if de-associated from all of its orphan-enabled parents. The new flag ``legacy_is_orphan`` - is added to :func:`_orm.mapper` which re-establishes the + is added to :class:`_orm.Mapper` which re-establishes the legacy behavior. See the change note and example case at :ref:`legacy_is_orphan_addition` diff --git a/doc/build/changelog/changelog_10.rst b/doc/build/changelog/changelog_10.rst index 4d3b84d3b..95a5da35b 100644 --- a/doc/build/changelog/changelog_10.rst +++ b/doc/build/changelog/changelog_10.rst @@ -1606,7 +1606,7 @@ the full "instrumentation manager" for a class before it was mapped for the purpose of the new ``@declared_attr`` features described in :ref:`feature_3150`, but the change was also made - against the classical use of :func:`.mapper` for consistency. + against the classical use of :class:`_orm.Mapper` for consistency. However, SQLSoup relies upon the instrumentation event happening before any instrumentation under classical mapping. The behavior is reverted in the case of classical and declarative diff --git a/doc/build/changelog/changelog_14.rst b/doc/build/changelog/changelog_14.rst index 3c8678382..635f99638 100644 --- a/doc/build/changelog/changelog_14.rst +++ b/doc/build/changelog/changelog_14.rst @@ -4796,7 +4796,7 @@ This document details individual issue-level changes made throughout Fixed ORM unit of work regression where an errant "assert primary_key" statement interferes with primary key generation sequences that don't actually consider the columns in the table to use a real primary key - constraint, instead using :paramref:`_orm.mapper.primary_key` to establish + constraint, instead using :paramref:`_orm.Mapper.primary_key` to establish certain columns as "primary". .. change:: diff --git a/doc/build/changelog/migration_13.rst b/doc/build/changelog/migration_13.rst index d7a26084e..cdef36e12 100644 --- a/doc/build/changelog/migration_13.rst +++ b/doc/build/changelog/migration_13.rst @@ -84,11 +84,11 @@ New Features and Improvements - ORM Relationship to AliasedClass replaces the need for non primary mappers ----------------------------------------------------------------------- -The "non primary mapper" is a :func:`.mapper` created in the +The "non primary mapper" is a :class:`_orm.Mapper` created in the :ref:`classical_mapping` style, which acts as an additional mapper against an already mapped class against a different kind of selectable. The non primary mapper has its roots in the 0.1, 0.2 series of SQLAlchemy where it was -anticipated that the :func:`.mapper` object was to be the primary query +anticipated that the :class:`_orm.Mapper` object was to be the primary query construction interface, before the :class:`_query.Query` object existed. With the advent of :class:`_query.Query` and later the :class:`.AliasedClass` diff --git a/doc/build/changelog/migration_14.rst b/doc/build/changelog/migration_14.rst index f1e56b391..7001acb05 100644 --- a/doc/build/changelog/migration_14.rst +++ b/doc/build/changelog/migration_14.rst @@ -292,11 +292,11 @@ the :class:`_orm.registry` object, and fall into these categories: * Using :meth:`_orm.registry.map_imperatively` * :ref:`orm_imperative_dataclasses` -The existing classical mapping function :func:`_orm.mapper` remains, however -it is deprecated to call upon :func:`_orm.mapper` directly; the new -:meth:`_orm.registry.map_imperatively` method now routes the request through -the :meth:`_orm.registry` so that it integrates with other declarative mappings -unambiguously. +The existing classical mapping function ``sqlalchemy.orm.mapper()`` remains, +however it is deprecated to call upon ``sqlalchemy.orm.mapper()`` directly; the +new :meth:`_orm.registry.map_imperatively` method now routes the request +through the :meth:`_orm.registry` so that it integrates with other declarative +mappings unambiguously. The new approach interoperates with 3rd party class instrumentation systems which necessarily must take place on the class before the mapping process diff --git a/doc/build/changelog/migration_20.rst b/doc/build/changelog/migration_20.rst index 4c2ef22bd..afab78277 100644 --- a/doc/build/changelog/migration_20.rst +++ b/doc/build/changelog/migration_20.rst @@ -1381,8 +1381,8 @@ The original "mapper()" function now a core element of Declarative, renamed **Synopsis** -The :func:`_orm.mapper` function moves behind the scenes to be invoked -by higher level APIs. The new version of this function is the method +The ``sqlalchemy.orm.mapper()`` standalone function moves behind the scenes to +be invoked by higher level APIs. The new version of this function is the method :meth:`_orm.registry.map_imperatively` taken from a :class:`_orm.registry` object. diff --git a/doc/build/changelog/unreleased_20/7257.rst b/doc/build/changelog/unreleased_20/7257.rst index 6a3e4ffda..079b0554e 100644 --- a/doc/build/changelog/unreleased_20/7257.rst +++ b/doc/build/changelog/unreleased_20/7257.rst @@ -3,7 +3,8 @@ :tickets: 7257 Migrated the codebase to remove all pre-2.0 behaviors and architectures - that were previously noted as deprecated for removal in 2.0, including: + that were previously noted as deprecated for removal in 2.0, including, + but not limited to: * removal of all Python 2 code, minimum version is now Python 3.7 @@ -26,6 +27,10 @@ :class:`.Table`, and from all DDL/DML/DQL elements that previously could refer to a "bound engine" + * The standalone ``sqlalchemy.orm.mapper()`` function is removed; all + classical mapping should be done through the + :meth:`_orm.registry.map_imperatively` method of :class:`_orm.registry`. + * The :meth:`_orm.Query.join` method no longer accepts strings for relationship names; the long-documented approach of using ``Class.attrname`` for join targets is now standard. @@ -39,6 +44,14 @@ * ``Query.from_self()``, ``Query.select_entity_from()`` and ``Query.with_polymorphic()`` are removed. + * The :paramref:`_orm.relationship.cascade_backrefs` parameter must now + remain at its new default of ``False``; the ``save-update`` cascade + no longer cascades along a backref. + + * the :paramref:`_orm.Session.future` parameter must always be set to + ``True``. 2.0-style transactional patterns for :class:`_orm.Session` + are now always in effect. + * Loader options no longer accept strings for attribute names. The long-documented approach of using ``Class.attrname`` for loader option targets is now standard. @@ -47,4 +60,6 @@ ``select([cols])``, the "whereclause" and keyword parameters of ``some_table.select()``. - * More are in progress as development continues + * Legacy "in-place mutator" methods on :class:`_sql.Select` such as + ``append_whereclause()``, ``append_order_by()`` etc are removed. + diff --git a/doc/build/errors.rst b/doc/build/errors.rst index 4845963b0..e76263692 100644 --- a/doc/build/errors.rst +++ b/doc/build/errors.rst @@ -211,38 +211,6 @@ each, see the section :ref:`faq_new_caching`. :ref:`faq_new_caching` - in the :ref:`faq_toplevel` section -.. _error_s9r1: - -Object is being merged into a Session along the backref cascade ---------------------------------------------------------------- - -This message refers to the "backref cascade" behavior of SQLAlchemy, -which is described at :ref:`backref_cascade`. This refers to the action of -an object being added into a :class:`_orm.Session` as a result of another -object that's already present in that session being associated with it. -As this behavior has been shown to be more confusing than helpful, -the :paramref:`_orm.relationship.cascade_backrefs` and -:paramref:`_orm.backref.cascade_backrefs` parameters were added, which can -be set to ``False`` to disable it, and in SQLAlchemy 2.0 the "cascade backrefs" -behavior will be disabled completely. - -To set :paramref:`_orm.relationship.cascade_backrefs` to ``False`` on a -backref that is currently configured using the -:paramref:`_orm.relationship.backref` string parameter, the backref must -be declared using the :func:`_orm.backref` function first so that the -:paramref:`_orm.backref.cascade_backrefs` parameter may be passed. - -Alternatively, the entire "cascade backrefs" behavior can be turned off -across the board by using the :class:`_orm.Session` in "future" mode, -by passing ``True`` for the :paramref:`_orm.Session.future` parameter. - -.. seealso:: - - :ref:`backref_cascade` - complete description of the cascade backrefs - behavior - - :ref:`change_5150` - background on the change for SQLAlchemy 2.0. - .. _error_xaj1: An alias is being generated automatically for raw clauseelement @@ -1611,3 +1579,33 @@ In SQLAlchemy 1.4, this :term:`2.0 style` behavior is enabled when the :paramref:`_orm.Session.future` flag is set on :class:`_orm.sessionmaker` or :class:`_orm.Session`. +.. _error_s9r1: + +Object is being merged into a Session along the backref cascade +--------------------------------------------------------------- + +This message refers to the "backref cascade" behavior of SQLAlchemy, +removed in version 2.0. This refers to the action of +an object being added into a :class:`_orm.Session` as a result of another +object that's already present in that session being associated with it. +As this behavior has been shown to be more confusing than helpful, +the :paramref:`_orm.relationship.cascade_backrefs` and +:paramref:`_orm.backref.cascade_backrefs` parameters were added, which can +be set to ``False`` to disable it, and in SQLAlchemy 2.0 the "cascade backrefs" +behavior has been removed entirely. + +For older SQLAlchemy versions, to set +:paramref:`_orm.relationship.cascade_backrefs` to ``False`` on a backref that +is currently configured using the :paramref:`_orm.relationship.backref` string +parameter, the backref must be declared using the :func:`_orm.backref` function +first so that the :paramref:`_orm.backref.cascade_backrefs` parameter may be +passed. + +Alternatively, the entire "cascade backrefs" behavior can be turned off +across the board by using the :class:`_orm.Session` in "future" mode, +by passing ``True`` for the :paramref:`_orm.Session.future` parameter. + +.. seealso:: + + :ref:`change_5150` - background on the change for SQLAlchemy 2.0. + diff --git a/doc/build/faq/sessions.rst b/doc/build/faq/sessions.rst index 0c03080f4..6027ab371 100644 --- a/doc/build/faq/sessions.rst +++ b/doc/build/faq/sessions.rst @@ -305,9 +305,9 @@ I've created a mapping against an Outer Join, and while the query returns rows, Rows returned by an outer join may contain NULL for part of the primary key, as the primary key is the composite of both tables. The :class:`_query.Query` object ignores incoming rows that don't have an acceptable primary key. Based on the setting of the ``allow_partial_pks`` -flag on :func:`.mapper`, a primary key is accepted if the value has at least one non-NULL +flag on :class:`_orm.Mapper`, a primary key is accepted if the value has at least one non-NULL value, or alternatively if the value has no NULL values. See ``allow_partial_pks`` -at :func:`.mapper`. +at :class:`_orm.Mapper`. I'm using ``joinedload()`` or ``lazy=False`` to create a JOIN/OUTER JOIN and SQLAlchemy is not constructing the correct query when I try to add a WHERE, ORDER BY, LIMIT, etc. (which relies upon the (OUTER) JOIN) diff --git a/doc/build/glossary.rst b/doc/build/glossary.rst index 08a503ecb..5b84e0a7b 100644 --- a/doc/build/glossary.rst +++ b/doc/build/glossary.rst @@ -427,11 +427,11 @@ Glossary mapping mapped mapped class - We say a class is "mapped" when it has been passed through the - :func:`_orm.mapper` function. This process associates the - class with a database table or other :term:`selectable` - construct, so that instances of it can be persisted - and loaded using a :class:`.Session`. + We say a class is "mapped" when it has been associated with an + instance of the :class:`_orm.Mapper` class. This process associates + the class with a database table or other :term:`selectable` construct, + so that instances of it can be persisted and loaded using a + :class:`.Session`. .. seealso:: diff --git a/doc/build/orm/backref.rst b/doc/build/orm/backref.rst index 65d19eb18..2e1a1920c 100644 --- a/doc/build/orm/backref.rst +++ b/doc/build/orm/backref.rst @@ -186,55 +186,6 @@ returned ``Address``. The :func:`.backref` function formatted the arguments we it into a form that is interpreted by the receiving :func:`_orm.relationship` as additional arguments to be applied to the new relationship it creates. -Setting cascade for backrefs -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A key behavior that occurs in the 1.x series of SQLAlchemy regarding backrefs -is that :ref:`cascades <unitofwork_cascades>` will occur bidirectionally by -default. This basically means, if one starts with an ``User`` object -that's been persisted in the :class:`.Session`:: - - user = session.query(User).filter(User.id == 1).first() - -The above ``User`` is :term:`persistent` in the :class:`.Session`. It usually -is intuitive that if we create an ``Address`` object and append to the -``User.addresses`` collection, it is automatically added to the -:class:`.Session` as in the example below:: - - user = session.query(User).filter(User.id == 1).first() - address = Address(email_address='foo') - user.addresses.append(address) - -The above behavior is known as the "save update cascade" and is described -in the section :ref:`unitofwork_cascades`. - -However, if we instead created a new ``Address`` object, and associated the -``User`` object with the ``Address`` as follows:: - - address = Address(email_address='foo', user=user) - -In the above example, it is **not** as intuitive that the ``Address`` would -automatically be added to the :class:`.Session`. However, the backref behavior -of ``Address.user`` indicates that the ``Address`` object is also appended to -the ``User.addresses`` collection. This in turn initiates a **cascade** -operation which indicates that this ``Address`` should be placed into the -:class:`.Session` as a :term:`pending` object. - -Since this behavior has been identified as counter-intuitive to most people, -it can be disabled by setting :paramref:`_orm.relationship.cascade_backrefs` -to False, as in:: - - - class User(Base): - # ... - - addresses = relationship("Address", back_populates="user", cascade_backrefs=False) - -See the example in :ref:`backref_cascade` for further information. - -.. seealso:: - - :ref:`backref_cascade`. One Way Backrefs diff --git a/doc/build/orm/cascades.rst b/doc/build/orm/cascades.rst index 1a2a7804c..eab49f40c 100644 --- a/doc/build/orm/cascades.rst +++ b/doc/build/orm/cascades.rst @@ -122,13 +122,6 @@ for granted; it simplifies code by allowing a single call to that :class:`.Session` at once. While it can be disabled, there is usually not a need to do so. -One case where ``save-update`` cascade does sometimes get in the way is in that -it takes place in both directions for bi-directional relationships, e.g. -backrefs, meaning that the association of a child object with a particular parent -can have the effect of the parent object being implicitly associated with that -child object's :class:`.Session`; this pattern, as well as how to modify its -behavior using the :paramref:`_orm.relationship.cascade_backrefs` flag, -is discussed in the section :ref:`backref_cascade`. .. _cascade_delete: @@ -560,69 +553,6 @@ expunge from the :class:`.Session` using :meth:`.Session.expunge`, the operation should be propagated down to referred objects. -.. _backref_cascade: - -Controlling Cascade on Backrefs -------------------------------- - -.. note:: This section applies to a behavior that is removed in SQLAlchemy 2.0. - By setting the :paramref:`_orm.Session.future` flag on a given - :class:`_orm.Session`, the 2.0 behavior will be achieved which is - essentially that the :paramref:`_orm.relationship.cascade_backrefs` flag is - ignored. See the section :ref:`change_5150` for notes. - -In :term:`1.x style` ORM usage, the :ref:`cascade_save_update` cascade by -default takes place on attribute change events emitted from backrefs. This is -probably a confusing statement more easily described through demonstration; it -means that, given a mapping such as this:: - - mapper_registry.map_imperatively(Order, order_table, properties={ - 'items' : relationship(Item, backref='order') - }) - -If an ``Order`` is already in the session, and is assigned to the ``order`` -attribute of an ``Item``, the backref appends the ``Item`` to the ``items`` -collection of that ``Order``, resulting in the ``save-update`` cascade taking -place:: - - >>> o1 = Order() - >>> session.add(o1) - >>> o1 in session - True - - >>> i1 = Item() - >>> i1.order = o1 - >>> i1 in o1.items - True - >>> i1 in session - True - -This behavior can be disabled using the :paramref:`_orm.relationship.cascade_backrefs` flag:: - - mapper_registry.map_imperatively(Order, order_table, properties={ - 'items' : relationship(Item, backref='order', cascade_backrefs=False) - }) - -So above, the assignment of ``i1.order = o1`` will append ``i1`` to the ``items`` -collection of ``o1``, but will not add ``i1`` to the session. You can, of -course, :meth:`~.Session.add` ``i1`` to the session at a later point. This -option may be helpful for situations where an object needs to be kept out of a -session until it's construction is completed, but still needs to be given -associations to objects which are already persistent in the target session. - -When relationships are created by the :paramref:`_orm.relationship.backref` -parameter on :func:`_orm.relationship`, the :paramref:`_orm.cascade_backrefs` -parameter may be set to ``False`` on the backref side by using the -:func:`_orm.backref` function instead of a string. For example, the above relationship -could be declared:: - - mapper_registry.map_imperatively(Order, order_table, properties={ - 'items' : relationship( - Item, backref=backref('order', cascade_backrefs=False), cascade_backrefs=False - ) - }) - -This sets the ``cascade_backrefs=False`` behavior on both relationships. .. _session_deleting_from_collections: diff --git a/doc/build/orm/declarative_config.rst b/doc/build/orm/declarative_config.rst index 4a091c848..d19e9ffc0 100644 --- a/doc/build/orm/declarative_config.rst +++ b/doc/build/orm/declarative_config.rst @@ -152,19 +152,19 @@ Mapper Configuration Options with Declarative With all mapping forms, the mapping of the class is configured through parameters that become part of the :class:`_orm.Mapper` object. The function which ultimately receives these arguments is the -:func:`_orm.mapper` function, and are delivered to it from one of +:class:`_orm.Mapper` function, and are delivered to it from one of the front-facing mapping functions defined on the :class:`_orm.registry` object. For the declarative form of mapping, mapper arguments are specified using the ``__mapper_args__`` declarative class variable, which is a dictionary -that is passed as keyword arguments to the :func:`_orm.mapper` function. +that is passed as keyword arguments to the :class:`_orm.Mapper` function. Some examples: **Version ID Column** -The :paramref:`_orm.mapper.version_id_col` and -:paramref:`_orm.mapper.version_id_generator` parameters:: +The :paramref:`_orm.Mapper.version_id_col` and +:paramref:`_orm.Mapper.version_id_generator` parameters:: from datetime import datetime @@ -181,8 +181,8 @@ The :paramref:`_orm.mapper.version_id_col` and **Single Table Inheritance** -The :paramref:`_orm.mapper.polymorphic_on` and -:paramref:`_orm.mapper.polymorphic_identity` parameters:: +The :paramref:`_orm.Mapper.polymorphic_on` and +:paramref:`_orm.Mapper.polymorphic_identity` parameters:: class Person(Base): __tablename__ = 'person' diff --git a/doc/build/orm/extensions/associationproxy.rst b/doc/build/orm/extensions/associationproxy.rst index de2001e6f..aef046b04 100644 --- a/doc/build/orm/extensions/associationproxy.rst +++ b/doc/build/orm/extensions/associationproxy.rst @@ -98,7 +98,7 @@ for us transparently:: The :class:`.AssociationProxy` object produced by the :func:`.association_proxy` function is an instance of a `Python descriptor <https://docs.python.org/howto/descriptor.html>`_. It is always declared with the user-defined class being mapped, regardless of -whether Declarative or classical mappings via the :func:`.mapper` function are used. +whether Declarative or classical mappings via the :class:`_orm.Mapper` function are used. The proxy functions by operating upon the underlying mapped attribute or collection in response to operations, and changes made via the proxy are immediately diff --git a/doc/build/orm/extensions/asyncio.rst b/doc/build/orm/extensions/asyncio.rst index a7d2fb16b..23eed9e76 100644 --- a/doc/build/orm/extensions/asyncio.rst +++ b/doc/build/orm/extensions/asyncio.rst @@ -295,7 +295,7 @@ prevent this: :paramref:`_schema.Column.default` parameter is assigned to a SQL expression object. To access this value with asyncio, it has to be refreshed within the flush process, which is achieved by setting the - :paramref:`_orm.mapper.eager_defaults` parameter on the mapping:: + :paramref:`_orm.Mapper.eager_defaults` parameter on the mapping:: class A(Base): diff --git a/doc/build/orm/extensions/mypy.rst b/doc/build/orm/extensions/mypy.rst index b710d1f44..fc2654996 100644 --- a/doc/build/orm/extensions/mypy.rst +++ b/doc/build/orm/extensions/mypy.rst @@ -17,12 +17,14 @@ Support for :pep:`484` typing annotations as well as the Installation ------------ -The Mypy plugin depends upon new stubs for SQLAlchemy packaged at -`sqlalchemy2-stubs <https://pypi.org/project/sqlalchemy2-stubs/>`_. These -stubs necessarily fully replace the previous ``sqlalchemy-stubs`` typing -annotations published by Dropbox, as they occupy the same ``sqlalchemy-stubs`` -namespace as specified by :pep:`561`. The `Mypy <https://pypi.org/project/mypy/>`_ -package itself is also a dependency. +TODO: document uninstallation of existing stubs: + +* ``sqlalchemy2-stubs`` +* ``sqlalchemy-stubs`` + +SQLAlchemy 2.0 is expected to be directly typed. + +The `Mypy <https://pypi.org/project/mypy/>`_ package itself is a dependency. Both packages may be installed using the "mypy" extras hook using pip:: diff --git a/doc/build/orm/mapping_api.rst b/doc/build/orm/mapping_api.rst index 5d0b6c0d0..eeba54040 100644 --- a/doc/build/orm/mapping_api.rst +++ b/doc/build/orm/mapping_api.rst @@ -20,8 +20,6 @@ Class Mapping API .. autofunction:: synonym_for -.. autofunction:: mapper - .. autofunction:: object_mapper .. autofunction:: class_mapper diff --git a/doc/build/orm/mapping_columns.rst b/doc/build/orm/mapping_columns.rst index 596c64f7c..66fb22e01 100644 --- a/doc/build/orm/mapping_columns.rst +++ b/doc/build/orm/mapping_columns.rst @@ -5,7 +5,7 @@ Mapping Table Columns ===================== -The default behavior of :func:`_orm.mapper` is to assemble all the columns in +The default behavior of :class:`_orm.Mapper` is to assemble all the columns in the mapped :class:`_schema.Table` into mapped object attributes, each of which are named according to the name of the column itself (specifically, the ``key`` attribute of :class:`_schema.Column`). This behavior can be @@ -43,7 +43,7 @@ can be referenced directly:: name = user_table.c.user_name The corresponding technique for an :term:`imperative` mapping is -to place the desired key in the :paramref:`_orm.mapper.properties` +to place the desired key in the :paramref:`_orm.Mapper.properties` dictionary with the desired key:: mapper_registry.map_imperatively(User, user_table, properties={ @@ -118,8 +118,8 @@ Using column_property for column level options Options can be specified when mapping a :class:`_schema.Column` using the :func:`.column_property` function. This function explicitly creates the :class:`.ColumnProperty` used by the -:func:`.mapper` to keep track of the :class:`_schema.Column`; normally, the -:func:`.mapper` creates this automatically. Using :func:`.column_property`, +:class:`_orm.Mapper` to keep track of the :class:`_schema.Column`; normally, the +:class:`_orm.Mapper` creates this automatically. Using :func:`.column_property`, we can pass additional arguments about how we'd like the :class:`_schema.Column` to be mapped. Below, we pass an option ``active_history``, which specifies that a change to this column's value should diff --git a/doc/build/orm/mapping_styles.rst b/doc/build/orm/mapping_styles.rst index 723b54068..f273196b4 100644 --- a/doc/build/orm/mapping_styles.rst +++ b/doc/build/orm/mapping_styles.rst @@ -107,11 +107,11 @@ Documentation for Declarative mapping continues at :ref:`declarative_config_topl Creating an Explicit Base Non-Dynamically (for use with mypy, similar) ---------------------------------------------------------------------- +TODO: update for 2.0 - code here may not be accurate + SQLAlchemy includes a :ref:`Mypy plugin <mypy_toplevel>` that automatically accommodates for the dynamically generated ``Base`` class delivered by SQLAlchemy functions like :func:`_orm.declarative_base`. -This plugin works along with a new set of typing stubs published at -`sqlalchemy2-stubs <https://pypi.org/project/sqlalchemy2-stubs>`_. When this plugin is not in use, or when using other :pep:`484` tools which may not know how to interpret this class, the declarative base class may @@ -126,8 +126,6 @@ be produced in a fully explicit fashion using the class Base(metaclass=DeclarativeMeta): __abstract__ = True - # these are supplied by the sqlalchemy2-stubs, so may be omitted - # when they are installed registry = mapper_registry metadata = mapper_registry.metadata @@ -339,9 +337,10 @@ during flush from autoincrement or other default value generator. To allow them to be specified in the constructor explicitly, they would instead be given a default value of ``None``. -For a :func:`_orm.relationship` to be declared separately, it needs to -be specified directly within the :paramref:`_orm.mapper.properties` -dictionary passed to the :func:`_orm.mapper`. An alternative to this +For a :func:`_orm.relationship` to be declared separately, it needs to be +specified directly within the :paramref:`_orm.Mapper.properties` dictionary +which itself is specified within the ``__mapper_args__`` dictionary, so that it +is passed to the constructor for :class:`_orm.Mapper`. An alternative to this approach is in the next example. .. _orm_declarative_dataclasses_declarative_table: @@ -527,16 +526,10 @@ Imperative (a.k.a. Classical) Mappings An **imperative** or **classical** mapping refers to the configuration of a mapped class using the :meth:`_orm.registry.map_imperatively` method, where the target class does not include any declarative class attributes. -The "map imperative" style has historically been achieved using the -:func:`_orm.mapper` function directly, however this function now expects -that a :meth:`_orm.registry` is present. - -.. deprecated:: 1.4 Using the :func:`_orm.mapper` function directly to - achieve a classical mapping directly is deprecated. The - :meth:`_orm.registry.map_imperatively` method retains the identical - functionality while also allowing for string-based resolution of - other mapped classes from within the registry. +.. versionchanged:: 2.0 The :meth:`_orm.registry.map_imperatively` method + is now used to create classical mappings. The ``sqlalchemy.orm.mapper()`` + standalone function is effectively removed. In "classical" form, the table metadata is created separately with the :class:`_schema.Table` construct, then associated with the ``User`` class via @@ -588,8 +581,8 @@ yet be linked to table metadata, nor can we specify a string here. Some examples in the documentation still use the classical approach, but note that the classical as well as Declarative approaches are **fully interchangeable**. Both systems ultimately create the same configuration, consisting of a :class:`_schema.Table`, -user-defined class, linked together with a :func:`.mapper`. When we talk about -"the behavior of :func:`.mapper`", this includes when using the Declarative system +user-defined class, linked together with a :class:`_orm.Mapper` object. When we talk about +"the behavior of :class:`_orm.Mapper`", this includes when using the Declarative system as well - it's still used, just behind the scenes. @@ -671,15 +664,15 @@ on the class itself as declarative class variables:: Mapper Configuration Overview ============================= -With all mapping forms, the mapping of the class can be -configured in many ways by passing construction arguments that become -part of the :class:`_orm.Mapper` object. The function which ultimately -receives these arguments is the :func:`_orm.mapper` function, which are delivered -to it originating from one of the front-facing mapping functions defined -on the :class:`_orm.registry` object. +With all mapping forms, the mapping of the class can be configured in many ways +by passing construction arguments that become part of the :class:`_orm.Mapper` +object. The construct which ultimately receives these arguments is the +constructor to the :class:`_orm.Mapper` class, and the arguments are delivered +to it originating from one of the front-facing mapping functions defined on the +:class:`_orm.registry` object. There are four general classes of configuration information that the -:func:`_orm.mapper` function looks for: +:class:`_orm.Mapper` class looks for: The class to be mapped ---------------------- @@ -746,12 +739,12 @@ the section :ref:`orm_declarative_properties` for notes on this process. When mapping with the :ref:`imperative <orm_imperative_mapping>` style, the properties dictionary is passed directly as the ``properties`` argument to :meth:`_orm.registry.map_imperatively`, which will pass it along to the -:paramref:`_orm.mapper.properties` parameter. +:paramref:`_orm.Mapper.properties` parameter. Other mapper configuration parameters ------------------------------------- -These flags are documented at :func:`_orm.mapper`. +These flags are documented at :class:`_orm.Mapper`. When mapping with the :ref:`declarative <orm_declarative_mapping>` mapping style, additional mapper configuration arguments are configured via the @@ -760,7 +753,7 @@ style, additional mapper configuration arguments are configured via the When mapping with the :ref:`imperative <orm_imperative_mapping>` style, keyword arguments are passed to the to :meth:`_orm.registry.map_imperatively` -method which passes them along to the :func:`_orm.mapper` function. +method which passes them along to the :class:`_orm.Mapper` class. .. [1] When running under Python 2, a Python 2 "old style" class is the only diff --git a/doc/build/orm/nonstandard_mappings.rst b/doc/build/orm/nonstandard_mappings.rst index bf6b0f247..ff02109e8 100644 --- a/doc/build/orm/nonstandard_mappings.rst +++ b/doc/build/orm/nonstandard_mappings.rst @@ -161,7 +161,7 @@ key. almost never needed; it necessarily tends to produce complex queries which are often less efficient than that which would be produced by direct query construction. The practice is to some degree - based on the very early history of SQLAlchemy where the :func:`.mapper` + based on the very early history of SQLAlchemy where the :class:`_orm.Mapper` construct was meant to represent the primary querying interface; in modern usage, the :class:`_query.Query` object can be used to construct virtually any SELECT statement, including complex composites, and should @@ -174,7 +174,7 @@ In modern SQLAlchemy, a particular class is mapped by only one so-called **primary** mapper at a time. This mapper is involved in three main areas of functionality: querying, persistence, and instrumentation of the mapped class. The rationale of the primary mapper relates to the fact that the -:func:`.mapper` modifies the class itself, not only persisting it towards a +:class:`_orm.Mapper` modifies the class itself, not only persisting it towards a particular :class:`_schema.Table`, but also :term:`instrumenting` attributes upon the class which are structured specifically according to the table metadata. It's not possible for more than one mapper to be associated with a class in equal diff --git a/doc/build/orm/relationship_persistence.rst b/doc/build/orm/relationship_persistence.rst index f84376474..765c5b69d 100644 --- a/doc/build/orm/relationship_persistence.rst +++ b/doc/build/orm/relationship_persistence.rst @@ -213,7 +213,7 @@ should be enabled, using the configuration described at :ref:`passive_deletes` - supporting ON DELETE CASCADE with relationships - :paramref:`.orm.mapper.passive_updates` - similar feature on :func:`.mapper` + :paramref:`.orm.mapper.passive_updates` - similar feature on :class:`_orm.Mapper` Simulating limited ON UPDATE CASCADE without foreign key support diff --git a/doc/build/orm/versioning.rst b/doc/build/orm/versioning.rst index a141df6a0..7aeca0873 100644 --- a/doc/build/orm/versioning.rst +++ b/doc/build/orm/versioning.rst @@ -175,7 +175,7 @@ automatically providing the new value of the version id counter. The ORM typically does not actively fetch the values of database-generated values when it emits an INSERT or UPDATE, instead leaving these columns as "expired" and to be fetched when they are next accessed, unless the ``eager_defaults`` -:func:`.mapper` flag is set. However, when a +:class:`_orm.Mapper` flag is set. However, when a server side version column is used, the ORM needs to actively fetch the newly generated value. This is so that the version counter is set up *before* any concurrent transaction may update it again. This fetching is also |