.. autoclass:: sqlalchemy.sql.elements.quoted_name
+ .. attribute:: quote
+
+ whether the string should be unconditionally quoted
+
.. autoclass:: UnaryExpression
:members:
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.
"""
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.
"""
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
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`.
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
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
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"
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 ""
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,
: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.
"""
"""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.
"""
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::
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
".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.
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.
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):
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
"""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
"""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.
--- /dev/null
+--- 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
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__()
.. 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.
"""
: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.
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.
.. 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__()
"""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:
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.
"""
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:
: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`,
: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
: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.
+
"""
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.
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")
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)
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.
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)
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.
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.
"""
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)
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.
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
engine-specific format.
:param autocommit:
- Deprecated. Use .execution_options(autocommit=<True|False>)
- 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::
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):
"""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
):
return value
self = super(quoted_name, cls).__new__(cls, value)
+
self.quote = quote
return self
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
return util.generic_repr(self, omit_kwarg=['info'])
@property
- @util.deprecated('0.9', 'Use ``<obj>.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
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`.
"""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)
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`,
_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`
"""
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
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.
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:
FROM clause specification.
:param autocommit:
- Deprecated. Use ``.execution_options(autocommit=<True|False>)``
- 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
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:
.. 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
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 '
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
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)
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
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')
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):
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
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()
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):
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 = []
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
