diff options
Diffstat (limited to 'lib/sqlalchemy/orm')
| -rw-r--r-- | lib/sqlalchemy/orm/__init__.py | 3 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/attributes.py | 17 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/base.py | 31 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/descriptor_props.py | 12 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/events.py | 142 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/exc.py | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/interfaces.py | 26 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/loading.py | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/mapper.py | 227 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/persistence.py | 4 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/properties.py | 7 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/query.py | 523 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/relationships.py | 250 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/scoping.py | 5 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/session.py | 181 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/state.py | 12 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/strategies.py | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/strategy_options.py | 109 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/util.py | 106 |
19 files changed, 935 insertions, 726 deletions
diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py index 53118c573..24945ef52 100644 --- a/lib/sqlalchemy/orm/__init__.py +++ b/lib/sqlalchemy/orm/__init__.py @@ -153,7 +153,8 @@ def deferred(*columns, **kw): not load unless accessed. :param \*columns: columns to be mapped. This is typically a single - :class:`.Column` object, however a collection is supported in order + :class:`_schema.Column` object, + however a collection is supported in order to support multiple columns mapped under the same attribute. :param raiseload: boolean, if True, indicates an exception should be raised diff --git a/lib/sqlalchemy/orm/attributes.py b/lib/sqlalchemy/orm/attributes.py index 82979b188..ec706d4d8 100644 --- a/lib/sqlalchemy/orm/attributes.py +++ b/lib/sqlalchemy/orm/attributes.py @@ -72,9 +72,9 @@ class QueryableAttribute( :class:`.MapperProperty` - :attr:`.Mapper.all_orm_descriptors` + :attr:`_orm.Mapper.all_orm_descriptors` - :attr:`.Mapper.attrs` + :attr:`_orm.Mapper.attrs` """ is_attribute = True @@ -134,12 +134,13 @@ class QueryableAttribute( * If the attribute is a column-mapped property, i.e. :class:`.ColumnProperty`, which is mapped directly - to a schema-level :class:`.Column` object, this attribute + to a schema-level :class:`_schema.Column` object, this attribute will return the :attr:`.SchemaItem.info` dictionary associated - with the core-level :class:`.Column` object. + with the core-level :class:`_schema.Column` object. * If the attribute is a :class:`.ColumnProperty` but is mapped to - any other kind of SQL expression other than a :class:`.Column`, + any other kind of SQL expression other than a + :class:`_schema.Column`, the attribute will refer to the :attr:`.MapperProperty.info` dictionary associated directly with the :class:`.ColumnProperty`, assuming the SQL expression itself does not have its own ``.info`` @@ -154,7 +155,7 @@ class QueryableAttribute( * To access the :attr:`.MapperProperty.info` dictionary of the :class:`.MapperProperty` unconditionally, including for a :class:`.ColumnProperty` that's associated directly with a - :class:`.schema.Column`, the attribute can be referred to using + :class:`_schema.Column`, the attribute can be referred to using :attr:`.QueryableAttribute.property` attribute, as ``MyClass.someattribute.property.info``. @@ -171,7 +172,7 @@ class QueryableAttribute( def parent(self): """Return an inspection instance representing the parent. - This will be either an instance of :class:`.Mapper` + This will be either an instance of :class:`_orm.Mapper` or :class:`.AliasedInsp`, depending upon the nature of the parent entity which this attribute is associated with. @@ -1608,7 +1609,7 @@ class History(util.namedtuple("History", ["added", "unchanged", "deleted"])): attribute. The easiest way to get a :class:`.History` object for a particular - attribute on an object is to use the :func:`.inspect` function:: + attribute on an object is to use the :func:`_sa.inspect` function:: from sqlalchemy import inspect diff --git a/lib/sqlalchemy/orm/base.py b/lib/sqlalchemy/orm/base.py index 6df8acf1e..07809282b 100644 --- a/lib/sqlalchemy/orm/base.py +++ b/lib/sqlalchemy/orm/base.py @@ -166,7 +166,7 @@ EXT_SKIP = util.symbol("EXT_SKIP") ONETOMANY = util.symbol( "ONETOMANY", - """Indicates the one-to-many direction for a :func:`.relationship`. + """Indicates the one-to-many direction for a :func:`_orm.relationship`. This symbol is typically used by the internals but may be exposed within certain API features. @@ -176,7 +176,7 @@ ONETOMANY = util.symbol( MANYTOONE = util.symbol( "MANYTOONE", - """Indicates the many-to-one direction for a :func:`.relationship`. + """Indicates the many-to-one direction for a :func:`_orm.relationship`. This symbol is typically used by the internals but may be exposed within certain API features. @@ -186,7 +186,7 @@ MANYTOONE = util.symbol( MANYTOMANY = util.symbol( "MANYTOMANY", - """Indicates the many-to-many direction for a :func:`.relationship`. + """Indicates the many-to-many direction for a :func:`_orm.relationship`. This symbol is typically used by the internals but may be exposed within certain API features. @@ -298,7 +298,7 @@ def object_state(instance): Raises :class:`sqlalchemy.orm.exc.UnmappedInstanceError` if no mapping is configured. - Equivalent functionality is available via the :func:`.inspect` + Equivalent functionality is available via the :func:`_sa.inspect` function as:: inspect(instance) @@ -336,7 +336,7 @@ def _class_to_mapper(class_or_mapper): def _mapper_or_none(entity): - """Return the :class:`.Mapper` for the given class or None if the + """Return the :class:`_orm.Mapper` for the given class or None if the class is not mapped. """ @@ -349,7 +349,7 @@ def _mapper_or_none(entity): def _is_mapped_class(entity): """Return True if the given object is a mapped class, - :class:`.Mapper`, or :class:`.AliasedClass`. + :class:`_orm.Mapper`, or :class:`.AliasedClass`. """ insp = inspection.inspect(entity, False) @@ -422,14 +422,14 @@ def _inspect_mapped_class(class_, configure=False): def class_mapper(class_, configure=True): - """Given a class, return the primary :class:`.Mapper` associated + """Given a class, return the primary :class:`_orm.Mapper` associated with the key. Raises :exc:`.UnmappedClassError` if no mapping is configured on the given class, or :exc:`.ArgumentError` if a non-class object is passed. - Equivalent functionality is available via the :func:`.inspect` + Equivalent functionality is available via the :func:`_sa.inspect` function as:: inspect(some_mapped_class) @@ -451,7 +451,7 @@ def class_mapper(class_, configure=True): class InspectionAttr(object): """A base class applied to all ORM objects that can be returned - by the :func:`.inspect` function. + by the :func:`_sa.inspect` function. The attributes defined here allow the usage of simple boolean checks to test basic facts about the object returned. @@ -467,7 +467,8 @@ class InspectionAttr(object): __slots__ = () is_selectable = False - """Return True if this object is an instance of :class:`.Selectable`.""" + """Return True if this object is an instance of """ + """:class:`expression.Selectable`.""" is_aliased_class = False """True if this object is an instance of :class:`.AliasedClass`.""" @@ -476,7 +477,7 @@ class InspectionAttr(object): """True if this object is an instance of :class:`.InstanceState`.""" is_mapper = False - """True if this object is an instance of :class:`.Mapper`.""" + """True if this object is an instance of :class:`_orm.Mapper`.""" is_property = False """True if this object is an instance of :class:`.MapperProperty`.""" @@ -493,7 +494,7 @@ class InspectionAttr(object): .. seealso:: - :attr:`.Mapper.all_orm_descriptors` + :attr:`_orm.Mapper.all_orm_descriptors` """ @@ -505,7 +506,8 @@ class InspectionAttr(object): """ is_clause_element = False - """True if this object is an instance of :class:`.ClauseElement`.""" + """True if this object is an instance of """ + """:class:`_expression.ClauseElement`.""" extension_type = NOT_EXTENSION """The extension type, if any. @@ -538,7 +540,8 @@ class InspectionAttrInfo(InspectionAttr): The dictionary is generated when first accessed. Alternatively, it can be specified as a constructor argument to the - :func:`.column_property`, :func:`.relationship`, or :func:`.composite` + :func:`.column_property`, :func:`_orm.relationship`, or + :func:`.composite` functions. .. versionchanged:: 1.0.0 :attr:`.MapperProperty.info` is also diff --git a/lib/sqlalchemy/orm/descriptor_props.py b/lib/sqlalchemy/orm/descriptor_props.py index 3bc009da8..7fff13101 100644 --- a/lib/sqlalchemy/orm/descriptor_props.py +++ b/lib/sqlalchemy/orm/descriptor_props.py @@ -550,14 +550,18 @@ class SynonymProperty(DescriptorProperty): :param map_column: **For classical mappings and mappings against an existing Table object only**. if ``True``, the :func:`.synonym` - construct will locate the :class:`.Column` object upon the mapped + construct will locate the :class:`_schema.Column` + object upon the mapped table that would normally be associated with the attribute name of this synonym, and produce a new :class:`.ColumnProperty` that instead - maps this :class:`.Column` to the alternate name given as the "name" + maps this :class:`_schema.Column` + to the alternate name given as the "name" argument of the synonym; in this way, the usual step of redefining - the mapping of the :class:`.Column` to be under a different name is + the mapping of the :class:`_schema.Column` + to be under a different name is unnecessary. This is usually intended to be used when a - :class:`.Column` is to be replaced with an attribute that also uses a + :class:`_schema.Column` + is to be replaced with an attribute that also uses a descriptor, that is, in conjunction with the :paramref:`.synonym.descriptor` parameter:: diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py index a41ea49e8..f08ef085b 100644 --- a/lib/sqlalchemy/orm/events.py +++ b/lib/sqlalchemy/orm/events.py @@ -143,8 +143,8 @@ class InstanceEvents(event.Events): * mapped classes * unmapped superclasses of mapped or to-be-mapped classes (using the ``propagate=True`` flag) - * :class:`.Mapper` objects - * the :class:`.Mapper` class itself and the :func:`.mapper` + * :class:`_orm.Mapper` objects + * the :class:`_orm.Mapper` class itself and the :func:`.mapper` function indicate listening for all mappers. Instance events are closely related to mapper events, but @@ -369,15 +369,15 @@ class InstanceEvents(event.Events): The :meth:`.InstanceEvents.load` event is also available in a - class-method decorator format called :func:`.orm.reconstructor`. + class-method decorator format called :func:`_orm.reconstructor`. :param target: the mapped instance. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param context: the :class:`.QueryContext` corresponding to the - current :class:`.Query` in progress. This argument may be - ``None`` if the load does not correspond to a :class:`.Query`, + current :class:`_query.Query` in progress. This argument may be + ``None`` if the load does not correspond to a :class:`_query.Query`, such as during :meth:`.Session.merge`. .. seealso:: @@ -413,7 +413,7 @@ class InstanceEvents(event.Events): instead be the :class:`.InstanceState` state-management object associated with the instance. :param context: the :class:`.QueryContext` corresponding to the - current :class:`.Query` in progress. + current :class:`_query.Query` in progress. :param attrs: sequence of attribute names which were populated, or None if all column-mapped, non-deferred attributes were populated. @@ -617,8 +617,8 @@ class MapperEvents(event.Events): * mapped classes * unmapped superclasses of mapped or to-be-mapped classes (using the ``propagate=True`` flag) - * :class:`.Mapper` objects - * the :class:`.Mapper` class itself and the :func:`.mapper` + * :class:`_orm.Mapper` objects + * the :class:`_orm.Mapper` class itself and the :func:`.mapper` function indicate listening for all mappers. Mapper events provide hooks into critical sections of the @@ -747,7 +747,7 @@ class MapperEvents(event.Events): This event is the earliest phase of mapper construction. Most attributes of the mapper are not yet initialized. - This listener can either be applied to the :class:`.Mapper` + This listener can either be applied to the :class:`_orm.Mapper` class overall, or to any un-mapped class which serves as a base for classes that will be mapped (using the ``propagate=True`` flag):: @@ -757,7 +757,7 @@ class MapperEvents(event.Events): def on_new_class(mapper, cls_): " ... " - :param mapper: the :class:`.Mapper` which is the target + :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param class\_: the mapped class. @@ -817,9 +817,9 @@ class MapperEvents(event.Events): The :meth:`.MapperEvents.mapper_configured` event is invoked for each mapper that is encountered when the - :func:`.orm.configure_mappers` function proceeds through the current + :func:`_orm.configure_mappers` function proceeds through the current list of not-yet-configured mappers. - :func:`.orm.configure_mappers` is typically invoked + :func:`_orm.configure_mappers` is typically invoked automatically as mappings are first used, as well as each time new mappers have been made available and new mapper use is detected. @@ -850,7 +850,7 @@ class MapperEvents(event.Events): on a specific mapper basis, which don't require that "backref" configurations are necessarily ready yet. - :param mapper: the :class:`.Mapper` which is the target + :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param class\_: the mapped class. @@ -869,14 +869,14 @@ class MapperEvents(event.Events): """Called before a series of mappers have been configured. The :meth:`.MapperEvents.before_configured` event is invoked - each time the :func:`.orm.configure_mappers` function is + each time the :func:`_orm.configure_mappers` function is invoked, before the function has done any of its work. - :func:`.orm.configure_mappers` is typically invoked + :func:`_orm.configure_mappers` is typically invoked automatically as mappings are first used, as well as each time new mappers have been made available and new mapper use is detected. - This event can **only** be applied to the :class:`.Mapper` class + This event can **only** be applied to the :class:`_orm.Mapper` class or :func:`.mapper` function, and not to individual mappings or mapped classes. It is only invoked for all mappings as a whole:: @@ -894,7 +894,7 @@ class MapperEvents(event.Events): Theoretically this event is called once per application, but is actually called any time new mappers - are to be affected by a :func:`.orm.configure_mappers` + are to be affected by a :func:`_orm.configure_mappers` call. If new mappings are constructed after existing ones have already been used, this event will likely be called again. To ensure that a particular event is only called once and no further, the @@ -924,9 +924,9 @@ class MapperEvents(event.Events): """Called after a series of mappers have been configured. The :meth:`.MapperEvents.after_configured` event is invoked - each time the :func:`.orm.configure_mappers` function is + each time the :func:`_orm.configure_mappers` function is invoked, after the function has completed its work. - :func:`.orm.configure_mappers` is typically invoked + :func:`_orm.configure_mappers` is typically invoked automatically as mappings are first used, as well as each time new mappers have been made available and new mapper use is detected. @@ -939,7 +939,7 @@ class MapperEvents(event.Events): Also contrast to :meth:`.MapperEvents.before_configured`, which is invoked before the series of mappers has been configured. - This event can **only** be applied to the :class:`.Mapper` class + This event can **only** be applied to the :class:`_orm.Mapper` class or :func:`.mapper` function, and not to individual mappings or mapped classes. It is only invoked for all mappings as a whole:: @@ -951,7 +951,7 @@ class MapperEvents(event.Events): Theoretically this event is called once per application, but is actually called any time new mappers - have been affected by a :func:`.orm.configure_mappers` + have been affected by a :func:`_orm.configure_mappers` call. If new mappings are constructed after existing ones have already been used, this event will likely be called again. To ensure that a particular event is only called once and no further, the @@ -996,14 +996,14 @@ class MapperEvents(event.Events): Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given - :class:`.Connection`. **Please read fully** the notes + :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. - :param mapper: the :class:`.Mapper` which is the target + :param mapper: the :class:`_orm.Mapper` which is the target of this event. - :param connection: the :class:`.Connection` being used to + :param connection: the :class:`_engine.Connection` being used to emit INSERT statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. @@ -1042,14 +1042,14 @@ class MapperEvents(event.Events): Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given - :class:`.Connection`. **Please read fully** the notes + :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. - :param mapper: the :class:`.Mapper` which is the target + :param mapper: the :class:`_orm.Mapper` which is the target of this event. - :param connection: the :class:`.Connection` being used to + :param connection: the :class:`_engine.Connection` being used to emit INSERT statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. @@ -1107,14 +1107,14 @@ class MapperEvents(event.Events): Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given - :class:`.Connection`. **Please read fully** the notes + :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. - :param mapper: the :class:`.Mapper` which is the target + :param mapper: the :class:`_orm.Mapper` which is the target of this event. - :param connection: the :class:`.Connection` being used to + :param connection: the :class:`_engine.Connection` being used to emit UPDATE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. @@ -1171,14 +1171,14 @@ class MapperEvents(event.Events): Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given - :class:`.Connection`. **Please read fully** the notes + :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. - :param mapper: the :class:`.Mapper` which is the target + :param mapper: the :class:`_orm.Mapper` which is the target of this event. - :param connection: the :class:`.Connection` being used to + :param connection: the :class:`_engine.Connection` being used to emit UPDATE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. @@ -1211,14 +1211,14 @@ class MapperEvents(event.Events): Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given - :class:`.Connection`. **Please read fully** the notes + :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. - :param mapper: the :class:`.Mapper` which is the target + :param mapper: the :class:`_orm.Mapper` which is the target of this event. - :param connection: the :class:`.Connection` being used to + :param connection: the :class:`_engine.Connection` being used to emit DELETE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. @@ -1251,14 +1251,14 @@ class MapperEvents(event.Events): Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given - :class:`.Connection`. **Please read fully** the notes + :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. - :param mapper: the :class:`.Mapper` which is the target + :param mapper: the :class:`_orm.Mapper` which is the target of this event. - :param connection: the :class:`.Connection` being used to + :param connection: the :class:`_engine.Connection` being used to emit DELETE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. @@ -1666,7 +1666,7 @@ class SessionEvents(event.Events): :param session: The target :class:`.Session`. :param transaction: The :class:`.SessionTransaction`. - :param connection: The :class:`~.engine.Connection` object + :param connection: The :class:`_engine.Connection` object which will be used for SQL statements. .. seealso:: @@ -1734,16 +1734,17 @@ class SessionEvents(event.Events): def after_bulk_update(self, update_context): """Execute after a bulk update operation to the session. - This is called as a result of the :meth:`.Query.update` method. + This is called as a result of the :meth:`_query.Query.update` method. :param update_context: an "update context" object which contains details about the update, including these attributes: * ``session`` - the :class:`.Session` involved - * ``query`` -the :class:`.Query` object that this update operation + * ``query`` -the :class:`_query.Query` + object that this update operation was called upon. * ``values`` The "values" dictionary that was passed to - :meth:`.Query.update`. + :meth:`_query.Query.update`. * ``context`` The :class:`.QueryContext` object, corresponding to the invocation of an ORM query. * ``result`` the :class:`.ResultProxy` returned as a result of the @@ -1770,13 +1771,14 @@ class SessionEvents(event.Events): def after_bulk_delete(self, delete_context): """Execute after a bulk delete operation to the session. - This is called as a result of the :meth:`.Query.delete` method. + This is called as a result of the :meth:`_query.Query.delete` method. :param delete_context: a "delete context" object which contains details about the update, including these attributes: * ``session`` - the :class:`.Session` involved - * ``query`` -the :class:`.Query` object that this update operation + * ``query`` -the :class:`_query.Query` + object that this update operation was called upon. * ``context`` The :class:`.QueryContext` object, corresponding to the invocation of an ORM query. @@ -2098,7 +2100,7 @@ class AttributeEvents(event.Events): replaced unconditionally, even if this requires firing off database loads. Note that ``active_history`` can also be set directly via :func:`.column_property` and - :func:`.relationship`. + :func:`_orm.relationship`. :param propagate=False: When True, the listener function will be established not just for the class attribute given, but @@ -2338,10 +2340,12 @@ class AttributeEvents(event.Events): Python's usual behavior of raising ``AttributeError``. The event here can be used to customize what value is actually returned, with the assumption that the event listener would be mirroring - a default generator that is configured on the Core :class:`.Column` + a default generator that is configured on the Core + :class:`_schema.Column` object as well. - Since a default generator on a :class:`.Column` might also produce + Since a default generator on a :class:`_schema.Column` + might also produce a changing value such as a timestamp, the :meth:`.AttributeEvents.init_scalar` event handler can also be used to **set** the newly returned value, so @@ -2375,7 +2379,7 @@ class AttributeEvents(event.Events): * By setting the value ``SOME_CONSTANT`` in the given ``dict_``, we indicate that this value is to be persisted to the database. This supersedes the use of ``SOME_CONSTANT`` in the default generator - for the :class:`.Column`. The ``active_column_defaults.py`` + for the :class:`_schema.Column`. The ``active_column_defaults.py`` example given at :ref:`examples_instrumentation` illustrates using the same approach for a changing default, e.g. a timestamp generator. In this particular example, it is not strictly @@ -2394,7 +2398,7 @@ class AttributeEvents(event.Events): In the above example, the attribute set event :meth:`.AttributeEvents.set` as well as the related validation feature - provided by :obj:`.orm.validates` is **not** invoked when we apply our + provided by :obj:`_orm.validates` is **not** invoked when we apply our value to the given ``dict_``. To have these events to invoke in response to our newly generated value, apply the value to the given object as a normal attribute set operation:: @@ -2467,7 +2471,7 @@ class AttributeEvents(event.Events): be the :class:`.InstanceState` object. :param collection: the new collection. This will always be generated from what was specified as - :paramref:`.relationship.collection_class`, and will always + :paramref:`_orm.relationship.collection_class`, and will always be empty. :param collection_adapter: the :class:`.CollectionAdapter` that will mediate internal access to the collection. @@ -2537,10 +2541,11 @@ class AttributeEvents(event.Events): class QueryEvents(event.Events): - """Represent events within the construction of a :class:`.Query` object. + """Represent events within the construction of a :class:`_query.Query` + object. The events here are intended to be used with an as-yet-unreleased - inspection system for :class:`.Query`. Some very basic operations + inspection system for :class:`_query.Query`. Some very basic operations are possible now, however the inspection system is intended to allow complex query manipulations to be automated. @@ -2552,8 +2557,9 @@ class QueryEvents(event.Events): _dispatch_target = Query def before_compile(self, query): - """Receive the :class:`.Query` object before it is composed into a - core :class:`.Select` object. + """Receive the :class:`_query.Query` + object before it is composed into a + core :class:`_expression.Select` object. This event is intended to allow changes to the query given:: @@ -2570,7 +2576,8 @@ class QueryEvents(event.Events): The :meth:`.QueryEvents.before_compile` event by default will disallow "baked" queries from caching a query, if the event - hook returns a new :class:`.Query` object. This affects both direct + hook returns a new :class:`_query.Query` object. + This affects both direct use of the baked query extension as well as its operation within lazy loaders and eager loaders for relationships. In order to re-establish the query being cached, apply the event adding the @@ -2592,7 +2599,7 @@ class QueryEvents(event.Events): .. versionadded:: 1.3.11 - added the "bake_ok" flag to the :meth:`.QueryEvents.before_compile` event and disallowed caching via the "baked" extension from occurring for event handlers that - return a new :class:`.Query` object if this flag is not set. + return a new :class:`_query.Query` object if this flag is not set. .. seealso:: @@ -2605,13 +2612,13 @@ class QueryEvents(event.Events): """ def before_compile_update(self, query, update_context): - """Allow modifications to the :class:`.Query` object within - :meth:`.Query.update`. + """Allow modifications to the :class:`_query.Query` object within + :meth:`_query.Query.update`. Like the :meth:`.QueryEvents.before_compile` event, if the event - is to be used to alter the :class:`.Query` object, it should + is to be used to alter the :class:`_query.Query` object, it should be configured with ``retval=True``, and the modified - :class:`.Query` object returned, as in :: + :class:`_query.Query` object returned, as in :: @event.listens_for(Query, "before_compile_update", retval=True) def no_deleted(query, update_context): @@ -2626,7 +2633,7 @@ class QueryEvents(event.Events): The ``.values`` dictionary of the "update context" object can also be modified in place as illustrated above. - :param query: a :class:`.Query` instance; this is also + :param query: a :class:`_query.Query` instance; this is also the ``.query`` attribute of the given "update context" object. @@ -2634,7 +2641,8 @@ class QueryEvents(event.Events): the same kind of object as described in :paramref:`.QueryEvents.after_bulk_update.update_context`. The object has a ``.values`` attribute in an UPDATE context which is - the dictionary of parameters passed to :meth:`.Query.update`. This + the dictionary of parameters passed to :meth:`_query.Query.update`. + This dictionary can be modified to alter the VALUES clause of the resulting UPDATE statement. @@ -2650,12 +2658,12 @@ class QueryEvents(event.Events): """ def before_compile_delete(self, query, delete_context): - """Allow modifications to the :class:`.Query` object within - :meth:`.Query.delete`. + """Allow modifications to the :class:`_query.Query` object within + :meth:`_query.Query.delete`. Like the :meth:`.QueryEvents.before_compile` event, this event should be configured with ``retval=True``, and the modified - :class:`.Query` object returned, as in :: + :class:`_query.Query` object returned, as in :: @event.listens_for(Query, "before_compile_delete", retval=True) def no_deleted(query, delete_context): @@ -2665,7 +2673,7 @@ class QueryEvents(event.Events): query = query.filter(entity.deleted == False) return query - :param query: a :class:`.Query` instance; this is also + :param query: a :class:`_query.Query` instance; this is also the ``.query`` attribute of the given "delete context" object. diff --git a/lib/sqlalchemy/orm/exc.py b/lib/sqlalchemy/orm/exc.py index 0c2565487..b04b844b3 100644 --- a/lib/sqlalchemy/orm/exc.py +++ b/lib/sqlalchemy/orm/exc.py @@ -111,7 +111,7 @@ class ObjectDeletedError(sa_exc.InvalidRequestError): row corresponding to an object's known primary key identity. A refresh operation proceeds when an expired attribute is - accessed on an object, or when :meth:`.Query.get` is + accessed on an object, or when :meth:`_query.Query.get` is used to retrieve an object which is, upon retrieval, detected as expired. A SELECT is emitted for the target row based on primary key; if no row is returned, this diff --git a/lib/sqlalchemy/orm/interfaces.py b/lib/sqlalchemy/orm/interfaces.py index 57c192a5d..612724357 100644 --- a/lib/sqlalchemy/orm/interfaces.py +++ b/lib/sqlalchemy/orm/interfaces.py @@ -65,12 +65,12 @@ __all__ = ( class MapperProperty( HasCacheKey, _MappedAttribute, InspectionAttr, util.MemoizedSlots ): - """Represent a particular class attribute mapped by :class:`.Mapper`. + """Represent a particular class attribute mapped by :class:`_orm.Mapper`. The most common occurrences of :class:`.MapperProperty` are the - mapped :class:`.Column`, which is represented in a mapping as + mapped :class:`_schema.Column`, which is represented in a mapping as an instance of :class:`.ColumnProperty`, - and a reference to another class produced by :func:`.relationship`, + and a reference to another class produced by :func:`_orm.relationship`, represented in the mapping as an instance of :class:`.RelationshipProperty`. @@ -110,7 +110,8 @@ class MapperProperty( The dictionary is generated when first accessed. Alternatively, it can be specified as a constructor argument to the - :func:`.column_property`, :func:`.relationship`, or :func:`.composite` + :func:`.column_property`, :func:`_orm.relationship`, or + :func:`.composite` functions. .. versionchanged:: 1.0.0 :attr:`.MapperProperty.info` is also @@ -389,7 +390,8 @@ class PropComparator(operators.ColumnOperators): """Receive a SQL expression that represents a value in the SET clause of an UPDATE statement. - Return a tuple that can be passed to a :class:`.Update` construct. + Return a tuple that can be passed to a :class:`_expression.Update` + construct. """ @@ -655,7 +657,7 @@ class MapperOption(object): """ def process_query(self, query): - """Apply a modification to the given :class:`.Query`.""" + """Apply a modification to the given :class:`_query.Query`.""" def process_query_conditionally(self, query): """same as process_query(), except that this option may not @@ -673,14 +675,15 @@ class MapperOption(object): def _generate_path_cache_key(self, path): """Used by the "baked lazy loader" to see if this option can be cached. - The "baked lazy loader" refers to the :class:`.Query` that is + The "baked lazy loader" refers to the :class:`_query.Query` that is produced during a lazy load operation for a mapped relationship. It does not yet apply to the "lazy" load operation for deferred or expired column attributes, however this may change in the future. This loader generates SQL for a query only once and attempts to cache it; from that point on, if the SQL has been cached it will no longer - run the :meth:`.Query.options` method of the :class:`.Query`. The + run the :meth:`_query.Query.options` method of the + :class:`_query.Query`. The :class:`.MapperOption` object that wishes to participate within a lazy load operation therefore needs to tell the baked loader that it either needs to forego this caching, or that it needs to include the state of @@ -694,7 +697,7 @@ class MapperOption(object): not cache the SQL when this :class:`.MapperOption` is present. This is the safest option and ensures both that the option is invoked every time, and also that the cache isn't filled up with - an unlimited number of :class:`.Query` objects for an unlimited + an unlimited number of :class:`_query.Query` objects for an unlimited number of :class:`.MapperOption` objects. .. versionchanged:: 1.2.8 the default return value of @@ -702,7 +705,8 @@ class MapperOption(object): was ``None`` indicating "safe to cache, don't include as part of the cache key" - To enable caching of :class:`.Query` objects within lazy loaders, a + To enable caching of :class:`_query.Query` objects within lazy loaders + , a given :class:`.MapperOption` that returns a cache key must return a key that uniquely identifies the complete state of this option, which will match any other :class:`.MapperOption` that itself retains the @@ -712,7 +716,7 @@ class MapperOption(object): If the :class:`.MapperOption` does not apply to the given path and would not affect query results on such a path, it should return None, - indicating the :class:`.Query` is safe to cache for this given + indicating the :class:`_query.Query` is safe to cache for this given loader path and that this :class:`.MapperOption` need not be part of the cache key. diff --git a/lib/sqlalchemy/orm/loading.py b/lib/sqlalchemy/orm/loading.py index b7ef96e1a..5ef2f10ec 100644 --- a/lib/sqlalchemy/orm/loading.py +++ b/lib/sqlalchemy/orm/loading.py @@ -106,7 +106,7 @@ def instances(query, cursor, context): @util.preload_module("sqlalchemy.orm.query") def merge_result(query, iterator, load=True): - """Merge a result into this :class:`.Query` object's Session.""" + """Merge a result into this :class:`_query.Query` object's Session.""" querylib = util.preloaded.orm_query session = query.session diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py index 3e4c3a5d5..31f005769 100644 --- a/lib/sqlalchemy/orm/mapper.py +++ b/lib/sqlalchemy/orm/mapper.py @@ -74,9 +74,9 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """Define the correlation of class attributes to database table columns. - The :class:`.Mapper` object is instantiated using the + The :class:`_orm.Mapper` object is instantiated using the :func:`~sqlalchemy.orm.mapper` function. For information - about instantiating new :class:`.Mapper` objects, see + about instantiating new :class:`_orm.Mapper` objects, see that function's documentation. @@ -89,8 +89,8 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): makes usage of :func:`.mapper` behind the scenes. Given a particular class known to be mapped by the ORM, - the :class:`.Mapper` which maintains it can be acquired - using the :func:`.inspect` function:: + the :class:`_orm.Mapper` which maintains it can be acquired + using the :func:`_sa.inspect` function:: from sqlalchemy import inspect @@ -113,7 +113,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): "and will be removed in a future release. The functionality " "of non primary mappers is now better suited using the " ":class:`.AliasedClass` construct, which can also be used " - "as the target of a :func:`.relationship` in 1.3.", + "as the target of a :func:`_orm.relationship` in 1.3.", ), ) def __init__( @@ -147,7 +147,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): legacy_is_orphan=False, _compiled_cache_size=100, ): - r"""Return a new :class:`~.Mapper` object. + r"""Return a new :class:`_orm.Mapper` object. This function is typically used behind the scenes via the Declarative extension. When using Declarative, @@ -196,21 +196,22 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): this argument is automatically passed as the declared class itself. - :param local_table: The :class:`.Table` or other selectable + :param local_table: The :class:`_schema.Table` or other selectable to which the class is mapped. May be ``None`` if this mapper inherits from another mapper using single-table inheritance. When using Declarative, this argument is automatically passed by the extension, based on what is configured via the ``__table__`` argument or via the - :class:`.Table` produced as a result of the ``__tablename__`` - and :class:`.Column` arguments present. + :class:`_schema.Table` + produced as a result of the ``__tablename__`` + and :class:`_schema.Column` arguments present. :param always_refresh: If True, all query operations for this mapped class will overwrite all data within object instances that already exist within the session, erasing any in-memory changes with whatever information was loaded from the database. Usage of this flag is highly discouraged; as an alternative, see the method - :meth:`.Query.populate_existing`. + :meth:`_query.Query.populate_existing`. :param allow_partial_pks: Defaults to True. Indicates that a composite primary key with some NULL values should be considered as @@ -229,7 +230,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): in between individual row persistence operations. :param column_prefix: A string which will be prepended - to the mapped attribute name when :class:`.Column` + to the mapped attribute name when :class:`_schema.Column` objects are automatically assigned as attributes to the mapped class. Does not affect explicitly specified column-based properties. @@ -283,8 +284,9 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): See :ref:`include_exclude_cols` for an example. - :param inherits: A mapped class or the corresponding :class:`.Mapper` - of one indicating a superclass to which this :class:`.Mapper` + :param inherits: A mapped class or the corresponding + :class:`_orm.Mapper` + of one indicating a superclass to which this :class:`_orm.Mapper` should *inherit* from. The mapped class here must be a subclass of the other mapper's class. When using Declarative, this argument is passed automatically as a result of the natural class @@ -300,7 +302,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): between the two tables. :param inherit_foreign_keys: When ``inherit_condition`` is used and - the columns present are missing a :class:`.ForeignKey` + the columns present are missing a :class:`_schema.ForeignKey` configuration, this parameter can be used to specify which columns are "foreign". In most cases can be left as ``None``. @@ -320,14 +322,15 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): See the change note and example at :ref:`legacy_is_orphan_addition` for more detail on this change. - :param non_primary: Specify that this :class:`.Mapper` is in addition + :param non_primary: Specify that this :class:`_orm.Mapper` + is in addition to the "primary" mapper, that is, the one used for persistence. - The :class:`.Mapper` created here may be used for ad-hoc + The :class:`_orm.Mapper` created here may be used for ad-hoc mapping of the class to an alternate selectable, for loading only. - :paramref:`.Mapper.non_primary` is not an often used option, but - is useful in some specific :func:`.relationship` cases. + :paramref:`_orm.Mapper.non_primary` is not an often used option, but + is useful in some specific :func:`_orm.relationship` cases. .. seealso:: @@ -362,7 +365,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): .. seealso:: :ref:`passive_deletes` - description of similar feature as - used with :func:`.relationship` + used with :func:`_orm.relationship` :paramref:`.mapper.passive_updates` - supporting ON UPDATE CASCADE for joined-table inheritance mappers @@ -385,7 +388,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): .. seealso:: :ref:`passive_updates` - description of a similar feature as - used with :func:`.relationship` + used with :func:`_orm.relationship` :paramref:`.mapper.passive_deletes` - supporting ON DELETE CASCADE for joined-table inheritance mappers @@ -415,8 +418,8 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): SQL expression used to determine the target class for an incoming row, when inheriting classes are present. - This value is commonly a :class:`.Column` object that's - present in the mapped :class:`.Table`:: + This value is commonly a :class:`_schema.Column` object that's + present in the mapped :class:`_schema.Table`:: class Employee(Base): __tablename__ = 'employee' @@ -471,7 +474,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): When setting ``polymorphic_on`` to reference an attribute or expression that's not present in the - locally mapped :class:`.Table`, yet the value + locally mapped :class:`_schema.Table`, yet the value of the discriminator should be persisted to the database, the value of the discriminator is not automatically set on new @@ -513,20 +516,22 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): :param properties: A dictionary mapping the string names of object attributes to :class:`.MapperProperty` instances, which define the - persistence behavior of that attribute. Note that :class:`.Column` + persistence behavior of that attribute. Note that + :class:`_schema.Column` objects present in - the mapped :class:`.Table` are automatically placed into + the mapped :class:`_schema.Table` are automatically placed into ``ColumnProperty`` instances upon mapping, unless overridden. When using Declarative, this argument is passed automatically, based on all those :class:`.MapperProperty` instances declared in the declared class body. - :param primary_key: A list of :class:`.Column` objects which define + :param primary_key: A list of :class:`_schema.Column` + objects which define the primary key to be used against this mapper's selectable unit. This is normally simply the primary key of the ``local_table``, but can be overridden here. - :param version_id_col: A :class:`.Column` + :param version_id_col: A :class:`_schema.Column` that will be used to keep a running version id of rows in the table. This is used to detect concurrent updates or the presence of stale data in a flush. The methodology is to @@ -721,34 +726,38 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): return self.class_ local_table = None - """The :class:`.Selectable` which this :class:`.Mapper` manages. + """The :class:`expression.Selectable` which this :class:`_orm.Mapper` + manages. - Typically is an instance of :class:`.Table` or :class:`.Alias`. + Typically is an instance of :class:`_schema.Table` or + :class:`_expression.Alias`. May also be ``None``. The "local" table is the - selectable that the :class:`.Mapper` is directly responsible for + selectable that the :class:`_orm.Mapper` is directly responsible for managing from an attribute access and flush perspective. For non-inheriting mappers, the local table is the same as the "mapped" table. For joined-table inheritance mappers, local_table will be the particular sub-table of the overall "join" which - this :class:`.Mapper` represents. If this mapper is a + this :class:`_orm.Mapper` represents. If this mapper is a single-table inheriting mapper, local_table will be ``None``. .. seealso:: - :attr:`~.Mapper.persist_selectable`. + :attr:`_orm.Mapper.persist_selectable`. """ persist_selectable = None - """The :class:`.Selectable` to which this :class:`.Mapper` is mapped. + """The :class:`expression.Selectable` to which this :class:`_orm.Mapper` + is mapped. - Typically an instance of :class:`.Table`, :class:`.Join`, or - :class:`.Alias`. + Typically an instance of :class:`_schema.Table`, :class:`_expression.Join` + , or + :class:`_expression.Alias`. - The :attr:`.Mapper.persist_selectable` is separate from - :attr:`.Mapper.selectable` in that the former represents columns + The :attr:`_orm.Mapper.persist_selectable` is separate from + :attr:`_orm.Mapper.selectable` in that the former represents columns that are mapped on this class or its superclasses, whereas the latter may be a "polymorphic" selectable that contains additional columns which are in fact mapped on subclasses only. @@ -756,21 +765,21 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): "persist selectable" is the "thing the mapper writes to" and "selectable" is the "thing the mapper selects from". - :attr:`.Mapper.persist_selectable` is also separate from - :attr:`.Mapper.local_table`, which represents the set of columns that + :attr:`_orm.Mapper.persist_selectable` is also separate from + :attr:`_orm.Mapper.local_table`, which represents the set of columns that are locally mapped on this class directly. .. seealso:: - :attr:`~.Mapper.selectable`. + :attr:`_orm.Mapper.selectable`. - :attr:`~.Mapper.local_table`. + :attr:`_orm.Mapper.local_table`. """ inherits = None - """References the :class:`.Mapper` which this :class:`.Mapper` + """References the :class:`_orm.Mapper` which this :class:`_orm.Mapper` inherits from, if any. This is a *read only* attribute determined during mapper construction. @@ -779,7 +788,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ configured = None - """Represent ``True`` if this :class:`.Mapper` has been configured. + """Represent ``True`` if this :class:`_orm.Mapper` has been configured. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. @@ -791,7 +800,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ concrete = None - """Represent ``True`` if this :class:`.Mapper` is a concrete + """Represent ``True`` if this :class:`_orm.Mapper` is a concrete inheritance mapper. This is a *read only* attribute determined during mapper construction. @@ -800,11 +809,13 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ tables = None - """An iterable containing the collection of :class:`.Table` objects - which this :class:`.Mapper` is aware of. + """An iterable containing the collection of :class:`_schema.Table` objects + which this :class:`_orm.Mapper` is aware of. - If the mapper is mapped to a :class:`.Join`, or an :class:`.Alias` - representing a :class:`.Select`, the individual :class:`.Table` + If the mapper is mapped to a :class:`_expression.Join`, or an + :class:`_expression.Alias` + representing a :class:`_expression.Select`, the individual + :class:`_schema.Table` objects that comprise the full construct will be represented here. This is a *read only* attribute determined during mapper construction. @@ -813,20 +824,23 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ primary_key = None - """An iterable containing the collection of :class:`.Column` objects + """An iterable containing the collection of :class:`_schema.Column` + objects which comprise the 'primary key' of the mapped table, from the - perspective of this :class:`.Mapper`. + perspective of this :class:`_orm.Mapper`. - This list is against the selectable in :attr:`~.Mapper.persist_selectable`. + This list is against the selectable in + :attr:`_orm.Mapper.persist_selectable`. In the case of inheriting mappers, some columns may be managed by a - superclass mapper. For example, in the case of a :class:`.Join`, the + superclass mapper. For example, in the case of a + :class:`_expression.Join`, the primary key is determined by all of the primary key columns across all - tables referenced by the :class:`.Join`. + tables referenced by the :class:`_expression.Join`. The list is also not necessarily the same as the primary key column - collection associated with the underlying tables; the :class:`.Mapper` + collection associated with the underlying tables; the :class:`_orm.Mapper` features a ``primary_key`` argument that can override what the - :class:`.Mapper` considers as primary key columns. + :class:`_orm.Mapper` considers as primary key columns. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. @@ -834,7 +848,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ class_ = None - """The Python class which this :class:`.Mapper` maps. + """The Python class which this :class:`_orm.Mapper` maps. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. @@ -843,7 +857,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): class_manager = None """The :class:`.ClassManager` which maintains event listeners - and class-bound descriptors for this :class:`.Mapper`. + and class-bound descriptors for this :class:`_orm.Mapper`. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. @@ -851,10 +865,10 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ single = None - """Represent ``True`` if this :class:`.Mapper` is a single table + """Represent ``True`` if this :class:`_orm.Mapper` is a single table inheritance mapper. - :attr:`~.Mapper.local_table` will be ``None`` if this flag is set. + :attr:`_orm.Mapper.local_table` will be ``None`` if this flag is set. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. @@ -862,7 +876,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ non_primary = None - """Represent ``True`` if this :class:`.Mapper` is a "non-primary" + """Represent ``True`` if this :class:`_orm.Mapper` is a "non-primary" mapper, e.g. a mapper that is used only to select rows but not for persistence management. @@ -872,11 +886,11 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ polymorphic_on = None - """The :class:`.Column` or SQL expression specified as the + """The :class:`_schema.Column` or SQL expression specified as the ``polymorphic_on`` argument - for this :class:`.Mapper`, within an inheritance scenario. + for this :class:`_orm.Mapper`, within an inheritance scenario. - This attribute is normally a :class:`.Column` instance but + This attribute is normally a :class:`_schema.Column` instance but may also be an expression, such as one derived from :func:`.cast`. @@ -887,10 +901,10 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): polymorphic_map = None """A mapping of "polymorphic identity" identifiers mapped to - :class:`.Mapper` instances, within an inheritance scenario. + :class:`_orm.Mapper` instances, within an inheritance scenario. The identifiers can be of any type which is comparable to the - type of column represented by :attr:`~.Mapper.polymorphic_on`. + type of column represented by :attr:`_orm.Mapper.polymorphic_on`. An inheritance chain of mappers will all reference the same polymorphic map object. The object is used to correlate incoming @@ -903,11 +917,11 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): polymorphic_identity = None """Represent an identifier which is matched against the - :attr:`~.Mapper.polymorphic_on` column during result row loading. + :attr:`_orm.Mapper.polymorphic_on` column during result row loading. Used only with inheritance, this object can be of any type which is comparable to the type of column represented by - :attr:`~.Mapper.polymorphic_on`. + :attr:`_orm.Mapper.polymorphic_on`. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. @@ -915,11 +929,11 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ base_mapper = None - """The base-most :class:`.Mapper` in an inheritance chain. + """The base-most :class:`_orm.Mapper` in an inheritance chain. In a non-inheriting scenario, this attribute will always be this - :class:`.Mapper`. In an inheritance scenario, it references - the :class:`.Mapper` which is parent to all other :class:`.Mapper` + :class:`_orm.Mapper`. In an inheritance scenario, it references + the :class:`_orm.Mapper` which is parent to all other :class:`_orm.Mapper` objects in the inheritance chain. This is a *read only* attribute determined during mapper construction. @@ -928,14 +942,15 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ columns = None - """A collection of :class:`.Column` or other scalar expression - objects maintained by this :class:`.Mapper`. + """A collection of :class:`_schema.Column` or other scalar expression + objects maintained by this :class:`_orm.Mapper`. The collection behaves the same as that of the ``c`` attribute on - any :class:`.Table` object, except that only those columns included in + any :class:`_schema.Table` object, + except that only those columns included in this mapping are present, and are keyed based on the attribute name defined in the mapping, not necessarily the ``key`` attribute of the - :class:`.Column` itself. Additionally, scalar expressions mapped + :class:`_schema.Column` itself. Additionally, scalar expressions mapped by :func:`.column_property` are also present here. This is a *read only* attribute determined during mapper construction. @@ -945,7 +960,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): validators = None """An immutable dictionary of attributes which have been decorated - using the :func:`~.orm.validates` decorator. + using the :func:`_orm.validates` decorator. The dictionary contains string attribute names as keys mapped to the actual validation method. @@ -953,7 +968,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ c = None - """A synonym for :attr:`~.Mapper.columns`.""" + """A synonym for :attr:`_orm.Mapper.columns`.""" @property @util.deprecated("1.3", "Use .persist_selectable") @@ -1139,8 +1154,8 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): ) def _set_concrete_base(self, mapper): - """Set the given :class:`.Mapper` as the 'inherits' for this - :class:`.Mapper`, assuming this :class:`.Mapper` is concrete + """Set the given :class:`_orm.Mapper` as the 'inherits' for this + :class:`_orm.Mapper`, assuming this :class:`_orm.Mapper` is concrete and does not already have an inherits.""" assert self.concrete @@ -1778,7 +1793,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): @util.preload_module("sqlalchemy.orm.descriptor_props") def _property_from_column(self, key, prop): """generate/update a :class:`.ColumnProperty` given a - :class:`.Column` object. """ + :class:`_schema.Column` object. """ descriptor_props = util.preloaded.orm_descriptor_props # we were passed a Column or a list of Columns; # generate a properties.ColumnProperty @@ -1979,7 +1994,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): ) def get_property_by_column(self, column): - """Given a :class:`.Column` object, return the + """Given a :class:`_schema.Column` object, return the :class:`.MapperProperty` which maps this column.""" return self._columntoproperty[column] @@ -2083,7 +2098,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): ) with_polymorphic_mappers = _with_polymorphic_mappers - """The list of :class:`.Mapper` objects included in the + """The list of :class:`_orm.Mapper` objects included in the default "polymorphic" query. """ @@ -2201,8 +2216,8 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): @property def selectable(self): - """The :func:`~.sql.expression.select` construct this - :class:`.Mapper` selects from by default. + """The :func:`_expression.select` construct this + :class:`_orm.Mapper` selects from by default. Normally, this is equivalent to :attr:`.persist_selectable`, unless the ``with_polymorphic`` feature is in use, in which case the @@ -2281,14 +2296,14 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): column. The namespace object can also be iterated, which would yield each :class:`.MapperProperty`. - :class:`.Mapper` has several pre-filtered views + :class:`_orm.Mapper` has several pre-filtered views of this attribute which limit the types of properties returned, including :attr:`.synonyms`, :attr:`.column_attrs`, :attr:`.relationships`, and :attr:`.composites`. .. warning:: - The :attr:`.Mapper.attrs` accessor namespace is an + The :attr:`_orm.Mapper.attrs` accessor namespace is an instance of :class:`.OrderedProperties`. This is a dictionary-like object which includes a small number of named methods such as :meth:`.OrderedProperties.items` @@ -2299,7 +2314,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): .. seealso:: - :attr:`.Mapper.all_orm_descriptors` + :attr:`_orm.Mapper.all_orm_descriptors` """ if Mapper._new_mappers: @@ -2330,11 +2345,12 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): :attr:`.QueryableAttribute.property` attribute refers to the :class:`.MapperProperty` property, which is what you get when referring to the collection of mapped properties via - :attr:`.Mapper.attrs`. + :attr:`_orm.Mapper.attrs`. .. warning:: - The :attr:`.Mapper.all_orm_descriptors` accessor namespace is an + The :attr:`_orm.Mapper.all_orm_descriptors` + accessor namespace is an instance of :class:`.OrderedProperties`. This is a dictionary-like object which includes a small number of named methods such as :meth:`.OrderedProperties.items` @@ -2346,7 +2362,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): .. seealso:: - :attr:`.Mapper.attrs` + :attr:`_orm.Mapper.attrs` """ return util.ImmutableProperties( @@ -2357,11 +2373,12 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): @util.preload_module("sqlalchemy.orm.descriptor_props") def synonyms(self): """Return a namespace of all :class:`.SynonymProperty` - properties maintained by this :class:`.Mapper`. + properties maintained by this :class:`_orm.Mapper`. .. seealso:: - :attr:`.Mapper.attrs` - namespace of all :class:`.MapperProperty` + :attr:`_orm.Mapper.attrs` - namespace of all + :class:`.MapperProperty` objects. """ @@ -2372,11 +2389,12 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): @HasMemoized.memoized_attribute def column_attrs(self): """Return a namespace of all :class:`.ColumnProperty` - properties maintained by this :class:`.Mapper`. + properties maintained by this :class:`_orm.Mapper`. .. seealso:: - :attr:`.Mapper.attrs` - namespace of all :class:`.MapperProperty` + :attr:`_orm.Mapper.attrs` - namespace of all + :class:`.MapperProperty` objects. """ @@ -2386,11 +2404,11 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): @HasMemoized.memoized_attribute def relationships(self): """A namespace of all :class:`.RelationshipProperty` properties - maintained by this :class:`.Mapper`. + maintained by this :class:`_orm.Mapper`. .. warning:: - the :attr:`.Mapper.relationships` accessor namespace is an + the :attr:`_orm.Mapper.relationships` accessor namespace is an instance of :class:`.OrderedProperties`. This is a dictionary-like object which includes a small number of named methods such as :meth:`.OrderedProperties.items` @@ -2402,7 +2420,8 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): .. seealso:: - :attr:`.Mapper.attrs` - namespace of all :class:`.MapperProperty` + :attr:`_orm.Mapper.attrs` - namespace of all + :class:`.MapperProperty` objects. """ @@ -2414,11 +2433,12 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): @util.preload_module("sqlalchemy.orm.descriptor_props") def composites(self): """Return a namespace of all :class:`.CompositeProperty` - properties maintained by this :class:`.Mapper`. + properties maintained by this :class:`_orm.Mapper`. .. seealso:: - :attr:`.Mapper.attrs` - namespace of all :class:`.MapperProperty` + :attr:`_orm.Mapper.attrs` - namespace of all + :class:`.MapperProperty` objects. """ @@ -2638,9 +2658,10 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): item from the identity map. :param row: A :class:`.Row` instance. The columns which are - mapped by this :class:`.Mapper` should be locatable in the row, - preferably via the :class:`.Column` object directly (as is the case - when a :func:`~.sql.expression.select` construct is executed), or + mapped by this :class:`_orm.Mapper` should be locatable in the row, + preferably via the :class:`_schema.Column` + object directly (as is the case + when a :func:`_expression.select` construct is executed), or via string names of the form ``<tablename>_<colname>``. """ @@ -3157,13 +3178,13 @@ def configure_mappers(): proceeds. * :meth:`.MapperEvents.mapper_configured` - called as each individual - :class:`.Mapper` is configured within the process; will include all + :class:`_orm.Mapper` is configured within the process; will include all mapper state except for backrefs set up by other mappers that are still to be configured. * :meth:`.MapperEvents.after_configured` - called once after :func:`.configure_mappers` is complete; at this stage, all - :class:`.Mapper` objects that are known to SQLAlchemy will be fully + :class:`_orm.Mapper` objects that are known to SQLAlchemy will be fully configured. Note that the calling application may still have other mappings that haven't been produced yet, such as if they are in modules as yet unimported. diff --git a/lib/sqlalchemy/orm/persistence.py b/lib/sqlalchemy/orm/persistence.py index 1460ae208..87bc8ea1d 100644 --- a/lib/sqlalchemy/orm/persistence.py +++ b/lib/sqlalchemy/orm/persistence.py @@ -6,7 +6,7 @@ # the MIT License: http://www.opensource.org/licenses/mit-license.php """private module containing functions used to emit INSERT, UPDATE -and DELETE statements on behalf of a :class:`.Mapper` and its descending +and DELETE statements on behalf of a :class:`_orm.Mapper` and its descending mappers. The functions here are called only by the unit of work functions @@ -1649,7 +1649,7 @@ def _sort_states(mapper, states): class BulkUD(object): - """Handle bulk update and deletes via a :class:`.Query`.""" + """Handle bulk update and deletes via a :class:`_query.Query`.""" def __init__(self, query): self.query = query.enable_eagerloads(False) diff --git a/lib/sqlalchemy/orm/properties.py b/lib/sqlalchemy/orm/properties.py index 05904d1a9..1022f4ef6 100644 --- a/lib/sqlalchemy/orm/properties.py +++ b/lib/sqlalchemy/orm/properties.py @@ -40,7 +40,7 @@ __all__ = [ class ColumnProperty(StrategizedProperty): """Describes an object attribute that corresponds to a table column. - Public constructor is the :func:`.orm.column_property` function. + Public constructor is the :func:`_orm.column_property` function. """ @@ -71,12 +71,13 @@ class ColumnProperty(StrategizedProperty): r"""Provide a column-level property for use with a mapping. Column-based properties can normally be applied to the mapper's - ``properties`` dictionary using the :class:`.Column` element directly. + ``properties`` dictionary using the :class:`_schema.Column` + element directly. Use this function when the given column is not directly present within the mapper's selectable; examples include SQL expressions, functions, and scalar SELECT queries. - The :func:`.orm.column_property` function returns an instance of + The :func:`_orm.column_property` function returns an instance of :class:`.ColumnProperty`. Columns that aren't present in the mapper's selectable won't be diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py index e131a4aa3..ce051cdcb 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -7,11 +7,11 @@ """The Query class and support. -Defines the :class:`.Query` class, the central +Defines the :class:`_query.Query` class, the central construct used by the ORM to construct database queries. -The :class:`.Query` class should not be confused with the -:class:`.Select` class, which defines database +The :class:`_query.Query` class should not be confused with the +:class:`_expression.Select` class, which defines database SELECT operations at the SQL (non-ORM) level. ``Query`` differs from ``Select`` in that it returns ORM-mapped objects and interacts with an ORM session, whereas the ``Select`` construct interacts directly with the @@ -70,20 +70,22 @@ _path_registry = PathRegistry.root class Query(Generative): """ORM-level SQL construction object. - :class:`.Query` is the source of all SELECT statements generated by the + :class:`_query.Query` + is the source of all SELECT statements generated by the ORM, both those formulated by end-user query operations as well as by high level internal operations such as related collection loading. It features a generative interface whereby successive calls return a new - :class:`.Query` object, a copy of the former with additional + :class:`_query.Query` object, a copy of the former with additional criteria and options associated with it. - :class:`.Query` objects are normally initially generated using the + :class:`_query.Query` objects are normally initially generated using the :meth:`~.Session.query` method of :class:`.Session`, and in - less common cases by instantiating the :class:`.Query` directly and - associating with a :class:`.Session` using the :meth:`.Query.with_session` + less common cases by instantiating the :class:`_query.Query` directly and + associating with a :class:`.Session` using the + :meth:`_query.Query.with_session` method. - For a full walkthrough of :class:`.Query` usage, see the + For a full walkthrough of :class:`_query.Query` usage, see the :ref:`ormtutorial_toplevel`. """ @@ -131,7 +133,8 @@ class Query(Generative): _bake_ok = True lazy_loaded_from = None - """An :class:`.InstanceState` that is using this :class:`.Query` for a + """An :class:`.InstanceState` that is using this :class:`_query.Query` + for a lazy load operation. The primary rationale for this attribute is to support the horizontal @@ -143,7 +146,8 @@ class Query(Generative): .. note:: - Within the realm of regular :class:`.Query` usage, this attribute is + Within the realm of regular :class:`_query.Query` usage, + this attribute is set by the lazy loader strategy before the query is invoked. However there is no established hook that is available to reliably intercept this value programmatically. It is set by the lazy loading strategy @@ -152,12 +156,14 @@ class Query(Generative): cache SQL compilation, the :meth:`.QueryEvents.before_compile` hook is also not reliable. - Currently, setting the :paramref:`.relationship.bake_queries` to - ``False`` on the target :func:`.relationship`, and then making use of + Currently, setting the :paramref:`_orm.relationship.bake_queries` to + ``False`` on the target :func:`_orm.relationship`, + and then making use of the :meth:`.QueryEvents.before_compile` event hook, is the only available programmatic path to intercepting this attribute. In future releases, there will be new hooks available that allow interception of - the :class:`.Query` before it is executed, rather than before it is + the :class:`_query.Query` before it is executed, + rather than before it is compiled. .. versionadded:: 1.2.9 @@ -165,7 +171,7 @@ class Query(Generative): """ def __init__(self, entities, session=None): - """Construct a :class:`.Query` directly. + """Construct a :class:`_query.Query` directly. E.g.:: @@ -177,16 +183,18 @@ class Query(Generative): :param entities: a sequence of entities and/or SQL expressions. - :param session: a :class:`.Session` with which the :class:`.Query` - will be associated. Optional; a :class:`.Query` can be associated + :param session: a :class:`.Session` with which the + :class:`_query.Query` + will be associated. Optional; a :class:`_query.Query` + can be associated with a :class:`.Session` generatively via the - :meth:`.Query.with_session` method as well. + :meth:`_query.Query.with_session` method as well. .. seealso:: :meth:`.Session.query` - :meth:`.Query.with_session` + :meth:`_query.Query.with_session` """ self.session = session @@ -535,21 +543,23 @@ class Query(Generative): def subquery(self, name=None, with_labels=False, reduce_columns=False): """return the full SELECT statement represented by - this :class:`.Query`, embedded within an :class:`.Alias`. + this :class:`_query.Query`, embedded within an + :class:`_expression.Alias`. Eager JOIN generation within the query is disabled. :param name: string name to be assigned as the alias; - this is passed through to :meth:`.FromClause.alias`. + this is passed through to :meth:`_expression.FromClause.alias`. If ``None``, a name will be deterministically generated at compile time. :param with_labels: if True, :meth:`.with_labels` will be called - on the :class:`.Query` first to apply table-qualified labels + on the :class:`_query.Query` first to apply table-qualified labels to all columns. - :param reduce_columns: if True, :meth:`.Select.reduce_columns` will - be called on the resulting :func:`~.sql.expression.select` construct, + :param reduce_columns: if True, + :meth:`_expression.Select.reduce_columns` will + be called on the resulting :func:`_expression.select` construct, to remove same-named columns where one also refers to the other via foreign key or WHERE clause equivalence. @@ -565,10 +575,10 @@ class Query(Generative): def cte(self, name=None, recursive=False): r"""Return the full SELECT statement represented by this - :class:`.Query` represented as a common table expression (CTE). + :class:`_query.Query` represented as a common table expression (CTE). Parameters and usage are the same as those of the - :meth:`.SelectBase.cte` method; see that method for + :meth:`_expression.SelectBase.cte` method; see that method for further details. Here is the `PostgreSQL WITH @@ -577,7 +587,7 @@ class Query(Generative): Note that, in this example, the ``included_parts`` cte and the ``incl_alias`` alias of it are Core selectables, which means the columns are accessed via the ``.c.`` attribute. The - ``parts_alias`` object is an :func:`.orm.aliased` instance of the + ``parts_alias`` object is an :func:`_orm.aliased` instance of the ``Part`` entity, so column-mapped attributes are available directly:: @@ -615,7 +625,7 @@ class Query(Generative): .. seealso:: - :meth:`.HasCTE.cte` + :meth:`_expression.HasCTE.cte` """ return self.enable_eagerloads(False).statement.cte( @@ -624,7 +634,7 @@ class Query(Generative): def label(self, name): """Return the full SELECT statement represented by this - :class:`.Query`, converted + :class:`_query.Query`, converted to a scalar subquery with a label of the given name. Analogous to :meth:`sqlalchemy.sql.expression.SelectBase.label`. @@ -635,26 +645,27 @@ class Query(Generative): @util.deprecated( "1.4", - "The :meth:`.Query.as_scalar` method is deprecated and will be " + "The :meth:`_query.Query.as_scalar` method is deprecated and will be " "removed in a future release. Please refer to " - ":meth:`.Query.scalar_subquery`.", + ":meth:`_query.Query.scalar_subquery`.", ) def as_scalar(self): """Return the full SELECT statement represented by this - :class:`.Query`, converted to a scalar subquery. + :class:`_query.Query`, converted to a scalar subquery. """ return self.scalar_subquery() def scalar_subquery(self): """Return the full SELECT statement represented by this - :class:`.Query`, converted to a scalar subquery. + :class:`_query.Query`, converted to a scalar subquery. Analogous to :meth:`sqlalchemy.sql.expression.SelectBase.scalar_subquery`. - .. versionchanged:: 1.4 the :meth:`.Query.scalar_subquery` method - replaces the :meth:`.Query.as_scalar` method. + .. versionchanged:: 1.4 the :meth:`_query.Query.scalar_subquery` + method + replaces the :meth:`_query.Query.as_scalar` method. """ return self.enable_eagerloads(False).statement.scalar_subquery() @@ -672,14 +683,15 @@ class Query(Generative): .. seealso:: - :meth:`.Query.is_single_entity` + :meth:`_query.Query.is_single_entity` """ self._only_return_tuples = value @property def is_single_entity(self): - """Indicates if this :class:`.Query` returns tuples or single entities. + """Indicates if this :class:`_query.Query` + returns tuples or single entities. Returns True if this query returns a single entity for each instance in its result list, and False if this query returns a tuple of entities @@ -689,7 +701,7 @@ class Query(Generative): .. seealso:: - :meth:`.Query.only_return_tuples` + :meth:`_query.Query.only_return_tuples` """ return ( @@ -711,7 +723,7 @@ class Query(Generative): This is used primarily when nesting the Query's statement into a subquery or other - selectable, or when using :meth:`.Query.yield_per`. + selectable, or when using :meth:`_query.Query.yield_per`. """ self._enable_eagerloads = value @@ -738,12 +750,14 @@ class Query(Generative): When the `Query` actually issues SQL to load rows, it always uses column labeling. - .. note:: The :meth:`.Query.with_labels` method *only* applies - the output of :attr:`.Query.statement`, and *not* to any of - the result-row invoking systems of :class:`.Query` itself, e.g. - :meth:`.Query.first`, :meth:`.Query.all`, etc. To execute - a query using :meth:`.Query.with_labels`, invoke the - :attr:`.Query.statement` using :meth:`.Session.execute`:: + .. note:: The :meth:`_query.Query.with_labels` method *only* applies + the output of :attr:`_query.Query.statement`, and *not* to any of + the result-row invoking systems of :class:`_query.Query` itself, e. + g. + :meth:`_query.Query.first`, :meth:`_query.Query.all`, etc. + To execute + a query using :meth:`_query.Query.with_labels`, invoke the + :attr:`_query.Query.statement` using :meth:`.Session.execute`:: result = session.execute(query.with_labels().statement) @@ -803,9 +817,9 @@ class Query(Generative): ): """Load columns for inheriting classes. - :meth:`.Query.with_polymorphic` applies transformations - to the "main" mapped class represented by this :class:`.Query`. - The "main" mapped class here means the :class:`.Query` + :meth:`_query.Query.with_polymorphic` applies transformations + to the "main" mapped class represented by this :class:`_query.Query`. + The "main" mapped class here means the :class:`_query.Query` object's first argument is a full class, i.e. ``session.query(SomeClass)``. These transformations allow additional tables to be present in the FROM clause so that columns for a @@ -849,7 +863,7 @@ class Query(Generative): (e.g. approximately 1000) is used, even with DBAPIs that buffer rows (which are most). - The :meth:`.Query.yield_per` method **is not compatible + The :meth:`_query.Query.yield_per` method **is not compatible subqueryload eager loading or joinedload eager loading when using collections**. It is potentially compatible with "select in" eager loading, **provided the database driver supports multiple, @@ -858,7 +872,7 @@ class Query(Generative): Therefore in some cases, it may be helpful to disable eager loads, either unconditionally with - :meth:`.Query.enable_eagerloads`:: + :meth:`_query.Query.enable_eagerloads`:: q = sess.query(Object).yield_per(100).enable_eagerloads(False) @@ -898,7 +912,7 @@ class Query(Generative): .. seealso:: - :meth:`.Query.enable_eagerloads` + :meth:`_query.Query.enable_eagerloads` """ self._yield_per = count @@ -919,7 +933,7 @@ class Query(Generative): some_object = session.query(VersionedFoo).get( {"id": 5, "version_id": 10}) - :meth:`~.Query.get` is special in that it provides direct + :meth:`_query.Query.get` is special in that it provides direct access to the identity map of the owning :class:`.Session`. If the given primary key identifier is present in the local identity map, the object is returned @@ -928,28 +942,28 @@ class Query(Generative): If not present, a SELECT is performed in order to locate the object. - :meth:`~.Query.get` also will perform a check if + :meth:`_query.Query.get` also will perform a check if the object is present in the identity map and marked as expired - a SELECT is emitted to refresh the object as well as to ensure that the row is still present. If not, :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised. - :meth:`~.Query.get` is only used to return a single + :meth:`_query.Query.get` is only used to return a single mapped instance, not multiple instances or individual column constructs, and strictly on a single primary key value. The originating - :class:`.Query` must be constructed in this way, + :class:`_query.Query` must be constructed in this way, i.e. against a single mapped entity, with no additional filtering criterion. Loading - options via :meth:`~.Query.options` may be applied + options via :meth:`_query.Query.options` may be applied however, and will be used if the object is not yet locally present. A lazy-loading, many-to-one attribute configured - by :func:`.relationship`, using a simple + by :func:`_orm.relationship`, using a simple foreign-key-to-primary-key criterion, will also use an - operation equivalent to :meth:`~.Query.get` in order to retrieve + operation equivalent to :meth:`_query.Query.get` in order to retrieve the target value from the local identity map before querying the database. See :doc:`/orm/loading_relationships` for further details on relationship loading. @@ -965,9 +979,11 @@ class Query(Generative): my_object = query.get(5) The tuple form contains primary key values typically in - the order in which they correspond to the mapped :class:`.Table` + the order in which they correspond to the mapped + :class:`_schema.Table` object's primary key columns, or if the - :paramref:`.Mapper.primary_key` configuration parameter were used, in + :paramref:`_orm.Mapper.primary_key` configuration parameter were used + , in the order used for that parameter. For example, if the primary key of a row is represented by the integer digits "5, 10" the call would look like:: @@ -981,7 +997,8 @@ class Query(Generative): my_object = query.get({"id": 5, "version_id": 10}) - .. versionadded:: 1.3 the :meth:`.Query.get` method now optionally + .. versionadded:: 1.3 the :meth:`_query.Query.get` + method now optionally accepts a dictionary of attribute names to values in order to indicate a primary key identifier. @@ -1056,9 +1073,10 @@ class Query(Generative): @_generative def correlate(self, *args): - """Return a :class:`.Query` construct which will correlate the given - FROM clauses to that of an enclosing :class:`.Query` or - :func:`~.expression.select`. + """Return a :class:`_query.Query` + construct which will correlate the given + FROM clauses to that of an enclosing :class:`_query.Query` or + :func:`_expression.select`. The method here accepts mapped classes, :func:`.aliased` constructs, and :func:`.mapper` constructs as arguments, which are resolved into @@ -1066,12 +1084,13 @@ class Query(Generative): constructs. The correlation arguments are ultimately passed to - :meth:`.Select.correlate` after coercion to expression constructs. + :meth:`_expression.Select.correlate` + after coercion to expression constructs. The correlation arguments take effect in such cases - as when :meth:`.Query.from_self` is used, or when - a subquery as returned by :meth:`.Query.subquery` is - embedded in another :func:`~.expression.select` construct. + as when :meth:`_query.Query.from_self` is used, or when + a subquery as returned by :meth:`_query.Query.subquery` is + embedded in another :func:`_expression.select` construct. """ @@ -1099,7 +1118,8 @@ class Query(Generative): @_generative def populate_existing(self): - """Return a :class:`.Query` that will expire and refresh all instances + """Return a :class:`_query.Query` + that will expire and refresh all instances as they are loaded, or reused from the current :class:`.Session`. :meth:`.populate_existing` does not improve behavior when @@ -1117,7 +1137,7 @@ class Query(Generative): subquery loaders to traverse into already-loaded related objects and collections. - Default is that of :attr:`.Query._invoke_all_eagers`. + Default is that of :attr:`_query.Query._invoke_all_eagers`. """ self._invoke_all_eagers = value @@ -1126,18 +1146,19 @@ class Query(Generative): def with_parent(self, instance, property=None, from_entity=None): # noqa """Add filtering criterion that relates the given instance to a child object or collection, using its attribute state - as well as an established :func:`.relationship()` + as well as an established :func:`_orm.relationship()` configuration. The method uses the :func:`.with_parent` function to generate - the clause, the result of which is passed to :meth:`.Query.filter`. + the clause, the result of which is passed to + :meth:`_query.Query.filter`. Parameters are the same as :func:`.with_parent`, with the exception that the given property can be None, in which case a search is - performed against this :class:`.Query` object's target mapper. + performed against this :class:`_query.Query` object's target mapper. :param instance: - An instance which has some :func:`.relationship`. + An instance which has some :func:`_orm.relationship`. :param property: String property name, or class-bound attribute, which indicates @@ -1146,7 +1167,7 @@ class Query(Generative): :param from_entity: Entity in which to consider as the left side. This defaults to the - "zero" entity of the :class:`.Query` itself. + "zero" entity of the :class:`_query.Query` itself. """ relationships = util.preloaded.orm_relationships @@ -1191,13 +1212,18 @@ class Query(Generative): @_generative def with_session(self, session): - """Return a :class:`.Query` that will use the given :class:`.Session`. + """Return a :class:`_query.Query` that will use the given + :class:`.Session`. - While the :class:`.Query` object is normally instantiated using the - :meth:`.Session.query` method, it is legal to build the :class:`.Query` + While the :class:`_query.Query` + object is normally instantiated using the + :meth:`.Session.query` method, it is legal to build the + :class:`_query.Query` directly without necessarily using a :class:`.Session`. Such a - :class:`.Query` object, or any :class:`.Query` already associated - with a different :class:`.Session`, can produce a new :class:`.Query` + :class:`_query.Query` object, or any :class:`_query.Query` + already associated + with a different :class:`.Session`, can produce a new + :class:`_query.Query` object associated with a target session using this method:: from sqlalchemy.orm import Query @@ -1211,7 +1237,7 @@ class Query(Generative): self.session = session @util.deprecated_20( - ":meth:`.Query.from_self`", + ":meth:`_query.Query.from_self`", alternative="The new approach is to use the :func:`.orm.aliased` " "construct in conjunction with a subquery. See the section " ":ref:`Selecting from the query itself as a subquery " @@ -1222,12 +1248,12 @@ class Query(Generative): r"""return a Query that selects from this Query's SELECT statement. - :meth:`.Query.from_self` essentially turns the SELECT statement + :meth:`_query.Query.from_self` essentially turns the SELECT statement into a SELECT of itself. Given a query such as:: q = session.query(User).filter(User.name.like('e%')) - Given the :meth:`.Query.from_self` version:: + Given the :meth:`_query.Query.from_self` version:: q = session.query(User).filter(User.name.like('e%')).from_self() @@ -1241,7 +1267,8 @@ class Query(Generative): FROM "user" WHERE "user".name LIKE :name_1) AS anon_1 - There are lots of cases where :meth:`.Query.from_self` may be useful. + There are lots of cases where :meth:`_query.Query.from_self` + may be useful. A simple one is where above, we may want to apply a row LIMIT to the set of user objects we query against, and then apply additional joins against that row-limited set:: @@ -1266,7 +1293,8 @@ class Query(Generative): **Automatic Aliasing** - Another key behavior of :meth:`.Query.from_self` is that it applies + Another key behavior of :meth:`_query.Query.from_self` + is that it applies **automatic aliasing** to the entities inside the subquery, when they are referenced on the outside. Above, if we continue to refer to the ``User`` entity without any additional aliasing applied @@ -1295,13 +1323,15 @@ class Query(Generative): for simple filters and orderings. More ambitious constructions such as referring to the entity in joins should prefer to use explicit subquery objects, typically making use of the - :meth:`.Query.subquery` method to produce an explicit subquery object. + :meth:`_query.Query.subquery` + method to produce an explicit subquery object. Always test the structure of queries by viewing the SQL to ensure a particular structure does what's expected! **Changing the Entities** - :meth:`.Query.from_self` also includes the ability to modify what + :meth:`_query.Query.from_self` + also includes the ability to modify what columns are being queried. In our example, we want ``User.id`` to be queried by the inner query, so that we can join to the ``Address`` entity on the outside, but we only wanted the outer @@ -1340,8 +1370,9 @@ class Query(Generative): q = q.add_entity(User).from_self().\ options(contains_eager(Address.user)) - We use :meth:`.Query.add_entity` above **before** we call - :meth:`.Query.from_self` so that the ``User`` columns are present + We use :meth:`_query.Query.add_entity` above **before** we call + :meth:`_query.Query.from_self` + so that the ``User`` columns are present in the inner subquery, so that they are available to the :func:`.contains_eager` modifier we are using on the outside, producing: @@ -1457,7 +1488,8 @@ class Query(Generative): @_generative def with_entities(self, *entities): - r"""Return a new :class:`.Query` replacing the SELECT list with the + r"""Return a new :class:`_query.Query` + replacing the SELECT list with the given entities. e.g.:: @@ -1493,8 +1525,9 @@ class Query(Generative): @util.deprecated( "1.4", - ":meth:`.Query.add_column` is deprecated and will be removed in a " - "future release. Please use :meth:`.Query.add_columns`", + ":meth:`_query.Query.add_column` " + "is deprecated and will be removed in a " + "future release. Please use :meth:`_query.Query.add_columns`", ) def add_column(self, column): """Add a column expression to the list of result columns to be @@ -1504,7 +1537,8 @@ class Query(Generative): return self.add_columns(column) def options(self, *args): - """Return a new :class:`.Query` object, applying the given list of + """Return a new :class:`_query.Query` object, + applying the given list of mapper options. Most supplied options regard changing how column- and @@ -1539,7 +1573,7 @@ class Query(Generative): opt.process_query(self) def with_transformation(self, fn): - """Return a new :class:`.Query` object transformed by + """Return a new :class:`_query.Query` object transformed by the given function. E.g.:: @@ -1551,7 +1585,7 @@ class Query(Generative): q = q.with_transformation(filter_something(x==5)) - This allows ad-hoc recipes to be created for :class:`.Query` + This allows ad-hoc recipes to be created for :class:`_query.Query` objects. See the example at :ref:`hybrid_transformers`. """ @@ -1561,17 +1595,18 @@ class Query(Generative): def with_hint(self, selectable, text, dialect_name="*"): """Add an indexing or other executional context hint for the given entity or selectable to - this :class:`.Query`. + this :class:`_query.Query`. Functionality is passed straight through to :meth:`~sqlalchemy.sql.expression.Select.with_hint`, with the addition that ``selectable`` can be a - :class:`.Table`, :class:`.Alias`, or ORM entity / mapped class + :class:`_schema.Table`, :class:`_expression.Alias`, + or ORM entity / mapped class /etc. .. seealso:: - :meth:`.Query.with_statement_hint` + :meth:`_query.Query.with_statement_hint` :meth:.`.Query.prefix_with` - generic SELECT prefixing which also can suit some database-specific HINT syntaxes such as MySQL @@ -1584,19 +1619,21 @@ class Query(Generative): self._with_hints += ((selectable, text, dialect_name),) def with_statement_hint(self, text, dialect_name="*"): - """add a statement hint to this :class:`.Select`. + """add a statement hint to this :class:`_expression.Select`. - This method is similar to :meth:`.Select.with_hint` except that + This method is similar to :meth:`_expression.Select.with_hint` + except that it does not require an individual table, and instead applies to the statement as a whole. - This feature calls down into :meth:`.Select.with_statement_hint`. + This feature calls down into + :meth:`_expression.Select.with_statement_hint`. .. versionadded:: 1.0.0 .. seealso:: - :meth:`.Query.with_hint` + :meth:`_query.Query.with_hint` """ return self.with_hint(None, text, dialect_name) @@ -1608,7 +1645,7 @@ class Query(Generative): .. seealso:: - :meth:`.Query.execution_options` + :meth:`_query.Query.execution_options` """ return self._execution_options @@ -1617,7 +1654,7 @@ class Query(Generative): """ Set non-SQL options which take effect during execution. The options are the same as those accepted by - :meth:`.Connection.execution_options`. + :meth:`_engine.Connection.execution_options`. Note that the ``stream_results`` execution option is enabled automatically if the :meth:`~sqlalchemy.orm.query.Query.yield_per()` @@ -1625,7 +1662,7 @@ class Query(Generative): .. seealso:: - :meth:`.Query.get_execution_options` + :meth:`_query.Query.get_execution_options` """ self._execution_options = self._execution_options.union(kwargs) @@ -1639,11 +1676,13 @@ class Query(Generative): skip_locked=False, key_share=False, ): - """return a new :class:`.Query` with the specified options for the + """return a new :class:`_query.Query` + with the specified options for the ``FOR UPDATE`` clause. The behavior of this method is identical to that of - :meth:`.SelectBase.with_for_update`. When called with no arguments, + :meth:`_expression.SelectBase.with_for_update`. + When called with no arguments, the resulting ``SELECT`` statement will have a ``FOR UPDATE`` clause appended. When additional arguments are specified, backend-specific options such as ``FOR UPDATE NOWAIT`` or ``LOCK IN SHARE MODE`` @@ -1659,7 +1698,8 @@ class Query(Generative): .. seealso:: - :meth:`.GenerativeSelect.with_for_update` - Core level method with + :meth:`_expression.GenerativeSelect.with_for_update` + - Core level method with full argument and behavioral description. """ @@ -1696,7 +1736,7 @@ class Query(Generative): @_assertions(_no_statement_condition, _no_limit_offset) def filter(self, *criterion): r"""apply the given filtering criterion to a copy - of this :class:`.Query`, using SQL expressions. + of this :class:`_query.Query`, using SQL expressions. e.g.:: @@ -1711,11 +1751,12 @@ class Query(Generative): The criterion is any SQL expression object applicable to the WHERE clause of a select. String expressions are coerced - into SQL expression constructs via the :func:`.text` construct. + into SQL expression constructs via the :func:`_expression.text` + construct. .. seealso:: - :meth:`.Query.filter_by` - filter on keyword expressions. + :meth:`_query.Query.filter_by` - filter on keyword expressions. """ for criterion in list(criterion): @@ -1729,7 +1770,7 @@ class Query(Generative): def filter_by(self, **kwargs): r"""apply the given filtering criterion to a copy - of this :class:`.Query`, using keyword expressions. + of this :class:`_query.Query`, using keyword expressions. e.g.:: @@ -1744,11 +1785,11 @@ class Query(Generative): The keyword expressions are extracted from the primary entity of the query, or the last entity that was the - target of a call to :meth:`.Query.join`. + target of a call to :meth:`_query.Query.join`. .. seealso:: - :meth:`.Query.filter` - filter on SQL expressions. + :meth:`_query.Query.filter` - filter on SQL expressions. """ @@ -1788,7 +1829,7 @@ class Query(Generative): @_assertions(_no_statement_condition, _no_limit_offset) def group_by(self, *criterion): """apply one or more GROUP BY criterion to the query and return - the newly resulting :class:`.Query` + the newly resulting :class:`_query.Query` All existing GROUP BY settings can be suppressed by passing ``None`` - this will suppress any GROUP BY configured @@ -1816,10 +1857,10 @@ class Query(Generative): @_assertions(_no_statement_condition, _no_limit_offset) def having(self, criterion): r"""apply a HAVING criterion to the query and return the - newly resulting :class:`.Query`. + newly resulting :class:`_query.Query`. - :meth:`~.Query.having` is used in conjunction with - :meth:`~.Query.group_by`. + :meth:`_query.Query.having` is used in conjunction with + :meth:`_query.Query.group_by`. HAVING criterion makes it possible to use filters on aggregate functions like COUNT, SUM, AVG, MAX, and MIN, eg.:: @@ -1884,7 +1925,7 @@ class Query(Generative): be rendered on a query called within UNION, EXCEPT, etc. To disable all ORDER BY clauses including those configured on mappers, issue ``query.order_by(None)`` - the resulting - :class:`.Query` object will not render ORDER BY within + :class:`_query.Query` object will not render ORDER BY within its SELECT statement. """ @@ -1936,27 +1977,31 @@ class Query(Generative): return self._set_op(expression.except_all, *q) def join(self, *props, **kwargs): - r"""Create a SQL JOIN against this :class:`.Query` object's criterion - and apply generatively, returning the newly resulting :class:`.Query`. + r"""Create a SQL JOIN against this :class:`_query.Query` + object's criterion + and apply generatively, returning the newly resulting + :class:`_query.Query`. **Simple Relationship Joins** Consider a mapping between two classes ``User`` and ``Address``, with a relationship ``User.addresses`` representing a collection of ``Address`` objects associated with each ``User``. The most - common usage of :meth:`~.Query.join` is to create a JOIN along this + common usage of :meth:`_query.Query.join` + is to create a JOIN along this relationship, using the ``User.addresses`` attribute as an indicator for how this should occur:: q = session.query(User).join(User.addresses) - Where above, the call to :meth:`~.Query.join` along ``User.addresses`` + Where above, the call to :meth:`_query.Query.join` along ``User. + addresses`` will result in SQL equivalent to:: SELECT user.* FROM user JOIN address ON user.id = address.user_id In the above example we refer to ``User.addresses`` as passed to - :meth:`~.Query.join` as the *on clause*, that is, it indicates + :meth:`_query.Query.join` as the *on clause*, that is, it indicates how the "ON" portion of the JOIN should be constructed. For a single-entity query such as the one above (i.e. we start by selecting only from ``User`` and nothing else), the relationship can also be @@ -1964,14 +2009,15 @@ class Query(Generative): q = session.query(User).join("addresses") - :meth:`~.Query.join` can also accommodate multiple + :meth:`_query.Query.join` can also accommodate multiple "on clause" arguments to produce a chain of joins, such as below where a join across four related entities is constructed:: q = session.query(User).join("orders", "items", "keywords") The above would be shorthand for three separate calls to - :meth:`~.Query.join`, each using an explicit attribute to indicate + :meth:`_query.Query.join`, + each using an explicit attribute to indicate the source entity:: q = session.query(User).\ @@ -1981,20 +2027,21 @@ class Query(Generative): **Joins to a Target Entity or Selectable** - A second form of :meth:`~.Query.join` allows any mapped entity + A second form of :meth:`_query.Query.join` allows any mapped entity or core selectable construct as a target. In this usage, - :meth:`~.Query.join` will attempt + :meth:`_query.Query.join` will attempt to create a JOIN along the natural foreign key relationship between two entities:: q = session.query(User).join(Address) - The above calling form of :meth:`~.Query.join` will raise an error if + The above calling form of :meth:`_query.Query.join` + will raise an error if either there are no foreign keys between the two entities, or if there are multiple foreign key linkages between them. In the - above calling form, :meth:`~.Query.join` is called upon to + above calling form, :meth:`_query.Query.join` is called upon to create the "on clause" automatically for us. The target can - be any mapped entity or selectable, such as a :class:`.Table`:: + be any mapped entity or selectable, such as a :class:`_schema.Table`:: q = session.query(User).join(addresses_table) @@ -2025,7 +2072,7 @@ class Query(Generative): WHERE address.email_address = :email_address_1 AND address_1.email_address = :email_address_2 - The two-argument calling form of :meth:`~.Query.join` + The two-argument calling form of :meth:`_query.Query.join` also allows us to construct arbitrary joins with SQL-oriented "on clause" expressions, not relying upon configured relationships at all. Any SQL expression can be passed as the ON clause @@ -2037,9 +2084,10 @@ class Query(Generative): **Advanced Join Targeting and Adaption** There is a lot of flexibility in what the "target" can be when using - :meth:`~.Query.join`. As noted previously, it also accepts - :class:`.Table` constructs and other selectables such as :func:`.alias` - and :func:`~.sql.expression.select` constructs, with either the one or + :meth:`_query.Query.join`. As noted previously, it also accepts + :class:`_schema.Table` constructs and other selectables such as + :func:`.alias` + and :func:`_expression.select` constructs, with either the one or two-argument forms:: addresses_q = select([Address.user_id]).\ @@ -2049,7 +2097,7 @@ class Query(Generative): q = session.query(User).\ join(addresses_q, addresses_q.c.user_id==User.id) - :meth:`~.Query.join` also features the ability to *adapt* a + :meth:`_query.Query.join` also features the ability to *adapt* a :meth:`~sqlalchemy.orm.relationship` -driven ON clause to the target selectable. Below we construct a JOIN from ``User`` to a subquery against ``Address``, allowing the relationship denoted by @@ -2080,12 +2128,12 @@ class Query(Generative): **Controlling what to Join From** - While :meth:`~.Query.join` exclusively deals with the "right" + While :meth:`_query.Query.join` exclusively deals with the "right" side of the JOIN, we can also control the "left" side, in those - cases where it's needed, using :meth:`~.Query.select_from`. + cases where it's needed, using :meth:`_query.Query.select_from`. Below we construct a query against ``Address`` but can still make usage of ``User.addresses`` as our ON clause by instructing - the :class:`.Query` to select first from the ``User`` + the :class:`_query.Query` to select first from the ``User`` entity:: q = session.query(Address).select_from(User).\ @@ -2100,7 +2148,7 @@ class Query(Generative): **Constructing Aliases Anonymously** - :meth:`~.Query.join` can construct anonymous aliases + :meth:`_query.Query.join` can construct anonymous aliases using the ``aliased=True`` flag. This feature is useful when a query is being joined algorithmically, such as when querying self-referentially to an arbitrary depth:: @@ -2110,7 +2158,7 @@ class Query(Generative): When ``aliased=True`` is used, the actual "alias" construct is not explicitly available. To work with it, methods such as - :meth:`.Query.filter` will adapt the incoming entity to + :meth:`_query.Query.filter` will adapt the incoming entity to the last join point:: q = session.query(Node).\ @@ -2119,7 +2167,7 @@ class Query(Generative): When using automatic aliasing, the ``from_joinpoint=True`` argument can allow a multi-node join to be broken into - multiple calls to :meth:`~.Query.join`, so that + multiple calls to :meth:`_query.Query.join`, so that each path along the way can be further filtered:: q = session.query(Node).\ @@ -2129,7 +2177,7 @@ class Query(Generative): filter(Node.name == 'grandchild 1') The filtering aliases above can then be reset back to the - original ``Node`` entity using :meth:`~.Query.reset_joinpoint`:: + original ``Node`` entity using :meth:`_query.Query.reset_joinpoint`:: q = session.query(Node).\ join("children", "children", aliased=True).\ @@ -2148,13 +2196,14 @@ class Query(Generative): A special two-argument calling form of the form ``target, onclause`` is also accepted. :param aliased=False: If True, indicate that the JOIN target should be - anonymously aliased. Subsequent calls to :meth:`~.Query.filter` + anonymously aliased. Subsequent calls to :meth:`_query.Query.filter` and similar will adapt the incoming criterion to the target - alias, until :meth:`~.Query.reset_joinpoint` is called. + alias, until :meth:`_query.Query.reset_joinpoint` is called. :param isouter=False: If True, the join used will be a left outer join, - just as if the :meth:`.Query.outerjoin` method were called. This + just as if the :meth:`_query.Query.outerjoin` method were called. + This flag is here to maintain consistency with the same flag as accepted - by :meth:`.FromClause.join` and other Core constructs. + by :meth:`_expression.FromClause.join` and other Core constructs. .. versionadded:: 1.0.0 @@ -2173,10 +2222,10 @@ class Query(Generative): :ref:`ormtutorial_joins` in the ORM tutorial. :ref:`inheritance_toplevel` for details on how - :meth:`~.Query.join` is used for inheritance relationships. + :meth:`_query.Query.join` is used for inheritance relationships. - :func:`.orm.join` - a standalone ORM-level join function, - used internally by :meth:`.Query.join`, which in previous + :func:`_orm.join` - a standalone ORM-level join function, + used internally by :meth:`_query.Query.join`, which in previous SQLAlchemy versions was the primary ORM-level joining interface. """ @@ -2809,12 +2858,12 @@ class Query(Generative): @_generative @_assertions(_no_statement_condition) def reset_joinpoint(self): - """Return a new :class:`.Query`, where the "join point" has + """Return a new :class:`_query.Query`, where the "join point" has been reset back to the base FROM entities of the query. This method is usually used in conjunction with the - ``aliased=True`` feature of the :meth:`~.Query.join` - method. See the example in :meth:`~.Query.join` for how + ``aliased=True`` feature of the :meth:`_query.Query.join` + method. See the example in :meth:`_query.Query.join` for how this is used. """ @@ -2823,16 +2872,16 @@ class Query(Generative): @_generative @_assertions(_no_clauseelement_condition) def select_from(self, *from_obj): - r"""Set the FROM clause of this :class:`.Query` explicitly. + r"""Set the FROM clause of this :class:`_query.Query` explicitly. - :meth:`.Query.select_from` is often used in conjunction with - :meth:`.Query.join` in order to control which entity is selected + :meth:`_query.Query.select_from` is often used in conjunction with + :meth:`_query.Query.join` in order to control which entity is selected from on the "left" side of the join. The entity or selectable object here effectively replaces the - "left edge" of any calls to :meth:`~.Query.join`, when no + "left edge" of any calls to :meth:`_query.Query.join`, when no joinpoint is otherwise established - usually, the default "join - point" is the leftmost entity in the :class:`~.Query` object's + point" is the leftmost entity in the :class:`_query.Query` object's list of entities to be selected. A typical example:: @@ -2849,8 +2898,9 @@ class Query(Generative): :param \*from_obj: collection of one or more entities to apply to the FROM clause. Entities can be mapped classes, - :class:`.AliasedClass` objects, :class:`.Mapper` objects - as well as core :class:`.FromClause` elements like subqueries. + :class:`.AliasedClass` objects, :class:`_orm.Mapper` objects + as well as core :class:`_expression.FromClause` + elements like subqueries. .. versionchanged:: 0.9 This method no longer applies the given FROM object @@ -2861,9 +2911,9 @@ class Query(Generative): .. seealso:: - :meth:`~.Query.join` + :meth:`_query.Query.join` - :meth:`.Query.select_entity_from` + :meth:`_query.Query.select_entity_from` """ @@ -2872,15 +2922,16 @@ class Query(Generative): @_generative @_assertions(_no_clauseelement_condition) def select_entity_from(self, from_obj): - r"""Set the FROM clause of this :class:`.Query` to a + r"""Set the FROM clause of this :class:`_query.Query` to a core selectable, applying it as a replacement FROM clause for corresponding mapped entities. - The :meth:`.Query.select_entity_from` method supplies an alternative + The :meth:`_query.Query.select_entity_from` + method supplies an alternative approach to the use case of applying an :func:`.aliased` construct explicitly throughout a query. Instead of referring to the :func:`.aliased` construct explicitly, - :meth:`.Query.select_entity_from` automatically *adapts* all + :meth:`_query.Query.select_entity_from` automatically *adapts* all occurrences of the entity to the target selectable. Given a case for :func:`.aliased` such as selecting ``User`` @@ -2894,7 +2945,8 @@ class Query(Generative): Above, we apply the ``user_alias`` object explicitly throughout the query. When it's not feasible for ``user_alias`` to be referenced - explicitly in many places, :meth:`.Query.select_entity_from` may be + explicitly in many places, :meth:`_query.Query.select_entity_from` + may be used at the start of the query to adapt the existing ``User`` entity:: q = session.query(User).\ @@ -2912,11 +2964,12 @@ class Query(Generative): WHERE "user".id = :id_1) AS anon_1 WHERE anon_1.name = :name_1 - The :meth:`.Query.select_entity_from` method is similar to the - :meth:`.Query.select_from` method, in that it sets the FROM clause + The :meth:`_query.Query.select_entity_from` method is similar to the + :meth:`_query.Query.select_from` method, + in that it sets the FROM clause of the query. The difference is that it additionally applies adaptation to the other parts of the query that refer to the - primary entity. If above we had used :meth:`.Query.select_from` + primary entity. If above we had used :meth:`_query.Query.select_from` instead, the SQL generated would have been: .. sourcecode:: sql @@ -2928,24 +2981,30 @@ class Query(Generative): WHERE "user".id = :id_1) AS anon_1 WHERE "user".name = :name_1 - To supply textual SQL to the :meth:`.Query.select_entity_from` method, - we can make use of the :func:`.text` construct. However, the - :func:`.text` construct needs to be aligned with the columns of our + To supply textual SQL to the :meth:`_query.Query.select_entity_from` + method, + we can make use of the :func:`_expression.text` construct. However, + the + :func:`_expression.text` + construct needs to be aligned with the columns of our entity, which is achieved by making use of the - :meth:`.TextClause.columns` method:: + :meth:`_expression.TextClause.columns` method:: text_stmt = text("select id, name from user").columns( User.id, User.name).subquery() q = session.query(User).select_entity_from(text_stmt) - :meth:`.Query.select_entity_from` itself accepts an :func:`.aliased` + :meth:`_query.Query.select_entity_from` itself accepts an + :func:`.aliased` object, so that the special options of :func:`.aliased` such as :paramref:`.aliased.adapt_on_names` may be used within the - scope of the :meth:`.Query.select_entity_from` method's adaptation + scope of the :meth:`_query.Query.select_entity_from` + method's adaptation services. Suppose a view ``user_view`` also returns rows from ``user``. If - we reflect this view into a :class:`.Table`, this view has no - relationship to the :class:`.Table` to which we are mapped, however + we reflect this view into a :class:`_schema.Table`, this view has no + relationship to the :class:`_schema.Table` to which we are mapped, + however we can use name matching to select from it:: user_view = Table('user_view', metadata, @@ -2956,19 +3015,21 @@ class Query(Generative): select_entity_from(user_view_alias).\ order_by(User.name) - .. versionchanged:: 1.1.7 The :meth:`.Query.select_entity_from` + .. versionchanged:: 1.1.7 The :meth:`_query.Query.select_entity_from` method now accepts an :func:`.aliased` object as an alternative - to a :class:`.FromClause` object. + to a :class:`_expression.FromClause` object. - :param from_obj: a :class:`.FromClause` object that will replace - the FROM clause of this :class:`.Query`. It also may be an instance + :param from_obj: a :class:`_expression.FromClause` + object that will replace + the FROM clause of this :class:`_query.Query`. + It also may be an instance of :func:`.aliased`. .. seealso:: - :meth:`.Query.select_from` + :meth:`_query.Query.select_from` """ @@ -3006,8 +3067,8 @@ class Query(Generative): @_generative @_assertions(_no_statement_condition) def slice(self, start, stop): - """Computes the "slice" of the :class:`.Query` represented by - the given indices and returns the resulting :class:`.Query`. + """Computes the "slice" of the :class:`_query.Query` represented by + the given indices and returns the resulting :class:`_query.Query`. The start and stop indices behave like the argument to Python's built-in :func:`range` function. This method provides an @@ -3030,9 +3091,9 @@ class Query(Generative): .. seealso:: - :meth:`.Query.limit` + :meth:`_query.Query.limit` - :meth:`.Query.offset` + :meth:`_query.Query.offset` """ if start is not None and stop is not None: @@ -3082,9 +3143,10 @@ class Query(Generative): columns clause of the SELECT statement, to satisfy the common need of the database backend that ORDER BY columns be part of the SELECT list when DISTINCT is used. These columns *are not* added to the - list of columns actually fetched by the :class:`.Query`, however, + list of columns actually fetched by the :class:`_query.Query`, + however, so would not affect results. The columns are passed through when - using the :attr:`.Query.statement` accessor, however. + using the :attr:`_query.Query.statement` accessor, however. .. deprecated:: 2.0 This logic is deprecated and will be removed in SQLAlchemy 2.0. See :ref:`migration_20_query_distinct` @@ -3127,7 +3189,7 @@ class Query(Generative): .. seealso:: - :meth:`.HasPrefixes.prefix_with` + :meth:`_expression.HasPrefixes.prefix_with` """ if self._prefixes: @@ -3147,9 +3209,9 @@ class Query(Generative): .. seealso:: - :meth:`.Query.prefix_with` + :meth:`_query.Query.prefix_with` - :meth:`.HasSuffixes.suffix_with` + :meth:`_expression.HasSuffixes.suffix_with` """ if self._suffixes: @@ -3158,11 +3220,13 @@ class Query(Generative): self._suffixes = suffixes def all(self): - """Return the results represented by this :class:`.Query` as a list. + """Return the results represented by this :class:`_query.Query` + as a list. This results in an execution of the underlying SQL statement. - .. warning:: The :class:`.Query` object, when asked to return either + .. warning:: The :class:`_query.Query` object, + when asked to return either a sequence or iterator that consists of full ORM-mapped entities, will **deduplicate entries based on primary key**. See the FAQ for more details. @@ -3181,10 +3245,11 @@ class Query(Generative): This method bypasses all internal statement compilation, and the statement is executed without modification. - The statement is typically either a :func:`~.expression.text` - or :func:`~.expression.select` construct, and should return the set + The statement is typically either a :func:`_expression.text` + or :func:`_expression.select` construct, and should return the set of columns - appropriate to the entity class represented by this :class:`.Query`. + appropriate to the entity class represented by this + :class:`_query.Query`. .. seealso:: @@ -3204,14 +3269,15 @@ class Query(Generative): (note this may consist of multiple result rows if join-loaded collections are present). - Calling :meth:`.Query.first` results in an execution of the underlying + Calling :meth:`_query.Query.first` + results in an execution of the underlying query. .. seealso:: - :meth:`.Query.one` + :meth:`_query.Query.one` - :meth:`.Query.one_or_none` + :meth:`_query.Query.one_or_none` """ if self._statement is not None: @@ -3232,18 +3298,19 @@ class Query(Generative): rows are returned for a query that returns only scalar values as opposed to full identity-mapped entities. - Calling :meth:`.Query.one_or_none` results in an execution of the + Calling :meth:`_query.Query.one_or_none` + results in an execution of the underlying query. .. versionadded:: 1.0.9 - Added :meth:`.Query.one_or_none` + Added :meth:`_query.Query.one_or_none` .. seealso:: - :meth:`.Query.first` + :meth:`_query.Query.first` - :meth:`.Query.one` + :meth:`_query.Query.one` """ ret = list(self) @@ -3271,9 +3338,9 @@ class Query(Generative): .. seealso:: - :meth:`.Query.first` + :meth:`_query.Query.first` - :meth:`.Query.one_or_none` + :meth:`_query.Query.one_or_none` """ try: @@ -3365,7 +3432,7 @@ class Query(Generative): @property def column_descriptions(self): """Return metadata about the columns which would be - returned by this :class:`.Query`. + returned by this :class:`_query.Query`. Format is a list of dictionaries:: @@ -3435,7 +3502,7 @@ class Query(Generative): util.warn_deprecated( "Using the Query.instances() method without a context " "is deprecated and will be disallowed in a future release. " - "Please make use of :meth:`.Query.from_statement` " + "Please make use of :meth:`_query.Query.from_statement` " "for linking ORM results to arbitrary select constructs.", version="1.4", ) @@ -3444,9 +3511,10 @@ class Query(Generative): return loading.instances(self, result_proxy, context) def merge_result(self, iterator, load=True): - """Merge a result into this :class:`.Query` object's Session. + """Merge a result into this :class:`_query.Query` object's Session. - Given an iterator returned by a :class:`.Query` of the same structure + Given an iterator returned by a :class:`_query.Query` + of the same structure as this one, return an identical iterator of results, with all mapped instances merged into the session using :meth:`.Session.merge`. This is an optimized method which will merge all mapped instances, @@ -3455,14 +3523,15 @@ class Query(Generative): explicitly for each value. The structure of the results is determined based on the column list of - this :class:`.Query` - if these do not correspond, unchecked errors + this :class:`_query.Query` - if these do not correspond, + unchecked errors will occur. The 'load' argument is the same as that of :meth:`.Session.merge`. - For an example of how :meth:`~.Query.merge_result` is used, see + For an example of how :meth:`_query.Query.merge_result` is used, see the source code for the example :ref:`examples_caching`, where - :meth:`~.Query.merge_result` is used to efficiently restore state + :meth:`_query.Query.merge_result` is used to efficiently restore state from a cache back into a target :class:`.Session`. """ @@ -3544,7 +3613,8 @@ class Query(Generative): ) AS anon_1 The above SQL returns a single row, which is the aggregate value - of the count function; the :meth:`.Query.count` method then returns + of the count function; the :meth:`_query.Query.count` + method then returns that single integer value. .. warning:: @@ -3552,7 +3622,8 @@ class Query(Generative): It is important to note that the value returned by count() is **not the same as the number of ORM objects that this Query would return from a method such as the .all() method**. - The :class:`.Query` object, when asked to return full entities, + The :class:`_query.Query` object, + when asked to return full entities, will **deduplicate entries based on primary key**, meaning if the same primary key value would appear in the results more than once, only one object of that primary key would be present. This does @@ -3602,7 +3673,8 @@ class Query(Generative): sess.query(User).filter(User.age == 25).\ delete(synchronize_session='evaluate') - .. warning:: The :meth:`.Query.delete` method is a "bulk" operation, + .. warning:: The :meth:`_query.Query.delete` + method is a "bulk" operation, which bypasses ORM unit-of-work automation in favor of greater performance. **Please read all caveats and warnings below.** @@ -3702,7 +3774,7 @@ class Query(Generative): .. seealso:: - :meth:`.Query.update` + :meth:`_query.Query.update` :ref:`inserts_and_updates` - Core SQL tutorial @@ -3726,7 +3798,8 @@ class Query(Generative): update({"age": User.age - 10}, synchronize_session='evaluate') - .. warning:: The :meth:`.Query.update` method is a "bulk" operation, + .. warning:: The :meth:`_query.Query.update` + method is a "bulk" operation, which bypasses ORM unit-of-work automation in favor of greater performance. **Please read all caveats and warnings below.** @@ -3768,7 +3841,8 @@ class Query(Generative): string collations between the database and Python. :param update_args: Optional dictionary, if present will be passed - to the underlying :func:`.update` construct as the ``**kw`` for + to the underlying :func:`_expression.update` + construct as the ``**kw`` for the object. May be used to pass dialect-specific arguments such as ``mysql_limit``, as well as other special arguments such as :paramref:`~sqlalchemy.sql.expression.update.preserve_parameter_order`. @@ -3834,7 +3908,7 @@ class Query(Generative): .. seealso:: - :meth:`.Query.delete` + :meth:`_query.Query.delete` :ref:`inserts_and_updates` - Core SQL tutorial @@ -4272,11 +4346,13 @@ class _MapperEntity(_QueryEntity): @inspection._self_inspects class Bundle(InspectionAttr): - """A grouping of SQL expressions that are returned by a :class:`.Query` + """A grouping of SQL expressions that are returned by a + :class:`_query.Query` under one namespace. The :class:`.Bundle` essentially allows nesting of the tuple-based - results returned by a column-oriented :class:`.Query` object. It also + results returned by a column-oriented :class:`_query.Query` object. + It also is extensible via simple subclassing, where the primary capability to override is that of how the set of expressions should be returned, allowing post-processing as well as custom return types, without @@ -4765,7 +4841,8 @@ class QueryContext(object): class AliasOption(interfaces.MapperOption): def __init__(self, alias): - r"""Return a :class:`.MapperOption` that will indicate to the :class:`.Query` + r"""Return a :class:`.MapperOption` that will indicate to the + :class:`_query.Query` that the main table has been aliased. This is a seldom-used option to suit the @@ -4793,7 +4870,7 @@ class AliasOption(interfaces.MapperOption): results = query.from_statement(statement).all() :param alias: is the string name of an alias, or a - :class:`~.sql.expression.Alias` object representing + :class:`_expression.Alias` object representing the alias. """ diff --git a/lib/sqlalchemy/orm/relationships.py b/lib/sqlalchemy/orm/relationships.py index c6f3bc30a..7d33c4649 100644 --- a/lib/sqlalchemy/orm/relationships.py +++ b/lib/sqlalchemy/orm/relationships.py @@ -6,11 +6,11 @@ # the MIT License: http://www.opensource.org/licenses/mit-license.php """Heuristics related to join conditions as used in -:func:`.relationship`. +:func:`_orm.relationship`. Provides the :class:`.JoinCondition` object, which encapsulates SQL annotation and aliasing behavior focused on the `primaryjoin` -and `secondaryjoin` aspects of :func:`.relationship`. +and `secondaryjoin` aspects of :func:`_orm.relationship`. """ from __future__ import absolute_import @@ -98,7 +98,7 @@ class RelationshipProperty(StrategizedProperty): """Describes an object property that holds a single item or list of items that correspond to a related database table. - Public constructor is the :func:`.orm.relationship` function. + Public constructor is the :func:`_orm.relationship` function. .. seealso:: @@ -160,15 +160,16 @@ class RelationshipProperty(StrategizedProperty): The constructed class is an instance of :class:`.RelationshipProperty`. - A typical :func:`.relationship`, used in a classical mapping:: + A typical :func:`_orm.relationship`, used in a classical mapping:: mapper(Parent, properties={ 'children': relationship(Child) }) - Some arguments accepted by :func:`.relationship` optionally accept a + Some arguments accepted by :func:`_orm.relationship` + optionally accept a callable function, which when called produces the desired value. - The callable is invoked by the parent :class:`.Mapper` at "mapper + The callable is invoked by the parent :class:`_orm.Mapper` at "mapper initialization" time, which happens only when mappers are first used, and is assumed to be after all mappings have been constructed. This can be used to resolve order-of-declaration and other dependency @@ -182,7 +183,7 @@ class RelationshipProperty(StrategizedProperty): When using the :ref:`declarative_toplevel` extension, the Declarative initializer allows string arguments to be passed to - :func:`.relationship`. These string arguments are converted into + :func:`_orm.relationship`. These string arguments are converted into callables that evaluate the string as Python code, using the Declarative class-registry as a namespace. This allows the lookup of related classes to be automatic via their string name, and removes the @@ -191,7 +192,8 @@ class RelationshipProperty(StrategizedProperty): that the modules in which these related classes appear are imported anywhere in the application at some point before the related mappings are actually used, else a lookup error will be raised when the - :func:`.relationship` attempts to resolve the string reference to the + :func:`_orm.relationship` + attempts to resolve the string reference to the related class. An example of a string- resolved class is as follows:: @@ -207,15 +209,17 @@ class RelationshipProperty(StrategizedProperty): .. seealso:: :ref:`relationship_config_toplevel` - Full introductory and - reference documentation for :func:`.relationship`. + reference documentation for :func:`_orm.relationship`. :ref:`orm_tutorial_relationship` - ORM tutorial introduction. :param argument: - a mapped class, or actual :class:`.Mapper` instance, representing + a mapped class, or actual :class:`_orm.Mapper` instance, + representing the target of the relationship. - :paramref:`~.relationship.argument` may also be passed as a callable + :paramref:`_orm.relationship.argument` + may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a string name when using Declarative. @@ -223,7 +227,7 @@ class RelationshipProperty(StrategizedProperty): using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on - declarative evaluation of :func:`.relationship` arguments. + declarative evaluation of :func:`_orm.relationship` arguments. .. versionchanged 1.3.16:: @@ -238,30 +242,35 @@ class RelationshipProperty(StrategizedProperty): :param secondary: for a many-to-many relationship, specifies the intermediary - table, and is typically an instance of :class:`.Table`. + table, and is typically an instance of :class:`_schema.Table`. In less common circumstances, the argument may also be specified - as an :class:`.Alias` construct, or even a :class:`.Join` construct. + as an :class:`_expression.Alias` construct, or even a + :class:`_expression.Join` construct. - :paramref:`~.relationship.secondary` may + :paramref:`_orm.relationship.secondary` may also be passed as a callable function which is evaluated at mapper initialization time. When using Declarative, it may also - be a string argument noting the name of a :class:`.Table` that is - present in the :class:`.MetaData` collection associated with the - parent-mapped :class:`.Table`. + be a string argument noting the name of a :class:`_schema.Table` + that is + present in the :class:`_schema.MetaData` + collection associated with the + parent-mapped :class:`_schema.Table`. .. warning:: When passed as a Python-evaluable string, the argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on - declarative evaluation of :func:`.relationship` arguments. + declarative evaluation of :func:`_orm.relationship` arguments. - The :paramref:`~.relationship.secondary` keyword argument is - typically applied in the case where the intermediary :class:`.Table` + The :paramref:`_orm.relationship.secondary` keyword argument is + typically applied in the case where the intermediary + :class:`_schema.Table` is not otherwise expressed in any direct class mapping. If the "secondary" table is also explicitly mapped elsewhere (e.g. as in :ref:`association_pattern`), one should consider applying the - :paramref:`~.relationship.viewonly` flag so that this - :func:`.relationship` is not used for persistence operations which + :paramref:`_orm.relationship.viewonly` flag so that this + :func:`_orm.relationship` + is not used for persistence operations which may conflict with those of the association object pattern. .. seealso:: @@ -279,16 +288,19 @@ class RelationshipProperty(StrategizedProperty): Declarative. :ref:`association_pattern` - an alternative to - :paramref:`~.relationship.secondary` when composing association + :paramref:`_orm.relationship.secondary` + when composing association table relationships, allowing additional attributes to be specified on the association table. :ref:`composite_secondary_join` - a lesser-used pattern which - in some cases can enable complex :func:`.relationship` SQL + in some cases can enable complex :func:`_orm.relationship` SQL conditions to be used. - .. versionadded:: 0.9.2 :paramref:`~.relationship.secondary` works - more effectively when referring to a :class:`.Join` instance. + .. versionadded:: 0.9.2 :paramref:`_orm.relationship.secondary` + works + more effectively when referring to a :class:`_expression.Join` + instance. :param active_history=False: When ``True``, indicates that the "previous" value for a @@ -313,20 +325,20 @@ class RelationshipProperty(StrategizedProperty): :ref:`relationships_backref` - Introductory documentation and examples. - :paramref:`~.relationship.back_populates` - alternative form + :paramref:`_orm.relationship.back_populates` - alternative form of backref specification. - :func:`.backref` - allows control over :func:`.relationship` - configuration when using :paramref:`~.relationship.backref`. + :func:`.backref` - allows control over :func:`_orm.relationship` + configuration when using :paramref:`_orm.relationship.backref`. :param back_populates: Takes a string name and has the same meaning as - :paramref:`~.relationship.backref`, except the complementing + :paramref:`_orm.relationship.backref`, except the complementing property is **not** created automatically, and instead must be configured explicitly on the other mapper. The complementing property should also indicate - :paramref:`~.relationship.back_populates` to this relationship to + :paramref:`_orm.relationship.back_populates` to this relationship to ensure proper functioning. .. seealso:: @@ -334,7 +346,7 @@ class RelationshipProperty(StrategizedProperty): :ref:`relationships_backref` - Introductory documentation and examples. - :paramref:`~.relationship.backref` - alternative form + :paramref:`_orm.relationship.backref` - alternative form of backref specification. :param overlaps: @@ -397,7 +409,7 @@ class RelationshipProperty(StrategizedProperty): .. seealso:: :ref:`backref_cascade` - Full discussion and examples on how - the :paramref:`~.relationship.cascade_backrefs` option is used. + the :paramref:`_orm.relationship.cascade_backrefs` option is used. :param collection_class: a class or callable that returns a new list-holding object. will @@ -434,7 +446,7 @@ class RelationshipProperty(StrategizedProperty): duplicate innermost rows may be causing. .. versionchanged:: 0.9.0 - - :paramref:`~.relationship.distinct_target_key` now defaults to + :paramref:`_orm.relationship.distinct_target_key` now defaults to ``None``, so that the feature enables itself automatically for those cases where the innermost query targets a non-unique key. @@ -451,51 +463,55 @@ class RelationshipProperty(StrategizedProperty): a list of columns which are to be used as "foreign key" columns, or columns which refer to the value in a remote - column, within the context of this :func:`.relationship` - object's :paramref:`~.relationship.primaryjoin` condition. - That is, if the :paramref:`~.relationship.primaryjoin` - condition of this :func:`.relationship` is ``a.id == + column, within the context of this :func:`_orm.relationship` + object's :paramref:`_orm.relationship.primaryjoin` condition. + That is, if the :paramref:`_orm.relationship.primaryjoin` + condition of this :func:`_orm.relationship` is ``a.id == b.a_id``, and the values in ``b.a_id`` are required to be present in ``a.id``, then the "foreign key" column of this - :func:`.relationship` is ``b.a_id``. + :func:`_orm.relationship` is ``b.a_id``. - In normal cases, the :paramref:`~.relationship.foreign_keys` - parameter is **not required.** :func:`.relationship` will + In normal cases, the :paramref:`_orm.relationship.foreign_keys` + parameter is **not required.** :func:`_orm.relationship` will automatically determine which columns in the - :paramref:`~.relationship.primaryjoin` condition are to be + :paramref:`_orm.relationship.primaryjoin` condition are to be considered "foreign key" columns based on those - :class:`.Column` objects that specify :class:`.ForeignKey`, + :class:`_schema.Column` objects that specify + :class:`_schema.ForeignKey`, or are otherwise listed as referencing columns in a - :class:`.ForeignKeyConstraint` construct. - :paramref:`~.relationship.foreign_keys` is only needed when: + :class:`_schema.ForeignKeyConstraint` construct. + :paramref:`_orm.relationship.foreign_keys` is only needed when: 1. There is more than one way to construct a join from the local table to the remote table, as there are multiple foreign key references present. Setting ``foreign_keys`` will limit the - :func:`.relationship` to consider just those columns specified + :func:`_orm.relationship` + to consider just those columns specified here as "foreign". - 2. The :class:`.Table` being mapped does not actually have - :class:`.ForeignKey` or :class:`.ForeignKeyConstraint` + 2. The :class:`_schema.Table` being mapped does not actually have + :class:`_schema.ForeignKey` or + :class:`_schema.ForeignKeyConstraint` constructs present, often because the table was reflected from a database that does not support foreign key reflection (MySQL MyISAM). - 3. The :paramref:`~.relationship.primaryjoin` argument is used to + 3. The :paramref:`_orm.relationship.primaryjoin` + argument is used to construct a non-standard join condition, which makes use of columns or expressions that do not normally refer to their "parent" column, such as a join condition expressed by a complex comparison using a SQL function. - The :func:`.relationship` construct will raise informative + The :func:`_orm.relationship` construct will raise informative error messages that suggest the use of the - :paramref:`~.relationship.foreign_keys` parameter when + :paramref:`_orm.relationship.foreign_keys` parameter when presented with an ambiguous condition. In typical cases, - if :func:`.relationship` doesn't raise any exceptions, the - :paramref:`~.relationship.foreign_keys` parameter is usually + if :func:`_orm.relationship` doesn't raise any exceptions, the + :paramref:`_orm.relationship.foreign_keys` parameter is usually not needed. - :paramref:`~.relationship.foreign_keys` may also be passed as a + :paramref:`_orm.relationship.foreign_keys` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. @@ -504,7 +520,7 @@ class RelationshipProperty(StrategizedProperty): argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on - declarative evaluation of :func:`.relationship` arguments. + declarative evaluation of :func:`_orm.relationship` arguments. .. seealso:: @@ -513,7 +529,8 @@ class RelationshipProperty(StrategizedProperty): :ref:`relationship_custom_foreign` :func:`.foreign` - allows direct annotation of the "foreign" - columns within a :paramref:`~.relationship.primaryjoin` condition. + columns within a :paramref:`_orm.relationship.primaryjoin` + condition. :param info: Optional data dictionary which will be populated into the :attr:`.MapperProperty.info` attribute of this object. @@ -530,12 +547,12 @@ class RelationshipProperty(StrategizedProperty): is guaranteed to have one or at least one entry. The option supports the same "nested" and "unnested" options as - that of :paramref:`.joinedload.innerjoin`. See that flag + that of :paramref:`_orm.joinedload.innerjoin`. See that flag for details on nested / unnested behaviors. .. seealso:: - :paramref:`.joinedload.innerjoin` - the option as specified by + :paramref:`_orm.joinedload.innerjoin` - the option as specified by loader option, including detail on nesting behavior. :ref:`what_kind_of_loading` - Discussion of some details of @@ -572,7 +589,7 @@ class RelationshipProperty(StrategizedProperty): * ``joined`` - items should be loaded "eagerly" in the same query as that of the parent, using a JOIN or LEFT OUTER JOIN. Whether the join is "outer" or not is determined by the - :paramref:`~.relationship.innerjoin` parameter. + :paramref:`_orm.relationship.innerjoin` parameter. * ``subquery`` - items should be loaded "eagerly" as the parents are loaded, using one additional SQL statement, which issues a JOIN to @@ -611,7 +628,7 @@ class RelationshipProperty(StrategizedProperty): .. versionadded:: 1.1 * ``dynamic`` - the attribute will return a pre-configured - :class:`.Query` object for all read + :class:`_query.Query` object for all read operations, onto which further filtering operations can be applied before iterating the results. See the section :ref:`dynamic_relationship` for more details. @@ -641,7 +658,8 @@ class RelationshipProperty(StrategizedProperty): "attached" to a :class:`.Session` but is not part of its pending collection. - The :paramref:`~.relationship.load_on_pending` flag does not improve + The :paramref:`_orm.relationship.load_on_pending` + flag does not improve behavior when the ORM is used normally - object references should be constructed at the object level, not at the foreign key level, so that they are present in an ordinary way before a flush proceeds. @@ -656,12 +674,15 @@ class RelationshipProperty(StrategizedProperty): :param order_by: indicates the ordering that should be applied when loading these - items. :paramref:`~.relationship.order_by` is expected to refer to - one of the :class:`.Column` objects to which the target class is + items. :paramref:`_orm.relationship.order_by` + is expected to refer to + one of the :class:`_schema.Column` + objects to which the target class is mapped, or the attribute itself bound to the target class which refers to the column. - :paramref:`~.relationship.order_by` may also be passed as a callable + :paramref:`_orm.relationship.order_by` + may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. @@ -669,7 +690,7 @@ class RelationshipProperty(StrategizedProperty): argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on - declarative evaluation of :func:`.relationship` arguments. + declarative evaluation of :func:`_orm.relationship` arguments. :param passive_deletes=False: Indicates loading behavior during delete operations. @@ -706,7 +727,8 @@ class RelationshipProperty(StrategizedProperty): When True, it is assumed that ``ON UPDATE CASCADE`` is configured on the foreign key in the database, and that the database will handle propagation of an UPDATE from a source column to - dependent rows. When False, the SQLAlchemy :func:`.relationship` + dependent rows. When False, the SQLAlchemy + :func:`_orm.relationship` construct will attempt to emit its own UPDATE statements to modify related targets. However note that SQLAlchemy **cannot** emit an UPDATE for more than one level of cascade. Also, @@ -744,7 +766,7 @@ class RelationshipProperty(StrategizedProperty): list (i.e. both tables contain a foreign key to each other). If a flush operation returns an error that a "cyclical dependency" was detected, this is a cue that you might want to - use :paramref:`~.relationship.post_update` to "break" the cycle. + use :paramref:`_orm.relationship.post_update` to "break" the cycle. .. seealso:: @@ -758,7 +780,7 @@ class RelationshipProperty(StrategizedProperty): foreign key relationships of the parent and child tables (or association table). - :paramref:`~.relationship.primaryjoin` may also be passed as a + :paramref:`_orm.relationship.primaryjoin` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. @@ -767,7 +789,7 @@ class RelationshipProperty(StrategizedProperty): argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on - declarative evaluation of :func:`.relationship` arguments. + declarative evaluation of :func:`_orm.relationship` arguments. .. seealso:: @@ -777,7 +799,7 @@ class RelationshipProperty(StrategizedProperty): used for self-referential relationships, indicates the column or list of columns that form the "remote side" of the relationship. - :paramref:`.relationship.remote_side` may also be passed as a + :paramref:`_orm.relationship.remote_side` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. @@ -786,24 +808,26 @@ class RelationshipProperty(StrategizedProperty): argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on - declarative evaluation of :func:`.relationship` arguments. + declarative evaluation of :func:`_orm.relationship` arguments. .. seealso:: :ref:`self_referential` - in-depth explanation of how - :paramref:`~.relationship.remote_side` + :paramref:`_orm.relationship.remote_side` is used to configure self-referential relationships. :func:`.remote` - an annotation function that accomplishes the - same purpose as :paramref:`~.relationship.remote_side`, typically - when a custom :paramref:`~.relationship.primaryjoin` condition + same purpose as :paramref:`_orm.relationship.remote_side`, + typically + when a custom :paramref:`_orm.relationship.primaryjoin` condition is used. :param query_class: - a :class:`.Query` subclass that will be used as the base of the + a :class:`_query.Query` + subclass that will be used as the base of the "appender query" returned by a "dynamic" relationship, that is, a relationship that specifies ``lazy="dynamic"`` or was - otherwise constructed using the :func:`.orm.dynamic_loader` + otherwise constructed using the :func:`_orm.dynamic_loader` function. .. seealso:: @@ -817,7 +841,7 @@ class RelationshipProperty(StrategizedProperty): computed based on the foreign key relationships of the association and child tables. - :paramref:`~.relationship.secondaryjoin` may also be passed as a + :paramref:`_orm.relationship.secondaryjoin` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. @@ -826,7 +850,7 @@ class RelationshipProperty(StrategizedProperty): argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on - declarative evaluation of :func:`.relationship` arguments. + declarative evaluation of :func:`_orm.relationship` arguments. .. seealso:: @@ -837,31 +861,36 @@ class RelationshipProperty(StrategizedProperty): from being associated with more than one parent at a time. 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, except for :func:`.relationship` constructs which + is optional, except for :func:`_orm.relationship` constructs which are many-to-one or many-to-many and also specify the ``delete-orphan`` cascade option. The - :func:`.relationship` construct itself will raise an error + :func:`_orm.relationship` construct itself will raise an error instructing when this option is required. .. seealso:: :ref:`unitofwork_cascades` - includes detail on when the - :paramref:`~.relationship.single_parent` flag may be appropriate. + :paramref:`_orm.relationship.single_parent` + flag may be appropriate. :param uselist: a boolean that indicates if this property should be loaded as a list or a scalar. In most cases, this value is determined - automatically by :func:`.relationship` at mapper configuration + automatically by :func:`_orm.relationship` at mapper configuration time, based on the type and direction of the relationship - one to many forms a list, many to one forms a scalar, many to many is a list. If a scalar is desired where normally a list would be present, such as a bi-directional - one-to-one relationship, set :paramref:`~.relationship.uselist` to + one-to-one relationship, set :paramref:`_orm.relationship.uselist` + to False. - The :paramref:`~.relationship.uselist` flag is also available on an - existing :func:`.relationship` construct as a read-only attribute, - which can be used to determine if this :func:`.relationship` deals + The :paramref:`_orm.relationship.uselist` + flag is also available on an + existing :func:`_orm.relationship` + construct as a read-only attribute, + which can be used to determine if this :func:`_orm.relationship` + deals with collections or scalar attributes:: >>> User.addresses.property.uselist @@ -871,18 +900,20 @@ class RelationshipProperty(StrategizedProperty): :ref:`relationships_one_to_one` - Introduction to the "one to one" relationship pattern, which is typically when the - :paramref:`~.relationship.uselist` flag is needed. + :paramref:`_orm.relationship.uselist` flag is needed. :param viewonly=False: when set to True, the relationship is used only for loading objects, - and not for any persistence operation. A :func:`.relationship` - which specifies :paramref:`~.relationship.viewonly` can work + and not for any persistence operation. A :func:`_orm.relationship` + which specifies :paramref:`_orm.relationship.viewonly` can work with a wider range of SQL operations within the - :paramref:`~.relationship.primaryjoin` condition, including + :paramref:`_orm.relationship.primaryjoin` condition, including operations that feature the use of a variety of comparison operators - as well as SQL functions such as :func:`~.sql.expression.cast`. The - :paramref:`~.relationship.viewonly` flag is also of general use when - defining any kind of :func:`~.relationship` that doesn't represent + as well as SQL functions such as :func:`_expression.cast`. The + :paramref:`_orm.relationship.viewonly` + flag is also of general use when + defining any kind of :func:`_orm.relationship` + that doesn't represent the full set of related objects, to prevent modifications of the collection from resulting in persistence operations. @@ -893,8 +924,8 @@ class RelationshipProperty(StrategizedProperty): be accessed via read. Towards this behavior, it is also not appropriate for the viewonly=True relationship to have any kind of persistence cascade settings, nor should it be the target of - either :paramref:`.relationship.backref` or - :paramref:`.relationship.back_populates`, as backrefs imply + either :paramref:`_orm.relationship.backref` or + :paramref:`_orm.relationship.back_populates`, as backrefs imply in-Python mutation of the attribute. SQLAlchemy may emit warnings for some or all of these conditions as of the 1.3 and 1.4 series of SQLAlchemy and will eventually be disallowed. @@ -1077,22 +1108,22 @@ class RelationshipProperty(StrategizedProperty): """The target entity referred to by this :class:`.RelationshipProperty.Comparator`. - This is either a :class:`.Mapper` or :class:`.AliasedInsp` + This is either a :class:`_orm.Mapper` or :class:`.AliasedInsp` object. This is the "target" or "remote" side of the - :func:`.relationship`. + :func:`_orm.relationship`. """ return self.property.entity @util.memoized_property def mapper(self): - """The target :class:`.Mapper` referred to by this + """The target :class:`_orm.Mapper` referred to by this :class:`.RelationshipProperty.Comparator`. This is the "target" or "remote" side of the - :func:`.relationship`. + :func:`_orm.relationship`. """ return self.property.mapper @@ -1147,7 +1178,7 @@ class RelationshipProperty(StrategizedProperty): def in_(self, other): """Produce an IN clause - this is not implemented - for :func:`~.orm.relationship`-based attributes at this time. + for :func:`_orm.relationship`-based attributes at this time. """ raise NotImplementedError( @@ -1337,7 +1368,7 @@ class RelationshipProperty(StrategizedProperty): related.my_id=my_table.id)) :meth:`~.RelationshipProperty.Comparator.any` is only - valid for collections, i.e. a :func:`.relationship` + valid for collections, i.e. a :func:`_orm.relationship` that has ``uselist=True``. For scalar references, use :meth:`~.RelationshipProperty.Comparator.has`. @@ -1373,7 +1404,7 @@ class RelationshipProperty(StrategizedProperty): using a join. :meth:`~.RelationshipProperty.Comparator.has` is only - valid for scalar references, i.e. a :func:`.relationship` + valid for scalar references, i.e. a :func:`_orm.relationship` that has ``uselist=False``. For collection references, use :meth:`~.RelationshipProperty.Comparator.any`. @@ -1390,7 +1421,7 @@ class RelationshipProperty(StrategizedProperty): :meth:`~.RelationshipProperty.Comparator.contains` is only valid for a collection, i.e. a - :func:`~.orm.relationship` that implements + :func:`_orm.relationship` that implements one-to-many or many-to-many with ``uselist=True``. When used in a simple one-to-many context, an @@ -1436,7 +1467,8 @@ class RelationshipProperty(StrategizedProperty): explicit "outer joins" will need to be used instead. See :meth:`~.RelationshipProperty.Comparator.any` for a less-performant alternative using EXISTS, or refer - to :meth:`.Query.outerjoin` as well as :ref:`ormtutorial_joins` + to :meth:`_query.Query.outerjoin` + as well as :ref:`ormtutorial_joins` for more details on constructing outer joins. """ @@ -1521,7 +1553,7 @@ class RelationshipProperty(StrategizedProperty): * Comparisons against collections are not supported. Use :meth:`~.RelationshipProperty.Comparator.contains` - in conjunction with :func:`~.expression.not_`. + in conjunction with :func:`_expression.not_`. * Compared to a scalar one-to-many, will produce a clause that compares the target columns in the parent to the given target. @@ -1533,7 +1565,7 @@ class RelationshipProperty(StrategizedProperty): comparisons, such as those which use OR. Use explicit joins, outerjoins, or :meth:`~.RelationshipProperty.Comparator.has` in - conjunction with :func:`~.expression.not_` for + conjunction with :func:`_expression.not_` for more comprehensive non-many-to-one scalar membership tests. * Comparisons against ``None`` given in a one-to-many @@ -1984,7 +2016,7 @@ class RelationshipProperty(StrategizedProperty): @util.memoized_property def mapper(self): - """Return the targeted :class:`.Mapper` for this + """Return the targeted :class:`_orm.Mapper` for this :class:`.RelationshipProperty`. This is a lazy-initializing static attribute. @@ -2210,7 +2242,7 @@ class RelationshipProperty(StrategizedProperty): def _generate_backref(self): """Interpret the 'backref' instruction to create a - :func:`.relationship` complementary to this one.""" + :func:`_orm.relationship` complementary to this one.""" if self.parent.non_primary: return diff --git a/lib/sqlalchemy/orm/scoping.py b/lib/sqlalchemy/orm/scoping.py index 0d1e2a965..1090501ca 100644 --- a/lib/sqlalchemy/orm/scoping.py +++ b/lib/sqlalchemy/orm/scoping.py @@ -27,7 +27,7 @@ class scoped_session(object): session_factory = None """The `session_factory` provided to `__init__` is stored in this attribute and may be accessed at a later time. This can be useful when - a new non-scoped :class:`.Session` or :class:`.Connection` to the + a new non-scoped :class:`.Session` or :class:`_engine.Connection` to the database is needed.""" def __init__(self, session_factory, scopefunc=None): @@ -112,7 +112,8 @@ class scoped_session(object): self.session_factory.configure(**kwargs) def query_property(self, query_cls=None): - """return a class property which produces a :class:`.Query` object + """return a class property which produces a :class:`_query.Query` + object against the class and the current :class:`.Session` when called. e.g.:: diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index 98fa819b1..61442756d 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -103,7 +103,7 @@ class SessionTransaction(object): :class:`.SessionTransaction` is a mostly behind-the-scenes object not normally referenced directly by application code. It coordinates - among multiple :class:`.Connection` objects, maintaining a database + among multiple :class:`_engine.Connection` objects, maintaining a database transaction for each one individually, committing or rolling them back all at once. It also provides optional two-phase commit behavior which can augment this coordination operation. @@ -127,8 +127,10 @@ class SessionTransaction(object): its default mode of ``autocommit=False`` whenever the "autobegin" process takes place, associated with no database connections. As the :class:`.Session` is called upon to emit SQL on behalf of various - :class:`.Engine` or :class:`.Connection` objects, a corresponding - :class:`.Connection` and associated :class:`.Transaction` is added to a + :class:`_engine.Engine` or :class:`_engine.Connection` objects, + a corresponding + :class:`_engine.Connection` and associated :class:`.Transaction` + is added to a collection within the :class:`.SessionTransaction` object, becoming one of the connection/transaction pairs maintained by the :class:`.SessionTransaction`. The start of a :class:`.SessionTransaction` @@ -698,22 +700,27 @@ class Session(_SessionClassMethods): :meth:`~.Session.flush` are rarely needed; you usually only need to call :meth:`~.Session.commit` (which flushes) to finalize changes. - :param bind: An optional :class:`.Engine` or :class:`.Connection` to + :param bind: An optional :class:`_engine.Engine` or + :class:`_engine.Connection` to which this ``Session`` should be bound. When specified, all SQL operations performed by this session will execute via this connectable. :param binds: A dictionary which may specify any number of - :class:`.Engine` or :class:`.Connection` objects as the source of + :class:`_engine.Engine` or :class:`_engine.Connection` + objects as the source of connectivity for SQL operations on a per-entity basis. The keys of the dictionary consist of any series of mapped classes, arbitrary Python classes that are bases for mapped classes, - :class:`.Table` objects and :class:`.Mapper` objects. The - values of the dictionary are then instances of :class:`.Engine` - or less commonly :class:`.Connection` objects. Operations which + :class:`_schema.Table` objects and :class:`_orm.Mapper` objects. + The + values of the dictionary are then instances of + :class:`_engine.Engine` + or less commonly :class:`_engine.Connection` objects. + Operations which proceed relative to a particular mapped class will consult this dictionary for the closest matching entity in order to determine - which :class:`.Engine` should be used for a particular SQL + which :class:`_engine.Engine` should be used for a particular SQL operation. The complete heuristics for resolution are described at :meth:`.Session.get_bind`. Usage looks like:: @@ -772,7 +779,7 @@ class Session(_SessionClassMethods): :param query_cls: Class which should be used to create new Query objects, as returned by the :meth:`~.Session.query` method. - Defaults to :class:`.Query`. + Defaults to :class:`_query.Query`. :param twophase: When ``True``, all transactions will be started as a "two phase" transaction, i.e. using the "two phase" semantics @@ -1023,27 +1030,28 @@ class Session(_SessionClassMethods): execution_options=None, **kw ): - r"""Return a :class:`.Connection` object corresponding to this + r"""Return a :class:`_engine.Connection` object corresponding to this :class:`.Session` object's transactional state. If this :class:`.Session` is configured with ``autocommit=False``, - either the :class:`.Connection` corresponding to the current + either the :class:`_engine.Connection` corresponding to the current transaction is returned, or if no transaction is in progress, a new - one is begun and the :class:`.Connection` returned (note that no + one is begun and the :class:`_engine.Connection` + returned (note that no transactional state is established with the DBAPI until the first SQL statement is emitted). Alternatively, if this :class:`.Session` is configured with - ``autocommit=True``, an ad-hoc :class:`.Connection` is returned - using :meth:`.Engine.connect` on the underlying - :class:`.Engine`. + ``autocommit=True``, an ad-hoc :class:`_engine.Connection` is returned + using :meth:`_engine.Engine.connect` on the underlying + :class:`_engine.Engine`. Ambiguity in multi-bind or unbound :class:`.Session` objects can be resolved through any of the optional keyword arguments. This ultimately makes usage of the :meth:`.get_bind` method for resolution. :param bind: - Optional :class:`.Engine` to be used as the bind. If + Optional :class:`_engine.Engine` to be used as the bind. If this engine is already involved in an ongoing transaction, that connection will be used. This argument takes precedence over ``mapper``, ``clause``. @@ -1054,20 +1062,21 @@ class Session(_SessionClassMethods): ``clause``. :param clause: - A :class:`.ClauseElement` (i.e. :func:`~.sql.expression.select`, - :func:`~.sql.expression.text`, + A :class:`_expression.ClauseElement` (i.e. + :func:`_expression.select`, + :func:`_expression.text`, etc.) which will be used to locate a bind, if a bind cannot otherwise be identified. - :param close_with_result: Passed to :meth:`.Engine.connect`, - indicating the :class:`.Connection` should be considered + :param close_with_result: Passed to :meth:`_engine.Engine.connect`, + indicating the :class:`_engine.Connection` should be considered "single use", automatically closing when the first result set is closed. This flag only has an effect if this :class:`.Session` is configured with ``autocommit=True`` and does not already have a transaction in progress. :param execution_options: a dictionary of execution options that will - be passed to :meth:`.Connection.execution_options`, **when the + be passed to :meth:`_engine.Connection.execution_options`, **when the connection is first procured only**. If the connection is already present within the :class:`.Session`, a warning is emitted and the arguments are ignored. @@ -1112,8 +1121,8 @@ class Session(_SessionClassMethods): Returns a :class:`.ResultProxy` representing results of the statement execution, in the same manner as that of an - :class:`.Engine` or - :class:`.Connection`. + :class:`_engine.Engine` or + :class:`_engine.Connection`. E.g.:: @@ -1122,14 +1131,14 @@ class Session(_SessionClassMethods): ) :meth:`~.Session.execute` accepts any executable clause construct, - such as :func:`~.sql.expression.select`, - :func:`~.sql.expression.insert`, - :func:`~.sql.expression.update`, - :func:`~.sql.expression.delete`, and - :func:`~.sql.expression.text`. Plain SQL strings can be passed + such as :func:`_expression.select`, + :func:`_expression.insert`, + :func:`_expression.update`, + :func:`_expression.delete`, and + :func:`_expression.text`. Plain SQL strings can be passed as well, which in the case of :meth:`.Session.execute` only will be interpreted the same as if it were passed via a - :func:`~.expression.text` construct. That is, the following usage:: + :func:`_expression.text` construct. That is, the following usage:: result = session.execute( "SELECT * FROM user WHERE id=:param", @@ -1146,7 +1155,7 @@ class Session(_SessionClassMethods): The second positional argument to :meth:`.Session.execute` is an optional parameter set. Similar to that of - :meth:`.Connection.execute`, whether this is passed as a single + :meth:`_engine.Connection.execute`, whether this is passed as a single dictionary, or a sequence of dictionaries, determines whether the DBAPI cursor's ``execute()`` or ``executemany()`` is used to execute the statement. An INSERT construct may be invoked for a single row:: @@ -1163,14 +1172,16 @@ class Session(_SessionClassMethods): ]) The statement is executed within the current transactional context of - this :class:`.Session`. The :class:`.Connection` which is used + this :class:`.Session`. The :class:`_engine.Connection` + which is used to execute the statement can also be acquired directly by calling the :meth:`.Session.connection` method. Both methods use a rule-based resolution scheme in order to determine the - :class:`.Connection`, which in the average case is derived directly + :class:`_engine.Connection`, + which in the average case is derived directly from the "bind" of the :class:`.Session` itself, and in other cases can be based on the :func:`.mapper` - and :class:`.Table` objects passed to the method; see the + and :class:`_schema.Table` objects passed to the method; see the documentation for :meth:`.Session.get_bind` for a full description of this scheme. @@ -1180,7 +1191,8 @@ class Session(_SessionClassMethods): method is returned with the "close_with_result" flag set to true; the significance of this flag is that if this :class:`.Session` is autocommitting and does not have a transaction-dedicated - :class:`.Connection` available, a temporary :class:`.Connection` is + :class:`_engine.Connection` available, a temporary + :class:`_engine.Connection` is established for the statement execution, which is closed (meaning, returned to the connection pool) when the :class:`.ResultProxy` has consumed all available data. This applies *only* when the @@ -1189,7 +1201,7 @@ class Session(_SessionClassMethods): :param clause: An executable statement (i.e. an :class:`.Executable` expression - such as :func:`.expression.select`) or string SQL statement + such as :func:`_expression.select`) or string SQL statement to be executed. :param params: @@ -1206,7 +1218,7 @@ class Session(_SessionClassMethods): for more details. :param bind: - Optional :class:`.Engine` to be used as the bind. If + Optional :class:`_engine.Engine` to be used as the bind. If this engine is already involved in an ongoing transaction, that connection will be used. This argument takes precedence over ``mapper`` and ``clause`` when locating @@ -1224,7 +1236,8 @@ class Session(_SessionClassMethods): :ref:`connections_toplevel` - Further information on direct statement execution. - :meth:`.Connection.execute` - core level statement execution + :meth:`_engine.Connection.execute` + - core level statement execution method, which is :meth:`.Session.execute` ultimately uses in order to execute the statement. @@ -1266,8 +1279,9 @@ class Session(_SessionClassMethods): """Close this Session, using connection invalidation. This is a variant of :meth:`.Session.close` that will additionally - ensure that the :meth:`.Connection.invalidate` method will be called - on all :class:`.Connection` objects. This can be called when + ensure that the :meth:`_engine.Connection.invalidate` + method will be called + on all :class:`_engine.Connection` objects. This can be called when the database is known to be in a state where the connections are no longer safe to be used. @@ -1342,17 +1356,20 @@ class Session(_SessionClassMethods): ) def bind_mapper(self, mapper, bind): - """Associate a :class:`.Mapper` or arbitrary Python class with a - "bind", e.g. an :class:`.Engine` or :class:`.Connection`. + """Associate a :class:`_orm.Mapper` or arbitrary Python class with a + "bind", e.g. an :class:`_engine.Engine` or :class:`_engine.Connection` + . The given entity is added to a lookup used by the :meth:`.Session.get_bind` method. - :param mapper: a :class:`.Mapper` object, or an instance of a mapped + :param mapper: a :class:`_orm.Mapper` object, + or an instance of a mapped class, or any Python class that is the base of a set of mapped classes. - :param bind: an :class:`.Engine` or :class:`.Connection` object. + :param bind: an :class:`_engine.Engine` or :class:`_engine.Connection` + object. .. seealso:: @@ -1367,17 +1384,20 @@ class Session(_SessionClassMethods): self._add_bind(mapper, bind) def bind_table(self, table, bind): - """Associate a :class:`.Table` with a "bind", e.g. an :class:`.Engine` - or :class:`.Connection`. + """Associate a :class:`_schema.Table` with a "bind", e.g. an + :class:`_engine.Engine` + or :class:`_engine.Connection`. - The given :class:`.Table` is added to a lookup used by the + The given :class:`_schema.Table` is added to a lookup used by the :meth:`.Session.get_bind` method. - :param table: a :class:`.Table` object, which is typically the target + :param table: a :class:`_schema.Table` object, + which is typically the target of an ORM mapping, or is present within a selectable that is mapped. - :param bind: an :class:`.Engine` or :class:`.Connection` object. + :param bind: an :class:`_engine.Engine` or :class:`_engine.Connection` + object. .. seealso:: @@ -1394,9 +1414,9 @@ class Session(_SessionClassMethods): def get_bind(self, mapper=None, clause=None): """Return a "bind" to which this :class:`.Session` is bound. - The "bind" is usually an instance of :class:`.Engine`, + The "bind" is usually an instance of :class:`_engine.Engine`, except in the case where the :class:`.Session` has been - explicitly bound directly to a :class:`.Connection`. + explicitly bound directly to a :class:`_engine.Connection`. For a multiply-bound or unbound :class:`.Session`, the ``mapper`` or ``clause`` arguments are used to determine the @@ -1416,15 +1436,15 @@ class Session(_SessionClassMethods): present in the ``__mro__`` of the mapped class, from more specific superclasses to more general. 2. if clause given and session.binds is present, - locate a bind based on :class:`.Table` objects + locate a bind based on :class:`_schema.Table` objects found in the given clause present in session.binds. 3. if session.bind is present, return that. 4. if clause given, attempt to return a bind - linked to the :class:`.MetaData` ultimately + linked to the :class:`_schema.MetaData` ultimately associated with the clause. 5. if mapper given, attempt to return a bind - linked to the :class:`.MetaData` ultimately - associated with the :class:`.Table` or other + linked to the :class:`_schema.MetaData` ultimately + associated with the :class:`_schema.Table` or other selectable to which the mapper is mapped. 6. No bind can be found, :exc:`~sqlalchemy.exc.UnboundExecutionError` is raised. @@ -1436,19 +1456,24 @@ class Session(_SessionClassMethods): :param mapper: Optional :func:`.mapper` mapped class or instance of - :class:`.Mapper`. The bind can be derived from a :class:`.Mapper` + :class:`_orm.Mapper`. The bind can be derived from a + :class:`_orm.Mapper` first by consulting the "binds" map associated with this - :class:`.Session`, and secondly by consulting the :class:`.MetaData` - associated with the :class:`.Table` to which the :class:`.Mapper` + :class:`.Session`, and secondly by consulting the + :class:`_schema.MetaData` + associated with the :class:`_schema.Table` to which the + :class:`_orm.Mapper` is mapped for a bind. :param clause: - A :class:`.ClauseElement` (i.e. :func:`~.sql.expression.select`, - :func:`~.sql.expression.text`, + A :class:`_expression.ClauseElement` (i.e. + :func:`_expression.select`, + :func:`_expression.text`, etc.). If the ``mapper`` argument is not present or could not produce a bind, the given expression construct will be searched - for a bound element, typically a :class:`.Table` associated with - bound :class:`.MetaData`. + for a bound element, typically a :class:`_schema.Table` + associated with + bound :class:`_schema.MetaData`. .. seealso:: @@ -1517,7 +1542,7 @@ class Session(_SessionClassMethods): ) def query(self, *entities, **kwargs): - """Return a new :class:`.Query` object corresponding to this + """Return a new :class:`_query.Query` object corresponding to this :class:`.Session`.""" return self._query_cls(entities, self, **kwargs) @@ -1564,9 +1589,9 @@ class Session(_SessionClassMethods): PASSIVE_NO_RESULT. In all other cases the instance is returned. .. versionchanged:: 1.4.0 - the :meth:`.Session._identity_lookup` - method was moved from :class:`.Query` to + method was moved from :class:`_query.Query` to :class:`.Session`, to avoid having to instantiate the - :class:`.Query` object. + :class:`_query.Query` object. """ @@ -1647,7 +1672,8 @@ class Session(_SessionClassMethods): :param with_for_update: optional boolean ``True`` indicating FOR UPDATE should be used, or may be a dictionary containing flags to indicate a more specific set of FOR UPDATE flags for the SELECT; - flags should match the parameters of :meth:`.Query.with_for_update`. + flags should match the parameters of + :meth:`_query.Query.with_for_update`. Supersedes the :paramref:`.Session.refresh.lockmode` parameter. .. versionadded:: 1.2 @@ -2342,7 +2368,7 @@ class Session(_SessionClassMethods): :meth:`.enable_relationship_loading` exists to serve special use cases and is not recommended for general use. - Accesses of attributes mapped with :func:`.relationship` + Accesses of attributes mapped with :func:`_orm.relationship` will attempt to load a value from the database using this :class:`.Session` as the source of connectivity. The values will be loaded based on foreign key and primary key values @@ -2360,7 +2386,7 @@ class Session(_SessionClassMethods): is what was already loaded from a foreign-key-holding value. The :meth:`.Session.enable_relationship_loading` method is - similar to the ``load_on_pending`` flag on :func:`.relationship`. + similar to the ``load_on_pending`` flag on :func:`_orm.relationship`. Unlike that flag, :meth:`.Session.enable_relationship_loading` allows an object to remain transient while still being able to load related items. @@ -2379,7 +2405,7 @@ class Session(_SessionClassMethods): .. seealso:: - ``load_on_pending`` at :func:`.relationship` - this flag + ``load_on_pending`` at :func:`_orm.relationship` - this flag allows per-relationship loading of many-to-ones on items that are pending. @@ -2743,7 +2769,8 @@ class Session(_SessionClassMethods): large numbers of simple rows. The values within the dictionaries as given are typically passed - without modification into Core :meth:`.Insert` constructs, after + without modification into Core :meth:`_expression.Insert` constructs, + after organizing the values within them across the tables to which the given mapper is mapped. @@ -2761,7 +2788,8 @@ class Session(_SessionClassMethods): **before using this method, and fully test and confirm the functionality of all code developed using these systems.** - :param mapper: a mapped class, or the actual :class:`.Mapper` object, + :param mapper: a mapped class, or the actual :class:`_orm.Mapper` + object, representing the single kind of object represented within the mapping list. @@ -2852,7 +2880,8 @@ class Session(_SessionClassMethods): **before using this method, and fully test and confirm the functionality of all code developed using these systems.** - :param mapper: a mapped class, or the actual :class:`.Mapper` object, + :param mapper: a mapped class, or the actual :class:`_orm.Mapper` + object, representing the single kind of object represented within the mapping list. @@ -3014,7 +3043,7 @@ class Session(_SessionClassMethods): :class:`.Session` has actually begun to use DBAPI resources is to implement a listener using the :meth:`.SessionEvents.after_begin` method, which will deliver both the :class:`.Session` as well as the - target :class:`.Connection` to a user-defined event listener. + target :class:`_engine.Connection` to a user-defined event listener. The "partial rollback" state refers to when an "inner" transaction, typically used during a flush, encounters an error and emits a @@ -3147,7 +3176,8 @@ class sessionmaker(_SessionClassMethods): The class also includes a method :meth:`.configure`, which can be used to specify additional keyword arguments to the factory, which will take effect for subsequent :class:`.Session` objects generated. - This is usually used to associate one or more :class:`.Engine` objects + This is usually used to associate one or more :class:`_engine.Engine` + objects with an existing :class:`.sessionmaker` factory before it is first used:: @@ -3183,7 +3213,8 @@ class sessionmaker(_SessionClassMethods): accepted by :class:`.Session` directly. See the :meth:`.Session.__init__` docstring for more details on parameters. - :param bind: a :class:`.Engine` or other :class:`.Connectable` with + :param bind: a :class:`_engine.Engine` or other :class:`.Connectable` + with which newly created :class:`.Session` objects will be associated. :param class\_: class to use in order to create new :class:`.Session` objects. Defaults to :class:`.Session`. diff --git a/lib/sqlalchemy/orm/state.py b/lib/sqlalchemy/orm/state.py index 5a885b118..48546f24e 100644 --- a/lib/sqlalchemy/orm/state.py +++ b/lib/sqlalchemy/orm/state.py @@ -47,7 +47,7 @@ class InstanceState(interfaces.InspectionAttrInfo): status within a particular :class:`.Session` and details about data on individual attributes. The public API in order to acquire a :class:`.InstanceState` object - is to use the :func:`.inspect` system:: + is to use the :func:`_sa.inspect` system:: >>> from sqlalchemy import inspect >>> insp = inspect(some_mapped_object) @@ -273,7 +273,7 @@ class InstanceState(interfaces.InspectionAttrInfo): """Return the mapped identity of the mapped object. This is the primary key identity as persisted by the ORM which can always be passed directly to - :meth:`.Query.get`. + :meth:`_query.Query.get`. Returns ``None`` if the object has no primary key identity. @@ -316,7 +316,7 @@ class InstanceState(interfaces.InspectionAttrInfo): @util.memoized_property def mapper(self): - """Return the :class:`.Mapper` used for this mapped object.""" + """Return the :class:`_orm.Mapper` used for this mapped object.""" return self.manager.mapper @property @@ -894,7 +894,8 @@ class AttributeState(object): The attribute history system tracks changes on a **per flush basis**. Each time the :class:`.Session` is flushed, the history of each attribute is reset to empty. The :class:`.Session` by - default autoflushes each time a :class:`.Query` is invoked. For + default autoflushes each time a :class:`_query.Query` is invoked. + For options on how to control this, see :ref:`session_flushing`. @@ -920,7 +921,8 @@ class AttributeState(object): The attribute history system tracks changes on a **per flush basis**. Each time the :class:`.Session` is flushed, the history of each attribute is reset to empty. The :class:`.Session` by - default autoflushes each time a :class:`.Query` is invoked. For + default autoflushes each time a :class:`_query.Query` is invoked. + For options on how to control this, see :ref:`session_flushing`. .. seealso:: diff --git a/lib/sqlalchemy/orm/strategies.py b/lib/sqlalchemy/orm/strategies.py index bb08d31ea..2e9b2f316 100644 --- a/lib/sqlalchemy/orm/strategies.py +++ b/lib/sqlalchemy/orm/strategies.py @@ -1374,7 +1374,7 @@ class SubqueryLoader(PostLoader): return q class _SubqCollections(object): - """Given a :class:`.Query` used to emit the "subquery load", + """Given a :class:`_query.Query` used to emit the "subquery load", provide a load interface that executes the query at the first moment a value is needed. diff --git a/lib/sqlalchemy/orm/strategy_options.py b/lib/sqlalchemy/orm/strategy_options.py index 6475f79de..2fd628d0b 100644 --- a/lib/sqlalchemy/orm/strategy_options.py +++ b/lib/sqlalchemy/orm/strategy_options.py @@ -34,26 +34,29 @@ from ..sql.traversals import HasCacheKey class Load(HasCacheKey, Generative, MapperOption): """Represents loader options which modify the state of a - :class:`.Query` in order to affect how various mapped attributes are + :class:`_query.Query` in order to affect how various mapped attributes are loaded. - The :class:`.Load` object is in most cases used implicitly behind the - scenes when one makes use of a query option like :func:`.joinedload`, - :func:`.defer`, or similar. However, the :class:`.Load` object + The :class:`_orm.Load` object is in most cases used implicitly behind the + scenes when one makes use of a query option like :func:`_orm.joinedload`, + :func:`.defer`, or similar. However, the :class:`_orm.Load` object can also be used directly, and in some cases can be useful. - To use :class:`.Load` directly, instantiate it with the target mapped + To use :class:`_orm.Load` directly, instantiate it with the target mapped class as the argument. This style of usage is - useful when dealing with a :class:`.Query` that has multiple entities:: + useful when dealing with a :class:`_query.Query` + that has multiple entities:: myopt = Load(MyClass).joinedload("widgets") - The above ``myopt`` can now be used with :meth:`.Query.options`, where it + The above ``myopt`` can now be used with :meth:`_query.Query.options`, + where it will only take effect for the ``MyClass`` entity:: session.query(MyClass, MyOtherClass).options(myopt) - One case where :class:`.Load` is useful as public API is when specifying + One case where :class:`_orm.Load` + is useful as public API is when specifying "wildcard" options that only take effect for a certain class:: session.query(Order).options(Load(Order).lazyload('*')) @@ -363,7 +366,8 @@ class Load(HasCacheKey, Generative, MapperOption): @_generative def options(self, *opts): - r"""Apply a series of options as sub-options to this :class:`.Load` + r"""Apply a series of options as sub-options to this + :class:`_orm.Load` object. E.g.:: @@ -379,8 +383,8 @@ class Load(HasCacheKey, Generative, MapperOption): ) :param \*opts: A series of loader option objects (ultimately - :class:`.Load` objects) which should be applied to the path - specified by this :class:`.Load` object. + :class:`_orm.Load` objects) which should be applied to the path + specified by this :class:`_orm.Load` object. .. versionadded:: 1.3.6 @@ -555,8 +559,8 @@ class Load(HasCacheKey, Generative, MapperOption): class _UnboundLoad(Load): """Represent a loader option that isn't tied to a root entity. - The loader option will produce an entity-linked :class:`.Load` - object when it is passed :meth:`.Query.options`. + The loader option will produce an entity-linked :class:`_orm.Load` + object when it is passed :meth:`_query.Query.options`. This provides compatibility with the traditional system of freestanding options, e.g. ``joinedload('x.y.z')``. @@ -981,7 +985,7 @@ class loader_option(object): def _add_unbound_fn(self, fn): self._unbound_fn = fn fn_doc = self.fn.__doc__ - self.fn.__doc__ = """Produce a new :class:`.Load` object with the + self.fn.__doc__ = """Produce a new :class:`_orm.Load` object with the :func:`_orm.%(name)s` option applied. See :func:`_orm.%(name)s` for usage examples. @@ -1029,7 +1033,7 @@ def contains_eager(loadopt, attr, alias=None): r"""Indicate that the given attribute should be eagerly loaded from columns stated manually in the query. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. The option is used in conjunction with an explicit join that loads @@ -1123,7 +1127,7 @@ def load_only(loadopt, *attrs): of column-based attribute names should be loaded; all others will be deferred. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. Example - given a class ``User``, load only the ``name`` and ``fullname`` @@ -1139,8 +1143,9 @@ def load_only(loadopt, *attrs): subqueryload("addresses").load_only("email_address") ) - For a :class:`.Query` that has multiple entities, the lead entity can be - specifically referred to using the :class:`.Load` constructor:: + For a :class:`_query.Query` that has multiple entities, + the lead entity can be + specifically referred to using the :class:`_orm.Load` constructor:: session.query(User, Address).join(User.addresses).options( Load(User).load_only("name", "fullname"), @@ -1170,7 +1175,7 @@ def joinedload(loadopt, attr, innerjoin=None): """Indicate that the given attribute should be loaded using joined eager loading. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. examples:: @@ -1221,7 +1226,7 @@ def joinedload(loadopt, attr, innerjoin=None): .. note:: The "unnested" flag does **not** affect the JOIN rendered from a many-to-many association table, e.g. a table configured - as :paramref:`.relationship.secondary`, to the target table; for + as :paramref:`_orm.relationship.secondary`, to the target table; for correctness of results, these joins are always INNER and are therefore right-nested if linked to an OUTER join. @@ -1233,15 +1238,17 @@ def joinedload(loadopt, attr, innerjoin=None): .. note:: - The joins produced by :func:`.orm.joinedload` are **anonymously + The joins produced by :func:`_orm.joinedload` are **anonymously aliased**. The criteria by which the join proceeds cannot be - modified, nor can the :class:`.Query` refer to these joins in any way, + modified, nor can the :class:`_query.Query` + refer to these joins in any way, including ordering. See :ref:`zen_of_eager_loading` for further detail. To produce a specific SQL JOIN which is explicitly available, use - :meth:`.Query.join`. To combine explicit JOINs with eager loading - of collections, use :func:`.orm.contains_eager`; see + :meth:`_query.Query.join`. + To combine explicit JOINs with eager loading + of collections, use :func:`_orm.contains_eager`; see :ref:`contains_eager`. .. seealso:: @@ -1267,7 +1274,7 @@ def subqueryload(loadopt, attr): """Indicate that the given attribute should be loaded using subquery eager loading. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. examples:: @@ -1305,7 +1312,7 @@ def selectinload(loadopt, attr): """Indicate that the given attribute should be loaded using SELECT IN eager loading. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. examples:: @@ -1344,7 +1351,7 @@ def lazyload(loadopt, attr): """Indicate that the given attribute should be loaded using "lazy" loading. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. .. seealso:: @@ -1371,7 +1378,7 @@ def immediateload(loadopt, attr): by the :func:`.selectinload` option, which performs the same task more efficiently by emitting a SELECT for all loaded objects. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. .. seealso:: @@ -1394,11 +1401,11 @@ def immediateload(*keys): def noload(loadopt, attr): """Indicate that the given relationship attribute should remain unloaded. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. - :func:`.orm.noload` applies to :func:`.relationship` attributes; for - column-based attributes, see :func:`.orm.defer`. + :func:`_orm.noload` applies to :func:`_orm.relationship` attributes; for + column-based attributes, see :func:`_orm.defer`. .. seealso:: @@ -1418,7 +1425,7 @@ def noload(*keys): def raiseload(loadopt, attr, sql_only=False): """Indicate that the given attribute should raise an error if accessed. - A relationship attribute configured with :func:`.orm.raiseload` will + A relationship attribute configured with :func:`_orm.raiseload` will raise an :exc:`~sqlalchemy.exc.InvalidRequestError` upon access. The typical way this is useful is when an application is attempting to ensure that all relationship attributes that are accessed in a particular context @@ -1426,7 +1433,8 @@ def raiseload(loadopt, attr, sql_only=False): to read through SQL logs to ensure lazy loads aren't occurring, this strategy will cause them to raise immediately. - :func:`.orm.raiseload` applies to :func:`.relationship` attributes only. + :func:`_orm.raiseload` applies to :func:`_orm.relationship` + attributes only. In order to apply raise-on-SQL behavior to a column-based attribute, use the :paramref:`.orm.defer.raiseload` parameter on the :func:`.defer` loader option. @@ -1436,7 +1444,7 @@ def raiseload(loadopt, attr, sql_only=False): related value should just be None due to missing keys. When False, the strategy will raise for all varieties of relationship loading. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. @@ -1487,7 +1495,7 @@ def defaultload(loadopt, attr): .. seealso:: - :meth:`.Load.options` - allows for complex hierarchical + :meth:`_orm.Load.options` - allows for complex hierarchical loader option structures with less verbosity than with individual :func:`.defaultload` directives. @@ -1509,7 +1517,7 @@ def defer(loadopt, key, raiseload=False): r"""Indicate that the given column-oriented attribute should be deferred, e.g. not loaded until accessed. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. e.g.:: @@ -1527,12 +1535,13 @@ def defer(loadopt, key, raiseload=False): To specify a deferred load of an attribute on a related class, the path can be specified one token at a time, specifying the loading style for each link along the chain. To leave the loading style - for a link unchanged, use :func:`.orm.defaultload`:: + for a link unchanged, use :func:`_orm.defaultload`:: session.query(MyClass).options(defaultload("someattr").defer("some_column")) - A :class:`.Load` object that is present on a certain path can have - :meth:`.Load.defer` called multiple times, each will operate on the same + A :class:`_orm.Load` object that is present on a certain path can have + :meth:`_orm.Load.defer` called multiple times, + each will operate on the same parent entity:: @@ -1559,7 +1568,7 @@ def defer(loadopt, key, raiseload=False): of specifying a path as a series of attributes, which is now superseded by the method-chained style. - .. deprecated:: 0.9 The \*addl_attrs on :func:`.orm.defer` is + .. deprecated:: 0.9 The \*addl_attrs on :func:`_orm.defer` is deprecated and will be removed in a future release. Please use method chaining in conjunction with defaultload() to indicate a path. @@ -1569,7 +1578,7 @@ def defer(loadopt, key, raiseload=False): :ref:`deferred` - :func:`.orm.undefer` + :func:`_orm.undefer` """ strategy = {"deferred": True, "instrument": True} @@ -1600,7 +1609,7 @@ def undefer(loadopt, key): The column being undeferred is typically set up on the mapping as a :func:`.deferred` attribute. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. Examples:: @@ -1622,7 +1631,7 @@ def undefer(loadopt, key): of specifying a path as a series of attributes, which is now superseded by the method-chained style. - .. deprecated:: 0.9 The \*addl_attrs on :func:`.orm.undefer` is + .. deprecated:: 0.9 The \*addl_attrs on :func:`_orm.undefer` is deprecated and will be removed in a future release. Please use method chaining in conjunction with defaultload() to indicate a path. @@ -1631,9 +1640,9 @@ def undefer(loadopt, key): :ref:`deferred` - :func:`.orm.defer` + :func:`_orm.defer` - :func:`.orm.undefer_group` + :func:`_orm.undefer_group` """ return loadopt.set_column_strategy( @@ -1669,21 +1678,21 @@ def undefer_group(loadopt, name): To undefer a group of attributes on a related entity, the path can be spelled out using relationship loader options, such as - :func:`.orm.defaultload`:: + :func:`_orm.defaultload`:: session.query(MyClass).options( defaultload("someattr").undefer_group("large_attrs")) - .. versionchanged:: 0.9.0 :func:`.orm.undefer_group` is now specific to a + .. versionchanged:: 0.9.0 :func:`_orm.undefer_group` is now specific to a particular entity load path. .. seealso:: :ref:`deferred` - :func:`.orm.defer` + :func:`_orm.defer` - :func:`.orm.undefer` + :func:`_orm.undefer` """ return loadopt.set_column_strategy( @@ -1700,7 +1709,7 @@ def undefer_group(name): def with_expression(loadopt, key, expression): r"""Apply an ad-hoc SQL expression to a "deferred expression" attribute. - This option is used in conjunction with the :func:`.orm.query_expression` + This option is used in conjunction with the :func:`_orm.query_expression` mapper-level construct that indicates an attribute which should be the target of an ad-hoc SQL expression. diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py index 48e9b19bf..37d3c99cf 100644 --- a/lib/sqlalchemy/orm/util.py +++ b/lib/sqlalchemy/orm/util.py @@ -193,7 +193,7 @@ def polymorphic_union( this is used. :param table_map: mapping of polymorphic identities to - :class:`.Table` objects. + :class:`_schema.Table` objects. :param typecolname: string name of a "discriminator" column, which will be derived from the query, producing the polymorphic identity for each row. If ``None``, no polymorphic discriminator is generated. @@ -293,7 +293,7 @@ def identity_key(*args, **kwargs): (<class '__main__.MyClass'>, (1, 2), None) In this form, the given instance is ultimately run though - :meth:`.Mapper.identity_key_from_instance`, which will have the + :meth:`_orm.Mapper.identity_key_from_instance`, which will have the effect of performing a database check for the corresponding row if the object is expired. @@ -420,12 +420,12 @@ class AliasedClass(object): :class:`.AliasedClass` is also capable of mapping an existing mapped class to an entirely new selectable, provided this selectable is column- compatible with the existing mapped selectable, and it can also be - configured in a mapping as the target of a :func:`.relationship`. + configured in a mapping as the target of a :func:`_orm.relationship`. See the links below for examples. The :class:`.AliasedClass` object is constructed typically using the - :func:`.orm.aliased` function. It also is produced with additional - configuration when using the :func:`.orm.with_polymorphic` function. + :func:`_orm.aliased` function. It also is produced with additional + configuration when using the :func:`_orm.with_polymorphic` function. The resulting object is an instance of :class:`.AliasedClass`. This object implements an attribute scheme which produces the @@ -435,8 +435,8 @@ class AliasedClass(object): including hybrid attributes (see :ref:`hybrids_toplevel`). The :class:`.AliasedClass` can be inspected for its underlying - :class:`.Mapper`, aliased selectable, and other information - using :func:`.inspect`:: + :class:`_orm.Mapper`, aliased selectable, and other information + using :func:`_sa.inspect`:: from sqlalchemy import inspect my_alias = aliased(MyClass) @@ -542,7 +542,7 @@ class AliasedInsp(sql_base.HasCacheKey, InspectionAttr): The :class:`.AliasedInsp` object is returned given an :class:`.AliasedClass` using the - :func:`.inspect` function:: + :func:`_sa.inspect` function:: from sqlalchemy import inspect from sqlalchemy.orm import aliased @@ -554,13 +554,16 @@ class AliasedInsp(sql_base.HasCacheKey, InspectionAttr): include: * ``entity`` - the :class:`.AliasedClass` represented. - * ``mapper`` - the :class:`.Mapper` mapping the underlying class. - * ``selectable`` - the :class:`.Alias` construct which ultimately - represents an aliased :class:`.Table` or :class:`.Select` + * ``mapper`` - the :class:`_orm.Mapper` mapping the underlying class. + * ``selectable`` - the :class:`_expression.Alias` + construct which ultimately + represents an aliased :class:`_schema.Table` or + :class:`_expression.Select` construct. * ``name`` - the name of the alias. Also is used as the attribute - name when returned in a result tuple from :class:`.Query`. - * ``with_polymorphic_mappers`` - collection of :class:`.Mapper` objects + name when returned in a result tuple from :class:`_query.Query`. + * ``with_polymorphic_mappers`` - collection of :class:`_orm.Mapper` + objects indicating all those mappers expressed in the select construct for the :class:`.AliasedClass`. * ``polymorphic_on`` - an alternate column or SQL expression which @@ -769,37 +772,45 @@ def aliased(element, alias=None, name=None, flat=False, adapt_on_names=False): The :func:`.aliased` function is used to create an ad-hoc mapping of a mapped class to a new selectable. By default, a selectable is generated - from the normally mapped selectable (typically a :class:`.Table`) using the - :meth:`.FromClause.alias` method. However, :func:`.aliased` can also be - used to link the class to a new :func:`~.sql.expression.select` statement. + from the normally mapped selectable (typically a :class:`_schema.Table` + ) using the + :meth:`_expression.FromClause.alias` method. However, :func:`.aliased` + can also be + used to link the class to a new :func:`_expression.select` statement. Also, the :func:`.with_polymorphic` function is a variant of :func:`.aliased` that is intended to specify a so-called "polymorphic selectable", that corresponds to the union of several joined-inheritance subclasses at once. For convenience, the :func:`.aliased` function also accepts plain - :class:`.FromClause` constructs, such as a :class:`.Table` or - :func:`~.sql.expression.select` construct. In those cases, the - :meth:`.FromClause.alias` method is called on the object and the new - :class:`.Alias` object returned. The returned :class:`.Alias` is not + :class:`_expression.FromClause` constructs, such as a + :class:`_schema.Table` or + :func:`_expression.select` construct. In those cases, the + :meth:`_expression.FromClause.alias` + method is called on the object and the new + :class:`_expression.Alias` object returned. The returned + :class:`_expression.Alias` is not ORM-mapped in this case. :param element: element to be aliased. Is normally a mapped class, - but for convenience can also be a :class:`.FromClause` element. + but for convenience can also be a :class:`_expression.FromClause` element + . :param alias: Optional selectable unit to map the element to. This should - normally be a :class:`.Alias` object corresponding to the :class:`.Table` - to which the class is mapped, or to a :func:`~.sql.expression.select` + normally be a :class:`_expression.Alias` object corresponding to the + :class:`_schema.Table` + to which the class is mapped, or to a :func:`_expression.select` construct that is compatible with the mapping. By default, a simple anonymous alias of the mapped table is generated. :param name: optional string name to use for the alias, if not specified by the ``alias`` parameter. The name, among other things, forms the attribute name that will be accessible via tuples returned by a - :class:`.Query` object. + :class:`_query.Query` object. :param flat: Boolean, will be passed through to the - :meth:`.FromClause.alias` call so that aliases of :class:`.Join` objects + :meth:`_expression.FromClause.alias` call so that aliases of + :class:`_expression.Join` objects don't include an enclosing SELECT. This can lead to more efficient queries in many circumstances. A JOIN against a nested JOIN will be rewritten as a JOIN against an aliased SELECT subquery on backends that @@ -807,7 +818,7 @@ def aliased(element, alias=None, name=None, flat=False, adapt_on_names=False): .. versionadded:: 0.9.0 - .. seealso:: :meth:`.Join.alias` + .. seealso:: :meth:`_expression.Join.alias` :param adapt_on_names: if True, more liberal "matching" will be used when mapping the mapped columns of the ORM entity to those of the @@ -879,7 +890,7 @@ def with_polymorphic( .. seealso:: :ref:`with_polymorphic` - full discussion of - :func:`.orm.with_polymorphic`. + :func:`_orm.with_polymorphic`. :param base: Base class to be aliased. @@ -895,11 +906,13 @@ def with_polymorphic( support parenthesized joins, such as SQLite and older versions of MySQL. However if the :paramref:`.with_polymorphic.selectable` parameter is in use - with an existing :class:`.Alias` construct, then you should not + with an existing :class:`_expression.Alias` construct, + then you should not set this flag. :param flat: Boolean, will be passed through to the - :meth:`.FromClause.alias` call so that aliases of :class:`.Join` + :meth:`_expression.FromClause.alias` call so that aliases of + :class:`_expression.Join` objects don't include an enclosing SELECT. This can lead to more efficient queries in many circumstances. A JOIN against a nested JOIN will be rewritten as a JOIN against an aliased SELECT subquery on @@ -910,7 +923,7 @@ def with_polymorphic( .. versionadded:: 0.9.0 - .. seealso:: :meth:`.Join.alias` + .. seealso:: :meth:`_expression.Join.alias` :param selectable: a table or subquery that will be used in place of the generated FROM clause. This argument is @@ -971,7 +984,7 @@ def _orm_deannotate(element): """Remove annotations that link a column to a particular mapping. Note this doesn't affect "remote" and "foreign" annotations - passed by the :func:`.orm.foreign` and :func:`.orm.remote` + passed by the :func:`_orm.foreign` and :func:`_orm.remote` annotators. """ @@ -1121,21 +1134,21 @@ def join( ): r"""Produce an inner join between left and right clauses. - :func:`.orm.join` is an extension to the core join interface - provided by :func:`.sql.expression.join()`, where the + :func:`_orm.join` is an extension to the core join interface + provided by :func:`_expression.join()`, where the left and right selectables may be not only core selectable - objects such as :class:`.Table`, but also mapped classes or + objects such as :class:`_schema.Table`, but also mapped classes or :class:`.AliasedClass` instances. The "on" clause can be a SQL expression, or an attribute or string name - referencing a configured :func:`.relationship`. + referencing a configured :func:`_orm.relationship`. - :func:`.orm.join` is not commonly needed in modern usage, + :func:`_orm.join` is not commonly needed in modern usage, as its functionality is encapsulated within that of the - :meth:`.Query.join` method, which features a - significant amount of automation beyond :func:`.orm.join` - by itself. Explicit usage of :func:`.orm.join` - with :class:`.Query` involves usage of the - :meth:`.Query.select_from` method, as in:: + :meth:`_query.Query.join` method, which features a + significant amount of automation beyond :func:`_orm.join` + by itself. Explicit usage of :func:`_orm.join` + with :class:`_query.Query` involves usage of the + :meth:`_query.Query.select_from` method, as in:: from sqlalchemy.orm import join session.query(User).\ @@ -1149,7 +1162,7 @@ def join( join(User.addresses).\ filter(Address.email_address=='foo@bar.com') - See :meth:`.Query.join` for information on modern usage + See :meth:`_query.Query.join` for information on modern usage of ORM level joins. .. deprecated:: 0.8 @@ -1164,7 +1177,7 @@ def join( def outerjoin(left, right, onclause=None, full=False, join_to_left=None): """Produce a left outer join between left and right clauses. - This is the "outer join" version of the :func:`.orm.join` function, + This is the "outer join" version of the :func:`_orm.join` function, featuring the same behavior except that an OUTER JOIN is generated. See that function's documentation for other usage details. @@ -1174,7 +1187,8 @@ def outerjoin(left, right, onclause=None, full=False, join_to_left=None): def with_parent(instance, prop, from_entity=None): """Create filtering criterion that relates this query's primary entity - to the given related instance, using established :func:`.relationship()` + to the given related instance, using established + :func:`_orm.relationship()` configuration. The SQL rendered is the same as that rendered when a lazy loader @@ -1184,7 +1198,7 @@ def with_parent(instance, prop, from_entity=None): in the rendered statement. :param instance: - An instance which has some :func:`.relationship`. + An instance which has some :func:`_orm.relationship`. :param property: String property name, or class-bound attribute, which indicates @@ -1193,7 +1207,7 @@ def with_parent(instance, prop, from_entity=None): :param from_entity: Entity in which to consider as the left side. This defaults to the - "zero" entity of the :class:`.Query` itself. + "zero" entity of the :class:`_query.Query` itself. .. versionadded:: 1.2 |