diff options
Diffstat (limited to 'lib/sqlalchemy/sql')
| -rw-r--r-- | lib/sqlalchemy/sql/compiler.py | 41 | ||||
| -rw-r--r-- | lib/sqlalchemy/sql/ddl.py | 12 | ||||
| -rw-r--r-- | lib/sqlalchemy/sql/elements.py | 64 | ||||
| -rw-r--r-- | lib/sqlalchemy/sql/functions.py | 16 | ||||
| -rw-r--r-- | lib/sqlalchemy/sql/schema.py | 29 | ||||
| -rw-r--r-- | lib/sqlalchemy/sql/selectable.py | 68 | ||||
| -rw-r--r-- | lib/sqlalchemy/sql/sqltypes.py | 22 |
7 files changed, 160 insertions, 92 deletions
diff --git a/lib/sqlalchemy/sql/compiler.py b/lib/sqlalchemy/sql/compiler.py index c752da013..f221fb00a 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 f247fa782..47a0a0957 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 858695719..efe11494f 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=<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:: @@ -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 e191cff15..9aea031f9 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 804c8bdb8..5c1bfe450 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 ``<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 @@ -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 beba1d242..847f8852f 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=<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 @@ -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 65527645b..06b9319fa 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( |