From: Mike Bayer Date: Tue, 8 Jan 2019 22:46:55 +0000 (-0500) Subject: use ..deprecated directive w/ version in all cases X-Git-Tag: rel_1_3_0b2~37^2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a6094d6682c956ce8a77fbec2a2700f901f3e75e;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git use ..deprecated directive w/ version in all cases These changes should be ported from 1.3 back to 1.0 or possibly 0.9 to the extent they are relevant in each version. In 1.3 we hope to turn all deprecation documentation into warnings. Change-Id: I205186cde161af9389af513a425c62ce90dd54d8 --- 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/dialects/mssql/base.py b/lib/sqlalchemy/dialects/mssql/base.py index ac427b5fd2..340e12fdd3 100644 --- a/lib/sqlalchemy/dialects/mssql/base.py +++ b/lib/sqlalchemy/dialects/mssql/base.py @@ -64,8 +64,13 @@ is set to ``False`` on any integer primary key column:: .. versionchanged:: 1.3 Added ``mssql_identity_start`` and ``mssql_identity_increment`` parameters to :class:`.Column`. These replace the use of the :class:`.Sequence` object in order to specify these values. + +.. deprecated:: 1.3 + The use of :class:`.Sequence` to specify IDENTITY characteristics is - deprecated and will emit a warning. + deprecated and will be removed in a future release. Please use + the ``mssql_identity_start`` and ``mssql_identity_increment`` parameters + documented at :ref:`mssql_identity`. .. note:: diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py index f738b5cafc..562a7deeb9 100644 --- a/lib/sqlalchemy/engine/interfaces.py +++ b/lib/sqlalchemy/engine/interfaces.py @@ -254,11 +254,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. """ @@ -1134,9 +1134,11 @@ class Connectable(object): @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`", + "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. @@ -1146,10 +1148,11 @@ class Connectable(object): @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`", - ) + "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 c822ff8203..f2acd996df 100644 --- a/lib/sqlalchemy/engine/reflection.py +++ b/lib/sqlalchemy/engine/reflection.py @@ -179,10 +179,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 @@ -381,8 +384,9 @@ class Inspector(object): @deprecated( "0.7", - "Call to deprecated method get_primary_keys." - " Use get_pk_constraint instead.", + "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 4064b3e21d..6a7cab0579 100644 --- a/lib/sqlalchemy/event/api.py +++ b/lib/sqlalchemy/event/api.py @@ -34,6 +34,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 @@ -95,6 +98,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 c30b922fd3..a5564e6d41 100644 --- a/lib/sqlalchemy/event/legacy.py +++ b/lib/sqlalchemy/event/legacy.py @@ -113,7 +113,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" @@ -132,17 +133,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 "", @@ -168,6 +170,7 @@ def _augment_fn_docs(dispatch_collection, parent_dispatch_cls, 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, 1) diff --git a/lib/sqlalchemy/events.py b/lib/sqlalchemy/events.py index 01e7b454b5..bfeb290a08 100644 --- a/lib/sqlalchemy/events.py +++ b/lib/sqlalchemy/events.py @@ -799,8 +799,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 bde854d24c..c241aafdb9 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. """ @@ -20,10 +24,11 @@ from . import 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:: @@ -156,10 +161,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 d9f50e1532..eedb89ecd8 100644 --- a/lib/sqlalchemy/orm/__init__.py +++ b/lib/sqlalchemy/orm/__init__.py @@ -193,8 +193,8 @@ comparable_property = public_factory( @_sa_util.deprecated( "0.7", - message=":func:`.compile_mappers` " - "is renamed to :func:`.configure_mappers`", + 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 diff --git a/lib/sqlalchemy/orm/collections.py b/lib/sqlalchemy/orm/collections.py index 2454f9fae1..76d5713aa3 100644 --- a/lib/sqlalchemy/orm/collections.py +++ b/lib/sqlalchemy/orm/collections.py @@ -428,6 +428,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. @@ -437,19 +444,27 @@ 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 - @util.deprecated("1.3", "Use the bulk_replace event handler") + @util.deprecated( + "1.3", + "The :meth:`.collection.converter` method 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." + ) def converter(fn): """Tag the method as the collection converter. diff --git a/lib/sqlalchemy/orm/deprecated_interfaces.py b/lib/sqlalchemy/orm/deprecated_interfaces.py index 0b99ce85d0..619bfaba10 100644 --- a/lib/sqlalchemy/orm/deprecated_interfaces.py +++ b/lib/sqlalchemy/orm/deprecated_interfaces.py @@ -14,11 +14,11 @@ from .. import util 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 @@ -318,11 +318,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 @@ -439,11 +439,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/descriptor_props.py b/lib/sqlalchemy/orm/descriptor_props.py index 0891a2a9d5..8a217e4cd3 100644 --- a/lib/sqlalchemy/orm/descriptor_props.py +++ b/lib/sqlalchemy/orm/descriptor_props.py @@ -145,7 +145,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 7c4cfc3bab..3ad5dfa7f7 100644 --- a/lib/sqlalchemy/orm/events.py +++ b/lib/sqlalchemy/orm/events.py @@ -2070,8 +2070,6 @@ class AttributeEvents(event.Events): else: return value - - .. versionadded:: 1.2 :param target: the object instance receiving the event. @@ -2279,7 +2277,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 c0a53694a2..975ffb6ab4 100644 --- a/lib/sqlalchemy/orm/mapper.py +++ b/lib/sqlalchemy/orm/mapper.py @@ -270,8 +270,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. @@ -344,8 +350,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 3ea68a913e..700e865665 100644 --- a/lib/sqlalchemy/orm/properties.py +++ b/lib/sqlalchemy/orm/properties.py @@ -122,12 +122,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 a4dddcd239..775a38635b 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -1595,7 +1595,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: @@ -1756,12 +1760,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 27a8c4ca98..b16a72996c 100644 --- a/lib/sqlalchemy/orm/relationships.py +++ b/lib/sqlalchemy/orm/relationships.py @@ -411,7 +411,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 d226edf817..a275e44aa7 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -751,10 +751,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`, @@ -764,8 +766,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 @@ -792,11 +800,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. + """ @@ -1757,8 +1772,9 @@ class Session(_SessionClassMethods): @util.deprecated( "0.7", - "The non-weak-referencing identity map " - "feature is no longer needed.", + "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 2d07169918..3aaf700138 100644 --- a/lib/sqlalchemy/orm/strategy_options.py +++ b/lib/sqlalchemy/orm/strategy_options.py @@ -821,9 +821,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 4a1e18c1a3..1f30fafec9 100644 --- a/lib/sqlalchemy/orm/util.py +++ b/lib/sqlalchemy/orm/util.py @@ -1085,8 +1085,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/base.py b/lib/sqlalchemy/pool/base.py index 8df0b89c6f..da660c40a6 100644 --- a/lib/sqlalchemy/pool/base.py +++ b/lib/sqlalchemy/pool/base.py @@ -170,12 +170,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. @@ -231,8 +236,10 @@ 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) @@ -283,7 +290,9 @@ class Pool(log.Identified): ) @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 c752da0136..f221fb00a0 100644 --- a/lib/sqlalchemy/sql/compiler.py +++ b/lib/sqlalchemy/sql/compiler.py @@ -312,7 +312,10 @@ class Compiled(object): @util.deprecated( "0.7", - ":class:`.Compiled` objects now compile " "within the constructor.", + "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. @@ -3437,20 +3440,48 @@ class IdentifierPreparer(object): ) 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 f247fa7823..47a0a09570 100644 --- a/lib/sqlalchemy/sql/ddl.py +++ b/lib/sqlalchemy/sql/ddl.py @@ -103,8 +103,10 @@ class DDLElement(Executable, _DDLCompiles): @util.deprecated( "0.7", - "See :class:`.DDLEvents`, as well as " - ":meth:`.DDLElement.execute_if`.", + "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. @@ -328,8 +330,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 858695719c..efe11494f8 100644 --- a/lib/sqlalchemy/sql/elements.py +++ b/lib/sqlalchemy/sql/elements.py @@ -1395,58 +1395,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:: @@ -3240,6 +3223,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 ): @@ -3386,9 +3373,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 @@ -4140,6 +4127,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 e191cff155..9aea031f96 100644 --- a/lib/sqlalchemy/sql/functions.py +++ b/lib/sqlalchemy/sql/functions.py @@ -756,6 +756,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 804c8bdb84..5c1bfe4504 100644 --- a/lib/sqlalchemy/sql/schema.py +++ b/lib/sqlalchemy/sql/schema.py @@ -113,7 +113,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 @@ -471,7 +476,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`. @@ -2587,14 +2597,16 @@ 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`.", + ":class:`.PassiveDefault` is deprecated and will be removed in a " + "future release. Use :class:`.DefaultClause`.", False, ) def __init__(self, *arg, **kw): @@ -3736,7 +3748,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 beba1d2429..847f8852f4 100644 --- a/lib/sqlalchemy/sql/selectable.py +++ b/lib/sqlalchemy/sql/selectable.py @@ -388,31 +388,19 @@ class FromClause(Selectable): @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.", + 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` """ @@ -1007,9 +995,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 @@ -2030,9 +2024,11 @@ class SelectBase(HasCTE, Executable, FromClause): @_generative @util.deprecated( "0.6", - message="``autocommit()`` is deprecated. Use " - ":meth:`.Executable.execution_options` with the " - "'autocommit' flag.", + 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 @@ -2099,9 +2095,9 @@ class GenerativeSelect(SelectBase): if autocommit is not None: util.warn_deprecated( - "autocommit on select() is " - "deprecated. Use .execution_options(a" - "utocommit=True)" + "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} @@ -2719,12 +2715,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 @@ -2765,9 +2764,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 65527645bc..06b9319fa9 100644 --- a/lib/sqlalchemy/sql/sqltypes.py +++ b/lib/sqlalchemy/sql/sqltypes.py @@ -727,11 +727,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 @@ -975,7 +980,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( diff --git a/lib/sqlalchemy/testing/suite/test_reflection.py b/lib/sqlalchemy/testing/suite/test_reflection.py index 96bd188eed..1c700e3288 100644 --- a/lib/sqlalchemy/testing/suite/test_reflection.py +++ b/lib/sqlalchemy/testing/suite/test_reflection.py @@ -584,8 +584,7 @@ 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.", + r".*get_primary_keys\(\) method is deprecated", insp.get_primary_keys, users.name, ) diff --git a/test/engine/test_ddlevents.py b/test/engine/test_ddlevents.py index 562ed4d68d..2762eaa7ec 100644 --- a/test/engine/test_ddlevents.py +++ b/test/engine/test_ddlevents.py @@ -444,7 +444,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) @@ -548,7 +548,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 @@ -607,7 +607,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 02eb5fc543..75caa233af 100644 --- a/test/engine/test_pool.py +++ b/test/engine/test_pool.py @@ -824,7 +824,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): def __init__(self): @@ -1009,7 +1012,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 1364683299..d8161a29ab 100644 --- a/test/engine/test_transaction.py +++ b/test/engine/test_transaction.py @@ -823,8 +823,8 @@ class ExplicitAutoCommitTest(fixtures.TestBase): conn2.close() @testing.uses_deprecated( - r"autocommit on select\(\) is deprecated", - r"``autocommit\(\)`` is deprecated", + r".*select.autocommit parameter is deprecated", + r".*SelectBase.autocommit\(\) .* is deprecated", ) def test_explicit_compiled_deprecated(self): conn1 = testing.db.connect() diff --git a/test/orm/test_collection.py b/test/orm/test_collection.py index 3ff0129c0f..4e40ac346d 100644 --- a/test/orm/test_collection.py +++ b/test/orm/test_collection.py @@ -1228,7 +1228,7 @@ class CollectionsTest(fixtures.ORMTest): self._test_dict_bulk(MyOrdered) self.assert_(getattr(MyOrdered, "_sa_instrumented") == id(MyOrdered)) - @testing.uses_deprecated(r".*Use the bulk_replace event handler") + @testing.uses_deprecated(r".*Please refer to the .*bulk_replace listener") def test_dict_subclass4(self): # tests #2654 class MyDict(collections.MappedCollection): @@ -2420,7 +2420,7 @@ class InstrumentationTest(fixtures.ORMTest): collections._instrument_class(Touchy) - @testing.uses_deprecated(r".*Use the bulk_replace event handler") + @testing.uses_deprecated(r".*Please refer to the .*bulk_replace listener") def test_name_setup(self): class Base(object): @collection.iterator @@ -2464,6 +2464,7 @@ class InstrumentationTest(fixtures.ORMTest): eq_(Sub._sa_iterator(Sub(), 5), "base_iterate") eq_(Sub._sa_converter(Sub(), 5), "sub_convert") + @testing.uses_deprecated(r".*Please refer to the .*init_collection") def test_link_event(self): canary = []