diff --git a/doc/build/core/sqlelement.rst b/doc/build/core/sqlelement.rst index acee8e4fcf..116c3cc6b7 100644 --- a/doc/build/core/sqlelement.rst +++ b/doc/build/core/sqlelement.rst @@ -158,6 +158,10 @@ the FROM clause of a SELECT statement. .. autoclass:: sqlalchemy.sql.elements.quoted_name + .. attribute:: quote + + whether the string should be unconditionally quoted + .. autoclass:: UnaryExpression :members: diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py index 2e54bc2fc6..551c360930 100644 --- a/lib/sqlalchemy/engine/interfaces.py +++ b/lib/sqlalchemy/engine/interfaces.py @@ -264,11 +264,11 @@ class Dialect(object): def get_primary_keys(self, connection, table_name, schema=None, **kw): """Return information about primary keys in `table_name`. + .. deprecated:: 0.8 - Deprecated. This method is only called by the default - implementation of :meth:`.Dialect.get_pk_constraint`. Dialects should - instead implement the :meth:`.Dialect.get_pk_constraint` method - directly. + The :meth:`.Dialect.get_primary_keys` method is deprecated and + will be removed in a future release. Please refer to the + :meth:`.Dialect.get_pk_constraint` method. """ @@ -1110,20 +1110,27 @@ class Connectable(object): raise NotImplementedError() - @util.deprecated("0.7", - "Use the create() method on the given schema " - "object directly, i.e. :meth:`.Table.create`, " - ":meth:`.Index.create`, :meth:`.MetaData.create_all`") + @util.deprecated( + "0.7", + "The :meth:`.Connectable.create` method is deprecated and will be " + "removed in a future release. Please use the ``.create()`` method " + "on specific schema objects to emit DDL sequences, including " + ":meth:`.Table.create`, :meth:`.Index.create`, and " + ":meth:`.MetaData.create_all`." + ) def create(self, entity, **kwargs): """Emit CREATE statements for the given schema entity. """ raise NotImplementedError() - @util.deprecated("0.7", - "Use the drop() method on the given schema " - "object directly, i.e. :meth:`.Table.drop`, " - ":meth:`.Index.drop`, :meth:`.MetaData.drop_all`") + @util.deprecated( + "0.7", + "The :meth:`.Connectable.drop` method is deprecated and will be " + "removed in a future release. Please use the ``.drop()`` method " + "on specific schema objects to emit DDL sequences, including " + ":meth:`.Table.drop`, :meth:`.Index.drop`, and " + ":meth:`.MetaData.drop_all`.") def drop(self, entity, **kwargs): """Emit DROP statements for the given schema entity. """ diff --git a/lib/sqlalchemy/engine/reflection.py b/lib/sqlalchemy/engine/reflection.py index 4a1e184dfd..671d77cd03 100644 --- a/lib/sqlalchemy/engine/reflection.py +++ b/lib/sqlalchemy/engine/reflection.py @@ -177,10 +177,13 @@ class Inspector(object): resolve cycles, and will raise :class:`.CircularDependencyError` if cycles exist. - .. deprecated:: 1.0.0 - see - :meth:`.Inspector.get_sorted_table_and_fkc_names` for a version - of this which resolves foreign key cycles between tables - automatically. + .. deprecated:: 1.0 + + The :paramref:`get_table_names.order_by` parameter is deprecated + and will be removed in a future release. Please refer to + :meth:`.Inspector.get_sorted_table_and_fkc_names` for a + more comprehensive solution to resolving foreign key cycles + between tables. .. versionchanged:: 0.8 the "foreign_key" sorting sorts tables in order of dependee to dependent; that is, in creation @@ -374,8 +377,12 @@ class Inspector(object): col_def['type'] = coltype() return col_defs - @deprecated('0.7', 'Call to deprecated method get_primary_keys.' - ' Use get_pk_constraint instead.') + @deprecated( + "0.7", + "The :meth:`.Inspector.get_primary_keys` method is deprecated and " + "will be removed in a future release. Please refer to the " + ":meth:`.Inspector.get_pk_constraint` method." + ) def get_primary_keys(self, table_name, schema=None, **kw): """Return information about primary keys in `table_name`. diff --git a/lib/sqlalchemy/event/api.py b/lib/sqlalchemy/event/api.py index acfacc233e..649b028322 100644 --- a/lib/sqlalchemy/event/api.py +++ b/lib/sqlalchemy/event/api.py @@ -31,6 +31,9 @@ def _event_key(target, identifier, fn): def listen(target, identifier, fn, *args, **kw): """Register a listener function for the given target. + The :func:`.listen` function is part of the primary interface for the + SQLAlchemy event system, documented at :ref:`event_toplevel`. + e.g.:: from sqlalchemy import event @@ -92,6 +95,9 @@ def listen(target, identifier, fn, *args, **kw): def listens_for(target, identifier, *args, **kw): """Decorate a function as a listener for the given target + identifier. + The :func:`.listens_for` decorator is part of the primary interface for the + SQLAlchemy event system, documented at :ref:`event_toplevel`. + e.g.:: from sqlalchemy import event diff --git a/lib/sqlalchemy/event/legacy.py b/lib/sqlalchemy/event/legacy.py index 1883070f4d..d03284f3ea 100644 --- a/lib/sqlalchemy/event/legacy.py +++ b/lib/sqlalchemy/event/legacy.py @@ -108,7 +108,8 @@ def _legacy_listen_examples(dispatch_collection, sample_target, fn): text = "" for since, args, conv in dispatch_collection.legacy_signatures: text += ( - "\n# legacy calling style (pre-%(since)s)\n" + "\n# DEPRECATED calling style (pre-%(since)s, " + "will be removed in a future release)\n" "@event.listens_for(%(sample_target)s, '%(event_name)s')\n" "def receive_%(event_name)s(" "%(named_event_arguments)s%(has_kw_arguments)s):\n" @@ -125,16 +126,18 @@ def _legacy_listen_examples(dispatch_collection, sample_target, fn): return text -def _version_signature_changes(dispatch_collection): +def _version_signature_changes(parent_dispatch_cls, dispatch_collection): since, args, conv = dispatch_collection.legacy_signatures[0] return ( - "\n.. versionchanged:: %(since)s\n" - " The ``%(event_name)s`` event now accepts the \n" + "\n.. deprecated:: %(since)s\n" + " The :class:`.%(clsname)s.%(event_name)s` event now accepts the \n" " arguments ``%(named_event_arguments)s%(has_kw_arguments)s``.\n" - " Listener functions which accept the previous argument \n" - " signature(s) listed above will be automatically \n" - " adapted to the new signature." % { + " Support for listener functions which accept the previous \n" + " argument signature(s) listed above as \"deprecated\" will be \n" + " removed in a future release." + % { "since": since, + "clsname": parent_dispatch_cls.__name__, "event_name": dispatch_collection.name, "named_event_arguments": ", ".join(dispatch_collection.arg_names), "has_kw_arguments": ", **kw" if dispatch_collection.has_kw else "" @@ -161,7 +164,8 @@ def _augment_fn_docs(dispatch_collection, parent_dispatch_cls, fn): dispatch_collection, sample_target, fn), " " * 8) - text += _version_signature_changes(dispatch_collection) + text += _version_signature_changes( + parent_dispatch_cls, dispatch_collection) return util.inject_docstring_text(fn.__doc__, text, diff --git a/lib/sqlalchemy/events.py b/lib/sqlalchemy/events.py index 2a84d0a25a..b33b844a34 100644 --- a/lib/sqlalchemy/events.py +++ b/lib/sqlalchemy/events.py @@ -779,8 +779,10 @@ class ConnectionEvents(event.Events): :param exception: The **unwrapped** exception emitted directly from the DBAPI. The class here is specific to the DBAPI module in use. - .. deprecated:: 0.9.7 - replaced by - :meth:`.ConnectionEvents.handle_error` + .. deprecated:: 0.9 - The :meth:`.ConnectionEvents.dbapi_error` + event is deprecated and will be removed in a future release. + Please refer to the :meth:`.ConnectionEvents.handle_error` + event. """ diff --git a/lib/sqlalchemy/interfaces.py b/lib/sqlalchemy/interfaces.py index 30698ea331..28f2b98839 100644 --- a/lib/sqlalchemy/interfaces.py +++ b/lib/sqlalchemy/interfaces.py @@ -8,8 +8,12 @@ """Deprecated core event interfaces. -This module is **deprecated** and is superseded by the -event system. + +.. deprecated:: 0.7 + As of SQLAlchemy 0.7, the new event system described in + :ref:`event_toplevel` replaces the extension/proxy/listener system, + providing a consistent interface to all events without the need for + subclassing. """ @@ -19,10 +23,11 @@ from . import event, util class PoolListener(object): """Hooks into the lifecycle of connections in a :class:`.Pool`. - .. note:: + .. deprecated:: 0.7 - :class:`.PoolListener` is deprecated. Please - refer to :class:`.PoolEvents`. + :class:`.PoolListener` is deprecated and will be removed in a future + release. Please refer to :func:`.event.listen` in conjunction with + the :class:`.PoolEvents` listener interface. Usage:: @@ -154,10 +159,11 @@ class PoolListener(object): class ConnectionProxy(object): """Allows interception of statement execution by Connections. - .. note:: + .. deprecated:: 0.7 - :class:`.ConnectionProxy` is deprecated. Please - refer to :class:`.ConnectionEvents`. + :class:`.ConnectionProxy` is deprecated and will be removed in a future + release. Please refer to :func:`.event.listen` in conjunction with + the :class:`.ConnectionEvents` listener interface. Either or both of the ``execute()`` and ``cursor_execute()`` may be implemented to intercept compiled statement and diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py index 85b84dbfd9..9c313f0893 100644 --- a/lib/sqlalchemy/orm/__init__.py +++ b/lib/sqlalchemy/orm/__init__.py @@ -185,8 +185,11 @@ comparable_property = public_factory(ComparableProperty, ".orm.comparable_property") -@_sa_util.deprecated("0.7", message=":func:`.compile_mappers` " - "is renamed to :func:`.configure_mappers`") +@_sa_util.deprecated( + "0.7", + message=":func:`.compile_mappers` is deprecated and will be removed " + "in a future release. Please use :func:`.configure_mappers`", +) def compile_mappers(): """Initialize the inter-mapper relationships of all mappers that have been defined. diff --git a/lib/sqlalchemy/orm/collections.py b/lib/sqlalchemy/orm/collections.py index 0573de9352..ac8a250709 100644 --- a/lib/sqlalchemy/orm/collections.py +++ b/lib/sqlalchemy/orm/collections.py @@ -421,6 +421,13 @@ class collection(object): return fn @staticmethod + @util.deprecated( + "1.0", + "The :meth:`.collection.linker` handler is deprecated and will " + "be removed in a future release. Please refer to the " + ":meth:`.AttributeEvents.init_collection` " + "and :meth:`.AttributeEvents.dispose_collection` event handlers. " + ) def linker(fn): """Tag the method as a "linked to attribute" event handler. @@ -430,16 +437,18 @@ class collection(object): the instance. A single argument is passed: the collection adapter that has been linked, or None if unlinking. - .. deprecated:: 1.0.0 - the :meth:`.collection.linker` handler - is superseded by the :meth:`.AttributeEvents.init_collection` - and :meth:`.AttributeEvents.dispose_collection` handlers. """ fn._sa_instrument_role = 'linker' return fn link = linker - """deprecated; synonym for :meth:`.collection.linker`.""" + """Synonym for :meth:`.collection.linker`. + + .. deprecated:: 1.0 - :meth:`.collection.link` is deprecated and will be + removed in a future release. + + """ @staticmethod def converter(fn): diff --git a/lib/sqlalchemy/orm/deprecated_interfaces.py b/lib/sqlalchemy/orm/deprecated_interfaces.py index 426288e03f..8d0c1e2031 100644 --- a/lib/sqlalchemy/orm/deprecated_interfaces.py +++ b/lib/sqlalchemy/orm/deprecated_interfaces.py @@ -13,11 +13,11 @@ from .interfaces import EXT_CONTINUE class MapperExtension(object): """Base implementation for :class:`.Mapper` event hooks. - .. note:: + .. deprecated:: 0.7 - :class:`.MapperExtension` is deprecated. Please - refer to :func:`.event.listen` as well as - :class:`.MapperEvents`. + :class:`.MapperExtension` is deprecated and will be removed in a future + release. Please refer to :func:`.event.listen` in conjunction with + the :class:`.MapperEvents` listener interface. New extension classes subclass :class:`.MapperExtension` and are specified using the ``extension`` mapper() argument, which is a single @@ -276,11 +276,11 @@ class SessionExtension(object): """Base implementation for :class:`.Session` event hooks. - .. note:: + .. deprecated:: 0.7 - :class:`.SessionExtension` is deprecated. Please - refer to :func:`.event.listen` as well as - :class:`.SessionEvents`. + :class:`.SessionExtension` is deprecated and will be removed in a future + release. Please refer to :func:`.event.listen` in conjunction with + the :class:`.SessionEvents` listener interface. Subclasses may be installed into a :class:`.Session` (or :class:`.sessionmaker`) using the ``extension`` keyword @@ -397,11 +397,11 @@ class AttributeExtension(object): """Base implementation for :class:`.AttributeImpl` event hooks, events that fire upon attribute mutations in user code. - .. note:: + .. deprecated:: 0.7 - :class:`.AttributeExtension` is deprecated. Please - refer to :func:`.event.listen` as well as - :class:`.AttributeEvents`. + :class:`.AttributeExtension` is deprecated and will be removed in a + future release. Please refer to :func:`.event.listen` in conjunction + with the :class:`.AttributeEvents` listener interface. :class:`.AttributeExtension` is used to listen for set, remove, and append events on individual mapped attributes. diff --git a/lib/sqlalchemy/orm/deprecated_interfaces.py.rej b/lib/sqlalchemy/orm/deprecated_interfaces.py.rej new file mode 100644 index 0000000000..25442f50f5 --- /dev/null +++ b/lib/sqlalchemy/orm/deprecated_interfaces.py.rej @@ -0,0 +1,37 @@ +--- lib/sqlalchemy/orm/deprecated_interfaces.py ++++ lib/sqlalchemy/orm/deprecated_interfaces.py +@@ -749,12 +749,14 @@ 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, including auto-expiry +- of instances on rollback and commit, maintenance of the "new" and +- "deleted" lists upon rollback, and autoflush of pending changes +- upon :meth:`~.Session.begin`, all of which are interdependent. ++ object accounting on transaction boundaries. ++ ++ .. deprecated:: ++ ++ 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`, +@@ -764,8 +766,12 @@ class Session(_SessionClassMethods): + :param extension: An optional + :class:`~.SessionExtension` instance, or a list + of such instances, which will receive pre- and post- commit and +- flush events, as well as a post-rollback event. **Deprecated.** +- Please see :class:`.SessionEvents`. ++ flush events, as well as a post-rollback event. ++ ++ .. deprecated:: ++ ++ 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 diff --git a/lib/sqlalchemy/orm/descriptor_props.py b/lib/sqlalchemy/orm/descriptor_props.py index 82e60cb6be..549a949216 100644 --- a/lib/sqlalchemy/orm/descriptor_props.py +++ b/lib/sqlalchemy/orm/descriptor_props.py @@ -142,7 +142,14 @@ class CompositeProperty(DescriptorProperty): an :class:`.AttributeExtension` instance, or list of extensions, which will be prepended to the list of attribute listeners for the resulting descriptor placed on the - class. **Deprecated.** Please see :class:`.AttributeEvents`. + class. + + .. deprecated:: 0.7 + + :class:`.AttributeExtension` is deprecated in favor of the + :class:`.AttributeEvents` listener interface. The + :paramref:`.CompositeProperty.extension` parameter will be + removed in a future release. """ super(CompositeProperty, self).__init__() diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py index 251e7dc5e2..9838da4bff 100644 --- a/lib/sqlalchemy/orm/events.py +++ b/lib/sqlalchemy/orm/events.py @@ -2121,7 +2121,7 @@ class AttributeEvents(event.Events): .. versionadded:: 1.0.0 the :meth:`.AttributeEvents.init_collection` and :meth:`.AttributeEvents.dispose_collection` events supersede - the :class:`.collection.linker` hook. + the :class:`.orm.collection.linker` hook. """ diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py index 1a43c2b1b9..46f20b90a2 100644 --- a/lib/sqlalchemy/orm/mapper.py +++ b/lib/sqlalchemy/orm/mapper.py @@ -251,8 +251,14 @@ class Mapper(InspectionAttr): :param extension: A :class:`.MapperExtension` instance or list of :class:`.MapperExtension` instances which will be applied - to all operations by this :class:`.Mapper`. **Deprecated.** - Please see :class:`.MapperEvents`. + 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. @@ -325,8 +331,9 @@ class Mapper(InspectionAttr): ordering. .. deprecated:: 1.1 The :paramref:`.Mapper.order_by` parameter - is deprecated. Use :meth:`.Query.order_by` to determine the - ordering of a result set. + 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. diff --git a/lib/sqlalchemy/orm/properties.py b/lib/sqlalchemy/orm/properties.py index 360edc6e9b..8d7a00f75c 100644 --- a/lib/sqlalchemy/orm/properties.py +++ b/lib/sqlalchemy/orm/properties.py @@ -108,12 +108,16 @@ class ColumnProperty(StrategizedProperty): .. versionadded:: 0.8 :param extension: - an - :class:`.AttributeExtension` - instance, or list of extensions, which will be prepended - to the list of attribute listeners for the resulting - descriptor placed on the class. - **Deprecated.** Please see :class:`.AttributeEvents`. + an :class:`.AttributeExtension` instance, or list of extensions, + 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:`.ColumnProperty.extension` parameter will be + removed in a future release. """ super(ColumnProperty, self).__init__() diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py index f7706f4179..393c431144 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -1420,7 +1420,11 @@ class Query(object): """Return a new :class:`.Query` object with the specified "locking mode", which essentially refers to the ``FOR UPDATE`` clause. - .. deprecated:: 0.9.0 superseded by :meth:`.Query.with_for_update`. + .. 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: @@ -1568,12 +1572,9 @@ class Query(object): the newly resulting ``Query`` All existing ORDER BY settings can be suppressed by - passing ``None`` - this will suppress any ORDER BY configured - on mappers as well. - - Alternatively, passing False will reset ORDER BY and additionally - re-allow default mapper.order_by to take place. Note mapper.order_by - is deprecated. + passing ``None`` - this will suppress any ordering configured + on the :func:`.mapper` object using the deprecated + :paramref:`.mapper.order_by` parameter. """ diff --git a/lib/sqlalchemy/orm/relationships.py b/lib/sqlalchemy/orm/relationships.py index 244e3b4e8c..0d36232965 100644 --- a/lib/sqlalchemy/orm/relationships.py +++ b/lib/sqlalchemy/orm/relationships.py @@ -392,7 +392,12 @@ class RelationshipProperty(StrategizedProperty): which will be prepended to the list of attribute listeners for the resulting descriptor placed on the class. - .. deprecated:: 0.7 Please see :class:`.AttributeEvents`. + .. deprecated:: 0.7 + + :class:`.AttributeExtension` is deprecated in favor of the + :class:`.AttributeEvents` listener interface. The + :paramref:`.RelationshipProperty.extension` parameter will be + removed in a future release. :param foreign_keys: diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index 69c0c397d6..f5975688ce 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -682,10 +682,12 @@ class Session(_SessionClassMethods): :param _enable_transaction_accounting: Defaults to ``True``. A legacy-only flag which when ``False`` disables *all* 0.5-style - object accounting on transaction boundaries, including auto-expiry - of instances on rollback and commit, maintenance of the "new" and - "deleted" lists upon rollback, and autoflush of pending changes - upon :meth:`~.Session.begin`, all of which are interdependent. + 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`, @@ -695,8 +697,14 @@ class Session(_SessionClassMethods): :param extension: An optional :class:`~.SessionExtension` instance, or a list of such instances, which will receive pre- and post- commit and - flush events, as well as a post-rollback event. **Deprecated.** - Please see :class:`.SessionEvents`. + 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 @@ -723,11 +731,18 @@ class Session(_SessionClassMethods): :param weak_identity_map: Defaults to ``True`` - when set to ``False``, objects placed in the :class:`.Session` will be strongly referenced until explicitly removed or the - :class:`.Session` is closed. **Deprecated** - The strong - reference identity map is legacy. See the - recipe at :ref:`session_referencing_behavior` for - an event-based approach to maintaining strong identity - references. + :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. + """ @@ -1634,8 +1649,12 @@ class Session(_SessionClassMethods): self._new.pop(state) state._detach(self) - @util.deprecated("0.7", "The non-weak-referencing identity map " - "feature is no longer needed.") + @util.deprecated( + "0.7", + "The :meth:`.Session.prune` method is deprecated along with " + ":paramref:`.Session.weak_identity_map`. This method will be " + "removed in a future release.", + ) def prune(self): """Remove unreferenced instances cached in the identity map. diff --git a/lib/sqlalchemy/orm/strategy_options.py b/lib/sqlalchemy/orm/strategy_options.py index 6b784ccfaa..153e3f2b1c 100644 --- a/lib/sqlalchemy/orm/strategy_options.py +++ b/lib/sqlalchemy/orm/strategy_options.py @@ -515,9 +515,11 @@ See :func:`.orm.%(name)s` for usage examples. self._unbound_all_fn = fn fn.__doc__ = """Produce a standalone "all" option for :func:`.orm.%(name)s`. -.. deprecated:: 0.9.0 +.. deprecated:: 0.9 - The "_all()" style is replaced by method chaining, e.g.:: + 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, as in:: session.query(MyClass).options( %(name)s("someattribute").%(name)s("anotherattribute") diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py index 9816600d8b..4f4e258f7a 100644 --- a/lib/sqlalchemy/orm/util.py +++ b/lib/sqlalchemy/orm/util.py @@ -933,8 +933,10 @@ def join( See :meth:`.Query.join` for information on modern usage of ORM level joins. - .. versionchanged:: 0.8.1 - the ``join_to_left`` parameter - is no longer used, and is deprecated. + .. deprecated:: 0.8 + + the ``join_to_left`` parameter is deprecated, and will be removed + in a future release. The parameter has no effect. """ return _ORMJoin(left, right, onclause, isouter, full) diff --git a/lib/sqlalchemy/pool.py b/lib/sqlalchemy/pool.py index 1a5fda4b7e..4a4b11a51b 100644 --- a/lib/sqlalchemy/pool.py +++ b/lib/sqlalchemy/pool.py @@ -200,12 +200,17 @@ class Pool(log.Identified): can be assigned via :func:`.create_engine` before dialect-level listeners are applied. - :param listeners: Deprecated. A list of - :class:`~sqlalchemy.interfaces.PoolListener`-like objects or + :param listeners: A list of :class:`.PoolListener`-like objects or dictionaries of callables that receive events when DB-API connections are created, checked out and checked in to the - pool. This has been superseded by - :func:`~sqlalchemy.event.listen`. + pool. + + .. deprecated:: 0.7 + + :class:`.PoolListener` is deprecated in favor of the + :class:`.PoolEvents` listener interface. The + :paramref:`.Pool.listeners` parameter will be removed in a + future release. :param dialect: a :class:`.Dialect` that will handle the job of calling rollback(), close(), or commit() on DBAPI connections. @@ -250,8 +255,11 @@ class Pool(log.Identified): event.listen(self, target, fn) if listeners: util.warn_deprecated( - "The 'listeners' argument to Pool (and " - "create_engine()) is deprecated. Use event.listen().") + "The 'listeners' argument to Pool and create_engine() is " + "deprecated and will be removed in a future release. " + "Please refer to the PoolEvents class in conjunction " + "with event.listen()" + ) for l in listeners: self.add_listener(l) @@ -300,7 +308,10 @@ class Pool(log.Identified): connection, exc_info=True) @util.deprecated( - 2.7, "Pool.add_listener is deprecated. Use event.listen()") + "0.7", "The :meth:`.Pool.add_listener` method is deprecated and " + "will be removed in a future release. Please use the " + ":class:`.PoolEvents` listener interface." + ) def add_listener(self, listener): """Add a :class:`.PoolListener`-like object to this pool. diff --git a/lib/sqlalchemy/sql/compiler.py b/lib/sqlalchemy/sql/compiler.py index 108f38a39c..eb598a89ad 100644 --- a/lib/sqlalchemy/sql/compiler.py +++ b/lib/sqlalchemy/sql/compiler.py @@ -215,8 +215,13 @@ class Compiled(object): self.execution_options = statement._execution_options self.string = self.process(self.statement, **compile_kwargs) - @util.deprecated("0.7", ":class:`.Compiled` objects now compile " - "within the constructor.") + @util.deprecated( + "0.7", + "The :meth:`.Compiled.compile` method is deprecated and will be " + "removed in a future release. The :class:`.Compiled` object " + "now runs its compilation within the constructor, and this method " + "does nothing." + ) def compile(self): """Produce the internal string representation of this element. """ @@ -2897,20 +2902,48 @@ class IdentifierPreparer(object): or (lc_value != value)) def quote_schema(self, schema, force=None): - """Conditionally quote a schema. + """Conditionally quote a schema name. + + The name is quoted if it is a reserved word, contains quote-necessary + characters, or is an instance of :class:`.quoted_name` which includes + ``quote`` set to ``True``. Subclasses can override this to provide database-dependent quoting behavior for schema names. - the 'force' flag should be considered deprecated. + :param schema: string schema name + :param force: this parameter is no longer used. + + .. deprecated:: 0.9 + + The :paramref:`.IdentifierPreparer.force` parameter is deprecated + and will be removed in a future release. Quoting preference + is now intrinsic to the string being quoted by making use of the + :class:`.quoted_name` class. """ return self.quote(schema, force) def quote(self, ident, force=None): - """Conditionally quote an identifier. + """Conditionally quote an identfier. + + The identifier is quoted if it is a reserved word, contains + quote-necessary characters, or is an instance of + :class:`.quoted_name` which includes ``quote`` set to ``True``. + + Subclasses can override this to provide database-dependent + quoting behavior for identifier names. + + :param ident: string identifier + :param force: this parameter is no longer used. + + .. deprecated:: 0.9 + + The :paramref:`.IdentifierPreparer.force` parameter is deprecated + and will be removed in a future release. Quoting preference + is now intrinsic to the string being quoted by making use of the + :class:`.quoted_name` class. - the 'force' flag should be considered deprecated. """ force = getattr(ident, "quote", None) diff --git a/lib/sqlalchemy/sql/ddl.py b/lib/sqlalchemy/sql/ddl.py index 8660a9fdaf..224e601aac 100644 --- a/lib/sqlalchemy/sql/ddl.py +++ b/lib/sqlalchemy/sql/ddl.py @@ -98,8 +98,13 @@ class DDLElement(Executable, _DDLCompiles): bind.engine.logger.info( "DDL execution skipped, criteria not met.") - @util.deprecated("0.7", "See :class:`.DDLEvents`, as well as " - ":meth:`.DDLElement.execute_if`.") + @util.deprecated( + "0.7", + "The :meth:`.DDLElement.execute_at` method is deprecated and will " + "be removed in a future release. Please use the :class:`.DDLEvents` " + "listener interface in conjunction with the " + ":meth:`.DDLElement.execute_if` method." + ) def execute_at(self, event_name, target): """Link execution of this DDL to the DDL lifecycle of a SchemaItem. @@ -317,8 +322,12 @@ class DDL(DDLElement): SQL bind parameters are not available in DDL statements. :param on: + .. deprecated:: 0.7 - See :meth:`.DDLElement.execute_if`. + + The :paramref:`.DDL.on` parameter is deprecated and will be + removed in a future release. Please refer to + :meth:`.DDLElement.execute_if`. Optional filtering criteria. May be a string, tuple or a callable predicate. If a string, it will be compared to the name of the diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py index 73ac1888d8..fb158879bb 100644 --- a/lib/sqlalchemy/sql/elements.py +++ b/lib/sqlalchemy/sql/elements.py @@ -1316,58 +1316,41 @@ class TextClause(Executable, ClauseElement): engine-specific format. :param autocommit: - Deprecated. Use .execution_options(autocommit=) - to set the autocommit option. + + .. deprecated:: 0.6 + + The :paramref:`.text.autocommit` flag is deprecated and + will be removed in a future release. Please use the + :paramref:`.Connection.execution_options.autocommit` parameter + in conjunction with the :meth:`.Executable.execution_options` + method. :param bind: an optional connection or engine to be used for this text query. :param bindparams: - Deprecated. A list of :func:`.bindparam` instances used to + A list of :func:`.bindparam` instances used to provide information about parameters embedded in the statement. - This argument now invokes the :meth:`.TextClause.bindparams` - method on the construct before returning it. E.g.:: + E.g.:: stmt = text("SELECT * FROM table WHERE id=:id", bindparams=[bindparam('id', value=5, type_=Integer)]) - Is equivalent to:: - - stmt = text("SELECT * FROM table WHERE id=:id").\ - bindparams(bindparam('id', value=5, type_=Integer)) - - .. deprecated:: 0.9.0 the :meth:`.TextClause.bindparams` method - supersedes the ``bindparams`` argument to :func:`.text`. + .. deprecated:: 0.9 the :paramref:`.TextClause.bindparams` parameter + is deprecated and will be removed in a future release. Please + refer to the :meth:`.TextClause.bindparams` method. :param typemap: - Deprecated. A dictionary mapping the names of columns - represented in the columns clause of a ``SELECT`` statement - to type objects, - which will be used to perform post-processing on columns within - the result set. This parameter now invokes the - :meth:`.TextClause.columns` method, which returns a - :class:`.TextAsFrom` construct that gains a ``.c`` collection and - can be embedded in other expressions. E.g.:: + A dictionary mapping the names of columns represented in the columns + clause of a ``SELECT`` statement to type objects, e.g.:: stmt = text("SELECT * FROM table", typemap={'id': Integer, 'name': String}, ) - Is equivalent to:: - - stmt = text("SELECT * FROM table").columns(id=Integer, - name=String) - - Or alternatively:: - - from sqlalchemy.sql import column - stmt = text("SELECT * FROM table").columns( - column('id', Integer), - column('name', String) - ) - - .. deprecated:: 0.9.0 the :meth:`.TextClause.columns` method - supersedes the ``typemap`` argument to :func:`.text`. + .. deprecated:: 0.9 The :paramref:`.TextClause.typemap` argument is + deprecated and will be removed in a future release. Please + refer to the :meth:`.TextClause.columns` method. .. seealso:: @@ -3092,6 +3075,10 @@ class Over(ColumnElement): order_by = None partition_by = None + element = None + """The underlying expression object to which this :class:`.Over` + object refers towards.""" + def __init__( self, element, partition_by=None, order_by=None, range_=None, rows=None): @@ -3231,9 +3218,9 @@ class Over(ColumnElement): """the element referred to by this :class:`.Over` clause. - .. deprecated:: 1.1 the ``func`` element has been renamed to - ``.element``. The two attributes are synonymous though - ``.func`` is read-only. + .. deprecated:: 1.1 the :attr:`.Over.func` member of the :class:`.Over` + class is deprecated and will be removed in a future release. Please + refer to the :attr:`.Over.element` attribute. """ return self.element @@ -3920,6 +3907,7 @@ class quoted_name(util.MemoizedSlots, util.text_type): ): return value self = super(quoted_name, cls).__new__(cls, value) + self.quote = quote return self diff --git a/lib/sqlalchemy/sql/functions.py b/lib/sqlalchemy/sql/functions.py index e63ca1bca6..d08b571347 100644 --- a/lib/sqlalchemy/sql/functions.py +++ b/lib/sqlalchemy/sql/functions.py @@ -621,6 +621,22 @@ class count(GenericFunction): r"""The ANSI COUNT aggregate function. With no arguments, emits COUNT \*. + E.g.:: + + from sqlalchemy import func + from sqlalchemy import select + from sqlalchemy import table, column + + my_table = table('some_table', column('id')) + + stmt = select([func.count()]).select_from(my_table) + + Executing ``stmt`` would emit:: + + SELECT count(*) AS count_1 + FROM some_table + + """ type = sqltypes.Integer diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py index acd21a832d..e47529ee1d 100644 --- a/lib/sqlalchemy/sql/schema.py +++ b/lib/sqlalchemy/sql/schema.py @@ -86,7 +86,12 @@ class SchemaItem(SchemaEventTarget, visitors.Visitable): return util.generic_repr(self, omit_kwarg=['info']) @property - @util.deprecated('0.9', 'Use ``.name.quote``') + @util.deprecated( + "0.9", + "The :attr:`.SchemaItem.quote` attribute is deprecated and will be " + "removed in a future release. Use the :attr:`.quoted_name.quote` " + "attribute on the ``name`` field of the target schema item to retrieve" + "quoted status.") def quote(self): """Return the value of the ``quote`` flag passed to this schema object, for those schema items which @@ -439,7 +444,12 @@ class Table(DialectKWArgs, SchemaItem, TableClause): metadata._remove_table(name, schema) @property - @util.deprecated('0.9', 'Use ``table.schema.quote``') + @util.deprecated( + "0.9", + "The :meth:`.SchemaItem.quote` method is deprecated and will be " + "removed in a future release. Use the :attr:`.quoted_name.quote` " + "attribute on the ``schema`` field of the target schema item to " + "retrieve quoted status.") def quote_schema(self): """Return the value of the ``quote_schema`` flag passed to this :class:`.Table`. @@ -2424,13 +2434,18 @@ class PassiveDefault(DefaultClause): """A DDL-specified DEFAULT column value. .. deprecated:: 0.6 - :class:`.PassiveDefault` is deprecated. - Use :class:`.DefaultClause`. + + The :class:`.PassiveDefault` class is deprecated and will be removed + in a future release. Please use :class:`.DefaultClause`. + """ - @util.deprecated("0.6", - ":class:`.PassiveDefault` is deprecated. " - "Use :class:`.DefaultClause`.", - False) + + @util.deprecated( + "0.6", + ":class:`.PassiveDefault` is deprecated and will be removed in a " + "future release. Use :class:`.DefaultClause`.", + False, + ) def __init__(self, *arg, **kw): DefaultClause.__init__(self, *arg, **kw) @@ -3507,7 +3522,10 @@ class MetaData(SchemaItem): Defaults to False. ``bind`` is required when this option is set. .. deprecated:: 0.8 - Please use the :meth:`.MetaData.reflect` method. + + The :paramref:`.MetaData.reflect` flag is deprecated and will + be removed in a future release. Please use the + :meth:`.MetaData.reflect` method. :param schema: The default schema to use for the :class:`.Table`, diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py index 0c0ed4626d..eaef8c772d 100644 --- a/lib/sqlalchemy/sql/selectable.py +++ b/lib/sqlalchemy/sql/selectable.py @@ -357,31 +357,20 @@ class FromClause(Selectable): _memoized_property = util.group_expirable_memoized_property(["_columns"]) @util.deprecated( - '1.1', - message="``FromClause.count()`` is deprecated. Counting " - "rows requires that the correct column expression and " - "accommodations for joins, DISTINCT, etc. must be made, " - "otherwise results may not be what's expected. " - "Please use an appropriate ``func.count()`` expression " - "directly.") + "1.1", + message="The :meth:`.FromClause.count` method is deprecated, " + "and will be removed in a future release. Please use the " + ":class:`.functions.count` function available from the " + ":attr:`.func` namespace." + ) @util.dependencies("sqlalchemy.sql.functions") def count(self, functions, whereclause=None, **params): """return a SELECT COUNT generated against this :class:`.FromClause`. - The function generates COUNT against the - first column in the primary key of the table, or against - the first column in the table overall. Explicit use of - ``func.count()`` should be preferred:: - - row_count = conn.scalar( - select([func.count('*')]).select_from(table) - ) - - .. seealso:: - :data:`.func` + :class:`.functions.count` """ @@ -948,9 +937,15 @@ class Join(FromClause): between the two selectables. If there are multiple ways to join, or no way to join, an error is raised. - :param ignore_nonexistent_tables: Deprecated - this - flag is no longer used. Only resolution errors regarding - the two given tables are propagated. + :param ignore_nonexistent_tables: + + .. deprecated:: 0.9 + + The :paramref:`_join_condition.ignore_nonexistent_tables` + parameter is deprecated and will be removed in a future + release. Tables outside of the two tables being handled + are no longer considered. + :param a_subset: An optional expression that is a sub-component of ``a``. An attempt will be made to join to just this sub-component @@ -1900,10 +1895,14 @@ class SelectBase(HasCTE, Executable, FromClause): return self.as_scalar().label(name) @_generative - @util.deprecated('0.6', - message="``autocommit()`` is deprecated. Use " - ":meth:`.Executable.execution_options` with the " - "'autocommit' flag.") + @util.deprecated( + "0.6", + message="The :meth:`.SelectBase.autocommit` method is deprecated, " + "and will be removed in a future release. Please use the " + "the :paramref:`.Connection.execution_options.autocommit` " + "parameter in conjunction with the " + ":meth:`.Executable.execution_options` method." + ) def autocommit(self): """return a new selectable with the 'autocommit' flag set to True. @@ -1965,12 +1964,14 @@ class GenerativeSelect(SelectBase): parse_legacy_select(for_update)) if autocommit is not None: - util.warn_deprecated('autocommit on select() is ' - 'deprecated. Use .execution_options(a' - 'utocommit=True)') - self._execution_options = \ - self._execution_options.union( - {'autocommit': autocommit}) + util.warn_deprecated( + "The select.autocommit parameter is deprecated and will be " + "removed in a future release. Please refer to the " + "Select.execution_options.autocommit` parameter." + ) + self._execution_options = self._execution_options.union( + {"autocommit": autocommit} + ) if limit is not None: self._limit_clause = _offset_or_limit_clause(limit) if offset is not None: @@ -2556,12 +2557,15 @@ class Select(HasPrefixes, HasSuffixes, GenerativeSelect): FROM clause specification. :param autocommit: - Deprecated. Use ``.execution_options(autocommit=)`` - to set the autocommit option. - .. seealso:: + .. deprecated:: 0.6 - :meth:`.Executable.execution_options` + The :paramref:`.select.autocommit` parameter is deprecated + and will be removed in a future release. Please refer to + the :paramref:`.Connection.execution_options.autocommit` + parameter in conjunction with the the + :meth:`.Executable.execution_options` method in order to + affect the autocommit behavior for a statement. :param bind=None: an :class:`~.Engine` or :class:`~.Connection` instance @@ -2602,9 +2606,12 @@ class Select(HasPrefixes, HasSuffixes, GenerativeSelect): when ``True``, applies ``FOR UPDATE`` to the end of the resulting statement. - .. deprecated:: 0.9.0 - use - :meth:`.Select.with_for_update` to specify the - structure of the ``FOR UPDATE`` clause. + .. deprecated:: 0.9 + + The :paramref:`.select.for_update` parameter is deprecated and + will be removed in a future release. Please refer to the + :meth:`.Select.with_for_update` to specify the + structure of the ``FOR UPDATE`` clause. ``for_update`` accepts various string values interpreted by specific backends, including: diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py index eef8276f2e..643c98eca0 100644 --- a/lib/sqlalchemy/sql/sqltypes.py +++ b/lib/sqlalchemy/sql/sqltypes.py @@ -695,11 +695,16 @@ class Float(Numeric): .. versionadded:: 0.9.0 - :param \**kwargs: deprecated. Additional arguments here are ignored - by the default :class:`.Float` type. For database specific - floats that support additional arguments, see that dialect's - documentation for details, such as - :class:`sqlalchemy.dialects.mysql.FLOAT`. + :param \**kwargs: + + .. deprecated:: 0.9 + + Additional keyword arguments are ignored by the base + :class:`.Float` type, and keyword arguments will no longer + be accepted in a future release. For database specific floats + that support additional arguments, see that dialect's + documentation for details, such as + :class:`sqlalchemy.dialects.mysql.FLOAT`. """ self.precision = precision @@ -957,7 +962,12 @@ class LargeBinary(_Binary): class Binary(LargeBinary): - """Deprecated. Renamed to LargeBinary.""" + """.. deprecated:: 0.6 + + The :class:`.Binary` class is deprecated and will be removed + in a future relase. Please use :class:`.LargeBinary`. + + """ def __init__(self, *arg, **kw): util.warn_deprecated('The Binary type has been renamed to ' diff --git a/lib/sqlalchemy/testing/suite/test_reflection.py b/lib/sqlalchemy/testing/suite/test_reflection.py index f2e178bd36..872390fe27 100644 --- a/lib/sqlalchemy/testing/suite/test_reflection.py +++ b/lib/sqlalchemy/testing/suite/test_reflection.py @@ -425,9 +425,9 @@ class ComponentReflectionTest(fixtures.TablesTest): insp = Inspector(meta.bind) assert_raises_message( sa_exc.SADeprecationWarning, - "Call to deprecated method get_primary_keys." - " Use get_pk_constraint instead.", - insp.get_primary_keys, users.name + r".*get_primary_keys\(\) method is deprecated", + insp.get_primary_keys, + users.name, ) @testing.provide_metadata diff --git a/test/engine/test_ddlevents.py b/test/engine/test_ddlevents.py index 80dd8084bb..8dfca5c10b 100644 --- a/test/engine/test_ddlevents.py +++ b/test/engine/test_ddlevents.py @@ -360,7 +360,7 @@ class DDLExecutionTest(fixtures.TestBase): assert 'xyzzy' in strings assert 'fnord' in strings - @testing.uses_deprecated(r'See DDLEvents') + @testing.uses_deprecated(r".*use the DDLEvents") def test_table_by_metadata_deprecated(self): metadata, users, engine = self.metadata, self.users, self.engine DDL('mxyzptlk').execute_at('before-create', users) @@ -462,7 +462,7 @@ class DDLExecutionTest(fixtures.TestBase): assert 'xyzzy' in strings assert 'fnord' in strings - @testing.uses_deprecated(r'See DDLEvents') + @testing.uses_deprecated(r".*use the DDLEvents") def test_metadata_deprecated(self): metadata, engine = self.metadata, self.engine @@ -520,7 +520,7 @@ class DDLExecutionTest(fixtures.TestBase): strings = ' '.join(str(x) for x in pg_mock.mock) assert 'my_test_constraint' in strings - @testing.uses_deprecated(r'See DDLEvents') + @testing.uses_deprecated(r".*use the DDLEvents") def test_conditional_constraint_deprecated(self): metadata, users, engine = self.metadata, self.users, self.engine nonpg_mock = engines.mock_engine(dialect_name='sqlite') diff --git a/test/engine/test_pool.py b/test/engine/test_pool.py index 87f549f514..c6965319f9 100644 --- a/test/engine/test_pool.py +++ b/test/engine/test_pool.py @@ -772,7 +772,10 @@ class PoolFirstConnectSyncTest(PoolTestBase): class DeprecatedPoolListenerTest(PoolTestBase): @testing.requires.predictable_gc - @testing.uses_deprecated(r".*Use event.listen") + @testing.uses_deprecated( + r".*Use the PoolEvents", + r".*'listeners' argument .* is deprecated" + ) def test_listeners(self): class InstrumentingListener(object): @@ -960,7 +963,10 @@ class DeprecatedPoolListenerTest(PoolTestBase): c.close() snoop.assert_total(1, 1, 2, 2) - @testing.uses_deprecated(r".*Use event.listen") + @testing.uses_deprecated( + r".*Use the PoolEvents", + r".*'listeners' argument .* is deprecated" + ) def test_listeners_callables(self): def connect(dbapi_con, con_record): counts[0] += 1 diff --git a/test/engine/test_transaction.py b/test/engine/test_transaction.py index d865b47a56..4c2687302c 100644 --- a/test/engine/test_transaction.py +++ b/test/engine/test_transaction.py @@ -746,8 +746,10 @@ class ExplicitAutoCommitTest(fixtures.TestBase): conn1.close() conn2.close() - @testing.uses_deprecated(r'autocommit on select\(\) is deprecated', - r'``autocommit\(\)`` is deprecated') + @testing.uses_deprecated( + r".*select.autocommit parameter is deprecated", + r".*SelectBase.autocommit\(\) .* is deprecated", + ) def test_explicit_compiled_deprecated(self): conn1 = testing.db.connect() conn2 = testing.db.connect() diff --git a/test/orm/test_collection.py b/test/orm/test_collection.py index fde9ce4129..0cd6a27d63 100644 --- a/test/orm/test_collection.py +++ b/test/orm/test_collection.py @@ -13,7 +13,7 @@ from sqlalchemy.orm import create_session, mapper, relationship, \ attributes, instrumentation from sqlalchemy.testing import fixtures from sqlalchemy.testing import assert_raises, assert_raises_message - +from sqlalchemy.testing import uses_deprecated class Canary(sa.orm.interfaces.AttributeExtension): def __init__(self): @@ -2286,6 +2286,7 @@ class InstrumentationTest(fixtures.ORMTest): eq_(Sub._sa_iterator(Sub(), 5), "base_iterate") eq_(Sub._sa_converter(Sub(), 5), "sub_convert") + @uses_deprecated(r".*Please refer to the .*init_collection") def test_link_event(self): canary = []