diff options
Diffstat (limited to 'lib/sqlalchemy/orm')
| -rw-r--r-- | lib/sqlalchemy/orm/attributes.py | 39 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/collections.py | 2 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/deprecated_interfaces.py | 28 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/descriptor_props.py | 26 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/mapper.py | 34 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/properties.py | 16 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/query.py | 12 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/relationships.py | 16 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/session.py | 87 | ||||
| -rw-r--r-- | lib/sqlalchemy/orm/strategy_options.py | 45 |
10 files changed, 191 insertions, 114 deletions
diff --git a/lib/sqlalchemy/orm/attributes.py b/lib/sqlalchemy/orm/attributes.py index c7c242501..cd81d759d 100644 --- a/lib/sqlalchemy/orm/attributes.py +++ b/lib/sqlalchemy/orm/attributes.py @@ -452,50 +452,57 @@ class AttributeImpl(object): ): r"""Construct an AttributeImpl. - \class_ - associated class + :param \class_: associated class - key - string name of the attribute + :param key: string name of the attribute - \callable_ + :param \callable_: optional function which generates a callable based on a parent instance, which produces the "default" values for a scalar or collection attribute when it's first accessed, if not present already. - trackparent + :param trackparent: if True, attempt to track if an instance has a parent attached to it via this attribute. - extension + :param extension: a single or list of AttributeExtension object(s) which will - receive set/delete/append/remove/etc. events. Deprecated. + receive set/delete/append/remove/etc. events. The event package is now used. - compare_function + .. deprecated:: 1.3 + + The :paramref:`.AttributeImpl.extension` parameter is deprecated + and will be removed in a future release, corresponding to the + "extension" parameter on the :class:`.MapperProprty` classes + like :func:`.column_property` and :func:`.relationship` The + events system is now used. + + :param compare_function: a function that compares two values which are normally assignable to this attribute. - active_history + :param active_history: indicates that get_history() should always return the "old" value, even if it means executing a lazy callable upon attribute change. - parent_token + :param parent_token: Usually references the MapperProperty, used as a key for the hasparent() function to identify an "owning" attribute. Allows multiple AttributeImpls to all match a single owner attribute. - expire_missing + :param expire_missing: if False, don't add an "expiry" callable to this attribute during state.expire_attributes(None), if no value is present for this key. - send_modified_events + :param send_modified_events: if False, the InstanceState._modified_event method will have no effect; this means the attribute will never show up as changed in a history entry. + """ self.class_ = class_ self.key = key @@ -1841,9 +1848,9 @@ def init_collection(obj, key): For an easier way to do the above, see :func:`~sqlalchemy.orm.attributes.set_committed_value`. - obj is an instrumented object instance. An InstanceState - is accepted directly for backwards compatibility but - this usage is deprecated. + :param obj: a mapped object + + :param key: string attribute name where the collection is located. """ state = instance_state(obj) diff --git a/lib/sqlalchemy/orm/collections.py b/lib/sqlalchemy/orm/collections.py index 1e561369f..b9297e15c 100644 --- a/lib/sqlalchemy/orm/collections.py +++ b/lib/sqlalchemy/orm/collections.py @@ -460,7 +460,7 @@ class collection(object): @staticmethod @util.deprecated( "1.3", - "The :meth:`.collection.converter` method is deprecated and will " + "The :meth:`.collection.converter` handler is deprecated and will " "be removed in a future release. Please refer to the " ":class:`.AttributeEvents.bulk_replace` listener interface in " "conjunction with the :func:`.event.listen` function.", diff --git a/lib/sqlalchemy/orm/deprecated_interfaces.py b/lib/sqlalchemy/orm/deprecated_interfaces.py index 50ef8448a..4069b43a5 100644 --- a/lib/sqlalchemy/orm/deprecated_interfaces.py +++ b/lib/sqlalchemy/orm/deprecated_interfaces.py @@ -87,6 +87,14 @@ class MapperExtension(object): ls_meth = getattr(listener, meth) if not util.methods_equivalent(me_meth, ls_meth): + util.warn_deprecated( + "MapperExtension.%s is deprecated. The " + "MapperExtension class will be removed in a future " + "release. Please transition to the @event interface, " + "using @event.listens_for(mapped_class, '%s')." + % (meth, meth) + ) + if meth == "reconstruct_instance": def go(ls_meth): @@ -359,6 +367,13 @@ class SessionExtension(object): ls_meth = getattr(listener, meth) if not util.methods_equivalent(me_meth, ls_meth): + util.warn_deprecated( + "SessionExtension.%s is deprecated. The " + "SessionExtension class will be removed in a future " + "release. Please transition to the @event interface, " + "using @event.listens_for(Session, '%s')." % (meth, meth) + ) + event.listen(self, meth, getattr(listener, meth)) def before_commit(self, session): @@ -492,6 +507,19 @@ class AttributeExtension(object): @classmethod def _adapt_listener(cls, self, listener): + for meth in ["append", "remove", "set"]: + me_meth = getattr(AttributeExtension, meth) + ls_meth = getattr(listener, meth) + + if not util.methods_equivalent(me_meth, ls_meth): + util.warn_deprecated( + "AttributeExtension.%s is deprecated. The " + "AttributeExtension class will be removed in a future " + "release. Please transition to the @event interface, " + "using @event.listens_for(Class.attribute, '%s')." + % (meth, meth) + ) + event.listen( self, "append", diff --git a/lib/sqlalchemy/orm/descriptor_props.py b/lib/sqlalchemy/orm/descriptor_props.py index 45600928f..c1e5866b5 100644 --- a/lib/sqlalchemy/orm/descriptor_props.py +++ b/lib/sqlalchemy/orm/descriptor_props.py @@ -93,6 +93,15 @@ class CompositeProperty(DescriptorProperty): """ + @util.deprecated_params( + extension=( + "0.7", + ":class:`.AttributeExtension` is deprecated in favor of the " + ":class:`.AttributeEvents` listener interface. The " + ":paramref:`.composite.extension` parameter will be " + "removed in a future release.", + ) + ) def __init__(self, class_, *attrs, **kwargs): r"""Return a composite column-based property for use with a Mapper. @@ -141,13 +150,6 @@ class CompositeProperty(DescriptorProperty): attribute listeners for the resulting descriptor placed on the class. - .. deprecated:: 0.7 - - :class:`.AttributeExtension` is deprecated in favor of the - :class:`.AttributeEvents` listener interface. The - :paramref:`.composite.extension` parameter will be - removed in a future release. - """ super(CompositeProperty, self).__init__() @@ -698,6 +700,12 @@ class SynonymProperty(DescriptorProperty): @util.langhelpers.dependency_for("sqlalchemy.orm.properties", add_to_all=True) +@util.deprecated_cls( + "0.7", + ":func:`.comparable_property` is deprecated and will be removed in a " + "future release. Please refer to the :mod:`~sqlalchemy.ext.hybrid` " + "extension.", +) class ComparableProperty(DescriptorProperty): """Instruments a Python property for use in query expressions.""" @@ -707,10 +715,6 @@ class ComparableProperty(DescriptorProperty): """Provides a method of applying a :class:`.PropComparator` to any Python descriptor attribute. - .. deprecated:: 0.7 - :func:`.comparable_property` is superseded by - the :mod:`~sqlalchemy.ext.hybrid` extension. See the example - at :ref:`hybrid_custom_comparators`. Allows any Python descriptor to behave like a SQL-enabled attribute when used at the class level in queries, allowing diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py index a394ec06e..0c8ab0b10 100644 --- a/lib/sqlalchemy/orm/mapper.py +++ b/lib/sqlalchemy/orm/mapper.py @@ -104,6 +104,22 @@ class Mapper(InspectionAttr): _new_mappers = False _dispose_called = False + @util.deprecated_params( + extension=( + "0.7", + ":class:`.MapperExtension` is deprecated in favor of the " + ":class:`.MapperEvents` listener interface. The " + ":paramref:`.mapper.extension` parameter will be " + "removed in a future release.", + ), + order_by=( + "1.1", + "The :paramref:`.Mapper.order_by` parameter " + "is deprecated, and will be removed in a future release. " + "Use :meth:`.Query.order_by` to determine the ordering of a " + "result set.", + ), + ) def __init__( self, class_, @@ -272,13 +288,6 @@ class Mapper(InspectionAttr): list of :class:`.MapperExtension` instances which will be applied to all operations by this :class:`.Mapper`. - .. deprecated:: 0.7 - - :class:`.MapperExtension` is deprecated in favor of the - :class:`.MapperEvents` listener interface. The - :paramref:`.mapper.extension` parameter will be - removed in a future release. - :param include_properties: An inclusive list or set of string column names to map. @@ -339,11 +348,6 @@ class Mapper(InspectionAttr): ordering for entities. By default mappers have no pre-defined ordering. - .. deprecated:: 1.1 The :paramref:`.Mapper.order_by` parameter - is deprecated, and will be removed in a future release. - Use :meth:`.Query.order_by` to determine the ordering of a - result set. - :param passive_deletes: Indicates DELETE behavior of foreign key columns when a joined-table inheritance entity is being deleted. Defaults to ``False`` for a base mapper; for an inheriting mapper, @@ -604,12 +608,6 @@ class Mapper(InspectionAttr): if order_by is not False: self.order_by = util.to_list(order_by) - util.warn_deprecated( - "Mapper.order_by is deprecated." - "Use Query.order_by() in order to affect the ordering of ORM " - "result sets." - ) - else: self.order_by = order_by diff --git a/lib/sqlalchemy/orm/properties.py b/lib/sqlalchemy/orm/properties.py index 328c9b1b4..530eadb6b 100644 --- a/lib/sqlalchemy/orm/properties.py +++ b/lib/sqlalchemy/orm/properties.py @@ -55,6 +55,15 @@ class ColumnProperty(StrategizedProperty): "_deferred_column_loader", ) + @util.deprecated_params( + extension=( + "0.7", + ":class:`.AttributeExtension` is deprecated in favor of the " + ":class:`.AttributeEvents` listener interface. The " + ":paramref:`.column_property.extension` parameter will be " + "removed in a future release.", + ) + ) def __init__(self, *columns, **kwargs): r"""Provide a column-level property for use with a Mapper. @@ -120,13 +129,6 @@ class ColumnProperty(StrategizedProperty): which will be prepended to the list of attribute listeners for the resulting descriptor placed on the class. - .. deprecated:: 0.7 - - :class:`.AttributeExtension` is deprecated in favor of the - :class:`.AttributeEvents` listener interface. The - :paramref:`.column_property.extension` parameter will be - removed in a future release. - """ super(ColumnProperty, self).__init__() self._orig_columns = [expression._labeled(c) for c in columns] diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py index 387a72d0b..150347995 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -1569,16 +1569,16 @@ class Query(object): self._execution_options = self._execution_options.union(kwargs) @_generative() + @util.deprecated( + "0.9", + "The :meth:`.Query.with_lockmode` method is deprecated and will " + "be removed in a future release. Please refer to " + ":meth:`.Query.with_for_update`. ", + ) def with_lockmode(self, mode): """Return a new :class:`.Query` object with the specified "locking mode", which essentially refers to the ``FOR UPDATE`` clause. - .. deprecated:: 0.9 - - The :meth:`.Query.with_lockmode` method is deprecated and will - be removed in a future release. Please refer to - :meth:`.Query.with_for_update`. - :param mode: a string representing the desired locking mode. Valid values are: diff --git a/lib/sqlalchemy/orm/relationships.py b/lib/sqlalchemy/orm/relationships.py index af4d9a782..be2093fb9 100644 --- a/lib/sqlalchemy/orm/relationships.py +++ b/lib/sqlalchemy/orm/relationships.py @@ -105,6 +105,15 @@ class RelationshipProperty(StrategizedProperty): _dependency_processor = None + @util.deprecated_params( + extension=( + "0.7", + ":class:`.AttributeExtension` is deprecated in favor of the " + ":class:`.AttributeEvents` listener interface. The " + ":paramref:`.relationship.extension` parameter will be " + "removed in a future release.", + ) + ) def __init__( self, argument, @@ -402,13 +411,6 @@ class RelationshipProperty(StrategizedProperty): which will be prepended to the list of attribute listeners for the resulting descriptor placed on the class. - .. deprecated:: 0.7 - - :class:`.AttributeExtension` is deprecated in favor of the - :class:`.AttributeEvents` listener interface. The - :paramref:`.relationship.extension` parameter will be - removed in a future release. - :param foreign_keys: a list of columns which are to be used as "foreign key" diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index 5993e91b8..53f99b99d 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -427,7 +427,7 @@ class SessionTransaction(object): "given Connection's Engine" ) else: - conn = bind.contextual_connect() + conn = bind._contextual_connect() if execution_options: conn = conn.execution_options(**execution_options) @@ -642,6 +642,30 @@ class Session(_SessionClassMethods): "scalar", ) + @util.deprecated_params( + weak_identity_map=( + "1.0", + "The :paramref:`.Session.weak_identity_map` parameter as well as " + "the strong-referencing identity map are deprecated, and will be " + "removed in a future release. For the use case where objects " + "present in a :class:`.Session` need to be automatically strong " + "referenced, see the recipe at " + ":ref:`session_referencing_behavior` for an event-based approach " + "to maintaining strong identity references. ", + ), + _enable_transaction_accounting=( + "0.7", + "The :paramref:`.Session._enable_transaction_accounting` " + "parameter is deprecated and will be removed in a future release.", + ), + extension=( + "0.7", + ":class:`.SessionExtension` is deprecated in favor of the " + ":class:`.SessionEvents` listener interface. The " + ":paramref:`.Session.extension` parameter will be " + "removed in a future release.", + ), + ) def __init__( self, bind=None, @@ -650,12 +674,12 @@ class Session(_SessionClassMethods): _enable_transaction_accounting=True, autocommit=False, twophase=False, - weak_identity_map=True, + weak_identity_map=None, binds=None, extension=None, enable_baked_queries=True, info=None, - query_cls=query.Query, + query_cls=None, ): r"""Construct a new Session. @@ -754,15 +778,10 @@ class Session(_SessionClassMethods): .. versionadded:: 1.2 - :param _enable_transaction_accounting: Defaults to ``True``. A + :param _enable_transaction_accounting: A legacy-only flag which when ``False`` disables *all* 0.5-style object accounting on transaction boundaries. - .. deprecated:: 0.7 - - the :paramref:`.Session._enable_transaction_accounting` - parameter will be removed in a future release. - :param expire_on_commit: Defaults to ``True``. When ``True``, all instances will be fully expired after each :meth:`~.commit`, so that all attribute/object access subsequent to a completed @@ -773,13 +792,6 @@ class Session(_SessionClassMethods): of such instances, which will receive pre- and post- commit and flush events, as well as a post-rollback event. - .. deprecated:: 0.7 - - :class:`.SessionExtension` is deprecated in favor of the - :class:`.SessionEvents` listener interface. The - :paramref:`.Session.extension` parameter will be - removed in a future release. - :param info: optional dictionary of arbitrary data to be associated with this :class:`.Session`. Is available via the :attr:`.Session.info` attribute. Note the dictionary is copied at @@ -807,30 +819,14 @@ class Session(_SessionClassMethods): strongly referenced until explicitly removed or the :class:`.Session` is closed. - .. deprecated:: 1.0 - - The :paramref:`.Session.weak_identity_map` parameter as well as - the strong-referencing identity map are deprecated, and will be - removed in a future release. For the use case where objects - present in a :class:`.Session` need to be automatically strong - referenced, see the recipe at - :ref:`session_referencing_behavior` for an event-based approach - to maintaining strong identity references. - """ - if weak_identity_map: + if weak_identity_map in (True, None): self._identity_cls = identity.WeakInstanceDict else: - util.warn_deprecated( - "weak_identity_map=False is deprecated. " - "See the documentation on 'Session Referencing Behavior' " - "for an event-based approach to maintaining strong identity " - "references." - ) - self._identity_cls = identity.StrongInstanceDict + self.identity_map = self._identity_cls() self._new = {} # InstanceState->object, strong refs object @@ -846,8 +842,9 @@ class Session(_SessionClassMethods): self.expire_on_commit = expire_on_commit self.enable_baked_queries = enable_baked_queries self._enable_transaction_accounting = _enable_transaction_accounting + self.twophase = twophase - self._query_cls = query_cls + self._query_cls = query_cls if query_cls else query.Query if info: self.info.update(info) @@ -1068,7 +1065,7 @@ class Session(_SessionClassMethods): Alternatively, if this :class:`.Session` is configured with ``autocommit=True``, an ad-hoc :class:`.Connection` is returned - using :meth:`.Engine.contextual_connect` on the underlying + using :meth:`.Engine.connect` on the underlying :class:`.Engine`. Ambiguity in multi-bind or unbound :class:`.Session` objects can be @@ -1132,7 +1129,7 @@ class Session(_SessionClassMethods): engine, execution_options ) else: - conn = engine.contextual_connect(**kw) + conn = engine._contextual_connect(**kw) if execution_options: conn = conn.execution_options(**execution_options) return conn @@ -2872,7 +2869,15 @@ class Session(_SessionClassMethods): finally: self._flushing = False - def is_modified(self, instance, include_collections=True, passive=True): + @util.deprecated_params( + passive=( + "0.8", + "The :paramref:`.Session.is_modified.passive` flag is deprecated " + "and will be removed in a future release. The flag is no longer " + "used and is ignored.", + ) + ) + def is_modified(self, instance, include_collections=True, passive=None): r"""Return ``True`` if the given instance has locally modified attributes. @@ -2921,11 +2926,7 @@ class Session(_SessionClassMethods): way to detect only local-column based properties (i.e. scalar columns or many-to-one foreign keys) that would result in an UPDATE for this instance upon flush. - :param passive: - - .. deprecated:: 0.8 - The ``passive`` flag is deprecated and will be removed - in a future release. The flag is no longer used and is ignored. + :param passive: not used """ state = object_state(instance) diff --git a/lib/sqlalchemy/orm/strategy_options.py b/lib/sqlalchemy/orm/strategy_options.py index b3f52a2f7..6f9746daa 100644 --- a/lib/sqlalchemy/orm/strategy_options.py +++ b/lib/sqlalchemy/orm/strategy_options.py @@ -818,7 +818,6 @@ See :func:`.orm.%(name)s` for usage examples. return self def _add_unbound_all_fn(self, fn): - self._unbound_all_fn = fn fn.__doc__ = """Produce a standalone "all" option for :func:`.orm.%(name)s`. .. deprecated:: 0.9 @@ -834,6 +833,15 @@ See :func:`.orm.%(name)s` for usage examples. """ % { "name": self.name } + fn = util.deprecated( + "0.9", + "The :func:`.%(name)s_all` function is deprecated, and will be " + "removed in a future release. Please use method chaining with " + ":func:`.%(name)s` instead" % {"name": self.name}, + add_deprecation_to_docstring=False, + )(fn) + + self._unbound_all_fn = fn return self @@ -1307,8 +1315,8 @@ def defaultload(*keys): @loader_option() def defer(loadopt, key): - r"""Indicate that the given column-oriented attribute should be deferred, e.g. - not loaded until accessed. + 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 both method-chained and standalone operation. @@ -1346,10 +1354,16 @@ def defer(loadopt, key): :param key: Attribute to be deferred. - :param \*addl_attrs: Deprecated; this option supports the old 0.8 style + :param \*addl_attrs: This option supports the old 0.8 style 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 and will be removed in a future release. Please + use method chaining in conjunction with defaultload() to + indicate a path. + + .. seealso:: :ref:`deferred` @@ -1364,6 +1378,12 @@ def defer(loadopt, key): @defer._add_unbound_fn def defer(key, *addl_attrs): + if addl_attrs: + util.warn_deprecated( + "The *addl_attrs on orm.defer is deprecated. Please use " + "method chaining in conjunction with defaultload() to " + "indicate a path." + ) return _UnboundLoad._from_keys( _UnboundLoad.defer, (key,) + addl_attrs, False, {} ) @@ -1389,12 +1409,21 @@ def undefer(loadopt, key): session.query(MyClass, MyOtherClass).options( Load(MyClass).undefer("*")) + # undefer a column on a related object + session.query(MyClass).options( + defaultload(MyClass.items).undefer('text')) + :param key: Attribute to be undeferred. - :param \*addl_attrs: Deprecated; this option supports the old 0.8 style + :param \*addl_attrs: This option supports the old 0.8 style 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 and will be removed in a future release. Please + use method chaining in conjunction with defaultload() to + indicate a path. + .. seealso:: :ref:`deferred` @@ -1411,6 +1440,12 @@ def undefer(loadopt, key): @undefer._add_unbound_fn def undefer(key, *addl_attrs): + if addl_attrs: + util.warn_deprecated( + "The *addl_attrs on orm.undefer is deprecated. Please use " + "method chaining in conjunction with defaultload() to " + "indicate a path." + ) return _UnboundLoad._from_keys( _UnboundLoad.undefer, (key,) + addl_attrs, False, {} ) |