From: Mike Bayer Date: Tue, 14 Apr 2020 17:15:21 +0000 (-0400) Subject: Run search and replace of symbolic module names X-Git-Tag: rel_1_4_0b1~381^2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=cea03be855514d592b6671fa6dbc074a19a795fb;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git Run search and replace of symbolic module names Replaces a wide array of Sphinx-relative doc references with an abbreviated absolute form now supported by zzzeeksphinx. Change-Id: I94bffcc3f37885ffdde6238767224296339698a2 --- diff --git a/doc/build/changelog/changelog_07.rst b/doc/build/changelog/changelog_07.rst index 43ae2fe0d3..ce561fcbbc 100644 --- a/doc/build/changelog/changelog_07.rst +++ b/doc/build/changelog/changelog_07.rst @@ -56,7 +56,7 @@ :versions: 0.8.3, 0.9.0b1 Fixed bug in :class:`.CheckConstraint` DDL where the "quote" flag from a - :class:`.Column` object would not be propagated. + :class:`_schema.Column` object would not be propagated. .. change:: :tags: bug, orm @@ -133,10 +133,10 @@ :tickets: 2604 :versions: 0.8.0b2 - Fixed :meth:`.MetaData.reflect` to correctly use - the given :class:`.Connection`, if given, without + Fixed :meth:`_schema.MetaData.reflect` to correctly use + the given :class:`_engine.Connection`, if given, without opening a second connection from that connection's - :class:`.Engine`. + :class:`_engine.Engine`. .. change:: :tags: mssql, bug @@ -172,8 +172,8 @@ :tags: sql, bug :tickets: 2643 - Fixed bug where :meth:`.Table.tometadata` would fail if a - :class:`.Column` had both a foreign key as well as an + Fixed bug where :meth:`_schema.Table.tometadata` would fail if a + :class:`_schema.Column` had both a foreign key as well as an alternate ".key" name for the column. .. change:: @@ -201,7 +201,7 @@ :tags: orm, bug :tickets: 2640 - :meth:`.Query.merge_result` can now load rows from an outer join + :meth:`_query.Query.merge_result` can now load rows from an outer join where an entity may be ``None`` without throwing an error. .. change:: diff --git a/doc/build/changelog/changelog_08.rst b/doc/build/changelog/changelog_08.rst index 7e0994dfc6..baaa0d4b9c 100644 --- a/doc/build/changelog/changelog_08.rst +++ b/doc/build/changelog/changelog_08.rst @@ -40,8 +40,8 @@ Fixed bug in :class:`.Enum` and other :class:`.SchemaType` subclasses where direct association of the type with a - :class:`.MetaData` would lead to a hang when events - (like create events) were emitted on the :class:`.MetaData`. + :class:`_schema.MetaData` would lead to a hang when events + (like create events) were emitted on the :class:`_schema.MetaData`. .. change:: :tags: bug, sql @@ -155,10 +155,10 @@ :tickets: 3045 :versions: 0.9.5, 1.0.0b1 - Fixed bug where :meth:`.Table.update` and :meth:`.Table.delete` + Fixed bug where :meth:`_schema.Table.update` and :meth:`_schema.Table.delete` would produce an empty WHERE clause when an empty :func:`.and_()` or :func:`.or_()` or other blank expression were applied. This is - now consistent with that of :func:`~.sql.expression.select`. + now consistent with that of :func:`_expression.select`. .. change:: :tags: bug, postgresql @@ -205,8 +205,8 @@ :versions: 0.9.4 Fixed regression from 0.8.3 as a result of :ticket:`2818` - where :meth:`.Query.exists` wouldn't work on a query that only - had a :meth:`.Query.select_from` entry but no other entities. + where :meth:`_query.Query.exists` wouldn't work on a query that only + had a :meth:`_query.Query.select_from` entry but no other entities. .. change:: :tags: bug, general @@ -235,8 +235,8 @@ :versions: 0.9.4 Improved an error message which would occur if a query() were made - against a non-selectable, such as a :func:`.literal_column`, and then - an attempt was made to use :meth:`.Query.join` such that the "left" + against a non-selectable, such as a :func:`_expression.literal_column`, and then + an attempt was made to use :meth:`_query.Query.join` such that the "left" side would be determined as ``None`` and then fail. This condition is now detected explicitly. @@ -310,7 +310,7 @@ Added support for the ``PARTITION BY`` and ``PARTITIONS`` MySQL table keywords, specified as ``mysql_partition_by='value'`` and - ``mysql_partitions='value'`` to :class:`.Table`. Pull request + ``mysql_partitions='value'`` to :class:`_schema.Table`. Pull request courtesy Marcus McCurdy. .. change:: @@ -318,7 +318,7 @@ :versions: 0.9.3 :tickets: 2944 - Fixed bug where calling :meth:`.Insert.values` with an empty list + Fixed bug where calling :meth:`_expression.Insert.values` with an empty list or tuple would raise an IndexError. It now produces an empty insert construct as would be the case with an empty dictionary. @@ -359,14 +359,14 @@ Fixed bug where :meth:`.ColumnOperators.in_()` would go into an endless loop if erroneously passed a column expression whose comparator included the ``__getitem__()`` method, such as a column that uses the - :class:`.postgresql.ARRAY` type. + :class:`_postgresql.ARRAY` type. .. change:: :tags: bug, orm :tickets: 2951 :versions: 0.9.3 - Fixed bug where :meth:`.Query.get` would fail to consistently + Fixed bug where :meth:`_query.Query.get` would fail to consistently raise the :class:`.InvalidRequestError` that invokes when called on a query with existing criterion, when the given identity is already present in the identity map. @@ -458,11 +458,11 @@ :versions: 0.9.0 :tickets: 2895 - Fixed bug with :meth:`.Insert.from_select` method where the order + Fixed bug with :meth:`_expression.Insert.from_select` method where the order of the given names would not be taken into account when generating the INSERT statement, thus producing a mismatch versus the column names in the given SELECT statement. Also noted that - :meth:`.Insert.from_select` implies that Python-side insert defaults + :meth:`_expression.Insert.from_select` implies that Python-side insert defaults cannot be used, since the statement has no VALUES clause. .. change:: @@ -509,7 +509,7 @@ :versions: 0.9.0 :tickets: 2888 - Error message when a string arg sent to :func:`.relationship` which + Error message when a string arg sent to :func:`_orm.relationship` which doesn't resolve to a class or mapper has been corrected to work the same way as when a non-string arg is received, which indicates the name of the relationship which had the configurational error. @@ -574,7 +574,7 @@ :versions: 0.9.0b1 Added support for "unique constraint" reflection, via the - :meth:`.Inspector.get_unique_constraints` method. + :meth:`_reflection.Inspector.get_unique_constraints` method. Thanks for Roman Podolyaka for the patch. .. change:: @@ -592,7 +592,7 @@ Fixed bug where SQL statement would be improperly ASCII-encoded when a pre-DBAPI :class:`.StatementError` were raised within - :meth:`.Connection.execute`, causing encoding errors for + :meth:`_engine.Connection.execute`, causing encoding errors for non-ASCII statements. The stringification now remains within Python unicode thus avoiding encoding errors. @@ -680,7 +680,7 @@ :versions: 0.9.0b1 The change in :ticket:`2721`, which is that the ``deferrable`` keyword - of :class:`.ForeignKeyConstraint` is silently ignored on the MySQL + of :class:`_schema.ForeignKeyConstraint` is silently ignored on the MySQL backend, will be reverted as of 0.9; this keyword will now render again, raising errors on MySQL as it is not understood - the same behavior will also apply to the ``initially`` keyword. In 0.8, the keywords will remain @@ -689,7 +689,7 @@ this keyword is not only silently ignored by MySQL but also breaks the ON UPDATE/ON DELETE options. - To use a :class:`.ForeignKeyConstraint` + To use a :class:`_schema.ForeignKeyConstraint` that does not render or renders differently on MySQL, use a custom compilation option. An example of this usage has been added to the documentation, see :ref:`mysql_foreign_keys`. @@ -700,7 +700,7 @@ :versions: 0.9.0b1 The ``.unique`` flag on :class:`.Index` could be produced as ``None`` - if it was generated from a :class:`.Column` that didn't specify ``unique`` + if it was generated from a :class:`_schema.Column` that didn't specify ``unique`` (where it defaults to ``None``). The flag will now always be ``True`` or ``False``. @@ -709,7 +709,7 @@ :tickets: 2836 :versions: 0.9.0b1 - Added new option to :func:`.relationship` ``distinct_target_key``. + Added new option to :func:`_orm.relationship` ``distinct_target_key``. This enables the subquery eager loader strategy to apply a DISTINCT to the innermost SELECT subquery, to assist in the case where duplicate rows are generated by the innermost query which corresponds @@ -760,7 +760,7 @@ :tickets: 2815 :versions: 0.9.0b1 - A :func:`~.sql.expression.select` that is made to refer to itself in its FROM clause, + A :func:`_expression.select` that is made to refer to itself in its FROM clause, typically via in-place mutation, will raise an informative error message rather than causing a recursion overflow. @@ -770,8 +770,8 @@ :versions: 0.9.0b1 Fixed bug where using an annotation such as :func:`.remote` or - :func:`.foreign` on a :class:`.Column` before association with a parent - :class:`.Table` could produce issues related to the parent table not + :func:`.foreign` on a :class:`_schema.Column` before association with a parent + :class:`_schema.Table` could produce issues related to the parent table not rendering within joins, due to the inherent copy operation performed by an annotation. @@ -779,7 +779,7 @@ :tags: bug, sql :tickets: 2831 - Non-working "schema" argument on :class:`.ForeignKey` is deprecated; + Non-working "schema" argument on :class:`_schema.ForeignKey` is deprecated; raises a warning. Removed in 0.9. .. change:: @@ -796,7 +796,7 @@ :tickets: 2821 :versions: 0.9.0b1 - ``repr()`` for the :class:`.URL` of an :class:`.Engine` + ``repr()`` for the :class:`.URL` of an :class:`_engine.Engine` will now conceal the password using asterisks. Courtesy Gunnlaugur Þór Briem. @@ -805,7 +805,7 @@ :tickets: 2818 :versions: 0.9.0b1 - Fixed bug where :meth:`.Query.exists` failed to work correctly + Fixed bug where :meth:`_query.Query.exists` failed to work correctly without any WHERE criterion. Courtesy Vladimir Magamedov. .. change:: @@ -814,14 +814,14 @@ :versions: 0.9.0b1 Fixed bug where using the ``column_reflect`` event to change the ``.key`` - of the incoming :class:`.Column` would prevent primary key constraints, + of the incoming :class:`_schema.Column` would prevent primary key constraints, indexes, and foreign key constraints from being correctly reflected. .. change:: :tags: feature :versions: 0.9.0b1 - Added a new flag ``system=True`` to :class:`.Column`, which marks + Added a new flag ``system=True`` to :class:`_schema.Column`, which marks the column as a "system" column which is automatically made present by the database (such as PostgreSQL ``oid`` or ``xmin``). The column will be omitted from the ``CREATE TABLE`` statement but will @@ -942,7 +942,7 @@ :tickets: 2776 :versions: 0.9.0b1 - Dialect.initialize() is not called a second time if an :class:`.Engine` + Dialect.initialize() is not called a second time if an :class:`_engine.Engine` is recreated, due to a disconnect error. This fixes a particular issue in the Oracle 8 dialect, but in general the dialect.initialize() phase should only be once per dialect. @@ -951,15 +951,15 @@ :tags: feature, sql :tickets: 722 - Added new method to the :func:`~.sql.expression.insert` construct - :meth:`.Insert.from_select`. Given a list of columns and + Added new method to the :func:`_expression.insert` construct + :meth:`_expression.Insert.from_select`. Given a list of columns and a selectable, renders ``INSERT INTO (table) (columns) SELECT ..``. .. change:: :tags: feature, sql :versions: 0.9.0b1 - The :func:`.update`, :func:`~.sql.expression.insert`, and :func:`.delete` constructs + The :func:`_expression.update`, :func:`_expression.insert`, and :func:`_expression.delete` constructs will now interpret ORM entities as target tables to be operated upon, e.g.:: @@ -1019,7 +1019,7 @@ ORM descriptors such as hybrid properties can now be referenced by name in a string argument used with ``order_by``, - ``primaryjoin``, or similar in :func:`.relationship`, + ``primaryjoin``, or similar in :func:`_orm.relationship`, in addition to column-bound attributes. .. change:: @@ -1101,17 +1101,17 @@ :versions: 0.9.0b1 Multiple fixes to the correlation behavior of - :class:`.Select` constructs, first introduced in 0.8.0: + :class:`_expression.Select` constructs, first introduced in 0.8.0: * To satisfy the use case where FROM entries should be correlated outwards to a SELECT that encloses another, which then encloses this one, correlation now works across multiple levels when explicit correlation is - established via :meth:`.Select.correlate`, provided + established via :meth:`_expression.Select.correlate`, provided that the target select is somewhere along the chain contained by a WHERE/ORDER BY/columns clause, not just nested FROM clauses. This makes - :meth:`.Select.correlate` act more compatibly to + :meth:`_expression.Select.correlate` act more compatibly to that of 0.7 again while still maintaining the new "smart" correlation. @@ -1122,7 +1122,7 @@ across nested FROMs in this case, maintaining compatibility with 0.8.0/0.8.1. - * The :meth:`.Select.correlate_except` method was not + * The :meth:`_expression.Select.correlate_except` method was not preventing the given FROM clauses from correlation in all cases, and also would cause FROM clauses to be incorrectly omitted entirely (more like what 0.7 would do), @@ -1193,7 +1193,7 @@ :tags: bug, engine :versions: 0.9.0b1 - Fixed bug where the ``reset_on_return`` argument to various :class:`.Pool` + Fixed bug where the ``reset_on_return`` argument to various :class:`_pool.Pool` implementations would not be propagated when the pool was regenerated. Courtesy Eevee. @@ -1202,7 +1202,7 @@ :tickets: 2754 :versions: 0.9.0b1 - Fixed bug where sending a composite attribute into :meth:`.Query.order_by` + Fixed bug where sending a composite attribute into :meth:`_query.Query.order_by` would produce a parenthesized expression not accepted by some databases. .. change:: @@ -1249,8 +1249,8 @@ :tickets: 2721 :versions: 0.9.0b1 - The ``deferrable`` keyword argument on :class:`.ForeignKey` and - :class:`.ForeignKeyConstraint` will not render the ``DEFERRABLE`` keyword + The ``deferrable`` keyword argument on :class:`_schema.ForeignKey` and + :class:`_schema.ForeignKeyConstraint` will not render the ``DEFERRABLE`` keyword on the MySQL dialect. For a long time we left this in place because a non-deferrable foreign key would act very differently than a deferrable one, but some environments just disable FKs on MySQL, so we'll be less @@ -1280,7 +1280,7 @@ :tickets: 2728 :versions: 0.9.0b1 - Fixed bug whereby using :meth:`.MetaData.reflect` across a remote + Fixed bug whereby using :meth:`_schema.MetaData.reflect` across a remote schema as well as a local schema could produce wrong results in the case where both schemas had a table of the same name. @@ -1304,11 +1304,11 @@ :tags: feature, orm :tickets: 2736 - Added a new method :meth:`.Query.select_entity_from` which + Added a new method :meth:`_query.Query.select_entity_from` which will in 0.9 replace part of the functionality of - :meth:`.Query.select_from`. In 0.8, the two methods perform + :meth:`_query.Query.select_from`. In 0.8, the two methods perform the same function, so that code can be migrated to use the - :meth:`.Query.select_entity_from` method as appropriate. + :meth:`_query.Query.select_entity_from` method as appropriate. See the 0.9 migration guide for details. .. change:: @@ -1316,7 +1316,7 @@ :tickets: 2737 Fixed a regression caused by :ticket:`2682` whereby the - evaluation invoked by :meth:`.Query.update` and :meth:`.Query.delete` + evaluation invoked by :meth:`_query.Query.update` and :meth:`_query.Query.delete` would hit upon unsupported ``True`` and ``False`` symbols which now appear due to the usage of ``IS``. @@ -1334,7 +1334,7 @@ Fixed a small bug in the dogpile example where the generation of SQL cache keys wasn't applying deduping labels to the - statement the same way :class:`.Query` normally does. + statement the same way :class:`_query.Query` normally does. .. change:: :tags: bug, engine, sybase @@ -1683,7 +1683,7 @@ A meaningful :attr:`.QueryableAttribute.info` attribute is added, which proxies down to the ``.info`` attribute on either - the :class:`.schema.Column` object if directly present, or + the :class:`_schema.Column` object if directly present, or the :class:`.MapperProperty` otherwise. The full behavior is documented and ensured by tests to remain stable. @@ -1692,7 +1692,7 @@ :tickets: 2668 The behavior of SELECT correlation has been improved such that - the :meth:`.Select.correlate` and :meth:`.Select.correlate_except` + the :meth:`_expression.Select.correlate` and :meth:`_expression.Select.correlate_except` methods, as well as their ORM analogues, will still retain "auto-correlation" behavior in that the FROM clause is modified only if the output would be legal SQL; that is, the FROM clause @@ -1741,7 +1741,7 @@ .. change:: :tags: feature, orm - Can set/change the "cascade" attribute on a :func:`.relationship` + Can set/change the "cascade" attribute on a :func:`_orm.relationship` construct after it's been constructed already. This is not a pattern for normal use but we like to change the setting for demonstration purposes in tutorials. @@ -1750,7 +1750,7 @@ :tags: bug, schema :tickets: 2664 - :meth:`.MetaData.create_all` and :meth:`.MetaData.drop_all` will + :meth:`_schema.MetaData.create_all` and :meth:`_schema.MetaData.drop_all` will now accommodate an empty list as an instruction to not create/drop any items, rather than ignoring the collection. @@ -1808,9 +1808,9 @@ :tags: bug, orm :tickets: 2661 - Fixed bug whereby :meth:`.Query.yield_per` would set the execution + Fixed bug whereby :meth:`_query.Query.yield_per` would set the execution options incorrectly, thereby breaking subsequent usage of the - :meth:`.Query.execution_options` method. Courtesy Ryan Kelly. + :meth:`_query.Query.execution_options` method. Courtesy Ryan Kelly. .. change:: :tags: bug, orm @@ -1825,8 +1825,8 @@ :tickets: 2660, 1768 Fixed a bug regarding column annotations which in particular - could impact some usages of the new :func:`.orm.remote` and - :func:`.orm.local` annotation functions, where annotations + could impact some usages of the new :func:`_orm.remote` and + :func:`_orm.local` annotation functions, where annotations could be lost when the column were used in a subsequent expression. @@ -1854,9 +1854,9 @@ Added a new argument to :class:`.Enum` and its base :class:`.SchemaType` ``inherit_schema``. When set to ``True``, the type will set its ``schema`` attribute of that of the - :class:`.Table` to which it is associated. This also occurs - during a :meth:`.Table.tometadata` operation; the :class:`.SchemaType` - is now copied in all cases when :meth:`.Table.tometadata` happens, + :class:`_schema.Table` to which it is associated. This also occurs + during a :meth:`_schema.Table.tometadata` operation; the :class:`.SchemaType` + is now copied in all cases when :meth:`_schema.Table.tometadata` happens, and if ``inherit_schema=True``, the type will take on the new schema name passed to the method. The ``schema`` is important when used with the PostgreSQL backend, as the type results in @@ -1874,8 +1874,8 @@ :tags: sql, bug :tickets: 2643 - Fixed bug where :meth:`.Table.tometadata` would fail if a - :class:`.Column` had both a foreign key as well as an + Fixed bug where :meth:`_schema.Table.tometadata` would fail if a + :class:`_schema.Column` had both a foreign key as well as an alternate ".key" name for the column. Also in 0.7.10. .. change:: @@ -1896,7 +1896,7 @@ de-associated from any of its orphan-enabled parents. Previously, the pending object would be expunged only if de-associated from all of its orphan-enabled parents. The new flag ``legacy_is_orphan`` - is added to :func:`.orm.mapper` which re-establishes the + is added to :func:`_orm.mapper` which re-establishes the legacy behavior. See the change note and example case at :ref:`legacy_is_orphan_addition` @@ -2001,7 +2001,7 @@ :tags: orm, bug :tickets: 2640 - :meth:`.Query.merge_result` can now load rows from an outer join + :meth:`_query.Query.merge_result` can now load rows from an outer join where an entity may be ``None`` without throwing an error. Also in 0.7.10. @@ -2018,7 +2018,7 @@ :tags: postgresql, bug Fixed bug in :class:`~sqlalchemy.dialects.postgresql.array()` construct whereby using it - inside of an :func:`.expression.insert` construct would produce an + inside of an :func:`_expression.insert` construct would produce an error regarding a parameter issue in the ``self_group()`` method. .. change:: @@ -2029,7 +2029,7 @@ This fulfills the common request of being able to inspect all :class:`.QueryableAttribute` descriptors in addition to extension types such as :class:`.hybrid_property` and - :class:`.AssociationProxy`. See :attr:`.Mapper.all_orm_descriptors`. + :class:`.AssociationProxy`. See :attr:`_orm.Mapper.all_orm_descriptors`. .. change:: :tags: mysql, feature @@ -2047,7 +2047,7 @@ :tags: orm, bug :tickets: 2637 - Fixes to the "dynamic" loader on :func:`.relationship`, includes + Fixes to the "dynamic" loader on :func:`_orm.relationship`, includes that backrefs will work properly even when autoflush is disabled, history events are more accurate in scenarios where multiple add/remove of the same object occurs. @@ -2060,7 +2060,7 @@ :tags: orm, bug :tickets: 2635 - The :meth:`.Query.select_from` method can now be used with a + The :meth:`_query.Query.select_from` method can now be used with a :func:`.aliased` construct without it interfering with the entities being selected. Basically, a statement like this:: @@ -2075,7 +2075,7 @@ JOIN users ON users.name < users_1.name Note that this behavior is in contrast - to the original, older use case for :meth:`.Query.select_from`, which is that + to the original, older use case for :meth:`_query.Query.select_from`, which is that of restating the mapped entity in terms of a different selectable:: session.query(User.name).\ @@ -2089,7 +2089,7 @@ It was the "aliasing" behavior of the latter use case that was getting in the way of the former use case. The method now specifically considers a SQL expression like - :func:`.expression.select` or :func:`.expression.alias` + :func:`_expression.select` or :func:`_expression.alias` separately from a mapped entity like a :func:`.aliased` construct. @@ -2099,7 +2099,7 @@ Fixed a regression caused by :ticket:`2410` whereby a :class:`.CheckConstraint` would apply itself back to the - original table during a :meth:`.Table.tometadata` operation, as + original table during a :meth:`_schema.Table.tometadata` operation, as it would parse the SQL expression for a parent table. The operation now copies the given expression to correspond to the new table. @@ -2137,7 +2137,7 @@ :tags: sql, feature :tickets: 2623 - The :class:`~.sql.expression.Insert` construct now supports multi-valued inserts, + The :class:`_expression.Insert` construct now supports multi-valued inserts, that is, an INSERT that renders like "INSERT INTO table VALUES (...), (...), ...". Supported by PostgreSQL, SQLite, and MySQL. @@ -2245,7 +2245,7 @@ :tags: sql, bug Fixed a gotcha where inadvertently calling list() on a - :class:`.ColumnElement` would go into an endless loop, if + :class:`_expression.ColumnElement` would go into an endless loop, if :meth:`.ColumnOperators.__getitem__` were implemented. A new NotImplementedError is emitted via ``__iter__()``. @@ -2274,11 +2274,11 @@ .. change:: :tags: engine, feature - The :meth:`.Connection.connect` and :meth:`.Connection.contextual_connect` - methods now return a "branched" version so that the :meth:`.Connection.close` + The :meth:`_engine.Connection.connect` and :meth:`_engine.Connection.contextual_connect` + methods now return a "branched" version so that the :meth:`_engine.Connection.close` method can be called on the returned connection without affecting the - original. Allows symmetry when using :class:`.Engine` and - :class:`.Connection` objects as context managers:: + original. Allows symmetry when using :class:`_engine.Engine` and + :class:`_engine.Connection` objects as context managers:: with conn.connect() as c: # leaves the Connection open c.execute("...") @@ -2290,7 +2290,7 @@ :tags: engine The "reflect=True" argument to :class:`~sqlalchemy.schema.MetaData` is deprecated. - Please use the :meth:`.MetaData.reflect` method. + Please use the :meth:`_schema.MetaData.reflect` method. .. change:: :tags: sql, bug @@ -2344,7 +2344,7 @@ .. change:: :tags: pool, feature - The :class:`.Pool` will now log all connection.close() + The :class:`_pool.Pool` will now log all connection.close() operations equally, including closes which occur for invalidated connections, detached connections, and connections beyond the pool capacity. @@ -2353,7 +2353,7 @@ :tags: pool, feature :tickets: 2611 - The :class:`.Pool` now consults the :class:`.Dialect` for + The :class:`_pool.Pool` now consults the :class:`.Dialect` for functionality regarding how the connection should be "auto rolled back", as well as closed. This grants more control of transaction scope to the dialect, so that we @@ -2363,7 +2363,7 @@ .. change:: :tags: pool, feature - Added new :meth:`.PoolEvents.reset` hook to capture + Added new :meth:`_events.PoolEvents.reset` hook to capture the event before a connection is auto-rolled back, upon return to the pool. Together with :meth:`.ConnectionEvents.rollback` this allows all rollback @@ -2387,9 +2387,9 @@ .. change:: :tags: sql, feature - Added a new method :meth:`.Engine.execution_options` - to :class:`.Engine`. This method works similarly to - :meth:`.Connection.execution_options` in that it creates + Added a new method :meth:`_engine.Engine.execution_options` + to :class:`_engine.Engine`. This method works similarly to + :meth:`_engine.Connection.execution_options` in that it creates a copy of the parent object which will refer to the new set of options. The method can be used to build sharding schemes where each engine shares the same @@ -2399,14 +2399,14 @@ .. seealso:: - :meth:`.Engine.execution_options` + :meth:`_engine.Engine.execution_options` .. change:: :tags: sql, orm, bug :tickets: 2595 - The auto-correlation feature of :func:`~.sql.expression.select`, and - by proxy that of :class:`.Query`, will not + The auto-correlation feature of :func:`_expression.select`, and + by proxy that of :class:`_query.Query`, will not take effect for a SELECT statement that is being rendered directly in the FROM list of the enclosing SELECT. Correlation in SQL only applies to column @@ -2417,7 +2417,7 @@ :tags: sqlite :changeset: c3addcc9ffad - Added :class:`.types.NCHAR`, :class:`.types.NVARCHAR` + Added :class:`_types.NCHAR`, :class:`_types.NVARCHAR` to the SQLite dialect's list of recognized type names for reflection. SQLite returns the name given to a type as the name returned. diff --git a/doc/build/changelog/changelog_09.rst b/doc/build/changelog/changelog_09.rst index 451c1a6c9e..e4a6ad77fd 100644 --- a/doc/build/changelog/changelog_09.rst +++ b/doc/build/changelog/changelog_09.rst @@ -60,7 +60,7 @@ :versions: 1.0.5 Added official support for a CTE used by the SELECT present - inside of :meth:`.Insert.from_select`. This behavior worked + inside of :meth:`_expression.Insert.from_select`. This behavior worked accidentally up until 0.9.9, when it no longer worked due to unrelated changes as part of :ticket:`3248`. Note that this is the rendering of the WITH clause after the INSERT, before the @@ -92,7 +92,7 @@ :versions: 1.0.1 Added the string value ``"none"`` to those accepted by the - :paramref:`.Pool.reset_on_return` parameter as a synonym for ``None``, + :paramref:`_pool.Pool.reset_on_return` parameter as a synonym for ``None``, so that string values can be used for all settings, allowing utilities like :func:`.engine_from_config` to be usable without issue. @@ -102,10 +102,10 @@ :tickets: 3362 :versions: 1.0.0 - Fixed issue where a :class:`.MetaData` object that used a naming + Fixed issue where a :class:`_schema.MetaData` object that used a naming convention would not properly work with pickle. The attribute was skipped leading to inconsistencies and failures if the unpickled - :class:`.MetaData` object were used to base additional tables + :class:`_schema.MetaData` object were used to base additional tables from. .. change:: @@ -116,18 +116,18 @@ Fixed a long-standing bug where the :class:`.Enum` type as used with the psycopg2 dialect in conjunction with non-ascii values and ``native_enum=False`` would fail to decode return results properly. - This stemmed from when the PG :class:`.postgresql.ENUM` type used + This stemmed from when the PG :class:`_postgresql.ENUM` type used to be a standalone type without a "non native" option. .. change:: :tags: bug, orm :tickets: 3349 - :class:`.Query` doesn't support joins, subselects, or special - FROM clauses when using the :meth:`.Query.update` or - :meth:`.Query.delete` methods; instead of silently ignoring these - fields if methods like :meth:`.Query.join` or - :meth:`.Query.select_from` has been called, a warning is emitted. + :class:`_query.Query` doesn't support joins, subselects, or special + FROM clauses when using the :meth:`_query.Query.update` or + :meth:`_query.Query.delete` methods; instead of silently ignoring these + fields if methods like :meth:`_query.Query.join` or + :meth:`_query.Query.select_from` has been called, a warning is emitted. As of 1.0.0b5 this will raise an error. .. change:: @@ -176,7 +176,7 @@ :versions: 1.0.0b1 Added a new entry ``"entity"`` to the dictionaries returned by - :attr:`.Query.column_descriptions`. This refers to the primary ORM + :attr:`_query.Query.column_descriptions`. This refers to the primary ORM mapped class or aliased class that is referred to by the expression. Compared to the existing entry for ``"type"``, it will always be a mapped entity, even if extracted from a column expression, or @@ -248,7 +248,7 @@ :tags: bug, orm :versions: 1.0.0b1 - Fixed bug where TypeError raised when :meth:`.Query.join` called + Fixed bug where TypeError raised when :meth:`_query.Query.join` called with unknown kw arguments would raise its own TypeError due to broken formatting. Pull request courtesy Malthe Borch. @@ -257,11 +257,11 @@ :tickets: 3302 :versions: 1.0.0b1 - Fixed bug in :class:`.Connection` and pool where the - :meth:`.Connection.invalidate` method, or an invalidation due + Fixed bug in :class:`_engine.Connection` and pool where the + :meth:`_engine.Connection.invalidate` method, or an invalidation due to a database disconnect, would fail if the ``isolation_level`` parameter had been used with - :meth:`.Connection.execution_options`; the "finalizer" that resets + :meth:`_engine.Connection.execution_options`; the "finalizer" that resets the isolation level would be called on the no longer opened connection. .. change:: @@ -270,7 +270,7 @@ :versions: 1.0.0b1 Added new parameter :paramref:`.Session.connection.execution_options` - which may be used to set up execution options on a :class:`.Connection` + which may be used to set up execution options on a :class:`_engine.Connection` when it is first checked out, before the transaction has begun. This is used to set up options such as isolation level on the connection before the transaction starts. @@ -287,7 +287,7 @@ :versions: 1.0.0b1 A warning is emitted if the ``isolation_level`` parameter is used - with :meth:`.Connection.execution_options` when a :class:`.Transaction` + with :meth:`_engine.Connection.execution_options` when a :class:`.Transaction` is in play; DBAPIs and/or SQLAlchemy dialects such as psycopg2, MySQLdb may implicitly rollback or commit the transaction, or not change the setting til next transaction, so this is never safe. @@ -345,13 +345,13 @@ :tickets: 3298, 1765 Fixed bug in 0.9's foreign key setup system, such that - the logic used to link a :class:`.ForeignKey` to its parent could fail + the logic used to link a :class:`_schema.ForeignKey` to its parent could fail when the foreign key used "link_to_name=True" in conjunction with - a target :class:`.Table` that would not receive its parent column until + a target :class:`_schema.Table` that would not receive its parent column until later, such as within a reflection + "useexisting" scenario, if the target column in fact had a key value different from its name, as would occur in reflection if column reflect events were used to - alter the .key of reflected :class:`.Column` objects so that the + alter the .key of reflected :class:`_schema.Column` objects so that the link_to_name becomes significant. Also repaired support for column type via FK transmission in a similar way when target columns had a different key and were referenced using link_to_name. @@ -361,8 +361,8 @@ :versions: 1.0.0b1 Added new user-space accessors for viewing transaction isolation - levels; :meth:`.Connection.get_isolation_level`, - :attr:`.Connection.default_isolation_level`. + levels; :meth:`_engine.Connection.get_isolation_level`, + :attr:`_engine.Connection.default_isolation_level`. .. change:: :tags: bug, postgresql @@ -371,7 +371,7 @@ Fixed bug where PostgreSQL dialect would fail to render an expression in an :class:`.Index` that did not correspond directly - to a table-bound column; typically when a :func:`.text` construct + to a table-bound column; typically when a :func:`_expression.text` construct was one of the expressions within the index; or could misinterpret the list of expressions if one or more of them were such an expression. @@ -381,7 +381,7 @@ :tickets: 3287 The "wildcard" loader options, in particular the one set up by - the :func:`.orm.load_only` option to cover all attributes not + the :func:`_orm.load_only` option to cover all attributes not explicitly mentioned, now takes into account the superclasses of a given entity, if that entity is mapped with inheritance mapping, so that attribute names within the superclasses are also omitted @@ -404,7 +404,7 @@ :tickets: 3285 Fixed bug where if an exception were thrown at the start of a - :class:`.Query` before it fetched results, particularly when + :class:`_query.Query` before it fetched results, particularly when row processors can't be formed, the cursor would stay open with results pending and not actually be closed. This is typically only an issue on an interpreter like PyPy where the cursor isn't @@ -445,7 +445,7 @@ Added new method :meth:`.Session.invalidate`, functions similarly to :meth:`.Session.close`, except also calls - :meth:`.Connection.invalidate` + :meth:`_engine.Connection.invalidate` on all connections, guaranteeing that they will not be returned to the connection pool. This is useful in situations e.g. dealing with gevent timeouts when it is not safe to use the connection further, @@ -504,7 +504,7 @@ Fixed bug regarding expression mutations which could express itself as a "Could not locate column" error when using - :class:`.Query` to select from multiple, anonymous column + :class:`_query.Query` to select from multiple, anonymous column entities when querying against SQLite, as a side effect of the "join rewriting" feature used by the SQLite dialect. @@ -525,8 +525,8 @@ :tickets: 3232 :versions: 1.0.0b1 - Fixed bug where the ON clause for :meth:`.Query.join`, - and :meth:`.Query.outerjoin` to a single-inheritance subclass + Fixed bug where the ON clause for :meth:`_query.Query.join`, + and :meth:`_query.Query.outerjoin` to a single-inheritance subclass using ``of_type()`` would not render the "single table criteria" in the ON clause if the ``from_joinpoint=True`` flag were set. @@ -589,17 +589,17 @@ :versions: 1.0.0b1 :tickets: 3200 - The execution options passed to an :class:`.Engine` either via + The execution options passed to an :class:`_engine.Engine` either via :paramref:`.create_engine.execution_options` or - :meth:`.Engine.update_execution_options` are not passed to the - special :class:`.Connection` used to initialize the dialect + :meth:`_engine.Engine.update_execution_options` are not passed to the + special :class:`_engine.Connection` used to initialize the dialect within the "first connect" event; dialects will usually perform their own queries in this phase, and none of the current available options should be applied here. In particular, the "autocommit" option was causing an attempt to autocommit within this initial connect which would fail with an AttributeError due to the non-standard state of the - :class:`.Connection`. + :class:`_engine.Connection`. .. change:: :tags: bug, sqlite @@ -768,7 +768,7 @@ * The value :func:`.null` can now be specified, which will always result in a NULL value resulting in the statement. - * A new parameter :paramref:`.JSON.none_as_null` is added, which + * A new parameter :paramref:`_types.JSON.none_as_null` is added, which when True indicates that the Python ``None`` value should be persisted as SQL NULL, rather than JSON-encoded ``'null'``. @@ -809,7 +809,7 @@ :versions: 1.0.0b1 :tickets: 3141 - Fixed bug in :class:`.postgresql.array` object where comparison + Fixed bug in :class:`_postgresql.array` object where comparison to a plain Python list would fail to use the correct array constructor. Pull request courtesy Andrew. @@ -903,9 +903,9 @@ :versions: 1.0.0b1 Fixed a regression from 0.9.0 due to :ticket:`2736` where the - :meth:`.Query.select_from` method no longer set up the "from - entity" of the :class:`.Query` object correctly, so that - subsequent :meth:`.Query.filter_by` or :meth:`.Query.join` + :meth:`_query.Query.select_from` method no longer set up the "from + entity" of the :class:`_query.Query` object correctly, so that + subsequent :meth:`_query.Query.filter_by` or :meth:`_query.Query.join` calls would fail to check the appropriate "from" entity when searching for attributes by string name. @@ -923,7 +923,7 @@ :tickets: 3069 :versions: 1.0.0b1 - Fixed bug where multi-valued :class:`~.sql.expression.Insert` construct would fail + Fixed bug where multi-valued :class:`_expression.Insert` construct would fail to check subsequent values entries beyond the first one given for literal SQL expressions. @@ -945,7 +945,7 @@ The :meth:`.TypeEngine.with_variant` method will now accept a type class as an argument which is internally converted to an instance, using the same convention long established by other - constructs such as :class:`.Column`. + constructs such as :class:`_schema.Column`. .. change:: :tags: bug, orm @@ -978,7 +978,7 @@ :tags: feature, postgresql :versions: 1.0.0b1 - Added support for PostgreSQL JSONB via :class:`.JSONB`. Pull request + Added support for PostgreSQL JSONB via :class:`_postgresql.JSONB`. Pull request courtesy Damian Dimmich. .. change:: @@ -1078,11 +1078,11 @@ :tickets: 3023 :versions: 1.0.0b1 - The :paramref:`.Column.nullable` flag is implicitly set to ``False`` - when that :class:`.Column` is referred to in an explicit + The :paramref:`_schema.Column.nullable` flag is implicitly set to ``False`` + when that :class:`_schema.Column` is referred to in an explicit :class:`.PrimaryKeyConstraint` for that table. This behavior now - matches that of when the :class:`.Column` itself has the - :paramref:`.Column.primary_key` flag set to ``True``, which is + matches that of when the :class:`_schema.Column` itself has the + :paramref:`_schema.Column.primary_key` flag set to ``True``, which is intended to be an exactly equivalent case. .. change:: @@ -1090,7 +1090,7 @@ :tickets: 3002 :versions: 1.0.0b1 - Added a new type :class:`.postgresql.OID` to the PostgreSQL dialect. + Added a new type :class:`_postgresql.OID` to the PostgreSQL dialect. While "oid" is generally a private type within PG that is not exposed in modern versions, there are some PG use cases such as large object support where these types might be exposed, as well as within some @@ -1101,7 +1101,7 @@ :tickets: 3080 :versions: 1.0.0b1 - Modified the behavior of :func:`.orm.load_only` such that primary key + Modified the behavior of :func:`_orm.load_only` such that primary key columns are always added to the list of columns to be "undeferred"; otherwise, the ORM can't load the row's identity. Apparently, one can defer the mapped primary keys and the ORM will fail, that @@ -1213,8 +1213,8 @@ :tickets: 2785 :versions: 1.0.0b1 - Added a new flag :paramref:`.ARRAY.zero_indexes` to the PostgreSQL - :class:`.ARRAY` type. When set to ``True``, a value of one will be + Added a new flag :paramref:`_types.ARRAY.zero_indexes` to the PostgreSQL + :class:`_types.ARRAY` type. When set to ``True``, a value of one will be added to all array index values before passing to the database, allowing better interoperability between Python style zero-based indexes and PostgreSQL one-based indexes. Pull request courtesy Alexey Terentev. @@ -1262,10 +1262,10 @@ :versions: 1.0.0b1 Liberalized the contract for :class:`.Index` a bit in that you can - specify a :func:`.text` expression as the target; the index no longer + specify a :func:`_expression.text` expression as the target; the index no longer needs to have a table-bound column present if the index is to be manually added to the table, either via inline declaration or via - :meth:`.Table.append_constraint`. + :meth:`_schema.Table.append_constraint`. .. change:: :tags: bug, firebird @@ -1342,8 +1342,8 @@ Fixes to the newly enhanced boolean coercion in :ticket:`2804` where the new rules for "where" and "having" woudn't take effect for the - "whereclause" and "having" kw arguments of the :func:`~.sql.expression.select` construct, - which is also what :class:`.Query` uses so wasn't working in the + "whereclause" and "having" kw arguments of the :func:`_expression.select` construct, + which is also what :class:`_query.Query` uses so wasn't working in the ORM either. .. change:: @@ -1410,7 +1410,7 @@ Improved the check for "how to join from A to B" such that when a table has multiple, composite foreign keys targeting a parent table, - the :paramref:`.relationship.foreign_keys` argument will be properly + the :paramref:`_orm.relationship.foreign_keys` argument will be properly interpreted in order to resolve the ambiguity; previously this condition would raise that there were multiple FK paths when in fact the foreign_keys argument should be establishing which one is expected. @@ -1439,12 +1439,12 @@ :tags: feature, engine :tickets: 2978 - An event listener can now be associated with a :class:`.Engine`, - after one or more :class:`.Connection` objects have been created + An event listener can now be associated with a :class:`_engine.Engine`, + after one or more :class:`_engine.Connection` objects have been created (such as by an orm :class:`.Session` or via explicit connect) and the listener will pick up events from those connections. Previously, performance concerns pushed the event transfer from - :class:`.Engine` to :class:`.Connection` at init-time only, but + :class:`_engine.Engine` to :class:`_engine.Connection` at init-time only, but we've inlined a bunch of conditional checks to make this possible without any additional function calls. @@ -1459,7 +1459,7 @@ :tags: bug, engine :tickets: 2985 - A major improvement made to the mechanics by which the :class:`.Engine` + A major improvement made to the mechanics by which the :class:`_engine.Engine` recycles the connection pool when a "disconnect" condition is detected; instead of discarding the pool and explicitly closing out connections, the pool is retained and a "generational" timestamp is updated to @@ -1474,7 +1474,7 @@ :tags: bug, oracle :tickets: 2987 - Added new datatype :class:`.oracle.DATE`, which is a subclass of + Added new datatype :class:`_oracle.DATE`, which is a subclass of :class:`.DateTime`. As Oracle has no "datetime" type per se, it instead has only ``DATE``, it is appropriate here that the ``DATE`` type as present in the Oracle dialect be an instance of @@ -1489,16 +1489,16 @@ :tags: bug, sql :tickets: 2988 - Fixed an 0.9 regression where a :class:`.Table` that failed to + Fixed an 0.9 regression where a :class:`_schema.Table` that failed to reflect correctly wouldn't be removed from the parent - :class:`.MetaData`, even though in an invalid state. Pullreq + :class:`_schema.MetaData`, even though in an invalid state. Pullreq courtesy Roman Podoliaka. .. change:: :tags: bug, engine The :meth:`.ConnectionEvents.after_cursor_execute` event is now - emitted for the "_cursor_execute()" method of :class:`.Connection`; + emitted for the "_cursor_execute()" method of :class:`_engine.Connection`; this is the "quick" executor that is used for things like when a sequence is executed ahead of an INSERT statement, as well as for dialect startup checks like unicode returns, charset, etc. @@ -1523,7 +1523,7 @@ .. change:: :tags: feature, sql - Added a new feature :func:`.schema.conv`, the purpose of which is to + Added a new feature :func:`_schema.conv`, the purpose of which is to mark a constraint name as already having had a naming convention applied. This token will be used by Alembic migrations as of Alembic 0.6.4 in order to render constraints in migration scripts with names marked @@ -1532,16 +1532,16 @@ .. change:: :tags: bug, sql - :paramref:`.MetaData.naming_convention` feature will now also + :paramref:`_schema.MetaData.naming_convention` feature will now also apply to :class:`.CheckConstraint` objects that are associated - directly with a :class:`.Column` instead of just on the - :class:`.Table`. + directly with a :class:`_schema.Column` instead of just on the + :class:`_schema.Table`. .. change:: :tags: bug, sql :tickets: 2991 - Fixed bug in new :paramref:`.MetaData.naming_convention` feature + Fixed bug in new :paramref:`_schema.MetaData.naming_convention` feature where the name of a check constraint making use of the `"%(constraint_name)s"` token would get doubled up for the constraint generated by a boolean or enum type, and overall @@ -1554,7 +1554,7 @@ A warning is emitted if the :meth:`.MapperEvents.before_configured` or :meth:`.MapperEvents.after_configured` events are applied to a specific mapper or mapped class, as the events are only invoked - for the :class:`.Mapper` target at the general level. + for the :class:`_orm.Mapper` target at the general level. .. change:: :tags: feature, orm @@ -1628,7 +1628,7 @@ :tags: feature, orm :tickets: 2976 - Added a new option to :paramref:`.relationship.innerjoin` which is + Added a new option to :paramref:`_orm.relationship.innerjoin` which is to specify the string ``"nested"``. When set to ``"nested"`` as opposed to ``True``, the "chaining" of joins will parenthesize the inner join on the right side of an existing outer join, instead of chaining as a string @@ -1657,7 +1657,7 @@ :tickets: 2974 Adjusted the logic which applies names to the .c collection when - a no-name :class:`.BindParameter` is received, e.g. via :func:`.sql.literal` + a no-name :class:`.BindParameter` is received, e.g. via :func:`_expression.literal` or similar; the "key" of the bind param is used as the key within .c. rather than the rendered name. Since these binds have "anonymous" names in any case, this allows individual bound parameters to @@ -1667,7 +1667,7 @@ :tags: bug, sql :tickets: 2974 - Some changes to how the :attr:`.FromClause.c` collection behaves + Some changes to how the :attr:`_expression.FromClause.c` collection behaves when presented with duplicate columns. The behavior of emitting a warning and replacing the old column with the same name still remains to some degree; the replacement in particular is to maintain @@ -1678,7 +1678,7 @@ list of columns rather than the unique set of key names. This helps with situations where SELECT statements with same-named columns are used in unions and such, so that the union can match the columns - up positionally and also there's some chance of :meth:`.FromClause.corresponding_column` + up positionally and also there's some chance of :meth:`_expression.FromClause.corresponding_column` still being usable here (it can now return a column that is only in selectable.c._all_columns and not otherwise named). The new collection is underscored as we still need to decide where this @@ -1690,7 +1690,7 @@ .. change:: :tags: bug, sql - Fixed issue in new :meth:`.TextClause.columns` method where the ordering + Fixed issue in new :meth:`_expression.TextClause.columns` method where the ordering of columns given positionally would not be preserved. This could have potential impact in positional situations such as applying the resulting :class:`.TextAsFrom` object to a union. @@ -1727,16 +1727,16 @@ :tickets: 2973 Fixed bug where events set to listen at the class - level (e.g. on the :class:`.Mapper` or :class:`.ClassManager` + level (e.g. on the :class:`_orm.Mapper` or :class:`.ClassManager` level, as opposed to on an individual mapped class, and also on - :class:`.Connection`) that also made use of internal argument conversion + :class:`_engine.Connection`) that also made use of internal argument conversion (which is most within those categories) would fail to be removable. .. change:: :tags: bug, orm Fixed regression from 0.8 where using an option like - :func:`.orm.lazyload` with the "wildcard" expression, e.g. ``"*"``, + :func:`_orm.lazyload` with the "wildcard" expression, e.g. ``"*"``, would raise an assertion error in the case where the query didn't contain any actual entities. This assertion is meant for other cases and was catching this one inadvertently. @@ -1781,7 +1781,7 @@ The SQLite dialect will now skip unsupported arguments when reflecting types; such as if it encounters a string like ``INTEGER(5)``, the - :class:`.INTEGER` type will be instantiated without the "5" being included, + :class:`_types.INTEGER` type will be instantiated without the "5" being included, based on detecting a ``TypeError`` on the first attempt. .. change:: @@ -1801,14 +1801,14 @@ :tags: postgresql, feature Added the :attr:`.TypeEngine.python_type` convenience accessor onto the - :class:`.postgresql.ARRAY` type. Pull request courtesy Alexey Terentev. + :class:`_postgresql.ARRAY` type. Pull request courtesy Alexey Terentev. .. change:: :tags: examples, feature Added optional "changed" column to the versioned rows example, as well - as support for when the versioned :class:`.Table` has an explicit - :paramref:`~.Table.schema` argument. Pull request + as support for when the versioned :class:`_schema.Table` has an explicit + :paramref:`_schema.Table.schema` argument. Pull request courtesy jplaverdure. .. change:: @@ -1921,7 +1921,7 @@ :tags: feature, sql Added :paramref:`.MetaData.reflect.**dialect_kwargs` - to support dialect-level reflection options for all :class:`.Table` + to support dialect-level reflection options for all :class:`_schema.Table` objects reflected. .. change:: @@ -1929,13 +1929,13 @@ :tickets: 2922 Added a new dialect-level argument ``postgresql_ignore_search_path``; - this argument is accepted by both the :class:`.Table` constructor - as well as by the :meth:`.MetaData.reflect` method. When in use + this argument is accepted by both the :class:`_schema.Table` constructor + as well as by the :meth:`_schema.MetaData.reflect` method. When in use against PostgreSQL, a foreign-key referenced table which specifies a remote schema name will retain that schema name even if the name is present in the ``search_path``; the default behavior since 0.7.3 has been that schemas present in ``search_path`` would not be copied - to reflected :class:`.ForeignKey` objects. The documentation has been + to reflected :class:`_schema.ForeignKey` objects. The documentation has been updated to describe in detail the behavior of the ``pg_get_constraintdef()`` function and how the ``postgresql_ignore_search_path`` feature essentially determines if we will honor the schema qualification reported by @@ -1949,12 +1949,12 @@ :tags: bug, sql :tickets: 2913 - The behavior of :meth:`.Table.tometadata` has been adjusted such that - the schema target of a :class:`.ForeignKey` will not be changed unless + The behavior of :meth:`_schema.Table.tometadata` has been adjusted such that + the schema target of a :class:`_schema.ForeignKey` will not be changed unless that schema matches that of the parent table. That is, if a table "schema_a.user" has a foreign key to "schema_b.order.id", the "schema_b" target will be maintained whether or not the - "schema" argument is passed to :meth:`.Table.tometadata`. However + "schema" argument is passed to :meth:`_schema.Table.tometadata`. However if a table "schema_a.user" refers to "schema_a.order.id", the presence of "schema_a" will be updated on both the parent and referred tables. This is a behavioral change hence isn't likely to be backported to @@ -1964,7 +1964,7 @@ Additionally, a new parameter has been added :paramref:`.Table.tometadata.referred_schema_fn`. This refers to a callable function which will be used to determine the new referred - schema for any :class:`.ForeignKeyConstraint` encountered in the + schema for any :class:`_schema.ForeignKeyConstraint` encountered in the tometadata operation. This callable can be used to revert to the previous behavior or to customize how referred schemas are treated on a per-constraint basis. @@ -1973,14 +1973,14 @@ :tags: bug, orm :tickets: 2932 - Fixed bug in new :class:`.TextAsFrom` construct where :class:`.Column`- + Fixed bug in new :class:`.TextAsFrom` construct where :class:`_schema.Column`- oriented row lookups were not matching up to the ad-hoc :class:`.ColumnClause` objects that :class:`.TextAsFrom` generates, thereby making it not - usable as a target in :meth:`.Query.from_statement`. Also fixed - :meth:`.Query.from_statement` mechanics to not mistake a :class:`.TextAsFrom` - for a :class:`.Select` construct. This bug is also an 0.9 regression - as the :meth:`.Text.columns` method is called to accommodate the - :paramref:`.text.typemap` argument. + usable as a target in :meth:`_query.Query.from_statement`. Also fixed + :meth:`_query.Query.from_statement` mechanics to not mistake a :class:`.TextAsFrom` + for a :class:`_expression.Select` construct. This bug is also an 0.9 regression + as the :meth:`_expression.TextClause.columns` method is called to accommodate the + :paramref:`_expression.text.typemap` argument. .. change:: :tags: feature, sql @@ -1991,9 +1991,9 @@ on a recipe in the wiki, the new feature uses schema-events to set up names as various schema objects are associated with each other. The events then expose a configuration system through a new argument - :paramref:`.MetaData.naming_convention`. This system allows production + :paramref:`_schema.MetaData.naming_convention`. This system allows production of both simple and custom naming schemes for constraints and indexes - on a per-:class:`.MetaData` basis. + on a per-:class:`_schema.MetaData` basis. .. seealso:: @@ -2015,7 +2015,7 @@ Added a new parameter :paramref:`.Operators.op.is_comparison`. This flag allows a custom op from :meth:`.Operators.op` to be considered as a "comparison" operator, thus usable for custom - :paramref:`.relationship.primaryjoin` conditions. + :paramref:`_orm.relationship.primaryjoin` conditions. .. seealso:: @@ -2068,9 +2068,9 @@ :tickets: 2918 Fixed an 0.9 regression where the automatic aliasing applied by - :class:`.Query` and in other situations where selects or joins + :class:`_query.Query` and in other situations where selects or joins were aliased (such as joined table inheritance) could fail if a - user-defined :class:`.Column` subclass were used in the expression. + user-defined :class:`_schema.Column` subclass were used in the expression. In this case, the subclass would fail to propagate ORM-specific "annotations" along needed by the adaptation. The "expression annotations" system has been corrected to account for this case. @@ -2078,9 +2078,9 @@ .. change:: :tags: feature, orm - Support is improved for supplying a :func:`.join` construct as the - target of :paramref:`.relationship.secondary` for the purposes - of creating very complex :func:`.relationship` join conditions. + Support is improved for supplying a :func:`_expression.join` construct as the + target of :paramref:`_orm.relationship.secondary` for the purposes + of creating very complex :func:`_orm.relationship` join conditions. The change includes adjustments to query joining, joined eager loading to not render a SELECT subquery, changes to lazy loading such that the "secondary" target is properly included in the SELECT, and @@ -2102,7 +2102,7 @@ where a more specific type is adapted to a more generic one - this use case is needed by some third party tools such as ``sqlacodegen``. The specific cases that needed repair within this test suite were that - of :class:`.mysql.ENUM` being downcast into a :class:`.types.Enum`, + of :class:`.mysql.ENUM` being downcast into a :class:`_types.Enum`, and that of SQLite date types being cast into generic date types. The ``adapt()`` method needed to become more specific here to counteract the removal of a "catch all" ``**kwargs`` collection on the base @@ -2124,7 +2124,7 @@ the columns, or if both are present, that the column lists match exactly. If an inconsistent set of columns in the :class:`.PrimaryKeyConstraint` - and within the :class:`.Table` marked as ``primary_key=True`` are + and within the :class:`_schema.Table` marked as ``primary_key=True`` are present, a warning is emitted, and the list of columns is taken only from the :class:`.PrimaryKeyConstraint` alone as was the case in previous releases. @@ -2141,13 +2141,13 @@ The system by which schema constructs and certain SQL constructs accept dialect-specific keyword arguments has been enhanced. This - system includes commonly the :class:`.Table` and :class:`.Index` constructs, + system includes commonly the :class:`_schema.Table` and :class:`.Index` constructs, which accept a wide variety of dialect-specific arguments such as ``mysql_engine`` and ``postgresql_where``, as well as the constructs :class:`.PrimaryKeyConstraint`, :class:`.UniqueConstraint`, - :class:`.Update`, :class:`~.sql.expression.Insert` and :class:`.Delete`, and also - newly added kwarg capability to :class:`.ForeignKeyConstraint` - and :class:`.ForeignKey`. The change is that participating dialects + :class:`_expression.Update`, :class:`_expression.Insert` and :class:`_expression.Delete`, and also + newly added kwarg capability to :class:`_schema.ForeignKeyConstraint` + and :class:`_schema.ForeignKey`. The change is that participating dialects can now specify acceptable argument lists for these constructs, allowing an argument error to be raised if an invalid keyword is specified for a particular dialect. If the dialect portion of the keyword is unrecognized, @@ -2162,7 +2162,7 @@ .. change:: :tags: bug, sql - A :class:`.UniqueConstraint` created inline with a :class:`.Table` + A :class:`.UniqueConstraint` created inline with a :class:`_schema.Table` that has no columns within it will be skipped. Pullreq courtesy Derek Harland. @@ -2183,9 +2183,9 @@ with the same name across tables. This also changes the name used for the bound parameter in the SET clause to "_" for the non-primary table only; as this parameter is typically specified - using the :class:`.Column` object directly this should not have an + using the :class:`_schema.Column` object directly this should not have an impact on applications. The fix takes effect for both - :meth:`.Table.update` as well as :meth:`.Query.update` in the ORM. + :meth:`_schema.Table.update` as well as :meth:`_query.Query.update` in the ORM. .. change:: :tags: bug, oracle @@ -2229,7 +2229,7 @@ :tickets: 2908 Fixed a bug involving the new flattened JOIN structures which - are used with :func:`.joinedload()` (thereby causing a regression + are used with :func:`_orm.joinedload()` (thereby causing a regression in joined eager loading) as well as :func:`.aliased` in conjunction with the ``flat=True`` flag and joined-table inheritance; basically multiple joins across a "parent JOIN sub" entity using different @@ -2269,12 +2269,12 @@ :tags: bug, mysql, pool, engine :tickets: 2907 - :class:`.Connection` now associates a new + :class:`_engine.Connection` now associates a new :class:`.RootTransaction` or :class:`.TwoPhaseTransaction` with its immediate :class:`._ConnectionFairy` as a "reset handler" for the span of that transaction, which takes over the task of calling commit() or rollback() for the "reset on return" behavior - of :class:`.Pool` if the transaction was not otherwise completed. + of :class:`_pool.Pool` if the transaction was not otherwise completed. This resolves the issue that a picky transaction like that of MySQL two-phase will be properly closed out when the connection is closed without an @@ -2293,14 +2293,14 @@ .. change:: :tags: feature, pool, engine - Added a new pool event :meth:`.PoolEvents.invalidate`. Called when + Added a new pool event :meth:`_events.PoolEvents.invalidate`. Called when a DBAPI connection is to be marked as "invalidated" and discarded from the pool. .. change:: :tags: bug, pool - The argument names for the :meth:`.PoolEvents.reset` event have been + The argument names for the :meth:`_events.PoolEvents.reset` event have been renamed to ``dbapi_connection`` and ``connection_record`` in order to maintain consistency with all the other pool events. It is expected that any existing listeners for this relatively new and @@ -2369,8 +2369,8 @@ .. change:: :tags: feature, schema - The :paramref:`.Table.extend_existing` and :paramref:`.Table.autoload_replace` - parameters are now available on the :meth:`.MetaData.reflect` + The :paramref:`_schema.Table.extend_existing` and :paramref:`_schema.Table.autoload_replace` + parameters are now available on the :meth:`_schema.MetaData.reflect` method. .. change:: @@ -2436,9 +2436,9 @@ :tickets: 2828 Declarative does an extra check to detect if the same - :class:`.Column` is mapped multiple times under different properties + :class:`_schema.Column` is mapped multiple times under different properties (which typically should be a :func:`.synonym` instead) or if two - or more :class:`.Column` objects are given the same name, raising + or more :class:`_schema.Column` objects are given the same name, raising a warning if this condition is detected. .. change:: @@ -2468,7 +2468,7 @@ :tickets: 2581 Support for PostgreSQL JSON has been added, using the new - :class:`.JSON` type. Huge thanks to Nathan Rice for + :class:`_types.JSON` type. Huge thanks to Nathan Rice for implementing and testing this. .. change:: @@ -2493,12 +2493,12 @@ :tags: bug, sql :tickets: 2883 - The :class:`.ForeignKey` class more aggressively checks the given + The :class:`_schema.ForeignKey` class more aggressively checks the given column argument. If not a string, it checks that the object is at least a :class:`.ColumnClause`, or an object that resolves to one, and that the ``.table`` attribute, if present, refers to a - :class:`.TableClause` or subclass, and not something like an - :class:`.Alias`. Otherwise, a :class:`.ArgumentError` is raised. + :class:`_expression.TableClause` or subclass, and not something like an + :class:`_expression.Alias`. Otherwise, a :class:`.ArgumentError` is raised. .. change:: @@ -2517,7 +2517,7 @@ :tags: feature, postgresql Added support for PostgreSQL TSVECTOR via the - :class:`.postgresql.TSVECTOR` type. Pull request courtesy + :class:`_postgresql.TSVECTOR` type. Pull request courtesy Noufal Ibrahim. .. change:: @@ -2554,9 +2554,9 @@ The :class:`.DeferredReflection` class has been enhanced to provide automatic reflection support for the "secondary" table referred - to by a :func:`.relationship`. "secondary", when specified - either as a string table name, or as a :class:`.Table` object with - only a name and :class:`.MetaData` object will also be included + to by a :func:`_orm.relationship`. "secondary", when specified + either as a string table name, or as a :class:`_schema.Table` object with + only a name and :class:`_schema.MetaData` object will also be included in the reflection process when :meth:`.DeferredReflection.prepare` is called. @@ -2597,17 +2597,17 @@ Fixed bug where in Py2K a unicode literal would not be accepted as the string name of a class or other argument within - declarative using :func:`.relationship`. + declarative using :func:`_orm.relationship`. .. change:: :tags: feature, sql :tickets: 2877, 2882 - New improvements to the :func:`.text` construct, including + New improvements to the :func:`_expression.text` construct, including more flexible ways to set up bound parameters and return types; - in particular, a :func:`.text` can now be turned into a full + in particular, a :func:`_expression.text` can now be turned into a full FROM-object, embeddable in other statements as an alias or CTE - using the new method :meth:`.TextClause.columns`. The :func:`.text` + using the new method :meth:`_expression.TextClause.columns`. The :func:`_expression.text` construct can also render "inline" bound parameters when the construct is compiled in a "literal bound" context. @@ -2619,12 +2619,12 @@ :tags: feature, sql A new API for specifying the ``FOR UPDATE`` clause of a ``SELECT`` - is added with the new :meth:`.GenerativeSelect.with_for_update` method. + is added with the new :meth:`_expression.GenerativeSelect.with_for_update` method. This method supports a more straightforward system of setting dialect-specific options compared to the ``for_update`` keyword - argument of :func:`~.sql.expression.select`, and also includes support for the + argument of :func:`_expression.select`, and also includes support for the SQL standard ``FOR UPDATE OF`` clause. The ORM also includes - a new corresponding method :meth:`.Query.with_for_update`. + a new corresponding method :meth:`_query.Query.with_for_update`. Pull request courtesy Mario Lassnig. .. seealso:: @@ -2635,8 +2635,8 @@ :tags: feature, orm A new API for specifying the ``FOR UPDATE`` clause of a ``SELECT`` - is added with the new :meth:`.Query.with_for_update` method, - to complement the new :meth:`.GenerativeSelect.with_for_update` method. + is added with the new :meth:`_query.Query.with_for_update` method, + to complement the new :meth:`_expression.GenerativeSelect.with_for_update` method. Pull request courtesy Mario Lassnig. .. seealso:: @@ -2719,7 +2719,7 @@ :tags: bug, orm :tickets: 2833 - The ``viewonly`` flag on :func:`.relationship` will now prevent + The ``viewonly`` flag on :func:`_orm.relationship` will now prevent attribute history from being written on behalf of the target attribute. This has the effect of the object not being written to the Session.dirty list if it is mutated. Previously, the object would @@ -2750,7 +2750,7 @@ :tags: bug, orm Fixed bug where usage of new :class:`.Bundle` object would cause - the :attr:`.Query.column_descriptions` attribute to fail. + the :attr:`_query.Query.column_descriptions` attribute to fail. .. change:: :tags: bug, examples @@ -2836,8 +2836,8 @@ new copy is assigned the actual type of the compared column. Previously, this logic would occur on the given :func:`.bindparam` in place. Additionally, a similar process now occurs for :func:`.bindparam` constructs - passed to :meth:`.ValuesBase.values` for an :class:`~.sql.expression.Insert` or - :class:`.Update` construct, within the compilation phase of the + passed to :meth:`.ValuesBase.values` for an :class:`_expression.Insert` or + :class:`_expression.Update` construct, within the compilation phase of the construct. These are both subtle behavioral changes which may impact some @@ -2853,8 +2853,8 @@ An overhaul of expression handling for special symbols particularly with conjunctions, e.g. - ``None`` :func:`.expression.null` :func:`.expression.true` - :func:`.expression.false`, including consistency in rendering NULL + ``None`` :func:`_expression.null` :func:`_expression.true` + :func:`_expression.false`, including consistency in rendering NULL in conjunctions, "short-circuiting" of :func:`.and_` and :func:`.or_` expressions which contain boolean constants, and rendering of boolean constants and expressions as compared to "1" or "0" for backends @@ -2885,12 +2885,12 @@ :tags: feature, sql :tickets: 2716 - The :meth:`.Table.tometadata` method now produces copies of + The :meth:`_schema.Table.tometadata` method now produces copies of all :attr:`.SchemaItem.info` dictionaries from all :class:`.SchemaItem` objects within the structure including columns, constraints, foreign keys, etc. As these dictionaries are copies, they are independent of the original dictionary. - Previously, only the ``.info`` dictionary of :class:`.Column` was transferred + Previously, only the ``.info`` dictionary of :class:`_schema.Column` was transferred within this operation, and it was only linked in place, not copied. .. change:: @@ -2914,7 +2914,7 @@ .. change:: :tags: feature, sql - The ``default`` argument of :class:`.Column` now accepts a class + The ``default`` argument of :class:`_schema.Column` now accepts a class or object method as an argument, in addition to a standalone function; will properly detect if the "context" argument is accepted or not. @@ -2941,7 +2941,7 @@ :tags: bug, sql :tickets: 2831 - The erroneous kw arg "schema" has been removed from the :class:`.ForeignKey` + The erroneous kw arg "schema" has been removed from the :class:`_schema.ForeignKey` object. this was an accidental commit that did nothing; a warning is raised in 0.8.3 when this kw arg is used. @@ -2949,7 +2949,7 @@ :tags: feature, orm :tickets: 1418 - Added a new load option :func:`.orm.load_only`. This allows a series + Added a new load option :func:`_orm.load_only`. This allows a series of column names to be specified as loading "only" those attributes, deferring the rest. @@ -2958,8 +2958,8 @@ :tickets: 1418 The system of loader options has been entirely rearchitected to build - upon a much more comprehensive base, the :class:`.Load` object. This - base allows any common loader option like :func:`.joinedload`, + upon a much more comprehensive base, the :class:`_orm.Load` object. This + base allows any common loader option like :func:`_orm.joinedload`, :func:`.defer`, etc. to be used in a "chained" style for the purpose of specifying options down a path, such as ``joinedload("foo").subqueryload("bar")``. The new system supersedes the usage of dot-separated path names, @@ -2974,7 +2974,7 @@ :tickets: 2824 The :func:`.composite` construct now maintains the return object - when used in a column-oriented :class:`.Query`, rather than expanding + when used in a column-oriented :class:`_query.Query`, rather than expanding out into individual columns. This makes use of the new :class:`.Bundle` feature internally. This behavior is backwards incompatible; to select from a composite column which will expand out, use @@ -2989,12 +2989,12 @@ :tickets: 2824 A new construct :class:`.Bundle` is added, which allows for specification - of groups of column expressions to a :class:`.Query` construct. + of groups of column expressions to a :class:`_query.Query` construct. The group of columns are returned as a single tuple by default. The behavior of :class:`.Bundle` can be overridden however to provide any sort of result processing to the returned row. The behavior of :class:`.Bundle` is also embedded into composite attributes now - when they are used in a column-oriented :class:`.Query`. + when they are used in a column-oriented :class:`_query.Query`. .. seealso:: @@ -3010,9 +3010,9 @@ instead of relying upon various ``quote=True`` flags being passed around, these flags are converted into rich string objects with quoting information included at the point at which they are passed to common schema constructs - like :class:`.Table`, :class:`.Column`, etc. This solves the issue + like :class:`_schema.Table`, :class:`_schema.Column`, etc. This solves the issue of various methods that don't correctly honor the "quote" flag such - as :meth:`.Engine.has_table` and related methods. The :class:`.quoted_name` + as :meth:`_engine.Engine.has_table` and related methods. The :class:`.quoted_name` object is a string subclass that can also be used explicitly if needed; the object will hold onto the quoting preferences passed and will also bypass the "name normalization" performed by dialects that @@ -3040,7 +3040,7 @@ :tags: feature, orm :tickets: 2793 - The ``eager_defaults`` flag of :class:`.Mapper` will now allow the + The ``eager_defaults`` flag of :class:`_orm.Mapper` will now allow the newly generated default values to be fetched using an inline RETURNING clause, rather than a second SELECT statement, for backends that support RETURNING. @@ -3134,8 +3134,8 @@ :tags: feature, sql :tickets: 722 - Added new method to the :func:`~.sql.expression.insert` construct - :meth:`.Insert.from_select`. Given a list of columns and + Added new method to the :func:`_expression.insert` construct + :meth:`_expression.Insert.from_select`. Given a list of columns and a selectable, renders ``INSERT INTO (table) (columns) SELECT ..``. While this feature is highlighted as part of 0.9 it is also backported to 0.8.3. @@ -3158,19 +3158,19 @@ :tags: bug, sql :tickets: 1765 - The resolution of :class:`.ForeignKey` objects to their - target :class:`.Column` has been reworked to be as + The resolution of :class:`_schema.ForeignKey` objects to their + target :class:`_schema.Column` has been reworked to be as immediate as possible, based on the moment that the - target :class:`.Column` is associated with the same - :class:`.MetaData` as this :class:`.ForeignKey`, rather + target :class:`_schema.Column` is associated with the same + :class:`_schema.MetaData` as this :class:`_schema.ForeignKey`, rather than waiting for the first time a join is constructed, or similar. This along with other improvements allows earlier detection of some foreign key configuration issues. Also included here is a rework of the type-propagation system, so that it should be reliable now to set the type as ``None`` - on any :class:`.Column` that refers to another via - :class:`.ForeignKey` - the type will be copied from the + on any :class:`_schema.Column` that refers to another via + :class:`_schema.ForeignKey` - the type will be copied from the target column as soon as that other column is associated, and now works for composite foreign keys as well. @@ -3247,8 +3247,8 @@ are no longer impacted by this workaround. As part of this change, a new argument ``flat=True`` has been added - to the :func:`.orm.aliased`, :meth:`.Join.alias`, and - :func:`.orm.with_polymorphic` functions, which allows an "alias" of a + to the :func:`_orm.aliased`, :meth:`_expression.Join.alias`, and + :func:`_orm.with_polymorphic` functions, which allows an "alias" of a JOIN to be produced which applies an anonymous alias to each component table within the join, rather than producing a subquery. @@ -3325,13 +3325,13 @@ :tags: bug, orm :tickets: 2736 - The "auto-aliasing" behavior of the :meth:`.Query.select_from` + The "auto-aliasing" behavior of the :meth:`_query.Query.select_from` method has been turned off. The specific behavior is now - available via a new method :meth:`.Query.select_entity_from`. + available via a new method :meth:`_query.Query.select_entity_from`. The auto-aliasing behavior here was never well documented and - is generally not what's desired, as :meth:`.Query.select_from` + is generally not what's desired, as :meth:`_query.Query.select_from` has become more oriented towards controlling how a JOIN is - rendered. :meth:`.Query.select_entity_from` will also be made + rendered. :meth:`_query.Query.select_entity_from` will also be made available in 0.8 so that applications which rely on the auto-aliasing can shift their applications to use this method. diff --git a/doc/build/changelog/changelog_10.rst b/doc/build/changelog/changelog_10.rst index 195f0f498b..fe31200925 100644 --- a/doc/build/changelog/changelog_10.rst +++ b/doc/build/changelog/changelog_10.rst @@ -169,8 +169,8 @@ :tickets: 3778 :versions: 1.1.4 - Fixed bug where the :attr:`.Mapper.attrs`, - :attr:`.Mapper.all_orm_descriptors` and other derived attributes would + Fixed bug where the :attr:`_orm.Mapper.attrs`, + :attr:`_orm.Mapper.all_orm_descriptors` and other derived attributes would fail to refresh when mapper properties or other ORM constructs were added to the mapper/class after these accessors were first called. @@ -214,11 +214,11 @@ :tickets: 3755 :versions: 1.1.0 - Fixed bug in :class:`.Table` where the internal method + Fixed bug in :class:`_schema.Table` where the internal method ``_reset_exported()`` would corrupt the state of the object. This method is intended for selectable objects and is called by the ORM in some cases; an erroneous mapper configuration would could lead the - ORM to call this on a :class:`.Table` object. + ORM to call this on a :class:`_schema.Table` object. .. change:: :tags: bug, ext @@ -280,7 +280,7 @@ :tags: bug, sql :tickets: 3724 - :meth:`.FromClause.count` is pending deprecation for 1.1. This function + :meth:`_expression.FromClause.count` is pending deprecation for 1.1. This function makes use of an arbitrary column in the table and is not reliable; for Core use, ``func.count()`` should be preferred. @@ -288,7 +288,7 @@ :tags: bug, sql :tickets: 3722 - Fixed bug in :class:`.CTE` structure which would cause it to not + Fixed bug in :class:`_expression.CTE` structure which would cause it to not clone properly when a union was used, as is common in a recursive CTE. The improper cloning would cause errors when the CTE is used in various ORM contexts such as that of a :func:`.column_property`. @@ -297,8 +297,8 @@ :tags: bug, sql :tickets: 3721 - Fixed bug whereby :meth:`.Table.tometadata` would make a duplicate - :class:`.UniqueConstraint` for each :class:`.Column` object that + Fixed bug whereby :meth:`_schema.Table.tometadata` would make a duplicate + :class:`.UniqueConstraint` for each :class:`_schema.Column` object that featured the ``unique=True`` parameter. .. change:: @@ -306,13 +306,13 @@ :tickets: 3716 Fixed bug in cross-schema foreign key reflection in conjunction - with the :paramref:`.MetaData.schema` argument, where a referenced + with the :paramref:`_schema.MetaData.schema` argument, where a referenced table that is present in the "default" schema would fail since there - would be no way to indicate a :class:`.Table` that has "blank" for - a schema. The special symbol :attr:`.schema.BLANK_SCHEMA` has been - added as an available value for :paramref:`.Table.schema` and + would be no way to indicate a :class:`_schema.Table` that has "blank" for + a schema. The special symbol :attr:`_schema.BLANK_SCHEMA` has been + added as an available value for :paramref:`_schema.Table.schema` and :paramref:`.Sequence.schema`, indicating that the schema name - should be forced to be ``None`` even if :paramref:`.MetaData.schema` + should be forced to be ``None`` even if :paramref:`_schema.MetaData.schema` is specified. .. change:: @@ -331,8 +331,8 @@ :tags: bug, orm :tickets: 3700 - Fixed bug in "evaluate" strategy of :meth:`.Query.update` and - :meth:`.Query.delete` which would fail to accommodate a bound + Fixed bug in "evaluate" strategy of :meth:`_query.Query.update` and + :meth:`_query.Query.delete` which would fail to accommodate a bound parameter with a "callable" value, as which occurs when filtering by a many-to-one equality expression along a relationship. @@ -366,8 +366,8 @@ :tags: bug, orm :tickets: 3706 - Fixed bug whereby passing a :func:`.text` construct to the - :meth:`.Query.group_by` method would raise an error, instead + Fixed bug whereby passing a :func:`_expression.text` construct to the + :meth:`_query.Query.group_by` method would raise an error, instead of interpreting the object as a SQL fragment. .. change:: @@ -405,7 +405,7 @@ :tickets: 3690 Fixed bug where when using ``case_sensitive=False`` with an - :class:`.Engine`, the result set would fail to correctly accommodate + :class:`_engine.Engine`, the result set would fail to correctly accommodate for duplicate column names in the result set, causing an error when the statement is executed in 1.0, and preventing the "ambiguous column" exception from functioning in 1.1. @@ -424,7 +424,7 @@ :tickets: 3666 Fixed bug where "unconsumed column names" exception would fail to - be raised in the case where :meth:`.Insert.values` were called + be raised in the case where :meth:`_expression.Insert.values` were called with a list of parameter mappings, instead of a single mapping of parameters. Pull request courtesy Athena Yao. @@ -445,7 +445,7 @@ Fixed bug in "to_list" conversion where a single bytes object would be turned into a list of individual characters. This would - impact among other things using the :meth:`.Query.get` method + impact among other things using the :meth:`_query.Query.get` method on a primary key that's a bytes object. .. change:: @@ -489,7 +489,7 @@ :tags: bug, postgresql :tickets: 3644 - Fixed bug in :func:`.expression.text` construct where a double-colon + Fixed bug in :func:`_expression.text` construct where a double-colon expression would not escape properly, e.g. ``some\:\:expr``, as is most commonly required when rendering PostgreSQL-style CAST expressions. @@ -498,8 +498,8 @@ :tickets: 3643 Fixed issue where the "literal_binds" flag was not propagated - for :func:`.expression.insert`, :func:`.expression.update` or - :func:`.expression.delete` constructs when compiled to string + for :func:`_expression.insert`, :func:`_expression.update` or + :func:`_expression.delete` constructs when compiled to string SQL. Pull request courtesy Tim Tate. .. change:: @@ -539,7 +539,7 @@ reraise" function which takes place across the ORM and Core in any place that a transaction is being rolled back in response to an error which occurred trying to commit, including the context managers - provided by :class:`.Session` and :class:`.Connection`, and taking + provided by :class:`.Session` and :class:`_engine.Connection`, and taking place for operations such as a failure on "RELEASE SAVEPOINT". Previously, the fix was only in place for a specific path within the ORM flush/commit process; it now takes place for all transactional @@ -549,10 +549,10 @@ :tags: bug, sql :tickets: 3632 - Fixed bug in :class:`.Table` metadata construct which appeared - around the 0.9 series where adding columns to a :class:`.Table` + Fixed bug in :class:`_schema.Table` metadata construct which appeared + around the 0.9 series where adding columns to a :class:`_schema.Table` that was unpickled would fail to correctly establish the - :class:`.Column` within the 'c' collection, leading to issues in + :class:`_schema.Column` within the 'c' collection, leading to issues in areas such as ORM configuration. This could impact use cases such as ``extend_existing`` and others. @@ -588,7 +588,7 @@ Fixed 1.0 regression where the eager fetch of cursor.rowcount was no longer called for an UPDATE or DELETE statement emitted via plain - text or via the :func:`.text` construct, affecting those drivers + text or via the :func:`_expression.text` construct, affecting those drivers that erase cursor.rowcount once the cursor is closed such as SQL Server ODBC and Firebird drivers. @@ -653,7 +653,7 @@ :tags: bug, sql :tickets: 3609 - Fixed bug in :meth:`.Update.return_defaults` which would cause all + Fixed bug in :meth:`_expression.Update.return_defaults` which would cause all insert-default holding columns not otherwise included in the SET clause (such as primary key cols) to get rendered into the RETURNING even though this is an UPDATE. @@ -662,7 +662,7 @@ :tags: bug, orm :tickets: 3609 - Major fixes to the :paramref:`.Mapper.eager_defaults` flag, this + Major fixes to the :paramref:`_orm.Mapper.eager_defaults` flag, this flag would not be honored correctly in the case that multiple UPDATE statements were to be emitted, either as part of a flush or a bulk update operation. Additionally, RETURNING @@ -672,8 +672,8 @@ :tags: bug, orm :tickets: 3606 - Fixed bug where use of the :meth:`.Query.select_from` method would - cause a subsequent call to the :meth:`.Query.with_parent` method to + Fixed bug where use of the :meth:`_query.Query.select_from` method would + cause a subsequent call to the :meth:`_query.Query.with_parent` method to fail. .. changelog:: @@ -698,13 +698,13 @@ :tags: bug, sql :tickets: 3603 - Fixed issue within the :meth:`.Insert.from_select` construct whereby - the :class:`.Select` construct would have its ``._raw_columns`` - collection mutated in-place when compiling the :class:`~.sql.expression.Insert` - construct, when the target :class:`.Table` has Python-side defaults. - The :class:`.Select` construct would compile standalone with the + Fixed issue within the :meth:`_expression.Insert.from_select` construct whereby + the :class:`_expression.Select` construct would have its ``._raw_columns`` + collection mutated in-place when compiling the :class:`_expression.Insert` + construct, when the target :class:`_schema.Table` has Python-side defaults. + The :class:`_expression.Select` construct would compile standalone with the erroneous column present subsequent to compilation of the - :class:`~.sql.expression.Insert`, and the :class:`~.sql.expression.Insert` statement itself would + :class:`_expression.Insert`, and the :class:`_expression.Insert` statement itself would fail on a second compile attempt due to duplicate bound parameters. .. change:: @@ -758,7 +758,7 @@ Fixed bug where some varieties of SQL expression passed to the - "where" clause of :class:`.postgresql.ExcludeConstraint` would fail + "where" clause of :class:`_postgresql.ExcludeConstraint` would fail to be accepted correctly. Pull request courtesy aisch. .. change:: @@ -767,7 +767,7 @@ Fixed bug where in Py2K a unicode literal would not be accepted as the string name of a class or other argument within declarative using - :func:`.backref` on :func:`.relationship`. Pull request courtesy + :func:`.backref` on :func:`_orm.relationship`. Pull request courtesy Nils Philippsen. .. change:: @@ -804,7 +804,7 @@ Added support for parameter-ordered SET clauses in an UPDATE statement. This feature is available by passing the :paramref:`~.sqlalchemy.sql.expression.update.preserve_parameter_order` - flag either to the core :class:`.Update` construct or alternatively + flag either to the core :class:`_expression.Update` construct or alternatively adding it to the :paramref:`.Query.update.update_args` dictionary at the ORM-level, also passing the parameters themselves as a list of 2-tuples. Thanks to Gorka Eguileor for implementation and tests. @@ -855,7 +855,7 @@ :tags: bug, postgresql :tickets: 3571 - Fixed the ``.python_type`` attribute of :class:`.postgresql.INTERVAL` + Fixed the ``.python_type`` attribute of :class:`_postgresql.INTERVAL` to return ``datetime.timedelta`` in the same way as that of :obj:`.types.Interval.python_type`, rather than raising ``NotImplementedError``. @@ -908,8 +908,8 @@ .. change:: :tags: feature, orm - Added new method :meth:`.Query.one_or_none`; same as - :meth:`.Query.one` but returns None if no row found. Pull request + Added new method :meth:`_query.Query.one_or_none`; same as + :meth:`_query.Query.one` but returns None if no row found. Pull request courtesy esiegerman. .. change:: @@ -1005,8 +1005,8 @@ :tags: feature, sql :tickets: 3459 - Added a :meth:`.ColumnElement.cast` method which performs the same - purpose as the standalone :func:`.expression.cast` function. Pull + Added a :meth:`_expression.ColumnElement.cast` method which performs the same + purpose as the standalone :func:`_expression.cast` function. Pull request courtesy Sebastian Bank. .. change:: @@ -1014,7 +1014,7 @@ :tickets: 3481 Fixed regression where new methods on :class:`.ResultProxy` used - by the ORM :class:`.Query` object (part of the performance + by the ORM :class:`_query.Query` object (part of the performance enhancements of :ticket:`3175`) would not raise the "this result does not return rows" exception in the case where the driver (typically MySQL) fails to generate cursor.description correctly; @@ -1103,7 +1103,7 @@ Fixed 1.0 regression where the "parent entity" of a synonym- mapped attribute on top of an :func:`.aliased` object would resolve to the original mapper, not the :func:`.aliased` - version of it, thereby causing problems for a :class:`.Query` + version of it, thereby causing problems for a :class:`_query.Query` that relies on this attribute (e.g. it's the only representative attribute given in the constructor) to figure out the correct FROM clause for the query. @@ -1131,9 +1131,9 @@ :tags: bug, mssql :tickets: 3464 - Fixed issue when using :class:`.VARBINARY` type in conjunction with + Fixed issue when using :class:`_types.VARBINARY` type in conjunction with an INSERT of NULL + pyodbc; pyodbc requires a special - object be passed in order to persist NULL. As the :class:`.VARBINARY` + object be passed in order to persist NULL. As the :class:`_types.VARBINARY` type is now usually the default for :class:`.LargeBinary` due to :ticket:`3039`, this issue is partially a regression in 1.0. The pymssql driver appears to be unaffected. @@ -1158,7 +1158,7 @@ as the ``postgresql_using`` flag, which will now be set on :class:`.Index` objects that are reflected, as well present in a new "dialect_options" dictionary in the result of - :meth:`.Inspector.get_indexes`. Pull request courtesy Pete Hollobon. + :meth:`_reflection.Inspector.get_indexes`. Pull request courtesy Pete Hollobon. .. seealso:: @@ -1181,7 +1181,7 @@ Repaired the :class:`.ExcludeConstraint` construct to support common features that other objects like :class:`.Index` now do, that the column expression may be specified as an arbitrary SQL - expression such as :obj:`.expression.cast` or :obj:`.expression.text`. + expression such as :obj:`_expression.cast` or :obj:`_expression.text`. .. change:: :tags: feature, postgresql @@ -1190,7 +1190,7 @@ by the psycopg2 dialect when the ``stream_results`` option is used, which sets a limit on the size of the row buffer that may be allocated. This value is also provided based on the integer - value sent to :meth:`.Query.yield_per`. Pull request courtesy + value sent to :meth:`_query.Query.yield_per`. Pull request courtesy mcclurem. .. change:: @@ -1210,7 +1210,7 @@ :class:`.types.TypeEngine.Comparator` objects that made use of the ``__clause_element__()`` method and returned an object that was an ORM-mapped :class:`.InstrumentedAttribute` and not explicitly a - :class:`.ColumnElement` would fail to be correctly handled when passed + :class:`_expression.ColumnElement` would fail to be correctly handled when passed as an expression to :meth:`.Session.query`. The logic in 0.9 happened to succeed on this, so this use case is now supported. @@ -1244,7 +1244,7 @@ :tags: feature, engine Added new engine event :meth:`.ConnectionEvents.engine_disposed`. - Called after the :meth:`.Engine.dispose` method is called. + Called after the :meth:`_engine.Engine.dispose` method is called. .. change:: :tags: bug, postgresql, pypy @@ -1372,7 +1372,7 @@ :tags: bug, orm :tickets: 3420 - The "lightweight named tuple" used when a :class:`.Query` returns + The "lightweight named tuple" used when a :class:`_query.Query` returns rows failed to implement ``__slots__`` correctly such that it still had a ``__dict__``. This is resolved, but in the extremely unlikely case someone was assigning values to the returned tuples, @@ -1425,7 +1425,7 @@ Fixed bug in enhanced constraint-attachment logic introduced in :ticket:`3341` where in the unusual case of a constraint that refers - to a mixture of :class:`.Column` objects and string column names + to a mixture of :class:`_schema.Column` objects and string column names at the same time, the auto-attach-on-column-attach logic will be skipped; for the constraint to be auto-attached in this case, all columns must be assembled on the target table up front. @@ -1442,7 +1442,7 @@ Repaired / added to tests yet more expressions that were reported as failing with the new 'entity' key value added to - :attr:`.Query.column_descriptions`, the logic to discover the "from" + :attr:`_query.Query.column_descriptions`, the logic to discover the "from" clause is again reworked to accommodate columns from aliased classes, as well as to report the correct value for the "aliased" flag in these cases. @@ -1457,8 +1457,8 @@ :tickets: 3405 Fixed regression from 0.9.10 prior to release due to :ticket:`3349` - where the check for query state on :meth:`.Query.update` or - :meth:`.Query.delete` compared the empty tuple to itself using ``is``, + where the check for query state on :meth:`_query.Query.update` or + :meth:`_query.Query.delete` compared the empty tuple to itself using ``is``, which fails on PyPy to produce ``True`` in this case; this would erronously emit a warning in 0.9 and raise an exception in 1.0. @@ -1473,7 +1473,7 @@ to a modern pool invalidation in that connections aren't actively closed, but are recycled only on next checkout; this is essentially a per-connection version of that feature. A new event - :class:`.PoolEvents.soft_invalidate` is added to complement it. + :class:`_events.PoolEvents.soft_invalidate` is added to complement it. Also added new flag :attr:`.ExceptionContext.invalidate_pool_on_disconnect`. @@ -1497,9 +1497,9 @@ :tickets: 3403, 3320 Fixed regression from 0.9.10 prior to release where the new addition - of ``entity`` to the :attr:`.Query.column_descriptions` accessor + of ``entity`` to the :attr:`_query.Query.column_descriptions` accessor would fail if the target entity was produced from a core selectable - such as a :class:`.Table` or :class:`.CTE` object. + such as a :class:`_schema.Table` or :class:`_expression.CTE` object. .. change:: :tags: feature, sql @@ -1547,7 +1547,7 @@ Fixed unexpected use regression due to :ticket:`2992` where textual elements placed - into the :meth:`.Query.order_by` clause in conjunction with joined + into the :meth:`_query.Query.order_by` clause in conjunction with joined eager loading would be added to the columns clause of the inner query in such a way that they were assumed to be table-bound column names, in the case where the joined eager load needs to wrap the query @@ -1566,14 +1566,14 @@ Beyond that, the feature also fails for deprecated cases such as ``order_by("name desc")``, which, while it emits a - warning that :func:`.text` should be used here (note that the issue - does not impact cases where :func:`.text` is used explicitly), + warning that :func:`_expression.text` should be used here (note that the issue + does not impact cases where :func:`_expression.text` is used explicitly), still produces a different query than previously where the "name desc" expression is copied into the columns clause inappropriately. The resolution is such that the "joined eager loading" aspect of the feature will skip over these so-called "label reference" expressions when augmenting the inner columns clause, as though they were - :func:`.text` constructs already. + :func:`_expression.text` constructs already. .. change:: :tags: bug, sql @@ -1618,7 +1618,7 @@ :tickets: 3387 Fixed issue in new :meth:`.QueryEvents.before_compile` event where - changes made to the :class:`.Query` object's collection of entities + changes made to the :class:`_query.Query` object's collection of entities to load within the event would render in the SQL, but would not be reflected during the loading process. @@ -1706,8 +1706,8 @@ the tables; we instead emit a warning and go with the unsorted list. If an environment needs both ordered DROPs *and* has foreign key cycles, then the warning notes they will need to restore the - ``use_alter`` flag to their :class:`.ForeignKey` and - :class:`.ForeignKeyConstraint` objects so that just those objects will + ``use_alter`` flag to their :class:`_schema.ForeignKey` and + :class:`_schema.ForeignKeyConstraint` objects so that just those objects will be omitted from the dependency sort. .. seealso:: @@ -1801,13 +1801,13 @@ :tags: bug, orm :tickets: 3367 - Identified an inconsistency when handling :meth:`.Query.join` to the + Identified an inconsistency when handling :meth:`_query.Query.join` to the same target more than once; it implicitly dedupes only in the case of a relationship join, and due to :ticket:`3233`, in 1.0 a join to the same table twice behaves differently than 0.9 in that it no longer erroneously aliases. To help document this change, the verbiage regarding :ticket:`3233` in the migration notes has - been generalized, and a warning has been added when :meth:`.Query.join` + been generalized, and a warning has been added when :meth:`_query.Query.join` is called against the same target relationship more than once. .. change:: @@ -1853,8 +1853,8 @@ :tags: feature, sql :tickets: 3084 - The topological sorting used to sort :class:`.Table` objects - and available via the :attr:`.MetaData.sorted_tables` collection + The topological sorting used to sort :class:`_schema.Table` objects + and available via the :attr:`_schema.MetaData.sorted_tables` collection will now produce a **deterministic** ordering; that is, the same ordering each time given a set of tables with particular names and dependencies. This is to help with comparison of DDL scripts @@ -1872,7 +1872,7 @@ Added new argument :paramref:`.Query.update.update_args` which allows kw arguments such as ``mysql_limit`` to be passed to the underlying - :class:`.Update` construct. Pull request courtesy Amir Sadoughi. + :class:`_expression.Update` construct. Pull request courtesy Amir Sadoughi. .. changelog:: :version: 1.0.0b5 @@ -1882,11 +1882,11 @@ :tags: bug, orm :tickets: 3349 - :class:`.Query` doesn't support joins, subselects, or special - FROM clauses when using the :meth:`.Query.update` or - :meth:`.Query.delete` methods; instead of silently ignoring these - fields if methods like :meth:`.Query.join` or - :meth:`.Query.select_from` has been called, an error is raised. + :class:`_query.Query` doesn't support joins, subselects, or special + FROM clauses when using the :meth:`_query.Query.update` or + :meth:`_query.Query.delete` methods; instead of silently ignoring these + fields if methods like :meth:`_query.Query.join` or + :meth:`_query.Query.select_from` has been called, an error is raised. In 0.9.10 this only emits a warning. .. change:: @@ -1959,7 +1959,7 @@ The "auto-attach" feature of constraints such as :class:`.UniqueConstraint` and :class:`.CheckConstraint` has been further enhanced such that - when the constraint is associated with non-table-bound :class:`.Column` + when the constraint is associated with non-table-bound :class:`_schema.Column` objects, the constraint will set up event listeners with the columns themselves such that the constraint auto attaches at the same time the columns are associated with the table. This in particular @@ -2053,7 +2053,7 @@ Fixed unexpected use regression from pullreq github:137 where Py2K unicode literals (e.g. ``u""``) would not be accepted by the - :paramref:`.relationship.cascade` option. + :paramref:`_orm.relationship.cascade` option. Pull request courtesy Julien Castets. @@ -2072,7 +2072,7 @@ Added a new extension suite :mod:`sqlalchemy.ext.baked`. This simple but unusual system allows for a dramatic savings in Python - overhead for the construction and processing of orm :class:`.Query` + overhead for the construction and processing of orm :class:`_query.Query` objects, from query construction up through rendering of a string SQL statement. @@ -2084,12 +2084,12 @@ :tags: bug, postgresql :tickets: 3319 - The PostgreSQL :class:`.postgresql.ENUM` type will emit a + The PostgreSQL :class:`_postgresql.ENUM` type will emit a DROP TYPE instruction when a plain ``table.drop()`` is called, assuming the object is not associated directly with a - :class:`.MetaData` object. In order to accommodate the use case of + :class:`_schema.MetaData` object. In order to accommodate the use case of an enumerated type shared between multiple tables, the type should - be associated directly with the :class:`.MetaData` object; in this + be associated directly with the :class:`_schema.MetaData` object; in this case the type will only be created at the metadata level, or if created directly. The rules for create/drop of PostgreSQL enumerated types have been highly reworked in general. @@ -2105,11 +2105,11 @@ Added a new event suite :class:`.QueryEvents`. The :meth:`.QueryEvents.before_compile` event allows the creation of functions which may place additional modifications to - :class:`.Query` objects before the construction of the SELECT + :class:`_query.Query` objects before the construction of the SELECT statement. It is hoped that this event be made much more useful via the advent of a new inspection system that will allow for detailed modifications to be made against - :class:`.Query` objects in an automated fashion. + :class:`_query.Query` objects in an automated fashion. .. seealso:: @@ -2124,7 +2124,7 @@ is used with a one-to-many query that also features LIMIT, OFFSET, or DISTINCT has been disabled in the case of a one-to-one relationship, that is a one-to-many with - :paramref:`.relationship.uselist` set to False. This will produce + :paramref:`_orm.relationship.uselist` set to False. This will produce more efficient queries in these cases. .. seealso:: @@ -2226,7 +2226,7 @@ :tickets: 3087 Literal values within a :class:`.DefaultClause`, which is invoked - when using the :paramref:`.Column.server_default` parameter, will + when using the :paramref:`_schema.Column.server_default` parameter, will now be rendered using the "inline" compiler, so that they are rendered as-is, rather than as bound parameters. @@ -2310,9 +2310,9 @@ :tags: bug, orm :tickets: 3227, 3242, 1326 - The primary :class:`.Mapper` of a :class:`.Query` is now passed to the + The primary :class:`_orm.Mapper` of a :class:`_query.Query` is now passed to the :meth:`.Session.get_bind` method when calling upon - :meth:`.Query.count`, :meth:`.Query.update`, :meth:`.Query.delete`, + :meth:`_query.Query.count`, :meth:`_query.Query.update`, :meth:`_query.Query.delete`, as well as queries against mapped columns, :obj:`.column_property` objects, and SQL functions and expressions derived from mapped columns. This allows sessions that rely upon @@ -2343,7 +2343,7 @@ :tags: bug, sql :tickets: 3288 - The multi-values version of :meth:`.Insert.values` has been + The multi-values version of :meth:`_expression.Insert.values` has been repaired to work more usefully with tables that have Python- side default values and/or functions, as well as server-side defaults. The feature will now work with a dialect that uses @@ -2398,11 +2398,11 @@ :tags: feature, schema :tickets: 3282 - The DDL generation system of :meth:`.MetaData.create_all` - and :meth:`.MetaData.drop_all` has been enhanced to in most + The DDL generation system of :meth:`_schema.MetaData.create_all` + and :meth:`_schema.MetaData.drop_all` has been enhanced to in most cases automatically handle the case of mutually dependent foreign key constraints; the need for the - :paramref:`.ForeignKeyConstraint.use_alter` flag is greatly + :paramref:`_schema.ForeignKeyConstraint.use_alter` flag is greatly reduced. The system also works for constraints which aren't given a name up front; only in the case of DROP is a name required for at least one of the constraints involved in the cycle. @@ -2414,9 +2414,9 @@ .. change:: :tags: feature, schema - Added a new accessor :attr:`.Table.foreign_key_constraints` - to complement the :attr:`.Table.foreign_keys` collection, - as well as :attr:`.ForeignKeyConstraint.referred_table`. + Added a new accessor :attr:`_schema.Table.foreign_key_constraints` + to complement the :attr:`_schema.Table.foreign_keys` collection, + as well as :attr:`_schema.ForeignKeyConstraint.referred_table`. .. change:: :tags: bug, sqlite @@ -2473,9 +2473,9 @@ :tags: bug, sqlite :tickets: 3257 - The SQLite dialect, when using the :class:`.sqlite.DATE`, - :class:`.sqlite.TIME`, - or :class:`.sqlite.DATETIME` types, and given a ``storage_format`` that + The SQLite dialect, when using the :class:`_sqlite.DATE`, + :class:`_sqlite.TIME`, + or :class:`_sqlite.DATETIME` types, and given a ``storage_format`` that only renders numbers, will render the types in DDL as ``DATE_CHAR``, ``TIME_CHAR``, and ``DATETIME_CHAR``, so that despite the lack of alpha characters in the values, the column will still @@ -2495,7 +2495,7 @@ take effect in all engine connection use cases, including when user-custom connect routines are used via the :paramref:`.create_engine.creator` parameter, as well as when - the :class:`.Connection` encounters a connection error on + the :class:`_engine.Connection` encounters a connection error on revalidation. .. seealso:: @@ -2512,7 +2512,7 @@ :tags: bug, oracle An alias name will be properly quoted when referred to using the - ``%(name)s`` token inside the :meth:`.Select.with_hint` method. + ``%(name)s`` token inside the :meth:`_expression.Select.with_hint` method. Previously, the Oracle backend hadn't implemented this quoting. .. change:: @@ -2521,7 +2521,7 @@ Added support for CTEs under Oracle. This includes some tweaks to the aliasing syntax, as well as a new CTE feature - :meth:`.CTE.suffix_with`, which is useful for adding in special + :meth:`_expression.CTE.suffix_with`, which is useful for adding in special Oracle-specific directives to the CTE. .. seealso:: @@ -2582,7 +2582,7 @@ :tags: bug, sql :tickets: 3260 - Fixed bug in :meth:`.Table.tometadata` method where the + Fixed bug in :meth:`_schema.Table.tometadata` method where the :class:`.CheckConstraint` associated with a :class:`.Boolean` or :class:`.Enum` type object would be doubled in the target table. The copy process now tracks the production of this constraint object @@ -2593,19 +2593,19 @@ :tickets: 3217 Added a parameter :paramref:`.Query.join.isouter` which is synonymous - with calling :meth:`.Query.outerjoin`; this flag is to provide a more - consistent interface compared to Core :meth:`.FromClause.join`. + with calling :meth:`_query.Query.outerjoin`; this flag is to provide a more + consistent interface compared to Core :meth:`_expression.FromClause.join`. Pull request courtesy Jonathan Vanasco. .. change:: :tags: bug, sql :tickets: 3243 - The behavioral contract of the :attr:`.ForeignKeyConstraint.columns` + The behavioral contract of the :attr:`_schema.ForeignKeyConstraint.columns` collection has been made consistent; this attribute is now a - :class:`.ColumnCollection` like that of all other constraints and + :class:`_expression.ColumnCollection` like that of all other constraints and is initialized at the point when the constraint is associated with - a :class:`.Table`. + a :class:`_schema.Table`. .. seealso:: @@ -2617,7 +2617,7 @@ The :meth:`.PropComparator.of_type` modifier has been improved in conjunction with loader directives such as - :func:`.joinedload` and :func:`.contains_eager` such that if + :func:`_orm.joinedload` and :func:`.contains_eager` such that if two :meth:`.PropComparator.of_type` modifiers of the same base type/path are encountered, they will be joined together into a single "polymorphic" entity, rather than replacing @@ -2637,10 +2637,10 @@ :tags: bug, sql :tickets: 3245 - The :attr:`.Column.key` attribute is now used as the source of + The :attr:`_schema.Column.key` attribute is now used as the source of anonymous bound parameter names within expressions, to match the existing use of this value as the key when rendered in an INSERT - or UPDATE statement. This allows :attr:`.Column.key` to be used + or UPDATE statement. This allows :attr:`_schema.Column.key` to be used as a "substitute" string to work around a difficult column name that doesn't translate well into a bound parameter name. Note that the paramstyle is configurable on :func:`.create_engine` in any case, @@ -2658,11 +2658,11 @@ :tags: feature, sql Added a new parameter :paramref:`.Table.tometadata.name` to - the :meth:`.Table.tometadata` method. Similar to + the :meth:`_schema.Table.tometadata` method. Similar to :paramref:`.Table.tometadata.schema`, this argument causes the newly - copied :class:`.Table` to take on the new name instead of + copied :class:`_schema.Table` to take on the new name instead of the existing one. An interesting capability this adds is that of - copying a :class:`.Table` object to the *same* :class:`.MetaData` + copying a :class:`_schema.Table` object to the *same* :class:`_schema.MetaData` target with a new name. Pull request courtesy n.d. parker. .. change:: @@ -2670,7 +2670,7 @@ Repaired support of the ``copy.deepcopy()`` call when used by the :class:`.orm.util.CascadeOptions` argument, which occurs - if ``copy.deepcopy()`` is being used with :func:`.relationship` + if ``copy.deepcopy()`` is being used with :func:`_orm.relationship` (not an officially supported use case). Pull request courtesy duesenfranz. @@ -2737,13 +2737,13 @@ :tags: bug, orm :tickets: 3228 - The :meth:`.Query.update` method will now convert string key + The :meth:`_query.Query.update` method will now convert string key names in the given dictionary of values into mapped attribute names against the mapped class being updated. Previously, string names were taken in directly and passed to the core update statement without any means to resolve against the mapped entity. Support for synonyms and hybrid attributes as the subject attributes of - :meth:`.Query.update` are also supported. + :meth:`_query.Query.update` are also supported. .. seealso:: @@ -2774,7 +2774,7 @@ .. change:: :tags: feature, sql - :meth:`.Insert.from_select` now includes Python and SQL-expression + :meth:`_expression.Insert.from_select` now includes Python and SQL-expression defaults if otherwise unspecified; the limitation where non- server column defaults aren't included in an INSERT FROM SELECT is now lifted and these expressions are rendered as @@ -2807,9 +2807,9 @@ :tags: bug, orm :tickets: 3222 - The ON clause rendered when using :meth:`.Query.join`, - :meth:`.Query.outerjoin`, or the standalone :func:`.orm.join` / - :func:`.orm.outerjoin` functions to a single-inheritance subclass will + The ON clause rendered when using :meth:`_query.Query.join`, + :meth:`_query.Query.outerjoin`, or the standalone :func:`_orm.join` / + :func:`_orm.outerjoin` functions to a single-inheritance subclass will now include the "single table criteria" in the ON clause even if the ON clause is otherwise hand-rolled; it is now added to the criteria using AND, the same way as if joining to a single-table @@ -2826,7 +2826,7 @@ :tickets: 3184 The :class:`.UniqueConstraint` construct is now included when - reflecting a :class:`.Table` object, for databases where this + reflecting a :class:`_schema.Table` object, for databases where this is applicable. In order to achieve this with sufficient accuracy, MySQL and PostgreSQL now contain features that correct for the duplication of indexes and unique constraints @@ -2834,14 +2834,14 @@ In the case of MySQL, there is not actually a "unique constraint" concept independent of a "unique index", so for this backend :class:`.UniqueConstraint` continues to remain non-present for a - reflected :class:`.Table`. For PostgreSQL, the query used to + reflected :class:`_schema.Table`. For PostgreSQL, the query used to detect indexes against ``pg_index`` has been improved to check for the same construct in ``pg_constraint``, and the implicitly constructed unique index is not included with a - reflected :class:`.Table`. + reflected :class:`_schema.Table`. - In both cases, the :meth:`.Inspector.get_indexes` and the - :meth:`.Inspector.get_unique_constraints` methods return both + In both cases, the :meth:`_reflection.Inspector.get_indexes` and the + :meth:`_reflection.Inspector.get_unique_constraints` methods return both constructs individually, but include a new token ``duplicates_constraint`` in the case of PostgreSQL or ``duplicates_index`` in the case @@ -2868,7 +2868,7 @@ :tickets: 3215 Fixed bug where a "branched" connection, that is the kind you get - when you call :meth:`.Connection.connect`, would not share invalidation + when you call :meth:`_engine.Connection.connect`, would not share invalidation status with the parent. The architecture of branching has been tweaked a bit so that the branched connection defers to the parent for all invalidation status and operations. @@ -2878,7 +2878,7 @@ :tickets: 3190 Fixed bug where a "branched" connection, that is the kind you get - when you call :meth:`.Connection.connect`, would not share transaction + when you call :meth:`_engine.Connection.connect`, would not share transaction status with the parent. The architecture of branching has been tweaked a bit so that the branched connection defers to the parent for all transactional status and operations. @@ -2922,7 +2922,7 @@ one or more non-nullable columns. This argument is present in the keywords passed to :func:`.automap.generate_relationship` in this case and can still be overridden. Additionally, if the - :class:`.ForeignKeyConstraint` specifies ``ondelete="CASCADE"`` + :class:`_schema.ForeignKeyConstraint` specifies ``ondelete="CASCADE"`` for a non-nullable or ``ondelete="SET NULL"`` for a nullable set of columns, the argument ``passive_deletes=True`` is also added to the relationship. Note that not all backends support reflection of @@ -2932,8 +2932,8 @@ :tags: feature, sql :tickets: 3206 - Added new method :meth:`.Select.with_statement_hint` and ORM - method :meth:`.Query.with_statement_hint` to support statement-level + Added new method :meth:`_expression.Select.with_statement_hint` and ORM + method :meth:`_query.Query.with_statement_hint` to support statement-level hints that are not specific to a table. .. change:: @@ -2953,12 +2953,12 @@ :tags: bug, sqlite :tickets: 3204 - Added :meth:`.Inspector.get_temp_table_names` and - :meth:`.Inspector.get_temp_view_names`; currently, only the + Added :meth:`_reflection.Inspector.get_temp_table_names` and + :meth:`_reflection.Inspector.get_temp_view_names`; currently, only the SQLite and Oracle dialects support these methods. The return of temporary table and view names has been **removed** from SQLite and - Oracle's version of :meth:`.Inspector.get_table_names` and - :meth:`.Inspector.get_view_names`; other database backends cannot + Oracle's version of :meth:`_reflection.Inspector.get_table_names` and + :meth:`_reflection.Inspector.get_view_names`; other database backends cannot support this information (such as MySQL), and the scope of operation is different in that the tables can be local to a session and typically aren't supported in remote schemas. @@ -2973,9 +2973,9 @@ Support has been added for reflection of materialized views and foreign tables, as well as support for materialized views - within :meth:`.Inspector.get_view_names`, and a new method + within :meth:`_reflection.Inspector.get_view_names`, and a new method :meth:`.PGInspector.get_foreign_table_names` available on the - PostgreSQL version of :class:`.Inspector`. Pull request courtesy + PostgreSQL version of :class:`_reflection.Inspector`. Pull request courtesy Rodrigo Menezes. .. seealso:: @@ -3053,7 +3053,7 @@ .. change:: :tags: changed, sql - The :func:`~.expression.column` and :func:`~.expression.table` + The :func:`_expression.column` and :func:`_expression.table` constructs are now importable from the "from sqlalchemy" namespace, just like every other Core construct. @@ -3061,9 +3061,9 @@ :tags: changed, sql :tickets: 2992 - The implicit conversion of strings to :func:`.text` constructs - when passed to most builder methods of :func:`~.sql.expression.select` as - well as :class:`.Query` now emits a warning with just the + The implicit conversion of strings to :func:`_expression.text` constructs + when passed to most builder methods of :func:`_expression.select` as + well as :class:`_query.Query` now emits a warning with just the plain string sent. The textual conversion still proceeds normally, however. The only method that accepts a string without a warning are the "label reference" methods like order_by(), group_by(); @@ -3100,13 +3100,13 @@ .. change:: :tags: feature, orm - The :class:`.Query` will raise an exception when :meth:`.Query.yield_per` + The :class:`_query.Query` will raise an exception when :meth:`_query.Query.yield_per` is used with mappings or options where either subquery eager loading, or joined eager loading with collections, would take place. These loading strategies are not currently compatible with yield_per, so by raising this error, the method is safer to use. Eager loads can be disabled with - the ``lazyload('*')`` option or :meth:`.Query.enable_eagerloads`. + the ``lazyload('*')`` option or :meth:`_query.Query.enable_eagerloads`. .. seealso:: @@ -3117,8 +3117,8 @@ :tickets: 3177 Changed the approach by which the "single inheritance criterion" - is applied, when using :meth:`.Query.from_self`, or its common - user :meth:`.Query.count`. The criteria to limit rows to those + is applied, when using :meth:`_query.Query.from_self`, or its common + user :meth:`_query.Query.count`. The criteria to limit rows to those with a certain type is now indicated on the inside subquery, not the outside one, so that even if the "type" column is not available in the columns clause, we can filter on it on the "inner" @@ -3166,7 +3166,7 @@ :tickets: 3176 A new implementation for :class:`.KeyedTuple` used by the - :class:`.Query` object offers dramatic speed improvements when + :class:`_query.Query` object offers dramatic speed improvements when fetching large numbers of column-oriented rows. .. seealso:: @@ -3177,8 +3177,8 @@ :tags: feature, orm :tickets: 3008 - The behavior of :paramref:`.joinedload.innerjoin` as well as - :paramref:`.relationship.innerjoin` is now to use "nested" + The behavior of :paramref:`_orm.joinedload.innerjoin` as well as + :paramref:`_orm.relationship.innerjoin` is now to use "nested" inner joins, that is, right-nested, as the default behavior when an inner join joined eager load is chained to an outer join eager load. @@ -3198,8 +3198,8 @@ :tags: bug, sql :tickets: 3169 - Using :meth:`.Insert.from_select` now implies ``inline=True`` - on :func:`~.sql.expression.insert`. This helps to fix a bug where an + Using :meth:`_expression.Insert.from_select` now implies ``inline=True`` + on :func:`_expression.insert`. This helps to fix a bug where an INSERT...FROM SELECT construct would inadvertently be compiled as "implicit returning" on supporting backends, which would cause breakage in the case of an INSERT that inserts zero rows @@ -3215,7 +3215,7 @@ may prefer ``inline=True`` with INSERT..FROM SELECT as some databases don't support returning and therefore can't do "implicit" returning, but there's no reason an INSERT...FROM SELECT needs implicit returning - in any case. Regular explicit :meth:`.Insert.returning` should + in any case. Regular explicit :meth:`_expression.Insert.returning` should be used to return variable numbers of result rows if inserted data is needed. @@ -3240,7 +3240,7 @@ Added support for PG table options TABLESPACE, ON COMMIT, WITH(OUT) OIDS, and INHERITS, when rendering DDL via - the :class:`.Table` construct. Pull request courtesy + the :class:`_schema.Table` construct. Pull request courtesy malikdiarra. .. seealso:: @@ -3291,8 +3291,8 @@ :tickets: 2963 The ``info`` parameter has been added as a constructor argument - to all schema constructs including :class:`.MetaData`, - :class:`.Index`, :class:`.ForeignKey`, :class:`.ForeignKeyConstraint`, + to all schema constructs including :class:`_schema.MetaData`, + :class:`.Index`, :class:`_schema.ForeignKey`, :class:`_schema.ForeignKeyConstraint`, :class:`.UniqueConstraint`, :class:`.PrimaryKeyConstraint`, :class:`.CheckConstraint`. @@ -3304,14 +3304,14 @@ :class:`.InspectionAttr`, where in addition to being available on all :class:`.MapperProperty` objects, it is also now available on hybrid properties, association proxies, when accessed via - :attr:`.Mapper.all_orm_descriptors`. + :attr:`_orm.Mapper.all_orm_descriptors`. .. change:: :tags: sql, feature :tickets: 3027 - The :paramref:`.Table.autoload_with` flag now implies that - :paramref:`.Table.autoload` should be ``True``. Pull request + The :paramref:`_schema.Table.autoload_with` flag now implies that + :paramref:`_schema.Table.autoload` should be ``True``. Pull request courtesy Malik Diarra. .. change:: @@ -3385,7 +3385,7 @@ :tags: feature, sql :tickets: 3034 - The :meth:`.Select.limit` and :meth:`.Select.offset` methods + The :meth:`_expression.Select.limit` and :meth:`_expression.Select.offset` methods now accept any SQL expression, in addition to integer values, as arguments. Typically this is used to allow a bound parameter to be passed, which can be substituted with a value later thus allowing diff --git a/doc/build/changelog/changelog_11.rst b/doc/build/changelog/changelog_11.rst index c50322ad1e..9c5427a69e 100644 --- a/doc/build/changelog/changelog_11.rst +++ b/doc/build/changelog/changelog_11.rst @@ -121,8 +121,8 @@ :tickets: 4162 :versions: 1.2.1 - Fixed bug in :meth:`.Insert.values` where using the "multi-values" - format in combination with :class:`.Column` objects as keys rather + Fixed bug in :meth:`_expression.Insert.values` where using the "multi-values" + format in combination with :class:`_schema.Column` objects as keys rather than strings would fail. Pull request courtesy Aubrey Stark-Toller. .. change:: @@ -140,7 +140,7 @@ Fixed a fairly serious connection pool bug where a connection that is acquired after being refreshed as a result of a user-defined - :class:`.DisconnectionError` or due to the 1.2-released "pre_ping" feature + :class:`_exc.DisconnectionError` or due to the 1.2-released "pre_ping" feature would not be correctly reset if the connection were returned to the pool by weakref cleanup (e.g. the front-facing object is garbage collected); the weakref would still refer to the previously invalidated DBAPI connection @@ -222,7 +222,7 @@ :tickets: 4006 :versions: 1.2.0b3 - Made further fixes to the :class:`.ARRAY` class in conjunction with + Made further fixes to the :class:`_types.ARRAY` class in conjunction with COLLATE, as the fix made in :ticket:`4006` failed to accommodate for a multidimensional array. @@ -250,9 +250,9 @@ :tickets: 4107 :versions: 1.2.0b3 - Fixed bug in :obj:`.array_agg` function where passing an argument - that is already of type :class:`.ARRAY`, such as a PostgreSQL - :obj:`.postgresql.array` construct, would produce a ``ValueError``, due + Fixed bug in :obj:`_functions.array_agg` function where passing an argument + that is already of type :class:`_types.ARRAY`, such as a PostgreSQL + :obj:`_postgresql.array` construct, would produce a ``ValueError``, due to the function attempting to nest the arrays. .. change:: @@ -272,7 +272,7 @@ Fixed bug in PostgreSQL :meth:`.postgresql.dml.Insert.on_conflict_do_update` which would prevent the insert statement from being used as a CTE, - e.g. via :meth:`.Insert.cte`, within another statement. + e.g. via :meth:`_expression.Insert.cte`, within another statement. .. change:: :tags: bug, orm @@ -311,7 +311,7 @@ Fixed bug where the recently added :meth:`.ColumnOperators.any_` and :meth:`.ColumnOperators.all_` methods didn't work when called as methods, as opposed to using the standalone functions - :func:`~.expression.any_` and :func:`~.expression.all_`. Also + :func:`_expression.any_` and :func:`_expression.all_`. Also added documentation examples for these relatively unintuitive SQL operators. @@ -420,7 +420,7 @@ Fixed bug involving JSON NULL evaluation logic added in 1.1 as part of :ticket:`3514` where the logic would not accommodate ORM - mapped attributes named differently from the :class:`.Column` + mapped attributes named differently from the :class:`_schema.Column` that was mapped. .. change:: 4030 @@ -480,7 +480,7 @@ :tickets: 4006 :versions: 1.2.0b1 - Fixed bug where using :class:`.ARRAY` with a string type that + Fixed bug where using :class:`_types.ARRAY` with a string type that features a collation would fail to produce the correct syntax within CREATE TABLE. @@ -523,7 +523,7 @@ :tickets: 3973 :versions: 1.2.0b1 - Added a placeholder type :class:`.mssql.XML` to the SQL Server + Added a placeholder type :class:`_mssql.XML` to the SQL Server dialect, so that a reflected table which includes this type can be re-rendered as a CREATE TABLE. The type has no special round-trip behavior nor does it currently support additional qualifying @@ -558,7 +558,7 @@ :tickets: 3949 An :class:`.ArgumentError` is now raised if a - :class:`.ForeignKeyConstraint` object is created with a mismatched + :class:`_schema.ForeignKeyConstraint` object is created with a mismatched number of "local" and "remote" columns, which otherwise causes the internal state of the constraint to be incorrect. Note that this also impacts the condition where a dialect's reflection process @@ -634,7 +634,7 @@ :tickets: 3955 Changed the mechanics of :class:`.ResultProxy` to unconditionally - delay the "autoclose" step until the :class:`.Connection` is done + delay the "autoclose" step until the :class:`_engine.Connection` is done with the object; in the case where PostgreSQL ON CONFLICT with RETURNING returns no rows, autoclose was occurring in this previously non-existent use case, causing the usual autocommit behavior that @@ -654,8 +654,8 @@ been copied using :meth:`.TypeEngine.copy`. This became more of a regression in 1.1 compared to 1.0 because the :class:`.TypeDecorator` class is now a subclass of :class:`.SchemaEventTarget`, which among - other things indicates to the parent :class:`.Column` that the type - should be copied when the :class:`.Column` is. These copies are + other things indicates to the parent :class:`_schema.Column` that the type + should be copied when the :class:`_schema.Column` is. These copies are common when using declarative with mixins or abstract classes. .. change:: @@ -663,7 +663,7 @@ :versions: 1.2.0b1 Added support for bound parameters, e.g. those normally set up - via :meth:`.Query.params`, to the :meth:`.baked.Result.count` + via :meth:`_query.Query.params`, to the :meth:`.baked.Result.count` method. Previously, support for parameters were omitted. Pull request courtesy Pat Deegan. @@ -685,11 +685,11 @@ :versions: 1.2.0b1 An :func:`.aliased()` construct can now be passed to the - :meth:`.Query.select_entity_from` method. Entities will be pulled + :meth:`_query.Query.select_entity_from` method. Entities will be pulled from the selectable represented by the :func:`.aliased` construct. This allows special options for :func:`.aliased` such as :paramref:`.aliased.adapt_on_names` to be used in conjunction with - :meth:`.Query.select_entity_from`. + :meth:`_query.Query.select_entity_from`. .. change:: :tags: bug, engine @@ -697,7 +697,7 @@ :versions: 1.2.0b1 Added an exception handler that will warn for the "cause" exception on - Py2K when the "autorollback" feature of :class:`.Connection` itself + Py2K when the "autorollback" feature of :class:`_engine.Connection` itself raises an exception. In Py3K, the two exceptions are naturally reported by the interpreter as one occurring during the handling of the other. This is continuing with the series of changes for rollback failure @@ -733,11 +733,11 @@ Fixed bug in compiler where the string identifier of a savepoint would be cached in the identifier quoting dictionary; as these identifiers are arbitrary, a small memory leak could occur if a single - :class:`.Connection` had an unbounded number of savepoints used, + :class:`_engine.Connection` had an unbounded number of savepoints used, as well as if the savepoint clause constructs were used directly with an unbounded umber of savepoint names. The memory leak does **not** impact the vast majority of cases as normally the - :class:`.Connection`, which renders savepoint names with a simple + :class:`_engine.Connection`, which renders savepoint names with a simple counter starting at "1", is used on a per-transaction or per-fixed-number-of-transactions basis before being discarded. @@ -823,7 +823,7 @@ allow a non-textual expression to be passed as the value of the "default" for the new column, such as a :class:`.FetchedValue` object to indicate a generic triggered default or a - :func:`.sql.expression.text` construct. Clarified the documentation + :func:`_expression.text` construct. Clarified the documentation in this regard as well. .. change:: 3901 @@ -840,7 +840,7 @@ Fixed bug in PostgreSQL :class:`.ExcludeConstraint` where the "whereclause" and "using" parameters would not be copied during an - operation like :meth:`.Table.tometadata`. + operation like :meth:`_schema.Table.tometadata`. .. change:: 3898 :tags: bug, mssql @@ -959,7 +959,7 @@ :tickets: 3880 Fixed bug where literal_binds compiler flag was not honored by the - :class:`~.sql.expression.Insert` construct for the "multiple values" feature; the + :class:`_expression.Insert` construct for the "multiple values" feature; the subsequent values are now rendered as literals. .. change:: 3877 @@ -1000,9 +1000,9 @@ :tags: bug, sql The engine URL embedded in the exception for "could not reflect" - in :meth:`.MetaData.reflect` now conceals the password; also + in :meth:`_schema.MetaData.reflect` now conceals the password; also the ``__repr__`` for :class:`.TLEngine` now acts like that of - :class:`.Engine`, concealing the URL password. Pull request courtesy + :class:`_engine.Engine`, concealing the URL password. Pull request courtesy Valery Yundin. .. change:: 3867 @@ -1017,7 +1017,7 @@ .. change:: pg_timestamp_zero_prec :tags: bug, postgresql - The :class:`.postgresql.TIME` and :class:`.postgresql.TIMESTAMP` + The :class:`_postgresql.TIME` and :class:`_postgresql.TIMESTAMP` datatypes now support a setting of zero for "precision"; previously a zero would be ignored. Pull request courtesy Ionuț Ciocîrlan. @@ -1025,12 +1025,12 @@ :tags: bug, engine :tickets: 3861 - The "extend_existing" option of :class:`.Table` reflection would + The "extend_existing" option of :class:`_schema.Table` reflection would cause indexes and constraints to be doubled up in the case that the parameter - were used with :meth:`.MetaData.reflect` (as the automap extension does) + were used with :meth:`_schema.MetaData.reflect` (as the automap extension does) due to tables being reflected both within the foreign key path as well as directly. A new de-duplicating set is passed through within the - :meth:`.MetaData.reflect` sequence to prevent double reflection in this + :meth:`_schema.MetaData.reflect` sequence to prevent double reflection in this way. .. change:: 3859 @@ -1051,12 +1051,12 @@ :tickets: 3856 Fixed bug related to :ticket:`3177`, where a UNION or other set operation - emitted by a :class:`.Query` would apply "single-inheritance" criteria + emitted by a :class:`_query.Query` would apply "single-inheritance" criteria to the outside of the union (also referencing the wrong selectable), even though this criteria is now expected to be already present on the inside subqueries. The single-inheritance criteria is now omitted once union() or another set operation is - called against :class:`.Query` in the same way as :meth:`.Query.from_self`. + called against :class:`_query.Query` in the same way as :meth:`_query.Query.from_self`. .. change:: 3548 :tags: bug, firebird @@ -1092,7 +1092,7 @@ :tags: bug, engine Removed long-broken "default_schema_name()" method from - :class:`.Connection`. This method was left over from a very old + :class:`_engine.Connection`. This method was left over from a very old version and was non-working (e.g. would raise). Pull request courtesy Benjamin Dopplinger. @@ -1176,7 +1176,7 @@ :tickets: 3835 PostgreSQL table reflection will ensure that the - :paramref:`.Column.autoincrement` flag is set to False when reflecting + :paramref:`_schema.Column.autoincrement` flag is set to False when reflecting a primary key column that is not of an :class:`.Integer` datatype, even if the default is related to an integer-generating sequence. This can happen if a column is created as SERIAL and the datatype @@ -1187,8 +1187,8 @@ :tags: bug, orm :tickets: 3836 - Fixed regression where some :class:`.Query` methods like - :meth:`.Query.update` and others would fail if the :class:`.Query` + Fixed regression where some :class:`_query.Query` methods like + :meth:`_query.Query.update` and others would fail if the :class:`_query.Query` were against a series of mapped columns, rather than the mapped entity as a whole. @@ -1320,7 +1320,7 @@ ORM attributes can now be assigned any object that is has a ``__clause_element__()`` attribute, which will result in inline - SQL the way any :class:`.ClauseElement` class does. This covers other + SQL the way any :class:`_expression.ClauseElement` class does. This covers other mapped attributes not otherwise transformed by further expression constructs. @@ -1330,7 +1330,7 @@ Enhanced the new "raise" lazy loader strategy to also include a "raise_on_sql" variant, available both via :paramref:`.orm.relationship.lazy` - as well as :func:`.orm.raiseload`. This variant only raises if the + as well as :func:`_orm.raiseload`. This variant only raises if the lazy load would actually emit SQL, vs. raising if the lazy loader mechanism is invoked at all. @@ -1368,7 +1368,7 @@ :tickets: 3809 A string sent as a column default via the - :paramref:`.Column.server_default` parameter is now escaped for quotes. + :paramref:`_schema.Column.server_default` parameter is now escaped for quotes. .. seealso:: @@ -1398,9 +1398,9 @@ :tickets: 3803 The ``BaseException`` exception class is now intercepted by the - exception-handling routines of :class:`.Connection`, and includes + exception-handling routines of :class:`_engine.Connection`, and includes handling by the :meth:`~.ConnectionEvents.handle_error` - event. The :class:`.Connection` is now **invalidated** by default in + event. The :class:`_engine.Connection` is now **invalidated** by default in the case of a system level exception that is not a subclass of ``Exception``, including ``KeyboardInterrupt`` and the greenlet ``GreenletExit`` class, to prevent further operations from occurring @@ -1426,7 +1426,7 @@ :tags: bug, orm :tickets: 3767 - The primaryjoin of a :func:`.relationship` construct can now include + The primaryjoin of a :func:`_orm.relationship` construct can now include a :func:`.bindparam` object that includes a callable function to generate values. Previously, the lazy loader strategy would be incompatible with this use, and additionally would fail to correctly @@ -1462,7 +1462,7 @@ :tags: bug, sql :tickets: 3789 - Stringify of expression with unnamed :class:`.Column` objects, as + Stringify of expression with unnamed :class:`_schema.Column` objects, as occurs in lots of situations including ORM error reporting, will now render the name in string context as "" rather than raising a compile error. @@ -1519,16 +1519,16 @@ .. change:: :tags: change, orm - Passing False to :meth:`.Query.order_by` in order to cancel + Passing False to :meth:`_query.Query.order_by` in order to cancel all order by's is deprecated; there is no longer any difference between calling this method with False or with None. .. change:: :tags: feature, orm - The :meth:`.Query.group_by` method now resets the group by collection + The :meth:`_query.Query.group_by` method now resets the group by collection if an argument of ``None`` is passed, in the same way that - :meth:`.Query.order_by` has worked for a long time. Pull request + :meth:`_query.Query.order_by` has worked for a long time. Pull request courtesy Iuri Diniz. .. change:: @@ -1581,7 +1581,7 @@ :tickets: 3744 Fixed bug in new CTE feature for update/insert/delete whereby - an anonymous (e.g. no name passed) :class:`.CTE` construct around + an anonymous (e.g. no name passed) :class:`_expression.CTE` construct around the statement would fail. .. change:: @@ -1608,10 +1608,10 @@ extension, whereby the existing compilation schemes for an established construct would be removed if that construct itself didn't already have its own dedicated ``__visit_name__``. This was a - rare occurrence in 1.0, however in 1.1 :class:`.postgresql.ARRAY` - subclasses :class:`.sqltypes.ARRAY` and has this behavior. + rare occurrence in 1.0, however in 1.1 :class:`_postgresql.ARRAY` + subclasses :class:`_types.ARRAY` and has this behavior. As a result, setting up a compilation handler for another dialect - such as SQLite would render the main :class:`.postgresql.ARRAY` + such as SQLite would render the main :class:`_postgresql.ARRAY` object no longer compilable. .. change:: @@ -1661,7 +1661,7 @@ :tags: feature, sql :tickets: 3718 - Added TABLESAMPLE support via the new :meth:`.FromClause.tablesample` + Added TABLESAMPLE support via the new :meth:`_expression.FromClause.tablesample` method and standalone function. Pull request courtesy Ilja Everilä. .. seealso:: @@ -1684,7 +1684,7 @@ :tags: bug, sql :tickets: 3724 - :meth:`.FromClause.count` is deprecated. This function makes use of + :meth:`_expression.FromClause.count` is deprecated. This function makes use of an arbitrary column in the table and is not reliable; for Core use, ``func.count()`` should be preferred. @@ -1786,7 +1786,7 @@ Added ``postgresql_tablespace`` as an argument to :class:`.Index` to allow specification of TABLESPACE for an index in PostgreSQL. - Complements the same-named parameter on :class:`.Table`. Pull + Complements the same-named parameter on :class:`_schema.Table`. Pull request courtesy Benjamin Bertrand. .. change:: @@ -1816,8 +1816,8 @@ Implemented reflection of CHECK constraints for SQLite and PostgreSQL. This is available via the new inspector method - :meth:`.Inspector.get_check_constraints` as well as when reflecting - :class:`.Table` objects in the form of :class:`.CheckConstraint` + :meth:`_reflection.Inspector.get_check_constraints` as well as when reflecting + :class:`_schema.Table` objects in the form of :class:`.CheckConstraint` objects present in the constraints collection. Pull request courtesy Alex Grönholm. @@ -1843,7 +1843,7 @@ :tags: change, orm :tickets: 3394 - The :paramref:`.Mapper.order_by` parameter is deprecated. + The :paramref:`_orm.Mapper.order_by` parameter is deprecated. This is an old parameter no longer relevant to how SQLAlchemy works, once the Query object was introduced. By deprecating it we establish that we aren't supporting non-working use cases @@ -1927,7 +1927,7 @@ :tags: feature, sql :tickets: 2857 - Added :meth:`.Select.lateral` and related constructs to allow + Added :meth:`_expression.Select.lateral` and related constructs to allow for the SQL standard LATERAL keyword, currently only supported by PostgreSQL. @@ -2012,7 +2012,7 @@ :tags: bug, orm :tickets: 3662 - An improvement to the workings of :meth:`.Query.correlate` such + An improvement to the workings of :meth:`_query.Query.correlate` such that when a "polymorphic" entity is used which represents a straight join of several tables, the statement will ensure that all the tables within the join are part of what's correlating. @@ -2078,7 +2078,7 @@ :tickets: 3641 A refinement to the logic which adds columns to the resulting SQL when - :meth:`.Query.distinct` is combined with :meth:`.Query.order_by` such + :meth:`_query.Query.distinct` is combined with :meth:`_query.Query.order_by` such that columns which are already present will not be added a second time, even if they are labeled with a different name. Regardless of this change, the extra columns added to the SQL have @@ -2098,8 +2098,8 @@ Added support for PEP-435-style enumerated classes, namely Python 3's ``enum.Enum`` class but also including compatible - enumeration libraries, to the :class:`.types.Enum` datatype. - The :class:`.types.Enum` datatype now also performs in-Python validation + enumeration libraries, to the :class:`_types.Enum` datatype. + The :class:`_types.Enum` datatype now also performs in-Python validation of incoming values, and adds an option to forego creating the CHECK constraint :paramref:`.Enum.create_constraint`. Pull request courtesy Alex Grönholm. @@ -2199,14 +2199,14 @@ :tags: feature, orm :tickets: 3081 - The ``str()`` call for :class:`.Query` will now take into account - the :class:`.Engine` to which the :class:`.Session` is bound, when + The ``str()`` call for :class:`_query.Query` will now take into account + the :class:`_engine.Engine` to which the :class:`.Session` is bound, when generating the string form of the SQL, so that the actual SQL that would be emitted to the database is shown, if possible. Previously, - only the engine associated with the :class:`.MetaData` to which the + only the engine associated with the :class:`_schema.MetaData` to which the mappings are associated would be used, if present. If no bind can be located either on the :class:`.Session` or on - the :class:`.MetaData` to which the mappings are associated, then + the :class:`_schema.MetaData` to which the mappings are associated, then the "default" dialect is used to render the SQL, as was the case previously. @@ -2218,7 +2218,7 @@ :tags: feature, sql :tickets: 3501 - A deep improvement to the recently added :meth:`.TextClause.columns` + A deep improvement to the recently added :meth:`_expression.TextClause.columns` method, and its interaction with result-row processing, now allows the columns passed to the method to be positionally matched with the result columns in the statement, rather than matching on name alone. @@ -2240,9 +2240,9 @@ :tags: feature, engine :tickets: 2685 - Multi-tenancy schema translation for :class:`.Table` objects is added. + Multi-tenancy schema translation for :class:`_schema.Table` objects is added. This supports the use case of an application that uses the same set of - :class:`.Table` objects in many schemas, such as schema-per-user. + :class:`_schema.Table` objects in many schemas, such as schema-per-user. A new execution option :paramref:`.Connection.execution_options.schema_translate_map` is added. @@ -2281,8 +2281,8 @@ :tags: feature, sql :tickets: 3619 - Added a new type to core :class:`.types.JSON`. This is the - base of the PostgreSQL :class:`.postgresql.JSON` type as well as that + Added a new type to core :class:`_types.JSON`. This is the + base of the PostgreSQL :class:`_postgresql.JSON` type as well as that of the new :class:`.mysql.JSON` type, so that a PG/MySQL-agnostic JSON column may be used. The type features basic index and path searching support. @@ -2296,10 +2296,10 @@ :tickets: 3616 Fixed an assertion that would raise somewhat inappropriately - if a :class:`.Index` were associated with a :class:`.Column` that - is associated with a lower-case-t :class:`.TableClause`; the + if a :class:`.Index` were associated with a :class:`_schema.Column` that + is associated with a lower-case-t :class:`_expression.TableClause`; the association should be ignored for the purposes of associating - the index with a :class:`.Table`. + the index with a :class:`_schema.Table`. .. change:: :tags: bug, orm @@ -2320,7 +2320,7 @@ :tickets: 3587 Added support for reflecting the source of materialized views - to the PostgreSQL version of the :meth:`.Inspector.get_view_definition` + to the PostgreSQL version of the :meth:`_reflection.Inspector.get_view_definition` method. .. change:: @@ -2338,7 +2338,7 @@ .. change:: :tags: enhancement, schema - The default generation functions passed to :class:`.Column` objects + The default generation functions passed to :class:`_schema.Column` objects are now run through "update_wrapper", or an equivalent function if a callable non-function is passed, so that introspection tools preserve the name and docstring of the wrapped function. Pull @@ -2348,14 +2348,14 @@ :tags: change, sql, mysql :tickets: 3216 - The system by which a :class:`.Column` considers itself to be an + The system by which a :class:`_schema.Column` considers itself to be an "auto increment" column has been changed, such that autoincrement - is no longer implicitly enabled for a :class:`.Table` that has a + is no longer implicitly enabled for a :class:`_schema.Table` that has a composite primary key. In order to accommodate being able to enable autoincrement for a composite PK member column while at the same time maintaining SQLAlchemy's long standing behavior of enabling implicit autoincrement for a single integer primary key, a third - state has been added to the :paramref:`.Column.autoincrement` parameter + state has been added to the :paramref:`_schema.Column.autoincrement` parameter ``"auto"``, which is now the default. .. seealso:: @@ -2385,7 +2385,7 @@ :tags: change, sqlite Added support to the SQLite dialect for the - :meth:`.Inspector.get_schema_names` method to work with SQLite; + :meth:`_reflection.Inspector.get_schema_names` method to work with SQLite; pull request courtesy Brian Van Klaveren. Also repaired support for creation of indexes with schemas as well as reflection of foreign key constraints in schema-bound tables. @@ -2426,8 +2426,8 @@ :tags: bug, postgresql :tickets: 2729 - The use of a :class:`.postgresql.ARRAY` object that refers - to a :class:`.types.Enum` or :class:`.postgresql.ENUM` subtype + The use of a :class:`_postgresql.ARRAY` object that refers + to a :class:`_types.Enum` or :class:`_postgresql.ENUM` subtype will now emit the expected "CREATE TYPE" and "DROP TYPE" DDL when the type is used within a "CREATE TABLE" or "DROP TABLE". @@ -2542,14 +2542,14 @@ :tags: feature, sql, postgresql :tickets: 3132 - Added support for the SQL-standard function :class:`.array_agg`, - which automatically returns an :class:`.postgresql.ARRAY` of the correct type + Added support for the SQL-standard function :class:`_functions.array_agg`, + which automatically returns an :class:`_postgresql.ARRAY` of the correct type and supports index / slice operations, as well as - :func:`.postgresql.array_agg`, which returns a :class:`.postgresql.ARRAY` + :func:`_postgresql.array_agg`, which returns a :class:`_postgresql.ARRAY` with additional comparison features. As arrays are only supported on PostgreSQL at the moment, only actually works on PostgreSQL. Also added a new construct - :class:`.postgresql.aggregate_order_by` in support of PG's + :class:`_postgresql.aggregate_order_by` in support of PG's "ORDER BY" extension. .. seealso:: @@ -2560,13 +2560,13 @@ :tags: feature, sql :tickets: 3516 - Added a new type to core :class:`.types.ARRAY`. This is the - base of the PostgreSQL :class:`.postgresql.ARRAY` type, and is now part of Core + Added a new type to core :class:`_types.ARRAY`. This is the + base of the PostgreSQL :class:`_postgresql.ARRAY` type, and is now part of Core to begin supporting various SQL-standard array-supporting features including some functions and eventual support for native arrays on other databases that have an "array" concept, such as DB2 or Oracle. - Additionally, new operators :func:`.expression.any_` and - :func:`.expression.all_` have been added. These support not just + Additionally, new operators :func:`_expression.any_` and + :func:`_expression.all_` have been added. These support not just array constructs on PostgreSQL, but also subqueries that are usable on MySQL (but sadly not on PostgreSQL). @@ -2590,8 +2590,8 @@ :tags: bug, postgresql :tickets: 3499 - The "hashable" flag on special datatypes such as :class:`.postgresql.ARRAY`, - :class:`.postgresql.JSON` and :class:`.postgresql.HSTORE` is now + The "hashable" flag on special datatypes such as :class:`_postgresql.ARRAY`, + :class:`_postgresql.JSON` and :class:`_postgresql.HSTORE` is now set to False, which allows these types to be fetchable in ORM queries that include entities within the row. @@ -2605,7 +2605,7 @@ :tags: bug, postgresql :tickets: 3487 - The PostgreSQL :class:`.postgresql.ARRAY` type now supports multidimensional + The PostgreSQL :class:`_postgresql.ARRAY` type now supports multidimensional indexed access, e.g. expressions such as ``somecol[5][6]`` without any need for explicit casts or type coercions, provided that the :paramref:`.postgresql.ARRAY.dimensions` parameter is set to the @@ -2619,10 +2619,10 @@ :tags: bug, postgresql :tickets: 3503 - The return type for the :class:`.postgresql.JSON` and :class:`.postgresql.JSONB` + The return type for the :class:`_postgresql.JSON` and :class:`_postgresql.JSONB` when using indexed access has been fixed to work like PostgreSQL itself, - and returns an expression that itself is of type :class:`.postgresql.JSON` - or :class:`.postgresql.JSONB`. Previously, the accessor would return + and returns an expression that itself is of type :class:`_postgresql.JSON` + or :class:`_postgresql.JSONB`. Previously, the accessor would return :class:`.NullType` which disallowed subsequent JSON-like operators to be used. @@ -2634,8 +2634,8 @@ :tags: bug, postgresql :tickets: 3503 - The :class:`.postgresql.JSON`, :class:`.postgresql.JSONB` and - :class:`.postgresql.HSTORE` datatypes now allow full control over the + The :class:`_postgresql.JSON`, :class:`_postgresql.JSONB` and + :class:`_postgresql.HSTORE` datatypes now allow full control over the return type from an indexed textual access operation, either ``column[someindex].astext`` for a JSON type or ``column[someindex]`` for an HSTORE type, via the :paramref:`.postgresql.JSON.astext_type` and @@ -2651,9 +2651,9 @@ :tickets: 3503 The :attr:`.postgresql.JSON.Comparator.astext` modifier no longer - calls upon :meth:`.ColumnElement.cast` implicitly, as PG's JSON/JSONB + calls upon :meth:`_expression.ColumnElement.cast` implicitly, as PG's JSON/JSONB types allow cross-casting between each other as well. Code that - makes use of :meth:`.ColumnElement.cast` on JSON indexed access, + makes use of :meth:`_expression.ColumnElement.cast` on JSON indexed access, e.g. ``col[someindex].cast(Integer)``, will need to be changed to call :attr:`.postgresql.JSON.Comparator.astext` explicitly. @@ -2667,8 +2667,8 @@ :tickets: 3514 Additional fixes have been made regarding the value of ``None`` - in conjunction with the PostgreSQL :class:`.postgresql.JSON` type. When - the :paramref:`.JSON.none_as_null` flag is left at its default + in conjunction with the PostgreSQL :class:`_postgresql.JSON` type. When + the :paramref:`_types.JSON.none_as_null` flag is left at its default value of ``False``, the ORM will now correctly insert the JSON "'null'" string into the column whenever the value on the ORM object is set to the value ``None`` or when the value ``None`` @@ -2697,8 +2697,8 @@ :tags: bug, sql :tickets: 2528 - The behavior of the :func:`.union` construct and related constructs - such as :meth:`.Query.union` now handle the case where the embedded + The behavior of the :func:`_expression.union` construct and related constructs + such as :meth:`_query.Query.union` now handle the case where the embedded SELECT statements need to be parenthesized due to the fact that they include LIMIT, OFFSET and/or ORDER BY. These queries **do not work on SQLite**, and will fail on that backend as they did before, but @@ -2712,9 +2712,9 @@ :tags: feature, orm :tickets: 3512 - Added new relationship loading strategy :func:`.orm.raiseload` (also + Added new relationship loading strategy :func:`_orm.raiseload` (also accessible via ``lazy='raise'``). This strategy behaves almost like - :func:`.orm.noload` but instead of returning ``None`` it raises an + :func:`_orm.noload` but instead of returning ``None`` it raises an InvalidRequestError. Pull request courtesy Adrian Moennich. .. seealso:: diff --git a/doc/build/changelog/changelog_12.rst b/doc/build/changelog/changelog_12.rst index e5c145642c..24ef4eeaf3 100644 --- a/doc/build/changelog/changelog_12.rst +++ b/doc/build/changelog/changelog_12.rst @@ -34,8 +34,8 @@ :tags: bug, oracle :tickets: 4506 - Added support for reflection of the :class:`.NCHAR` datatype to the Oracle - dialect, and added :class:`.NCHAR` to the list of types exported by the + Added support for reflection of the :class:`_types.NCHAR` datatype to the Oracle + dialect, and added :class:`_types.NCHAR` to the list of types exported by the Oracle dialect. @@ -97,8 +97,8 @@ :tags: bug, sql :tickets: 4485 - Fixed issue where the :class:`.JSON` type had a read-only - :attr:`.JSON.should_evaluate_none` attribute, which would cause failures + Fixed issue where the :class:`_types.JSON` type had a read-only + :attr:`_types.JSON.should_evaluate_none` attribute, which would cause failures when making use of the :meth:`.TypeEngine.evaluates_none` method in conjunction with this type. Pull request courtesy Sanjana S. @@ -108,8 +108,8 @@ Fixed bug where the SQL Server "IDENTITY_INSERT" logic that allows an INSERT to proceed with an explicit value on an IDENTITY column was not detecting - the case where :meth:`.Insert.values` were used with a dictionary that - contained a :class:`.Column` as key and a SQL expression as a value. + the case where :meth:`_expression.Insert.values` were used with a dictionary that + contained a :class:`_schema.Column` as key and a SQL expression as a value. .. change:: :tags: bug, sqlite @@ -142,8 +142,8 @@ Added new event hooks :meth:`.QueryEvents.before_compile_update` and :meth:`.QueryEvents.before_compile_delete` which complement - :meth:`.QueryEvents.before_compile` in the case of the :meth:`.Query.update` - and :meth:`.Query.delete` methods. + :meth:`.QueryEvents.before_compile` in the case of the :meth:`_query.Query.update` + and :meth:`_query.Query.delete` methods. .. change:: @@ -195,7 +195,7 @@ :tags: bug, postgresql :tickets: 4416 - Fixed issue where a :class:`.postgresql.ENUM` or a custom domain present + Fixed issue where a :class:`_postgresql.ENUM` or a custom domain present in a remote schema would not be recognized within column reflection if the name of the enum/domain or the name of the schema required quoting. A new parsing scheme now fully parses out quoted or non-quoted tokens @@ -204,11 +204,11 @@ .. change:: :tags: bug, postgresql - Fixed issue where multiple :class:`.postgresql.ENUM` objects referred to - by the same :class:`.MetaData` object would fail to be created if + Fixed issue where multiple :class:`_postgresql.ENUM` objects referred to + by the same :class:`_schema.MetaData` object would fail to be created if multiple objects had the same name under different schema names. The internal memoization the PostgreSQL dialect uses to track if it has - created a particular :class:`.postgresql.ENUM` in the database during + created a particular :class:`_postgresql.ENUM` in the database during a DDL creation sequence now takes schema name into account. .. change:: @@ -257,7 +257,7 @@ primaryjoin/secondaryjoin a relationship if one used the pattern ``ForeignKey(SomeClass.id)`` in the declarative mappings. This pattern would leak undesired annotations into the join conditions which can break - aliasing operations done within :class:`.Query` that are not supposed to + aliasing operations done within :class:`_query.Query` that are not supposed to impact elements in that join condition. These annotations are now removed up front if present. @@ -265,9 +265,9 @@ :tags: bug, orm, declarative :tickets: 4374 - A warning is emitted in the case that a :func:`.column` object is applied to + A warning is emitted in the case that a :func:`_expression.column` object is applied to a declarative class, as it seems likely this intended to be a - :class:`.Column` object. + :class:`_schema.Column` object. .. change:: :tags: bug, orm @@ -277,7 +277,7 @@ repaired issue with :meth:`.RelationshipProperty.Comparator.any` and :meth:`.RelationshipProperty.Comparator.has` where the "secondary" selectable needs to be explicitly part of the FROM clause in the - EXISTS subquery to suit the case where this "secondary" is a :class:`.Join` + EXISTS subquery to suit the case where this "secondary" is a :class:`_expression.Join` object. .. change:: @@ -286,9 +286,9 @@ Fixed regression caused by :ticket:`4349` where adding the "secondary" table to the FROM clause for a dynamic loader would affect the ability of - the :class:`.Query` to make a subsequent join to another entity. The fix + the :class:`_query.Query` to make a subsequent join to another entity. The fix adds the primary entity as the first element of the FROM list since - :meth:`.Query.join` wants to jump from that. Version 1.3 will have + :meth:`_query.Query.join` wants to jump from that. Version 1.3 will have a more comprehensive solution to this problem as well (:ticket:`4365`). @@ -411,7 +411,7 @@ Fixed regression caused by :ticket:`4326` in version 1.2.12 where using :class:`.declared_attr` with a mixin in conjunction with - :func:`.orm.synonym` would fail to map the synonym properly to an inherited + :func:`_orm.synonym` would fail to map the synonym properly to an inherited subclass. .. change:: @@ -453,7 +453,7 @@ :tickets: 4352 The column conflict resolution technique discussed at - :ref:`declarative_column_conflicts` is now functional for a :class:`.Column` + :ref:`declarative_column_conflicts` is now functional for a :class:`_schema.Column` that is also a primary key column. Previously, a check for primary key columns declared on a single-inheritance subclass would occur before the column copy were allowed to pass. @@ -484,8 +484,8 @@ :tags: bug, postgresql :tickets: 4324 - Fixed the :func:`.postgresql.array_agg` function, which is a slightly - altered version of the usual :func:`.functions.array_agg` function, to also + Fixed the :func:`_postgresql.array_agg` function, which is a slightly + altered version of the usual :func:`_functions.array_agg` function, to also accept an incoming "type" argument without forcing an ARRAY around it, essentially the same thing that was fixed for the generic function in 1.1 in :ticket:`4107`. @@ -517,7 +517,7 @@ not the hybrid attribute itself, when receiving the descriptor via the ``@declared_attr`` callable on a subclass of an already-mapped class. This would lead to an attribute that did not report itself as a hybrid when - viewed within :attr:`.Mapper.all_orm_descriptors`. + viewed within :attr:`_orm.Mapper.all_orm_descriptors`. .. change:: @@ -525,14 +525,14 @@ :tickets: 4334 :versions: 1.3.0b1 - Fixed bug where use of :class:`.Lateral` construct in conjunction with - :meth:`.Query.join` as well as :meth:`.Query.select_entity_from` would not + Fixed bug where use of :class:`_expression.Lateral` construct in conjunction with + :meth:`_query.Query.join` as well as :meth:`_query.Query.select_entity_from` would not apply clause adaption to the right side of the join. "lateral" introduces the use case of the right side of a join being correlatable. Previously, adaptation of this clause wasn't considered. Note that in 1.2 only, - a selectable introduced by :meth:`.Query.subquery` is still not adapted + a selectable introduced by :meth:`_query.Query.subquery` is still not adapted due to :ticket:`4304`; the selectable needs to be produced by the - :func:`~.sql.expression.select` function to be the right side of the "lateral" join. + :func:`_expression.select` function to be the right side of the "lateral" join. .. change:: :tags: bug, oracle @@ -587,7 +587,7 @@ Fixed issue that is closely related to :ticket:`3639` where an expression rendered in a boolean context on a non-native boolean backend would be compared to 1/0 even though it is already an implicitly boolean - expression, when :meth:`.ColumnElement.self_group` were used. While this + expression, when :meth:`_expression.ColumnElement.self_group` were used. While this does not affect the user-friendly backends (MySQL, SQLite) it was not handled by Oracle (and possibly SQL Server). Whether or not the expression is implicitly boolean on any database is now determined @@ -638,10 +638,10 @@ change now includes that a SELECT statement in the WHERE clause for such a statement will try to auto-correlate back to these additional tables in the parent UPDATE/DELETE or unconditionally correlate if - :meth:`.Select.correlate` is used. Note that auto-correlation raises an + :meth:`_expression.Select.correlate` is used. Note that auto-correlation raises an error if the SELECT statement would have no FROM clauses as a result, which can now occur if the parent UPDATE/DELETE specifies the same tables in its - additional set of tables; specify :meth:`.Select.correlate` explicitly to + additional set of tables; specify :meth:`_expression.Select.correlate` explicitly to resolve. .. changelog:: @@ -653,9 +653,9 @@ :tickets: 4300 Fixed bug where a :class:`.Sequence` would be dropped explicitly before any - :class:`.Table` that refers to it, which breaks in the case when the + :class:`_schema.Table` that refers to it, which breaks in the case when the sequence is also involved in a server-side default for that table, when - using :meth:`.MetaData.drop_all`. The step which processes sequences + using :meth:`_schema.MetaData.drop_all`. The step which processes sequences to be dropped via non server-side column default functions is now invoked after the table itself is dropped. @@ -673,7 +673,7 @@ :tickets: 4298 Fixed regression in 1.2.9 due to :ticket:`4287` where using a - :class:`.Load` option in conjunction with a string wildcard would result + :class:`_orm.Load` option in conjunction with a string wildcard would result in a TypeError. .. changelog:: @@ -706,10 +706,10 @@ :tags: bug, sql :tickets: 4279 - Fixed regression in 1.2 due to :ticket:`4147` where a :class:`.Table` that + Fixed regression in 1.2 due to :ticket:`4147` where a :class:`_schema.Table` that has had some of its indexed columns redefined with new ones, as would occur when overriding columns during reflection or when using - :paramref:`.Table.extend_existing`, such that the :meth:`.Table.tometadata` + :paramref:`_schema.Table.extend_existing`, such that the :meth:`_schema.Table.tometadata` method would fail when attempting to copy those indexes as they still referred to the replaced column. The copy logic now accommodates for this condition. @@ -729,7 +729,7 @@ :tickets: 3505 Fixed issue where chaining multiple join elements inside of - :meth:`.Query.join` might not correctly adapt to the previous left-hand + :meth:`_query.Query.join` might not correctly adapt to the previous left-hand side, when chaining joined inheritance classes that share the same base class. @@ -789,8 +789,8 @@ :tickets: 4243 :versions: 1.3.0b1 - Added new attribute :attr:`.Query.lazy_loaded_from` which is populated - with an :class:`.InstanceState` that is using this :class:`.Query` in + Added new attribute :attr:`_query.Query.lazy_loaded_from` which is populated + with an :class:`.InstanceState` that is using this :class:`_query.Query` in order to lazy load a relationship. The rationale for this is that it serves as a hint for the horizontal sharding feature to use, such that the identity token of the state can be used as the default identity token @@ -817,7 +817,7 @@ :tags: bug, mysql :tickets: 3645 - The :class:`.Update` construct now accommodates a :class:`.Join` object + The :class:`_expression.Update` construct now accommodates a :class:`_expression.Join` object as supported by MySQL for UPDATE..FROM. As the construct already accepted an alias object for a similar purpose, the feature of UPDATE against a non-table was already implied so this has been added. @@ -840,10 +840,10 @@ Fixed regression caused by :ticket:`4256` (itself a regression fix for :ticket:`4228`) which breaks an undocumented behavior which converted for a - non-sequence of entities passed directly to the :class:`.Query` constructor + non-sequence of entities passed directly to the :class:`_query.Query` constructor into a single-element sequence. While this behavior was never supported or documented, it's already in use so has been added as a behavioral contract - to :class:`.Query`. + to :class:`_query.Query`. .. change:: :tags: bug, orm @@ -851,13 +851,13 @@ Fixed an issue that was both a performance regression in 1.2 as well as an incorrect result regarding the "baked" lazy loader, involving the - generation of cache keys from the original :class:`.Query` object's loader + generation of cache keys from the original :class:`_query.Query` object's loader options. If the loader options were built up in a "branched" style using common base elements for multiple options, the same options would be rendered into the cache key repeatedly, causing both a performance issue as well as generating the wrong cache key. This is fixed, along with a performance improvement when such "branched" options are applied via - :meth:`.Query.options` to prevent the same option objects from being + :meth:`_query.Query.options` to prevent the same option objects from being applied repeatedly. .. change:: @@ -883,10 +883,10 @@ Fixed regression in 1.2.7 caused by :ticket:`4228`, which itself was fixing a 1.2-level regression, where the ``query_cls`` callable passed to a - :class:`.Session` was assumed to be a subclass of :class:`.Query` with + :class:`.Session` was assumed to be a subclass of :class:`_query.Query` with class method availability, as opposed to an arbitrary callable. In particular, the dogpile caching example illustrates ``query_cls`` as a - function and not a :class:`.Query` subclass. + function and not a :class:`_query.Query` subclass. .. change:: :tags: bug, engine @@ -894,10 +894,10 @@ Fixed connection pool issue whereby if a disconnection error were raised during the connection pool's "reset on return" sequence in conjunction with - an explicit transaction opened against the enclosing :class:`.Connection` + an explicit transaction opened against the enclosing :class:`_engine.Connection` object (such as from calling :meth:`.Session.close` without a rollback or - commit, or calling :meth:`.Connection.close` without first closing a - transaction declared with :meth:`.Connection.begin`), a double-checkin would + commit, or calling :meth:`_engine.Connection.close` without first closing a + transaction declared with :meth:`_engine.Connection.begin`), a double-checkin would result, which could then lead towards concurrent checkouts of the same connection. The double-checkin condition is now prevented overall by an assertion, as well as the specific double-checkin scenario has been @@ -909,8 +909,8 @@ The Oracle BINARY_FLOAT and BINARY_DOUBLE datatypes now participate within cx_Oracle.setinputsizes(), passing along NATIVE_FLOAT, so as to support the - NaN value. Additionally, :class:`.oracle.BINARY_FLOAT`, - :class:`.oracle.BINARY_DOUBLE` and :class:`.oracle.DOUBLE_PRECISION` now + NaN value. Additionally, :class:`_oracle.BINARY_FLOAT`, + :class:`_oracle.BINARY_DOUBLE` and :class:`_oracle.DOUBLE_PRECISION` now subclass :class:`.Float`, since these are floating point datatypes, not decimal. These datatypes were already defaulting the :paramref:`.Float.asdecimal` flag to False in line with what @@ -919,8 +919,8 @@ .. change:: :tags: bug, oracle - Added reflection capabilities for the :class:`.oracle.BINARY_FLOAT`, - :class:`.oracle.BINARY_DOUBLE` datatypes. + Added reflection capabilities for the :class:`_oracle.BINARY_FLOAT`, + :class:`_oracle.BINARY_DOUBLE` datatypes. .. change:: @@ -983,11 +983,11 @@ Fixed a long-standing regression that occurred in version 1.0, which prevented the use of a custom :class:`.MapperOption` - that alters the _params of a :class:`.Query` object for a + that alters the _params of a :class:`_query.Query` object for a lazy load, since the lazy loader itself would overwrite those parameters. This applies to the "temporal range" example on the wiki. Note however that the - :meth:`.Query.populate_existing` method is now required in + :meth:`_query.Query.populate_existing` method is now required in order to rewrite the mapper options associated with an object already loaded in the identity map. @@ -1093,7 +1093,7 @@ :tickets: 4160 :versions: 1.3.0b1 - Added new PG type :class:`.postgresql.REGCLASS` which assists in casting + Added new PG type :class:`_postgresql.REGCLASS` which assists in casting table names to OID values. Pull request courtesy Sebastian Bank. .. change:: @@ -1111,7 +1111,7 @@ Fixed issue in single-inheritance loading where the use of an aliased entity against a single-inheritance subclass in conjunction with the - :meth:`.Query.select_from` method would cause the SQL to be rendered with + :meth:`_query.Query.select_from` method would cause the SQL to be rendered with the unaliased table mixed in to the query, causing a cartesian product. In particular this was affecting the new "selectin" loader when used against a single-inheritance subclass. @@ -1142,7 +1142,7 @@ Fixed a regression that occurred from the previous fix to :ticket:`4204` in version 1.2.5, where a CTE that refers to itself after the - :meth:`.CTE.alias` method has been called would not refer to itself + :meth:`_expression.CTE.alias` method has been called would not refer to itself correctly. .. change:: @@ -1197,9 +1197,9 @@ :tickets: 4210 Fixed bug in :class:.`CTE` construct along the same lines as that of - :ticket:`4204` where a :class:`.CTE` that was aliased would not copy itself + :ticket:`4204` where a :class:`_expression.CTE` that was aliased would not copy itself correctly during a "clone" operation as is frequent within the ORM as well - as when using the :meth:`.ClauseElement.params` method. + as when using the :meth:`_expression.ClauseElement.params` method. .. change:: :tags: bug, orm @@ -1214,8 +1214,8 @@ :tags: bug, sql :tickets: 4204 - Fixed bug in CTE rendering where a :class:`.CTE` that was also turned into - an :class:`.Alias` would not render its "ctename AS aliasname" clause + Fixed bug in CTE rendering where a :class:`_expression.CTE` that was also turned into + an :class:`_expression.Alias` would not render its "ctename AS aliasname" clause appropriately if there were more than one reference to the CTE in a FROM clause. @@ -1233,8 +1233,8 @@ :tags: feature, orm :versions: 1.3.0b1 - Added new feature :meth:`.Query.only_return_tuples`. Causes the - :class:`.Query` object to return keyed tuple objects unconditionally even + Added new feature :meth:`_query.Query.only_return_tuples`. Causes the + :class:`_query.Query` object to return keyed tuple objects unconditionally even if the query is against a single entity. Pull request courtesy Eric Atkin. @@ -1256,7 +1256,7 @@ :tickets: 4193 Fixed 1.2 regression in ORM versioning feature where a mapping against a - :func:`~.sql.expression.select` or :func:`.alias` that also used a versioning column + :func:`_expression.select` or :func:`.alias` that also used a versioning column against the underlying table would fail due to the check added as part of :ticket:`3673`. @@ -1265,7 +1265,7 @@ :tickets: 4190 Fixed regression caused in 1.2.3 due to fix from :ticket:`4181` where - the changes to the event system involving :class:`.Engine` and + the changes to the event system involving :class:`_engine.Engine` and :class:`.OptionEngine` did not accommodate for event removals, which would raise an ``AttributeError`` when invoked at the class level. @@ -1305,7 +1305,7 @@ :tickets: 4175 Fixed bug where the :class:`.Bundle` object did not - correctly report upon the primary :class:`.Mapper` object + correctly report upon the primary :class:`_orm.Mapper` object represented by the bundle, if any. An immediate side effect of this issue was that the new selectinload loader strategy wouldn't work with the horizontal sharding @@ -1326,11 +1326,11 @@ Fixed bug where events associated with an :class:`Engine` at the class level would be doubled when the - :meth:`.Engine.execution_options` method were used. To + :meth:`_engine.Engine.execution_options` method were used. To achieve this, the semi-private class :class:`.OptionEngine` no longer accepts events directly at the class level and will raise an error; the class only propagates class-level - events from its parent :class:`.Engine`. Instance-level + events from its parent :class:`_engine.Engine`. Instance-level events continue to work as before. .. change:: @@ -1367,7 +1367,7 @@ :tags: bug, orm :tickets: 4178 - Fixed bug where the :func:`.orm.reconstructor` event + Fixed bug where the :func:`_orm.reconstructor` event helper would not be recognized if it were applied to the ``__init__()`` method of the mapped class. @@ -1587,19 +1587,19 @@ :tags: bug, sql :tickets: 4147 - Fixed bug where the :meth:`.Table.tometadata` method would not properly + Fixed bug where the :meth:`_schema.Table.tometadata` method would not properly accommodate :class:`.Index` objects that didn't consist of simple - column expressions, such as indexes against a :func:`.text` construct, + column expressions, such as indexes against a :func:`_expression.text` construct, indexes that used SQL expressions or :attr:`.func`, etc. The routine now copies expressions fully to a new :class:`.Index` object while - substituting all table-bound :class:`.Column` objects for those + substituting all table-bound :class:`_schema.Column` objects for those of the target table. .. change:: :tags: bug, sql :tickets: 4142 - Changed the "visit name" of :class:`.ColumnElement` from "column" to + Changed the "visit name" of :class:`_expression.ColumnElement` from "column" to "column_element", so that when this element is used as the basis for a user-defined SQL element, it is not assumed to behave like a table-bound :class:`.ColumnClause` when processed by various SQL traversal utilities, @@ -1609,9 +1609,9 @@ :tags: bug, sql, ext :tickets: 4141 - Fixed issue in :class:`.ARRAY` datatype which is essentially the same + Fixed issue in :class:`_types.ARRAY` datatype which is essentially the same issue as that of :ticket:`3832`, except not a regression, where - column attachment events on top of :class:`.ARRAY` would not fire + column attachment events on top of :class:`_types.ARRAY` would not fire correctly, thus interfering with systems which rely upon this. A key use case that was broken by this is the use of mixins to declare columns that make use of :meth:`.MutableList.as_mutable`. @@ -1646,7 +1646,7 @@ .. change:: :tags: feature, postgresql - Added new :class:`.postgresql.MONEY` datatype. Pull request courtesy + Added new :class:`_postgresql.MONEY` datatype. Pull request courtesy Cleber J Santos. .. change:: @@ -1701,10 +1701,10 @@ :tags: bug, orm :tickets: 4032 - The :meth:`.Query.exists` method will now disable eager loaders for when + The :meth:`_query.Query.exists` method will now disable eager loaders for when the query is rendered. Previously, joined-eager load joins would be rendered unnecessarily as well as subquery eager load queries would be needlessly - generated. The new behavior matches that of the :meth:`.Query.subquery` + generated. The new behavior matches that of the :meth:`_query.Query.subquery` method. .. changelog:: @@ -1718,7 +1718,7 @@ Added a new flag ``use_batch_mode`` to the psycopg2 dialect. This flag enables the use of psycopg2's ``psycopg2.extras.execute_batch`` - extension when the :class:`.Engine` calls upon + extension when the :class:`_engine.Engine` calls upon ``cursor.executemany()``. This extension provides a critical performance increase by over an order of magnitude when running INSERT statements in batch. The flag is False by default as it is considered @@ -1783,7 +1783,7 @@ .. change:: :tags: bug, oracle - The column keys present in a result set when using :meth:`.Insert.returning` + The column keys present in a result set when using :meth:`_expression.Insert.returning` with the cx_Oracle backend now use the correct column / label names like that of all other dialects. Previously, these came out as ``ret_nnn``. @@ -1840,7 +1840,7 @@ :tickets: 4041 Fixed bug where the pg8000 driver would fail if using - :meth:`.MetaData.reflect` with a schema name, since the schema name would + :meth:`_schema.MetaData.reflect` with a schema name, since the schema name would be sent as a "quoted_name" object that's a string subclass, which pg8000 doesn't recognize. The quoted_name type is added to pg8000's py_types collection on connect. @@ -1898,10 +1898,10 @@ :tags: feature, mssql :tickets: 4086 - Added a new :class:`.mssql.TIMESTAMP` datatype, that + Added a new :class:`_mssql.TIMESTAMP` datatype, that correctly acts like a binary datatype for SQL Server rather than a datetime type, as SQL Server breaks the - SQL standard here. Also added :class:`.mssql.ROWVERSION`, + SQL standard here. Also added :class:`_mssql.ROWVERSION`, as the "TIMESTAMP" type in SQL Server is deprecated in favor of ROWVERSION. @@ -1998,7 +1998,7 @@ :tickets: 4058 Added support for "AUTOCOMMIT" isolation level, as established - via :meth:`.Connection.execution_options`, to the + via :meth:`_engine.Connection.execution_options`, to the PyODBC and pymssql dialects. This isolation level sets the appropriate DBAPI-specific flags on the underlying connection object. @@ -2022,7 +2022,7 @@ :tickets: 4087 Fixed bug in new SQL comments feature where table and column comment - would not be copied when using :meth:`.Table.tometadata`. + would not be copied when using :meth:`_schema.Table.tometadata`. .. change:: :tags: bug, sql @@ -2064,7 +2064,7 @@ Changed the name of the ``.values`` attribute of the new MySQL INSERT..ON DUPLICATE KEY UPDATE construct to ``.inserted``, as - :class:`~.sql.expression.Insert` already has a method called :meth:`.Insert.values`. + :class:`_expression.Insert` already has a method called :meth:`_expression.Insert.values`. The ``.inserted`` attribute ultimately renders the MySQL ``VALUES()`` function. @@ -2091,9 +2091,9 @@ :class:`.Emulated` that indicates a type that provides Python-side emulation of a DB native type, switching out to the DB native type when a supporting backend is in use. The PostgreSQL - :class:`.postgresql.INTERVAL` type when used directly will now include + :class:`_postgresql.INTERVAL` type when used directly will now include the correct type coercion rules for SQL expressions that also take - effect for :class:`.sqltypes.Interval` (such as adding a date to an + effect for :class:`_types.Interval` (such as adding a date to an interval yields a datetime). @@ -2110,7 +2110,7 @@ :tags: bug, engine :tickets: 4028 - Made some adjustments to :class:`.Pool` and :class:`.Connection` such + Made some adjustments to :class:`_pool.Pool` and :class:`_engine.Connection` such that recovery logic is not run underneath exception catches for ``pool.Empty``, ``AttributeError``, since when the recovery operation itself fails, Python 3 creates a misleading stack trace referring to the @@ -2226,7 +2226,7 @@ :tags: feature, orm :tickets: 3058 - Added a new feature :func:`.orm.with_expression` that allows an ad-hoc + Added a new feature :func:`_orm.with_expression` that allows an ad-hoc SQL expression to be added to a specific entity in a query at result time. This is an alternative to the SQL expression being delivered as a separate element in the result tuple. @@ -2240,7 +2240,7 @@ :tickets: 3496 An UPDATE emitted as a result of the - :paramref:`.relationship.post_update` feature will now integrate with + :paramref:`_orm.relationship.post_update` feature will now integrate with the versioning feature to both bump the version id of the row as well as assert that the existing version number was matched. @@ -2290,10 +2290,10 @@ :tickets: 4003 The Oracle dialect now inspects unique and check constraints when using - :meth:`.Inspector.get_unique_constraints`, - :meth:`.Inspector.get_check_constraints`. + :meth:`_reflection.Inspector.get_unique_constraints`, + :meth:`_reflection.Inspector.get_check_constraints`. As Oracle does not have unique constraints that are separate from a unique - :class:`.Index`, a :class:`.Table` that's reflected will still continue + :class:`.Index`, a :class:`_schema.Table` that's reflected will still continue to not have :class:`.UniqueConstraint` objects associated with it. Pull requests courtesy Eloy Felix. @@ -2321,7 +2321,7 @@ :tickets: 3471, 3472 Repaired several use cases involving the - :paramref:`.relationship.post_update` feature when used in conjunction + :paramref:`_orm.relationship.post_update` feature when used in conjunction with a column that has an "onupdate" value. When the UPDATE emits, the corresponding object attribute is now expired or refreshed so that the newly generated "onupdate" value can populate on the object; @@ -2406,7 +2406,7 @@ :tickets: 3871 Added support for views that are unreflectable due to stale - table definitions, when calling :meth:`.MetaData.reflect`; a warning + table definitions, when calling :meth:`_schema.MetaData.reflect`; a warning is emitted for the table that cannot respond to ``DESCRIBE``, but the operation succeeds. @@ -2435,8 +2435,8 @@ :tickets: 3991 Added new argument :paramref:`.with_for_update` to the - :meth:`.Session.refresh` method. When the :meth:`.Query.with_lockmode` - method were deprecated in favor of :meth:`.Query.with_for_update`, + :meth:`.Session.refresh` method. When the :meth:`_query.Query.with_lockmode` + method were deprecated in favor of :meth:`_query.Query.with_for_update`, the :meth:`.Session.refresh` method was never updated to reflect the new option. @@ -2493,7 +2493,7 @@ values from the loaded parent objects, rather than re-stating the original query. This produces a more efficient query that is "baked" (e.g. the SQL string is cached) and also works in the - context of :meth:`.Query.yield_per`. + context of :meth:`_query.Query.yield_per`. .. seealso:: @@ -2511,13 +2511,13 @@ .. change:: :tags: bug, orm - Added warnings to the LRU "compiled cache" used by the :class:`.Mapper` + Added warnings to the LRU "compiled cache" used by the :class:`_orm.Mapper` (and ultimately will be for other ORM-based LRU caches) such that when the cache starts hitting its size limits, the application will emit a warning that this is a performance-degrading situation that may require attention. The LRU caches can reach their size limits primarily if an application is making use of an unbounded number - of :class:`.Engine` objects, which is an antipattern. Otherwise, + of :class:`_engine.Engine` objects, which is an antipattern. Otherwise, this may suggest an issue that should be brought to the SQLAlchemy developer's attention. @@ -2525,8 +2525,8 @@ :tags: bug, postgresql :tickets: 3964 - Fixed bug where the base :class:`.sqltypes.ARRAY` datatype would not - invoke the bind/result processors of :class:`.postgresql.ARRAY`. + Fixed bug where the base :class:`_types.ARRAY` datatype would not + invoke the bind/result processors of :class:`_postgresql.ARRAY`. .. change:: 3963 :tags: bug, orm @@ -2543,8 +2543,8 @@ The ``lazy="select"`` loader strategy now makes used of the :class:`.BakedQuery` query caching system in all cases. This - removes most overhead of generating a :class:`.Query` object and - running it into a :func:`~.sql.expression.select` and then string SQL statement from + removes most overhead of generating a :class:`_query.Query` object and + running it into a :func:`_expression.select` and then string SQL statement from the process of lazy-loading related collections and objects. The "baked" lazy loader has also been improved such that it can now cache in most cases where query load options are used. @@ -2559,13 +2559,13 @@ The system by which percent signs in SQL statements are "doubled" for escaping purposes has been refined. The "doubling" of percent - signs mostly associated with the :obj:`.literal_column` construct + signs mostly associated with the :obj:`_expression.literal_column` construct as well as operators like :meth:`.ColumnOperators.contains` now occurs based on the stated paramstyle of the DBAPI in use; for percent-sensitive paramstyles as are common with the PostgreSQL and MySQL drivers the doubling will occur, for others like that of SQLite it will not. This allows more database-agnostic use - of the :obj:`.literal_column` construct to be possible. + of the :obj:`_expression.literal_column` construct to be possible. .. seealso:: @@ -2577,7 +2577,7 @@ Added support for all possible "fields" identifiers when reflecting the PostgreSQL ``INTERVAL`` datatype, e.g. "YEAR", "MONTH", "DAY TO - MINUTE", etc.. In addition, the :class:`.postgresql.INTERVAL` + MINUTE", etc.. In addition, the :class:`_postgresql.INTERVAL` datatype itself now includes a new parameter :paramref:`.postgresql.INTERVAL.fields` where these qualifiers can be specified; the qualifier is also reflected back into the resulting @@ -2649,7 +2649,7 @@ :tickets: 3785 The expression used for COLLATE as rendered by the column-level - :func:`.expression.collate` and :meth:`.ColumnOperators.collate` is now + :func:`_expression.collate` and :meth:`.ColumnOperators.collate` is now quoted as an identifier when the name is case sensitive, e.g. has uppercase characters. Note that this does not impact type-level collation, which is already quoted. @@ -2662,7 +2662,7 @@ :tags: feature, orm, ext :tickets: 3229 - The :meth:`.Query.update` method can now accommodate both + The :meth:`_query.Query.update` method can now accommodate both hybrid attributes as well as composite attributes as a source of the key to be placed in the SET clause. For hybrids, an additional decorator :meth:`.hybrid_property.update_expression` @@ -2708,12 +2708,12 @@ :tags: feature, sql, postgresql, mysql, oracle :tickets: 1546 - Added support for SQL comments on :class:`.Table` and :class:`.Column` - objects, via the new :paramref:`.Table.comment` and - :paramref:`.Column.comment` arguments. The comments are included + Added support for SQL comments on :class:`_schema.Table` and :class:`_schema.Column` + objects, via the new :paramref:`_schema.Table.comment` and + :paramref:`_schema.Column.comment` arguments. The comments are included as part of DDL on table creation, either inline or via an appropriate ALTER statement, and are also reflected back within table reflection, - as well as via the :class:`.Inspector`. Supported backends currently + as well as via the :class:`_reflection.Inspector`. Supported backends currently include MySQL, PostgreSQL, and Oracle. Many thanks to Frazer McLean for a large amount of effort on this. @@ -2725,8 +2725,8 @@ :tags: feature, engine :tickets: 3919 - Added native "pessimistic disconnection" handling to the :class:`.Pool` - object. The new parameter :paramref:`.Pool.pre_ping`, available from + Added native "pessimistic disconnection" handling to the :class:`_pool.Pool` + object. The new parameter :paramref:`_pool.Pool.pre_ping`, available from the engine as :paramref:`.create_engine.pool_pre_ping`, applies an efficient form of the "pre-ping" recipe featured in the pooling documentation, which upon each connection check out, emits a simple @@ -2745,9 +2745,9 @@ :tags: bug, sql :tickets: 3939 - Fixed bug where the use of an :class:`.Alias` object in a column + Fixed bug where the use of an :class:`_expression.Alias` object in a column context would raise an argument error when it tried to group itself - into a parenthesized expression. Using :class:`.Alias` in this way + into a parenthesized expression. Using :class:`_expression.Alias` in this way is not yet a fully supported API, however it applies to some end-user recipes and may have a more prominent role in support of some future PostgreSQL features. @@ -2756,8 +2756,8 @@ :tags: bug, orm :tickets: 3366 - The "evaluate" strategy used by :meth:`.Query.update` and - :meth:`.Query.delete` can now accommodate a simple + The "evaluate" strategy used by :meth:`_query.Query.update` and + :meth:`_query.Query.delete` can now accommodate a simple object comparison from a many-to-one relationship to an instance, when the attribute names of the primary key / foreign key columns don't match the actual names of the columns. Previously this would @@ -2799,7 +2799,7 @@ :tickets: 3938 Fixed bug where in the unusual case of passing a - :class:`.Compiled` object directly to :meth:`.Connection.execute`, + :class:`.Compiled` object directly to :meth:`_engine.Connection.execute`, the dialect with which the :class:`.Compiled` object were generated was not consulted for the paramstyle of the string statement, instead assuming it would match the dialect-level paramstyle, causing @@ -2941,9 +2941,9 @@ :tags: bug, orm :tickets: 3607 - Fixed bug where :meth:`.Query.with_parent` would not work if the - :class:`.Query` were against an :func:`.aliased` construct rather than + Fixed bug where :meth:`_query.Query.with_parent` would not work if the + :class:`_query.Query` were against an :func:`.aliased` construct rather than a regular mapped class. Also adds a new parameter :paramref:`.util.with_parent.from_entity` to the standalone :func:`.util.with_parent` function as well as - :meth:`.Query.with_parent`. + :meth:`_query.Query.with_parent`. diff --git a/doc/build/changelog/changelog_13.rst b/doc/build/changelog/changelog_13.rst index f63e27c216..535cd51256 100644 --- a/doc/build/changelog/changelog_13.rst +++ b/doc/build/changelog/changelog_13.rst @@ -68,9 +68,9 @@ :tags: bug, orm :tickets: 5228 - Fixed bug in :func:`.orm.selectinload` loading option where two or more + Fixed bug in :func:`_orm.selectinload` loading option where two or more loaders that represent different relationships with the same string key - name as referenced from a single :func:`.orm.with_polymorphic` construct + name as referenced from a single :func:`_orm.with_polymorphic` construct with multiple subclass mappers would fail to invoke each subqueryload separately, instead making use of a single string-based slot that would prevent the other loaders from being invoked. @@ -81,8 +81,8 @@ :tickets: 5063 Added support for reflection of "computed" columns, which are now returned - as part of the structure returned by :meth:`.Inspector.get_columns`. - When reflecting full :class:`.Table` objects, computed columns will + as part of the structure returned by :meth:`_reflection.Inspector.get_columns`. + When reflecting full :class:`_schema.Table` objects, computed columns will be represented using the :class:`.Computed` construct. .. change:: @@ -164,11 +164,11 @@ :tickets: 5238 The string argument accepted as the first positional argument by the - :func:`.relationship` function when using the Declarative API is no longer + :func:`_orm.relationship` function when using the Declarative API is no longer interpreted using the Python ``eval()`` function; instead, the name is dot separated and the names are looked up directly in the name resolution dictionary without treating the value as a Python expression. However, - passing a string argument to the other :func:`.relationship` parameters + passing a string argument to the other :func:`_orm.relationship` parameters that necessarily must accept Python expressions will still use ``eval()``; the documentation has been clarified to ensure that there is no ambiguity that this is in use. @@ -185,11 +185,11 @@ :tags: bug, orm :tickets: 5194 - Adjusted the error message emitted by :meth:`.Query.join` when a left hand - side can't be located that the :meth:`.Query.select_from` method is the + Adjusted the error message emitted by :meth:`_query.Query.join` when a left hand + side can't be located that the :meth:`_query.Query.select_from` method is the best way to resolve the issue. Also, within the 1.3 series, used a deterministic ordering when determining the FROM clause from a given column - entity passed to :class:`.Query` so that the same expression is determined + entity passed to :class:`_query.Query` so that the same expression is determined each time. @@ -279,7 +279,7 @@ :tags: bug, mssql :tickets: 5132 - Fixed issue where the :class:`.mssql.DATETIMEOFFSET` type would not + Fixed issue where the :class:`_mssql.DATETIMEOFFSET` type would not accommodate for the ``None`` value, introduced as part of the series of fixes for this type first introduced in :ticket:`4983`, :ticket:`5045`. Additionally, added support for passing a backend-specific date formatted @@ -304,7 +304,7 @@ Fixed issue where the "schema_translate_map" feature would not work with a PostgreSQL native enumeration type (i.e. :class:`.Enum`, - :class:`.postgresql.ENUM`) in that while the "CREATE TYPE" statement would + :class:`_postgresql.ENUM`) in that while the "CREATE TYPE" statement would be emitted with the correct schema, the schema would not be rendered in the CREATE TABLE statement at the point at which the enumeration was referenced. @@ -509,20 +509,20 @@ :tags: usecase, postgresql :tickets: 5040 - Added support for prefixes to the :class:`.CTE` construct, to allow + Added support for prefixes to the :class:`_expression.CTE` construct, to allow support for Postgresql 12 "MATERIALIZED" and "NOT MATERIALIZED" phrases. Pull request courtesy Marat Sharafutdinov. .. seealso:: - :meth:`.HasCTE.cte` + :meth:`_expression.HasCTE.cte` .. change:: :tags: bug, mssql :tickets: 5045 Fixed issue where a timezone-aware ``datetime`` value being converted to - string for use as a parameter value of a :class:`.mssql.DATETIMEOFFSET` + string for use as a parameter value of a :class:`_mssql.DATETIMEOFFSET` column was omitting the fractional seconds. .. change:: @@ -541,7 +541,7 @@ :tickets: 5065 Fixed bug where usage of joined eager loading would not properly wrap the - query inside of a subquery when :meth:`.Query.group_by` were used against + query inside of a subquery when :meth:`_query.Query.group_by` were used against the query. When any kind of result-limiting approach is used, such as DISTINCT, LIMIT, OFFSET, joined eager loading embeds the row-limited query inside of a subquery so that the collection results are not impacted. For @@ -562,10 +562,10 @@ :tags: bug, sql :tickets: 5028 - Fixed bug where "distinct" keyword passed to :func:`~.sql.expression.select` would not + Fixed bug where "distinct" keyword passed to :func:`_expression.select` would not treat a string value as a "label reference" in the same way that the - :meth:`.select.distinct` does; it would instead raise unconditionally. This - keyword argument and the others passed to :func:`~.sql.expression.select` will ultimately + :meth:`_expression.select.distinct` does; it would instead raise unconditionally. This + keyword argument and the others passed to :func:`_expression.select` will ultimately be deprecated for SQLAlchemy 2.0. @@ -603,7 +603,7 @@ :tags: bug, mssql :tickets: 4983 - Repaired support for the :class:`.mssql.DATETIMEOFFSET` datatype on PyODBC, + Repaired support for the :class:`_mssql.DATETIMEOFFSET` datatype on PyODBC, by adding PyODBC-level result handlers as it does not include native support for this datatype. This includes usage of the Python 3 "timezone" tzinfo subclass in order to set up a timezone, which on Python 2 makes @@ -614,7 +614,7 @@ :tags: bug, orm :tickets: 4993 - Setting persistence-related flags on :func:`.relationship` while also + Setting persistence-related flags on :func:`_orm.relationship` while also setting viewonly=True will now emit a regular warning, as these flags do not make sense for a viewonly=True relationship. In particular, the "cascade" settings have their own warning that is generated based on the @@ -683,8 +683,8 @@ :tags: orm, usecase :tickets: 4934 - Added accessor :meth:`.Query.is_single_entity` to :class:`.Query`, which - will indicate if the results returned by this :class:`.Query` will be a + Added accessor :meth:`_query.Query.is_single_entity` to :class:`_query.Query`, which + will indicate if the results returned by this :class:`_query.Query` will be a list of ORM entities, or a tuple of entities or column expressions. SQLAlchemy hopes to improve upon the behavior of single entity / tuples in future releases such that the behavior would be explicit up front, however @@ -704,7 +704,7 @@ :tags: bug, orm :tickets: 4954 - The :paramref:`.relationship.omit_join` flag was not intended to be + The :paramref:`_orm.relationship.omit_join` flag was not intended to be manually set to True, and will now emit a warning when this occurs. The omit_join optimization is detected automatically, and the ``omit_join`` flag was only intended to disable the optimization in the hypothetical case @@ -719,7 +719,7 @@ :tags: bug, orm :tickets: 4915 - A warning is emitted if a primary key value is passed to :meth:`.Query.get` + A warning is emitted if a primary key value is passed to :meth:`_query.Query.get` that consists of None for all primary key column positions. Previously, passing a single None outside of a tuple would raise a ``TypeError`` and passing a composite None (tuple of None values) would silently pass @@ -798,7 +798,7 @@ were used later to generate a bound parameter name, in particular those used by the ORM when generating the WHERE clause for an UPDATE statement. The issue has been fixed by using an alternate ``._label`` accessor for DDL - generation that does not affect the state of the :class:`.Column`. The + generation that does not affect the state of the :class:`_schema.Column`. The accessor also bypasses the key-deduplication step as it is not necessary for DDL, the naming is now consistently ``"_"`` without any subsequent numeric symbols when used in DDL. @@ -842,7 +842,7 @@ :tags: bug, engine, postgresql :tickets: 4955 - Fixed bug in :class:`.Inspector` where the cache key generation did not + Fixed bug in :class:`_reflection.Inspector` where the cache key generation did not take into account arguments passed in the form of tuples, such as the tuple of view name styles to return for the PostgreSQL dialect. This would lead the inspector to cache too generally for a more specific set of criteria. @@ -855,15 +855,15 @@ :tags: bug, mssql :tickets: 4923 - Fixed an issue in the :meth:`.Engine.table_names` method where it would + Fixed an issue in the :meth:`_engine.Engine.table_names` method where it would feed the dialect's default schema name back into the dialect level table function, which in the case of SQL Server would interpret it as a dot-tokenized schema name as viewed by the mssql dialect, which would cause the method to fail in the case where the database username actually had a dot inside of it. In 1.3, this method is still used by the - :meth:`.MetaData.reflect` function so is a prominent codepath. In 1.4, + :meth:`_schema.MetaData.reflect` function so is a prominent codepath. In 1.4, which is the current master development branch, this issue doesn't exist, - both because :meth:`.MetaData.reflect` isn't using this method nor does the + both because :meth:`_schema.MetaData.reflect` isn't using this method nor does the method pass the default schema name explicitly. The fix nonetheless guards against the default server name value returned by the dialect from being interpreted as dot-tokenized name under any circumstances by @@ -876,14 +876,14 @@ Fixed ORM bug where a "secondary" table that referred to a selectable which in some way would refer to the local primary table would apply aliasing to both sides of the join condition when a relationship-related join, either - via :meth:`.Query.join` or by :func:`.joinedload`, were generated. The + via :meth:`_query.Query.join` or by :func:`_orm.joinedload`, were generated. The "local" side is now excluded. .. change:: :tags: usecase, sql :tickets: 4276 - Added new accessors to expressions of type :class:`.JSON` to allow for + Added new accessors to expressions of type :class:`_types.JSON` to allow for specific datatype access and comparison, covering strings, integers, numeric, boolean elements. This revises the documented approach of CASTing to string when comparing values, instead adding specific @@ -892,7 +892,7 @@ .. seealso:: - :class:`.JSON` + :class:`_types.JSON` :meth:`.JSON.Comparator.as_string` @@ -919,9 +919,9 @@ :tags: usecase, sql :tickets: 4933 - The :func:`.text` construct now supports "unique" bound parameters, which + The :func:`_expression.text` construct now supports "unique" bound parameters, which will dynamically uniquify themselves on compilation thus allowing multiple - :func:`.text` constructs with the same bound parameter names to be combined + :func:`_expression.text` constructs with the same bound parameter names to be combined together. @@ -929,13 +929,13 @@ :tags: bug, oracle :tickets: 4913 - The :class:`.sqltypes.NCHAR` datatype will now bind to the + The :class:`_types.NCHAR` datatype will now bind to the ``cx_Oracle.FIXED_NCHAR`` DBAPI data bindings when used in a bound parameter, which supplies proper comparison behavior against a - variable-length string. Previously, the :class:`.sqltypes.NCHAR` datatype + variable-length string. Previously, the :class:`_types.NCHAR` datatype would bind to ``cx_oracle.NCHAR`` which is not fixed length; the - :class:`.sqltypes.CHAR` datatype already binds to ``cx_Oracle.FIXED_CHAR`` - so it is now consistent that :class:`.sqltypes.NCHAR` binds to + :class:`_types.CHAR` datatype already binds to ``cx_Oracle.FIXED_CHAR`` + so it is now consistent that :class:`_types.NCHAR` binds to ``cx_Oracle.FIXED_NCHAR``. @@ -1056,8 +1056,8 @@ Added identifier quoting to the schema name applied to the "use" statement which is invoked when a SQL Server multipart schema name is used within a - :class:`.Table` that is being reflected, as well as for :class:`.Inspector` - methods such as :meth:`.Inspector.get_table_names`; this accommodates for + :class:`_schema.Table` that is being reflected, as well as for :class:`_reflection.Inspector` + methods such as :meth:`_reflection.Inspector.get_table_names`; this accommodates for special characters or spaces in the database name. Additionally, the "use" statement is not emitted if the current database matches the target owner database name being passed. @@ -1078,7 +1078,7 @@ Passing a plain string expression to :meth:`.Session.query` is deprecated, as all string coercions were removed in :ticket:`4481` and this one should - have been included. The :func:`.literal_column` function may be used to + have been included. The :func:`_expression.literal_column` function may be used to produce a textual column expression. .. change:: @@ -1086,7 +1086,7 @@ :tickets: 4847 Added an explicit error message for the case when objects passed to - :class:`.Table` are not :class:`.SchemaItem` objects, rather than resolving + :class:`_schema.Table` are not :class:`.SchemaItem` objects, rather than resolving to an attribute error. @@ -1131,7 +1131,7 @@ :tags: bug, orm :tickets: 4823 - Fixed bug where :class:`.Load` objects were not pickleable due to + Fixed bug where :class:`_orm.Load` objects were not pickleable due to mapper/relationship state in the internal context dictionary. These objects are now converted to picklable using similar techniques as that of other elements within the loader option system that have long been @@ -1204,7 +1204,7 @@ :meth:`.postgresql.ARRAY.Comparator.contains` and :meth:`.postgresql.ARRAY.Comparator.contained_by` would fail to function correctly for non-integer values when used against a - :class:`.postgresql.array` object, due to an erroneous assert statement. + :class:`_postgresql.array` object, due to an erroneous assert statement. .. change:: :tags: feature, engine @@ -1224,7 +1224,7 @@ constraints that were added to an exsiting table with the directive that they not be applied to existing data in the table. The PostgreSQL dictionary for CHECK constraints as returned by - :meth:`.Inspector.get_check_constraints` may include an additional entry + :meth:`_reflection.Inspector.get_check_constraints` may include an additional entry ``dialect_options`` which within will contain an entry ``"not_valid": True`` if this symbol is detected. Pull request courtesy Bill Finn. @@ -1278,7 +1278,7 @@ supersedes the previous experimental ``use_batch_mode`` flag. ``executemany_mode`` supports both the "execute batch" and "execute values" functions provided by psycopg2, the latter which is used for compiled - :func:`~.sql.expression.insert` constructs. Pull request courtesy Yuval Dinari. + :func:`_expression.insert` constructs. Pull request courtesy Yuval Dinari. .. seealso:: @@ -1293,7 +1293,7 @@ Fixed bug where :meth:`.TypeEngine.column_expression` method would not be applied to subsequent SELECT statements inside of a UNION or other - :class:`.CompoundSelect`, even though the SELECT statements are rendered at + :class:`_selectable.CompoundSelect`, even though the SELECT statements are rendered at the topmost level of the statement. New logic now differentiates between rendering the column expression, which is needed for all SELECTs in the list, vs. gathering the returned data type for the result row, which is @@ -1373,14 +1373,14 @@ :tags: usecase, mssql :tickets: 4782 - Added new :func:`.mssql.try_cast` construct for SQL Server which emits + Added new :func:`_mssql.try_cast` construct for SQL Server which emits "TRY_CAST" syntax. Pull request courtesy Leonel Atencio. .. change:: :tags: bug, orm :tickets: 4803 - Fixed bug where using :meth:`.Query.first` or a slice expression in + Fixed bug where using :meth:`_query.Query.first` or a slice expression in conjunction with a query that has an expression based "offset" applied would raise TypeError, due to an "or" conditional against "offset" that did not expect it to be a SQL expression as opposed to an integer or None. @@ -1394,8 +1394,8 @@ :tags: bug, engine :tickets: 4754 - Fixed bug where using reflection function such as :meth:`.MetaData.reflect` - with an :class:`.Engine` object that had execution options applied to it + Fixed bug where using reflection function such as :meth:`_schema.MetaData.reflect` + with an :class:`_engine.Engine` object that had execution options applied to it would fail, as the resulting :class:`.OptionEngine` proxy object failed to include a ``.engine`` attribute used within the reflection routines. @@ -1404,10 +1404,10 @@ :tickets: 4743 Fixed bug where the special logic to render "NULL" for the - :class:`.TIMESTAMP` datatype when ``nullable=True`` would not work if the + :class:`_types.TIMESTAMP` datatype when ``nullable=True`` would not work if the column's datatype were a :class:`.TypeDecorator` or a :class:`.Variant`. The logic now ensures that it unwraps down to the original - :class:`.TIMESTAMP` so that this special case NULL keyword is correctly + :class:`_types.TIMESTAMP` so that this special case NULL keyword is correctly rendered when requested. .. change:: @@ -1437,7 +1437,7 @@ :tags: orm, feature :tickets: 4736 - Added new loader option method :meth:`.Load.options` which allows loader + Added new loader option method :meth:`_orm.Load.options` which allows loader options to be constructed hierarchically, so that many sub-options can be applied to a particular path without needing to call :func:`.defaultload` many times. Thanks to Alessio Bogon for the idea. @@ -1481,7 +1481,7 @@ Fixed an issue where the :meth:`.orm._ORMJoin.join` method, which is a not-internally-used ORM-level method that exposes what is normally an - internal process of :meth:`.Query.join`, did not propagate the ``full`` and + internal process of :meth:`_query.Query.join`, did not propagate the ``full`` and ``outerjoin`` keyword arguments correctly. Pull request courtesy Denis Kataev. @@ -1532,18 +1532,18 @@ :tickets: 4756 Added support for multidimensional Postgresql array literals via nesting - the :class:`.postgresql.array` object within another one. The + the :class:`_postgresql.array` object within another one. The multidimensional array type is detected automatically. .. seealso:: - :class:`.postgresql.array` + :class:`_postgresql.array` .. change:: :tags: bug, sql, postgresql :tickets: 4760 - Fixed issue where the :class:`.array_agg` construct in combination with + Fixed issue where the :class:`_functions.array_agg` construct in combination with :meth:`.FunctionElement.filter` would not produce the correct operator precedence in combination with the array index operator. @@ -1553,10 +1553,10 @@ :tickets: 4747 Fixed an unlikely issue where the "corresponding column" routine for unions - and other :class:`.CompoundSelect` objects could return the wrong column in + and other :class:`_selectable.CompoundSelect` objects could return the wrong column in some overlapping column situtations, thus potentially impacting some ORM operations when set operations are in use, if the underlying - :func:`~.sql.expression.select` constructs were used previously in other similar kinds of + :func:`_expression.select` constructs were used previously in other similar kinds of routines, due to a cached value not being cleared. .. change:: @@ -1607,8 +1607,8 @@ :tags: bug, orm :tickets: 4729 - Fixed bug where the :attr:`.Mapper.all_orm_descriptors` accessor would - return an entry for the :class:`.Mapper` itself under the declarative + Fixed bug where the :attr:`_orm.Mapper.all_orm_descriptors` accessor would + return an entry for the :class:`_orm.Mapper` itself under the declarative ``__mapper___`` key, when this is not a descriptor. The ``.is_attribute`` flag that's present on all :class:`.InspectionAttr` objects is now consulted, which has also been modified to be ``True`` for an association @@ -1618,7 +1618,7 @@ :tags: bug, orm :tickets: 4704 - Fixed regression in :meth:`.Query.join` where the ``aliased=True`` flag + Fixed regression in :meth:`_query.Query.join` where the ``aliased=True`` flag would not properly apply clause adaptation to filter criteria, if a previous join were made to the same entity. This is because the adapters were placed in the wrong order. The order has been reversed so that the @@ -1673,15 +1673,15 @@ :tickets: 4730 Fixed a series of quoting issues which all stemmed from the concept of the - :func:`.literal_column` construct, which when being "proxied" through a + :func:`_expression.literal_column` construct, which when being "proxied" through a subquery to be referred towards by a label that matches its text, the label would not have quoting rules applied to it, even if the string in the :class:`.Label` were set up as a :class:`.quoted_name` construct. Not applying quoting to the text of the :class:`.Label` is a bug because this text is strictly a SQL identifier name and not a SQL expression, and the string should not have quotes embedded into it already unlike the - :func:`.literal_column` which it may be applied towards. The existing - behavior of a non-labeled :func:`.literal_column` being propagated as is on + :func:`_expression.literal_column` which it may be applied towards. The existing + behavior of a non-labeled :func:`_expression.literal_column` being propagated as is on the outside of a subquery is maintained in order to help with manual quoting schemes, although it's not clear if valid SQL can be generated for such a construct in any case. @@ -1860,9 +1860,9 @@ :tickets: 4585 Fixed behavioral regression as a result of deprecating the "use_threadlocal" - flag for :class:`.Pool`, where the :class:`.SingletonThreadPool` no longer + flag for :class:`_pool.Pool`, where the :class:`.SingletonThreadPool` no longer makes use of this option which causes the "rollback on return" logic to take - place when the same :class:`.Engine` is used multiple times in the context + place when the same :class:`_engine.Engine` is used multiple times in the context of a transaction to connect or implicitly execute, thereby cancelling the transaction. While this is not the recommended way to work with engines and connections, it is nonetheless a confusing behavioral change as when @@ -1878,11 +1878,11 @@ :tickets: 4584 Fixed 1.3 regression in new "ambiguous FROMs" query logic introduced in - :ref:`change_4365` where a :class:`.Query` that explicitly places an entity - in the FROM clause with :meth:`.Query.select_from` and also joins to it - using :meth:`.Query.join` would later cause an "ambiguous FROM" error if + :ref:`change_4365` where a :class:`_query.Query` that explicitly places an entity + in the FROM clause with :meth:`_query.Query.select_from` and also joins to it + using :meth:`_query.Query.join` would later cause an "ambiguous FROM" error if that entity were used in additional joins, as the entity appears twice in - the "from" list of the :class:`.Query`. The fix resolves this ambiguity by + the "from" list of the :class:`_query.Query`. The fix resolves this ambiguity by folding the standalone entity into the join that it's already a part of in the same way that ultimately happens when the SELECT statement is rendered. @@ -1904,14 +1904,14 @@ :tags: bug, orm :tickets: 4606 - Adjusted the :meth:`.Query.filter_by` method to not call :func:`.and()` + Adjusted the :meth:`_query.Query.filter_by` method to not call :func:`.and()` internally against multiple criteria, instead passing it off to - :meth:`.Query.filter` as a series of criteria, instead of a single criteria. - This allows :meth:`.Query.filter_by` to defer to :meth:`.Query.filter`'s + :meth:`_query.Query.filter` as a series of criteria, instead of a single criteria. + This allows :meth:`_query.Query.filter_by` to defer to :meth:`_query.Query.filter`'s treatment of variable numbers of clauses, including the case where the list - is empty. In this case, the :class:`.Query` object will not have a + is empty. In this case, the :class:`_query.Query` object will not have a ``.whereclause``, which allows subsequent "no whereclause" methods like - :meth:`.Query.select_from` to behave consistently. + :meth:`_query.Query.select_from` to behave consistently. .. change:: :tags: bug, mssql @@ -1945,7 +1945,7 @@ :tickets: 4550 Modified the :paramref:`.Select.with_for_update.of` parameter so that if a - join or other composed selectable is passed, the individual :class:`.Table` + join or other composed selectable is passed, the individual :class:`_schema.Table` objects will be filtered from it, allowing one to pass a join() object to the parameter, as occurs normally when using joined table inheritance with the ORM. Pull request courtesy Raymond Lu. @@ -1983,7 +1983,7 @@ Fixed bug where use of :func:`.with_polymorphic` or other aliased construct would not properly adapt when the aliased target were used as the - :meth:`.Select.correlate_except` target of a subquery used inside of a + :meth:`_expression.Select.correlate_except` target of a subquery used inside of a :func:`.column_property`. This required a fix to the clause adaption mechanics to properly handle a selectable that shows up in the "correlate except" list, in a similar manner as which occurs for selectables that show @@ -2029,12 +2029,12 @@ :tags: feature, schema :tickets: 4517 - Added new parameters :paramref:`.Table.resolve_fks` and + Added new parameters :paramref:`_schema.Table.resolve_fks` and :paramref:`.MetaData.reflect.resolve_fks` which when set to False will disable the automatic reflection of related tables encountered in - :class:`.ForeignKey` objects, which can both reduce SQL overhead for omitted + :class:`_schema.ForeignKey` objects, which can both reduce SQL overhead for omitted tables as well as avoid tables that can't be reflected for database-specific - reasons. Two :class:`.Table` objects present in the same :class:`.MetaData` + reasons. Two :class:`_schema.Table` objects present in the same :class:`_schema.MetaData` collection can still refer to each other even if the reflection of the two tables occurred separately. @@ -2043,7 +2043,7 @@ :tags: feature, orm :tickets: 4316 - The :meth:`.Query.get` method can now accept a dictionary of attribute keys + The :meth:`_query.Query.get` method can now accept a dictionary of attribute keys and values as a means of indicating the primary key value to load; is particularly useful for composite primary keys. Pull request courtesy Sanjana S. @@ -2063,8 +2063,8 @@ :tags: bug, sql :tickets: 4509 - The :class:`.Alias` class and related subclasses :class:`.CTE`, - :class:`.Lateral` and :class:`.TableSample` have been reworked so that it is + The :class:`_expression.Alias` class and related subclasses :class:`_expression.CTE`, + :class:`_expression.Lateral` and :class:`_expression.TableSample` have been reworked so that it is not possible for a user to construct the objects directly. These constructs require that the standalone construction function or selectable-bound method be used to instantiate new objects. @@ -2116,9 +2116,9 @@ :tags: bug, orm :tickets: 4469 - Improved the behavior of :func:`.orm.with_polymorphic` in conjunction with + Improved the behavior of :func:`_orm.with_polymorphic` in conjunction with loader options, in particular wildcard operations as well as - :func:`.orm.load_only`. The polymorphic object will be more accurately + :func:`_orm.load_only`. The polymorphic object will be more accurately targeted so that column-level options on the entity will correctly take effect.The issue is a continuation of the same kinds of things fixed in :ticket:`4468`. @@ -2129,7 +2129,7 @@ :tickets: 4481 Fully removed the behavior of strings passed directly as components of a - :func:`~.sql.expression.select` or :class:`.Query` object being coerced to :func:`.text` + :func:`_expression.select` or :class:`_query.Query` object being coerced to :func:`_expression.text` constructs automatically; the warning that has been emitted is now an ArgumentError or in the case of order_by() / group_by() a CompileError. This has emitted a warning since version 1.0 however its presence continues @@ -2148,7 +2148,7 @@ :tickets: 4467 Quoting is applied to :class:`.Function` names, those which are usually but - not necessarily generated from the :attr:`.sql.func` construct, at compile + not necessarily generated from the :attr:`_expression.func` construct, at compile time if they contain illegal characters, such as spaces or punctuation. The names are as before treated as case insensitive however, meaning if the names contain uppercase or mixed case characters, that alone does not @@ -2161,10 +2161,10 @@ :tickets: 4481 Added "SQL phrase validation" to key DDL phrases that are accepted as plain - strings, including :paramref:`.ForeignKeyConstraint.on_delete`, - :paramref:`.ForeignKeyConstraint.on_update`, + strings, including :paramref:`_schema.ForeignKeyConstraint.on_delete`, + :paramref:`_schema.ForeignKeyConstraint.on_update`, :paramref:`.ExcludeConstraint.using`, - :paramref:`.ForeignKeyConstraint.initially`, for areas where a series of SQL + :paramref:`_schema.ForeignKeyConstraint.initially`, for areas where a series of SQL keywords only are expected.Any non-space characters that suggest the phrase would need to be quoted will raise a :class:`.CompileError`. This change is related to the series of changes committed as part of :ticket:`4481`. @@ -2229,7 +2229,7 @@ :tickets: 4423 Implemented a new feature whereby the :class:`.AliasedClass` construct can - now be used as the target of a :func:`.relationship`. This allows the + now be used as the target of a :func:`_orm.relationship`. This allows the concept of "non primary mappers" to no longer be necessary, as the :class:`.AliasedClass` is much easier to configure and automatically inherits all the relationships of the mapped class, as well as preserves the @@ -2275,9 +2275,9 @@ Added new :meth:`.MapperEvents.before_mapper_configured` event. This event complements the other "configure" stage mapper events with a per - mapper event that receives each :class:`.Mapper` right before its + mapper event that receives each :class:`_orm.Mapper` right before its configure step, and additionally may be used to prevent or delay the - configuration of specific :class:`.Mapper` objects using a new + configuration of specific :class:`_orm.Mapper` objects using a new return value :attr:`.orm.interfaces.EXT_SKIP`. See the documentation link for an example. @@ -2312,9 +2312,9 @@ :tickets: 4464 Added accessors for execution options to Core and ORM, via - :meth:`.Query.get_execution_options`, - :meth:`.Connection.get_execution_options`, - :meth:`.Engine.get_execution_options`, and + :meth:`_query.Query.get_execution_options`, + :meth:`_engine.Connection.get_execution_options`, + :meth:`_engine.Engine.get_execution_options`, and :meth:`.Executable.get_execution_options`. PR courtesy Daniel Lister. .. change:: @@ -2359,7 +2359,7 @@ The "threadlocal" engine strategy which has been a legacy feature of SQLAlchemy since around version 0.2 is now deprecated, along with the - :paramref:`.Pool.threadlocal` parameter of :class:`.Pool` which has no + :paramref:`_pool.Pool.threadlocal` parameter of :class:`_pool.Pool` which has no effect in most modern use cases. .. seealso:: @@ -2515,7 +2515,7 @@ :tickets: 3850 Added support for SQLite's json functionality via the new - SQLite implementation for :class:`.types.JSON`, :class:`.sqlite.JSON`. + SQLite implementation for :class:`_types.JSON`, :class:`_sqlite.JSON`. The name used for the type is ``JSON``, following an example found at SQLite's own documentation. Pull request courtesy Ilja Everilä. @@ -2629,7 +2629,7 @@ Implemented the SQLite ``ON CONFLICT`` clause as understood at the DDL level, e.g. for primary key, unique, and CHECK constraints as well as - specified on a :class:`.Column` to satisfy inline primary key and NOT NULL. + specified on a :class:`_schema.Column` to satisfy inline primary key and NOT NULL. Pull request courtesy Denis Kataev. .. seealso:: @@ -2679,15 +2679,15 @@ :tags: bug, orm :tickets: 4365 - Refactored :meth:`.Query.join` to further clarify the individual components + Refactored :meth:`_query.Query.join` to further clarify the individual components of structuring the join. This refactor adds the ability for - :meth:`.Query.join` to determine the most appropriate "left" side of the + :meth:`_query.Query.join` to determine the most appropriate "left" side of the join when there is more than one element in the FROM list or the query is against multiple entities. If more than one FROM/entity matches, an error is raised that asks for an ON clause to be specified to resolve the ambiguity. In particular this targets the regression we saw in :ticket:`4363` but is also of general use. The codepaths within - :meth:`.Query.join` are now easier to follow and the error cases are + :meth:`_query.Query.join` are now easier to follow and the error cases are decided more specifically at an earlier point in the operation. .. seealso:: @@ -2715,20 +2715,20 @@ :tags: bug, orm :tickets: 4304 - Fixed long-standing issue in :class:`.Query` where a scalar subquery such - as produced by :meth:`.Query.exists`, :meth:`.Query.as_scalar` and other - derivations from :attr:`.Query.statement` would not correctly be adapted - when used in a new :class:`.Query` that required entity adaptation, such as + Fixed long-standing issue in :class:`_query.Query` where a scalar subquery such + as produced by :meth:`_query.Query.exists`, :meth:`_query.Query.as_scalar` and other + derivations from :attr:`_query.Query.statement` would not correctly be adapted + when used in a new :class:`_query.Query` that required entity adaptation, such as when the query were turned into a union, or a from_self(), etc. The change - removes the "no adaptation" annotation from the :func:`~.sql.expression.select` object - produced by the :attr:`.Query.statement` accessor. + removes the "no adaptation" annotation from the :func:`_expression.select` object + produced by the :attr:`_query.Query.statement` accessor. .. change:: :tags: bug, orm, declarative :tickets: 4133 Fixed bug where declarative would not update the state of the - :class:`.Mapper` as far as what attributes were present, when additional + :class:`_orm.Mapper` as far as what attributes were present, when additional attributes were added or removed after the mapper attribute collections had already been called and memoized. Additionally, a ``NotImplementedError`` is now raised if a fully mapped attribute (e.g. column, relationship, etc.) @@ -2830,10 +2830,10 @@ :tags: feature, ext :tickets: 4196 - Added support for bulk :meth:`.Query.update` and :meth:`.Query.delete` + Added support for bulk :meth:`_query.Query.update` and :meth:`_query.Query.delete` to the :class:`.ShardedQuery` class within the horizontal sharding extension. This also adds an additional expansion hook to the - bulk update/delete methods :meth:`.Query._execute_crud`. + bulk update/delete methods :meth:`_query.Query._execute_crud`. .. seealso:: @@ -2874,7 +2874,7 @@ one-to-many load, where it instead relies loads only from the related table, relying upon the foreign key columns of the related table in order to match up to primary keys in the parent table. This optimization can be - disabled by setting the :paramref:`.relationship.omit_join` flag to False. + disabled by setting the :paramref:`_orm.relationship.omit_join` flag to False. Many thanks to Jayson Reis for the efforts on this. .. seealso:: @@ -2906,7 +2906,7 @@ :tickets: 4257 Added ``.info`` dictionary to the :class:`.InstanceState` class, the object - that comes from calling :func:`.inspect` on a mapped object. + that comes from calling :func:`_sa.inspect` on a mapped object. .. seealso:: diff --git a/doc/build/changelog/migration_08.rst b/doc/build/changelog/migration_08.rst index b707a912ca..0ced6ce853 100644 --- a/doc/build/changelog/migration_08.rst +++ b/doc/build/changelog/migration_08.rst @@ -55,15 +55,14 @@ New ORM Features .. _feature_relationship_08: -Rewritten :func:`.relationship` mechanics ------------------------------------------ - +Rewritten :func:`_orm.relationship` mechanics +---------------------------------------------- 0.8 features a much improved and capable system regarding -how :func:`.relationship` determines how to join between two +how :func:`_orm.relationship` determines how to join between two entities. The new system includes these features: * The ``primaryjoin`` argument is **no longer needed** when - constructing a :func:`.relationship` against a class that + constructing a :func:`_orm.relationship` against a class that has multiple foreign key paths to the target. Only the ``foreign_keys`` argument is needed to specify those columns which should be included: @@ -158,7 +157,7 @@ entities. The new system includes these features: remote_side=ip_address ) - The new :func:`.relationship` mechanics make use of a + The new :func:`_orm.relationship` mechanics make use of a SQLAlchemy concept known as :term:`annotations`. These annotations are also available to application code explicitly via the :func:`.foreign` and :func:`.remote` functions, either @@ -185,7 +184,7 @@ entities. The new system includes these features: .. seealso:: - :ref:`relationship_configure_joins` - a newly revised section on :func:`.relationship` + :ref:`relationship_configure_joins` - a newly revised section on :func:`_orm.relationship` detailing the latest techniques for customizing related attributes and collection access. @@ -204,7 +203,7 @@ typically for the purpose of building data-marshalling systems, like JSON/XML conversion schemes and of course form libraries galore. -Originally, the :class:`.Table` and :class:`.Column` model were the +Originally, the :class:`_schema.Table` and :class:`_schema.Column` model were the original inspection points, which have a well-documented system. While SQLAlchemy ORM models are also fully introspectable, this has never been a fully stable and @@ -215,11 +214,11 @@ how to get at this information. documented API for this purpose, including an inspection system which works on mapped classes, instances, attributes, and other Core and ORM constructs. The entrypoint to this -system is the core-level :func:`.inspect` function. +system is the core-level :func:`_sa.inspect` function. In most cases, the object being inspected is one already part of SQLAlchemy's system, -such as :class:`.Mapper`, :class:`.InstanceState`, -:class:`.Inspector`. In some cases, new objects have been +such as :class:`_orm.Mapper`, :class:`.InstanceState`, +:class:`_reflection.Inspector`. In some cases, new objects have been added with the job of providing the inspection API in certain contexts, such as :class:`.AliasedInsp` and :class:`.AttributeState`. @@ -341,7 +340,7 @@ A walkthrough of some key capabilities follows:: New with_polymorphic() feature, can be used anywhere ---------------------------------------------------- -The :meth:`.Query.with_polymorphic` method allows the user to +The :meth:`_query.Query.with_polymorphic` method allows the user to specify which tables should be present when querying against a joined-table entity. Unfortunately the method is awkward and only applies to the first entity in the list, and @@ -372,7 +371,7 @@ of_type() works with alias(), with_polymorphic(), any(), has(), joinedload(), su The :meth:`.PropComparator.of_type` method is used to specify a specific subtype to use when constructing SQL expressions along -a :func:`.relationship` that has a :term:`polymorphic` mapping as its target. +a :func:`_orm.relationship` that has a :term:`polymorphic` mapping as its target. This method can now be used to target *any number* of target subtypes, by combining it with the new :func:`.with_polymorphic` function:: @@ -384,7 +383,7 @@ by combining it with the new :func:`.with_polymorphic` function:: The method now works equally well in most places a regular relationship attribute is accepted, including with loader functions like -:func:`.joinedload`, :func:`.subqueryload`, :func:`.contains_eager`, +:func:`_orm.joinedload`, :func:`.subqueryload`, :func:`.contains_eager`, and comparison methods like :meth:`.PropComparator.any` and :meth:`.PropComparator.has`:: @@ -509,11 +508,11 @@ in one step: ORM Classes Now Accepted by Core Constructs ------------------------------------------- -While the SQL expressions used with :meth:`.Query.filter`, +While the SQL expressions used with :meth:`_query.Query.filter`, such as ``User.id == 5``, have always been compatible for -use with core constructs such as :func:`~.sql.expression.select`, the mapped -class itself would not be recognized when passed to :func:`~.sql.expression.select`, -:meth:`.Select.select_from`, or :meth:`.Select.correlate`. +use with core constructs such as :func:`_expression.select`, the mapped +class itself would not be recognized when passed to :func:`_expression.select`, +:meth:`_expression.Select.select_from`, or :meth:`_expression.Select.correlate`. A new SQL registration system allows a mapped class to be accepted as a FROM clause within the core:: @@ -522,7 +521,7 @@ accepted as a FROM clause within the core:: stmt = select([User]).where(User.id == 5) Above, the mapped ``User`` class will expand into -the :class:`.Table` to which ``User`` is mapped. +the :class:`_schema.Table` to which ``User`` is mapped. :ticket:`2245` @@ -634,7 +633,7 @@ not really a column, CAST operator, or SQL function that really drives what kinds of operations are present, it's the *type* of the expression. The implementation details are minimal - only a few extra methods are added to the core -:class:`.ColumnElement` type so that it consults its +:class:`_expression.ColumnElement` type so that it consults its :class:`.TypeEngine` object for an optional set of operators. New or revised operations can be associated with any type, either via subclassing of an existing type, by using @@ -690,7 +689,7 @@ as more string, integer and date operators. Multiple-VALUES support for Insert ---------------------------------- -The :meth:`.Insert.values` method now supports a list of dictionaries, +The :meth:`_expression.Insert.values` method now supports a list of dictionaries, which will render a multi-VALUES statement such as ``VALUES (), (), ...``. This is only relevant to backends which support this syntax, including PostgreSQL, SQLite, and MySQL. It is @@ -705,7 +704,7 @@ remains unchanged:: .. seealso:: - :meth:`.Insert.values` + :meth:`_expression.Insert.values` :ticket:`2623` @@ -757,9 +756,9 @@ to embed PostGIS expressions inline in SQL based on type rules. Core Inspection System ---------------------- -The :func:`.inspect` function introduced in :ref:`feature_orminspection_08` -also applies to the core. Applied to an :class:`.Engine` it produces -an :class:`.Inspector` object:: +The :func:`_sa.inspect` function introduced in :ref:`feature_orminspection_08` +also applies to the core. Applied to an :class:`_engine.Engine` it produces +an :class:`_reflection.Inspector` object:: from sqlalchemy import inspect from sqlalchemy import create_engine @@ -768,16 +767,15 @@ an :class:`.Inspector` object:: insp = inspect(engine) print(insp.get_table_names()) -It can also be applied to any :class:`.ClauseElement`, which returns -the :class:`.ClauseElement` itself, such as :class:`.Table`, :class:`.Column`, -:class:`.Select`, etc. This allows it to work fluently between Core +It can also be applied to any :class:`_expression.ClauseElement`, which returns +the :class:`_expression.ClauseElement` itself, such as :class:`_schema.Table`, :class:`_schema.Column`, +:class:`_expression.Select`, etc. This allows it to work fluently between Core and ORM constructs. -New Method :meth:`.Select.correlate_except` -------------------------------------------- - -:func:`~.sql.expression.select` now has a method :meth:`.Select.correlate_except` +New Method :meth:`_expression.Select.correlate_except` +------------------------------------------------------- +:func:`_expression.select` now has a method :meth:`_expression.Select.correlate_except` which specifies "correlate on all FROM clauses except those specified". It can be used for mapping scenarios where a related subquery should correlate normally, except @@ -804,13 +802,13 @@ against a particular target selectable:: .. seealso:: - :meth:`.Select.correlate_except` + :meth:`_expression.Select.correlate_except` PostgreSQL HSTORE type ---------------------- Support for PostgreSQL's ``HSTORE`` type is now available as -:class:`.postgresql.HSTORE`. This type makes great usage +:class:`_postgresql.HSTORE`. This type makes great usage of the new operator system to provide a full range of operators for HSTORE types, including index access, concatenation, and containment methods such as @@ -836,16 +834,16 @@ and containment methods such as .. seealso:: - :class:`.postgresql.HSTORE` + :class:`_postgresql.HSTORE` - :class:`.postgresql.hstore` + :class:`_postgresql.hstore` :ticket:`2606` Enhanced PostgreSQL ARRAY type ------------------------------ -The :class:`.postgresql.ARRAY` type will accept an optional +The :class:`_postgresql.ARRAY` type will accept an optional "dimension" argument, pinning it to a fixed number of dimensions and greatly improving efficiency when retrieving results: @@ -895,9 +893,9 @@ array concatenation, where below, the right side ``[4, 5, 6]`` is coerced into a .. seealso:: - :class:`.postgresql.ARRAY` + :class:`_postgresql.ARRAY` - :class:`.postgresql.array` + :class:`_postgresql.array` :ticket:`2441` @@ -933,11 +931,11 @@ Huge thanks to Nate Dub for the sprinting on this at Pycon 2012. .. seealso:: - :class:`.sqlite.DATETIME` + :class:`_sqlite.DATETIME` - :class:`.sqlite.DATE` + :class:`_sqlite.DATE` - :class:`.sqlite.TIME` + :class:`_sqlite.TIME` :ticket:`2363` @@ -946,7 +944,7 @@ Huge thanks to Nate Dub for the sprinting on this at Pycon 2012. The "collate" keyword, long accepted by the MySQL dialect, is now established on all :class:`.String` types and will render on any backend, including -when features such as :meth:`.MetaData.create_all` and :func:`.cast` is used:: +when features such as :meth:`_schema.MetaData.create_all` and :func:`.cast` is used:: >>> stmt = select([cast(sometable.c.somechar, String(20, collation='utf8'))]) >>> print(stmt) @@ -959,9 +957,8 @@ when features such as :meth:`.MetaData.create_all` and :func:`.cast` is used:: :ticket:`2276` -"Prefixes" now supported for :func:`.update`, :func:`.delete` ----------------------------------------------------------------------------- - +"Prefixes" now supported for :func:`_expression.update`, :func:`_expression.delete` +------------------------------------------------------------------------------------ Geared towards MySQL, a "prefix" can be rendered within any of these constructs. E.g.:: @@ -971,19 +968,19 @@ these constructs. E.g.:: stmt = table.update().prefix_with("LOW_PRIORITY", dialect="mysql") The method is new in addition to those which already existed -on :func:`~.sql.expression.insert`, :func:`~.sql.expression.select` and :class:`.Query`. +on :func:`_expression.insert`, :func:`_expression.select` and :class:`_query.Query`. .. seealso:: - :meth:`.Update.prefix_with` + :meth:`_expression.Update.prefix_with` - :meth:`.Delete.prefix_with` + :meth:`_expression.Delete.prefix_with` - :meth:`.Insert.prefix_with` + :meth:`_expression.Insert.prefix_with` - :meth:`.Select.prefix_with` + :meth:`_expression.Select.prefix_with` - :meth:`.Query.prefix_with` + :meth:`_query.Query.prefix_with` :ticket:`2431` @@ -1003,7 +1000,7 @@ such that an object that's "pending", meaning that it's associated with a :class:`.Session` but hasn't been inserted into the database yet, is automatically expunged from the :class:`.Session` when it becomes an "orphan", which means it has been de-associated with a parent object that refers to it -with ``delete-orphan`` cascade on the configured :func:`.relationship`. This +with ``delete-orphan`` cascade on the configured :func:`_orm.relationship`. This behavior is intended to approximately mirror the behavior of a persistent (that is, already inserted) object, where the ORM will emit a DELETE for such objects that become orphans based on the interception of detachment events. @@ -1039,7 +1036,7 @@ omission which should be silently skipped - silently skipping the INSERT here wo make user errors of this nature very hard to debug. The old behavior, for applications that might have been relying upon it, can be re-enabled for -any :class:`.Mapper` by specifying the flag ``legacy_is_orphan`` as a mapper +any :class:`_orm.Mapper` by specifying the flag ``legacy_is_orphan`` as a mapper option. The new behavior allows the following test case to work:: @@ -1143,7 +1140,7 @@ use cases should use the new "before_attach" event: Query now auto-correlates like a select() does ---------------------------------------------- -Previously it was necessary to call :meth:`.Query.correlate` in +Previously it was necessary to call :meth:`_query.Query.correlate` in order to have a column- or WHERE-subquery correlate to the parent: @@ -1178,7 +1175,7 @@ Correlation is now always context-specific ------------------------------------------ To allow a wider variety of correlation scenarios, the behavior of -:meth:`.Select.correlate` and :meth:`.Query.correlate` has changed slightly +:meth:`_expression.Select.correlate` and :meth:`_query.Query.correlate` has changed slightly such that the SELECT statement will omit the "correlated" target from the FROM clause only if the statement is actually used in that context. Additionally, it's no longer possible for a SELECT statement that's placed as a FROM @@ -1230,8 +1227,8 @@ SELECT used in a non-correlating context would see any change. create_all() and drop_all() will now honor an empty list as such ---------------------------------------------------------------- -The methods :meth:`.MetaData.create_all` and :meth:`.MetaData.drop_all` -will now accept a list of :class:`.Table` objects that is empty, +The methods :meth:`_schema.MetaData.create_all` and :meth:`_schema.MetaData.drop_all` +will now accept a list of :class:`_schema.Table` objects that is empty, and will not emit any CREATE or DROP statements. Previously, an empty list was interpreted the same as passing ``None`` for a collection, and CREATE/DROP would be emitted for all @@ -1297,12 +1294,11 @@ be no pending state change on an unloaded attribute. :ticket:`2320` -:attr:`.Column.key` is honored in the :attr:`.Select.c` attribute of :func:`~.sql.expression.select` with :meth:`.Select.apply_labels` +:attr:`_schema.Column.key` is honored in the :attr:`_expression.Select.c` attribute of :func:`_expression.select` with :meth:`_expression.Select.apply_labels` --------------------------------------------------------------------------------------------------------------------------------------------------------------- - -Users of the expression system know that :meth:`.Select.apply_labels` +Users of the expression system know that :meth:`_expression.Select.apply_labels` prepends the table name to each column name, affecting the -names that are available from :attr:`.Select.c`: +names that are available from :attr:`_expression.Select.c`: :: @@ -1310,9 +1306,9 @@ names that are available from :attr:`.Select.c`: s.c.table1_col1 s.c.table1_col2 -Before 0.8, if the :class:`.Column` had a different :attr:`.Column.key`, this +Before 0.8, if the :class:`_schema.Column` had a different :attr:`_schema.Column.key`, this key would be ignored, inconsistently versus when -:meth:`.Select.apply_labels` were not used: +:meth:`_expression.Select.apply_labels` were not used: :: @@ -1328,7 +1324,7 @@ key would be ignored, inconsistently versus when s.c.table1_column_one # would raise AttributeError s.c.table1_col1 # would be accessible like this -In 0.8, :attr:`.Column.key` is honored in both cases: +In 0.8, :attr:`_schema.Column.key` is honored in both cases: :: @@ -1347,16 +1343,16 @@ In 0.8, :attr:`.Column.key` is honored in both cases: All other behavior regarding "name" and "key" are the same, including that the rendered SQL will still use the form ``_`` - the emphasis here was on -preventing the :attr:`.Column.key` contents from being rendered into the +preventing the :attr:`_schema.Column.key` contents from being rendered into the ``SELECT`` statement so that there are no issues with -special/ non-ascii characters used in the :attr:`.Column.key`. +special/ non-ascii characters used in the :attr:`_schema.Column.key`. :ticket:`2397` single_parent warning is now an error ------------------------------------- -A :func:`.relationship` that is many-to-one or many-to-many and +A :func:`_orm.relationship` that is many-to-one or many-to-many and specifies "cascade='all, delete-orphan'", which is an awkward but nonetheless supported use case (with restrictions) will now raise an error if the relationship diff --git a/doc/build/changelog/migration_09.rst b/doc/build/changelog/migration_09.rst index df4a2c57f9..b73e784ea7 100644 --- a/doc/build/changelog/migration_09.rst +++ b/doc/build/changelog/migration_09.rst @@ -56,7 +56,7 @@ Behavioral Changes - ORM Composite attributes are now returned as their object form when queried on a per-attribute basis ------------------------------------------------------------------------------------------------ -Using a :class:`.Query` in conjunction with a composite attribute now returns the object +Using a :class:`_query.Query` in conjunction with a composite attribute now returns the object type maintained by that composite, rather than being broken out into individual columns. Using the mapping setup at :ref:`mapper_composite`:: @@ -82,11 +82,10 @@ accessor:: .. _migration_2736: -:meth:`.Query.select_from` no longer applies the clause to corresponding entities ------------------------------------------------------------------------------------------------ - -The :meth:`.Query.select_from` method has been popularized in recent versions -as a means of controlling the first thing that a :class:`.Query` object +:meth:`_query.Query.select_from` no longer applies the clause to corresponding entities +---------------------------------------------------------------------------------------- +The :meth:`_query.Query.select_from` method has been popularized in recent versions +as a means of controlling the first thing that a :class:`_query.Query` object "selects from", typically for the purposes of controlling how a JOIN will render. @@ -108,14 +107,14 @@ The above statement predictably renders SQL like the following:: If we wanted to reverse the order of the left and right elements of the JOIN, the documentation would lead us to believe we could use -:meth:`.Query.select_from` to do so:: +:meth:`_query.Query.select_from` to do so:: q = session.query(User).\ select_from(select_stmt).\ join(User, User.id == select_stmt.c.id).\ filter(User.name == 'ed') -However, in version 0.8 and earlier, the above use of :meth:`.Query.select_from` +However, in version 0.8 and earlier, the above use of :meth:`_query.Query.select_from` would apply the ``select_stmt`` to **replace** the ``User`` entity, as it selects from the ``user`` table which is compatible with ``User``:: @@ -130,8 +129,8 @@ The above statement is a mess, the ON clause refers ``anon_1.id = anon_1.id``, our WHERE clause has been replaced with ``anon_1`` as well. This behavior is quite intentional, but has a different use case from that -which has become popular for :meth:`.Query.select_from`. The above behavior -is now available by a new method known as :meth:`.Query.select_entity_from`. +which has become popular for :meth:`_query.Query.select_from`. The above behavior +is now available by a new method known as :meth:`_query.Query.select_entity_from`. This is a lesser used behavior that in modern SQLAlchemy is roughly equivalent to selecting from a customized :func:`.aliased` construct:: @@ -150,7 +149,7 @@ the SQL we expect:: WHERE "user".id = :id_1) AS anon_1 JOIN "user" ON "user".id = id WHERE "user".name = :name_1 -The :meth:`.Query.select_entity_from` method will be available in SQLAlchemy +The :meth:`_query.Query.select_entity_from` method will be available in SQLAlchemy **0.8.2**, so applications which rely on the old behavior can transition to this method first, ensure all tests continue to function, then upgrade to 0.9 without issue. @@ -163,7 +162,7 @@ to 0.9 without issue. ``viewonly=True`` on ``relationship()`` prevents history from taking effect --------------------------------------------------------------------------- -The ``viewonly`` flag on :func:`.relationship` is applied to prevent changes +The ``viewonly`` flag on :func:`_orm.relationship` is applied to prevent changes to the target attribute from having any effect within the flush process. This is achieved by eliminating the attribute from being considered during the flush. However, up until now, changes to the attribute would still @@ -601,7 +600,7 @@ generated:: PostgreSQL CREATE TYPE AS ENUM now applies quoting to values ---------------------------------------------------------------- -The :class:`.postgresql.ENUM` type will now apply escaping to single quote +The :class:`_postgresql.ENUM` type will now apply escaping to single quote signs within the enumerated values:: >>> from sqlalchemy.dialects import postgresql @@ -656,9 +655,9 @@ such as listener targets, to be garbage collected when they go out of scope. New Query Options API; ``load_only()`` option --------------------------------------------- -The system of loader options such as :func:`.orm.joinedload`, -:func:`.orm.subqueryload`, :func:`.orm.lazyload`, :func:`.orm.defer`, etc. -all build upon a new system known as :class:`.Load`. :class:`.Load` provides +The system of loader options such as :func:`_orm.joinedload`, +:func:`_orm.subqueryload`, :func:`_orm.lazyload`, :func:`_orm.defer`, etc. +all build upon a new system known as :class:`_orm.Load`. :class:`_orm.Load` provides a "method chained" (a.k.a. :term:`generative`) approach to loader options, so that instead of joining together long paths using dots or multiple attribute names, an explicit loader style is given for each path. @@ -680,7 +679,7 @@ option has to be used:: Loader options are now chainable, so the same ``joinedload(x)`` method is applied equally to each link, without the need to keep straight between -:func:`.joinedload` and :func:`.joinedload_all`:: +:func:`_orm.joinedload` and :func:`_orm.joinedload_all`:: query(User).options(joinedload("orders").joinedload("items").joinedload("keywords")) @@ -742,15 +741,15 @@ path for each column:: **New Way** -A single :class:`.Load` object that arrives at the target path can have -:meth:`.Load.defer` called upon it repeatedly:: +A single :class:`_orm.Load` object that arrives at the target path can have +:meth:`_orm.Load.defer` called upon it repeatedly:: query(User).options(defaultload("orders").defer("description").defer("isopen")) The Load Class ^^^^^^^^^^^^^^^ -The :class:`.Load` class can be used directly to provide a "bound" target, +The :class:`_orm.Load` class can be used directly to provide a "bound" target, especially when multiple parent entities are present:: from sqlalchemy.orm import Load @@ -776,7 +775,7 @@ loading only the given columns and deferring the rest:: Class-specific Wildcards ^^^^^^^^^^^^^^^^^^^^^^^^^ -Using :class:`.Load`, a wildcard may be used to set the loading for all +Using :class:`_orm.Load`, a wildcard may be used to set the loading for all relationships (or perhaps columns) on a given entity, without affecting any others:: @@ -801,9 +800,9 @@ others:: New ``text()`` Capabilities --------------------------- -The :func:`.text` construct gains new methods: +The :func:`_expression.text` construct gains new methods: -* :meth:`.TextClause.bindparams` allows bound parameter types and values +* :meth:`_expression.TextClause.bindparams` allows bound parameter types and values to be set flexibly:: # setup values @@ -819,8 +818,8 @@ The :func:`.text` construct gains new methods: bindparam("timestamp", type_=DateTime() ).bindparam(timestamp=datetime(2012, 11, 10, 15, 12, 35)) -* :meth:`.TextClause.columns` supersedes the ``typemap`` option - of :func:`.text`, returning a new construct :class:`.TextAsFrom`:: +* :meth:`_expression.TextClause.columns` supersedes the ``typemap`` option + of :func:`_expression.text`, returning a new construct :class:`.TextAsFrom`:: # turn a text() into an alias(), with a .c. collection: stmt = text("SELECT id, name FROM user").columns(id=Integer, name=String) @@ -846,8 +845,8 @@ INSERT from SELECT After literally years of pointless procrastination this relatively minor syntactical feature has been added, and is also backported to 0.8.3, -so technically isn't "new" in 0.9. A :func:`~.sql.expression.select` construct or other -compatible construct can be passed to the new method :meth:`.Insert.from_select` +so technically isn't "new" in 0.9. A :func:`_expression.select` construct or other +compatible construct can be passed to the new method :meth:`_expression.Insert.from_select` where it will be used to render an ``INSERT .. SELECT`` construct:: >>> from sqlalchemy.sql import table, column @@ -859,7 +858,7 @@ where it will be used to render an ``INSERT .. SELECT`` construct:: WHERE t2.y = :y_1 The construct is smart enough to also accommodate ORM objects such as classes -and :class:`.Query` objects:: +and :class:`_query.Query` objects:: s = Session() q = s.query(User.id, User.name).filter_by(name='ed') @@ -882,7 +881,7 @@ An attempt is made to simplify the specification of the ``FOR UPDATE`` clause on ``SELECT`` statements made within Core and ORM, and support is added for the ``FOR UPDATE OF`` SQL supported by PostgreSQL and Oracle. -Using the core :meth:`.GenerativeSelect.with_for_update`, options like ``FOR SHARE`` and +Using the core :meth:`_expression.GenerativeSelect.with_for_update`, options like ``FOR SHARE`` and ``NOWAIT`` can be specified individually, rather than linking to arbitrary string codes:: @@ -892,9 +891,9 @@ On Posgtresql the above statement might render like:: SELECT table.a, table.b FROM table FOR SHARE OF table NOWAIT -The :class:`.Query` object gains a similar method :meth:`.Query.with_for_update` +The :class:`_query.Query` object gains a similar method :meth:`_query.Query.with_for_update` which behaves in the same way. This method supersedes the existing -:meth:`.Query.with_lockmode` method, which translated ``FOR UPDATE`` clauses +:meth:`_query.Query.with_lockmode` method, which translated ``FOR UPDATE`` clauses using a different system. At the moment, the "lockmode" string argument is still accepted by the :meth:`.Session.refresh` method. @@ -1037,12 +1036,12 @@ from a backref:: PostgreSQL JSON Type -------------------- -The PostgreSQL dialect now features a :class:`.postgresql.JSON` type to -complement the :class:`.postgresql.HSTORE` type. +The PostgreSQL dialect now features a :class:`_postgresql.JSON` type to +complement the :class:`_postgresql.HSTORE` type. .. seealso:: - :class:`.postgresql.JSON` + :class:`_postgresql.JSON` :ticket:`2581` @@ -1057,7 +1056,7 @@ as well as the :class:`.DeferredReflection` class. Essentially, the extension provides a base class :class:`.AutomapBase` which automatically generates mapped classes and relationships between them based on given table metadata. -The :class:`.MetaData` in use normally might be produced via reflection, but +The :class:`_schema.MetaData` in use normally might be produced via reflection, but there is no requirement that reflection is used. The most basic usage illustrates how :mod:`sqlalchemy.ext.automap` is able to deliver mapped classes, including relationships, based on a reflected schema:: @@ -1158,8 +1157,8 @@ SELECT often degrades performance on platforms like PostgreSQL and MySQL:: ) AS anon_1 ON a.id=anon_1.b_id A JOIN like the above form is commonplace when working with joined-table inheritance structures; -any time :meth:`.Query.join` is used to join from some parent to a joined-table subclass, or -when :func:`.joinedload` is used similarly, SQLAlchemy's ORM would always make sure a nested +any time :meth:`_query.Query.join` is used to join from some parent to a joined-table subclass, or +when :func:`_orm.joinedload` is used similarly, SQLAlchemy's ORM would always make sure a nested JOIN was never rendered, lest the query wouldn't be able to run on SQLite. Even though the Core has always supported a JOIN of the more compact form, the ORM had to avoid it. @@ -1210,11 +1209,11 @@ Many-to-many joins and eagerloads will right nest the "secondary" and "right" ta (order_item JOIN item ON order_item.item_id = item.id AND item.type = 'subitem') ON order_item.order_id = order.id -All of these joins, when rendered with a :class:`.Select` statement that specifically +All of these joins, when rendered with a :class:`_expression.Select` statement that specifically specifies ``use_labels=True``, which is true for all the queries the ORM emits, are candidates for "join rewriting", which is the process of rewriting all those right-nested joins into nested SELECT statements, while maintaining the identical labeling used by -the :class:`.Select`. So SQLite, the one database that won't support this very +the :class:`_expression.Select`. So SQLite, the one database that won't support this very common SQL syntax even in 2013, shoulders the extra complexity itself, with the above queries rewritten as:: @@ -1255,7 +1254,7 @@ with the above queries rewritten as:: will automatically disable themselves when SQLite version **3.7.16** or greater is detected, as SQLite has repaired support for right-nested joins. -The :meth:`.Join.alias`, :func:`.aliased` and :func:`.with_polymorphic` functions now +The :meth:`_expression.Join.alias`, :func:`.aliased` and :func:`.with_polymorphic` functions now support a new argument, ``flat=True``, which is used to construct aliases of joined-table entities without embedding into a SELECT. This flag is not on by default, to help with backwards compatibility - but now a "polymorphic" selectable can be joined as a target @@ -1310,7 +1309,7 @@ the new "right-nested joins are OK" logic would kick in, and we'd get:: FROM users LEFT OUTER JOIN (orders JOIN items ON ) ON Since we missed the boat on that, to avoid further regressions we've added the above -functionality by specifying the string ``"nested"`` to :paramref:`.joinedload.innerjoin`:: +functionality by specifying the string ``"nested"`` to :paramref:`_orm.joinedload.innerjoin`:: query(User).options(joinedload("orders", innerjoin=False).joinedload("items", innerjoin="nested")) @@ -1323,7 +1322,7 @@ This feature is new in 0.9.4. ORM can efficiently fetch just-generated INSERT/UPDATE defaults using RETURNING ------------------------------------------------------------------------------- -The :class:`.Mapper` has long supported an undocumented flag known as +The :class:`_orm.Mapper` has long supported an undocumented flag known as ``eager_defaults=True``. The effect of this flag is that when an INSERT or UPDATE proceeds, and the row is known to have server-generated default values, a SELECT would immediately follow it in order to "eagerly" load those new values. @@ -1339,7 +1338,7 @@ emit a RETURNING clause for these values, so on a backend with strong RETURNING support in particular PostgreSQL, the ORM can fetch newly generated default and SQL expression values inline with the INSERT or UPDATE. ``eager_defaults``, when enabled, makes use of RETURNING automatically when the target backend -and :class:`.Table` supports "implicit returning". +and :class:`_schema.Table` supports "implicit returning". .. _change_2836: @@ -1360,7 +1359,7 @@ That is, when subquery loading on a many-to-one from A->B:: Since ``a.b_id`` is a non-distinct foreign key, DISTINCT is applied so that redundant ``a.b_id`` are eliminated. The behavior can be turned on or off -unconditionally for a particular :func:`.relationship` using the flag +unconditionally for a particular :func:`_orm.relationship` using the flag ``distinct_target_key``, setting the value to ``True`` for unconditionally on, ``False`` for unconditionally off, and ``None`` for the feature to take effect when the target SELECT is against columns that do not comprise a full @@ -1486,13 +1485,13 @@ Schema identifiers now carry along their own quoting information --------------------------------------------------------------------- This change simplifies the Core's usage of so-called "quote" flags, such -as the ``quote`` flag passed to :class:`.Table` and :class:`.Column`. The flag +as the ``quote`` flag passed to :class:`_schema.Table` and :class:`_schema.Column`. The flag is now internalized within the string name itself, which is now represented as an instance of :class:`.quoted_name`, a string subclass. The :class:`.IdentifierPreparer` now relies solely on the quoting preferences reported by the :class:`.quoted_name` object rather than checking for any explicit ``quote`` flags in most cases. The issue resolved here includes -that various case-sensitive methods such as :meth:`.Engine.has_table` as well +that various case-sensitive methods such as :meth:`_engine.Engine.has_table` as well as similar methods within dialects now function with explicitly quoted names, without the need to complicate or introduce backwards-incompatible changes to those APIs (many of which are 3rd party) with the details of quoting flags - @@ -1643,7 +1642,7 @@ The logic which "upgrades" a :func:`.bindparam` construct to take on the type of the enclosing expression has been improved in two ways. First, the :func:`.bindparam` object is **copied** before the new type is assigned, so that the given :func:`.bindparam` is not mutated in place. Secondly, this same -operation occurs when an :class:`~.sql.expression.Insert` or :class:`.Update` construct is compiled, +operation occurs when an :class:`_expression.Insert` or :class:`_expression.Update` construct is compiled, regarding the "values" that were set in the statement via the :meth:`.ValuesBase.values` method. @@ -1660,7 +1659,7 @@ is of type ``String``, then ``expr.right``, that is the right side of the binary expression, will take on the ``String`` type. Previously, ``bp`` itself would have been changed in place to have ``String`` as its type. -Similarly, this operation occurs in an :class:`~.sql.expression.Insert` or :class:`.Update`:: +Similarly, this operation occurs in an :class:`_expression.Insert` or :class:`_expression.Update`:: stmt = mytable.update().values(col=bp) @@ -1679,7 +1678,7 @@ The potentially backwards-compatible changes involve two unlikely scenarios. Since the bound parameter is **cloned**, users should not be relying upon making in-place changes to a :func:`.bindparam` construct once created. Additionally, code which uses -:func:`.bindparam` within an :class:`~.sql.expression.Insert` or :class:`.Update` statement +:func:`.bindparam` within an :class:`_expression.Insert` or :class:`_expression.Update` statement which is relying on the fact that the :func:`.bindparam` is not typed according to the column being assigned towards will no longer function in that way. @@ -1691,39 +1690,39 @@ to the column being assigned towards will no longer function in that way. Columns can reliably get their type from a column referred to via ForeignKey ---------------------------------------------------------------------------- -There's a long standing behavior which says that a :class:`.Column` can be -declared without a type, as long as that :class:`.Column` is referred to -by a :class:`.ForeignKeyConstraint`, and the type from the referenced column +There's a long standing behavior which says that a :class:`_schema.Column` can be +declared without a type, as long as that :class:`_schema.Column` is referred to +by a :class:`_schema.ForeignKeyConstraint`, and the type from the referenced column will be copied into this one. The problem has been that this feature never worked very well and wasn't maintained. The core issue was that the -:class:`.ForeignKey` object doesn't know what target :class:`.Column` it +:class:`_schema.ForeignKey` object doesn't know what target :class:`_schema.Column` it refers to until it is asked, typically the first time the foreign key is used -to construct a :class:`.Join`. So until that time, the parent :class:`.Column` +to construct a :class:`_expression.Join`. So until that time, the parent :class:`_schema.Column` would not have a type, or more specifically, it would have a default type of :class:`.NullType`. While it's taken a long time, the work to reorganize the initialization of -:class:`.ForeignKey` objects has been completed such that this feature can -finally work acceptably. At the core of the change is that the :attr:`.ForeignKey.column` -attribute no longer lazily initializes the location of the target :class:`.Column`; -the issue with this system was that the owning :class:`.Column` would be stuck -with :class:`.NullType` as its type until the :class:`.ForeignKey` happened to +:class:`_schema.ForeignKey` objects has been completed such that this feature can +finally work acceptably. At the core of the change is that the :attr:`_schema.ForeignKey.column` +attribute no longer lazily initializes the location of the target :class:`_schema.Column`; +the issue with this system was that the owning :class:`_schema.Column` would be stuck +with :class:`.NullType` as its type until the :class:`_schema.ForeignKey` happened to be used. -In the new version, the :class:`.ForeignKey` coordinates with the eventual -:class:`.Column` it will refer to using internal attachment events, so that the -moment the referencing :class:`.Column` is associated with the -:class:`.MetaData`, all :class:`.ForeignKey` objects that +In the new version, the :class:`_schema.ForeignKey` coordinates with the eventual +:class:`_schema.Column` it will refer to using internal attachment events, so that the +moment the referencing :class:`_schema.Column` is associated with the +:class:`_schema.MetaData`, all :class:`_schema.ForeignKey` objects that refer to it will be sent a message that they need to initialize their parent column. This system is more complicated but works more solidly; as a bonus, -there are now tests in place for a wide variety of :class:`.Column` / -:class:`.ForeignKey` configuration scenarios and error messages have been +there are now tests in place for a wide variety of :class:`_schema.Column` / +:class:`_schema.ForeignKey` configuration scenarios and error messages have been improved to be very specific to no less than seven different error conditions. Scenarios which now work correctly include: -1. The type on a :class:`.Column` is immediately present as soon as the - target :class:`.Column` becomes associated with the same :class:`.MetaData`; +1. The type on a :class:`_schema.Column` is immediately present as soon as the + target :class:`_schema.Column` becomes associated with the same :class:`_schema.MetaData`; this works no matter which side is configured first:: >>> from sqlalchemy import Table, MetaData, Column, Integer, ForeignKey @@ -1735,7 +1734,7 @@ Scenarios which now work correctly include: >>> t2.c.t1id.type Integer() -2. The system now works with :class:`.ForeignKeyConstraint` as well:: +2. The system now works with :class:`_schema.ForeignKeyConstraint` as well:: >>> from sqlalchemy import Table, MetaData, Column, Integer, ForeignKeyConstraint >>> metadata = MetaData() @@ -1754,8 +1753,8 @@ Scenarios which now work correctly include: >>> t2.c.t1b.type Integer() -3. It even works for "multiple hops" - that is, a :class:`.ForeignKey` that refers to a - :class:`.Column` that refers to another :class:`.Column`:: +3. It even works for "multiple hops" - that is, a :class:`_schema.ForeignKey` that refers to a + :class:`_schema.Column` that refers to another :class:`_schema.Column`:: >>> from sqlalchemy import Table, MetaData, Column, Integer, ForeignKey >>> metadata = MetaData() diff --git a/doc/build/changelog/migration_10.rst b/doc/build/changelog/migration_10.rst index 21ca831393..4066c567cb 100644 --- a/doc/build/changelog/migration_10.rst +++ b/doc/build/changelog/migration_10.rst @@ -60,10 +60,10 @@ displays. --------------- The "baked" query feature is an unusual new approach which allows for -straightforward construction an invocation of :class:`.Query` objects +straightforward construction an invocation of :class:`_query.Query` objects using caching, which upon successive calls features vastly reduced Python function call overhead (over 75%). By specifying a -:class:`.Query` object as a series of lambdas which are only invoked +:class:`_query.Query` object as a series of lambdas which are only invoked once, a query as a pre-compiled unit begins to be feasible:: from sqlalchemy.ext import baked @@ -102,7 +102,7 @@ overhauled to support new capabilities. A function decorated with :class:`.declared_attr` is now called only **after** any mixin-based column copies are generated. This means the function can call upon mixin-established columns and will receive a reference to the correct -:class:`.Column` object:: +:class:`_schema.Column` object:: class HasFooBar(object): foobar = Column(Integer) @@ -116,7 +116,7 @@ call upon mixin-established columns and will receive a reference to the correct id = Column(Integer, primary_key=True) Above, ``SomeClass.foobar_prop`` will be invoked against ``SomeClass``, -and ``SomeClass.foobar`` will be the final :class:`.Column` object that is +and ``SomeClass.foobar`` will be the final :class:`_schema.Column` object that is to be mapped to ``SomeClass``, as opposed to the non-copied object present directly on ``HasFooBar``, even though the columns aren't mapped yet. @@ -264,10 +264,10 @@ of load that's improved the most:: print("Total time: %d" % (time.time() - now)) Local MacBookPro results bench from 19 seconds for 0.9 down to 14 seconds for -1.0. The :meth:`.Query.yield_per` call is always a good idea when batching +1.0. The :meth:`_query.Query.yield_per` call is always a good idea when batching huge numbers of rows, as it prevents the Python interpreter from having to allocate a huge amount of memory for all objects and their instrumentation -at once. Without the :meth:`.Query.yield_per`, the above script on the +at once. Without the :meth:`_query.Query.yield_per`, the above script on the MacBookPro is 31 seconds on 0.9 and 26 seconds on 1.0, the extra time spent setting up very large memory buffers. @@ -421,12 +421,12 @@ Session.get_bind() will receive the Mapper in all relevant Query cases ---------------------------------------------------------------------- A series of issues were repaired where the :meth:`.Session.get_bind` -would not receive the primary :class:`.Mapper` of the :class:`.Query`, +would not receive the primary :class:`_orm.Mapper` of the :class:`_query.Query`, even though this mapper was readily available (the primary mapper is the single mapper, or alternatively the first mapper, that is associated with -a :class:`.Query` object). +a :class:`_query.Query` object). -The :class:`.Mapper` object, when passed to :meth:`.Session.get_bind`, +The :class:`_orm.Mapper` object, when passed to :meth:`.Session.get_bind`, is typically used by sessions that make use of the :paramref:`.Session.binds` parameter to associate mappers with a series of engines (although in this use case, things frequently @@ -438,11 +438,11 @@ so-called "routing" session that routes queries to different backends. These scenarios include: -* :meth:`.Query.count`:: +* :meth:`_query.Query.count`:: session.query(User).count() -* :meth:`.Query.update` and :meth:`.Query.delete`, both for the UPDATE/DELETE +* :meth:`_query.Query.update` and :meth:`_query.Query.delete`, both for the UPDATE/DELETE statement as well as for the SELECT used by the "fetch" strategy:: session.query(User).filter(User.id == 15).update( @@ -473,12 +473,12 @@ These scenarios include: ----------------------------- The :attr:`.InspectionAttr.info` collection is now available on every kind -of object that one would retrieve from the :attr:`.Mapper.all_orm_descriptors` +of object that one would retrieve from the :attr:`_orm.Mapper.all_orm_descriptors` collection. This includes :class:`.hybrid_property` and :func:`.association_proxy`. However, as these objects are class-bound descriptors, they must be accessed **separately** from the class to which they are attached in order to get at the attribute. Below this is illustrated using the -:attr:`.Mapper.all_orm_descriptors` namespace:: +:attr:`_orm.Mapper.all_orm_descriptors` namespace:: class SomeObject(Base): # ... @@ -491,8 +491,8 @@ at the attribute. Below this is illustrated using the inspect(SomeObject).all_orm_descriptors.some_prop.info['foo'] = 'bar' It is also available as a constructor argument for all :class:`.SchemaItem` -objects (e.g. :class:`.ForeignKey`, :class:`.UniqueConstraint` etc.) as well -as remaining ORM constructs such as :func:`.orm.synonym`. +objects (e.g. :class:`_schema.ForeignKey`, :class:`.UniqueConstraint` etc.) as well +as remaining ORM constructs such as :func:`_orm.synonym`. :ticket:`2971` @@ -585,10 +585,10 @@ New Features and Improvements - Core Select/Query LIMIT / OFFSET may be specified as an arbitrary SQL expression --------------------------------------------------------------------------- -The :meth:`.Select.limit` and :meth:`.Select.offset` methods now accept +The :meth:`_expression.Select.limit` and :meth:`_expression.Select.offset` methods now accept any SQL expression, in addition to integer values, as arguments. The ORM -:class:`.Query` object also passes through any expression to the underlying -:class:`.Select` object. Typically +:class:`_query.Query` object also passes through any expression to the underlying +:class:`_expression.Select` object. Typically this is used to allow a bound parameter to be passed, which can be substituted with a value later:: @@ -610,11 +610,11 @@ than the integer value. The ``use_alter`` flag on ``ForeignKeyConstraint`` is (usually) no longer needed -------------------------------------------------------------------------------- -The :meth:`.MetaData.create_all` and :meth:`.MetaData.drop_all` methods will +The :meth:`_schema.MetaData.create_all` and :meth:`_schema.MetaData.drop_all` methods will now make use of a system that automatically renders an ALTER statement for foreign key constraints that are involved in mutually-dependent cycles between tables, without the -need to specify :paramref:`.ForeignKeyConstraint.use_alter`. Additionally, +need to specify :paramref:`_schema.ForeignKeyConstraint.use_alter`. Additionally, the foreign key constraints no longer need to have a name in order to be created via ALTER; only the DROP operation requires a name. In the case of a DROP, the feature will ensure that only constraints which have @@ -622,8 +622,8 @@ explicit names are actually included as ALTER statements. In the case of an unresolvable cycle within a DROP, the system emits a succinct and clear error message now if the DROP cannot proceed. -The :paramref:`.ForeignKeyConstraint.use_alter` and -:paramref:`.ForeignKey.use_alter` flags remain in place, and continue to have +The :paramref:`_schema.ForeignKeyConstraint.use_alter` and +:paramref:`_schema.ForeignKey.use_alter` flags remain in place, and continue to have the same effect of establishing those constraints for which ALTER is required during a CREATE/DROP scenario. @@ -634,7 +634,7 @@ are dropped with **no** ordering, which is usually fine on SQLite unless constraints are enabled. To resolve the warning and proceed with at least a partial ordering on a SQLite database, particularly one where constraints are enabled, re-apply "use_alter" flags to those -:class:`.ForeignKey` and :class:`.ForeignKeyConstraint` objects which should +:class:`_schema.ForeignKey` and :class:`_schema.ForeignKeyConstraint` objects which should be explicitly omitted from the sort. .. seealso:: @@ -737,7 +737,7 @@ Constraints referring to unattached Columns can auto-attach to the Table when th ----------------------------------------------------------------------------------------------------------------- Since at least version 0.8, a :class:`.Constraint` has had the ability to -"auto-attach" itself to a :class:`.Table` based on being passed table-attached columns:: +"auto-attach" itself to a :class:`_schema.Table` based on being passed table-attached columns:: from sqlalchemy import Table, Column, MetaData, Integer, UniqueConstraint @@ -753,9 +753,9 @@ Since at least version 0.8, a :class:`.Constraint` has had the ability to assert uq in t.constraints In order to assist with some cases that tend to come up with declarative, -this same auto-attachment logic can now function even if the :class:`.Column` -objects are not yet associated with the :class:`.Table`; additional events -are established such that when those :class:`.Column` objects are associated, +this same auto-attachment logic can now function even if the :class:`_schema.Column` +objects are not yet associated with the :class:`_schema.Table`; additional events +are established such that when those :class:`_schema.Column` objects are associated, the :class:`.Constraint` is also added:: from sqlalchemy import Table, Column, MetaData, Integer, UniqueConstraint @@ -774,8 +774,8 @@ the :class:`.Constraint` is also added:: The above feature was a late add as of version 1.0.0b3. A fix as of version 1.0.4 for :ticket:`3411` ensures that this logic does not occur if the :class:`.Constraint` refers to a mixture of -:class:`.Column` objects and string column names; as we do not yet have -tracking for the addition of names to a :class:`.Table`:: +:class:`_schema.Column` objects and string column names; as we do not yet have +tracking for the addition of names to a :class:`_schema.Table`:: from sqlalchemy import Table, Column, MetaData, Integer, UniqueConstraint @@ -793,13 +793,13 @@ tracking for the addition of names to a :class:`.Table`:: assert uq not in t.constraints Above, the attachment event for column "a" to table "t" will fire off before -column "b" is attached (as "a" is stated in the :class:`.Table` constructor +column "b" is attached (as "a" is stated in the :class:`_schema.Table` constructor before "b"), and the constraint will fail to locate "b" if it were to attempt an attachment. For consistency, if the constraint refers to any string names, the autoattach-on-column-attach logic is skipped. -The original auto-attach logic of course remains in place, if the :class:`.Table` -already contains all the target :class:`.Column` objects at the time +The original auto-attach logic of course remains in place, if the :class:`_schema.Table` +already contains all the target :class:`_schema.Column` objects at the time the :class:`.Constraint` is constructed:: from sqlalchemy import Table, Column, MetaData, Integer, UniqueConstraint @@ -828,7 +828,7 @@ the :class:`.Constraint` is constructed:: INSERT FROM SELECT now includes Python and SQL-expression defaults ------------------------------------------------------------------ -:meth:`.Insert.from_select` now includes Python and SQL-expression defaults if +:meth:`_expression.Insert.from_select` now includes Python and SQL-expression defaults if otherwise unspecified; the limitation where non-server column defaults aren't included in an INSERT FROM SELECT is now lifted and these expressions are rendered as constants into the SELECT statement:: @@ -859,7 +859,7 @@ Column server defaults now render literal values ------------------------------------------------ The "literal binds" compiler flag is switched on when a -:class:`.DefaultClause`, set up by :paramref:`.Column.server_default` +:class:`.DefaultClause`, set up by :paramref:`_schema.Column.server_default` is present as a SQL expression to be compiled. This allows literals embedded in SQL to render correctly, such as:: @@ -893,7 +893,7 @@ bound parameters, which are useless in DDL. UniqueConstraint is now part of the Table reflection process ------------------------------------------------------------ -A :class:`.Table` object populated using ``autoload=True`` will now +A :class:`_schema.Table` object populated using ``autoload=True`` will now include :class:`.UniqueConstraint` constructs as well as :class:`.Index` constructs. This logic has a few caveats for PostgreSQL and MySQL: @@ -903,17 +903,17 @@ PostgreSQL PostgreSQL has the behavior such that when a UNIQUE constraint is created, it implicitly creates a UNIQUE INDEX corresponding to that -constraint as well. The :meth:`.Inspector.get_indexes` and the -:meth:`.Inspector.get_unique_constraints` methods will continue to +constraint as well. The :meth:`_reflection.Inspector.get_indexes` and the +:meth:`_reflection.Inspector.get_unique_constraints` methods will continue to **both** return these entries distinctly, where -:meth:`.Inspector.get_indexes` now features a token +:meth:`_reflection.Inspector.get_indexes` now features a token ``duplicates_constraint`` within the index entry indicating the corresponding constraint when detected. However, when performing full table reflection using ``Table(..., autoload=True)``, the :class:`.Index` construct is detected as being linked to the :class:`.UniqueConstraint`, and is **not** present within the -:attr:`.Table.indexes` collection; only the :class:`.UniqueConstraint` -will be present in the :attr:`.Table.constraints` collection. This +:attr:`_schema.Table.indexes` collection; only the :class:`.UniqueConstraint` +will be present in the :attr:`_schema.Table.constraints` collection. This deduplication logic works by joining to the ``pg_constraint`` table when querying ``pg_index`` to see if the two constructs are linked. @@ -923,17 +923,17 @@ MySQL MySQL does not have separate concepts for a UNIQUE INDEX and a UNIQUE constraint. While it supports both syntaxes when creating tables and indexes, it does not store them any differently. The -:meth:`.Inspector.get_indexes` -and the :meth:`.Inspector.get_unique_constraints` methods will continue to +:meth:`_reflection.Inspector.get_indexes` +and the :meth:`_reflection.Inspector.get_unique_constraints` methods will continue to **both** return an entry for a UNIQUE index in MySQL, -where :meth:`.Inspector.get_unique_constraints` features a new token +where :meth:`_reflection.Inspector.get_unique_constraints` features a new token ``duplicates_index`` within the constraint entry indicating that this is a dupe entry corresponding to that index. However, when performing full table reflection using ``Table(..., autoload=True)``, the :class:`.UniqueConstraint` construct is -**not** part of the fully reflected :class:`.Table` construct under any +**not** part of the fully reflected :class:`_schema.Table` construct under any circumstances; this construct is always represented by a :class:`.Index` -with the ``unique=True`` setting present in the :attr:`.Table.indexes` +with the ``unique=True`` setting present in the :attr:`_schema.Table.indexes` collection. .. seealso:: @@ -1001,7 +1001,7 @@ Key Behavioral Changes - ORM query.update() now resolves string names into mapped attribute names -------------------------------------------------------------------- -The documentation for :meth:`.Query.update` states that the given +The documentation for :meth:`_query.Query.update` states that the given ``values`` dictionary is "a dictionary with attributes names as keys", implying that these are mapped attribute names. Unfortunately, the function was designed more in mind to receive attributes and SQL expressions and @@ -1021,7 +1021,7 @@ The string names are now resolved as attribute names in earnest:: name = Column('user_name', String(50)) Above, the column ``user_name`` is mapped as ``name``. Previously, -a call to :meth:`.Query.update` that was passed strings would have to +a call to :meth:`_query.Query.update` that was passed strings would have to have been called as follows:: session.query(User).update({'user_name': 'moonbeam'}) @@ -1234,7 +1234,7 @@ attribute set operation on a many-to-one is received; previously, the "old" valu would be "None" if it had been not set otherwise; it now will send the value :data:`.orm.attributes.NEVER_SET`, which is a value that may be sent to an attribute listener now. This symbol may also be received when -calling on mapper utility functions such as :meth:`.Mapper.primary_key_from_instance`; +calling on mapper utility functions such as :meth:`_orm.Mapper.primary_key_from_instance`; if the primary key attributes have no setting at all, whereas the value would be ``None`` before, it will now be the :data:`.orm.attributes.NEVER_SET` symbol, and no change to the object's state occurs. @@ -1331,7 +1331,7 @@ that rely on :meth:`.Session.expunge` such as :func:`.make_transient`. Joined/Subquery eager loading explicitly disallowed with yield_per ------------------------------------------------------------------ -In order to make the :meth:`.Query.yield_per` method easier to use, +In order to make the :meth:`_query.Query.yield_per` method easier to use, an exception is raised if any subquery eager loaders, or joined eager loaders that would use collections, are to take effect when yield_per is used, as these are currently not compatible @@ -1341,7 +1341,7 @@ an asterisk:: q = sess.query(Object).options(lazyload('*')).yield_per(100) -or use :meth:`.Query.enable_eagerloads`:: +or use :meth:`_query.Query.enable_eagerloads`:: q = sess.query(Object).enable_eagerloads(False).yield_per(100) @@ -1574,8 +1574,8 @@ The unused ``result`` member is now removed:: Right inner join nesting now the default for joinedload with innerjoin=True --------------------------------------------------------------------------- -The behavior of :paramref:`.joinedload.innerjoin` as well as -:paramref:`.relationship.innerjoin` is now to use "nested" +The behavior of :paramref:`_orm.joinedload.innerjoin` as well as +:paramref:`_orm.relationship.innerjoin` is now to use "nested" inner joins, that is, right-nested, as the default behavior when an inner join joined eager load is chained to an outer join eager load. In order to get the old behavior of chaining all joined eager loads as @@ -1595,7 +1595,7 @@ With the new default, this will render the FROM clause in the form:: That is, using a right-nested join for the INNER join so that the full result of ``users`` can be returned. The use of an INNER join is more efficient -than using an OUTER join, and allows the :paramref:`.joinedload.innerjoin` +than using an OUTER join, and allows the :paramref:`_orm.joinedload.innerjoin` optimization parameter to take effect in all cases. To get the older behavior, use ``innerjoin="unnested"``:: @@ -1671,10 +1671,10 @@ query.update() / query.delete() raises if used with join(), select_from(), from_ -------------------------------------------------------------------------------------- A warning is emitted in SQLAlchemy 0.9.10 (not yet released as of -June 9, 2015) when the :meth:`.Query.update` or :meth:`.Query.delete` methods -are invoked against a query which has also called upon :meth:`.Query.join`, -:meth:`.Query.outerjoin`, -:meth:`.Query.select_from` or :meth:`.Query.from_self`. These are unsupported +June 9, 2015) when the :meth:`_query.Query.update` or :meth:`_query.Query.delete` methods +are invoked against a query which has also called upon :meth:`_query.Query.join`, +:meth:`_query.Query.outerjoin`, +:meth:`_query.Query.select_from` or :meth:`_query.Query.from_self`. These are unsupported use cases which silently fail in the 0.9 series up until 0.9.10 where it emits a warning. In 1.0, these cases raise an exception. @@ -1684,7 +1684,7 @@ a warning. In 1.0, these cases raise an exception. query.update() with ``synchronize_session='evaluate'`` raises on multi-table update ----------------------------------------------------------------------------------- -The "evaluator" for :meth:`.Query.update` won't work with multi-table +The "evaluator" for :meth:`_query.Query.update` won't work with multi-table updates, and needs to be set to ``synchronize_session=False`` or ``synchronize_session='fetch'`` when multiple tables are present. The new behavior is that an explicit exception is now raised, with a message @@ -1714,7 +1714,7 @@ Given a single-table inheritance mapping, such as:: class FooWidget(Widget): pass -Using :meth:`.Query.from_self` or :meth:`.Query.count` against a subclass +Using :meth:`_query.Query.from_self` or :meth:`_query.Query.count` against a subclass would produce a subquery, but then add the "WHERE" criteria for subtypes to the outside:: @@ -1795,7 +1795,7 @@ SQL output:: SELECT related.id AS related_id FROM related JOIN widget ON related.id = widget.related_id AND widget.type IN (:type_1) -Above, because we joined to a subclass ``FooWidget``, :meth:`.Query.join` +Above, because we joined to a subclass ``FooWidget``, :meth:`_query.Query.join` knew to add the ``AND widget.type IN ('foo')`` criteria to the ON clause. The change here is that the ``AND widget.type IN()`` criteria is now appended @@ -1835,9 +1835,9 @@ Since SQLAlchemy's inception, there has always been an emphasis on not getting in the way of the usage of plain text. The Core and ORM expression systems were intended to allow any number of points at which the user can just use plain text SQL expressions, not just in the sense that you can send a -full SQL string to :meth:`.Connection.execute`, but that you can send strings -with SQL expressions into many functions, such as :meth:`.Select.where`, -:meth:`.Query.filter`, and :meth:`.Select.order_by`. +full SQL string to :meth:`_engine.Connection.execute`, but that you can send strings +with SQL expressions into many functions, such as :meth:`_expression.Select.where`, +:meth:`_query.Query.filter`, and :meth:`_expression.Select.order_by`. Note that by "SQL expressions" we mean a **full fragment of a SQL string**, such as:: @@ -1853,12 +1853,12 @@ behavior of passing string values that become parameterized:: stmt = select([sometable]).where(sometable.c.somecolumn == 'value') The Core tutorial has long featured an example of the use of this technique, -using a :func:`~.sql.expression.select` construct where virtually all components of it +using a :func:`_expression.select` construct where virtually all components of it are specified as straight strings. However, despite this long-standing behavior and example, users are apparently surprised that this behavior exists, and when asking around the community, I was unable to find any user that was in fact *not* surprised that you can send a full string into a method -like :meth:`.Query.filter`. +like :meth:`_query.Query.filter`. So the change here is to encourage the user to qualify textual strings when composing SQL that is partially or fully composed from textual fragments. @@ -1905,26 +1905,26 @@ to get rid of the warnings we would rewrite our statement as follows:: ]).where(text("a = b")).select_from(text("sometable")) and as the warnings suggest, we can give our statement more specificity -about the text if we use :func:`.column` and :func:`.table`:: +about the text if we use :func:`_expression.column` and :func:`.table`:: from sqlalchemy import select, text, column, table stmt = select([column("a"), column("b")]).\ where(text("a = b")).select_from(table("sometable")) -Where note also that :func:`.table` and :func:`.column` can now +Where note also that :func:`.table` and :func:`_expression.column` can now be imported from "sqlalchemy" without the "sql" part. -The behavior here applies to :func:`~.sql.expression.select` as well as to key methods -on :class:`.Query`, including :meth:`.Query.filter`, -:meth:`.Query.from_statement` and :meth:`.Query.having`. +The behavior here applies to :func:`_expression.select` as well as to key methods +on :class:`_query.Query`, including :meth:`_query.Query.filter`, +:meth:`_query.Query.from_statement` and :meth:`_query.Query.having`. ORDER BY and GROUP BY are special cases ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ There is one case where usage of a string has special meaning, and as part of this change we have enhanced its functionality. When we have a -:func:`~.sql.expression.select` or :class:`.Query` that refers to some column name or named +:func:`_expression.select` or :class:`_query.Query` that refers to some column name or named label, we might want to GROUP BY and/or ORDER BY known columns or labels:: stmt = select([ @@ -1963,16 +1963,16 @@ OVER clause as well as a DISTINCT ON clause that refers to columns (e.g. the PostgreSQL syntax). We can still specify any arbitrary expression for ORDER BY or others using -:func:`.text`:: +:func:`_expression.text`:: stmt = select([users]).order_by(text("some special expression")) The upshot of the whole change is that SQLAlchemy now would like us to tell it when a string is sent that this string is explicitly -a :func:`.text` construct, or a column, table, etc., and if we use it as a +a :func:`_expression.text` construct, or a column, table, etc., and if we use it as a label name in an order by, group by, or other expression, SQLAlchemy expects that the string resolves to something known, else it should again -be qualified with :func:`.text` or similar. +be qualified with :func:`_expression.text` or similar. :ticket:`2992` @@ -1982,7 +1982,7 @@ Python-side defaults invoked for each row individually when using a multivalued -------------------------------------------------------------------------------------- Support for Python-side column defaults when using the multi-valued -version of :meth:`.Insert.values` were essentially not implemented, and +version of :meth:`_expression.Insert.values` were essentially not implemented, and would only work "by accident" in specific situations, when the dialect in use was using a non-positional (e.g. named) style of bound parameter, and when it was not necessary that a Python-side callable be invoked for each @@ -2078,8 +2078,8 @@ removals during iteration, and instead raises ``RuntimeError``. The INSERT...FROM SELECT construct now implies ``inline=True`` -------------------------------------------------------------- -Using :meth:`.Insert.from_select` now implies ``inline=True`` -on :func:`~.sql.expression.insert`. This helps to fix a bug where an +Using :meth:`_expression.Insert.from_select` now implies ``inline=True`` +on :func:`_expression.insert`. This helps to fix a bug where an INSERT...FROM SELECT construct would inadvertently be compiled as "implicit returning" on supporting backends, which would cause breakage in the case of an INSERT that inserts zero rows @@ -2095,7 +2095,7 @@ apply. Previously, there was a documentation note that one may prefer ``inline=True`` with INSERT..FROM SELECT as some databases don't support returning and therefore can't do "implicit" returning, but there's no reason an INSERT...FROM SELECT needs implicit returning -in any case. Regular explicit :meth:`.Insert.returning` should +in any case. Regular explicit :meth:`_expression.Insert.returning` should be used to return variable numbers of result rows if inserted data is needed. @@ -2106,8 +2106,8 @@ data is needed. ``autoload_with`` now implies ``autoload=True`` ----------------------------------------------- -A :class:`.Table` can be set up for reflection by passing -:paramref:`.Table.autoload_with` alone:: +A :class:`_schema.Table` can be set up for reflection by passing +:paramref:`_schema.Table.autoload_with` alone:: my_table = Table('my_table', metadata, autoload_with=some_engine) @@ -2119,7 +2119,7 @@ DBAPI exception wrapping and handle_error() event improvements -------------------------------------------------------------- SQLAlchemy's wrapping of DBAPI exceptions was not taking place in the -case where a :class:`.Connection` object was invalidated, and then tried +case where a :class:`_engine.Connection` object was invalidated, and then tried to reconnect and encountered an error; this has been resolved. Additionally, the recently added :meth:`.ConnectionEvents.handle_error` @@ -2128,8 +2128,8 @@ reconnect, and when :func:`.create_engine` is used given a custom connection function via :paramref:`.create_engine.creator`. The :class:`.ExceptionContext` object has a new datamember -:attr:`.ExceptionContext.engine` that will always refer to the :class:`.Engine` -in use, in those cases when the :class:`.Connection` object is not available +:attr:`.ExceptionContext.engine` that will always refer to the :class:`_engine.Engine` +in use, in those cases when the :class:`_engine.Connection` object is not available (e.g. on initial connect). @@ -2140,13 +2140,13 @@ in use, in those cases when the :class:`.Connection` object is not available ForeignKeyConstraint.columns is now a ColumnCollection ------------------------------------------------------ -:attr:`.ForeignKeyConstraint.columns` was previously a plain list -containing either strings or :class:`.Column` objects, depending on -how the :class:`.ForeignKeyConstraint` was constructed and whether it was -associated with a table. The collection is now a :class:`.ColumnCollection`, -and is only initialized after the :class:`.ForeignKeyConstraint` is -associated with a :class:`.Table`. A new accessor -:attr:`.ForeignKeyConstraint.column_keys` +:attr:`_schema.ForeignKeyConstraint.columns` was previously a plain list +containing either strings or :class:`_schema.Column` objects, depending on +how the :class:`_schema.ForeignKeyConstraint` was constructed and whether it was +associated with a table. The collection is now a :class:`_expression.ColumnCollection`, +and is only initialized after the :class:`_schema.ForeignKeyConstraint` is +associated with a :class:`_schema.Table`. A new accessor +:attr:`_schema.ForeignKeyConstraint.column_keys` is added to unconditionally return string keys for the local set of columns regardless of how the object was constructed or its current state. @@ -2157,14 +2157,14 @@ state. MetaData.sorted_tables accessor is "deterministic" -------------------------------------------------- -The sorting of tables resulting from the :attr:`.MetaData.sorted_tables` +The sorting of tables resulting from the :attr:`_schema.MetaData.sorted_tables` accessor is "deterministic"; the ordering should be the same in all cases regardless of Python hashing. This is done by first sorting the tables by name before passing them to the topological algorithm, which maintains that ordering as it iterates. Note that this change does **not** yet apply to the ordering applied -when emitting :meth:`.MetaData.create_all` or :meth:`.MetaData.drop_all`. +when emitting :meth:`_schema.MetaData.create_all` or :meth:`_schema.MetaData.drop_all`. :ticket:`3084` @@ -2194,16 +2194,16 @@ labeled uniquely. SQLite/Oracle have distinct methods for temporary table/view name reporting --------------------------------------------------------------------------- -The :meth:`.Inspector.get_table_names` and :meth:`.Inspector.get_view_names` +The :meth:`_reflection.Inspector.get_table_names` and :meth:`_reflection.Inspector.get_view_names` methods in the case of SQLite/Oracle would also return the names of temporary tables and views, which is not provided by any other dialect (in the case of MySQL at least it is not even possible). This logic has been moved -out to two new methods :meth:`.Inspector.get_temp_table_names` and -:meth:`.Inspector.get_temp_view_names`. +out to two new methods :meth:`_reflection.Inspector.get_temp_table_names` and +:meth:`_reflection.Inspector.get_temp_view_names`. Note that reflection of a specific named temporary table or temporary view, either by ``Table('name', autoload=True)`` or via methods like -:meth:`.Inspector.get_columns` continues to function for most if not all +:meth:`_reflection.Inspector.get_columns` continues to function for most if not all dialects. For SQLite specifically, there is a bug fix for UNIQUE constraint reflection from temp tables as well, which is :ticket:`3203`. @@ -2217,12 +2217,12 @@ Dialect Improvements and Changes - PostgreSQL Overhaul of ENUM type create/drop rules --------------------------------------- -The rules for PostgreSQL :class:`.postgresql.ENUM` have been made more strict +The rules for PostgreSQL :class:`_postgresql.ENUM` have been made more strict with regards to creating and dropping of the TYPE. -An :class:`.postgresql.ENUM` that is created **without** being explicitly -associated with a :class:`.MetaData` object will be created *and* dropped -corresponding to :meth:`.Table.create` and :meth:`.Table.drop`:: +An :class:`_postgresql.ENUM` that is created **without** being explicitly +associated with a :class:`_schema.MetaData` object will be created *and* dropped +corresponding to :meth:`_schema.Table.create` and :meth:`_schema.Table.drop`:: table = Table('sometable', metadata, Column('some_enum', ENUM('a', 'b', 'c', name='myenum')) @@ -2236,10 +2236,10 @@ above DROP operation will now fail. In order to accommodate the use case of a common shared enumerated type, the behavior of a metadata-associated enumeration has been enhanced. -An :class:`.postgresql.ENUM` that is created **with** being explicitly -associated with a :class:`.MetaData` object will *not* be created *or* dropped -corresponding to :meth:`.Table.create` and :meth:`.Table.drop`, with -the exception of :meth:`.Table.create` called with the ``checkfirst=True`` +An :class:`_postgresql.ENUM` that is created **with** being explicitly +associated with a :class:`_schema.MetaData` object will *not* be created *or* dropped +corresponding to :meth:`_schema.Table.create` and :meth:`_schema.Table.drop`, with +the exception of :meth:`_schema.Table.create` called with the ``checkfirst=True`` flag:: my_enum = ENUM('a', 'b', 'c', name='myenum', metadata=metadata) @@ -2268,7 +2268,7 @@ New PostgreSQL Table options Added support for PG table options TABLESPACE, ON COMMIT, WITH(OUT) OIDS, and INHERITS, when rendering DDL via -the :class:`.Table` construct. +the :class:`_schema.Table` construct. .. seealso:: @@ -2281,7 +2281,7 @@ the :class:`.Table` construct. New get_enums() method with PostgreSQL Dialect ---------------------------------------------- -The :func:`.inspect` method returns a :class:`.PGInspector` object in the +The :func:`_sa.inspect` method returns a :class:`.PGInspector` object in the case of PostgreSQL, which includes a new :meth:`.PGInspector.get_enums` method that returns information on all available ``ENUM`` types:: @@ -2305,10 +2305,10 @@ Changes are as follows: * the :class:`Table` construct with ``autoload=True`` will now match a name that exists in the database as a materialized view or foreign table. -* :meth:`.Inspector.get_view_names` will return plain and materialized view +* :meth:`_reflection.Inspector.get_view_names` will return plain and materialized view names. -* :meth:`.Inspector.get_table_names` does **not** change for PostgreSQL, it +* :meth:`_reflection.Inspector.get_table_names` does **not** change for PostgreSQL, it continues to return only the names of plain tables. * A new method :meth:`.PGInspector.get_foreign_table_names` is added which @@ -2626,7 +2626,7 @@ when using ODBC to avoid this issue entirely. SQL Server 2012 large text / binary types render as VARCHAR, NVARCHAR, VARBINARY -------------------------------------------------------------------------------- -The rendering of the :class:`.Text`, :class:`.UnicodeText`, and :class:`.LargeBinary` +The rendering of the :class:`_expression.TextClause`, :class:`.UnicodeText`, and :class:`.LargeBinary` types has been changed for SQL Server 2012 and greater, with options to control the behavior completely, based on deprecation guidelines from Microsoft. See :ref:`mssql_large_type_deprecation` for details. @@ -2640,7 +2640,7 @@ Improved support for CTEs in Oracle ----------------------------------- CTE support has been fixed up for Oracle, and there is also a new feature -:meth:`.CTE.with_suffixes` that can assist with Oracle's special directives:: +:meth:`_expression.CTE.with_suffixes` that can assist with Oracle's special directives:: included_parts = select([ part.c.sub_part, part.c.part, part.c.quantity diff --git a/doc/build/changelog/migration_11.rst b/doc/build/changelog/migration_11.rst index a96e0dd753..67dec39bcb 100644 --- a/doc/build/changelog/migration_11.rst +++ b/doc/build/changelog/migration_11.rst @@ -173,7 +173,7 @@ can instead be:: Changes regarding "unhashable" types, impacts deduping of ORM rows ------------------------------------------------------------------ -The :class:`.Query` object has a well-known behavior of "deduping" +The :class:`_query.Query` object has a well-known behavior of "deduping" returned rows that contain at least one ORM-mapped entity (e.g., a full mapped object, as opposed to individual column values). The primary purpose of this is so that the handling of entities works @@ -184,8 +184,8 @@ of filtering on additional columns. This deduplication relies upon the hashability of the elements within the row. With the introduction of PostgreSQL's special types like -:class:`.postgresql.ARRAY`, :class:`.postgresql.HSTORE` and -:class:`.postgresql.JSON`, the experience of types within rows being +:class:`_postgresql.ARRAY`, :class:`_postgresql.HSTORE` and +:class:`_postgresql.JSON`, the experience of types within rows being unhashable and encountering problems here is more prevalent than it was previously. @@ -247,7 +247,7 @@ Specific checks added for passing mapped classes, instances as SQL literals The typing system now has specific checks for passing of SQLAlchemy "inspectable" objects in contexts where they would otherwise be handled as literal values. Any SQLAlchemy built-in object that is legal to pass as a -SQL value (which is not already a :class:`.ClauseElement` instance) +SQL value (which is not already a :class:`_expression.ClauseElement` instance) includes a method ``__clause_element__()`` which provides a valid SQL expression for that object. For SQLAlchemy objects that don't provide this, such as mapped classes, mappers, and mapped @@ -327,7 +327,7 @@ of the ``None`` value on an attribute to be persisted as NULL, rather than omitting the column from the INSERT statement, which has the effect of using the column-level default. This allows a mapper-level configuration of the existing object-level technique of assigning -:func:`.sql.null` to the attribute. +:func:`_expression.null` to the attribute. .. seealso:: @@ -341,7 +341,7 @@ configuration of the existing object-level technique of assigning Further Fixes to single-table inheritance querying -------------------------------------------------- -Continuing from 1.0's :ref:`migration_3177`, the :class:`.Query` should +Continuing from 1.0's :ref:`migration_3177`, the :class:`_query.Query` should no longer inappropriately add the "single inheritance" criteria when the query is against a subquery expression such as an exists:: @@ -832,7 +832,7 @@ Improvements to the Query.correlate method with polymorphic entities In recent SQLAlchemy versions, the SQL generated by many forms of "polymorphic" queries has a more "flat" form than it used to, where a JOIN of several tables is no longer bundled into a subquery unconditionally. -To accommodate this, the :meth:`.Query.correlate` method now extracts the +To accommodate this, the :meth:`_query.Query.correlate` method now extracts the individual tables from such a polymorphic selectable and ensures that all are part of the "correlate" for the subquery. Assuming the ``Person/Manager/Engineer->Company`` setup from the mapping documentation, @@ -895,17 +895,17 @@ subquery, the polymorphic form is correctly used. Stringify of Query will consult the Session for the correct dialect ------------------------------------------------------------------- -Calling ``str()`` on a :class:`.Query` object will consult the :class:`.Session` +Calling ``str()`` on a :class:`_query.Query` object will consult the :class:`.Session` for the correct "bind" to use, in order to render the SQL that would be -passed to the database. In particular this allows a :class:`.Query` that +passed to the database. In particular this allows a :class:`_query.Query` that refers to dialect-specific SQL constructs to be renderable, assuming the -:class:`.Query` is associated with an appropriate :class:`.Session`. -Previously, this behavior would only take effect if the :class:`.MetaData` +:class:`_query.Query` is associated with an appropriate :class:`.Session`. +Previously, this behavior would only take effect if the :class:`_schema.MetaData` to which the mappings were associated were itself bound to the target -:class:`.Engine`. +:class:`_engine.Engine`. -If neither the underlying :class:`.MetaData` nor the :class:`.Session` are -associated with any bound :class:`.Engine`, then the fallback to the +If neither the underlying :class:`_schema.MetaData` nor the :class:`.Session` are +associated with any bound :class:`_engine.Engine`, then the fallback to the "default" dialect is used to generate the SQL string. .. seealso:: @@ -1021,7 +1021,7 @@ New "raise" / "raise_on_sql" loader strategies To assist with the use case of preventing unwanted lazy loads from occurring after a series of objects are loaded, the new "lazy='raise'" and "lazy='raise_on_sql'" strategies and -corresponding loader option :func:`.orm.raiseload` may be applied to a +corresponding loader option :func:`_orm.raiseload` may be applied to a relationship attribute which will cause it to raise ``InvalidRequestError`` when a non-eagerly-loaded attribute is accessed for read. The two variants test for either a lazy load of any variety, including those that would @@ -1051,12 +1051,12 @@ Mapper.order_by is deprecated ----------------------------- This old parameter from the very first versions of SQLAlchemy was part of -the original design of the ORM which featured the :class:`.Mapper` object +the original design of the ORM which featured the :class:`_orm.Mapper` object as a public-facing query structure. This role has long since been replaced -by the :class:`.Query` object, where we use :meth:`.Query.order_by` to +by the :class:`_query.Query` object, where we use :meth:`_query.Query.order_by` to indicate the ordering of results in a way that works consistently for any combination of SELECT statements, entities and SQL expressions. There are -many areas in which :paramref:`.Mapper.order_by` doesn't work as expected +many areas in which :paramref:`_orm.Mapper.order_by` doesn't work as expected (or what would be expected is not clear), such as when queries are combined into unions; these cases are not supported. @@ -1078,15 +1078,15 @@ The Python ``BaseException`` class is below that of ``Exception`` but is the identifiable base for system-level exceptions such as ``KeyboardInterrupt``, ``SystemExit``, and notably the ``GreenletExit`` exception that's used by eventlet and gevent. This exception class is now intercepted by the exception- -handling routines of :class:`.Connection`, and includes handling by the -:meth:`~.ConnectionEvents.handle_error` event. The :class:`.Connection` is now +handling routines of :class:`_engine.Connection`, and includes handling by the +:meth:`~.ConnectionEvents.handle_error` event. The :class:`_engine.Connection` is now **invalidated** by default in the case of a system level exception that is not a subclass of ``Exception``, as it is assumed an operation was interrupted and the connection may be in an unusable state. The MySQL drivers are most targeted by this change however the change is across all DBAPIs. Note that upon invalidation, the immediate DBAPI connection used by -:class:`.Connection` is disposed, and the :class:`.Connection`, if still +:class:`_engine.Connection` is disposed, and the :class:`_engine.Connection`, if still being used subsequent to the exception raise, will use a new DBAPI connection for subsequent operations upon next use; however, the state of any transaction in progress is lost and the appropriate ``.rollback()`` method @@ -1224,7 +1224,7 @@ Support for the SQL LATERAL keyword The LATERAL keyword is currently known to only be supported by PostgreSQL 9.3 and greater, however as it is part of the SQL standard support for this keyword -is added to Core. The implementation of :meth:`.Select.lateral` employs +is added to Core. The implementation of :meth:`_expression.Select.lateral` employs special logic beyond just rendering the LATERAL keyword to allow for correlation of tables that are derived from the same FROM clause as the selectable, e.g. lateral correlation:: @@ -1244,9 +1244,9 @@ selectable, e.g. lateral correlation:: :ref:`lateral_selects` - :class:`.Lateral` + :class:`_expression.Lateral` - :meth:`.Select.lateral` + :meth:`_expression.Select.lateral` :ticket:`2857` @@ -1257,7 +1257,7 @@ Support for TABLESAMPLE ----------------------- The SQL standard TABLESAMPLE can be rendered using the -:meth:`.FromClause.tablesample` method, which returns a :class:`.TableSample` +:meth:`_expression.FromClause.tablesample` method, which returns a :class:`_expression.TableSample` construct similar to an alias:: from sqlalchemy import func @@ -1288,7 +1288,7 @@ we mean that the database column will include whatever DDL directives the database provides in order to indicate an auto-incrementing integer identifier, such as the SERIAL keyword on PostgreSQL or AUTO_INCREMENT on MySQL, and additionally that the dialect will receive these generated values from the execution -of a :meth:`.Table.insert` construct using techniques appropriate to that +of a :meth:`_schema.Table.insert` construct using techniques appropriate to that backend. What's changed is that this feature no longer turns on automatically for a @@ -1322,7 +1322,7 @@ semantics unless a column is marked explicitly with ``autoincrement=True``:: ) In order to anticipate some potential backwards-incompatible scenarios, -the :meth:`.Table.insert` construct will perform more thorough checks +the :meth:`_schema.Table.insert` construct will perform more thorough checks for missing primary key values on composite primary key columns that don't have autoincrement set up; given a table such as:: @@ -1429,19 +1429,19 @@ information about the result rows to be returned. This allows a dramatic savin on Python overhead as well as much greater accuracy in linking ORM and Core SQL expressions to result rows. In 1.1, this reorganization has been taken further internally, and also has been made available to pure-text SQL -constructs via the use of the recently added :meth:`.TextClause.columns` method. +constructs via the use of the recently added :meth:`_expression.TextClause.columns` method. TextAsFrom.columns() now works positionally ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The :meth:`.TextClause.columns` method, added in 0.9, accepts column-based arguments +The :meth:`_expression.TextClause.columns` method, added in 0.9, accepts column-based arguments positionally; in 1.1, when all columns are passed positionally, the correlation of these columns to the ultimate result set is also performed positionally. The key advantage here is that textual SQL can now be linked to an ORM- level result set without the need to deal with ambiguous or duplicate column names, or with having to match labeling schemes to ORM-level labeling schemes. All that's needed now is the same ordering of columns within the textual SQL -and the column arguments passed to :meth:`.TextClause.columns`:: +and the column arguments passed to :meth:`_expression.TextClause.columns`:: from sqlalchemy import text @@ -1464,7 +1464,7 @@ Above, the textual SQL contains the column "id" three times, which would normally be ambiguous. Using the new feature, we can apply the mapped columns from the ``User`` and ``Address`` class directly, even linking the ``Address.user_id`` column to the ``users.id`` column in textual SQL -for fun, and the :class:`.Query` object will receive rows that are correctly +for fun, and the :class:`_query.Query` object will receive rows that are correctly targetable as needed, including for an eager load. This change is **backwards incompatible** with code that passes the columns @@ -1721,9 +1721,9 @@ NULL values as well as expression handling. :ref:`change_3547` - :class:`.types.JSON` + :class:`_types.JSON` - :class:`.postgresql.JSON` + :class:`_postgresql.JSON` :class:`.mysql.JSON` @@ -1734,7 +1734,7 @@ NULL values as well as expression handling. JSON "null" is inserted as expected with ORM operations, omitted when not present ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The :class:`.types.JSON` type and its descendant types :class:`.postgresql.JSON` +The :class:`_types.JSON` type and its descendant types :class:`_postgresql.JSON` and :class:`.mysql.JSON` have a flag :paramref:`.types.JSON.none_as_null` which when set to True indicates that the Python value ``None`` should translate into a SQL NULL rather than a JSON NULL value. This flag defaults to False, @@ -1790,14 +1790,14 @@ would be ignored in all cases:: MyObject, [{"json_value": None}]) -The :class:`.types.JSON` type now implements the +The :class:`_types.JSON` type now implements the :attr:`.TypeEngine.should_evaluate_none` flag, indicating that ``None`` should not be ignored here; it is configured automatically based on the value of :paramref:`.types.JSON.none_as_null`. Thanks to :ticket:`3061`, we can differentiate when the value ``None`` is actively set by the user versus when it was never set at all. -The feature applies as well to the new base :class:`.types.JSON` type +The feature applies as well to the new base :class:`_types.JSON` type and its descendant types. :ticket:`3514` @@ -1808,8 +1808,8 @@ New JSON.NULL Constant Added ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To ensure that an application can always have full control at the value level -of whether a :class:`.types.JSON`, :class:`.postgresql.JSON`, :class:`.mysql.JSON`, -or :class:`.postgresql.JSONB` column +of whether a :class:`_types.JSON`, :class:`_postgresql.JSON`, :class:`.mysql.JSON`, +or :class:`_postgresql.JSONB` column should receive a SQL NULL or JSON ``"null"`` value, the constant :attr:`.types.JSON.NULL` has been added, which in conjunction with :func:`.null` can be used to determine fully between SQL NULL and @@ -1825,7 +1825,7 @@ to:: session.add_all([obj1, obj2]) session.commit() -The feature applies as well to the new base :class:`.types.JSON` type +The feature applies as well to the new base :class:`_types.JSON` type and its descendant types. :ticket:`3514` @@ -1835,15 +1835,15 @@ and its descendant types. Array support added to Core; new ANY and ALL operators ------------------------------------------------------ -Along with the enhancements made to the PostgreSQL :class:`.postgresql.ARRAY` -type described in :ref:`change_3503`, the base class of :class:`.postgresql.ARRAY` -itself has been moved to Core in a new class :class:`.types.ARRAY`. +Along with the enhancements made to the PostgreSQL :class:`_postgresql.ARRAY` +type described in :ref:`change_3503`, the base class of :class:`_postgresql.ARRAY` +itself has been moved to Core in a new class :class:`_types.ARRAY`. Arrays are part of the SQL standard, as are several array-oriented functions such as ``array_agg()`` and ``unnest()``. In support of these constructs for not just PostgreSQL but also potentially for other array-capable backends in the future such as DB2, the majority of array logic for SQL expressions -is now in Core. The :class:`.types.ARRAY` type still **only works on +is now in Core. The :class:`_types.ARRAY` type still **only works on PostgreSQL**, however it can be used directly, supporting special array use cases such as indexed access, as well as support for the ANY and ALL:: @@ -1855,11 +1855,11 @@ use cases such as indexed access, as well as support for the ANY and ALL:: expr = mytable.c.data[5].any(12) -In support of ANY and ALL, the :class:`.types.ARRAY` type retains the same +In support of ANY and ALL, the :class:`_types.ARRAY` type retains the same :meth:`.types.ARRAY.Comparator.any` and :meth:`.types.ARRAY.Comparator.all` methods from the PostgreSQL type, but also exports these operations to new -standalone operator functions :func:`.sql.expression.any_` and -:func:`.sql.expression.all_`. These two functions work in more +standalone operator functions :func:`_expression.any_` and +:func:`_expression.all_`. These two functions work in more of the traditional SQL way, allowing a right-side expression form such as:: @@ -1868,11 +1868,11 @@ as:: select([mytable]).where(12 == any_(mytable.c.data[5])) For the PostgreSQL-specific operators "contains", "contained_by", and -"overlaps", one should continue to use the :class:`.postgresql.ARRAY` -type directly, which provides all functionality of the :class:`.types.ARRAY` +"overlaps", one should continue to use the :class:`_postgresql.ARRAY` +type directly, which provides all functionality of the :class:`_types.ARRAY` type as well. -The :func:`.sql.expression.any_` and :func:`.sql.expression.all_` operators +The :func:`_expression.any_` and :func:`_expression.all_` operators are open-ended at the Core level, however their interpretation by backend databases is limited. On the PostgreSQL backend, the two operators **only accept array values**. Whereas on the MySQL backend, they @@ -1892,15 +1892,15 @@ such as:: New Function features, "WITHIN GROUP", array_agg and set aggregate functions ---------------------------------------------------------------------------- -With the new :class:`.types.ARRAY` type we can also implement a pre-typed +With the new :class:`_types.ARRAY` type we can also implement a pre-typed function for the ``array_agg()`` SQL function that returns an array, -which is now available using :class:`.array_agg`:: +which is now available using :class:`_functions.array_agg`:: from sqlalchemy import func stmt = select([func.array_agg(table.c.value)]) A PostgreSQL element for an aggregate ORDER BY is also added via -:class:`.postgresql.aggregate_order_by`:: +:class:`_postgresql.aggregate_order_by`:: from sqlalchemy.dialects.postgresql import aggregate_order_by expr = func.array_agg(aggregate_order_by(table.c.a, table.c.b.desc())) @@ -1910,8 +1910,8 @@ Producing:: SELECT array_agg(table1.a ORDER BY table1.b DESC) AS array_agg_1 FROM table1 -The PG dialect itself also provides an :func:`.postgresql.array_agg` wrapper to -ensure the :class:`.postgresql.ARRAY` type:: +The PG dialect itself also provides an :func:`_postgresql.array_agg` wrapper to +ensure the :class:`_postgresql.ARRAY` type:: from sqlalchemy.dialects.postgresql import array_agg stmt = select([array_agg(table.c.value).contains('foo')]) @@ -1952,7 +1952,7 @@ and :class:`.Boolean` which, in addition to corresponding to a database type, also generate either a CHECK constraint or in the case of PostgreSQL ENUM a new CREATE TYPE statement, will now work automatically with :class:`.TypeDecorator` recipes. Previously, a :class:`.TypeDecorator` for -an :class:`.postgresql.ENUM` had to look like this:: +an :class:`_postgresql.ENUM` had to look like this:: # old way class MyEnum(TypeDecorator, SchemaType): @@ -1977,11 +1977,11 @@ Multi-Tenancy Schema Translation for Table objects -------------------------------------------------- To support the use case of an application that uses the same set of -:class:`.Table` objects in many schemas, such as schema-per-user, a new +:class:`_schema.Table` objects in many schemas, such as schema-per-user, a new execution option :paramref:`.Connection.execution_options.schema_translate_map` -is added. Using this mapping, a set of :class:`.Table` +is added. Using this mapping, a set of :class:`_schema.Table` objects can be made on a per-connection basis to refer to any set of schemas -instead of the :paramref:`.Table.schema` to which they were assigned. The +instead of the :paramref:`_schema.Table.schema` to which they were assigned. The translation works for DDL and SQL generation, as well as with the ORM. For example, if the ``User`` class were assigned the schema "per_user":: @@ -2039,11 +2039,11 @@ to this dialect/compiler without impacting behaviors on real dialects. The type_coerce function is now a persistent SQL element -------------------------------------------------------- -The :func:`.expression.type_coerce` function previously would return +The :func:`_expression.type_coerce` function previously would return an object either of type :class:`.BindParameter` or :class:`.Label`, depending on the input. An effect this would have was that in the case where expression transformations were used, such as the conversion of an element from a -:class:`.Column` to a :class:`.BindParameter` that's critical to ORM-level +:class:`_schema.Column` to a :class:`.BindParameter` that's critical to ORM-level lazy loading, the type coercion information would not be used since it would have been lost already. @@ -2088,13 +2088,13 @@ table to an integer "id" column on the other:: id = Column('id', Integer, primary_key=True) person_id = Column('person_id', Integer) -Above, in the :paramref:`.relationship.primaryjoin` expression, we are +Above, in the :paramref:`_orm.relationship.primaryjoin` expression, we are using :func:`.type_coerce` to handle bound parameters passed via lazyloading as integers, since we already know these will come from our ``StringAsInt`` type which maintains the value as an integer in Python. We are then using :func:`.cast` so that as a SQL expression, the VARCHAR "id" column will be CAST to an integer for a regular non- -converted join as with :meth:`.Query.join` or :func:`.orm.joinedload`. +converted join as with :meth:`_query.Query.join` or :func:`_orm.joinedload`. That is, a joinedload of ``.pets`` looks like:: SELECT person.id AS person_id, pets_1.id AS pets_1_id, @@ -2145,7 +2145,7 @@ Key Behavioral Changes - ORM JSON Columns will not insert JSON NULL if no value is supplied and no default is established -------------------------------------------------------------------------------------------- -As detailed in :ref:`change_3514`, :class:`.types.JSON` will not render +As detailed in :ref:`change_3514`, :class:`_types.JSON` will not render a JSON "null" value if the value is missing entirely. To prevent SQL NULL, a default should be set up. Given the following mapping:: @@ -2177,7 +2177,7 @@ Or, ensure the value is present on the object:: Note that setting ``None`` for the default is the same as omitting it entirely; the :paramref:`.types.JSON.none_as_null` flag does not impact the value of ``None`` -passed to :paramref:`.Column.default` or :paramref:`.Column.server_default`:: +passed to :paramref:`_schema.Column.default` or :paramref:`_schema.Column.server_default`:: # default=None is the same as omitting it entirely, does not apply JSON NULL json_value = Column(JSON(none_as_null=False), nullable=False, default=None) @@ -2216,7 +2216,7 @@ would not be affected, as the additional columns are not included in the result in any case, but the columns are unnecessary. Additionally, when the PostgreSQL DISTINCT ON format is used by passing -expressions to :meth:`.Query.distinct`, the above "column adding" logic +expressions to :meth:`_query.Query.distinct`, the above "column adding" logic is disabled entirely. When the query is being bundled into a subquery for the purposes of @@ -2231,7 +2231,7 @@ remains unchanged. Same-named @validates decorators will now raise an exception ------------------------------------------------------------ -The :func:`.orm.validates` decorator is only intended to be created once +The :func:`_orm.validates` decorator is only intended to be created once per class for a particular attribute name. Creating more than one now raises an error, whereas previously it would silently pick only the last defined validator:: @@ -2266,7 +2266,7 @@ Key Behavioral Changes - Core TextClause.columns() will match columns positionally, not by name, when passed positionally ------------------------------------------------------------------------------------------- -The new behavior of the :meth:`.TextClause.columns` method, which itself +The new behavior of the :meth:`_expression.TextClause.columns` method, which itself was recently added as of the 0.9 series, is that when columns are passed positionally without any additional keyword arguments, they are linked to the ultimate result set @@ -2276,8 +2276,8 @@ illustrating the columns being passed in the same order as that of the textual SQL statement, as would seem intuitive, even though the internals weren't checking for this. -An application that is using this method by passing :class:`.Column` objects -to it positionally must ensure that the position of those :class:`.Column` +An application that is using this method by passing :class:`_schema.Column` objects +to it positionally must ensure that the position of those :class:`_schema.Column` objects matches the position in which these columns are stated in the textual SQL. @@ -2302,7 +2302,7 @@ Possibly more likely, a statement that worked like this:: is now slightly risky, as the "*" specification will generally deliver columns in the order in which they are present in the table itself. If the structure of the table changes due to schema changes, this ordering may no longer be the same. -Therefore when using :meth:`.TextClause.columns`, it's advised to list out +Therefore when using :meth:`_expression.TextClause.columns`, it's advised to list out the desired columns explicitly in the textual SQL, though it's no longer necessary to worry about the names themselves in the textual SQL. @@ -2315,7 +2315,7 @@ necessary to worry about the names themselves in the textual SQL. String server_default now literal quoted ---------------------------------------- -A server default passed to :paramref:`.Column.server_default` as a plain +A server default passed to :paramref:`_schema.Column.server_default` as a plain Python string that has quotes embedded is now passed through the literal quoting system:: @@ -2403,9 +2403,9 @@ Support for INSERT..ON CONFLICT (DO UPDATE | DO NOTHING) The ``ON CONFLICT`` clause of ``INSERT`` added to PostgreSQL as of version 9.5 is now supported using a PostgreSQL-specific version of the -:class:`~.sql.expression.Insert` object, via :func:`sqlalchemy.dialects.postgresql.dml.insert`. -This :class:`~.sql.expression.Insert` subclass adds two new methods :meth:`.Insert.on_conflict_do_update` -and :meth:`.Insert.on_conflict_do_nothing` which implement the full syntax +:class:`_expression.Insert` object, via :func:`sqlalchemy.dialects.postgresql.dml.insert`. +This :class:`_expression.Insert` subclass adds two new methods :meth:`_expression.Insert.on_conflict_do_update` +and :meth:`_expression.Insert.on_conflict_do_nothing` which implement the full syntax supported by PostgreSQL 9.5 in this area:: from sqlalchemy.dialects.postgresql import insert @@ -2441,9 +2441,9 @@ As described in :ref:`change_3499`, the ORM relies upon being able to produce a hash function for column values when a query's selected entities mixes full ORM entities with column expressions. The ``hashable=False`` flag is now correctly set on all of PG's "data structure" types, including -:class:`.postgresql.ARRAY` and :class:`.postgresql.JSON`. -The :class:`.JSONB` and :class:`.HSTORE` -types already included this flag. For :class:`.postgresql.ARRAY`, +:class:`_postgresql.ARRAY` and :class:`_postgresql.JSON`. +The :class:`_postgresql.JSONB` and :class:`.HSTORE` +types already included this flag. For :class:`_postgresql.ARRAY`, this is conditional based on the :paramref:`.postgresql.ARRAY.as_tuple` flag, however it should no longer be necessary to set this flag in order to have an array value present in a composed ORM row. @@ -2461,15 +2461,15 @@ in order to have an array value present in a composed ORM row. Correct SQL Types are Established from Indexed Access of ARRAY, JSON, HSTORE ---------------------------------------------------------------------------- -For all three of :class:`~.postgresql.ARRAY`, :class:`~.postgresql.JSON` and :class:`.HSTORE`, +For all three of :class:`_postgresql.ARRAY`, :class:`_postgresql.JSON` and :class:`.HSTORE`, the SQL type assigned to the expression returned by indexed access, e.g. ``col[someindex]``, should be correct in all cases. This includes: -* The SQL type assigned to indexed access of an :class:`~.postgresql.ARRAY` takes into - account the number of dimensions configured. An :class:`~.postgresql.ARRAY` with three - dimensions will return a SQL expression with a type of :class:`~.postgresql.ARRAY` of +* The SQL type assigned to indexed access of an :class:`_postgresql.ARRAY` takes into + account the number of dimensions configured. An :class:`_postgresql.ARRAY` with three + dimensions will return a SQL expression with a type of :class:`_postgresql.ARRAY` of one less dimension. Given a column with type ``ARRAY(Integer, dimensions=3)``, we can now perform this expression:: @@ -2479,24 +2479,24 @@ This includes: type :class:`.Integer` where we could no longer perform indexed access for the remaining dimensions, unless we used :func:`.cast` or :func:`.type_coerce`. -* The :class:`~.postgresql.JSON` and :class:`~.postgresql.JSONB` types now mirror what PostgreSQL +* The :class:`_postgresql.JSON` and :class:`_postgresql.JSONB` types now mirror what PostgreSQL itself does for indexed access. This means that all indexed access for - a :class:`~.postgresql.JSON` or :class:`~.postgresql.JSONB` type returns an expression that itself - is *always* :class:`~.postgresql.JSON` or :class:`~.postgresql.JSONB` itself, unless the + a :class:`_postgresql.JSON` or :class:`_postgresql.JSONB` type returns an expression that itself + is *always* :class:`_postgresql.JSON` or :class:`_postgresql.JSONB` itself, unless the :attr:`~.postgresql.JSON.Comparator.astext` modifier is used. This means that whether the indexed access of the JSON structure ultimately refers to a string, list, number, or other JSON structure, PostgreSQL always considers it to be JSON itself unless it is explicitly cast differently. Like - the :class:`~.postgresql.ARRAY` type, this means that it is now straightforward + the :class:`_postgresql.ARRAY` type, this means that it is now straightforward to produce JSON expressions with multiple levels of indexed access:: json_expr = json_col['key1']['attr1'][5] * The "textual" type that is returned by indexed access of :class:`.HSTORE` as well as the "textual" type that is returned by indexed access of - :class:`~.postgresql.JSON` and :class:`~.postgresql.JSONB` in conjunction with the + :class:`_postgresql.JSON` and :class:`_postgresql.JSONB` in conjunction with the :attr:`~.postgresql.JSON.Comparator.astext` modifier is now configurable; it defaults - to :class:`.Text` in both cases but can be set to a user-defined + to :class:`_expression.TextClause` in both cases but can be set to a user-defined type using the :paramref:`.postgresql.JSON.astext_type` or :paramref:`.postgresql.HSTORE.text_type` parameters. @@ -2513,8 +2513,8 @@ The JSON cast() operation now requires ``.astext`` is called explicitly ----------------------------------------------------------------------- As part of the changes in :ref:`change_3503`, the workings of the -:meth:`.ColumnElement.cast` operator on :class:`.postgresql.JSON` and -:class:`.postgresql.JSONB` no longer implicitly invoke the +:meth:`_expression.ColumnElement.cast` operator on :class:`_postgresql.JSON` and +:class:`_postgresql.JSONB` no longer implicitly invoke the :attr:`.postgresql.JSON.Comparator.astext` modifier; PostgreSQL's JSON/JSONB types support CAST operations to each other without the "astext" aspect. @@ -2569,8 +2569,8 @@ Check constraints now reflect ----------------------------- The PostgreSQL dialect now supports reflection of CHECK constraints -both within the method :meth:`.Inspector.get_check_constraints` as well -as within :class:`.Table` reflection within the :attr:`.Table.constraints` +both within the method :meth:`_reflection.Inspector.get_check_constraints` as well +as within :class:`_schema.Table` reflection within the :attr:`_schema.Table.constraints` collection. "Plain" and "Materialized" views can be inspected separately @@ -2593,7 +2593,7 @@ Added tablespace option to Index The :class:`.Index` object now accepts the argument ``postgresql_tablespace`` in order to specify TABLESPACE, the same way as accepted by the -:class:`.Table` object. +:class:`_schema.Table` object. .. seealso:: @@ -2651,7 +2651,7 @@ A new type :class:`.mysql.JSON` is added to the MySQL dialect supporting the JSON type newly added to MySQL 5.7. This type provides both persistence of JSON as well as rudimentary indexed-access using the ``JSON_EXTRACT`` function internally. An indexable JSON column that works across MySQL -and PostgreSQL can be achieved by using the :class:`.types.JSON` datatype +and PostgreSQL can be achieved by using the :class:`_types.JSON` datatype common to both MySQL and PostgreSQL. .. seealso:: @@ -2733,7 +2733,7 @@ use the :class:`.PrimaryKeyConstraint` construct explicitly (1.1.0b2) Along with the change :ref:`change_3216`, composite primary keys with or without auto increment are now easier to specify; -:paramref:`.Column.autoincrement` +:paramref:`_schema.Column.autoincrement` now defaults to the value ``"auto"`` and the ``autoincrement=False`` directives are no longer needed:: @@ -2801,12 +2801,12 @@ case. Improved Support for Remote Schemas ----------------------------------- -The SQLite dialect now implements :meth:`.Inspector.get_schema_names` +The SQLite dialect now implements :meth:`_reflection.Inspector.get_schema_names` and additionally has improved support for tables and indexes that are created and reflected from a remote schema, which in SQLite is a database that is assigned a name via the ``ATTACH`` statement; previously, the``CREATE INDEX`` DDL didn't work correctly for a schema-bound table -and the :meth:`.Inspector.get_foreign_keys` method will now indicate the +and the :meth:`_reflection.Inspector.get_foreign_keys` method will now indicate the given schema in the results. Cross-schema foreign keys aren't supported. .. _change_3629: @@ -2825,17 +2825,17 @@ Check constraints now reflect ----------------------------- The SQLite dialect now supports reflection of CHECK constraints -both within the method :meth:`.Inspector.get_check_constraints` as well -as within :class:`.Table` reflection within the :attr:`.Table.constraints` +both within the method :meth:`_reflection.Inspector.get_check_constraints` as well +as within :class:`_schema.Table` reflection within the :attr:`_schema.Table.constraints` collection. ON DELETE and ON UPDATE foreign key phrases now reflect ------------------------------------------------------- -The :class:`.Inspector` will now include ON DELETE and ON UPDATE +The :class:`_reflection.Inspector` will now include ON DELETE and ON UPDATE phrases from foreign key constraints on the SQLite dialect, and the -:class:`.ForeignKeyConstraint` object as reflected as part of a -:class:`.Table` will also indicate these phrases. +:class:`_schema.ForeignKeyConstraint` object as reflected as part of a +:class:`_schema.Table` will also indicate these phrases. Dialect Improvements and Changes - SQL Server ============================================= @@ -2867,7 +2867,7 @@ parameters. The four standard levels are supported as well as String / varlength types no longer represent "max" explicitly on reflection --------------------------------------------------------------------------- -When reflecting a type such as :class:`.String`, :class:`.Text`, etc. +When reflecting a type such as :class:`.String`, :class:`_expression.TextClause`, etc. which includes a length, an "un-lengthed" type under SQL Server would copy the "length" parameter as the value ``"max"``:: diff --git a/doc/build/changelog/migration_12.rst b/doc/build/changelog/migration_12.rst index 47f6d43afc..9369886230 100644 --- a/doc/build/changelog/migration_12.rst +++ b/doc/build/changelog/migration_12.rst @@ -40,17 +40,17 @@ New Features and Improvements - ORM The :mod:`sqlalchemy.ext.baked` extension, first introduced in the 1.0 series, allows for the construction of a so-called :class:`.BakedQuery` object, -which is an object that generates a :class:`.Query` object in conjunction +which is an object that generates a :class:`_query.Query` object in conjunction with a cache key representing the structure of the query; this cache key is then linked to the resulting string SQL statement so that subsequent use of another :class:`.BakedQuery` with the same structure will bypass all the -overhead of building the :class:`.Query` object, building the core -:func:`~.sql.expression.select` object within, as well as the compilation of the :func:`~.sql.expression.select` +overhead of building the :class:`_query.Query` object, building the core +:func:`_expression.select` object within, as well as the compilation of the :func:`_expression.select` into a string, cutting out well the majority of function call overhead normally -associated with constructing and emitting an ORM :class:`.Query` object. +associated with constructing and emitting an ORM :class:`_query.Query` object. The :class:`.BakedQuery` is now used by default by the ORM when it generates -a "lazy" query for the lazy load of a :func:`.relationship` construct, e.g. +a "lazy" query for the lazy load of a :func:`_orm.relationship` construct, e.g. that of the default ``lazy="select"`` relationship loader strategy. This will allow for a significant reduction in function calls within the scope of an application's use of lazy load queries to load collections and related @@ -62,9 +62,9 @@ for objects that have additional loader options in effect subsequent to the lazy load. The caching behavior can be disabled on a per-relationship basis using the -:paramref:`.relationship.bake_queries` flag, which is available for +:paramref:`_orm.relationship.bake_queries` flag, which is available for very unusual cases, such as a relationship that uses a custom -:class:`.Query` implementation that's not compatible with caching. +:class:`_query.Query` implementation that's not compatible with caching. :ticket:`3954` @@ -138,11 +138,11 @@ The above SELECT statement includes these advantages: significantly * Because the query only fetches for a given list of primary key identifiers, - "selectin" loading is potentially compatible with :meth:`.Query.yield_per` to + "selectin" loading is potentially compatible with :meth:`_query.Query.yield_per` to operate on chunks of a SELECT result at a time, provided that the database driver allows for multiple, simultaneous cursors (SQLite, PostgreSQL; **not** MySQL drivers or SQL Server ODBC drivers). Neither joined eager - loading nor subquery eager loading are compatible with :meth:`.Query.yield_per`. + loading nor subquery eager loading are compatible with :meth:`_query.Query.yield_per`. The disadvantages of selectin eager loading are potentially large SQL queries, with large lists of IN parameters. The list of IN parameters themselves @@ -217,9 +217,9 @@ are loaded with additional SELECT statements: ORM attributes that can receive ad-hoc SQL expressions ------------------------------------------------------ -A new ORM attribute type :func:`.orm.query_expression` is added which -is similar to :func:`.orm.deferred`, except its SQL expression -is determined at query time using a new option :func:`.orm.with_expression`; +A new ORM attribute type :func:`_orm.query_expression` is added which +is similar to :func:`_orm.deferred`, except its SQL expression +is determined at query time using a new option :func:`_orm.with_expression`; if not specified, the attribute defaults to ``None``:: from sqlalchemy.orm import query_expression @@ -250,7 +250,7 @@ if not specified, the attribute defaults to ``None``:: ORM Support of multiple-table deletes ------------------------------------- -The ORM :meth:`.Query.delete` method supports multiple-table criteria +The ORM :meth:`_query.Query.delete` method supports multiple-table criteria for DELETE, as introduced in :ref:`change_959`. The feature works in the same manner as multiple-table criteria for UPDATE, first introduced in 0.8 and described at :ref:`change_orm_2365`. @@ -277,7 +277,7 @@ Support for bulk updates of hybrids, composites Both hybrid attributes (e.g. :mod:`sqlalchemy.ext.hybrid`) as well as composite attributes (:ref:`mapper_composite`) now support being used in the -SET clause of an UPDATE statement when using :meth:`.Query.update`. +SET clause of an UPDATE statement when using :meth:`_query.Query.update`. For hybrids, simple expressions can be used directly, or the new decorator :meth:`.hybrid_property.update_expression` can be used to break a value @@ -477,8 +477,8 @@ Added "for update" arguments to Session.refresh ------------------------------------------------ Added new argument :paramref:`.Session.refresh.with_for_update` to the -:meth:`.Session.refresh` method. When the :meth:`.Query.with_lockmode` -method were deprecated in favor of :meth:`.Query.with_for_update`, +:meth:`.Session.refresh` method. When the :meth:`_query.Query.with_lockmode` +method were deprecated in favor of :meth:`_query.Query.with_for_update`, the :meth:`.Session.refresh` method was never updated to reflect the new option:: @@ -486,7 +486,7 @@ the new option:: The :paramref:`.Session.refresh.with_for_update` argument accepts a dictionary of options that will be passed as the same arguments which are sent to -:meth:`.Query.with_for_update`:: +:meth:`_query.Query.with_for_update`:: session.refresh(some_objects, with_for_update={"read": True}) @@ -858,8 +858,8 @@ Support for SQL Comments on Table, Column, includes DDL, reflection ------------------------------------------------------------------- The Core receives support for string comments associated with tables -and columns. These are specified via the :paramref:`.Table.comment` and -:paramref:`.Column.comment` arguments:: +and columns. These are specified via the :paramref:`_schema.Table.comment` and +:paramref:`_schema.Column.comment` arguments:: Table( 'my_table', metadata, @@ -869,9 +869,9 @@ and columns. These are specified via the :paramref:`.Table.comment` and Above, DDL will be rendered appropriately upon table create to associate the above comments with the table/ column within the schema. When -the above table is autoloaded or inspected with :meth:`.Inspector.get_columns`, +the above table is autoloaded or inspected with :meth:`_reflection.Inspector.get_columns`, the comments are included. The table comment is also available independently -using the :meth:`.Inspector.get_table_comment` method. +using the :meth:`_reflection.Inspector.get_table_comment` method. Current backend support includes MySQL, PostgreSQL, and Oracle. @@ -882,7 +882,7 @@ Current backend support includes MySQL, PostgreSQL, and Oracle. Multiple-table criteria support for DELETE ------------------------------------------ -The :class:`.Delete` construct now supports multiple-table criteria, +The :class:`_expression.Delete` construct now supports multiple-table criteria, implemented for those backends which support it, currently these are PostgreSQL, MySQL and Microsoft SQL Server (support is also added to the currently non-working Sybase dialect). The feature works in the same @@ -1032,8 +1032,8 @@ Parameter helper for multi-valued INSERT with contextual default generator A default generation function, e.g. that described at :ref:`context_default_functions`, can look at the current parameters relevant to the statement via the :attr:`.DefaultExecutionContext.current_parameters` -attribute. However, in the case of a :class:`~.sql.expression.Insert` construct that specifies -multiple VALUES clauses via the :meth:`.Insert.values` method, the user-defined +attribute. However, in the case of a :class:`_expression.Insert` construct that specifies +multiple VALUES clauses via the :meth:`_expression.Insert.values` method, the user-defined function is called multiple times, once for each parameter set, however there was no way to know which subset of keys in :attr:`.DefaultExecutionContext.current_parameters` apply to that column. A @@ -1108,7 +1108,7 @@ able to load within the scope of the event. Fixed issue involving single-table inheritance with ``select_from()`` --------------------------------------------------------------------- -The :meth:`.Query.select_from` method now honors the single-table inheritance +The :meth:`_query.Query.select_from` method now honors the single-table inheritance column discriminator when generating SQL; previously, only the expressions in the query column list would be taken into account. @@ -1120,7 +1120,7 @@ Would generate SQL as:: SELECT employee.id FROM employee WHERE employee.type IN ('manager') -However, if ``Manager`` were only specified by :meth:`.Query.select_from` +However, if ``Manager`` were only specified by :meth:`_query.Query.select_from` and not in the columns list, the discriminator would not be added:: sess.query(func.count(1)).select_from(Manager) @@ -1129,7 +1129,7 @@ would generate:: SELECT count(1) FROM employee -With the fix, :meth:`.Query.select_from` now works correctly and we get:: +With the fix, :meth:`_query.Query.select_from` now works correctly and we get:: SELECT count(1) FROM employee WHERE employee.type IN ('manager') @@ -1305,8 +1305,8 @@ beta testing, it can be restored with a deprecation. Refinements to post_update in conjunction with onupdate ------------------------------------------------------- -A relationship that uses the :paramref:`.relationship.post_update` feature -will now interact better with a column that has an :paramref:`.Column.onupdate` +A relationship that uses the :paramref:`_orm.relationship.post_update` feature +will now interact better with a column that has an :paramref:`_schema.Column.onupdate` value set. If an object is inserted with an explicit value for the column, it is re-stated during the UPDATE so that the "onupdate" rule does not overwrite it:: @@ -1455,7 +1455,7 @@ As most user-defined operators tend to be "comparison" operators, often one of the many special operators defined by PostgreSQL, the :paramref:`.Operators.op.is_comparison` flag has been repaired to follow its documented behavior of allowing the return type to be :class:`.Boolean` -in all cases, including for :class:`.ARRAY` and :class:`.JSON`:: +in all cases, including for :class:`_types.ARRAY` and :class:`_types.JSON`:: >>> column('x', types.String(50)).op('-%>', is_comparison=True)(None).type Boolean() @@ -1477,11 +1477,11 @@ for on-the-fly boolean operators:: Percent signs in literal_column() now conditionally escaped ----------------------------------------------------------- -The :obj:`.literal_column` construct now escapes percent sign characters +The :obj:`_expression.literal_column` construct now escapes percent sign characters conditionally, based on whether or not the DBAPI in use makes use of a percent-sign-sensitive paramstyle or not (e.g. 'format' or 'pyformat'). -Previously, it was not possible to produce a :obj:`.literal_column` +Previously, it was not possible to produce a :obj:`_expression.literal_column` construct that stated a single percent sign:: >>> from sqlalchemy import literal_column @@ -1513,7 +1513,7 @@ is also refined to only occur when appropriate. The column-level COLLATE keyword now quotes the collation name -------------------------------------------------------------- -A bug in the :func:`.expression.collate` and :meth:`.ColumnOperators.collate` +A bug in the :func:`_expression.collate` and :meth:`.ColumnOperators.collate` functions, used to supply ad-hoc column collations at the statement level, is fixed, where a case sensitive name would not be quoted:: @@ -1547,7 +1547,7 @@ poorly, particularly with INSERT statements. To alleviate this, psycopg2 has added `Fast Execution Helpers `_ which rework statements into fewer server round trips by sending multiple DML statements in batch. SQLAlchemy 1.2 now includes support for these -helpers to be used transparently whenever the :class:`.Engine` makes use +helpers to be used transparently whenever the :class:`_engine.Engine` makes use of ``cursor.executemany()`` to invoke a statement against multiple parameter sets. The feature is off by default and can be enabled using the ``use_batch_mode`` argument on :func:`.create_engine`:: @@ -1572,7 +1572,7 @@ Support for fields specification in INTERVAL, including full reflection The "fields" specifier in PostgreSQL's INTERVAL datatype allows specification of which fields of the interval to store, including such values as "YEAR", -"MONTH", "YEAR TO MONTH", etc. The :class:`.postgresql.INTERVAL` datatype +"MONTH", "YEAR TO MONTH", etc. The :class:`_postgresql.INTERVAL` datatype now allows these values to be specified:: from sqlalchemy.dialects.postgresql import INTERVAL @@ -1604,8 +1604,8 @@ Support for INSERT..ON DUPLICATE KEY UPDATE The ``ON DUPLICATE KEY UPDATE`` clause of ``INSERT`` supported by MySQL is now supported using a MySQL-specific version of the -:class:`~.expression.Insert` object, via :func:`sqlalchemy.dialects.mysql.dml.insert`. -This :class:`~.expression.Insert` subclass adds a new method +:class:`_expression.Insert` object, via :func:`sqlalchemy.dialects.mysql.dml.insert`. +This :class:`_expression.Insert` subclass adds a new method :meth:`~.mysql.dml.Insert.on_duplicate_key_update` that implements MySQL's syntax:: from sqlalchemy.dialects.mysql import insert @@ -1708,11 +1708,11 @@ Oracle Unique, Check constraints now reflected ---------------------------------------------- UNIQUE and CHECK constraints now reflect via -:meth:`.Inspector.get_unique_constraints` and -:meth:`.Inspector.get_check_constraints`. A :class:`.Table` object that's +:meth:`_reflection.Inspector.get_unique_constraints` and +:meth:`_reflection.Inspector.get_check_constraints`. A :class:`_schema.Table` object that's reflected will now include :class:`.CheckConstraint` objects as well. See the notes at :ref:`oracle_constraint_reflection` for information -on behavioral quirks here, including that most :class:`.Table` objects +on behavioral quirks here, including that most :class:`_schema.Table` objects will still not include any :class:`.UniqueConstraint` objects as these usually represent via :class:`.Index`. @@ -1729,8 +1729,8 @@ Oracle foreign key constraint names are now "name normalized" ------------------------------------------------------------- The names of foreign key constraints as delivered to a -:class:`.ForeignKeyConstraint` object during table reflection as well as -within the :meth:`.Inspector.get_foreign_keys` method will now be +:class:`_schema.ForeignKeyConstraint` object during table reflection as well as +within the :meth:`_reflection.Inspector.get_foreign_keys` method will now be "name normalized", that is, expressed as lower case for a case insensitive name, rather than the raw UPPERCASE format that Oracle uses:: @@ -1805,5 +1805,5 @@ AUTOCOMMIT isolation level support ---------------------------------- Both the PyODBC and pymssql dialects now support the "AUTOCOMMIT" isolation -level as set by :meth:`.Connection.execution_options` which will establish +level as set by :meth:`_engine.Connection.execution_options` which will establish the correct flags on the DBAPI connection object. diff --git a/doc/build/changelog/migration_13.rst b/doc/build/changelog/migration_13.rst index 6f99bb708e..a7237c1bf7 100644 --- a/doc/build/changelog/migration_13.rst +++ b/doc/build/changelog/migration_13.rst @@ -89,18 +89,18 @@ The "non primary mapper" is a :func:`.mapper` created in the already mapped class against a different kind of selectable. The non primary mapper has its roots in the 0.1, 0.2 series of SQLAlchemy where it was anticipated that the :func:`.mapper` object was to be the primary query -construction interface, before the :class:`.Query` object existed. +construction interface, before the :class:`_query.Query` object existed. -With the advent of :class:`.Query` and later the :class:`.AliasedClass` +With the advent of :class:`_query.Query` and later the :class:`.AliasedClass` construct, most use cases for the non primary mapper went away. This was a good thing since SQLAlchemy also moved away from "classical" mappings altogether around the 0.5 series in favor of the declarative system. One use case remained around for non primary mappers when it was realized that -some very hard-to-define :func:`.relationship` configurations could be made +some very hard-to-define :func:`_orm.relationship` configurations could be made possible when a non-primary mapper with an alternative selectable was made as the mapping target, rather than trying to construct a -:paramref:`.relationship.primaryjoin` that encompassed all the complexity of a +:paramref:`_orm.relationship.primaryjoin` that encompassed all the complexity of a particular inter-object relationship. As this use case became more popular, its limitations became apparent, @@ -110,10 +110,10 @@ relationships of the original mapping, that relationships which are configured explicitly on the non primary mapper do not function well with loader options, and that the non primary mapper also doesn't provide a fully functional namespace of column-based attributes which can be used in queries (which again, -in the old 0.1 - 0.4 days, one would use :class:`.Table` objects directly with +in the old 0.1 - 0.4 days, one would use :class:`_schema.Table` objects directly with the ORM). -The missing piece was to allow the :func:`.relationship` to refer directly +The missing piece was to allow the :func:`_orm.relationship` to refer directly to the :class:`.AliasedClass`. The :class:`.AliasedClass` already does everything we want the non primary mapper to do; it allows an existing mapped class to be loaded from an alternative selectable, it inherits all the @@ -222,8 +222,8 @@ directly from the identity map. However, as with most querying features, the feature's implementation became more complex as a result of advanced scenarios regarding polymorphic loading. If problems are encountered, users should report a bug, however the change also includes a flag -:paramref:`.relationship.omit_join` which can be set to ``False`` on the -:func:`.relationship` to disable the optimization. +:paramref:`_orm.relationship.omit_join` which can be set to ``False`` on the +:func:`_orm.relationship` to disable the optimization. :ticket:`4340` @@ -307,7 +307,7 @@ Many-to-one replacement won't raise for "raiseload" or detached for "old" object Given the case where a lazy load would proceed on a many-to-one relationship in order to load the "old" value, if the relationship does not specify -the :paramref:`.relationship.active_history` flag, an assertion will not +the :paramref:`_orm.relationship.active_history` flag, an assertion will not be raised for a detached object:: a1 = session.query(Address).filter_by(id=5).one() @@ -360,7 +360,7 @@ info dictionary added to InstanceState -------------------------------------- Added the ``.info`` dictionary to the :class:`.InstanceState` class, the object -that comes from calling :func:`.inspect` on a mapped object. This allows custom +that comes from calling :func:`_sa.inspect` on a mapped object. This allows custom recipes to add additional information about an object that will be carried along with that object's full lifecycle in memory:: @@ -378,8 +378,8 @@ along with that object's full lifecycle in memory:: Horizontal Sharding extension supports bulk update and delete methods --------------------------------------------------------------------- -The :class:`.ShardedQuery` extension object supports the :meth:`.Query.update` -and :meth:`.Query.delete` bulk update/delete methods. The ``query_chooser`` +The :class:`.ShardedQuery` extension object supports the :meth:`_query.Query.update` +and :meth:`_query.Query.delete` bulk update/delete methods. The ``query_chooser`` callable is consulted when they are called in order to run the update/delete across multiple shards based on given criteria. @@ -737,12 +737,12 @@ Many-to-one backref checks for collection duplicates during remove operation ---------------------------------------------------------------------------- When an ORM-mapped collection that existed as a Python sequence, typically a -Python ``list`` as is the default for :func:`.relationship`, contained +Python ``list`` as is the default for :func:`_orm.relationship`, contained duplicates, and the object were removed from one of its positions but not the other(s), a many-to-one backref would set its attribute to ``None`` even though the one-to-many side still represented the object as present. Even though one-to-many collections cannot have duplicates in the relational model, -an ORM-mapped :func:`.relationship` that uses a sequence collection can have +an ORM-mapped :func:`_orm.relationship` that uses a sequence collection can have duplicates inside of it in memory, with the restriction that this duplicate state can neither be persisted nor retrieved from the database. In particular, having a duplicate temporarily present in the list is intrinsic to a Python @@ -884,15 +884,15 @@ implicit" philosophy. FOR UPDATE clause is rendered within the joined eager load subquery as well as outside -------------------------------------------------------------------------------------- -This change applies specifically to the use of the :func:`.joinedload` loading -strategy in conjunction with a row limited query, e.g. using :meth:`.Query.first` -or :meth:`.Query.limit`, as well as with use of the :class:`.Query.with_for_update` method. +This change applies specifically to the use of the :func:`_orm.joinedload` loading +strategy in conjunction with a row limited query, e.g. using :meth:`_query.Query.first` +or :meth:`_query.Query.limit`, as well as with use of the :class:`_query.Query.with_for_update` method. Given a query as:: session.query(A).options(joinedload(A.b)).limit(5) -The :class:`.Query` object renders a SELECT of the following form when joined +The :class:`_query.Query` object renders a SELECT of the following form when joined eager loading is combined with LIMIT:: SELECT subq.a_id, subq.a_data, b_alias.id, b_alias.data FROM ( @@ -948,7 +948,7 @@ and can't easily be generalized for more complex queries. passive_deletes='all' will leave FK unchanged for object removed from collection -------------------------------------------------------------------------------- -The :paramref:`.relationship.passive_deletes` option accepts the value +The :paramref:`_orm.relationship.passive_deletes` option accepts the value ``"all"`` to indicate that no foreign key attributes should be modified when the object is flushed, even if the relationship's collection / reference has been removed. Previously, this did not take place for one-to-many, or @@ -995,7 +995,7 @@ New Features and Improvements - Core New multi-column naming convention tokens, long name truncation ---------------------------------------------------------------- -To suit the case where a :class:`.MetaData` naming convention needs to +To suit the case where a :class:`_schema.MetaData` naming convention needs to disambiguate between multiple-column constraints and wishes to use all the columns within the generated constraint name, a new series of naming convention tokens are added, including @@ -1117,7 +1117,7 @@ different. :ref:`constraint_naming_conventions` - :paramref:`.MetaData.naming_convention` + :paramref:`_schema.MetaData.naming_convention` :ticket:`3989` @@ -1130,7 +1130,7 @@ This enhancement is implemented at the Core level, however is applicable primarily to the ORM. A SQL function that compares two elements can now be used as a "comparison" -object, suitable for usage in an ORM :func:`.relationship`, by first +object, suitable for usage in an ORM :func:`_orm.relationship`, by first creating the function as usual using the :data:`.func` factory, then when the function is complete calling upon the :meth:`.FunctionElement.as_comparison` modifier to produce a :class:`.BinaryExpression` that has a "left" and a "right" @@ -1150,7 +1150,7 @@ side:: order_by=name ) -Above, the :paramref:`.relationship.primaryjoin` of the "descendants" relationship +Above, the :paramref:`_orm.relationship.primaryjoin` of the "descendants" relationship will produce a "left" and a "right" expression based on the first and second arguments passed to ``instr()``. This allows features like the ORM lazyload to produce SQL like:: @@ -1306,10 +1306,10 @@ Coercion of string SQL fragments to text() fully removed The warnings that were first added in version 1.0, described at :ref:`migration_2992`, have now been converted into exceptions. Continued concerns have been raised regarding the automatic coercion of string fragments -passed to methods like :meth:`.Query.filter` and :meth:`.Select.order_by` being -converted to :func:`.text` constructs, even though this has emitted a warning. -In the case of :meth:`.Select.order_by`, :meth:`.Query.order_by`, -:meth:`.Select.group_by`, and :meth:`.Query.group_by`, a string label or column +passed to methods like :meth:`_query.Query.filter` and :meth:`_expression.Select.order_by` being +converted to :func:`_expression.text` constructs, even though this has emitted a warning. +In the case of :meth:`_expression.Select.order_by`, :meth:`_query.Query.order_by`, +:meth:`_expression.Select.group_by`, and :meth:`_query.Query.group_by`, a string label or column name is still resolved into the corresponding expression construct, however if the resolution fails, a :class:`.CompileError` is raised, thus preventing raw SQL text from being rendered directly. @@ -1377,16 +1377,12 @@ the original pattern, thanks to context managers:: At this point, any remaining code that is still relying upon the "threadlocal" style will be encouraged via this deprecation to modernize - the feature should be removed totally by the next major series of SQLAlchemy, e.g. 1.4. The -connection pool parameter :paramref:`.Pool.use_threadlocal` is also deprecated +connection pool parameter :paramref:`_pool.Pool.use_threadlocal` is also deprecated as it does not actually have any effect in most cases, as is the -:meth:`.Engine.contextual_connect` method, which is normally synonymous with -the :meth:`.Engine.connect` method except in the case where the threadlocal +:meth:`_engine.Engine.contextual_connect` method, which is normally synonymous with +the :meth:`_engine.Engine.connect` method except in the case where the threadlocal engine is in use. -.. seealso:: - - :ref:`threadlocal_strategy` - :ticket:`4393` @@ -1463,7 +1459,7 @@ Given a schema such as:: ) The two table names ``'data_values'`` and ``'data_values_4_10'`` will come -back from :meth:`.Inspector.get_table_names` and additionally the columns +back from :meth:`_reflection.Inspector.get_table_names` and additionally the columns will come back from ``Inspector.get_columns('data_values')`` as well as ``Inspector.get_columns('data_values_4_10')``. This also extends to the use of ``Table(..., autoload=True)`` with these tables. @@ -1519,8 +1515,8 @@ Dialect Improvements and Changes - SQLite Support for SQLite JSON Added ----------------------------- -A new datatype :class:`.sqlite.JSON` is added which implements SQLite's json -member access functions on behalf of the :class:`.types.JSON` +A new datatype :class:`_sqlite.JSON` is added which implements SQLite's json +member access functions on behalf of the :class:`_types.JSON` base datatype. The SQLite ``JSON_EXTRACT`` and ``JSON_QUOTE`` functions are used by the implementation to provide basic JSON support. @@ -1543,7 +1539,7 @@ SQLite supports a non-standard ON CONFLICT clause that may be specified for standalone constraints as well as some column-inline constraints such as NOT NULL. Support has been added for these clauses via the ``sqlite_on_conflict`` keyword added to objects like :class:`.UniqueConstraint` as well -as several :class:`.Column` -specific variants:: +as several :class:`_schema.Column` -specific variants:: some_table = Table( 'some_table', metadata, @@ -1592,7 +1588,7 @@ database that is not using a Unicode-compliant character set. In this case, the flag ``use_nchar_for_unicode`` can be passed to :func:`.create_engine` to re-enable the old behavior. -As always, using the :class:`.oracle.NVARCHAR2` and :class:`.oracle.NCLOB` +As always, using the :class:`_oracle.NVARCHAR2` and :class:`_oracle.NCLOB` datatypes explicitly will continue to make use of ``NVARCHAR2`` and ``NCLOB``, including within DDL as well as when handling bound parameters with cx_Oracle's ``setinputsizes()``. @@ -1622,7 +1618,7 @@ dialect as well as the URL string: * The value of the ``threaded`` parameter, which has always been defaulted to True for the SQLAlchemy dialect, is no longer generated by default. - The SQLAlchemy :class:`.Connection` object is not considered to be thread-safe + The SQLAlchemy :class:`_engine.Connection` object is not considered to be thread-safe itself so there's no need for this flag to be passed. * It's deprecated to pass ``threaded`` to :func:`.create_engine` itself. @@ -1679,7 +1675,7 @@ to make the transition towards normal sequences being available as well, using :class:.`.Sequence` will emit a deprecation warning throughout the 1.3 series. In order to affect "start" and "increment", use the new ``mssql_identity_start`` and ``mssql_identity_increment`` parameters -on :class:`.Column`:: +on :class:`_schema.Column`:: test = Table( 'test', metadata, @@ -1691,7 +1687,7 @@ on :class:`.Column`:: ) In order to emit ``IDENTITY`` on a non-primary key column, which is a little-used -but valid SQL Server use case, use the :paramref:`.Column.autoincrement` flag, +but valid SQL Server use case, use the :paramref:`_schema.Column.autoincrement` flag, setting it to ``True`` on the target column, ``False`` on any integer primary key column:: diff --git a/doc/build/changelog/migration_14.rst b/doc/build/changelog/migration_14.rst index a5a3f83d0c..f26181f7f5 100644 --- a/doc/build/changelog/migration_14.rst +++ b/doc/build/changelog/migration_14.rst @@ -35,14 +35,14 @@ of statement creation and compilation, where the compilation step would be cached, based on a cache key generated by the created statement object, which itself is newly created for each use. Towards this goal, much of the Python computation which occurs within the construction of statements, particularly -the ORM :class:`.Query`, is being moved to occur only when the statement is +the ORM :class:`_query.Query`, is being moved to occur only when the statement is invoked. This means that some of the error messages which can arise based on arguments passed to the object will no longer be raised immediately, and instead will occur only when the statement is invoked. Error conditions which fall under this category include: -* when a :class:`.CompoundSelect` is constructed (e.g. a UNION, EXCEPT, etc.) +* when a :class:`_selectable.CompoundSelect` is constructed (e.g. a UNION, EXCEPT, etc.) and the SELECT statements passed do not have the same number of columns, a :class:`.CompileError` is now raised to this effect; previously, a :class:`.ArgumentError` would be raised immediately upon statement @@ -84,13 +84,13 @@ This change is one of the larger conceptual changes in SQLAlchemy in many years, however it is hoped that the end user impact is relatively small, as the change more closely matches what databases like MySQL and PostgreSQL require in any case. -The most immediate noticeable impact is that a :func:`~.sql.expression.select` can no longer -be embedded inside of another :func:`~.sql.expression.select` directly, without explicitly -turning the inner :func:`~.sql.expression.select` into a subquery first. This is historically -performed by using the :meth:`.SelectBase.alias` method, which remains, however -is more explicitly suited by using a new method :meth:`.SelectBase.subquery`; +The most immediate noticeable impact is that a :func:`_expression.select` can no longer +be embedded inside of another :func:`_expression.select` directly, without explicitly +turning the inner :func:`_expression.select` into a subquery first. This is historically +performed by using the :meth:`_expression.SelectBase.alias` method, which remains, however +is more explicitly suited by using a new method :meth:`_expression.SelectBase.subquery`; both methods do the same thing. The object returned is now :class:`.Subquery`, -which is very similar to the :class:`.Alias` object and shares a common +which is very similar to the :class:`_expression.Alias` object and shares a common base :class:`.AliasedReturnsRows`. That is, this will now raise:: @@ -109,22 +109,22 @@ The correct calling form is instead:: sq1 = select([user.c.id, user.c.name]).subquery() stmt2 = select([addresses, sq1]).select_from(addresses.join(sq1)) -Noting above that the :meth:`.SelectBase.subquery` method is essentially -equivalent to using the :meth:`.SelectBase.alias` method. +Noting above that the :meth:`_expression.SelectBase.subquery` method is essentially +equivalent to using the :meth:`_expression.SelectBase.alias` method. The above calling form is typically required in any case as the call to -:meth:`.SelectBase.subquery` or :meth:`.SelectBase.alias` is needed to +:meth:`_expression.SelectBase.subquery` or :meth:`_expression.SelectBase.alias` is needed to ensure the subquery has a name. The MySQL and PostgreSQL databases do not accept unnamed subqueries in the FROM clause and they are of limited use on other platforms; this is described further below. -Along with the above change, the general capability of :func:`~.sql.expression.select` and +Along with the above change, the general capability of :func:`_expression.select` and related constructs to create unnamed subqueries, which means a FROM subquery that renders without any name i.e. "AS somename", has been removed, and the -ability of the :func:`~.sql.expression.select` construct to implicitly create subqueries +ability of the :func:`_expression.select` construct to implicitly create subqueries without explicit calling code to do so is mostly deprecated. In the above -example, as has always been the case, using the :meth:`.SelectBase.alias` -method as well as the new :meth:`.SelectBase.subquery` method without passing a +example, as has always been the case, using the :meth:`_expression.SelectBase.alias` +method as well as the new :meth:`_expression.SelectBase.subquery` method without passing a name will generate a so-called "anonymous" name, which is the familiar ``anon_1`` name we see in SQLAlchemy queries:: @@ -180,19 +180,19 @@ the user to, or implicitly create, an anonymously named subquery; it is hoped by moving to an all-explicit subquery much of the complexity incurred by these areas can be removed. -As :class:`.SelectBase` objects are no longer :class:`.FromClause` objects, +As :class:`_expression.SelectBase` objects are no longer :class:`_expression.FromClause` objects, attributes like the ``.c`` attribute as well as methods like ``.select()``, -``.join()``, and ``.outerjoin()`` upon :class:`.SelectBase` are now +``.join()``, and ``.outerjoin()`` upon :class:`_expression.SelectBase` are now deprecated, as these methods all imply implicit production of a subquery. Instead, as is already what the vast majority of applications have to do -in any case, invoking :meth:`.SelectBase.alias` or :meth:`.SelectBase.subquery` +in any case, invoking :meth:`_expression.SelectBase.alias` or :meth:`_expression.SelectBase.subquery` will provide for a :class:`.Subquery` object that provides all these attributes, -as it is part of the :class:`.FromClause` hierarchy. In the interim, these +as it is part of the :class:`_expression.FromClause` hierarchy. In the interim, these methods are still available, however they now produce an anonymously named subquery rather than an unnamed one, and this subquery is distinct from the -:class:`.SelectBase` construct itself. +:class:`_expression.SelectBase` construct itself. -In place of the ``.c`` attribute, a new attribute :attr:`.SelectBase.selected_columns` +In place of the ``.c`` attribute, a new attribute :attr:`_expression.SelectBase.selected_columns` is added. This attribute resolves to a column collection that is what most people hope that ``.c`` does (but does not), which is to reference the columns that are in the columns clause of the SELECT statement. A common beginner mistake @@ -206,24 +206,24 @@ The above code appears intuitive and that it would generate recognize that it in fact generates a useless subquery resembling "SELECT * FROM (SELECT * FROM users) WHERE name='foo'". -The new :attr:`.SelectBase.selected_columns` attribute however **does** suit +The new :attr:`_expression.SelectBase.selected_columns` attribute however **does** suit the use case above, as in a case like the above it links directly to the columns present in the ``users.c`` collection:: stmt = select([users]) stmt = stmt.where(stmt.selected_columns.name == 'foo') -There is of course the notion that perhaps ``.c`` on :class:`.SelectBase` could -simply act the way :attr:`.SelectBase.selected_columns` does above, however in -light of the fact that ``.c`` is strongly associated with the :class:`.FromClause` +There is of course the notion that perhaps ``.c`` on :class:`_expression.SelectBase` could +simply act the way :attr:`_expression.SelectBase.selected_columns` does above, however in +light of the fact that ``.c`` is strongly associated with the :class:`_expression.FromClause` hierarchy, meaning that it is a set of columns that can be directly in the FROM clause of another SELECT, it's better that a column collection that serves an entirely different purpose have a new name. In the bigger picture, the reason this change is being made now is towards the -goal of unifying the ORM :class:`.Query` object into the :class:`.SelectBase` +goal of unifying the ORM :class:`_query.Query` object into the :class:`_expression.SelectBase` hierarchy in SQLAlchemy 2.0, so that the ORM will have a "``select()``" -construct that extends directly from the existing :func:`~.sql.expression.select` object, +construct that extends directly from the existing :func:`_expression.select` object, having the same methods and behaviors except that it will have additional ORM functionality. All statement objects in Core will also be fully cacheable using a new system that resembles "baked queries" except that it will work @@ -262,9 +262,9 @@ brought about the "expanding IN" feature. In contrast to the existing behavior whereby the parameter list is expanded at statement construction time into individual :class:`.BindParameter` objects, the feature instead uses a single :class:`.BindParameter` that stores the list of values at once; when the -statement is executed by the :class:`.Engine`, it is "expanded" on the fly into +statement is executed by the :class:`_engine.Engine`, it is "expanded" on the fly into individual bound parameter positions based on the parameters passed to the call -to :meth:`.Connection.execute`, and the existing SQL string which may have been +to :meth:`_engine.Connection.execute`, and the existing SQL string which may have been retrieved from a previous execution is modified using a regular expression to suit the current parameter set. This allows for the same :class:`.Compiled` object, which stores the rendered string statement, to be invoked multiple @@ -370,7 +370,7 @@ patterns in place in order to support this process. The note in For release 1.4, the :class:`.Row` class provides an additional subclass :class:`.LegacyRow`, which is used by Core and provides a backwards-compatible version of :class:`.RowProxy` while emitting deprecation warnings for those API -features and behaviors that will be moved. ORM :class:`.Query` now makes use +features and behaviors that will be moved. ORM :class:`_query.Query` now makes use of :class:`.Row` directly as a replacement for :class:`.KeyedTuple`. The :class:`.LegacyRow` class is a transitional class where the @@ -520,7 +520,7 @@ the attribute:: book_w_excerpt = session.query(Book).options(undefer(Book.excerpt)).first() It was originally considered that the existing :func:`.raiseload` option that -works for :func:`.relationship` attributes be expanded to also support column-oriented +works for :func:`_orm.relationship` attributes be expanded to also support column-oriented attributes. However, this would break the "wildcard" behavior of :func:`.raiseload`, which is documented as allowing one to prevent all relationships from loading:: @@ -571,7 +571,7 @@ The "KeyedTuple" object returned by Query is replaced by Row As discussed at :ref:`change_4710_core`, the Core :class:`.RowProxy` object is now replaced by a class called :class:`.Row`. The base :class:`.Row` object now behaves more fully like a named tuple, and as such it is now -used as the basis for tuple-like results returned by the :class:`.Query` +used as the basis for tuple-like results returned by the :class:`_query.Query` object, rather than the previous "KeyedTuple" class. The rationale is so that by SQLAlchemy 2.0, both Core and ORM SELECT statements @@ -581,7 +581,7 @@ via the :attr:`.Row._mapping` attribute. In the interim, Core result sets will make use of a :class:`.Row` subclass :class:`.LegacyRow` which maintains the previous dict/tuple hybrid behavior for backwards compatibility while the :class:`.Row` class will be used directly for ORM tuple results returned -by the :class:`.Query` object. +by the :class:`_query.Query` object. Effort has been made to get most of the featureset of :class:`.Row` to be available within the ORM, meaning that access by string name as well @@ -663,7 +663,7 @@ event is emitted, the change should have no other user-visible impact on the :class:`.Session` object's behavior; the :class:`.Session` will continue to have the behavior that it remains usable for new operations after :meth:`.Session.close` is called, and the sequencing of how the :class:`.Session` interacts with the -:class:`.Engine` and the database itself should also remain unaffected, since +:class:`_engine.Engine` and the database itself should also remain unaffected, since these operations were already operating in an on-demand fashion. :ticket:`5074` @@ -696,8 +696,8 @@ include the joinedload operation as well:: WHERE a.id = ? The behavior applies both to loader strategies applied to the -:func:`.relationship` directly, as well as with options used with -:meth:`.Query.options`, provided that the object was originally loaded by that +:func:`_orm.relationship` directly, as well as with options used with +:meth:`_query.Query.options`, provided that the object was originally loaded by that query. For the "secondary" eager loaders "selectinload" and "subqueryload", the SQL @@ -936,12 +936,12 @@ configured to raise an exception using the Python warnings filter. Persistence-related cascade operations disallowed with viewonly=True --------------------------------------------------------------------- -When a :func:`.relationship` is set as ``viewonly=True`` using the -:paramref:`.relationship.viewonly` flag, it indicates this relationship should +When a :func:`_orm.relationship` is set as ``viewonly=True`` using the +:paramref:`_orm.relationship.viewonly` flag, it indicates this relationship should only be used to load data from the database, and should not be mutated or involved in a persistence operation. In order to ensure this contract works successfully, the relationship can no longer specify -:paramref:`.relationship.cascade` settings that make no sense in terms of +:paramref:`_orm.relationship.cascade` settings that make no sense in terms of "viewonly". The primary targets here are the "delete, delete-orphan" cascades, which @@ -984,7 +984,7 @@ to select from. If the given subquery returns rows that do not correspond to the requested polymorphic identity or identities, an error is raised. Previously, this condition would pass silently under joined table inheritance, returning an invalid subclass, and under single table inheritance, the -:class:`.Query` would be adding additional criteria against the subquery to +:class:`_query.Query` would be adding additional criteria against the subquery to limit the results which could inappropriately interfere with the intent of the query. @@ -1037,7 +1037,7 @@ only a ``Manager`` object is returned:: 2020-01-29 18:08:32,975 INFO sqlalchemy.engine.base.Engine ('manager',) [<__main__.Manager object at 0x7ff1b0200d50>] -The :class:`.Query` added the "single table inheritance" criteria to the +The :class:`_query.Query` added the "single table inheritance" criteria to the subquery, editorializing on the intent that was originally set up by it. This behavior was added in version 1.0 in :ticket:`3891`, and creates a behavioral inconsistency between "joined" and "single" table inheritance, @@ -1146,7 +1146,7 @@ where the JOIN keyword is not used and instead each FROM element is linked with another one via the WHERE clause. For some years there has been a recipe on the Wiki that applies a graph -algorithm to a :func:`~.sql.expression.select` construct at query execution time and inspects +algorithm to a :func:`_expression.select` construct at query execution time and inspects the structure of the query for these un-linked FROM clauses, parsing through the WHERE clause and all JOIN clauses to determine how FROM elements are linked together and ensuring that all the FROM elements are connected in a single @@ -1199,7 +1199,7 @@ following query will return all rows and produce no warnings:: q = session.query(User).join(Address, true()) # intentional cartesian product The warning is only generated by default when the statement is compiled by the -:class:`.Connection` for execution; calling the :meth:`.ClauseElement.compile` +:class:`_engine.Connection` for execution; calling the :meth:`_expression.ClauseElement.compile` method will not emit a warning unless the linting flag is supplied:: >>> from sqlalchemy.sql import FROM_LINTING @@ -1221,10 +1221,10 @@ Behavior Changes - Core SELECT objects and derived FROM clauses allow for duplicate columns and column labels ------------------------------------------------------------------------------------- -This change allows that the :func:`~.sql.expression.select` construct now allows for duplicate +This change allows that the :func:`_expression.select` construct now allows for duplicate column labels as well as duplicate column objects themselves, so that result tuples are organized and ordered in the identical way in that the columns were -selected. The ORM :class:`.Query` already works this way, so this change +selected. The ORM :class:`_query.Query` already works this way, so this change allows for greater cross-compatibility between the two, which is a key goal of the 2.0 transition:: @@ -1234,12 +1234,12 @@ the 2.0 transition:: >>> print(stmt) SELECT c1, c2, c3 AS c2, c2, c4 -To support this change, the :class:`.ColumnCollection` used by -:class:`.SelectBase` as well as for derived FROM clauses such as subqueries +To support this change, the :class:`_expression.ColumnCollection` used by +:class:`_expression.SelectBase` as well as for derived FROM clauses such as subqueries also support duplicate columns; this includes the new -:attr:`.SelectBase.selected_columns` attribute, the deprecated ``SelectBase.c`` -attribute, as well as the :attr:`.FromClause.c` attribute seen on constructs -such as :class:`.Subquery` and :class:`.Alias`:: +:attr:`_expression.SelectBase.selected_columns` attribute, the deprecated ``SelectBase.c`` +attribute, as well as the :attr:`_expression.FromClause.c` attribute seen on constructs +such as :class:`.Subquery` and :class:`_expression.Alias`:: >>> list(stmt.selected_columns) [ @@ -1254,20 +1254,20 @@ such as :class:`.Subquery` and :class:`.Alias`:: SELECT anon_1.c1, anon_1.c2, anon_1.c2, anon_1.c2, anon_1.c4 FROM (SELECT c1, c2, c3 AS c2, c2, c4) AS anon_1 -:class:`.ColumnCollection` also allows access by integer index to support +:class:`_expression.ColumnCollection` also allows access by integer index to support when the string "key" is ambiguous:: >>> stmt.selected_columns[2] -To suit the use of :class:`.ColumnCollection` in objects such as -:class:`.Table` and :class:`.PrimaryKeyConstraint`, the old "deduplicating" +To suit the use of :class:`_expression.ColumnCollection` in objects such as +:class:`_schema.Table` and :class:`.PrimaryKeyConstraint`, the old "deduplicating" behavior which is more critical for these objects is preserved in a new class :class:`.DedupeColumnCollection`. The change includes that the familiar warning ``"Column %r on table %r being replaced by %r, which has the same key. Consider use_labels for select() -statements."`` is **removed**; the :meth:`.Select.apply_labels` is still +statements."`` is **removed**; the :meth:`_expression.Select.apply_labels` is still available and is still used by the ORM for all SELECT operations, however it does not imply deduplication of column objects, although it does imply deduplication of implicitly generated labels:: @@ -1280,7 +1280,7 @@ deduplication of implicitly generated labels:: FROM "user" Finally, the change makes it easier to create UNION and other -:class:`.CompoundSelect` objects, by ensuring that the number and position +:class:`_selectable.CompoundSelect` objects, by ensuring that the number and position of columns in a SELECT statement mirrors what was given, in a use case such as:: @@ -1469,18 +1469,18 @@ string values. Connection-level transactions can now be inactive based on subtransaction ------------------------------------------------------------------------- -A :class:`.Connection` now includes the behavior where a :class:`.Transaction` +A :class:`_engine.Connection` now includes the behavior where a :class:`.Transaction` can be made inactive due to a rollback on an inner transaction, however the :class:`.Transaction` will not clear until it is itself rolled back. This is essentially a new error condition which will disallow statement -executions to proceed on a :class:`.Connection` if an inner "sub" transaction +executions to proceed on a :class:`_engine.Connection` if an inner "sub" transaction has been rolled back. The behavior works very similarly to that of the ORM :class:`.Session`, where if an outer transaction has been begun, it needs to be rolled back to clear the invalid transaction; this behavior is described in :ref:`faq_session_rollback` -While the :class:`.Connection` has had a less strict behavioral pattern than +While the :class:`_engine.Connection` has had a less strict behavioral pattern than the :class:`.Session`, this change was made as it helps to identify when a subtransaction has rolled back the DBAPI transaction, however the external code isn't aware of this and attempts to continue proceeding, which in fact @@ -1531,7 +1531,7 @@ Added Sequence support for MariaDB 10.3 The MariaDB database as of 10.3 supports sequences. SQLAlchemy's MySQL dialect now implements support for the :class:`.Sequence` object against this database, meaning "CREATE SEQUENCE" DDL will be emitted for a -:class:`.Sequence` that is present in a :class:`.Table` or :class:`.MetaData` +:class:`.Sequence` that is present in a :class:`_schema.Table` or :class:`_schema.MetaData` collection in the same way as it works for backends such as PostgreSQL, Oracle, when the dialect's server version check has confirmed the database is MariaDB 10.3 or greater. Additionally, the :class:`.Sequence` will act as a diff --git a/doc/build/changelog/migration_20.rst b/doc/build/changelog/migration_20.rst index c712ab991d..bb6cc0383d 100644 --- a/doc/build/changelog/migration_20.rst +++ b/doc/build/changelog/migration_20.rst @@ -29,7 +29,7 @@ SQLAlchemy 2.0 Transition shortcomings that would be unknown today. The vast majority of Python packages that are today taken for granted did not exist. SQLAlchemy itself struggled with major API adjustments through versions 0.1 to 0.5, with such - major concepts as :class:`.Connection`, :class:`.orm.query.Query`, and the + major concepts as :class:`_engine.Connection`, :class:`.orm.query.Query`, and the Declarative mapping approach only being conceived and added to releases gradually over a period of a several years. @@ -198,9 +198,9 @@ of Core use cases, it's the pattern that is already recommended:: conn.execute(some_table.insert().values(foo='bar')) For "commit as you go, or rollback instead" usage, which resembles how the -:class:`.orm.Session` is normally used today, new ``.commit()`` and -``.rollback()`` methods will also be added to :class:`.Connection` itself. -These will typically be used in conjunction with the :meth:`.Engine.connect` +:class:`_orm.Session` is normally used today, new ``.commit()`` and +``.rollback()`` methods will also be added to :class:`_engine.Connection` itself. +These will typically be used in conjunction with the :meth:`_engine.Engine.connect` method:: # 1.4 / 2.0 code @@ -216,7 +216,7 @@ method:: conn.execute(text("some other SQL")) conn.rollback() -Above, the ``engine.connect()`` method will return a :class:`.Connection` that +Above, the ``engine.connect()`` method will return a :class:`_engine.Connection` that features **autobegin**, meaning the ``begin()`` event is emitted when the execute method is first used (note however that there is no actual "BEGIN" in the Python DBAPI). This is the same as how the ORM :class:`.Session` will @@ -252,7 +252,7 @@ the :class:`.Session` will not allow any database activity outside of the above transaction block. The 1.4 change :ref:`change_5074` is part of this architecture. -In the case of both core :class:`.Connection` as well as orm :class:`.Session`, +In the case of both core :class:`_engine.Connection` as well as orm :class:`.Session`, if neither ``.commit()`` nor ``.rollback()`` are called, the connection is returned to the pool normally where an implicit (yes, still need this one) rollback will occur. This is the case already for Core and ORM:: @@ -313,11 +313,11 @@ support is available for PostgreSQL, MySQL, SQL Server, and as of SQLAlchemy a lot of ``engine.execute()`` calls that will need to be adjusted. "Connectionless" execution refers to the still fairly popular pattern of -invoking ``.execute()`` from the :class:`.Engine`:: +invoking ``.execute()`` from the :class:`_engine.Engine`:: result = engine.execute(some_statement) -The above operation implicitly procures a :class:`.Connection` object, +The above operation implicitly procures a :class:`_engine.Connection` object, and runs the ``.execute()`` method on it. This seems like a pretty simple and intuitive method to have so that people who just need to invoke a few SQL statements don't need all the verbosity with connecting and all that. @@ -371,14 +371,14 @@ de-emphasize for many years. Because implicit execution is removed, there's really no reason for "bound" metadata to exist. There are many internal structures that are involved with -locating the "bind" for a particular statement, to see if an :class:`.Engine` +locating the "bind" for a particular statement, to see if an :class:`_engine.Engine` is associated with some SQL statement exists which necessarily involves an additional traversal of the statement, just to find the correct dialect with which to compile it. This complex and error-prone logic can be removed from Core by removing "bound" metadata. Overall, the above executional patterns were introduced in SQLAlchemy's -very first 0.1 release before the :class:`.Connection` object even existed. +very first 0.1 release before the :class:`_engine.Connection` object even existed. After many years of de-emphasizing these patterns, "implicit, connectionless" execution and "bound metadata" are no longer as widely used so in 2.0 we seek to finally reduce the number of choices for how to execute a statement in @@ -440,7 +440,7 @@ Slight Caveat - there still may need to be a "statement.execute()" kind of featu To suit the use case of ORM "dynamic" relationships as well as Flask-oriented ORM patterns, there still may be some semblance of "implicit" execution of a statement, however, it won't really be "connectionless". Likely, a statement -can be directly bound to a :class:`.Connection` or :class:`.Session` once +can be directly bound to a :class:`_engine.Connection` or :class:`.Session` once constructed:: # 1.4 / 2.0 code (tentative) @@ -466,9 +466,9 @@ execute() method more strict, .execution_options() are available on ORM Session The use of execution options is expected to be more prominent as the Core and ORM are largely unified at the statement handling level. To suit this, -the :class:`.orm.Session` will be able to receive execution options local +the :class:`_orm.Session` will be able to receive execution options local to a series of statement executions in the same way as that of -:class:`.Connection`:: +:class:`_engine.Connection`:: # 1.4 / 2.0 code @@ -586,7 +586,7 @@ Result rows unified between Core and ORM on named-tuple interface ================================================================== Already part of 1.4, the previous ``KeyedTuple`` class that was used when -selecting rows from the :class:`.Query` object has been replaced by the +selecting rows from the :class:`_query.Query` object has been replaced by the :class:`.Row` class, which is the base of the same :class:`.Row` that comes back with Core statement results (in 1.4 it is the :class:`.LegacyRow` class). @@ -719,7 +719,7 @@ to make for a pattern such as:: # "classical" mapping: base.mapper(MyClass, my_table) -In 2.0, an application that still wishes to use a separate :class:`.Table` and +In 2.0, an application that still wishes to use a separate :class:`_schema.Table` and does not want to use Declarative with ``__table__``, can instead use the above pattern which basically does the same thing. @@ -730,8 +730,8 @@ ORM Query Unified with Core Select .. admonition:: Certainty: tentative Tenative overall, however there will almost definitely be - architectural changes in :class:`.Query` that move it closer to - :func:`.select`. + architectural changes in :class:`_query.Query` that move it closer to + :func:`_expression.select`. The ``session.query()`` pattern itself will likely **not** be fully removed. As this pattern is extremely prevalent and numerous within any @@ -740,29 +740,29 @@ ORM Query Unified with Core Select that a transition to 2.0 won't require a rewrite of every ``session.query()`` call, however it will be a legacy pattern that may warn as such. -Ever wonder why SQLAlchemy :func:`~.sql.expression.select` uses :meth:`.Select.where` to add -a WHERE clause and :class:`.Query` uses :meth:`.Query.filter` ? Same here! -The :class:`.Query` object was not part of SQLAlchemy's original concept. -Originally, the idea was that the :class:`.Mapper` construct itself would -be able to select rows, and that :class:`.Table` objects, not classes, +Ever wonder why SQLAlchemy :func:`_expression.select` uses :meth:`_expression.Select.where` to add +a WHERE clause and :class:`_query.Query` uses :meth:`_query.Query.filter` ? Same here! +The :class:`_query.Query` object was not part of SQLAlchemy's original concept. +Originally, the idea was that the :class:`_orm.Mapper` construct itself would +be able to select rows, and that :class:`_schema.Table` objects, not classes, would be used to create the various criteria in a Core-style approach. The -:class:`.Query` was basically an extension that was proposed by a user who +:class:`_query.Query` was basically an extension that was proposed by a user who quite plainly had a better idea of how to build up SQL queries. The -"buildable" approach of :class:`.Query`, originally called ``SelectResults``, -was also adapted to the Core SQL objects, so that :func:`~.sql.expression.select` gained -methods like :meth:`.Select.where`, rather than being an all-at-once composed +"buildable" approach of :class:`_query.Query`, originally called ``SelectResults``, +was also adapted to the Core SQL objects, so that :func:`_expression.select` gained +methods like :meth:`_expression.Select.where`, rather than being an all-at-once composed object. Later on, ORM classes gained the ability to be used directly in -constructing SQL criteria. :class:`.Query` evolved over many years to -eventually support production of all the SQL that :func:`~.sql.expression.select` does, to +constructing SQL criteria. :class:`_query.Query` evolved over many years to +eventually support production of all the SQL that :func:`_expression.select` does, to the point where having both forms has now become redundant. SQLAlchemy 2.0 will resolve the inconsistency here by promoting the concept -of :func:`~.sql.expression.select` to be the single way that one constructs a SELECT construct. +of :func:`_expression.select` to be the single way that one constructs a SELECT construct. For Core usage, the ``select()`` works mostly as it does now, except that it gains a real working ``.join()`` method that will append JOIN conditions to the -statement in the same way as works for :meth:`.Query.join` right now. +statement in the same way as works for :meth:`_query.Query.join` right now. -For ORM use however, one can construct a :func:`~.sql.expression.select` using ORM objects, and +For ORM use however, one can construct a :func:`_expression.select` using ORM objects, and then when delivered to the ``.invoke()`` or ``.execute()`` method of :class:`.Session`, it will be interpreted appropriately:: @@ -774,8 +774,8 @@ then when delivered to the ``.invoke()`` or ``.execute()`` method of rows = session.execute(stmt).all() -Similarly, methods like :meth:`.Query.update` and :meth:`.Query.delete` are now -replaced by usage of the :func:`.update` and :func:`.delete` constructs directly:: +Similarly, methods like :meth:`_query.Query.update` and :meth:`_query.Query.delete` are now +replaced by usage of the :func:`_expression.update` and :func:`_expression.delete` constructs directly:: from sqlalchemy.future import update @@ -795,8 +795,8 @@ ORM Query relationship patterns simplified Joining / loading on relationships uses attributes, not strings ---------------------------------------------------------------- -This refers to patterns such as that of :meth:`.Query.join` as well as -query options like :func:`.joinedload` which currently accept a mixture of +This refers to patterns such as that of :meth:`_query.Query.join` as well as +query options like :func:`_orm.joinedload` which currently accept a mixture of string attribute names or actual class attributes. The string calling form leaves a lot more ambiguity and is also more complicated internally, so will be deprecated in 1.4 and removed by 2.0. This means the following won't work:: @@ -848,7 +848,7 @@ attributes in a list will also be removed:: join(..., aliased=True), from_joinpoint removed ----------------------------------------------- -The ``aliased=True`` option on :meth:`.Query.join` is another feature that +The ``aliased=True`` option on :meth:`_query.Query.join` is another feature that seems to be almost never used, based on extensive code searches to find actual use of this feature. The internal complexity that the ``aliased=True`` flag requires is **enormous**, and will be going away in 2.0. @@ -881,14 +881,14 @@ parameter ever being used in real world applications:: filter(Node.name == 'some sub child') The ``aliased=True`` and ``from_joinpoint`` parameters were developed at a time -when the :class:`.Query` object didn't yet have good capabilities regarding +when the :class:`_query.Query` object didn't yet have good capabilities regarding joining along relationship attributes, functions like :meth:`.PropComparator.of_type` did not exist, and the :func:`.aliased` construct itself didn't exist early on. The above patterns are all suited by standard use of the :func:`.aliased` construct, resulting in a much clearer query as well as removing hundreds of -lines of complexity from the internals of :class:`.Query` (or whatever it is +lines of complexity from the internals of :class:`_query.Query` (or whatever it is to be called in 2.0 :) ) :: n1 = aliased(Node) @@ -914,13 +914,13 @@ of the form ``(target, onclause)`` as well:: -By using attributes instead of strings above, the :meth:`.Query.join` method +By using attributes instead of strings above, the :meth:`_query.Query.join` method no longer needs the almost never-used option of ``from_joinpoint``. Other ORM Query patterns changed ================================= -This section will collect various :class:`.Query` patterns and how they work +This section will collect various :class:`_query.Query` patterns and how they work in terms of :func:`.future.select`. .. _migration_20_query_distinct: @@ -928,7 +928,7 @@ in terms of :func:`.future.select`. Using DISTINCT with additional columns, but only select the entity ------------------------------------------------------------------- -:class:`.Query` will automatically add columns in the ORDER BY when +:class:`_query.Query` will automatically add columns in the ORDER BY when distinct is used. The following query will select from all User columns as well as "address.email_address" but only return User objects:: @@ -956,28 +956,28 @@ and the limiting of the entities/columns to ``User`` is done on the result:: Selecting from the query itself as a subquery, e.g. "from_self()" ------------------------------------------------------------------- -The :meth:`.Query.from_self` method is a very complicated method that is rarely -used. The purpose of this method is to convert a :class:`.Query` into a -subquery, then return a new :class:`.Query` which SELECTs from that subquery. +The :meth:`_query.Query.from_self` method is a very complicated method that is rarely +used. The purpose of this method is to convert a :class:`_query.Query` into a +subquery, then return a new :class:`_query.Query` which SELECTs from that subquery. The elaborate aspect of this method is that the returned query applies automatic translation of ORM entities and columns to be stated in the SELECT in terms of the subquery, as well as that it allows the entities and columns to be SELECTed from to be modified. -Because :meth:`.Query.from_self` packs an intense amount of implicit +Because :meth:`_query.Query.from_self` packs an intense amount of implicit translation into the SQL it produces, while it does allow a certain kind of pattern to be executed very succinctly, real world use of this method is infrequent as it is not simple to understand. In SQLAlchemy 2.0, as the :func:`.future.select` construct will be expected -to handle every pattern the ORM :class:`.Query` does now, the pattern of -:meth:`.Query.from_self` can be invoked now by making use of the -:func:`.orm.aliased` function in conjunction with a subquery, that is -the :meth:`.Query.subquery` or :meth:`.Select.subquery` method. Version 1.4 -of SQLAlchemy has enhanced the ability of the :func:`.orm.aliased` construct +to handle every pattern the ORM :class:`_query.Query` does now, the pattern of +:meth:`_query.Query.from_self` can be invoked now by making use of the +:func:`_orm.aliased` function in conjunction with a subquery, that is +the :meth:`_query.Query.subquery` or :meth:`_expression.Select.subquery` method. Version 1.4 +of SQLAlchemy has enhanced the ability of the :func:`_orm.aliased` construct to correctly extract columns from a given subquery. -Starting with a :meth:`.Query.from_self` query that selects from two different +Starting with a :meth:`_query.Query.from_self` query that selects from two different entities, then converts itself to select just one of the entities from a subquery:: @@ -1000,7 +1000,7 @@ column:: The SQL query above illustrates the automatic translation of the "user" and "address" tables in terms of the anonymously named subquery. -In 2.0, we perform these steps explicitly using :func:`.orm.aliased`:: +In 2.0, we perform these steps explicitly using :func:`_orm.aliased`:: # 1.4/2.0 code @@ -1020,7 +1020,7 @@ In 2.0, we perform these steps explicitly using :func:`.orm.aliased`:: The above query renders the identical SQL structure, but uses a more succinct labeling scheme that doesn't pull in table names (that labeling -scheme is still available if the :meth:`.Select.apply_labels` method is used):: +scheme is still available if the :meth:`_expression.Select.apply_labels` method is used):: SELECT anon_1.id AS anon_1_id FROM ( @@ -1067,7 +1067,7 @@ Transparent Statement Compilation Caching replaces "Baked" queries, works in Cor Pending further architectural prototyping and performance testing A major restructuring of the Core internals as well as of that of the ORM -:class:`.Query` will be reorganizing the major statement objects to have very +:class:`_query.Query` will be reorganizing the major statement objects to have very simplified "builder" internals, that is, when you construct an object like ``select(table).where(criteria).join(some_table)``, the arguments passed are simply stored and as little processing as possible will occur. Then there is @@ -1271,12 +1271,12 @@ of asyncio-everything, here are the bulletpoints: to keep up with SQLAlchemy's own capabilities and they likely don't really work for lots of existing use cases either. -* Essentially, it is hoped that the re-architecting of :class:`.Connection` +* Essentially, it is hoped that the re-architecting of :class:`_engine.Connection` to no longer support things like "autocommit" and "connectionless" execution, as well as the changes to how result fetching will work with the ``Result`` which is hoped to be simpler in how it interacts with the cursor, will make it **much easier** to build async versions of - SQLAlchemy's :class:`.Connection`. The simplified model of + SQLAlchemy's :class:`_engine.Connection`. The simplified model of ``Connection.execute()`` and ``Session.execute()`` as the single point of invocation of queries should also make things easier. diff --git a/doc/build/changelog/unreleased_13/4138.rst b/doc/build/changelog/unreleased_13/4138.rst index fd8f0eb903..600f608e58 100644 --- a/doc/build/changelog/unreleased_13/4138.rst +++ b/doc/build/changelog/unreleased_13/4138.rst @@ -2,4 +2,4 @@ :tags: schema :tickets: 4138 - Add ``comment`` attribute to :class:`.Column` ``__repr__`` method. + Add ``comment`` attribute to :class:`_schema.Column` ``__repr__`` method. diff --git a/doc/build/changelog/unreleased_14/4194.rst b/doc/build/changelog/unreleased_14/4194.rst index 7c01ea2d22..9fd7a5c646 100644 --- a/doc/build/changelog/unreleased_14/4194.rst +++ b/doc/build/changelog/unreleased_14/4194.rst @@ -3,9 +3,9 @@ :tickets: 4194 Fixed bug where a versioning column specified on a mapper against a - :func:`~.sql.expression.select` construct where the version_id_col itself were against the + :func:`_expression.select` construct where the version_id_col itself were against the underlying table would incur additional loads when accessed, even if the value were locally persisted by the flush. The actual fix is a result of - the changes in :ticket:`4617`, by fact that a :func:`~.sql.expression.select` object no + the changes in :ticket:`4617`, by fact that a :func:`_expression.select` object no longer has a ``.c`` attribute and therefore does not confuse the mapper into thinking there's an unknown column value present. diff --git a/doc/build/changelog/unreleased_14/4336.rst b/doc/build/changelog/unreleased_14/4336.rst index 8a994357f5..56f7f06b81 100644 --- a/doc/build/changelog/unreleased_14/4336.rst +++ b/doc/build/changelog/unreleased_14/4336.rst @@ -2,9 +2,9 @@ :tags: bug, sql :tickets: 4336 - Reworked the :meth:`.ClauseElement.compare` methods in terms of a new + Reworked the :meth:`_expression.ClauseElement.compare` methods in terms of a new visitor-based approach, and additionally added test coverage ensuring that - all :class:`.ClauseElement` subclasses can be accurately compared + all :class:`_expression.ClauseElement` subclasses can be accurately compared against each other in terms of structure. Structural comparison capability is used to a small degree within the ORM currently, however it also may form the basis for new caching features. diff --git a/doc/build/changelog/unreleased_14/4449.rst b/doc/build/changelog/unreleased_14/4449.rst index a8ca2d2b70..f010bf47f9 100644 --- a/doc/build/changelog/unreleased_14/4449.rst +++ b/doc/build/changelog/unreleased_14/4449.rst @@ -11,7 +11,7 @@ "anon_1" label, that is, ``CAST(table.colname AS INTEGER) AS colname``. If the inner expression doesn't have a name, then the previous "anonymous label" logic is used. When using SELECT statements that make use of - :meth:`.Select.apply_labels`, such as those emitted by the ORM, the + :meth:`_expression.Select.apply_labels`, such as those emitted by the ORM, the labeling logic will produce ``_`` in the same was as if the column were named alone. The logic applies right now to the :func:`.cast` and :func:`.type_coerce` constructs as well as some diff --git a/doc/build/changelog/unreleased_14/4617_coercion.rst b/doc/build/changelog/unreleased_14/4617_coercion.rst index 198a2d0da6..09d0b8e6d6 100644 --- a/doc/build/changelog/unreleased_14/4617_coercion.rst +++ b/doc/build/changelog/unreleased_14/4617_coercion.rst @@ -3,11 +3,11 @@ :tickets: 4617 The "clause coercion" system, which is SQLAlchemy Core's system of receiving - arguments and resolving them into :class:`.ClauseElement` structures in order + arguments and resolving them into :class:`_expression.ClauseElement` structures in order to build up SQL expression objects, has been rewritten from a series of ad-hoc functions to a fully consistent class-based system. This change is internal and should have no impact on end users other than more specific error messages when the wrong kind of argument is passed to an expression object, however the change is part of a larger set of changes involving - the role and behavior of :func:`~.sql.expression.select` objects. + the role and behavior of :func:`_expression.select` objects. diff --git a/doc/build/changelog/unreleased_14/4617_implicit_subquery.rst b/doc/build/changelog/unreleased_14/4617_implicit_subquery.rst index 49a973c76a..a8bfad1383 100644 --- a/doc/build/changelog/unreleased_14/4617_implicit_subquery.rst +++ b/doc/build/changelog/unreleased_14/4617_implicit_subquery.rst @@ -3,15 +3,15 @@ :tickets: 4617 As part of the SQLAlchemy 2.0 migration project, a conceptual change has - been made to the role of the :class:`.SelectBase` class hierarchy, + been made to the role of the :class:`_expression.SelectBase` class hierarchy, which is the root of all "SELECT" statement constructs, in that they no longer serve directly as FROM clauses, that is, they no longer subclass - :class:`.FromClause`. For end users, the change mostly means that any - placement of a :func:`~.sql.expression.select` construct in the FROM clause of another - :func:`~.sql.expression.select` requires first that it be wrapped in a subquery first, - which historically is through the use of the :meth:`.SelectBase.alias` + :class:`_expression.FromClause`. For end users, the change mostly means that any + placement of a :func:`_expression.select` construct in the FROM clause of another + :func:`_expression.select` requires first that it be wrapped in a subquery first, + which historically is through the use of the :meth:`_expression.SelectBase.alias` method, and is now also available through the use of - :meth:`.SelectBase.subquery`. This was usually a requirement in any + :meth:`_expression.SelectBase.subquery`. This was usually a requirement in any case since several databases don't accept unnamed SELECT subqueries in their FROM clause in any case. @@ -24,10 +24,10 @@ :tickets: 4617 Added a new Core class :class:`.Subquery`, which takes the place of - :class:`.Alias` when creating named subqueries against a :class:`.SelectBase` - object. :class:`.Subquery` acts in the same way as :class:`.Alias` - and is produced from the :meth:`.SelectBase.subquery` method; for - ease of use and backwards compatibility, the :meth:`.SelectBase.alias` + :class:`_expression.Alias` when creating named subqueries against a :class:`_expression.SelectBase` + object. :class:`.Subquery` acts in the same way as :class:`_expression.Alias` + and is produced from the :meth:`_expression.SelectBase.subquery` method; for + ease of use and backwards compatibility, the :meth:`_expression.SelectBase.alias` method is synonymous with this new method. .. seealso:: @@ -38,15 +38,15 @@ :tags: change, orm :tickets: 4617 - The ORM will now warn when asked to coerce a :func:`~.sql.expression.select` construct into + The ORM will now warn when asked to coerce a :func:`_expression.select` construct into a subquery implicitly. This occurs within places such as the - :meth:`.Query.select_entity_from` and :meth:`.Query.select_from` methods + :meth:`_query.Query.select_entity_from` and :meth:`_query.Query.select_from` methods as well as within the :func:`.with_polymorphic` function. When a - :class:`.SelectBase` (which is what's produced by :func:`~.sql.expression.select`) or - :class:`.Query` object is passed directly to these functions and others, + :class:`_expression.SelectBase` (which is what's produced by :func:`_expression.select`) or + :class:`_query.Query` object is passed directly to these functions and others, the ORM is typically coercing them to be a subquery by calling the - :meth:`.SelectBase.alias` method automatically (which is now superceded by - the :meth:`.SelectBase.subquery` method). See the migration notes linked + :meth:`_expression.SelectBase.alias` method automatically (which is now superceded by + the :meth:`_expression.SelectBase.subquery` method). See the migration notes linked below for further details. .. seealso:: @@ -57,15 +57,15 @@ :tags: bug, sql :tickets: 4617 - The ORDER BY clause of a :class:`.CompoundSelect`, e.g. UNION, EXCEPT, etc. + The ORDER BY clause of a :class:`_selectable.CompoundSelect`, e.g. UNION, EXCEPT, etc. will not render the table name associated with a given column when applying - :meth:`.CompoundSelect.order_by` in terms of a :class:`.Table` - bound + :meth:`_selectable.CompoundSelect.order_by` in terms of a :class:`_schema.Table` - bound column. Most databases require that the names in the ORDER BY clause be expressed as label names only which are matched to names in the first SELECT statement. The change is related to :ticket:`4617` in that a previous workaround was to refer to the ``.c`` attribute of the - :class:`.CompoundSelect` in order to get at a column that has no table + :class:`_selectable.CompoundSelect` in order to get at a column that has no table name. As the subquery is now named, this change allows both the workaround to continue to work, as well as allows table-bound columns as well as the - :attr:`.CompoundSelect.selected_columns` collections to be usable in the - :meth:`.CompoundSelect.order_by` method. \ No newline at end of file + :attr:`_selectable.CompoundSelect.selected_columns` collections to be usable in the + :meth:`_selectable.CompoundSelect.order_by` method. \ No newline at end of file diff --git a/doc/build/changelog/unreleased_14/4617_scalar.rst b/doc/build/changelog/unreleased_14/4617_scalar.rst index 9582c5948a..3486fe3bcf 100644 --- a/doc/build/changelog/unreleased_14/4617_scalar.rst +++ b/doc/build/changelog/unreleased_14/4617_scalar.rst @@ -2,23 +2,23 @@ :tags: change, sql :tickets: 4617 - The :meth:`.SelectBase.as_scalar` and :meth:`.Query.as_scalar` methods have - been renamed to :meth:`.SelectBase.scalar_subquery` and - :meth:`.Query.scalar_subquery`, respectively. The old names continue to + The :meth:`_expression.SelectBase.as_scalar` and :meth:`_query.Query.as_scalar` methods have + been renamed to :meth:`_expression.SelectBase.scalar_subquery` and + :meth:`_query.Query.scalar_subquery`, respectively. The old names continue to exist within 1.4 series with a deprecation warning. In addition, the - implicit coercion of :class:`.SelectBase`, :class:`.Alias`, and other + implicit coercion of :class:`_expression.SelectBase`, :class:`_expression.Alias`, and other SELECT oriented objects into scalar subqueries when evaluated in a column context is also deprecated, and emits a warning that the - :meth:`.SelectBase.scalar_subquery` method should be called explicitly. + :meth:`_expression.SelectBase.scalar_subquery` method should be called explicitly. This warning will in a later major release become an error, however the - message will always be clear when :meth:`.SelectBase.scalar_subquery` needs + message will always be clear when :meth:`_expression.SelectBase.scalar_subquery` needs to be invoked. The latter part of the change is for clarity and to reduce the implicit decisionmaking by the query coercion system. The :meth:`.Subquery.as_scalar` method, which was previously ``Alias.as_scalar``, is also deprecated; ``.scalar_subquery()`` should be - invoked directly from ` :func:`~.sql.expression.select` object or :class:`.Query` object. + invoked directly from ` :func:`_expression.select` object or :class:`_query.Query` object. - This change is part of the larger change to convert :func:`~.sql.expression.select` objects + This change is part of the larger change to convert :func:`_expression.select` objects to no longer be directly part of the "from clause" class hierarchy, which also includes an overhaul of the clause coercion system. diff --git a/doc/build/changelog/unreleased_14/4621.rst b/doc/build/changelog/unreleased_14/4621.rst index 2247783421..22537ec7c7 100644 --- a/doc/build/changelog/unreleased_14/4621.rst +++ b/doc/build/changelog/unreleased_14/4621.rst @@ -2,11 +2,11 @@ :tags: bug, sql :tickets: 4621 - The :class:`.Join` construct no longer considers the "onclause" as a source + The :class:`_expression.Join` construct no longer considers the "onclause" as a source of additional FROM objects to be omitted from the FROM list of an enclosing - :class:`.Select` object as standalone FROM objects. This applies to an ON + :class:`_expression.Select` object as standalone FROM objects. This applies to an ON clause that includes a reference to another FROM object outside the JOIN; while this is usually not correct from a SQL perspective, it's also incorrect for it to be omitted, and the behavioral change makes the - :class:`.Select` / :class:`.Join` behave a bit more intuitively. + :class:`_expression.Select` / :class:`_expression.Join` behave a bit more intuitively. diff --git a/doc/build/changelog/unreleased_14/4643.rst b/doc/build/changelog/unreleased_14/4643.rst index 0caa5f2bb4..9a96785dd3 100644 --- a/doc/build/changelog/unreleased_14/4643.rst +++ b/doc/build/changelog/unreleased_14/4643.rst @@ -3,8 +3,8 @@ :tickets: 4643 Remove deprecated method ``get_primary_keys` in the :class:`.Dialect` and - :class:`.Inspector` classes. Please refer to the - :meth:`.Dialect.get_pk_constraint` and :meth:`.Inspector.get_primary_keys` + :class:`_reflection.Inspector` classes. Please refer to the + :meth:`.Dialect.get_pk_constraint` and :meth:`_reflection.Inspector.get_primary_keys` methods. Remove deprecated event ``dbapi_error`` and the method @@ -53,7 +53,7 @@ maintaining strong identity references. This change also removes the class ``StrongInstanceDict``. - Remove deprecated parameter ``mapper.order_by``. Use :meth:`.Query.order_by` + Remove deprecated parameter ``mapper.order_by``. Use :meth:`_query.Query.order_by` to determine the ordering of a result set. Remove deprecated parameter ``Session._enable_transaction_accounting`. @@ -74,7 +74,7 @@ ``ClauseElement.__or__`` and attribute ``Over.func``. Remove deprecated ``FromClause.count`` method. Please use the - :class:`.functions.count` function available from the + :class:`_functions.count` function available from the :attr:`.func` namespace. .. change:: @@ -82,8 +82,8 @@ :tickets: 4643 Remove deprecated parameters ``text.bindparams`` and ``text.typemap``. - Please refer to the :meth:`.TextClause.bindparams` and - :meth:`.TextClause.columns` methods. + Please refer to the :meth:`_expression.TextClause.bindparams` and + :meth:`_expression.TextClause.columns` methods. Remove deprecated parameter ``Table.useexisting``. Please use - :paramref:`.Table.extend_existing`. + :paramref:`_schema.Table.extend_existing`. diff --git a/doc/build/changelog/unreleased_14/4710.rst b/doc/build/changelog/unreleased_14/4710.rst index 8ba8bb9554..49b9b73b61 100644 --- a/doc/build/changelog/unreleased_14/4710.rst +++ b/doc/build/changelog/unreleased_14/4710.rst @@ -21,7 +21,7 @@ :tags: change, orm :tickets: 4710 - The "KeyedTuple" class returned by :class:`.Query` is now replaced with the + The "KeyedTuple" class returned by :class:`_query.Query` is now replaced with the Core :class:`.Row` class, which behaves in the same way as KeyedTuple. In SQLAlchemy 2.0, both Core and ORM will return result rows using the same :class:`.Row` object. In the interim, Core uses a backwards-compatibility diff --git a/doc/build/changelog/unreleased_14/4712.rst b/doc/build/changelog/unreleased_14/4712.rst index cc8764c72c..aa5771ac54 100644 --- a/doc/build/changelog/unreleased_14/4712.rst +++ b/doc/build/changelog/unreleased_14/4712.rst @@ -2,7 +2,7 @@ :tags: bug, engine :tickets: 4712 - The :class:`.Connection` object will now not clear a rolled-back + The :class:`_engine.Connection` object will now not clear a rolled-back transaction until the outermost transaction is explicitly rolled back. This is essentially the same behavior that the ORM :class:`.Session` has had for a long time, where an explicit call to ``.rollback()`` on all diff --git a/doc/build/changelog/unreleased_14/4719.rst b/doc/build/changelog/unreleased_14/4719.rst index d0a5cca91a..d16f813bea 100644 --- a/doc/build/changelog/unreleased_14/4719.rst +++ b/doc/build/changelog/unreleased_14/4719.rst @@ -2,13 +2,13 @@ :tags: bug, orm :tickets: 4719 - Calling the :meth:`.Query.instances` method without passing a + Calling the :meth:`_query.Query.instances` method without passing a :class:`.QueryContext` is deprecated. The original use case for this was - that a :class:`.Query` could yield ORM objects when given only the entities + that a :class:`_query.Query` could yield ORM objects when given only the entities to be selected as well as a DBAPI cursor object. However, for this to work correctly there is essential metadata that is passed from a SQLAlchemy :class:`.ResultProxy` that is derived from the mapped column expressions, which comes originally from the :class:`.QueryContext`. To retrieve ORM - results from arbitrary SELECT statements, the :meth:`.Query.from_statement` + results from arbitrary SELECT statements, the :meth:`_query.Query.from_statement` method should be used. diff --git a/doc/build/changelog/unreleased_14/4753.rst b/doc/build/changelog/unreleased_14/4753.rst index 3fce341018..53735bd927 100644 --- a/doc/build/changelog/unreleased_14/4753.rst +++ b/doc/build/changelog/unreleased_14/4753.rst @@ -2,16 +2,16 @@ :tags: change,engine :tickets: 4753 - The :func:`~.sql.expression.select` construct and related constructs now allow for + The :func:`_expression.select` construct and related constructs now allow for duplication of column labels and columns themselves in the columns clause, mirroring exactly how column expressions were passed in. This allows the tuples returned by an executed result to match what was SELECTed - for in the first place, which is how the ORM :class:`.Query` works, so + for in the first place, which is how the ORM :class:`_query.Query` works, so this establishes better cross-compatibility between the two constructs. Additionally, it allows column-positioning-sensitive structures such as - UNIONs (i.e. :class:`.CompoundSelect`) to be more intuitively constructed + UNIONs (i.e. :class:`_selectable.CompoundSelect`) to be more intuitively constructed in those cases where a particular column might appear in more than one - place. To support this change, the :class:`.ColumnCollection` has been + place. To support this change, the :class:`_expression.ColumnCollection` has been revised to support duplicate columns as well as to allow integer index access. diff --git a/doc/build/changelog/unreleased_14/4755.rst b/doc/build/changelog/unreleased_14/4755.rst index 8e2ff2e012..b25eb64c90 100644 --- a/doc/build/changelog/unreleased_14/4755.rst +++ b/doc/build/changelog/unreleased_14/4755.rst @@ -3,10 +3,10 @@ :tickets: 4755 Deprecated remaining engine-level introspection and utility methods - including :meth:`.Engine.run_callable`, :meth:`.Engine.transaction`, - :meth:`.Engine.table_names`, :meth:`.Engine.has_table`. The utility + including :meth:`_engine.Engine.run_callable`, :meth:`_engine.Engine.transaction`, + :meth:`_engine.Engine.table_names`, :meth:`_engine.Engine.has_table`. The utility methods are superseded by modern context-manager patterns, and the table - introspection tasks are suited by the :class:`.Inspector` object. + introspection tasks are suited by the :class:`_reflection.Inspector` object. .. change:: :tags: changed, engine @@ -30,6 +30,6 @@ :tags: feature, engine :tickets: 4755 - The :paramref:`.Table.autoload_with` parameter now accepts an :class:`.Inspector` object - directly, as well as any :class:`.Engine` or :class:`.Connection` as was the case before. + The :paramref:`_schema.Table.autoload_with` parameter now accepts an :class:`_reflection.Inspector` object + directly, as well as any :class:`_engine.Engine` or :class:`_engine.Connection` as was the case before. diff --git a/doc/build/changelog/unreleased_14/4829.rst b/doc/build/changelog/unreleased_14/4829.rst index 93c582fa21..10af26af58 100644 --- a/doc/build/changelog/unreleased_14/4829.rst +++ b/doc/build/changelog/unreleased_14/4829.rst @@ -2,11 +2,11 @@ :tags: bug, orm :tickets: 4829 - Added new entity-targeting capabilities to the :class:`.Query` object to + Added new entity-targeting capabilities to the :class:`_query.Query` object to help with the case where the :class:`.Session` is using a bind dictionary - against mapped classes, rather than a single bind, and the :class:`.Query` + against mapped classes, rather than a single bind, and the :class:`_query.Query` is against a Core statement that was ultimately generated from a method - such as :meth:`.Query.subquery`; a deep search is performed to locate + such as :meth:`_query.Query.subquery`; a deep search is performed to locate any ORM entity related to the query in order to locate a mapper if one is not otherwise present. diff --git a/doc/build/changelog/unreleased_14/4877.rst b/doc/build/changelog/unreleased_14/4877.rst index 4a81e021e7..d0f79cea2d 100644 --- a/doc/build/changelog/unreleased_14/4877.rst +++ b/doc/build/changelog/unreleased_14/4877.rst @@ -2,10 +2,10 @@ :tags: bug, engine :tickets: 4877 - Deprecated the behavior by which a :class:`.Column` can be used as the key - in a result set row lookup, when that :class:`.Column` is not part of the + Deprecated the behavior by which a :class:`_schema.Column` can be used as the key + in a result set row lookup, when that :class:`_schema.Column` is not part of the SQL selectable that is being selected; that is, it is only matched on name. A deprecation warning is now emitted for this case. Various ORM use - cases, such as those involving :func:`.text` constructs, have been improved + cases, such as those involving :func:`_expression.text` constructs, have been improved so that this fallback logic is avoided in most cases. diff --git a/doc/build/changelog/unreleased_14/4971.rst b/doc/build/changelog/unreleased_14/4971.rst index 08e94a09cf..13eb73c56c 100644 --- a/doc/build/changelog/unreleased_14/4971.rst +++ b/doc/build/changelog/unreleased_14/4971.rst @@ -2,7 +2,7 @@ :tags: bug, oracle :tickets: 4971 - The :class:`.oracle.INTERVAL` class of the Oracle dialect is now correctly + The :class:`_oracle.INTERVAL` class of the Oracle dialect is now correctly a subclass of the abstract version of :class:`.Interval` as well as the correct "emulated" base class, which allows for correct behavior under both native and non-native modes; previously it was only based on diff --git a/doc/build/changelog/unreleased_14/4976.rst b/doc/build/changelog/unreleased_14/4976.rst index ec8ae89eca..2bba598969 100644 --- a/doc/build/changelog/unreleased_14/4976.rst +++ b/doc/build/changelog/unreleased_14/4976.rst @@ -4,10 +4,10 @@ Added support for use of the :class:`.Sequence` construct with MariaDB 10.3 and greater, as this is now supported by this database. The construct - integrates with the :class:`.Table` object in the same way that it does for + integrates with the :class:`_schema.Table` object in the same way that it does for other databases like PostrgreSQL and Oracle; if is present on the integer primary key "autoincrement" column, it is used to generate defaults. For - backwards compatibility, to support a :class:`.Table` that has a + backwards compatibility, to support a :class:`_schema.Table` that has a :class:`.Sequence` on it to support sequence only databases like Oracle, while still not having the sequence fire off for MariaDB, the optional=True flag should be set, which indicates the sequence should only be used to diff --git a/doc/build/changelog/unreleased_14/4980.rst b/doc/build/changelog/unreleased_14/4980.rst index cfb827c4db..715cbd01ed 100644 --- a/doc/build/changelog/unreleased_14/4980.rst +++ b/doc/build/changelog/unreleased_14/4980.rst @@ -2,7 +2,7 @@ :tags: bug, mssql :tickets: 4980 - Fixed the base class of the :class:`.mssql.DATETIMEOFFSET` datatype to + Fixed the base class of the :class:`_mssql.DATETIMEOFFSET` datatype to be based on the :class:`.DateTime` class hierarchy, as this is a datetime-holding datatype. diff --git a/doc/build/changelog/unreleased_14/4994.rst b/doc/build/changelog/unreleased_14/4994.rst index 979af71daa..8d19063bcc 100644 --- a/doc/build/changelog/unreleased_14/4994.rst +++ b/doc/build/changelog/unreleased_14/4994.rst @@ -3,7 +3,7 @@ :tickets: 4994 An error is raised if any persistence-related "cascade" settings are made - on a :func:`.relationship` that also sets up viewonly=True. The "cascade" + on a :func:`_orm.relationship` that also sets up viewonly=True. The "cascade" settings now default to non-persistence related settings only when viewonly is also set. This is the continuation from :ticket:`4993` where this setting was changed to emit a warning in 1.3. diff --git a/doc/build/changelog/unreleased_14/5001.rst b/doc/build/changelog/unreleased_14/5001.rst index 986fec8d47..c4e170db7e 100644 --- a/doc/build/changelog/unreleased_14/5001.rst +++ b/doc/build/changelog/unreleased_14/5001.rst @@ -3,7 +3,7 @@ :tickets: 5001 Fixed issue where when constructing constraints from ORM-bound columns, - primarily :class:`.ForeignKey` objects but also :class:`.UniqueConstraint`, + primarily :class:`_schema.ForeignKey` objects but also :class:`.UniqueConstraint`, :class:`.CheckConstraint` and others, the ORM-level :class:`.InstrumentedAttribute` is discarded entirely, and all ORM-level annotations from the columns are removed; this is so that the constraints diff --git a/doc/build/changelog/unreleased_14/5074.rst b/doc/build/changelog/unreleased_14/5074.rst index 3b6b951c46..95e93b3dce 100644 --- a/doc/build/changelog/unreleased_14/5074.rst +++ b/doc/build/changelog/unreleased_14/5074.rst @@ -14,7 +14,7 @@ will be emitted when the :class:`.Session` first requires a :class:`.SessionTransaction` be present, rather than whenever the :class:`.Session` were created or the previous :class:`.SessionTransaction` - were closed. Interactions with the :class:`.Engine` and the database + were closed. Interactions with the :class:`_engine.Engine` and the database itself remain unaffected. .. seealso:: diff --git a/doc/build/changelog/unreleased_14/5122.rst b/doc/build/changelog/unreleased_14/5122.rst index 8a76e597c4..fbc7397acd 100644 --- a/doc/build/changelog/unreleased_14/5122.rst +++ b/doc/build/changelog/unreleased_14/5122.rst @@ -3,14 +3,14 @@ :tickets: 5122 A query that is against a mapped inheritance subclass which also uses - :meth:`.Query.select_entity_from` or a similar technique in order to + :meth:`_query.Query.select_entity_from` or a similar technique in order to provide an existing subquery to SELECT from, will now raise an error if the given subquery returns entities that do not correspond to the given subclass, that is, they are sibling or superclasses in the same hierarchy. Previously, these would be returned without error. Additionally, if the inheritance mapping is a single-inheritance mapping, the given subquery must apply the appropriate filtering against the polymorphic discriminator - column in order to avoid this error; previously, the :class:`.Query` would + column in order to avoid this error; previously, the :class:`_query.Query` would add this criteria to the outside query however this interferes with some kinds of query that return other kinds of entities as well. diff --git a/doc/build/changelog/unreleased_14/5131.rst b/doc/build/changelog/unreleased_14/5131.rst index 5205699d8d..3243007579 100644 --- a/doc/build/changelog/unreleased_14/5131.rst +++ b/doc/build/changelog/unreleased_14/5131.rst @@ -2,7 +2,7 @@ :tags: usecase, engine :tickets: 5131 - The :meth:`.Connection.connect` method is deprecated as is the concept of - "connection branching", which copies a :class:`.Connection` into a new one + The :meth:`_engine.Connection.connect` method is deprecated as is the concept of + "connection branching", which copies a :class:`_engine.Connection` into a new one that has a no-op ".close()" method. This pattern is oriented around the "connectionless execution" concept which is also being removed in 2.0. diff --git a/doc/build/changelog/unreleased_14/5134.rst b/doc/build/changelog/unreleased_14/5134.rst index 229fd5e2db..c7b0e8398e 100644 --- a/doc/build/changelog/unreleased_14/5134.rst +++ b/doc/build/changelog/unreleased_14/5134.rst @@ -2,7 +2,7 @@ :tags: orm, bug :tickets: 5134 - Deprecated logic in :meth:`.Query.distinct` that automatically adds + Deprecated logic in :meth:`_query.Query.distinct` that automatically adds columns in the ORDER BY clause to the columns clause; this will be removed in 2.0. diff --git a/doc/build/changelog/unreleased_14/5171.rst b/doc/build/changelog/unreleased_14/5171.rst index 65824a0a6c..5082e4bcb2 100644 --- a/doc/build/changelog/unreleased_14/5171.rst +++ b/doc/build/changelog/unreleased_14/5171.rst @@ -9,6 +9,6 @@ and are not otherwise in an inheriting sibling/overriding arrangement, and will populate the same foreign key column, a warning is emitted at mapper configuration time warning that a conflict may arise. A new parameter - :paramref:`.relationship.overlaps` is added to suit those very rare cases + :paramref:`_orm.relationship.overlaps` is added to suit those very rare cases where such an overlapping persistence arrangement may be unavoidable. diff --git a/doc/build/changelog/unreleased_14/5192.rst b/doc/build/changelog/unreleased_14/5192.rst index cb8833b5db..ac49c49569 100644 --- a/doc/build/changelog/unreleased_14/5192.rst +++ b/doc/build/changelog/unreleased_14/5192.rst @@ -3,6 +3,6 @@ :tickets: 5192 The :func:`.eagerload` and :func:`.relation` were old aliases and are - now deprecated. Use :func:`.joinedload` and :func:`.relationship` + now deprecated. Use :func:`_orm.joinedload` and :func:`_orm.relationship` respectively. diff --git a/doc/build/changelog/unreleased_14/5221.rst b/doc/build/changelog/unreleased_14/5221.rst index afb35f3fdb..883f0029df 100644 --- a/doc/build/changelog/unreleased_14/5221.rst +++ b/doc/build/changelog/unreleased_14/5221.rst @@ -3,13 +3,13 @@ :tickets: 5221 Enhanced the disambiguating labels feature of the - :func:`~.sql.expression.select` construct such that when a select statement + :func:`_expression.select` construct such that when a select statement is used in a subquery, repeated column names from different tables are now automatically labeled with a unique label name, without the need to use the full "apply_labels()" feature that conbines tablename plus column name. The disambigated labels are available as plain string keys in the .c collection of the subquery, and most importantly the feature allows an ORM - :func:`.orm.aliased` construct against the combination of an entity and an + :func:`_orm.aliased` construct against the combination of an entity and an arbitrary subquery to work correctly, targeting the correct columns despite same-named columns in the source tables, without the need for an "apply labels" warning. @@ -19,4 +19,4 @@ :ref:`migration_20_query_from_self` - Illustrates the new disambiguation feature as part of a strategy to migrate away from the - :meth:`.Query.from_self` method. \ No newline at end of file + :meth:`_query.Query.from_self` method. \ No newline at end of file diff --git a/doc/build/changelog/unreleased_14/5244.rst b/doc/build/changelog/unreleased_14/5244.rst index c6a7520b0d..e2e97d0a2c 100644 --- a/doc/build/changelog/unreleased_14/5244.rst +++ b/doc/build/changelog/unreleased_14/5244.rst @@ -2,5 +2,5 @@ :tags: change, reflection :tickets: 5244 - The :meth:`.Inspector.reflecttable` was renamed to - :meth:`.Inspector.reflect_table`. \ No newline at end of file + The :meth:`_reflection.Inspector.reflecttable` was renamed to + :meth:`_reflection.Inspector.reflect_table`. \ No newline at end of file diff --git a/doc/build/changelog/unreleased_14/527.rst b/doc/build/changelog/unreleased_14/527.rst index 83f59daf5b..22d0c636d7 100644 --- a/doc/build/changelog/unreleased_14/527.rst +++ b/doc/build/changelog/unreleased_14/527.rst @@ -4,7 +4,7 @@ The :meth:`.Index.create` and :meth:`.Index.drop` methods now have a parameter :paramref:`.Index.create.checkfirst`, in the same way as that of - :class:`.Table` and :class:`.Sequence`, which when enabled will cause the + :class:`_schema.Table` and :class:`.Sequence`, which when enabled will cause the operation to detect if the index exists (or not) before performing a create or drop operation. diff --git a/doc/build/changelog/unreleased_14/asbool_join.rst b/doc/build/changelog/unreleased_14/asbool_join.rst index 154f056bb4..fbad8008e0 100644 --- a/doc/build/changelog/unreleased_14/asbool_join.rst +++ b/doc/build/changelog/unreleased_14/asbool_join.rst @@ -2,7 +2,7 @@ :tags: usecase, sql The :func:`.true` and :func:`.false` operators may now be applied as the - "onclause" of a :func:`.sql.join` on a backend that does not support + "onclause" of a :func:`_expression.join` on a backend that does not support "native boolean" expressions, e.g. Oracle or SQL Server, and the expression will render as "1=1" for true and "1=0" false. This is the behavior that was introduced many years ago in :ticket:`2804` for and/or expressions. diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst index 2191dee6e3..b9b9d6fcbd 100644 --- a/doc/build/core/connections.rst +++ b/doc/build/core/connections.rst @@ -6,41 +6,41 @@ Working with Engines and Connections .. module:: sqlalchemy.engine -This section details direct usage of the :class:`.Engine`, -:class:`.Connection`, and related objects. Its important to note that when +This section details direct usage of the :class:`_engine.Engine`, +:class:`_engine.Connection`, and related objects. Its important to note that when using the SQLAlchemy ORM, these objects are not generally accessed; instead, the :class:`.Session` object is used as the interface to the database. However, for applications that are built around direct usage of textual SQL statements and/or SQL expression constructs without involvement by the ORM's -higher level management services, the :class:`.Engine` and -:class:`.Connection` are king (and queen?) - read on. +higher level management services, the :class:`_engine.Engine` and +:class:`_engine.Connection` are king (and queen?) - read on. Basic Usage =========== -Recall from :doc:`/core/engines` that an :class:`.Engine` is created via +Recall from :doc:`/core/engines` that an :class:`_engine.Engine` is created via the :func:`.create_engine` call:: engine = create_engine('mysql://scott:tiger@localhost/test') The typical usage of :func:`.create_engine()` is once per particular database URL, held globally for the lifetime of a single application process. A single -:class:`.Engine` manages many individual :term:`DBAPI` connections on behalf of +:class:`_engine.Engine` manages many individual :term:`DBAPI` connections on behalf of the process and is intended to be called upon in a concurrent fashion. The -:class:`.Engine` is **not** synonymous to the DBAPI ``connect`` function, which -represents just one connection resource - the :class:`.Engine` is most +:class:`_engine.Engine` is **not** synonymous to the DBAPI ``connect`` function, which +represents just one connection resource - the :class:`_engine.Engine` is most efficient when created just once at the module level of an application, not per-object or per-function call. .. sidebar:: tip - When using an :class:`.Engine` with multiple Python processes, such as when + When using an :class:`_engine.Engine` with multiple Python processes, such as when using ``os.fork`` or Python ``multiprocessing``, it's important that the engine is initialized per process. See :ref:`pooling_multiprocessing` for details. -The most basic function of the :class:`.Engine` is to provide access to a -:class:`.Connection`, which can then invoke SQL statements. To emit +The most basic function of the :class:`_engine.Engine` is to provide access to a +:class:`_engine.Connection`, which can then invoke SQL statements. To emit a textual statement to the database looks like:: from sqlalchemy import text @@ -50,12 +50,12 @@ a textual statement to the database looks like:: for row in result: print("username:", row['username']) -Above, the :meth:`.Engine.connect` method returns a :class:`.Connection` +Above, the :meth:`_engine.Engine.connect` method returns a :class:`_engine.Connection` object, and by using it in a Python context manager (e.g. the ``with:`` -statement) the :meth:`.Connection.close` method is automatically invoked at the -end of the block. The :class:`.Connection`, is a **proxy** object for an +statement) the :meth:`_engine.Connection.close` method is automatically invoked at the +end of the block. The :class:`_engine.Connection`, is a **proxy** object for an actual DBAPI connection. The DBAPI connection is retrieved from the connection -pool at the point at which :class:`.Connection` is created. +pool at the point at which :class:`_engine.Connection` is created. The object returned is known as :class:`.ResultProxy`, which references a DBAPI cursor and provides methods for fetching rows @@ -65,7 +65,7 @@ exhausted. A :class:`.ResultProxy` that returns no rows, such as that of an UPDATE statement (without any returned rows), releases cursor resources immediately upon construction. -When the :class:`.Connection` is closed at the end of the ``with:`` block, the +When the :class:`_engine.Connection` is closed at the end of the ``with:`` block, the referenced DBAPI connection is :term:`released` to the connection pool. From the perspective of the database itself, the connection pool will not actually "close" the connection assuming the pool has room to store this connection for @@ -78,8 +78,8 @@ its next use. 2.0 with a newly refined object known as :class:`.future.Result`. Our example above illustrated the execution of a textual SQL string, which -should be invoked by using the :func:`.text` construct to indicate that -we'd like to use textual SQL. The :meth:`~.Connection.execute` method can of +should be invoked by using the :func:`_expression.text` construct to indicate that +we'd like to use textual SQL. The :meth:`_engine.Connection.execute` method can of course accommodate more than that, including the variety of SQL expression constructs described in :ref:`sqlexpression_toplevel`. @@ -90,14 +90,14 @@ Using Transactions .. note:: This section describes how to use transactions when working directly - with :class:`.Engine` and :class:`.Connection` objects. When using the + with :class:`_engine.Engine` and :class:`_engine.Connection` objects. When using the SQLAlchemy ORM, the public API for transaction control is via the :class:`.Session` object, which makes usage of the :class:`.Transaction` object internally. See :ref:`unitofwork_transaction` for further information. -The :class:`~sqlalchemy.engine.Connection` object provides a :meth:`~.Connection.begin` -method which returns a :class:`.Transaction` object. Like the :class:`.Connection` +The :class:`~sqlalchemy.engine.Connection` object provides a :meth:`_engine.Connection.begin` +method which returns a :class:`.Transaction` object. Like the :class:`_engine.Connection` itself, this object is usually used within a Python ``with:`` block so that its scope is managed:: @@ -106,8 +106,8 @@ that its scope is managed:: r1 = connection.execute(table1.select()) connection.execute(table1.insert(), {"col1": 7, "col2": "this is some data"}) -The above block can be stated more simply by using the :meth:`.Engine.begin` -method of :class:`.Engine`:: +The above block can be stated more simply by using the :meth:`_engine.Engine.begin` +method of :class:`_engine.Engine`:: # runs a transaction with engine.begin() as connection: @@ -121,7 +121,7 @@ outwards. The underlying object used to represent the transaction is the :class:`.Transaction` object. This object is returned by the -:meth:`.Connection.begin` method and includes the methods +:meth:`_engine.Connection.begin` method and includes the methods :meth:`.Transaction.commit` and :meth:`.Transaction.rollback`. The context manager calling form, which invokes these methods automatically, is recommended as a best practice. @@ -137,7 +137,7 @@ Nesting of Transaction Blocks The :class:`.Transaction` object also handles "nested" behavior by keeping track of the outermost begin/commit pair. In this example, two functions both -issue a transaction on a :class:`.Connection`, but only the outermost +issue a transaction on a :class:`_engine.Connection`, but only the outermost :class:`.Transaction` object actually takes effect when it is committed. .. sourcecode:: python+sql @@ -209,10 +209,10 @@ the ORM, as the :class:`.Session` object by default always maintains an ongoing :class:`.Transaction`. Full control of the "autocommit" behavior is available using the generative -:meth:`.Connection.execution_options` method provided on :class:`.Connection` -and :class:`.Engine`, using the "autocommit" flag which will +:meth:`_engine.Connection.execution_options` method provided on :class:`_engine.Connection` +and :class:`_engine.Engine`, using the "autocommit" flag which will turn on or off the autocommit for the selected scope. For example, a -:func:`.text` construct representing a stored procedure that commits might use +:func:`_expression.text` construct representing a stored procedure that commits might use it so that a SELECT statement will issue a COMMIT:: with engine.connect().execution_options(autocommit=True) as conn: @@ -229,10 +229,10 @@ Connectionless Execution, Implicit Execution :ref:`migration_20_implicit_execution` for background. Recall from the first section we mentioned executing with and without explicit -usage of :class:`.Connection`. "Connectionless" execution +usage of :class:`_engine.Connection`. "Connectionless" execution refers to the usage of the ``execute()`` method on an object -which is not a :class:`.Connection`. This was illustrated using the -:meth:`~.Engine.execute` method of :class:`.Engine`:: +which is not a :class:`_engine.Connection`. This was illustrated using the +:meth:`_engine.Engine.execute` method of :class:`_engine.Engine`:: result = engine.execute(text("select username from users")) for row in result: @@ -242,7 +242,7 @@ In addition to "connectionless" execution, it is also possible to use the :meth:`~.Executable.execute` method of any :class:`.Executable` construct, which is a marker for SQL expression objects that support execution. The SQL expression object itself references an -:class:`.Engine` or :class:`.Connection` known as the **bind**, which it uses +:class:`_engine.Engine` or :class:`_engine.Connection` known as the **bind**, which it uses in order to provide so-called "implicit" execution services. Given a table as below:: @@ -256,7 +256,7 @@ Given a table as below:: ) Explicit execution delivers the SQL text or constructed SQL expression to the -:meth:`~.Connection.execute` method of :class:`~sqlalchemy.engine.Connection`: +:meth:`_engine.Connection.execute` method of :class:`~sqlalchemy.engine.Connection`: .. sourcecode:: python+sql @@ -267,7 +267,7 @@ Explicit execution delivers the SQL text or constructed SQL expression to the # .... Explicit, connectionless execution delivers the expression to the -:meth:`~.Engine.execute` method of :class:`~sqlalchemy.engine.Engine`: +:meth:`_engine.Engine.execute` method of :class:`~sqlalchemy.engine.Engine`: .. sourcecode:: python+sql @@ -284,9 +284,9 @@ for being invoked against the database. The method makes usage of the assumption that either an :class:`~sqlalchemy.engine.Engine` or :class:`~sqlalchemy.engine.Connection` has been **bound** to the expression -object. By "bound" we mean that the special attribute :attr:`.MetaData.bind` +object. By "bound" we mean that the special attribute :attr:`_schema.MetaData.bind` has been used to associate a series of -:class:`.Table` objects and all SQL constructs derived from them with a specific +:class:`_schema.Table` objects and all SQL constructs derived from them with a specific engine:: engine = create_engine('sqlite:///file.db') @@ -296,23 +296,23 @@ engine:: # .... result.close() -Above, we associate an :class:`.Engine` with a :class:`.MetaData` object using -the special attribute :attr:`.MetaData.bind`. The :func:`~.sql.expression.select` construct produced -from the :class:`.Table` object has a method :meth:`~.Executable.execute`, which will -search for an :class:`.Engine` that's "bound" to the :class:`.Table`. +Above, we associate an :class:`_engine.Engine` with a :class:`_schema.MetaData` object using +the special attribute :attr:`_schema.MetaData.bind`. The :func:`_expression.select` construct produced +from the :class:`_schema.Table` object has a method :meth:`~.Executable.execute`, which will +search for an :class:`_engine.Engine` that's "bound" to the :class:`_schema.Table`. Overall, the usage of "bound metadata" has three general effects: * SQL statement objects gain an :meth:`.Executable.execute` method which automatically locates a "bind" with which to execute themselves. * The ORM :class:`.Session` object supports using "bound metadata" in order - to establish which :class:`.Engine` should be used to invoke SQL statements + to establish which :class:`_engine.Engine` should be used to invoke SQL statements on behalf of a particular mapped class, though the :class:`.Session` - also features its own explicit system of establishing complex :class:`.Engine`/ + also features its own explicit system of establishing complex :class:`_engine.Engine`/ mapped class configurations. -* The :meth:`.MetaData.create_all`, :meth:`.MetaData.drop_all`, :meth:`.Table.create`, - :meth:`.Table.drop`, and "autoload" features all make usage of the bound - :class:`.Engine` automatically without the need to pass it explicitly. +* The :meth:`_schema.MetaData.create_all`, :meth:`_schema.MetaData.drop_all`, :meth:`_schema.Table.create`, + :meth:`_schema.Table.drop`, and "autoload" features all make usage of the bound + :class:`_engine.Engine` automatically without the need to pass it explicitly. .. note:: @@ -320,11 +320,11 @@ Overall, the usage of "bound metadata" has three general effects: While they offer some convenience, they are no longer required by any API and are never necessary. - In applications where multiple :class:`.Engine` objects are present, each one logically associated + In applications where multiple :class:`_engine.Engine` objects are present, each one logically associated with a certain set of tables (i.e. *vertical sharding*), the "bound metadata" technique can be used - so that individual :class:`.Table` can refer to the appropriate :class:`.Engine` automatically; + so that individual :class:`_schema.Table` can refer to the appropriate :class:`_engine.Engine` automatically; in particular this is supported within the ORM via the :class:`.Session` object - as a means to associate :class:`.Table` objects with an appropriate :class:`.Engine`, + as a means to associate :class:`_schema.Table` objects with an appropriate :class:`_engine.Engine`, as an alternative to using the bind arguments accepted directly by the :class:`.Session`. However, the "implicit execution" technique is not at all appropriate for use with the @@ -349,7 +349,7 @@ In both "connectionless" examples, the :class:`~sqlalchemy.engine.ResultProxy` returned by the ``execute()`` call references the :class:`~sqlalchemy.engine.Connection` used to issue the SQL statement. When the :class:`.ResultProxy` is closed, the underlying -:class:`.Connection` is closed for us, resulting in the +:class:`_engine.Connection` is closed for us, resulting in the DBAPI connection being returned to the pool with transactional resources removed. .. _schema_translating: @@ -360,7 +360,7 @@ Translation of Schema Names To support multi-tenancy applications that distribute common sets of tables into multiple schemas, the :paramref:`.Connection.execution_options.schema_translate_map` -execution option may be used to repurpose a set of :class:`.Table` objects +execution option may be used to repurpose a set of :class:`_schema.Table` objects to render under different schema names without any changes. Given a table:: @@ -371,10 +371,10 @@ Given a table:: Column('name', String(50)) ) -The "schema" of this :class:`.Table` as defined by the -:paramref:`.Table.schema` attribute is ``None``. The +The "schema" of this :class:`_schema.Table` as defined by the +:paramref:`_schema.Table.schema` attribute is ``None``. The :paramref:`.Connection.execution_options.schema_translate_map` can specify -that all :class:`.Table` objects with a schema of ``None`` would instead +that all :class:`_schema.Table` objects with a schema of ``None`` would instead render the schema as ``user_schema_one``:: connection = engine.connect().execution_options( @@ -399,18 +399,18 @@ map can specify any number of target->destination schemas:: The :paramref:`.Connection.execution_options.schema_translate_map` parameter affects all DDL and SQL constructs generated from the SQL expression language, -as derived from the :class:`.Table` or :class:`.Sequence` objects. -It does **not** impact literal string SQL used via the :func:`.expression.text` -construct nor via plain strings passed to :meth:`.Connection.execute`. +as derived from the :class:`_schema.Table` or :class:`.Sequence` objects. +It does **not** impact literal string SQL used via the :func:`_expression.text` +construct nor via plain strings passed to :meth:`_engine.Connection.execute`. The feature takes effect **only** in those cases where the name of the -schema is derived directly from that of a :class:`.Table` or :class:`.Sequence`; +schema is derived directly from that of a :class:`_schema.Table` or :class:`.Sequence`; it does not impact methods where a string schema name is passed directly. By this pattern, it takes effect within the "can create" / "can drop" checks -performed by methods such as :meth:`.MetaData.create_all` or -:meth:`.MetaData.drop_all` are called, and it takes effect when -using table reflection given a :class:`.Table` object. However it does -**not** affect the operations present on the :class:`.Inspector` object, +performed by methods such as :meth:`_schema.MetaData.create_all` or +:meth:`_schema.MetaData.drop_all` are called, and it takes effect when +using table reflection given a :class:`_schema.Table` object. However it does +**not** affect the operations present on the :class:`_reflection.Inspector` object, as the schema name is passed to these methods explicitly. .. versionadded:: 1.1 @@ -420,17 +420,17 @@ as the schema name is passed to these methods explicitly. Engine Disposal =============== -The :class:`.Engine` refers to a connection pool, which means under normal +The :class:`_engine.Engine` refers to a connection pool, which means under normal circumstances, there are open database connections present while the -:class:`.Engine` object is still resident in memory. When an :class:`.Engine` +:class:`_engine.Engine` object is still resident in memory. When an :class:`_engine.Engine` is garbage collected, its connection pool is no longer referred to by -that :class:`.Engine`, and assuming none of its connections are still checked +that :class:`_engine.Engine`, and assuming none of its connections are still checked out, the pool and its connections will also be garbage collected, which has the effect of closing out the actual database connections as well. But otherwise, -the :class:`.Engine` will hold onto open database connections assuming +the :class:`_engine.Engine` will hold onto open database connections assuming it uses the normally default pool implementation of :class:`.QueuePool`. -The :class:`.Engine` is intended to normally be a permanent +The :class:`_engine.Engine` is intended to normally be a permanent fixture established up-front and maintained throughout the lifespan of an application. It is **not** intended to be created and disposed on a per-connection basis; it is instead a registry that maintains both a pool @@ -439,45 +439,45 @@ and DBAPI in use, as well as some degree of internal caching of per-database resources. However, there are many cases where it is desirable that all connection resources -referred to by the :class:`.Engine` be completely closed out. It's +referred to by the :class:`_engine.Engine` be completely closed out. It's generally not a good idea to rely on Python garbage collection for this -to occur for these cases; instead, the :class:`.Engine` can be explicitly disposed using -the :meth:`.Engine.dispose` method. This disposes of the engine's +to occur for these cases; instead, the :class:`_engine.Engine` can be explicitly disposed using +the :meth:`_engine.Engine.dispose` method. This disposes of the engine's underlying connection pool and replaces it with a new one that's empty. -Provided that the :class:`.Engine` +Provided that the :class:`_engine.Engine` is discarded at this point and no longer used, all **checked-in** connections which it refers to will also be fully closed. -Valid use cases for calling :meth:`.Engine.dispose` include: +Valid use cases for calling :meth:`_engine.Engine.dispose` include: * When a program wants to release any remaining checked-in connections held by the connection pool and expects to no longer be connected to that database at all for any future operations. * When a program uses multiprocessing or ``fork()``, and an - :class:`.Engine` object is copied to the child process, - :meth:`.Engine.dispose` should be called so that the engine creates + :class:`_engine.Engine` object is copied to the child process, + :meth:`_engine.Engine.dispose` should be called so that the engine creates brand new database connections local to that fork. Database connections generally do **not** travel across process boundaries. * Within test suites or multitenancy scenarios where many - ad-hoc, short-lived :class:`.Engine` objects may be created and disposed. + ad-hoc, short-lived :class:`_engine.Engine` objects may be created and disposed. Connections that are **checked out** are **not** discarded when the engine is disposed or garbage collected, as these connections are still strongly referenced elsewhere by the application. -However, after :meth:`.Engine.dispose` is called, those -connections are no longer associated with that :class:`.Engine`; when they +However, after :meth:`_engine.Engine.dispose` is called, those +connections are no longer associated with that :class:`_engine.Engine`; when they are closed, they will be returned to their now-orphaned connection pool which will ultimately be garbage collected, once all connections which refer to it are also no longer referenced anywhere. Since this process is not easy to control, it is strongly recommended that -:meth:`.Engine.dispose` is called only after all checked out connections +:meth:`_engine.Engine.dispose` is called only after all checked out connections are checked in or otherwise de-associated from their pool. An alternative for applications that are negatively impacted by the -:class:`.Engine` object's use of connection pooling is to disable pooling +:class:`_engine.Engine` object's use of connection pooling is to disable pooling entirely. This typically incurs only a modest performance impact upon the use of new connections, and means that when a connection is checked in, it is entirely closed out and is not held in memory. See :ref:`pool_switching` @@ -488,12 +488,12 @@ for guidelines on how to disable pooling. Working with Driver SQL and Raw DBAPI Connections ================================================= -The introduction on using :meth:`.Connection.execute` made use of the -:func:`.sql.text` construct in order to illustrate how textual SQL statements +The introduction on using :meth:`_engine.Connection.execute` made use of the +:func:`_expression.text` construct in order to illustrate how textual SQL statements may be invoked. When working with SQLAlchemy, textual SQL is actually more of the exception rather than the norm, as the Core expression language and the ORM both abstract away the textual representation of SQL. Hpwever, the -:func:`.sql.text` construct itself also provides some abstraction of textual +:func:`_expression.text` construct itself also provides some abstraction of textual SQL in that it normalizes how bound parameters are passed, as well as that it supports datatyping behavior for parameters and result set rows. @@ -502,14 +502,14 @@ Invoking SQL strings directly to the driver For the use case where one wants to invoke textual SQL directly passed to the underlying driver (known as the :term:`DBAPI`) without any intervention -from the :func:`.sql.text` construct, the :meth:`.Connection.exec_driver_sql` +from the :func:`_expression.text` construct, the :meth:`_engine.Connection.exec_driver_sql` method may be used:: with engine.connect() as conn: conn.exec_driver_sql("SET param='bar'") -.. versionadded:: 1.4 Added the :meth:`.Connection.exec_driver_sql` method. +.. versionadded:: 1.4 Added the :meth:`_engine.Connection.exec_driver_sql` method. Working with the DBAPI cursor directly -------------------------------------- @@ -520,8 +520,8 @@ as dealing with multiple result sets. In these cases, it's just as expedient to deal with the raw DBAPI connection directly. The most common way to access the raw DBAPI connection is to get it -from an already present :class:`.Connection` object directly. It is -present using the :attr:`.Connection.connection` attribute:: +from an already present :class:`_engine.Connection` object directly. It is +present using the :attr:`_engine.Connection.connection` attribute:: connection = engine.connect() dbapi_conn = connection.connection @@ -529,17 +529,17 @@ present using the :attr:`.Connection.connection` attribute:: The DBAPI connection here is actually a "proxied" in terms of the originating connection pool, however this is an implementation detail that in most cases can be ignored. As this DBAPI connection is still -contained within the scope of an owning :class:`.Connection` object, it is -best to make use of the :class:`.Connection` object for most features such -as transaction control as well as calling the :meth:`.Connection.close` +contained within the scope of an owning :class:`_engine.Connection` object, it is +best to make use of the :class:`_engine.Connection` object for most features such +as transaction control as well as calling the :meth:`_engine.Connection.close` method; if these operations are performed on the DBAPI connection directly, -the owning :class:`.Connection` will not be aware of these changes in state. +the owning :class:`_engine.Connection` will not be aware of these changes in state. To overcome the limitations imposed by the DBAPI connection that is -maintained by an owning :class:`.Connection`, a DBAPI connection is also +maintained by an owning :class:`_engine.Connection`, a DBAPI connection is also available without the need to procure a -:class:`.Connection` first, using the :meth:`.Engine.raw_connection` method -of :class:`.Engine`:: +:class:`_engine.Connection` first, using the :meth:`_engine.Engine.raw_connection` method +of :class:`_engine.Engine`:: dbapi_conn = engine.raw_connection() diff --git a/doc/build/core/constraints.rst b/doc/build/core/constraints.rst index c077cd8377..4abe7709d7 100644 --- a/doc/build/core/constraints.rst +++ b/doc/build/core/constraints.rst @@ -8,7 +8,7 @@ Defining Constraints and Indexes ================================ This section will discuss SQL :term:`constraints` and indexes. In SQLAlchemy -the key classes include :class:`.ForeignKeyConstraint` and :class:`.Index`. +the key classes include :class:`_schema.ForeignKeyConstraint` and :class:`.Index`. .. _metadata_foreignkeys: @@ -111,11 +111,11 @@ rendered "inline" within the CREATE TABLE statement, such as: The ``CONSTRAINT .. FOREIGN KEY`` directive is used to create the constraint in an "inline" fashion within the CREATE TABLE definition. The -:meth:`.MetaData.create_all` and :meth:`.MetaData.drop_all` methods do -this by default, using a topological sort of all the :class:`.Table` objects +:meth:`_schema.MetaData.create_all` and :meth:`_schema.MetaData.drop_all` methods do +this by default, using a topological sort of all the :class:`_schema.Table` objects involved such that tables are created and dropped in order of their foreign key dependency (this sort is also available via the -:attr:`.MetaData.sorted_tables` accessor). +:attr:`_schema.MetaData.sorted_tables` accessor). This approach can't work when two or more foreign key constraints are involved in a "dependency cycle", where a set of tables @@ -144,7 +144,7 @@ most forms of ALTER. Given a schema like:: ) ) -When we call upon :meth:`.MetaData.create_all` on a backend such as the +When we call upon :meth:`_schema.MetaData.create_all` on a backend such as the PostgreSQL backend, the cycle between these two tables is resolved and the constraints are created separately: @@ -199,8 +199,8 @@ This error only applies to the DROP case as we can emit "ADD CONSTRAINT" in the CREATE case without a name; the database typically assigns one automatically. -The :paramref:`.ForeignKeyConstraint.use_alter` and -:paramref:`.ForeignKey.use_alter` keyword arguments can be used +The :paramref:`_schema.ForeignKeyConstraint.use_alter` and +:paramref:`_schema.ForeignKey.use_alter` keyword arguments can be used to manually resolve dependency cycles. We can add this flag only to the ``'element'`` table as follows:: @@ -238,8 +238,8 @@ and not the other one: FOREIGN KEY(parent_node_id) REFERENCES node (node_id) {stop} -:paramref:`.ForeignKeyConstraint.use_alter` and -:paramref:`.ForeignKey.use_alter`, when used in conjunction with a drop +:paramref:`_schema.ForeignKeyConstraint.use_alter` and +:paramref:`_schema.ForeignKey.use_alter`, when used in conjunction with a drop operation, will require that the constraint is named, else an error like the following is generated:: @@ -247,14 +247,14 @@ like the following is generated:: ForeignKeyConstraint(...); it has no name .. versionchanged:: 1.0.0 - The DDL system invoked by - :meth:`.MetaData.create_all` - and :meth:`.MetaData.drop_all` will now automatically resolve mutually + :meth:`_schema.MetaData.create_all` + and :meth:`_schema.MetaData.drop_all` will now automatically resolve mutually depdendent foreign keys between tables declared by - :class:`.ForeignKeyConstraint` and :class:`.ForeignKey` objects, without - the need to explicitly set the :paramref:`.ForeignKeyConstraint.use_alter` + :class:`_schema.ForeignKeyConstraint` and :class:`_schema.ForeignKey` objects, without + the need to explicitly set the :paramref:`_schema.ForeignKeyConstraint.use_alter` flag. -.. versionchanged:: 1.0.0 - The :paramref:`.ForeignKeyConstraint.use_alter` +.. versionchanged:: 1.0.0 - The :paramref:`_schema.ForeignKeyConstraint.use_alter` flag can be used with an un-named constraint; only the DROP operation will emit a specific error when actually called upon. @@ -370,9 +370,9 @@ MySQL. PRIMARY KEY Constraint ---------------------- -The primary key constraint of any :class:`.Table` object is implicitly -present, based on the :class:`.Column` objects that are marked with the -:paramref:`.Column.primary_key` flag. The :class:`.PrimaryKeyConstraint` +The primary key constraint of any :class:`_schema.Table` object is implicitly +present, based on the :class:`_schema.Column` objects that are marked with the +:paramref:`_schema.Column.primary_key` flag. The :class:`.PrimaryKeyConstraint` object provides explicit access to this constraint, which includes the option of being configured directly:: @@ -392,13 +392,13 @@ option of being configured directly:: Setting up Constraints when using the Declarative ORM Extension --------------------------------------------------------------- -The :class:`.Table` is the SQLAlchemy Core construct that allows one to define +The :class:`_schema.Table` is the SQLAlchemy Core construct that allows one to define table metadata, which among other things can be used by the SQLAlchemy ORM as a target to map a class. The :ref:`Declarative ` -extension allows the :class:`.Table` object to be created automatically, given -the contents of the table primarily as a mapping of :class:`.Column` objects. +extension allows the :class:`_schema.Table` object to be created automatically, given +the contents of the table primarily as a mapping of :class:`_schema.Column` objects. -To apply table-level constraint objects such as :class:`.ForeignKeyConstraint` +To apply table-level constraint objects such as :class:`_schema.ForeignKeyConstraint` to a table defined using Declarative, use the ``__table_args__`` attribute, described at :ref:`declarative_table_args`. @@ -420,7 +420,7 @@ specify the name of an existing constraint that is to be dropped or modified. Constraints can be named explicitly using the :paramref:`.Constraint.name` parameter, and for indexes the :paramref:`.Index.name` parameter. However, in the case of constraints this parameter is optional. There are also the use -cases of using the :paramref:`.Column.unique` and :paramref:`.Column.index` +cases of using the :paramref:`_schema.Column.unique` and :paramref:`_schema.Column.index` parameters which create :class:`.UniqueConstraint` and :class:`.Index` objects without an explicit name being specified. @@ -437,19 +437,19 @@ and :class:`.Index` objects, automated naming schemes can be constructed using events. This approach has the advantage that constraints will get a consistent naming scheme without the need for explicit name parameters throughout the code, and also that the convention takes place just as well -for those constraints and indexes produced by the :paramref:`.Column.unique` -and :paramref:`.Column.index` parameters. As of SQLAlchemy 0.9.2 this +for those constraints and indexes produced by the :paramref:`_schema.Column.unique` +and :paramref:`_schema.Column.index` parameters. As of SQLAlchemy 0.9.2 this event-based approach is included, and can be configured using the argument -:paramref:`.MetaData.naming_convention`. +:paramref:`_schema.MetaData.naming_convention`. -:paramref:`.MetaData.naming_convention` refers to a dictionary which accepts +:paramref:`_schema.MetaData.naming_convention` refers to a dictionary which accepts the :class:`.Index` class or individual :class:`.Constraint` classes as keys, and Python string templates as values. It also accepts a series of string-codes as alternative keys, ``"fk"``, ``"pk"``, ``"ix"``, ``"ck"``, ``"uq"`` for foreign key, primary key, index, check, and unique constraint, respectively. The string templates in this dictionary are used whenever a constraint or index is associated with this -:class:`.MetaData` object that does not have an existing name given (including +:class:`_schema.MetaData` object that does not have an existing name given (including one exception case where an existing name can be further embellished). An example naming convention that suits basic cases is as follows:: @@ -465,7 +465,7 @@ An example naming convention that suits basic cases is as follows:: metadata = MetaData(naming_convention=convention) The above convention will establish names for all constraints within -the target :class:`.MetaData` collection. +the target :class:`_schema.MetaData` collection. For example, we can observe the name produced when we create an unnamed :class:`.UniqueConstraint`:: @@ -477,7 +477,7 @@ For example, we can observe the name produced when we create an unnamed >>> list(user_table.constraints)[1].name 'uq_user_name' -This same feature takes effect even if we just use the :paramref:`.Column.unique` +This same feature takes effect even if we just use the :paramref:`_schema.Column.unique` flag:: >>> user_table = Table('user', metadata, @@ -498,9 +498,9 @@ will be explicit when a new migration script is generated:: The above ``"uq_user_name"`` string was copied from the :class:`.UniqueConstraint` object that ``--autogenerate`` located in our metadata. -The default value for :paramref:`.MetaData.naming_convention` handles +The default value for :paramref:`_schema.MetaData.naming_convention` handles the long-standing SQLAlchemy behavior of assigning a name to a :class:`.Index` -object that is created using the :paramref:`.Column.index` parameter:: +object that is created using the :paramref:`_schema.Column.index` parameter:: >>> from sqlalchemy.sql.schema import DEFAULT_NAMING_CONVENTION >>> DEFAULT_NAMING_CONVENTION @@ -512,7 +512,7 @@ The tokens available include ``%(table_name)s``, ``%(referred_table_name)s``, multiple-column versions of each including ``%(column_0N_name)s``, ``%(column_0_N_name)s``, ``%(referred_column_0_N_name)s`` which render all column names separated with or without an underscore. The documentation for -:paramref:`.MetaData.naming_convention` has further detail on each of these +:paramref:`_schema.MetaData.naming_convention` has further detail on each of these conventions. When a generated name, particularly those that use the multiple-column tokens, @@ -573,7 +573,7 @@ that as follows:: "fk": "fk_%(fk_guid)s", } -Above, when we create a new :class:`.ForeignKeyConstraint`, we will get a +Above, when we create a new :class:`_schema.ForeignKeyConstraint`, we will get a name as follows:: >>> metadata = MetaData(naming_convention=convention) @@ -596,7 +596,7 @@ name as follows:: .. seealso:: - :paramref:`.MetaData.naming_convention` - for additional usage details + :paramref:`_schema.MetaData.naming_convention` - for additional usage details as well as a listing of all available naming components. `The Importance of Naming Constraints `_ - in the Alembic documentation. @@ -635,8 +635,8 @@ The above table will produce the name ``ck_foo_value_gt_5``:: ) :class:`.CheckConstraint` also supports the ``%(columns_0_name)s`` -token; we can make use of this by ensuring we use a :class:`.Column` or -:func:`.sql.expression.column` element within the constraint's expression, +token; we can make use of this by ensuring we use a :class:`_schema.Column` or +:func:`_expression.column` element within the constraint's expression, either by declaring the constraint separate from the table:: metadata = MetaData( @@ -649,7 +649,7 @@ either by declaring the constraint separate from the table:: CheckConstraint(foo.c.value > 5) -or by using a :func:`.sql.expression.column` inline:: +or by using a :func:`_expression.column` inline:: from sqlalchemy import column @@ -833,9 +833,9 @@ INDEX" is issued right after the create statements for the table: CREATE INDEX idx_col34 ON mytable (col3, col4){stop} Note in the example above, the :class:`.Index` construct is created -externally to the table which it corresponds, using :class:`.Column` +externally to the table which it corresponds, using :class:`_schema.Column` objects directly. :class:`.Index` also supports -"inline" definition inside the :class:`.Table`, using string names to +"inline" definition inside the :class:`_schema.Table`, using string names to identify columns:: meta = MetaData() @@ -869,7 +869,7 @@ Functional Indexes :class:`.Index` supports SQL and function expressions, as supported by the target backend. To create an index against a column using a descending -value, the :meth:`.ColumnElement.desc` modifier may be used:: +value, the :meth:`_expression.ColumnElement.desc` modifier may be used:: from sqlalchemy import Index diff --git a/doc/build/core/custom_types.rst b/doc/build/core/custom_types.rst index 22c9e702ad..740d1593f3 100644 --- a/doc/build/core/custom_types.rst +++ b/doc/build/core/custom_types.rst @@ -28,7 +28,7 @@ can be associated with any type:: def compile_binary_sqlite(type_, compiler, **kw): return "BLOB" -The above code allows the usage of :class:`.types.BINARY`, which +The above code allows the usage of :class:`_types.BINARY`, which will produce the string ``BINARY`` against all backends except SQLite, in which case it will produce ``BLOB``. @@ -349,7 +349,7 @@ data into particular formats. Any :class:`.TypeEngine`, :class:`.UserDefinedType` or :class:`.TypeDecorator` subclass can include implementations of :meth:`.TypeEngine.bind_expression` and/or :meth:`.TypeEngine.column_expression`, which -when defined to return a non-``None`` value should return a :class:`.ColumnElement` +when defined to return a non-``None`` value should return a :class:`_expression.ColumnElement` expression to be injected into the SQL statement, either surrounding bound parameters or a column expression. For example, to build a ``Geometry`` type which will apply the PostGIS function ``ST_GeomFromText`` to all outgoing @@ -370,8 +370,8 @@ in conjunction with :data:`~.sqlalchemy.sql.expression.func`:: def column_expression(self, col): return func.ST_AsText(col, type_=self) -We can apply the ``Geometry`` type into :class:`.Table` metadata -and use it in a :func:`~.sql.expression.select` construct:: +We can apply the ``Geometry`` type into :class:`_schema.Table` metadata +and use it in a :func:`_expression.select` construct:: geometry = Table('geometry', metadata, Column('geom_id', Integer, primary_key=True), @@ -393,7 +393,7 @@ is run on the bound parameter so that the passed-in value is converted:: The :meth:`.TypeEngine.column_expression` method interacts with the mechanics of the compiler such that the SQL expression does not interfere with the labeling of the wrapped expression. Such as, if we rendered -a :func:`~.sql.expression.select` against a :func:`.label` of our expression, the string +a :func:`_expression.select` against a :func:`.label` of our expression, the string label is moved to the outside of the wrapped expression:: print(select([geometry.c.geom_data.label('my_data')])) @@ -404,7 +404,7 @@ Output:: FROM geometry Another example is we decorate -:class:`.postgresql.BYTEA` to provide a ``PGPString``, which will make use of the +:class:`_postgresql.BYTEA` to provide a ``PGPString``, which will make use of the PostgreSQL ``pgcrypto`` extension to encrypt/decrypt values transparently:: @@ -528,7 +528,7 @@ set to ``True``:: New methods added to a :class:`.TypeEngine.Comparator` are exposed on an owning SQL expression using a ``__getattr__`` scheme, which exposes methods added to -:class:`.TypeEngine.Comparator` onto the owning :class:`.ColumnElement`. +:class:`.TypeEngine.Comparator` onto the owning :class:`_expression.ColumnElement`. For example, to add a ``log()`` function to integers:: @@ -603,12 +603,12 @@ column, we might receive back the string ``"VARCHAR"``. SQLAlchemy's PostgreSQL dialect has a hardcoded mapping which links the string name ``"VARCHAR"`` to the SQLAlchemy :class:`.VARCHAR` class, and that's how when we emit a statement like ``Table('my_table', m, autoload_with=engine)``, the -:class:`.Column` object within it would have an instance of :class:`.VARCHAR` +:class:`_schema.Column` object within it would have an instance of :class:`.VARCHAR` present inside of it. -The implication of this is that if a :class:`.Table` object makes use of type +The implication of this is that if a :class:`_schema.Table` object makes use of type objects that don't correspond directly to the database-native type name, if we -create a new :class:`.Table` object against a new :class:`.MetaData` collection +create a new :class:`_schema.Table` object against a new :class:`_schema.MetaData` collection for this database table elsewhere using reflection, it will not have this datatype. For example:: @@ -635,7 +635,7 @@ object that was created by us directly, it is :class:`.PickleType`:: >>> my_table.c.data.type PickleType() -However, if we create another instance of :class:`.Table` using reflection, +However, if we create another instance of :class:`_schema.Table` using reflection, the use of :class:`.PickleType` is not represented in the SQLite database we've created; we instead get back :class:`.BLOB`:: @@ -650,19 +650,19 @@ created; we instead get back :class:`.BLOB`:: >>> my_reflected_table.c.data.type BLOB() -Typically, when an application defines explicit :class:`.Table` metadata with +Typically, when an application defines explicit :class:`_schema.Table` metadata with custom types, there is no need to use table reflection because the necessary -:class:`.Table` metadata is already present. However, for the case where an +:class:`_schema.Table` metadata is already present. However, for the case where an application, or a combination of them, need to make use of both explicit -:class:`.Table` metadata which includes custom, Python-level datatypes, as well -as :class:`.Table` objects which set up their :class:`.Column` objects as +:class:`_schema.Table` metadata which includes custom, Python-level datatypes, as well +as :class:`_schema.Table` objects which set up their :class:`_schema.Column` objects as reflected from the database, which nevertheless still need to exhibit the additional Python behaviors of the custom datatypes, additional steps must be taken to allow this. The most straightforward is to override specific columns as described at :ref:`reflection_overriding_columns`. In this technique, we simply -use reflection in combination with explicit :class:`.Column` objects for those +use reflection in combination with explicit :class:`_schema.Column` objects for those columns for which we want to use a custom or decorated datatype:: >>> metadata_three = MetaData() @@ -670,9 +670,9 @@ columns for which we want to use a custom or decorated datatype:: The ``my_reflected_table`` object above is reflected, and will load the definition of the "id" column from the SQLite database. But for the "data" -column, we've overridden the reflected object with an explicit :class:`.Column` +column, we've overridden the reflected object with an explicit :class:`_schema.Column` definition that includes our desired in-Python datatype, the -:class:`.PickleType`. The reflection process will leave this :class:`.Column` +:class:`.PickleType`. The reflection process will leave this :class:`_schema.Column` object intact:: >>> my_reflected_table.c.data.type @@ -696,8 +696,8 @@ for example we knew that we wanted all :class:`.BLOB` datatypes to in fact be When the above code is invoked *before* any table reflection occurs (note also it should be invoked **only once** in the application, as it is a global rule), -upon reflecting any :class:`.Table` that includes a column with a :class:`.BLOB` -datatype, the resulting datatype will be stored in the :class:`.Column` object +upon reflecting any :class:`_schema.Table` that includes a column with a :class:`.BLOB` +datatype, the resulting datatype will be stored in the :class:`_schema.Column` object as :class:`.PickleType`. In practice, the above event-based approach would likely have additional rules diff --git a/doc/build/core/ddl.rst b/doc/build/core/ddl.rst index 46a4e1d841..f38dcf849c 100644 --- a/doc/build/core/ddl.rst +++ b/doc/build/core/ddl.rst @@ -47,7 +47,7 @@ details. Controlling DDL Sequences ------------------------- -The :class:`~.schema.DDL` construct introduced previously also has the +The :class:`_schema.DDL` construct introduced previously also has the ability to be invoked conditionally based on inspection of the database. This feature is available using the :meth:`.DDLElement.execute_if` method. For example, if we wanted to create a trigger but only on @@ -167,8 +167,8 @@ The event-driven DDL system described in the previous section :ref:`schema_ddl_sequences` is available with other :class:`.DDLElement` objects as well. However, when dealing with the built-in constructs such as :class:`.CreateIndex`, :class:`.CreateSequence`, etc, the event -system is of **limited** use, as methods like :meth:`.Table.create` and -:meth:`.MetaData.create_all` will invoke these constructs unconditionally. +system is of **limited** use, as methods like :meth:`_schema.Table.create` and +:meth:`_schema.MetaData.create_all` will invoke these constructs unconditionally. In a future SQLAlchemy release, the DDL event system including conditional execution will taken into account for built-in constructs that currently invoke in all cases. @@ -220,7 +220,7 @@ While the above example is against the built-in :class:`.AddConstraint` and :class:`.DropConstraint` objects, the main usefulness of DDL events for now remains focused on the use of the :class:`.DDL` construct itself, as well as with user-defined subclasses of :class:`.DDLElement` that aren't -already part of the :meth:`.MetaData.create_all`, :meth:`.Table.create`, +already part of the :meth:`_schema.MetaData.create_all`, :meth:`_schema.Table.create`, and corresponding "drop" processes. .. _schema_api_ddl: diff --git a/doc/build/core/defaults.rst b/doc/build/core/defaults.rst index 73520bdfd1..fa9bf5867b 100644 --- a/doc/build/core/defaults.rst +++ b/doc/build/core/defaults.rst @@ -78,7 +78,7 @@ defaults):: Python-Executed Functions ------------------------- -The :paramref:`.Column.default` and :paramref:`.Column.onupdate` keyword arguments also accept Python +The :paramref:`_schema.Column.default` and :paramref:`_schema.Column.onupdate` keyword arguments also accept Python functions. These functions are invoked at the time of insert or update if no other value for that column is supplied, and the value returned is used for the column's value. Below illustrates a crude "sequence" that assigns an @@ -100,12 +100,12 @@ built-in capabilities of the database should normally be used, which may include sequence objects or other autoincrementing capabilities. For primary key columns, SQLAlchemy will in most cases use these capabilities automatically. See the API documentation for -:class:`~sqlalchemy.schema.Column` including the :paramref:`.Column.autoincrement` flag, as +:class:`~sqlalchemy.schema.Column` including the :paramref:`_schema.Column.autoincrement` flag, as well as the section on :class:`~sqlalchemy.schema.Sequence` later in this chapter for background on standard primary key generation techniques. To illustrate onupdate, we assign the Python ``datetime`` function ``now`` to -the :paramref:`.Column.onupdate` attribute:: +the :paramref:`_schema.Column.onupdate` attribute:: import datetime @@ -128,8 +128,8 @@ executes. Context-Sensitive Default Functions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The Python functions used by :paramref:`.Column.default` and -:paramref:`.Column.onupdate` may also make use of the current statement's +The Python functions used by :paramref:`_schema.Column.default` and +:paramref:`_schema.Column.onupdate` may also make use of the current statement's context in order to determine a value. The `context` of a statement is an internal SQLAlchemy object which contains all information about the statement being executed, including its source expression, the parameters associated with @@ -152,10 +152,10 @@ otherwise not provided, and the value will be that of whatever value is present in the execution for the ``counter`` column, plus the number 12. For a single statement that is being executed using "executemany" style, e.g. -with multiple parameter sets passed to :meth:`.Connection.execute`, the user- +with multiple parameter sets passed to :meth:`_engine.Connection.execute`, the user- defined function is called once for each set of parameters. For the use case of -a multi-valued :class:`~.sql.expression.Insert` construct (e.g. with more than one VALUES -clause set up via the :meth:`.Insert.values` method), the user-defined function +a multi-valued :class:`_expression.Insert` construct (e.g. with more than one VALUES +clause set up via the :meth:`_expression.Insert.values` method), the user-defined function is also called once for each set of parameters. When the function is invoked, the special method @@ -178,7 +178,7 @@ and returned alone. Client-Invoked SQL Expressions ------------------------------ -The :paramref:`.Column.default` and :paramref:`.Column.onupdate` keywords may +The :paramref:`_schema.Column.default` and :paramref:`_schema.Column.onupdate` keywords may also be passed SQL expressions, which are in most cases rendered inline within the INSERT or UPDATE statement:: @@ -213,21 +213,21 @@ emitted for this table. ``func.now()`` returns the SQL expression object that will render the "NOW" function into the SQL being emitted. -Default and update SQL expressions specified by :paramref:`.Column.default` and -:paramref:`.Column.onupdate` are invoked explicitly by SQLAlchemy when an +Default and update SQL expressions specified by :paramref:`_schema.Column.default` and +:paramref:`_schema.Column.onupdate` are invoked explicitly by SQLAlchemy when an INSERT or UPDATE statement occurs, typically rendered inline within the DML statement except in certain cases listed below. This is different than a "server side" default, which is part of the table's DDL definition, e.g. as part of the "CREATE TABLE" statement, which are likely more common. For server side defaults, see the next section :ref:`server_defaults`. -When a SQL expression indicated by :paramref:`.Column.default` is used with +When a SQL expression indicated by :paramref:`_schema.Column.default` is used with primary key columns, there are some cases where SQLAlchemy must "pre-execute" the default generation SQL function, meaning it is invoked in a separate SELECT statement, and the resulting value is passed as a parameter to the INSERT. This only occurs for primary key columns for an INSERT statement that is being asked to return this primary key value, where RETURNING or ``cursor.lastrowid`` -may not be used. An :class:`~.sql.expression.Insert` construct that specifies the +may not be used. An :class:`_expression.Insert` construct that specifies the :paramref:`~.expression.insert.inline` flag will always render default expressions inline. @@ -250,8 +250,8 @@ column primary keys are represented in the same format). Server-invoked DDL-Explicit Default Expressions ----------------------------------------------- -A variant on the SQL expression default is the :paramref:`.Column.server_default`, which gets -placed in the CREATE TABLE statement during a :meth:`.Table.create` operation: +A variant on the SQL expression default is the :paramref:`_schema.Column.server_default`, which gets +placed in the CREATE TABLE statement during a :meth:`_schema.Table.create` operation: .. sourcecode:: python+sql @@ -269,14 +269,14 @@ A create call for the above table will produce:: index_value integer default 0 ) -The above example illustrates the two typical use cases for :paramref:`.Column.server_default`, +The above example illustrates the two typical use cases for :paramref:`_schema.Column.server_default`, that of the SQL function (SYSDATE in the above example) as well as a server-side constant value (the integer "0" in the above example). It is advisable to use the -:func:`.text` construct for any literal SQL values as opposed to passing the +:func:`_expression.text` construct for any literal SQL values as opposed to passing the raw value, as SQLAlchemy does not typically perform any quoting or escaping on these values. -Like client-generated expressions, :paramref:`.Column.server_default` can accommodate +Like client-generated expressions, :paramref:`_schema.Column.server_default` can accommodate SQL expressions in general, however it is expected that these will usually be simple functions and expressions, and not the more complex cases like an embedded SELECT. @@ -305,8 +305,8 @@ and for supporting databases may be used to indicate that the column should be part of a RETURNING or OUTPUT clause for the statement. Tools such as the SQLAlchemy ORM then make use of this marker in order to know how to get at the value of the column after such an operation. In particular, the -:meth:`.ValuesBase.return_defaults` method can be used with an :class:`~.sql.expression.Insert` -or :class:`.Update` construct to indicate that these values should be +:meth:`.ValuesBase.return_defaults` method can be used with an :class:`_expression.Insert` +or :class:`_expression.Update` construct to indicate that these values should be returned. For details on using :class:`.FetchedValue` with the ORM, see @@ -354,14 +354,14 @@ value can be returned to the Python code:: RETURNING cart_id When the :class:`~sqlalchemy.schema.Sequence` is associated with a -:class:`.Column` as its **Python-side** default generator, the +:class:`_schema.Column` as its **Python-side** default generator, the :class:`.Sequence` will also be subject to "CREATE SEQUENCE" and "DROP -SEQUENCE" DDL when similar DDL is emitted for the owning :class:`.Table`. +SEQUENCE" DDL when similar DDL is emitted for the owning :class:`_schema.Table`. This is a limited scope convenience feature that does not accommodate for -inheritance of other aspects of the :class:`.MetaData`, such as the default +inheritance of other aspects of the :class:`_schema.MetaData`, such as the default schema. Therefore, it is best practice that for a :class:`.Sequence` which -is local to a certain :class:`.Column` / :class:`.Table`, that it be -explicitly associated with the :class:`.MetaData` using the +is local to a certain :class:`_schema.Column` / :class:`_schema.Table`, that it be +explicitly associated with the :class:`_schema.MetaData` using the :paramref:`.Sequence.metadata` parameter. See the section :ref:`sequence_metadata` for more background on this. @@ -370,7 +370,7 @@ Associating a Sequence on a SERIAL column PostgreSQL's SERIAL datatype is an auto-incrementing type that implies the implicit creation of a PostgreSQL sequence when CREATE TABLE is emitted. -If a :class:`.Column` specifies an explicit :class:`.Sequence` object +If a :class:`_schema.Column` specifies an explicit :class:`.Sequence` object which also specifies a true value for the :paramref:`.Sequence.optional` boolean flag, the :class:`.Sequence` will not take effect under PostgreSQL, and the SERIAL datatype will proceed normally. Instead, the :class:`.Sequence` @@ -416,7 +416,7 @@ example of associating a :class:`.Sequence` with a table as follows:: While the above is a prominent idiomatic pattern, it is recommended that the :class:`.Sequence` in most cases be explicitly associated with the -:class:`.MetaData`, using the :paramref:`.Sequence.metadata` parameter:: +:class:`_schema.MetaData`, using the :paramref:`.Sequence.metadata` parameter:: table = Table("cartitems", meta, Column( @@ -430,32 +430,32 @@ the :class:`.Sequence` in most cases be explicitly associated with the The :class:`.Sequence` object is a first class schema construct that can exist independently of any table in a database, and can also be shared among tables. Therefore SQLAlchemy does not implicitly -modify the :class:`.Sequence` when it is associated with a :class:`.Column` +modify the :class:`.Sequence` when it is associated with a :class:`_schema.Column` object as either the Python-side or server-side default generator. While the CREATE SEQUENCE / DROP SEQUENCE DDL is emitted for a :class:`.Sequence` defined as a Python side generator at the same time the table itself is subject to CREATE or DROP, this is a convenience feature that does not imply that the -:class:`.Sequence` is fully associated with the :class:`.MetaData` object. +:class:`.Sequence` is fully associated with the :class:`_schema.MetaData` object. -Explicitly associating the :class:`.Sequence` with :class:`.MetaData` +Explicitly associating the :class:`.Sequence` with :class:`_schema.MetaData` allows for the following behaviors: -* The :class:`.Sequence` will inherit the :paramref:`.MetaData.schema` - parameter specified to the target :class:`.MetaData`, which +* The :class:`.Sequence` will inherit the :paramref:`_schema.MetaData.schema` + parameter specified to the target :class:`_schema.MetaData`, which affects the production of CREATE / DROP DDL, if any. * The :meth:`.Sequence.create` and :meth:`.Sequence.drop` methods - automatically use the engine bound to the :class:`.MetaData` + automatically use the engine bound to the :class:`_schema.MetaData` object, if any. -* The :meth:`.MetaData.create_all` and :meth:`.MetaData.drop_all` +* The :meth:`_schema.MetaData.create_all` and :meth:`_schema.MetaData.drop_all` methods will emit CREATE / DROP for this :class:`.Sequence`, even if the :class:`.Sequence` is not associated with any - :class:`.Table` / :class:`.Column` that's a member of this - :class:`.MetaData`. + :class:`_schema.Table` / :class:`_schema.Column` that's a member of this + :class:`_schema.MetaData`. Since the vast majority of cases that deal with :class:`.Sequence` expect -that :class:`.Sequence` to be fully "owned" by the associated :class:`.Table` +that :class:`.Sequence` to be fully "owned" by the associated :class:`_schema.Table` and that options like default schema are propagated, setting the :paramref:`.Sequence.metadata` parameter should be considered a best practice. @@ -466,24 +466,24 @@ Associating a Sequence as the Server Side Default database. It does not work with Oracle. The preceding sections illustrate how to associate a :class:`.Sequence` with a -:class:`.Column` as the **Python side default generator**:: +:class:`_schema.Column` as the **Python side default generator**:: Column( "cart_id", Integer, Sequence('cart_id_seq', metadata=meta), primary_key=True) In the above case, the :class:`.Sequence` will automatically be subject -to CREATE SEQUENCE / DROP SEQUENCE DDL when the related :class:`.Table` +to CREATE SEQUENCE / DROP SEQUENCE DDL when the related :class:`_schema.Table` is subject to CREATE / DROP. However, the sequence will **not** be present as the server-side default for the column when CREATE TABLE is emitted. If we want the sequence to be used as a server-side default, meaning it takes place even if we emit INSERT commands to the table from -the SQL command line, we can use the :paramref:`.Column.server_default` +the SQL command line, we can use the :paramref:`_schema.Column.server_default` parameter in conjunction with the value-generation function of the sequence, available from the :meth:`.Sequence.next_value` method. Below we illustrate the same :class:`.Sequence` being associated with the -:class:`.Column` both as the Python-side default generator as well as +:class:`_schema.Column` both as the Python-side default generator as well as the server-side default generator:: cart_id_seq = Sequence('cart_id_seq', metadata=meta) @@ -527,8 +527,8 @@ of the INSERT statement itself, which only works if the sequence is included as the Python-side default generator function. The example also associates the :class:`.Sequence` with the enclosing -:class:`.MetaData` directly, which again ensures that the :class:`.Sequence` -is fully associated with the parameters of the :class:`.MetaData` collection +:class:`_schema.MetaData` directly, which again ensures that the :class:`.Sequence` +is fully associated with the parameters of the :class:`_schema.MetaData` collection including the default schema, if any. .. seealso:: @@ -544,10 +544,10 @@ Computed (GENERATED ALWAYS AS) Columns .. versionadded:: 1.3.11 -The :class:`.Computed` construct allows a :class:`.Column` to be declared in +The :class:`.Computed` construct allows a :class:`_schema.Column` to be declared in DDL as a "GENERATED ALWAYS AS" column, that is, one which has a value that is computed by the database server. The construct accepts a SQL expression -typically declared textually using a string or the :func:`.text` construct, in +typically declared textually using a string or the :func:`_expression.text` construct, in a similar manner as that of :class:`.CheckConstraint`. The SQL expression is then interpreted by the database server in order to determine the value for the column within a row. @@ -589,14 +589,14 @@ backend; leaving it unset will use a working default for the target backend. The :class:`.Computed` construct is a subclass of the :class:`.FetchedValue` object, and will set itself up as both the "server default" and "server -onupdate" generator for the target :class:`.Column`, meaning it will be treated +onupdate" generator for the target :class:`_schema.Column`, meaning it will be treated as a default generating column when INSERT and UPDATE statements are generated, as well as that it will be fetched as a generating column when using the ORM. This includes that it will be part of the RETURNING clause of the database for databases which support RETURNING and the generated values are to be eagerly fetched. -.. note:: A :class:`.Column` that is defined with the :class:`.Computed` +.. note:: A :class:`_schema.Column` that is defined with the :class:`.Computed` construct may not store any value outside of that which the server applies to it; SQLAlchemy's behavior when a value is passed for such a column to be written in INSERT or UPDATE is currently that the value will be diff --git a/doc/build/core/dml.rst b/doc/build/core/dml.rst index d116b67a5c..7da8fb66cb 100644 --- a/doc/build/core/dml.rst +++ b/doc/build/core/dml.rst @@ -2,7 +2,7 @@ Insert, Updates, Deletes ======================== INSERT, UPDATE and DELETE statements build on a hierarchy starting -with :class:`.UpdateBase`. The :class:`~.sql.expression.Insert` and :class:`.Update` +with :class:`.UpdateBase`. The :class:`_expression.Insert` and :class:`_expression.Update` constructs build on the intermediary :class:`.ValuesBase`. .. currentmodule:: sqlalchemy.sql.expression diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst index 643a06a985..f2e0beff6d 100644 --- a/doc/build/core/engines.rst +++ b/doc/build/core/engines.rst @@ -4,7 +4,7 @@ Engine Configuration ==================== -The :class:`.Engine` is the starting point for any SQLAlchemy application. It's +The :class:`_engine.Engine` is the starting point for any SQLAlchemy application. It's "home base" for the actual database and its :term:`DBAPI`, delivered to the SQLAlchemy application through a connection pool and a :class:`.Dialect`, which describes how to talk to a specific kind of database/DBAPI combination. @@ -13,8 +13,8 @@ The general structure can be illustrated as follows: .. image:: sqla_engine_arch.png -Where above, an :class:`.Engine` references both a -:class:`.Dialect` and a :class:`.Pool`, +Where above, an :class:`_engine.Engine` references both a +:class:`.Dialect` and a :class:`_pool.Pool`, which together interpret the DBAPI's module functions as well as the behavior of the database. @@ -25,18 +25,18 @@ Creating an engine is just a matter of issuing a single call, engine = create_engine('postgresql://scott:tiger@localhost:5432/mydatabase') The above engine creates a :class:`.Dialect` object tailored towards -PostgreSQL, as well as a :class:`.Pool` object which will establish a DBAPI +PostgreSQL, as well as a :class:`_pool.Pool` object which will establish a DBAPI connection at ``localhost:5432`` when a connection request is first received. -Note that the :class:`.Engine` and its underlying :class:`.Pool` do **not** -establish the first actual DBAPI connection until the :meth:`.Engine.connect` +Note that the :class:`_engine.Engine` and its underlying :class:`_pool.Pool` do **not** +establish the first actual DBAPI connection until the :meth:`_engine.Engine.connect` method is called, or an operation which is dependent on this method such as -:meth:`.Engine.execute` is invoked. In this way, :class:`.Engine` and -:class:`.Pool` can be said to have a *lazy initialization* behavior. +:meth:`_engine.Engine.execute` is invoked. In this way, :class:`_engine.Engine` and +:class:`_pool.Pool` can be said to have a *lazy initialization* behavior. -The :class:`.Engine`, once created, can either be used directly to interact with the database, +The :class:`_engine.Engine`, once created, can either be used directly to interact with the database, or can be passed to a :class:`.Session` object to work with the ORM. This section -covers the details of configuring an :class:`.Engine`. The next section, :ref:`connections_toplevel`, -will detail the usage API of the :class:`.Engine` and similar, typically for non-ORM +covers the details of configuring an :class:`_engine.Engine`. The next section, :ref:`connections_toplevel`, +will detail the usage API of the :class:`_engine.Engine` and similar, typically for non-ORM applications. .. _supported_dbapis: @@ -55,7 +55,7 @@ See the section :ref:`dialect_toplevel` for information on the various backends Database Urls ============= -The :func:`.create_engine` function produces an :class:`.Engine` object based +The :func:`.create_engine` function produces an :class:`_engine.Engine` object based on a URL. These URLs follow `RFC-1738 `_, and usually can include username, password, hostname, database name as well as optional keyword arguments for additional configuration. @@ -203,15 +203,15 @@ Engine Creation API Pooling ======= -The :class:`.Engine` will ask the connection pool for a +The :class:`_engine.Engine` will ask the connection pool for a connection when the ``connect()`` or ``execute()`` methods are called. The default connection pool, :class:`~.QueuePool`, will open connections to the database on an as-needed basis. As concurrent statements are executed, :class:`.QueuePool` will grow its pool of connections to a default size of five, and will allow a default "overflow" of ten. Since the -:class:`.Engine` is essentially "home base" for the +:class:`_engine.Engine` is essentially "home base" for the connection pool, it follows that you should keep a single -:class:`.Engine` per database established within an +:class:`_engine.Engine` per database established within an application, rather than creating a new one for each connection. .. note:: @@ -329,13 +329,13 @@ string. To set this to a specific name, use the "logging_name" and .. note:: - The SQLAlchemy :class:`.Engine` conserves Python function call overhead + The SQLAlchemy :class:`_engine.Engine` conserves Python function call overhead by only emitting log statements when the current logging level is detected as ``logging.INFO`` or ``logging.DEBUG``. It only checks this level when a new connection is procured from the connection pool. Therefore when changing the logging configuration for an already-running application, any - :class:`.Connection` that's currently active, or more commonly a + :class:`_engine.Connection` that's currently active, or more commonly a :class:`~.orm.session.Session` object that's active in a transaction, won't log any - SQL according to the new configuration until a new :class:`.Connection` + SQL according to the new configuration until a new :class:`_engine.Connection` is procured (in the case of :class:`~.orm.session.Session`, this is after the current transaction ends and a new one begins). diff --git a/doc/build/core/event.rst b/doc/build/core/event.rst index 6e53ae3b96..29f090a7b0 100644 --- a/doc/build/core/event.rst +++ b/doc/build/core/event.rst @@ -19,7 +19,7 @@ instructions regarding secondary event targets based on the given target. The name of an event and the argument signature of a corresponding listener function is derived from a class bound specification method, which exists bound to a marker class that's described in the documentation. -For example, the documentation for :meth:`.PoolEvents.connect` indicates that the event name is ``"connect"`` +For example, the documentation for :meth:`_events.PoolEvents.connect` indicates that the event name is ``"connect"`` and that a user-defined listener function should receive two positional arguments:: from sqlalchemy.event import listen @@ -43,7 +43,7 @@ Named Argument Styles --------------------- There are some varieties of argument styles which can be accepted by listener -functions. Taking the example of :meth:`.PoolEvents.connect`, this function +functions. Taking the example of :meth:`_events.PoolEvents.connect`, this function is documented as receiving ``dbapi_connection`` and ``connection_record`` arguments. We can opt to receive these arguments by name, by establishing a listener function that accepts ``**keyword`` arguments, by passing ``named=True`` to either @@ -84,7 +84,7 @@ The :func:`.listen` function is very flexible regarding targets. It generally accepts classes, instances of those classes, and related classes or objects from which the appropriate target can be derived. For example, the above mentioned ``"connect"`` event accepts -:class:`.Engine` classes and objects as well as :class:`.Pool` classes +:class:`_engine.Engine` classes and objects as well as :class:`_pool.Pool` classes and objects:: from sqlalchemy.event import listen diff --git a/doc/build/core/inspection.rst b/doc/build/core/inspection.rst index 01343102d9..eab1288422 100644 --- a/doc/build/core/inspection.rst +++ b/doc/build/core/inspection.rst @@ -14,11 +14,11 @@ Available Inspection Targets Below is a listing of many of the most common inspection targets. -* :class:`.Connectable` (i.e. :class:`.Engine`, - :class:`.Connection`) - returns an :class:`.Inspector` object. -* :class:`.ClauseElement` - all SQL expression components, including - :class:`.Table`, :class:`.Column`, serve as their own inspection objects, - meaning any of these objects passed to :func:`.inspect` return themselves. +* :class:`.Connectable` (i.e. :class:`_engine.Engine`, + :class:`_engine.Connection`) - returns an :class:`_reflection.Inspector` object. +* :class:`_expression.ClauseElement` - all SQL expression components, including + :class:`_schema.Table`, :class:`_schema.Column`, serve as their own inspection objects, + meaning any of these objects passed to :func:`_sa.inspect` return themselves. * ``object`` - an object given will be checked by the ORM for a mapping - if so, an :class:`.InstanceState` is returned representing the mapped state of the object. The :class:`.InstanceState` also provides access @@ -26,8 +26,8 @@ Below is a listing of many of the most common inspection targets. as the per-flush "history" of any attribute via the :class:`.History` object. * ``type`` (i.e. a class) - a class given will be checked by the ORM for a - mapping - if so, a :class:`.Mapper` for that class is returned. -* mapped attribute - passing a mapped attribute to :func:`.inspect`, such + mapping - if so, a :class:`_orm.Mapper` for that class is returned. +* mapped attribute - passing a mapped attribute to :func:`_sa.inspect`, such as ``inspect(MyClass.some_attribute)``, returns a :class:`.QueryableAttribute` object, which is the :term:`descriptor` associated with a mapped class. This descriptor refers to a :class:`.MapperProperty`, which is usually diff --git a/doc/build/core/metadata.rst b/doc/build/core/metadata.rst index c5865ae27d..22bad55372 100644 --- a/doc/build/core/metadata.rst +++ b/doc/build/core/metadata.rst @@ -10,8 +10,8 @@ Describing Databases with MetaData .. module:: sqlalchemy.schema -This section discusses the fundamental :class:`.Table`, :class:`.Column` -and :class:`.MetaData` objects. +This section discusses the fundamental :class:`_schema.Table`, :class:`_schema.Column` +and :class:`_schema.MetaData` objects. A collection of metadata entities is stored in an object aptly named :class:`~sqlalchemy.schema.MetaData`:: @@ -237,8 +237,8 @@ While SQLAlchemy directly supports emitting CREATE and DROP statements for schema constructs, the ability to alter those constructs, usually via the ALTER statement as well as other database-specific constructs, is outside of the scope of SQLAlchemy itself. While it's easy enough to emit ALTER statements -and similar by hand, such as by passing a :func:`.text` construct to -:meth:`.Connection.execute` or by using the :class:`.DDL` construct, it's a +and similar by hand, such as by passing a :func:`_expression.text` construct to +:meth:`_engine.Connection.execute` or by using the :class:`.DDL` construct, it's a common practice to automate the maintenance of database schemas in relation to application code using schema migration tools. @@ -303,15 +303,15 @@ Column, Table, MetaData API .. attribute:: sqlalchemy.schema.BLANK_SCHEMA - Symbol indicating that a :class:`.Table` or :class:`.Sequence` + Symbol indicating that a :class:`_schema.Table` or :class:`.Sequence` should have 'None' for its schema, even if the parent - :class:`.MetaData` has specified a schema. + :class:`_schema.MetaData` has specified a schema. .. seealso:: - :paramref:`.MetaData.schema` + :paramref:`_schema.MetaData.schema` - :paramref:`.Table.schema` + :paramref:`_schema.Table.schema` :paramref:`.Sequence.schema` diff --git a/doc/build/core/pooling.rst b/doc/build/core/pooling.rst index a4e01fcae4..572b18f26a 100644 --- a/doc/build/core/pooling.rst +++ b/doc/build/core/pooling.rst @@ -17,14 +17,14 @@ maintain a "pool" of active database connections in memory which are reused across requests. SQLAlchemy includes several connection pool implementations -which integrate with the :class:`.Engine`. They can also be used +which integrate with the :class:`_engine.Engine`. They can also be used directly for applications that want to add pooling to an otherwise plain DBAPI approach. Connection Pool Configuration ----------------------------- -The :class:`~.engine.Engine` returned by the +The :class:`_engine.Engine` returned by the :func:`~sqlalchemy.create_engine` function in most cases has a :class:`.QueuePool` integrated, pre-configured with reasonable pooling defaults. If you're reading this section only to learn how to enable pooling - congratulations! @@ -80,7 +80,7 @@ Disabling pooling using :class:`.NullPool`:: Using a Custom Connection Function ---------------------------------- -All :class:`.Pool` classes accept an argument ``creator`` which is +All :class:`_pool.Pool` classes accept an argument ``creator`` which is a callable that creates a new connection. :func:`.create_engine` accepts this function to pass onto the pool via an argument of the same name:: @@ -96,7 +96,7 @@ the same name:: engine = create_engine('postgresql+psycopg2://', creator=getconn) For most "initialize on connection" routines, it's more convenient -to use the :class:`.PoolEvents` event hooks, so that the usual URL argument to +to use the :class:`_events.PoolEvents` event hooks, so that the usual URL argument to :func:`.create_engine` is still usable. ``creator`` is there as a last resort for when a DBAPI has some form of ``connect`` that is not at all supported by SQLAlchemy. @@ -104,7 +104,7 @@ that is not at all supported by SQLAlchemy. Constructing a Pool ------------------- -To use a :class:`.Pool` by itself, the ``creator`` function is +To use a :class:`_pool.Pool` by itself, the ``creator`` function is the only argument that's required and is passed first, followed by any additional options:: @@ -117,7 +117,7 @@ by any additional options:: mypool = pool.QueuePool(getconn, max_overflow=10, pool_size=5) -DBAPI connections can then be procured from the pool using the :meth:`.Pool.connect` +DBAPI connections can then be procured from the pool using the :meth:`_pool.Pool.connect` function. The return value of this method is a DBAPI connection that's contained within a transparent proxy:: @@ -147,9 +147,9 @@ existing transaction on the connection is removed, not only ensuring that no existing state remains on next usage, but also so that table and row locks are released as well as that any isolated data snapshots are removed. This behavior can be disabled using the ``reset_on_return`` -option of :class:`.Pool`. +option of :class:`_pool.Pool`. -A particular pre-created :class:`.Pool` can be shared with one or more +A particular pre-created :class:`_pool.Pool` can be shared with one or more engines by passing it to the ``pool`` argument of :func:`.create_engine`:: e = create_engine('postgresql://', pool=mypool) @@ -159,7 +159,7 @@ Pool Events Connection pools support an event interface that allows hooks to execute upon first connect, upon each new connection, and upon checkout and -checkin of connections. See :class:`.PoolEvents` for details. +checkin of connections. See :class:`_events.PoolEvents` for details. .. _pool_disconnects: @@ -193,7 +193,7 @@ It is critical to note that the pre-ping approach **does not accommodate for connections dropped in the middle of transactions or other SQL operations**. If the database becomes unavailable while a transaction is in progress, the transaction will be lost and the database error will be raised. While -the :class:`.Connection` object will detect a "disconnect" situation and +the :class:`_engine.Connection` object will detect a "disconnect" situation and recycle the connection as well as invalidate the rest of the connection pool when this condition occurs, the individual operation where the exception was raised will be lost, and it's @@ -201,7 +201,7 @@ up to the application to either abandon the operation, or retry the whole transaction again. Pessimistic testing of connections upon checkout is achievable by -using the :paramref:`.Pool.pre_ping` argument, available from :func:`.create_engine` +using the :paramref:`_pool.Pool.pre_ping` argument, available from :func:`.create_engine` via the :paramref:`.create_engine.pool_pre_ping` argument:: engine = create_engine("mysql+pymysql://user:pw@host/db", pool_pre_ping=True) @@ -225,7 +225,7 @@ to three times before giving up, propagating the database error last received. Python latency. As such, this statement is **not logged in the SQL echo output**, and will not show up in SQLAlchemy's engine logging. -.. versionadded:: 1.2 Added "pre-ping" capability to the :class:`.Pool` +.. versionadded:: 1.2 Added "pre-ping" capability to the :class:`_pool.Pool` class. Custom / Legacy Pessimistic Ping @@ -281,9 +281,9 @@ behaviors are needed:: The above recipe has the advantage that we are making use of SQLAlchemy's facilities for detecting those DBAPI exceptions that are known to indicate -a "disconnect" situation, as well as the :class:`.Engine` object's ability +a "disconnect" situation, as well as the :class:`_engine.Engine` object's ability to correctly invalidate the current connection pool when this condition -occurs and allowing the current :class:`.Connection` to re-validate onto +occurs and allowing the current :class:`_engine.Connection` to re-validate onto a new DBAPI connection. @@ -296,13 +296,13 @@ a transaction, the other approach to dealing with stale / closed connections is to let SQLAlchemy handle disconnects as they occur, at which point all connections in the pool are invalidated, meaning they are assumed to be stale and will be refreshed upon next checkout. This behavior assumes the -:class:`.Pool` is used in conjunction with a :class:`.Engine`. -The :class:`.Engine` has logic which can detect +:class:`_pool.Pool` is used in conjunction with a :class:`_engine.Engine`. +The :class:`_engine.Engine` has logic which can detect disconnection events and refresh the pool automatically. -When the :class:`.Connection` attempts to use a DBAPI connection, and an +When the :class:`_engine.Connection` attempts to use a DBAPI connection, and an exception is raised that corresponds to a "disconnect" event, the connection -is invalidated. The :class:`.Connection` then calls the :meth:`.Pool.recreate` +is invalidated. The :class:`_engine.Connection` then calls the :meth:`_pool.Pool.recreate` method, effectively invalidating all connections not currently checked out so that they are replaced with new ones upon next checkout. This flow is illustrated by the code example below:: @@ -351,7 +351,7 @@ period of time:: Above, any DBAPI connection that has been open for more than one hour will be invalidated and replaced, upon next checkout. Note that the invalidation **only** occurs during checkout - not on any connections that are held in a checked out state. ``pool_recycle`` is a function -of the :class:`.Pool` itself, independent of whether or not an :class:`.Engine` is in use. +of the :class:`_pool.Pool` itself, independent of whether or not an :class:`_engine.Engine` is in use. .. _pool_connection_invalidation: @@ -359,7 +359,7 @@ of the :class:`.Pool` itself, independent of whether or not an :class:`.Engine` More on Invalidation ^^^^^^^^^^^^^^^^^^^^ -The :class:`.Pool` provides "connection invalidation" services which allow +The :class:`_pool.Pool` provides "connection invalidation" services which allow both explicit invalidation of a connection as well as automatic invalidation in response to conditions that are determined to render a connection unusable. @@ -368,7 +368,7 @@ pool and discarded. The ``.close()`` method is called on this connection if it is not clear that the connection itself might not be closed, however if this method fails, the exception is logged but the operation still proceeds. -When using a :class:`.Engine`, the :meth:`.Connection.invalidate` method is +When using a :class:`_engine.Engine`, the :meth:`_engine.Connection.invalidate` method is the usual entrypoint to explicit invalidation. Other conditions by which a DBAPI connection might be invalidated include: @@ -389,11 +389,11 @@ a DBAPI connection might be invalidated include: A final attempt at calling ``.close()`` on the connection will be made, and it is then discarded. -* When a listener implementing :meth:`.PoolEvents.checkout` raises the +* When a listener implementing :meth:`_events.PoolEvents.checkout` raises the :class:`~sqlalchemy.exc.DisconnectionError` exception, indicating that the connection won't be usable and a new connection attempt needs to be made. -All invalidations which occur will invoke the :meth:`.PoolEvents.invalidate` +All invalidations which occur will invoke the :meth:`_events.PoolEvents.invalidate` event. .. _pool_use_lifo: @@ -436,7 +436,7 @@ Using Connection Pools with Multiprocessing ------------------------------------------- It's critical that when using a connection pool, and by extension when -using an :class:`.Engine` created via :func:`.create_engine`, that +using an :class:`_engine.Engine` created via :func:`.create_engine`, that the pooled connections **are not shared to a forked process**. TCP connections are represented as file descriptors, which usually work across process boundaries, meaning this will cause concurrent access to the file descriptor @@ -444,8 +444,8 @@ on behalf of two or more entirely independent Python interpreter states. There are two approaches to dealing with this. -The first is, either create a new :class:`.Engine` within the child -process, or upon an existing :class:`.Engine`, call :meth:`.Engine.dispose` +The first is, either create a new :class:`_engine.Engine` within the child +process, or upon an existing :class:`_engine.Engine`, call :meth:`_engine.Engine.dispose` before the child process uses any connections. This will remove all existing connections from the pool so that it makes all new ones. Below is a simple version using ``multiprocessing.Process``, but this idea @@ -461,7 +461,7 @@ should be adapted to the style of forking in use:: p = Process(target=run_in_process) -The next approach is to instrument the :class:`.Pool` itself with events +The next approach is to instrument the :class:`_pool.Pool` itself with events so that connections are automatically invalidated in the subprocess. This is a little more magical but probably more foolproof:: diff --git a/doc/build/core/reflection.rst b/doc/build/core/reflection.rst index 1848c044e0..c320478a03 100644 --- a/doc/build/core/reflection.rst +++ b/doc/build/core/reflection.rst @@ -143,27 +143,27 @@ database is also available. This is known as the "Inspector":: Limitations of Reflection ------------------------- -It's important to note that the reflection process recreates :class:`.Table` +It's important to note that the reflection process recreates :class:`_schema.Table` metadata using only information which is represented in the relational database. This process by definition cannot restore aspects of a schema that aren't actually stored in the database. State which is not available from reflection includes but is not limited to: * Client side defaults, either Python functions or SQL expressions defined using - the ``default`` keyword of :class:`.Column` (note this is separate from ``server_default``, + the ``default`` keyword of :class:`_schema.Column` (note this is separate from ``server_default``, which specifically is what's available via reflection). * Column information, e.g. data that might have been placed into the - :attr:`.Column.info` dictionary + :attr:`_schema.Column.info` dictionary -* The value of the ``.quote`` setting for :class:`.Column` or :class:`.Table` +* The value of the ``.quote`` setting for :class:`_schema.Column` or :class:`_schema.Table` -* The association of a particular :class:`.Sequence` with a given :class:`.Column` +* The association of a particular :class:`.Sequence` with a given :class:`_schema.Column` The relational database also in many cases reports on table metadata in a -different format than what was specified in SQLAlchemy. The :class:`.Table` +different format than what was specified in SQLAlchemy. The :class:`_schema.Table` objects returned from reflection cannot be always relied upon to produce the identical -DDL as the original Python-defined :class:`.Table` objects. Areas where +DDL as the original Python-defined :class:`_schema.Table` objects. Areas where this occurs includes server defaults, column-associated sequences and various idiosyncrasies regarding constraints and datatypes. Server side defaults may be returned with cast directives (typically PostgreSQL will include a ``::`` diff --git a/doc/build/core/selectable.rst b/doc/build/core/selectable.rst index 2f69c0200c..72436d75d8 100644 --- a/doc/build/core/selectable.rst +++ b/doc/build/core/selectable.rst @@ -2,10 +2,10 @@ Selectables, Tables, FROM objects ================================= The term "selectable" refers to any object that rows can be selected from; -in SQLAlchemy, these objects descend from :class:`.FromClause` and their -distinguishing feature is their :attr:`.FromClause.c` attribute, which is +in SQLAlchemy, these objects descend from :class:`_expression.FromClause` and their +distinguishing feature is their :attr:`_expression.FromClause.c` attribute, which is a namespace of all the columns contained within the FROM clause (these -elements are themselves :class:`.ColumnElement` subclasses). +elements are themselves :class:`_expression.ColumnElement` subclasses). .. currentmodule:: sqlalchemy.sql.expression diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst index 720aadbe73..0973e487b3 100644 --- a/doc/build/core/tutorial.rst +++ b/doc/build/core/tutorial.rst @@ -78,7 +78,7 @@ the SQL behind a popup window so it doesn't get in our way; just click the "SQL" links to see what's being generated. The return value of :func:`.create_engine` is an instance of -:class:`.Engine`, and it represents the core interface to the +:class:`_engine.Engine`, and it represents the core interface to the database, adapted through a :term:`dialect` that handles the details of the database and :term:`DBAPI` in use. In this case the SQLite dialect will interpret instructions to the Python built-in ``sqlite3`` @@ -86,12 +86,12 @@ module. .. sidebar:: Lazy Connecting - The :class:`.Engine`, when first returned by :func:`.create_engine`, + The :class:`_engine.Engine`, when first returned by :func:`.create_engine`, has not actually tried to connect to the database yet; that happens only the first time it is asked to perform a task against the database. -The first time a method like :meth:`.Engine.execute` or :meth:`.Engine.connect` -is called, the :class:`.Engine` establishes a real :term:`DBAPI` connection to the +The first time a method like :meth:`_engine.Engine.execute` or :meth:`_engine.Engine.connect` +is called, the :class:`_engine.Engine` establishes a real :term:`DBAPI` connection to the database, which is then used to emit the SQL. .. seealso:: @@ -200,7 +200,7 @@ each table first before creating, so it's safe to call multiple times: Column('nickname', String(50)) ) - We include this more verbose :class:`~.schema.Table` construct separately + We include this more verbose :class:`_schema.Table` construct separately to highlight the difference between a minimal construct geared primarily towards in-Python usage only, versus one that will be used to emit CREATE TABLE statements on a particular set of backends with more stringent @@ -332,10 +332,10 @@ and use it in the "normal" way: {stop} Above, because we specified all three columns in the ``execute()`` method, -the compiled :class:`~.expression.Insert` included all three -columns. The :class:`~.expression.Insert` statement is compiled +the compiled :class:`_expression.Insert` included all three +columns. The :class:`_expression.Insert` statement is compiled at execution time based on the parameters we specified; if we specified fewer -parameters, the :class:`~.expression.Insert` would have fewer +parameters, the :class:`_expression.Insert` would have fewer entries in its VALUES clause. To issue many inserts using DBAPI's ``executemany()`` method, we can send in a @@ -366,7 +366,7 @@ assumed that all subsequent argument dictionaries are compatible with that statement. The "executemany" style of invocation is available for each of the -:func:`~.sql.expression.insert`, :func:`.update` and :func:`.delete` constructs. +:func:`_expression.insert`, :func:`_expression.update` and :func:`_expression.delete` constructs. .. _coretutorial_selecting: @@ -377,7 +377,7 @@ Selecting We began with inserts just so that our test database had some data in it. The more interesting part of the data is selecting it! We'll cover UPDATE and DELETE statements later. The primary construct used to generate SELECT -statements is the :func:`~.sql.expression.select` function: +statements is the :func:`_expression.select` function: .. sourcecode:: pycon+sql @@ -388,7 +388,7 @@ statements is the :func:`~.sql.expression.select` function: FROM users () -Above, we issued a basic :func:`~.sql.expression.select` call, placing the ``users`` table +Above, we issued a basic :func:`_expression.select` call, placing the ``users`` table within the COLUMNS clause of the select, and then executing. SQLAlchemy expanded the ``users`` table into the set of each of its columns, and also generated a FROM clause for us. The result returned is again a @@ -482,7 +482,7 @@ may be used as well: A more specialized method of column access is to use the SQL construct that directly corresponds to a particular column as the mapping key; in this -example, it means we would use the :class:`.Column` objects selected in our +example, it means we would use the :class:`_schema.Column` objects selected in our SELECT directly as keys in conjunction with the :attr:`.Row._mapping` collection: @@ -537,9 +537,9 @@ the ``c`` attribute of the :class:`~sqlalchemy.schema.Table` object: Lets observe something interesting about the FROM clause. Whereas the generated statement contains two distinct sections, a "SELECT columns" part -and a "FROM table" part, our :func:`~.sql.expression.select` construct only has a list +and a "FROM table" part, our :func:`_expression.select` construct only has a list containing columns. How does this work ? Let's try putting *two* tables into -our :func:`~.sql.expression.select` statement: +our :func:`_expression.select` statement: .. sourcecode:: pycon+sql @@ -561,7 +561,7 @@ It placed **both** tables into the FROM clause. But also, it made a real mess. Those who are familiar with SQL joins know that this is a **Cartesian product**; each row from the ``users`` table is produced against each row from the ``addresses`` table. So to put some sanity into this statement, we need a -WHERE clause. We do that using :meth:`.Select.where`: +WHERE clause. We do that using :meth:`_expression.Select.where`: .. sourcecode:: pycon+sql @@ -578,7 +578,7 @@ WHERE clause. We do that using :meth:`.Select.where`: (2, u'wendy', u'Wendy Williams', 3, 2, u'www@www.org') (2, u'wendy', u'Wendy Williams', 4, 2, u'wendy@aol.com') -So that looks a lot better, we added an expression to our :func:`~.sql.expression.select` +So that looks a lot better, we added an expression to our :func:`_expression.select` which had the effect of adding ``WHERE users.id = addresses.user_id`` to our statement, and our results were managed down so that the join of ``users`` and ``addresses`` rows made sense. But let's look at that expression? It's using @@ -600,11 +600,11 @@ Wow, surprise ! This is neither a ``True`` nor a ``False``. Well what is it ? 'users.id = addresses.user_id' As you can see, the ``==`` operator is producing an object that is very much -like the :class:`~.expression.Insert` and :func:`~.sql.expression.select` +like the :class:`_expression.Insert` and :func:`_expression.select` objects we've made so far, thanks to Python's ``__eq__()`` builtin; you call ``str()`` on it and it produces SQL. By now, one can see that everything we are working with is ultimately the same type of object. SQLAlchemy terms the -base class of all of these expressions as :class:`~.expression.ColumnElement`. +base class of all of these expressions as :class:`_expression.ColumnElement`. Operators ========= @@ -626,7 +626,7 @@ we get a bind parameter: users.id = :id_1 The ``7`` literal is embedded the resulting -:class:`~.expression.ColumnElement`; we can use the same trick +:class:`_expression.ColumnElement`; we can use the same trick we did with the :class:`~sqlalchemy.sql.expression.Insert` object to see it: .. sourcecode:: pycon+sql @@ -728,7 +728,7 @@ Conjunctions ============ -We'd like to show off some of our operators inside of :func:`~.sql.expression.select` +We'd like to show off some of our operators inside of :func:`_expression.select` constructs. But we need to lump them together a little more, so let's first introduce some conjunctions. Conjunctions are those little words like AND and OR that put things together. We'll also hit upon NOT. :func:`.and_`, :func:`.or_`, @@ -776,9 +776,9 @@ So with all of this vocabulary, let's select all users who have an email address at AOL or MSN, whose name starts with a letter between "m" and "z", and we'll also generate a column containing their full name combined with their email address. We will add two new constructs to this statement, -:meth:`~.ColumnOperators.between` and :meth:`~.ColumnElement.label`. +:meth:`~.ColumnOperators.between` and :meth:`_expression.ColumnElement.label`. :meth:`~.ColumnOperators.between` produces a BETWEEN clause, and -:meth:`~.ColumnElement.label` is used in a column expression to produce labels using the ``AS`` +:meth:`_expression.ColumnElement.label` is used in a column expression to produce labels using the ``AS`` keyword; it's recommended when selecting from expressions that otherwise would not have a name: @@ -811,7 +811,7 @@ clause, the where clause, and also some other elements which we haven't covered yet, which include ORDER BY, GROUP BY, and HAVING. A shortcut to using :func:`.and_` is to chain together multiple -:meth:`~.Select.where` clauses. The above can also be written as: +:meth:`_expression.Select.where` clauses. The above can also be written as: .. sourcecode:: pycon+sql @@ -834,7 +834,7 @@ A shortcut to using :func:`.and_` is to chain together multiple (', ', 'm', 'z', '%@aol.com', '%@msn.com') [(u'Wendy Williams, wendy@aol.com',)] -The way that we can build up a :func:`~.sql.expression.select` construct through successive +The way that we can build up a :func:`_expression.select` construct through successive method calls is called :term:`method chaining`. .. _sqlexpression_text: @@ -847,9 +847,9 @@ understands to be a textual SQL expression into a Python construct which groups components together in a programmatic style can be hard. That's why SQLAlchemy lets you just use strings, for those cases when the SQL is already known and there isn't a strong need for the statement to support -dynamic features. The :func:`~.expression.text` construct is used +dynamic features. The :func:`_expression.text` construct is used to compose a textual statement that is passed to the database mostly -unchanged. Below, we create a :func:`~.expression.text` object and execute it: +unchanged. Below, we create a :func:`_expression.text` object and execute it: .. sourcecode:: pycon+sql @@ -870,16 +870,16 @@ unchanged. Below, we create a :func:`~.expression.text` object and execute it: {stop}[(u'Wendy Williams, wendy@aol.com',)] Above, we can see that bound parameters are specified in -:func:`~.expression.text` using the named colon format; this format is +:func:`_expression.text` using the named colon format; this format is consistent regardless of database backend. To send values in for the -parameters, we passed them into the :meth:`~.Connection.execute` method +parameters, we passed them into the :meth:`_engine.Connection.execute` method as additional arguments. Specifying Bound Parameter Behaviors ------------------------------------ -The :func:`~.expression.text` construct supports pre-established bound values -using the :meth:`.TextClause.bindparams` method:: +The :func:`_expression.text` construct supports pre-established bound values +using the :meth:`_expression.TextClause.bindparams` method:: stmt = text("SELECT * FROM users WHERE users.name BETWEEN :x AND :y") stmt = stmt.bindparams(x="m", y="z") @@ -894,7 +894,7 @@ or special SQL-side processing provided by the datatype. .. seealso:: - :meth:`.TextClause.bindparams` - full method description + :meth:`_expression.TextClause.bindparams` - full method description .. _sqlexpression_text_columns: @@ -902,7 +902,7 @@ Specifying Result-Column Behaviors ---------------------------------- We may also specify information about the result columns using the -:meth:`.TextClause.columns` method; this method can be used to specify +:meth:`_expression.TextClause.columns` method; this method can be used to specify the return types, based on name:: stmt = stmt.columns(id=Integer, name=String) @@ -915,7 +915,7 @@ expressions to the SQL will be done positionally:: stmt = text("SELECT id, name FROM users") stmt = stmt.columns(users.c.id, users.c.name) -When we call the :meth:`.TextClause.columns` method, we get back a +When we call the :meth:`_expression.TextClause.columns` method, we get back a :class:`.TextAsFrom` object that supports the full suite of :attr:`.TextAsFrom.c` and other "selectable" operations:: @@ -924,7 +924,7 @@ When we call the :meth:`.TextClause.columns` method, we get back a new_stmt = select([stmt.c.id, addresses.c.id]).\ select_from(j).where(stmt.c.name == 'x') -The positional form of :meth:`.TextClause.columns` is particularly useful +The positional form of :meth:`_expression.TextClause.columns` is particularly useful when relating textual SQL to existing Core or ORM models, because we can use column expressions directly without worrying about name conflicts or other issues with the result column names in the textual SQL: @@ -967,40 +967,40 @@ the ``id`` value:: InvalidRequestError: Ambiguous column name 'id' in result set column descriptions It's important to note that while accessing columns from a result set using -:class:`.Column` objects may seem unusual, it is in fact the only system +:class:`_schema.Column` objects may seem unusual, it is in fact the only system used by the ORM, which occurs transparently beneath the facade of the -:class:`~.orm.query.Query` object; in this way, the :meth:`.TextClause.columns` method +:class:`~.orm.query.Query` object; in this way, the :meth:`_expression.TextClause.columns` method is typically very applicable to textual statements to be used in an ORM context. The example at :ref:`orm_tutorial_literal_sql` illustrates a simple usage. .. versionadded:: 1.1 - The :meth:`.TextClause.columns` method now accepts column expressions + The :meth:`_expression.TextClause.columns` method now accepts column expressions which will be matched positionally to a plain text SQL result set, eliminating the need for column names to match or even be unique in the SQL statement when matching table metadata or ORM models to textual SQL. .. seealso:: - :meth:`.TextClause.columns` - full method description + :meth:`_expression.TextClause.columns` - full method description :ref:`orm_tutorial_literal_sql` - integrating ORM-level queries with - :func:`.text` + :func:`_expression.text` Using text() fragments inside bigger statements ----------------------------------------------- -:func:`~.expression.text` can also be used to produce fragments of SQL +:func:`_expression.text` can also be used to produce fragments of SQL that can be freely within a -:func:`~.expression.select` object, which accepts :func:`~.expression.text` +:func:`_expression.select` object, which accepts :func:`_expression.text` objects as an argument for most of its builder functions. -Below, we combine the usage of :func:`~.expression.text` within a -:func:`~.sql.expression.select` object. The :func:`~.expression.select` construct provides the "geometry" -of the statement, and the :func:`~.expression.text` construct provides the +Below, we combine the usage of :func:`_expression.text` within a +:func:`_expression.select` object. The :func:`_expression.select` construct provides the "geometry" +of the statement, and the :func:`_expression.text` construct provides the textual content within this form. We can build a statement without the -need to refer to any pre-established :class:`.Table` metadata: +need to refer to any pre-established :class:`_schema.Table` metadata: .. sourcecode:: pycon+sql @@ -1025,30 +1025,29 @@ need to refer to any pre-established :class:`.Table` metadata: {stop}[(u'Wendy Williams, wendy@aol.com',)] .. versionchanged:: 1.0.0 - The :func:`~.sql.expression.select` construct emits warnings when string SQL - fragments are coerced to :func:`.text`, and :func:`.text` should + The :func:`_expression.select` construct emits warnings when string SQL + fragments are coerced to :func:`_expression.text`, and :func:`_expression.text` should be used explicitly. See :ref:`migration_2992` for background. .. _sqlexpression_literal_column: -Using More Specific Text with :func:`.table`, :func:`.literal_column`, and :func:`.column` -------------------------------------------------------------------------------------------- - +Using More Specific Text with :func:`.table`, :func:`_expression.literal_column`, and :func:`_expression.column` +----------------------------------------------------------------------------------------------------------------- We can move our level of structure back in the other direction too, -by using :func:`~.expression.column`, :func:`~.expression.literal_column`, -and :func:`~.expression.table` for some of the +by using :func:`_expression.column`, :func:`_expression.literal_column`, +and :func:`_expression.table` for some of the key elements of our statement. Using these constructs, we can get -some more expression capabilities than if we used :func:`~.expression.text` +some more expression capabilities than if we used :func:`_expression.text` directly, as they provide to the Core more information about how the strings they store are to be used, but still without the need to get into full -:class:`.Table` based metadata. Below, we also specify the :class:`.String` -datatype for two of the key :func:`~.expression.literal_column` objects, +:class:`_schema.Table` based metadata. Below, we also specify the :class:`.String` +datatype for two of the key :func:`_expression.literal_column` objects, so that the string-specific concatenation operator becomes available. -We also use :func:`~.expression.literal_column` in order to use table-qualified +We also use :func:`_expression.literal_column` in order to use table-qualified expressions, e.g. ``users.fullname``, that will be rendered as is; -using :func:`~.expression.column` implies an individual column name that may +using :func:`_expression.column` implies an individual column name that may be quoted: .. sourcecode:: pycon+sql @@ -1086,8 +1085,8 @@ One place where we sometimes want to use a string as a shortcut is when our statement has some labeled column element that we want to refer to in a place such as the "ORDER BY" or "GROUP BY" clause; other candidates include fields within an "OVER" or "DISTINCT" clause. If we have such a label -in our :func:`~.sql.expression.select` construct, we can refer to it directly by passing the -string straight into :meth:`.select.order_by` or :meth:`.select.group_by`, +in our :func:`_expression.select` construct, we can refer to it directly by passing the +string straight into :meth:`_expression.select.order_by` or :meth:`_expression.select.group_by`, among others. This will refer to the named label and also prevent the expression from being rendered twice. Label names that resolve to columns are rendered fully: @@ -1124,11 +1123,11 @@ name: {stop}[(1, 2), (2, 2)] Note that the string feature here is very much tailored to when we have -already used the :meth:`~.ColumnElement.label` method to create a +already used the :meth:`_expression.ColumnElement.label` method to create a specifically-named label. In other cases, we always want to refer to the -:class:`.ColumnElement` object directly so that the expression system can +:class:`_expression.ColumnElement` object directly so that the expression system can make the most effective choices for rendering. Below, we illustrate how using -the :class:`.ColumnElement` eliminates ambiguity when we want to order +the :class:`_expression.ColumnElement` eliminates ambiguity when we want to order by a column name that appears more than once: .. sourcecode:: pycon+sql @@ -1162,11 +1161,11 @@ FROM clause multiple times. In the case of a SELECT statement, it provides a parent name for the columns represented by the statement, allowing them to be referenced relative to this name. -In SQLAlchemy, any :class:`.Table` or other :class:`.FromClause` based -selectable can be turned into an alias using :meth:`.FromClause.alias` method, -which produces an :class:`.Alias` construct. :class:`.Alias` is a -:class:`.FromClause` object that refers to a mapping of :class:`.Column` -objects via its :attr:`.FromClause.c` collection, and can be used within the +In SQLAlchemy, any :class:`_schema.Table` or other :class:`_expression.FromClause` based +selectable can be turned into an alias using :meth:`_expression.FromClause.alias` method, +which produces an :class:`_expression.Alias` construct. :class:`_expression.Alias` is a +:class:`_expression.FromClause` object that refers to a mapping of :class:`_schema.Column` +objects via its :attr:`_expression.FromClause.c` collection, and can be used within the FROM clause of any subsequent SELECT statement, by referring to its column elements in the columns or WHERE clause of the statement, or through explicit placement in the FROM clause, either directly or within a join. @@ -1174,8 +1173,8 @@ placement in the FROM clause, either directly or within a join. As an example, suppose we know that our user ``jack`` has two particular email addresses. How can we locate jack based on the combination of those two addresses? To accomplish this, we'd use a join to the ``addresses`` table, -once for each address. We create two :class:`.Alias` constructs against -``addresses``, and then use them both within a :func:`~.sql.expression.select` construct: +once for each address. We create two :class:`_expression.Alias` constructs against +``addresses``, and then use them both within a :func:`_expression.select` construct: .. sourcecode:: pycon+sql @@ -1198,7 +1197,7 @@ once for each address. We create two :class:`.Alias` constructs against ('jack@msn.com', 'jack@yahoo.com') {stop}[(1, u'jack', u'Jack Jones')] -Note that the :class:`.Alias` construct generated the names ``addresses_1`` and +Note that the :class:`_expression.Alias` construct generated the names ``addresses_1`` and ``addresses_2`` in the final SQL result. The generation of these names is determined by the position of the construct within the statement. If we created a query using only the second ``a2`` alias, the name would come out as ``addresses_1``. The @@ -1206,22 +1205,22 @@ generation of the names is also *deterministic*, meaning the same SQLAlchemy statement construct will produce the identical SQL string each time it is rendered for a particular dialect. -Since on the outside, we refer to the alias using the :class:`.Alias` construct +Since on the outside, we refer to the alias using the :class:`_expression.Alias` construct itself, we don't need to be concerned about the generated name. However, for the purposes of debugging, it can be specified by passing a string name -to the :meth:`.FromClause.alias` method:: +to the :meth:`_expression.FromClause.alias` method:: >>> a1 = addresses.alias('a1') -SELECT-oriented constructs which extend from :class:`.SelectBase` may be turned -into aliased subqueries using the :meth:`.SelectBase.subquery` method, which +SELECT-oriented constructs which extend from :class:`_expression.SelectBase` may be turned +into aliased subqueries using the :meth:`_expression.SelectBase.subquery` method, which produces a :class:`.Subquery` construct; for ease of use, there is also a -:meth:`.SelectBase.alias` method that is synonymous with -:class:`.SelectBase.subquery`. Like :class:`.Alias`, :class:`.Subquery` is -also a :class:`.FromClause` object that may be part of any enclosing SELECT -using the same techniques one would use for a :class:`.Alias`. +:meth:`_expression.SelectBase.alias` method that is synonymous with +:class:`_expression.SelectBase.subquery`. Like :class:`_expression.Alias`, :class:`.Subquery` is +also a :class:`_expression.FromClause` object that may be part of any enclosing SELECT +using the same techniques one would use for a :class:`_expression.Alias`. -We can self-join the ``users`` table back to the :func:`~.sql.expression.select` we've created +We can self-join the ``users`` table back to the :func:`_expression.select` we've created by making :class:`.Subquery` of the entire statement: .. sourcecode:: pycon+sql @@ -1250,9 +1249,9 @@ Using Joins We're halfway along to being able to construct any SELECT expression. The next cornerstone of the SELECT is the JOIN expression. We've already been doing joins in our examples, by just placing two tables in either the columns clause -or the where clause of the :func:`~.sql.expression.select` construct. But if we want to make a -real "JOIN" or "OUTERJOIN" construct, we use the :meth:`~.FromClause.join` and -:meth:`~.FromClause.outerjoin` methods, most commonly accessed from the left table in the +or the where clause of the :func:`_expression.select` construct. But if we want to make a +real "JOIN" or "OUTERJOIN" construct, we use the :meth:`_expression.FromClause.join` and +:meth:`_expression.FromClause.outerjoin` methods, most commonly accessed from the left table in the join: .. sourcecode:: pycon+sql @@ -1279,10 +1278,10 @@ username: ... ) users JOIN addresses ON addresses.email_address LIKE users.name || :name_1 -When we create a :func:`~.sql.expression.select` construct, SQLAlchemy looks around at the +When we create a :func:`_expression.select` construct, SQLAlchemy looks around at the tables we've mentioned and then places them in the FROM clause of the statement. When we use JOINs however, we know what FROM clause we want, so -here we make use of the :meth:`~.Select.select_from` method: +here we make use of the :meth:`_expression.Select.select_from` method: .. sourcecode:: pycon+sql @@ -1296,8 +1295,8 @@ here we make use of the :meth:`~.Select.select_from` method: ('%',) {stop}[(u'Jack Jones',), (u'Jack Jones',), (u'Wendy Williams',)] -The :meth:`~.FromClause.outerjoin` method creates ``LEFT OUTER JOIN`` constructs, -and is used in the same way as :meth:`~.FromClause.join`: +The :meth:`_expression.FromClause.outerjoin` method creates ``LEFT OUTER JOIN`` constructs, +and is used in the same way as :meth:`_expression.FromClause.join`: .. sourcecode:: pycon+sql @@ -1324,11 +1323,11 @@ Oracle DBAs don't want their black magic being found out ;). .. seealso:: - :func:`.expression.join` + :func:`_expression.join` - :func:`.expression.outerjoin` + :func:`_expression.outerjoin` - :class:`.Join` + :class:`_expression.Join` Everything Else =============== @@ -1610,7 +1609,7 @@ another function :func:`.type_coerce` which is closely related to :func:`.cast`, in that it sets up a Python expression as having a specific SQL database type, but does not render the ``CAST`` keyword or datatype on the database side. :func:`.type_coerce` is particularly important when dealing -with the :class:`.types.JSON` datatype, which typically has an intricate +with the :class:`_types.JSON` datatype, which typically has an intricate relationship with string-oriented datatypes on different platforms and may not even be an explicit datatype, such as on SQLite and MariaDB. Below, we use :func:`.type_coerce` to deliver a Python structure as a JSON @@ -1632,7 +1631,7 @@ string into one of MySQL's JSON functions: Above, MySQL's ``JSON_EXTRACT`` SQL function was invoked because we used :func:`.type_coerce` to indicate that our Python dictionary -should be treated as :class:`.types.JSON`. The Python ``__getitem__`` +should be treated as :class:`_types.JSON`. The Python ``__getitem__`` operator, ``['some_key']`` in this case, became available as a result and allowed a ``JSON_EXTRACT`` path expression (not shown, however in this case it would ultimately be ``'$."some_key"'``) to be rendered. @@ -1641,8 +1640,8 @@ Unions and Other Set Operations ------------------------------- Unions come in two flavors, UNION and UNION ALL, which are available via -module level functions :func:`~.expression.union` and -:func:`~.expression.union_all`: +module level functions :func:`_expression.union` and +:func:`_expression.union_all`: .. sourcecode:: pycon+sql @@ -1666,9 +1665,9 @@ module level functions :func:`~.expression.union` and {stop}[(1, 1, u'jack@yahoo.com')] Also available, though not supported on all databases, are -:func:`~.expression.intersect`, -:func:`~.expression.intersect_all`, -:func:`~.expression.except_`, and :func:`~.expression.except_all`: +:func:`_expression.intersect`, +:func:`_expression.intersect_all`, +:func:`_expression.except_`, and :func:`_expression.except_all`: .. sourcecode:: pycon+sql @@ -1731,17 +1730,17 @@ want the "union" to be stated as a subquery: .. seealso:: - :func:`.union` + :func:`_expression.union` - :func:`.union_all` + :func:`_expression.union_all` - :func:`.intersect` + :func:`_expression.intersect` - :func:`.intersect_all` + :func:`_expression.intersect_all` :func:`.except_` - :func:`.except_all` + :func:`_expression.except_all` Ordering Unions ^^^^^^^^^^^^^^^ @@ -1752,7 +1751,7 @@ whole result usually requires that an ORDER BY clause refer to column names but not specific tables. As in the previous examples, we used ``.order_by(addresses.c.email_address)`` but SQLAlchemy rendered the ORDER BY without using the table name. A generalized way to apply ORDER BY to a union -is also to refer to the :attr:`.CompoundSelect.selected_columns` collection in +is also to refer to the :attr:`_selectable.CompoundSelect.selected_columns` collection in order to access the column expressions which are synonymous with the columns selected from the first SELECT; the SQLAlchemy compiler will ensure these will be rendered without table names:: @@ -1783,9 +1782,9 @@ column. It can then be used as a column expression. A scalar select is often a :term:`correlated subquery`, which relies upon the enclosing SELECT statement in order to acquire at least one of its FROM clauses. -The :func:`~.sql.expression.select` construct can be modified to act as a -column expression by calling either the :meth:`~.SelectBase.scalar_subquery` -or :meth:`~.SelectBase.label` method: +The :func:`_expression.select` construct can be modified to act as a +column expression by calling either the :meth:`_expression.SelectBase.scalar_subquery` +or :meth:`_expression.SelectBase.label` method: .. sourcecode:: pycon+sql @@ -1793,11 +1792,11 @@ or :meth:`~.SelectBase.label` method: ... where(users.c.id == addresses.c.user_id).\ ... scalar_subquery() -The above construct is now a :class:`~.expression.ScalarSelect` object, +The above construct is now a :class:`_expression.ScalarSelect` object, which is an adapter around the original :class:`.~expression.Select` -object; it participates within the :class:`~.expression.ColumnElement` +object; it participates within the :class:`_expression.ColumnElement` family of expression constructs. We can place this construct the same as any -other column within another :func:`~.sql.expression.select`: +other column within another :func:`_expression.select`: .. sourcecode:: pycon+sql @@ -1810,7 +1809,7 @@ other column within another :func:`~.sql.expression.select`: {stop}[(u'jack', 2), (u'wendy', 2)] To apply a non-anonymous column name to our scalar select, we create -it using :meth:`.SelectBase.label` instead: +it using :meth:`_expression.SelectBase.label` instead: .. sourcecode:: pycon+sql @@ -1827,9 +1826,9 @@ it using :meth:`.SelectBase.label` instead: .. seealso:: - :meth:`.Select.scalar_subquery` + :meth:`_expression.Select.scalar_subquery` - :meth:`.Select.label` + :meth:`_expression.Select.label` .. _correlated_subqueries: @@ -1862,7 +1861,7 @@ still have at least one FROM clause of its own. For example: Auto-correlation will usually do what's expected, however it can also be controlled. For example, if we wanted a statement to correlate only to the ``addresses`` table but not the ``users`` table, even if both were present in the enclosing SELECT, -we use the :meth:`~.Select.correlate` method to specify those FROM clauses that +we use the :meth:`_expression.Select.correlate` method to specify those FROM clauses that may be correlated: .. sourcecode:: pycon+sql @@ -1903,7 +1902,7 @@ as the argument: ('wendy',) {stop}[(u'wendy',)] -We can also control correlation via exclusion, using the :meth:`.Select.correlate_except` +We can also control correlation via exclusion, using the :meth:`_expression.Select.correlate_except` method. Such as, we can write our SELECT for the ``users`` table by telling it to correlate all FROM clauses except for ``users``: @@ -1954,7 +1953,7 @@ behavior around, allowing an expression such as: Where above, the right side of the JOIN contains a subquery that refers not just to the "books" table but also the "people" table, correlating to the left side of the JOIN. SQLAlchemy Core supports a statement -like the above using the :meth:`.Select.lateral` method as follows:: +like the above using the :meth:`_expression.Select.lateral` method as follows:: >>> from sqlalchemy import table, column, select, true >>> people = table('people', column('people_id'), column('age'), column('name')) @@ -1967,20 +1966,20 @@ like the above using the :meth:`.Select.lateral` method as follows:: FROM books WHERE books.owner_id = people.people_id) AS book_subq ON true -Above, we can see that the :meth:`.Select.lateral` method acts a lot like -the :meth:`.Select.alias` method, including that we can specify an optional -name. However the construct is the :class:`.Lateral` construct instead of -an :class:`.Alias` which provides for the LATERAL keyword as well as special +Above, we can see that the :meth:`_expression.Select.lateral` method acts a lot like +the :meth:`_expression.Select.alias` method, including that we can specify an optional +name. However the construct is the :class:`_expression.Lateral` construct instead of +an :class:`_expression.Alias` which provides for the LATERAL keyword as well as special instructions to allow correlation from inside the FROM clause of the enclosing statement. -The :meth:`.Select.lateral` method interacts normally with the -:meth:`.Select.correlate` and :meth:`.Select.correlate_except` methods, except +The :meth:`_expression.Select.lateral` method interacts normally with the +:meth:`_expression.Select.correlate` and :meth:`_expression.Select.correlate_except` methods, except that the correlation rules also apply to any other tables present in the enclosing statement's FROM clause. Correlation is "automatic" to these tables by default, is explicit if the table is specified to -:meth:`.Select.correlate`, and is explicit to all tables except those -specified to :meth:`.Select.correlate_except`. +:meth:`_expression.Select.correlate`, and is explicit to all tables except those +specified to :meth:`_expression.Select.correlate_except`. .. versionadded:: 1.1 @@ -1989,9 +1988,9 @@ specified to :meth:`.Select.correlate_except`. .. seealso:: - :class:`.Lateral` + :class:`_expression.Lateral` - :meth:`.Select.lateral` + :meth:`_expression.Select.lateral` .. _core_tutorial_ordering: @@ -2000,7 +1999,7 @@ Ordering, Grouping, Limiting, Offset...ing... --------------------------------------------- Ordering is done by passing column expressions to the -:meth:`~.SelectBase.order_by` method: +:meth:`_expression.SelectBase.order_by` method: .. sourcecode:: pycon+sql @@ -2011,8 +2010,8 @@ Ordering is done by passing column expressions to the () {stop}[(u'jack',), (u'wendy',)] -Ascending or descending can be controlled using the :meth:`~.ColumnElement.asc` -and :meth:`~.ColumnElement.desc` modifiers: +Ascending or descending can be controlled using the :meth:`_expression.ColumnElement.asc` +and :meth:`_expression.ColumnElement.desc` modifiers: .. sourcecode:: pycon+sql @@ -2025,7 +2024,7 @@ and :meth:`~.ColumnElement.desc` modifiers: Grouping refers to the GROUP BY clause, and is usually used in conjunction with aggregate functions to establish groups of rows to be aggregated. -This is provided via the :meth:`~.SelectBase.group_by` method: +This is provided via the :meth:`_expression.SelectBase.group_by` method: .. sourcecode:: pycon+sql @@ -2041,7 +2040,7 @@ This is provided via the :meth:`~.SelectBase.group_by` method: {stop}[(u'jack', 2), (u'wendy', 2)] HAVING can be used to filter results on an aggregate value, after GROUP BY has -been applied. It's available here via the :meth:`~.Select.having` +been applied. It's available here via the :meth:`_expression.Select.having` method: .. sourcecode:: pycon+sql @@ -2061,7 +2060,7 @@ method: A common system of dealing with duplicates in composed SELECT statements is the DISTINCT modifier. A simple DISTINCT clause can be added using the -:meth:`.Select.distinct` method: +:meth:`_expression.Select.distinct` method: .. sourcecode:: pycon+sql @@ -2081,8 +2080,8 @@ are returned, and the majority also feature a means of starting to return rows after a given "offset". While common backends like PostgreSQL, MySQL and SQLite support LIMIT and OFFSET keywords, other backends need to refer to more esoteric features such as "window functions" -and row ids to achieve the same effect. The :meth:`~.Select.limit` -and :meth:`~.Select.offset` methods provide an easy abstraction +and row ids to achieve the same effect. The :meth:`_expression.Select.limit` +and :meth:`_expression.Select.offset` methods provide an easy abstraction into the current backend's methodology: .. sourcecode:: pycon+sql @@ -2103,9 +2102,9 @@ into the current backend's methodology: Inserts, Updates and Deletes ============================ -We've seen :meth:`~.TableClause.insert` demonstrated -earlier in this tutorial. Where :meth:`~.TableClause.insert` -produces INSERT, the :meth:`~.TableClause.update` +We've seen :meth:`_expression.TableClause.insert` demonstrated +earlier in this tutorial. Where :meth:`_expression.TableClause.insert` +produces INSERT, the :meth:`_expression.TableClause.update` method produces UPDATE. Both of these constructs feature a method called :meth:`~.ValuesBase.values` which specifies the VALUES or SET clause of the statement. @@ -2123,16 +2122,16 @@ as a value: COMMIT {stop} -When using :meth:`~.TableClause.insert` or :meth:`~.TableClause.update` +When using :meth:`_expression.TableClause.insert` or :meth:`_expression.TableClause.update` in an "execute many" context, we may also want to specify named bound parameters which we can refer to in the argument list. The two constructs will automatically generate bound placeholders for any column names passed in the dictionaries sent to -:meth:`~.Connection.execute` at execution time. However, if we +:meth:`_engine.Connection.execute` at execution time. However, if we wish to use explicitly targeted named parameters with composed expressions, -we need to use the :func:`~.expression.bindparam` construct. -When using :func:`~.expression.bindparam` with -:meth:`~.TableClause.insert` or :meth:`~.TableClause.update`, +we need to use the :func:`_expression.bindparam` construct. +When using :func:`_expression.bindparam` with +:meth:`_expression.TableClause.insert` or :meth:`_expression.TableClause.update`, the names of the table's columns themselves are reserved for the "automatic" generation of bind names. We can combine the usage of implicitly available bind names and explicitly named parameters @@ -2152,7 +2151,7 @@ as in the example below: COMMIT -An UPDATE statement is emitted using the :meth:`~.TableClause.update` construct. This +An UPDATE statement is emitted using the :meth:`_expression.TableClause.update` construct. This works much like an INSERT, except there is an additional WHERE clause that can be specified: @@ -2168,9 +2167,9 @@ that can be specified: COMMIT {stop} -When using :meth:`~.TableClause.update` in an "executemany" context, +When using :meth:`_expression.TableClause.update` in an "executemany" context, we may wish to also use explicitly named bound parameters in the -WHERE clause. Again, :func:`~.expression.bindparam` is the construct +WHERE clause. Again, :func:`_expression.bindparam` is the construct used to achieve this: .. sourcecode:: pycon+sql @@ -2194,7 +2193,7 @@ Correlated Updates A correlated update lets you update a table using selection from another table, or the same table; the SELECT statement is passed as a scalar -subquery using :meth:`.Select.scalar_subquery`: +subquery using :meth:`_expression.Select.scalar_subquery`: .. sourcecode:: pycon+sql @@ -2220,7 +2219,7 @@ that refer to multiple tables. For PG and MSSQL, this is the "UPDATE FROM" syn which updates one table at a time, but can reference additional tables in an additional "FROM" clause that can then be referenced in the WHERE clause directly. On MySQL, multiple tables can be embedded into a single UPDATE statement separated by a comma. -The SQLAlchemy :func:`.update` construct supports both of these modes +The SQLAlchemy :func:`_expression.update` construct supports both of these modes implicitly, by specifying multiple tables in the WHERE clause:: stmt = users.update().\ @@ -2236,7 +2235,7 @@ The resulting SQL from the above statement would render as:: addresses.email_address LIKE :email_address_1 || '%' When using MySQL, columns from each table can be assigned to in the -SET clause directly, using the dictionary form passed to :meth:`.Update.values`:: +SET clause directly, using the dictionary form passed to :meth:`_expression.Update.values`:: stmt = users.update().\ values({ @@ -2263,14 +2262,14 @@ construct. Parameter-Ordered Updates ------------------------- -The default behavior of the :func:`.update` construct when rendering the SET +The default behavior of the :func:`_expression.update` construct when rendering the SET clauses is to render them using the column ordering given in the -originating :class:`.Table` object. +originating :class:`_schema.Table` object. This is an important behavior, since it means that the rendering of a particular UPDATE statement with particular columns will be rendered the same each time, which has an impact on query caching systems that rely on the form of the statement, either client side or server side. -Since the parameters themselves are passed to the :meth:`.Update.values` +Since the parameters themselves are passed to the :meth:`_expression.Update.values` method as Python dictionary keys, there is no other fixed ordering available. @@ -2290,7 +2289,7 @@ a per-value basis, as opposed to on a per-row basis, and as each SET clause is evaluated, the values embedded in the row are changing. To suit this specific use case, the -:meth:`.update.ordered_values` method may be used. When using this method, +:meth:`_expression.update.ordered_values` method may be used. When using this method, we supply a **series of 2-tuples** as the argument to the method:: @@ -2302,8 +2301,8 @@ dictionary, except that it explicitly suggests a specific ordering. Using the above form, we are assured that the "y" column's SET clause will render first, then the "x" column's SET clause. -.. versionchanged:: 1.4 Added the :meth:`.Update.ordered_values` method which - supersedes the :paramref:`.update.preserve_parameter_order` flag that will +.. versionchanged:: 1.4 Added the :meth:`_expression.Update.ordered_values` method which + supersedes the :paramref:`_expression.update.preserve_parameter_order` flag that will be removed in SQLAlchemy 2.0. .. seealso:: @@ -2317,7 +2316,7 @@ Deletes ------- Finally, a delete. This is accomplished easily enough using the -:meth:`~.TableClause.delete` construct: +:meth:`_expression.TableClause.delete` construct: .. sourcecode:: pycon+sql @@ -2344,7 +2343,7 @@ The PostgreSQL, Microsoft SQL Server, and MySQL backends all support DELETE statements that refer to multiple tables within the WHERE criteria. For PG and MySQL, this is the "DELETE USING" syntax, and for SQL Server, it's a "DELETE FROM" that refers to more than one table. The SQLAlchemy -:func:`.delete` construct supports both of these modes +:func:`_expression.delete` construct supports both of these modes implicitly, by specifying multiple tables in the WHERE clause:: stmt = users.delete().\ @@ -2367,8 +2366,8 @@ construct. Matched Row Counts ------------------ -Both of :meth:`~.TableClause.update` and -:meth:`~.TableClause.delete` are associated with *matched row counts*. This is a +Both of :meth:`_expression.TableClause.update` and +:meth:`_expression.TableClause.delete` are associated with *matched row counts*. This is a number indicating the number of rows that were matched by the WHERE clause. Note that by "matched", this includes rows where no UPDATE actually took place. The value is available as :attr:`~.ResultProxy.rowcount`: diff --git a/doc/build/core/visitors.rst b/doc/build/core/visitors.rst index 539d664405..6ef466265d 100644 --- a/doc/build/core/visitors.rst +++ b/doc/build/core/visitors.rst @@ -6,7 +6,7 @@ that serve the purpose of generically **traversing** a Core SQL expression structure. This is not unlike the Python ``ast`` module in that is presents a system by which a program can operate upon each component of a SQL expression. Common purposes this serves are locating various kinds of -elements such as :class:`.Table` or :class:`.BindParameter` objects, +elements such as :class:`_schema.Table` or :class:`.BindParameter` objects, as well as altering the state of the structure such as replacing certain FROM clauses with others. diff --git a/doc/build/dialects/oracle.rst b/doc/build/dialects/oracle.rst index 52d514aad2..988a698e82 100644 --- a/doc/build/dialects/oracle.rst +++ b/doc/build/dialects/oracle.rst @@ -18,7 +18,7 @@ they originate from :mod:`sqlalchemy.types` or from the local dialect:: NUMBER, NVARCHAR, NVARCHAR2, RAW, TIMESTAMP, VARCHAR, \ VARCHAR2 -.. versionadded:: 1.2.19 Added :class:`.NCHAR` to the list of datatypes +.. versionadded:: 1.2.19 Added :class:`_types.NCHAR` to the list of datatypes exported by the Oracle dialect. Types which are specific to Oracle, or have Oracle-specific diff --git a/doc/build/errors.rst b/doc/build/errors.rst index 43e0b9fa49..107bc3c251 100644 --- a/doc/build/errors.rst +++ b/doc/build/errors.rst @@ -88,7 +88,7 @@ familiar with. * **The SQLAlchemy Engine object uses a pool of connections by default** - What this means is that when one makes use of a SQL database connection resource - of an :class:`.Engine` object, and then :term:`releases` that resource, + of an :class:`_engine.Engine` object, and then :term:`releases` that resource, the database connection itself remains connected to the database and is returned to an internal queue where it can be used again. Even though the code may appear to be ending its conversation with the database, in many @@ -96,7 +96,7 @@ familiar with. that persist until the application ends or the pool is explicitly disposed. * Because of the pool, when an application makes use of a SQL database - connection, most typically from either making use of :meth:`.Engine.connect` + connection, most typically from either making use of :meth:`_engine.Engine.connect` or when making queries using an ORM :class:`.Session`, this activity does not necessarily establish a new connection to the database at the moment the connection object is acquired; it instead consults the @@ -114,7 +114,7 @@ familiar with. engine = create_engine("mysql://u:p@host/db", pool_size=10, max_overflow=20) - The above :class:`.Engine` will allow **at most 30 connections** to be in + The above :class:`_engine.Engine` will allow **at most 30 connections** to be in play at any time, not including connections that were detached from the engine or invalidated. If a request for a new connection arrives and 30 connections are already in use by other parts of the application, @@ -174,7 +174,7 @@ What causes an application to use up all the connections that it has available? A common reason this can occur is that the application uses ORM sessions and does not call :meth:`.Session.close` upon them one the work involving that session is complete. Solution is to make sure ORM sessions if using the ORM, - or engine-bound :class:`.Connection` objects if using Core, are explicitly + or engine-bound :class:`_engine.Connection` objects if using Core, are explicitly closed at the end of the work being done, either via the appropriate ``.close()`` method, or by using one of the available context managers (e.g. "with:" statement) to properly release the resource. @@ -231,8 +231,8 @@ This connection is on an inactive transaction. Please rollback() fully before p ------------------------------------------------------------------------------------------ This error condition was added to SQLAlchemy as of version 1.4. The error -refers to the state where a :class:`.Connection` is placed into a transaction -using a method like :meth:`.Connection.begin`, and then a further "sub" transaction +refers to the state where a :class:`_engine.Connection` is placed into a transaction +using a method like :meth:`_engine.Connection.begin`, and then a further "sub" transaction is created within that scope; the "sub" transaction is then rolled back using :meth:`.Transaction.rollback`, however the outer transaction is not rolled back. @@ -258,12 +258,12 @@ this pattern more commonly in the ORM :class:`.Session`, where the FAQ entry The "subtransaction" pattern in Core comes into play often when using the ORM pattern described at :ref:`session_external_transaction`. As this pattern -involves a behavior called "connection branching", where a :class:`.Connection` -serves a "branched" :class:`.Connection` object to the :class:`.Session` via -its :meth:`.Connection.connect` method, the same transaction behavior comes +involves a behavior called "connection branching", where a :class:`_engine.Connection` +serves a "branched" :class:`_engine.Connection` object to the :class:`.Session` via +its :meth:`_engine.Connection.connect` method, the same transaction behavior comes into play; if the :class:`.Session` rolls back the transaction, and savepoints have not been used to prevent a rollback of the entire transaction, the -outermost transaction started on the :class:`.Connection` is now in an inactive +outermost transaction started on the :class:`_engine.Connection` is now in an inactive state. @@ -412,7 +412,7 @@ kinds of SQL compiler classes will be named, such as ``SQLCompiler`` or more specific to the "stringification" use case but describes the general background as well. -Normally, a Core SQL construct or ORM :class:`.Query` object can be stringified +Normally, a Core SQL construct or ORM :class:`_query.Query` object can be stringified directly, such as when we use ``print()``:: >>> from sqlalchemy import column @@ -446,15 +446,15 @@ to turn into a string, such as the PostgreSQL In order to stringify constructs that are specific to particular backend, -the :meth:`.ClauseElement.compile` method must be used, passing either an -:class:`.Engine` or a :class:`.Dialect` object which will invoke the correct +the :meth:`_expression.ClauseElement.compile` method must be used, passing either an +:class:`_engine.Engine` or a :class:`.Dialect` object which will invoke the correct compiler. Below we use a PostgreSQL dialect:: >>> from sqlalchemy.dialects import postgresql >>> print(insert_stmt.compile(dialect=postgresql.dialect())) INSERT INTO my_table (x) VALUES (%(x)s) ON CONFLICT (y) DO NOTHING -For an ORM :class:`.Query` object, the statement can be accessed using the +For an ORM :class:`_query.Query` object, the statement can be accessed using the :attr:`~.orm.query.Query.statement` accessor:: statement = query.statement @@ -486,9 +486,9 @@ declarative such as:: ) Above, the ``cprop`` attribute is used inline before it has been mapped, -however this ``cprop`` attribute is not a :class:`.Column`, +however this ``cprop`` attribute is not a :class:`_schema.Column`, it's a :class:`.ColumnProperty`, which is an interim object and therefore -does not have the full functionality of either the :class:`.Column` object +does not have the full functionality of either the :class:`_schema.Column` object or the :class:`.InstrumentedAttribute` object that will be mapped onto the ``Bar`` class once the declarative process is complete. @@ -498,7 +498,7 @@ open-ended comparison context as illustrated above, since it has no Python ``__eq__()`` method that would allow it to interpret the comparison to the number "5" as a SQL expression and not a regular Python comparison. -The solution is to access the :class:`.Column` directly using the +The solution is to access the :class:`_schema.Column` directly using the :attr:`.ColumnProperty.expression` attribute:: class Bar(Base): @@ -519,7 +519,7 @@ This Compiled object is not bound to any Engine or Connection This error refers to the concept of "bound metadata", described at :ref:`dbengine_implicit`. The issue occurs when one invokes the :meth:`.Executable.execute` method directly off of a Core expression object -that is not associated with any :class:`.Engine`:: +that is not associated with any :class:`_engine.Engine`:: metadata = MetaData() table = Table('t', metadata, Column('q', Integer)) @@ -527,19 +527,19 @@ that is not associated with any :class:`.Engine`:: stmt = select([table]) result = stmt.execute() # <--- raises -What the logic is expecting is that the :class:`.MetaData` object has -been **bound** to a :class:`.Engine`:: +What the logic is expecting is that the :class:`_schema.MetaData` object has +been **bound** to a :class:`_engine.Engine`:: engine = create_engine("mysql+pymysql://user:pass@host/db") metadata = MetaData(bind=engine) -Where above, any statement that derives from a :class:`.Table` which -in turn derives from that :class:`.MetaData` will implicitly make use of -the given :class:`.Engine` in order to invoke the statement. +Where above, any statement that derives from a :class:`_schema.Table` which +in turn derives from that :class:`_schema.MetaData` will implicitly make use of +the given :class:`_engine.Engine` in order to invoke the statement. Note that the concept of bound metadata is a **legacy pattern** and in most cases is **highly discouraged**. The best way to invoke the statement is -to pass it to the :meth:`.Connection.execute` method of a :class:`.Connection`:: +to pass it to the :meth:`_engine.Connection.execute` method of a :class:`_engine.Connection`:: with engine.connect() as conn: result = conn.execute(stmt) @@ -628,8 +628,8 @@ Expected FROM clause, got Select. To create a FROM clause, use the .subquery() -------------------------------------------------------------------------------------- This refers to a change made as of SQLAlchemy 1.4 where a SELECT statement as generated -by a function such as :func:`~.sql.expression.select`, but also including things like unions and textual -SELECT expressions are no longer considered to be :class:`.FromClause` objects and +by a function such as :func:`_expression.select`, but also including things like unions and textual +SELECT expressions are no longer considered to be :class:`_expression.FromClause` objects and can't be placed directly in the FROM clause of another SELECT statement without them being wrapped in a :class:`.Subquery` first. This is a major conceptual change in the Core and the full rationale is discussed at :ref:`change_4617`. @@ -659,14 +659,14 @@ In previous versions of SQLAlchemy, using a SELECT inside of another SELECT would produce a parenthesized, unnamed subquery. In most cases, this form of SQL is not very useful as databases like MySQL and PostgreSQL require that subqueries in FROM clauses have named aliases, which means using the -:meth:`.SelectBase.alias` method or as of 1.4 using the -:meth:`.SelectBase.subquery` method to produce this. On other databases, it +:meth:`_expression.SelectBase.alias` method or as of 1.4 using the +:meth:`_expression.SelectBase.subquery` method to produce this. On other databases, it is still much clearer for the subquery to have a name to resolve any ambiguity on future references to column names inside the subquery. Beyond the above practical reasons, there are a lot of other SQLAlchemy-oriented reasons the change is being made. The correct form of the above two statements -therefore requires that :meth:`.SelectBase.subquery` is used:: +therefore requires that :meth:`_expression.SelectBase.subquery` is used:: subq = stmt.subquery() diff --git a/doc/build/faq/connections.rst b/doc/build/faq/connections.rst index d124d346a5..7dbeebc00e 100644 --- a/doc/build/faq/connections.rst +++ b/doc/build/faq/connections.rst @@ -16,7 +16,7 @@ How do I pool database connections? Are my connections pooled? ---------------------------------------------------------------- SQLAlchemy performs application-level connection pooling automatically -in most cases. With the exception of SQLite, a :class:`.Engine` object +in most cases. With the exception of SQLite, a :class:`_engine.Engine` object refers to a :class:`.QueuePool` as a source of connectivity. For more detail, see :ref:`engines_toplevel` and :ref:`pooling_toplevel`. @@ -81,7 +81,7 @@ connection pool, it will malfunction when checked out again. The mitigation for this issue is that the connection is **invalidated** when such a failure mode occurs so that the underlying database connection to MySQL is discarded. This invalidation occurs automatically for many known failure modes and can -also be called explicitly via the :meth:`.Connection.invalidate` method. +also be called explicitly via the :meth:`_engine.Connection.invalidate` method. There is also a second class of failure modes within this category where a context manager such as ``with session.begin_nested():`` wants to "roll back" the transaction @@ -111,13 +111,13 @@ which have been improved across SQLAlchemy versions but others which are unavoid the server receives interleaved messages and breaks the state of the connection. This scenario can occur very easily if a program uses Python's "multiprocessing" - module and makes use of an :class:`.Engine` that was created in the parent + module and makes use of an :class:`_engine.Engine` that was created in the parent process. It's common that "multiprocessing" is in use when using tools like - Celery. The correct approach should be either that a new :class:`.Engine` - is produced when a child process first starts, discarding any :class:`.Engine` - that came down from the parent process; or, the :class:`.Engine` that's inherited + Celery. The correct approach should be either that a new :class:`_engine.Engine` + is produced when a child process first starts, discarding any :class:`_engine.Engine` + that came down from the parent process; or, the :class:`_engine.Engine` that's inherited from the parent process can have it's internal pool of connections disposed by - calling :meth:`.Engine.dispose`. + calling :meth:`_engine.Engine.dispose`. * **Greenlet Monkeypatching w/ Exits** - When using a library like gevent or eventlet that monkeypatches the Python networking API, libraries like PyMySQL are now @@ -206,8 +206,8 @@ How do I get at the raw DBAPI connection when using an Engine? -------------------------------------------------------------- With a regular SA engine-level Connection, you can get at a pool-proxied -version of the DBAPI connection via the :attr:`.Connection.connection` attribute on -:class:`.Connection`, and for the really-real DBAPI connection you can call the +version of the DBAPI connection via the :attr:`_engine.Connection.connection` attribute on +:class:`_engine.Connection`, and for the really-real DBAPI connection you can call the :attr:`.ConnectionFairy.connection` attribute on that - but there should never be any need to access the non-pool-proxied DBAPI connection, as all methods are proxied through:: @@ -220,10 +220,10 @@ You must ensure that you revert any isolation level settings or other operation-specific settings on the connection back to normal before returning it to the pool. -As an alternative to reverting settings, you can call the :meth:`.Connection.detach` method on -either :class:`.Connection` or the proxied connection, which will de-associate +As an alternative to reverting settings, you can call the :meth:`_engine.Connection.detach` method on +either :class:`_engine.Connection` or the proxied connection, which will de-associate the connection from the pool such that it will be closed and discarded -when :meth:`.Connection.close` is called:: +when :meth:`_engine.Connection.close` is called:: conn = engine.connect() conn.detach() # detaches the DBAPI connection from the connection pool @@ -239,21 +239,21 @@ the issues that arise here range from non-working connections to socket connecti are used by multiple processes concurrently, leading to broken messaging (the latter case is typically the most common). -The SQLAlchemy :class:`.Engine` object refers to a connection pool of existing +The SQLAlchemy :class:`_engine.Engine` object refers to a connection pool of existing database connections. So when this object is replicated to a child process, the goal is to ensure that no database connections are carried over. There are three general approaches to this: 1. Disable pooling using :class:`.NullPool`. This is the most simplistic, - one shot system that prevents the :class:`.Engine` from using any connection + one shot system that prevents the :class:`_engine.Engine` from using any connection more than once. -2. Call :meth:`.Engine.dispose` on any given :class:`.Engine` as soon one is +2. Call :meth:`_engine.Engine.dispose` on any given :class:`_engine.Engine` as soon one is within the new process. In Python multiprocessing, constructs such as ``multiprocessing.Pool`` include "initializer" hooks which are a place that this can be performed; otherwise at the top of where ``os.fork()`` or where the ``Process`` object begins the child fork, a single call - to :meth:`.Engine.dispose` will ensure any remaining connections are flushed. + to :meth:`_engine.Engine.dispose` will ensure any remaining connections are flushed. 3. An event handler can be applied to the connection pool that tests for connections being shared across process boundaries, and invalidates them. This looks like @@ -294,17 +294,17 @@ are three general approaches to this: (connection_record.info['pid'], pid) ) - These events are applied to an :class:`.Engine` as soon as its created:: + These events are applied to an :class:`_engine.Engine` as soon as its created:: engine = create_engine("...") add_engine_pidguard(engine) -The above strategies will accommodate the case of an :class:`.Engine` +The above strategies will accommodate the case of an :class:`_engine.Engine` being shared among processes. However, for the case of a transaction-active -:class:`.Session` or :class:`.Connection` being shared, there's no automatic +:class:`.Session` or :class:`_engine.Connection` being shared, there's no automatic fix for this; an application needs to ensure a new child process only -initiate new :class:`.Connection` objects and transactions, as well as ORM +initiate new :class:`_engine.Connection` objects and transactions, as well as ORM :class:`.Session` objects. For a :class:`.Session` object, technically this is only needed if the session is currently transaction-bound, however the scope of a single :class:`.Session` is in any case intended to be diff --git a/doc/build/faq/metadata_schema.rst b/doc/build/faq/metadata_schema.rst index 94cbb17871..b0cc3a5bad 100644 --- a/doc/build/faq/metadata_schema.rst +++ b/doc/build/faq/metadata_schema.rst @@ -28,7 +28,7 @@ result object above also maintains a link to this connection. If the result object is closed or all rows are exhausted. The call to ``mytable.drop(engine)`` attempts to emit DROP TABLE on a second -connection procured from the :class:`.Engine` which will lock. +connection procured from the :class:`_engine.Engine` which will lock. The solution is to close out all connections before emitting DROP TABLE:: @@ -58,7 +58,7 @@ or SQLAlchemy-Migrate; see :ref:`schema_migrations` for discussion on this. How can I sort Table objects in order of their dependency? ========================================================== -This is available via the :attr:`.MetaData.sorted_tables` function:: +This is available via the :attr:`_schema.MetaData.sorted_tables` function:: metadata = MetaData() # ... add Table objects to metadata @@ -82,7 +82,7 @@ To get the string specific to a certain engine:: print(CreateTable(mytable).compile(engine)) -There's also a special form of :class:`.Engine` available via +There's also a special form of :class:`_engine.Engine` available via :func:`.create_mock_engine` that allows one to dump an entire metadata creation sequence as a string, using this recipe:: @@ -99,7 +99,7 @@ an "offline" SQL generation mode that renders database migrations as SQL scripts How can I subclass Table/Column to provide certain behaviors/configurations? ============================================================================ -:class:`.Table` and :class:`.Column` are not good targets for direct subclassing. +:class:`_schema.Table` and :class:`_schema.Column` are not good targets for direct subclassing. However, there are simple ways to get on-construction behaviors using creation functions, and behaviors related to the linkages between schema objects such as constraint conventions or naming conventions using attachment events. diff --git a/doc/build/faq/ormconfiguration.rst b/doc/build/faq/ormconfiguration.rst index be84a421f1..e4463d7fdb 100644 --- a/doc/build/faq/ormconfiguration.rst +++ b/doc/build/faq/ormconfiguration.rst @@ -34,8 +34,8 @@ and is also key to the most common (and not-so-common) patterns of ORM usage. .. note:: It's important to note that we're only talking about the SQLAlchemy ORM; an - application which builds on Core and deals only with :class:`.Table` objects, - :func:`~.sql.expression.select` constructs and the like, **does not** need any primary key + application which builds on Core and deals only with :class:`_schema.Table` objects, + :func:`_expression.select` constructs and the like, **does not** need any primary key to be present on or associated with a table in any way (though again, in SQL, all tables should really have some kind of primary key, lest you need to actually update or delete specific rows). @@ -80,10 +80,10 @@ Column-based attributes can be given any name desired in the mapping. See How do I get a list of all columns, relationships, mapped attributes, etc. given a mapped class? ------------------------------------------------------------------------------------------------- -This information is all available from the :class:`.Mapper` object. +This information is all available from the :class:`_orm.Mapper` object. -To get at the :class:`.Mapper` for a particular mapped class, call the -:func:`.inspect` function on it:: +To get at the :class:`_orm.Mapper` for a particular mapped class, call the +:func:`_sa.inspect` function on it:: from sqlalchemy import inspect @@ -92,27 +92,27 @@ To get at the :class:`.Mapper` for a particular mapped class, call the From there, all information about the class can be accessed through properties such as: -* :attr:`.Mapper.attrs` - a namespace of all mapped attributes. The attributes +* :attr:`_orm.Mapper.attrs` - a namespace of all mapped attributes. The attributes themselves are instances of :class:`.MapperProperty`, which contain additional attributes that can lead to the mapped SQL expression or column, if applicable. -* :attr:`.Mapper.column_attrs` - the mapped attribute namespace +* :attr:`_orm.Mapper.column_attrs` - the mapped attribute namespace limited to column and SQL expression attributes. You might want to use - :attr:`.Mapper.columns` to get at the :class:`.Column` objects directly. + :attr:`_orm.Mapper.columns` to get at the :class:`_schema.Column` objects directly. -* :attr:`.Mapper.relationships` - namespace of all :class:`.RelationshipProperty` attributes. +* :attr:`_orm.Mapper.relationships` - namespace of all :class:`.RelationshipProperty` attributes. -* :attr:`.Mapper.all_orm_descriptors` - namespace of all mapped attributes, plus user-defined +* :attr:`_orm.Mapper.all_orm_descriptors` - namespace of all mapped attributes, plus user-defined attributes defined using systems such as :class:`.hybrid_property`, :class:`.AssociationProxy` and others. -* :attr:`.Mapper.columns` - A namespace of :class:`.Column` objects and other named +* :attr:`_orm.Mapper.columns` - A namespace of :class:`_schema.Column` objects and other named SQL expressions associated with the mapping. -* :attr:`.Mapper.mapped_table` - The :class:`.Table` or other selectable to which +* :attr:`_orm.Mapper.mapped_table` - The :class:`_schema.Table` or other selectable to which this mapper is mapped. -* :attr:`.Mapper.local_table` - The :class:`.Table` that is "local" to this mapper; - this differs from :attr:`.Mapper.mapped_table` in the case of a mapper mapped +* :attr:`_orm.Mapper.local_table` - The :class:`_schema.Table` that is "local" to this mapper; + this differs from :attr:`_orm.Mapper.mapped_table` in the case of a mapper mapped using inheritance to a composed selectable. .. _faq_combining_columns: @@ -199,7 +199,7 @@ Are you doing this?:: foo = relationship("Dest", primaryjoin=and_("MyClass.id==Dest.foo_id", "MyClass.foo==Dest.bar")) -That's an ``and_()`` of two string expressions, which SQLAlchemy cannot apply any mapping towards. Declarative allows :func:`.relationship` arguments to be specified as strings, which are converted into expression objects using ``eval()``. But this doesn't occur inside of an ``and_()`` expression - it's a special operation declarative applies only to the *entirety* of what's passed to primaryjoin or other arguments as a string:: +That's an ``and_()`` of two string expressions, which SQLAlchemy cannot apply any mapping towards. Declarative allows :func:`_orm.relationship` arguments to be specified as strings, which are converted into expression objects using ``eval()``. But this doesn't occur inside of an ``and_()`` expression - it's a special operation declarative applies only to the *entirety* of what's passed to primaryjoin or other arguments as a string:: class MyClass(Base): # .... @@ -245,16 +245,16 @@ all queries. The consequence of this is that any query that limits rows using ``LIMIT`` or ``OFFSET`` should **always** specify an ``ORDER BY``. Otherwise, it is not deterministic which rows will actually be returned. -When we use a SQLAlchemy method like :meth:`.Query.first`, we are in fact +When we use a SQLAlchemy method like :meth:`_query.Query.first`, we are in fact applying a ``LIMIT`` of one to the query, so without an explicit ordering it is not deterministic what row we actually get back. While we may not notice this for simple queries on databases that usually returns rows in their natural -order, it becomes much more of an issue if we also use :func:`.orm.subqueryload` +order, it becomes much more of an issue if we also use :func:`_orm.subqueryload` to load related collections, and we may not be loading the collections as intended. -SQLAlchemy implements :func:`.orm.subqueryload` by issuing a separate query, +SQLAlchemy implements :func:`_orm.subqueryload` by issuing a separate query, the results of which are matched up to the results from the first query. We see two queries emitted like this: @@ -321,12 +321,12 @@ won't see that anything actually went wrong. The solution to this problem is to always specify a deterministic sort order, so that the main query always returns the same set of rows. This generally -means that you should :meth:`.Query.order_by` on a unique column on the table. +means that you should :meth:`_query.Query.order_by` on a unique column on the table. The primary key is a good choice for this:: session.query(User).options(subqueryload(User.addresses)).order_by(User.id).first() -Note that the :func:`.joinedload` eager loader strategy does not suffer from +Note that the :func:`_orm.joinedload` eager loader strategy does not suffer from the same problem because only one query is ever issued, so the load query cannot be different from the main query. Similarly, the :func:`.selectinload` eager loader strategy also does not have this issue as it links its collection diff --git a/doc/build/faq/performance.rst b/doc/build/faq/performance.rst index 65d6cc4605..745fb83e2f 100644 --- a/doc/build/faq/performance.rst +++ b/doc/build/faq/performance.rst @@ -36,7 +36,7 @@ Logging SQL will also illustrate if dozens/hundreds of queries are being issued which could be better organized into much fewer queries. When using the SQLAlchemy ORM, the "eager loading" feature is provided to partially (:func:`.contains_eager()`) or fully -(:func:`.joinedload()`, :func:`.subqueryload()`) +(:func:`_orm.joinedload()`, :func:`.subqueryload()`) automate this activity, but without the ORM "eager loading" typically means to use joins so that results across multiple tables can be loaded in one result set instead of multiplying numbers @@ -160,7 +160,7 @@ If on the other hand you see many thousands of calls related to fetching rows, or very long calls to ``fetchall()``, it may mean your query is returning more rows than expected, or that the fetching of rows itself is slow. The ORM itself typically uses ``fetchall()`` to fetch -rows (or ``fetchmany()`` if the :meth:`.Query.yield_per` option is used). +rows (or ``fetchmany()`` if the :meth:`_query.Query.yield_per` option is used). An inordinately large number of rows would be indicated by a very slow call to ``fetchall()`` at the DBAPI level:: @@ -171,7 +171,7 @@ An unexpectedly large number of rows, even if the ultimate result doesn't seem to have many rows, can be the result of a cartesian product - when multiple sets of rows are combined together without appropriately joining the tables together. It's often easy to produce this behavior with SQLAlchemy Core or -ORM query if the wrong :class:`.Column` objects are used in a complex query, +ORM query if the wrong :class:`_schema.Column` objects are used in a complex query, pulling in additional FROM clauses that are unexpected. On the other hand, a fast call to ``fetchall()`` at the DBAPI level, but then diff --git a/doc/build/faq/sessions.rst b/doc/build/faq/sessions.rst index 6fdaa2ceb9..76cabf7653 100644 --- a/doc/build/faq/sessions.rst +++ b/doc/build/faq/sessions.rst @@ -67,7 +67,7 @@ Three ways, from most common to least: 3. We can run whole queries while setting them to definitely overwrite already-loaded objects as they read rows by using - :meth:`.Query.populate_existing`. + :meth:`_query.Query.populate_existing`. But remember, **the ORM cannot see changes in rows if our isolation level is repeatable read or higher, unless we start a new transaction**. @@ -230,7 +230,7 @@ See the recipe at `FilteredQuery >> q.count() 2 -However, if we run :meth:`.Query.all` or iterate over the query, we get back +However, if we run :meth:`_query.Query.all` or iterate over the query, we get back **one element**:: >>> q.all() [User(id=5, name='jack', ...)] -This is because when the :class:`.Query` object returns full entities, they +This is because when the :class:`_query.Query` object returns full entities, they are **deduplicated**. This does not occur if we instead request individual columns back:: >>> session.query(User.id, User.name).outerjoin(User.addresses).filter(User.name == 'jack').all() [(5, 'jack'), (5, 'jack')] -There are two main reasons the :class:`.Query` will deduplicate: +There are two main reasons the :class:`_query.Query` will deduplicate: * **To allow joined eager loading to work correctly** - :ref:`joined_eager_loading` works by querying rows using joins against related tables, where it then routes @@ -270,7 +270,7 @@ There are two main reasons the :class:`.Query` will deduplicate: were queried, e.g. all the ``User()`` objects whose name is ``'jack'`` which for us is one object, with the ``User.addresses`` collection eagerly loaded as was indicated either - by ``lazy='joined'`` on the :func:`.relationship` or via the :func:`.joinedload` + by ``lazy='joined'`` on the :func:`_orm.relationship` or via the :func:`_orm.joinedload` option. For consistency, the deduplication is still applied whether or not the joinedload is established, as the key philosophy behind eager loading is that these options never affect the result. @@ -282,16 +282,16 @@ There are two main reasons the :class:`.Query` will deduplicate: which must be maintained uniquely on its identity, that is, its primary key / class combination. It doesn't actually make much sense, if one is querying for ``User()`` objects, to get the same object multiple times in the list. An - ordered set would potentially be a better representation of what :class:`.Query` + ordered set would potentially be a better representation of what :class:`_query.Query` seeks to return when it returns full objects. -The issue of :class:`.Query` deduplication remains problematic, mostly for the -single reason that the :meth:`.Query.count` method is inconsistent, and the +The issue of :class:`_query.Query` deduplication remains problematic, mostly for the +single reason that the :meth:`_query.Query.count` method is inconsistent, and the current status is that joined eager loading has in recent releases been superseded first by the "subquery eager loading" strategy and more recently the "select IN eager loading" strategy, both of which are generally more appropriate for collection eager loading. As this evolution continues, -SQLAlchemy may alter this behavior on :class:`.Query`, which may also involve +SQLAlchemy may alter this behavior on :class:`_query.Query`, which may also involve new APIs in order to more directly control this behavior, and may also alter the behavior of joined eager loading in order to create a more consistent usage pattern. @@ -301,7 +301,7 @@ I've created a mapping against an Outer Join, and while the query returns rows, ------------------------------------------------------------------------------------------------------------------ Rows returned by an outer join may contain NULL for part of the primary key, -as the primary key is the composite of both tables. The :class:`.Query` object ignores incoming rows +as the primary key is the composite of both tables. The :class:`_query.Query` object ignores incoming rows that don't have an acceptable primary key. Based on the setting of the ``allow_partial_pks`` flag on :func:`.mapper`, a primary key is accepted if the value has at least one non-NULL value, or alternatively if the value has no NULL values. See ``allow_partial_pks`` @@ -322,7 +322,7 @@ Query has no ``__len__()``, why not? The Python ``__len__()`` magic method applied to an object allows the ``len()`` builtin to be used to determine the length of the collection. It's intuitive -that a SQL query object would link ``__len__()`` to the :meth:`.Query.count` +that a SQL query object would link ``__len__()`` to the :meth:`_query.Query.count` method, which emits a `SELECT COUNT`. The reason this is not possible is because evaluating the query as a list would incur two SQL calls instead of one:: @@ -348,7 +348,7 @@ How Do I use Textual SQL with ORM Queries? See: -* :ref:`orm_tutorial_literal_sql` - Ad-hoc textual blocks with :class:`.Query` +* :ref:`orm_tutorial_literal_sql` - Ad-hoc textual blocks with :class:`_query.Query` * :ref:`session_sql_expressions` - Using :class:`.Session` with textual SQL directly. @@ -390,7 +390,7 @@ set ``o.foo`` is to do just that - set it!:: Manipulation of foreign key attributes is of course entirely legal. However, setting a foreign-key attribute to a new value currently does not trigger -an "expire" event of the :func:`.relationship` in which it's involved. This means +an "expire" event of the :func:`_orm.relationship` in which it's involved. This means that for the following sequence:: o = Session.query(SomeClass).first() @@ -450,7 +450,7 @@ have meaning until the row is inserted; otherwise there is no row yet:: .. topic:: Attribute loading for non-persistent objects One variant on the "pending" behavior above is if we use the flag - ``load_on_pending`` on :func:`.relationship`. When this flag is set, the + ``load_on_pending`` on :func:`_orm.relationship`. When this flag is set, the lazy loader will emit for ``new_obj.foo`` before the INSERT proceeds; another variant of this is to use the :meth:`.Session.enable_relationship_loading` method, which can "attach" an object to a :class:`.Session` in such a way that @@ -470,7 +470,7 @@ How do I walk all objects that are related to a given object? ------------------------------------------------------------- An object that has other objects related to it will correspond to the -:func:`.relationship` constructs set up between mappers. This code fragment will +:func:`_orm.relationship` constructs set up between mappers. This code fragment will iterate all the objects, correcting for cycles as well:: from sqlalchemy import inspect diff --git a/doc/build/faq/sqlexpressions.rst b/doc/build/faq/sqlexpressions.rst index f2d045d0cc..7f6c8e7cad 100644 --- a/doc/build/faq/sqlexpressions.rst +++ b/doc/build/faq/sqlexpressions.rst @@ -12,7 +12,7 @@ How do I render SQL expressions as strings, possibly with bound parameters inlin ------------------------------------------------------------------------------------ The "stringification" of a SQLAlchemy Core statement object or -expression fragment, as well as that of an ORM :class:`.Query` object, +expression fragment, as well as that of an ORM :class:`_query.Query` object, in the majority of simple cases is as simple as using the ``str()`` builtin function, as below when use it with the ``print`` function (note the Python ``print`` function also calls ``str()`` automatically @@ -26,8 +26,8 @@ if we don't use it explicitly):: FROM my_table The ``str()`` builtin, or an equivalent, can be invoked on ORM -:class:`.Query` object as well as any statement such as that of -:func:`~.sql.expression.select`, :func:`~.sql.expression.insert` etc. and also any expression fragment, such +:class:`_query.Query` object as well as any statement such as that of +:func:`_expression.select`, :func:`_expression.insert` etc. and also any expression fragment, such as:: >>> from sqlalchemy import column @@ -44,7 +44,7 @@ In these cases, we might get a stringified statement that is not in the correct syntax for the database we are targeting, or the operation may raise a :class:`.UnsupportedCompilationError` exception. In these cases, it is necessary that we stringify the statement using the -:meth:`.ClauseElement.compile` method, while passing along an :class:`.Engine` +:meth:`_expression.ClauseElement.compile` method, while passing along an :class:`_engine.Engine` or :class:`.Dialect` object that represents the target database. Such as below, if we have a MySQL database engine, we can stringify a statement in terms of the MySQL dialect:: @@ -54,7 +54,7 @@ terms of the MySQL dialect:: engine = create_engine("mysql+pymysql://scott:tiger@localhost/test") print(statement.compile(engine)) -More directly, without building up an :class:`.Engine` object we can +More directly, without building up an :class:`_engine.Engine` object we can instantiate a :class:`.Dialect` object directly, as below where we use a PostgreSQL dialect:: @@ -62,7 +62,7 @@ use a PostgreSQL dialect:: print(statement.compile(dialect=postgresql.dialect())) When given an ORM :class:`~.orm.query.Query` object, in order to get at the -:meth:`.ClauseElement.compile` +:meth:`_expression.ClauseElement.compile` method we only need access the :attr:`~.orm.query.Query.statement` accessor first:: @@ -160,7 +160,7 @@ SQLAlchemy operator is currently 15:: We can also usually force parenthesization around a binary expression (e.g. an expression that has left/right operands and an operator) using the -:meth:`.ColumnElement.self_group` method:: +:meth:`_expression.ColumnElement.self_group` method:: >>> print((column('q1') + column('q2')).self_group().op('->')(column('p'))) (q1 + q2) -> p diff --git a/doc/build/glossary.rst b/doc/build/glossary.rst index 83bf0b43ae..46d09b8e10 100644 --- a/doc/build/glossary.rst +++ b/doc/build/glossary.rst @@ -23,22 +23,22 @@ Glossary A term used in SQLAlchemy to describe a SQL construct that represents a collection of rows. It's largely similar to the concept of a "relation" in :term:`relational algebra`. In SQLAlchemy, objects - that subclass the :class:`.Selectable` class are considered to be + that subclass the :class:`expression.Selectable` class are considered to be usable as "selectables" when using SQLAlchemy Core. The two most - common constructs are that of the :class:`.Table` and that of the - :class:`.Select` statement. + common constructs are that of the :class:`_schema.Table` and that of the + :class:`_expression.Select` statement. annotations Annotations are a concept used internally by SQLAlchemy in order to store - additional information along with :class:`.ClauseElement` objects. A Python + additional information along with :class:`_expression.ClauseElement` objects. A Python dictionary is associated with a copy of the object, which contains key/value pairs significant to various internal systems, mostly within the ORM:: some_column = Column('some_column', Integer) some_column_annotated = some_column._annotate({"entity": User}) - The annotation system differs from the public dictionary :attr:`.Column.info` - in that the above annotation operation creates a *copy* of the new :class:`.Column`, + The annotation system differs from the public dictionary :attr:`_schema.Column.info` + in that the above annotation operation creates a *copy* of the new :class:`_schema.Column`, rather than considering all annotation values to be part of a single unit. The ORM creates copies of expression objects in order to apply annotations that are specific to their context, such as to differentiate @@ -90,7 +90,7 @@ Glossary The ``MyClass`` class will be :term:`mapped` when its definition is complete, at which point the ``id`` and ``data`` attributes, - starting out as :class:`.Column` objects, will be replaced + starting out as :class:`_schema.Column` objects, will be replaced by the :term:`instrumentation` system with instances of :class:`.InstrumentedAttribute`, which are descriptors that provide the above mentioned ``__get__()``, ``__set__()`` and @@ -145,7 +145,7 @@ Glossary The term "metadata" generally refers to "data that describes data"; data that itself represents the format and/or structure of some other kind of data. In SQLAlchemy, the term "metadata" typically refers to - the :class:`.MetaData` construct, which is a collection of information + the :class:`_schema.MetaData` construct, which is a collection of information about the tables, columns, constraints, and other :term:`DDL` objects that may exist in a particular database. @@ -189,9 +189,9 @@ Glossary A term used in SQLAlchemy to describe how an ORM persistence action that takes place on a particular object would extend into other objects which are directly associated with that object. In SQLAlchemy, these - object associations are configured using the :func:`.relationship` - construct. :func:`.relationship` contains a parameter called - :paramref:`.relationship.cascade` which provides options on how certain + object associations are configured using the :func:`_orm.relationship` + construct. :func:`_orm.relationship` contains a parameter called + :paramref:`_orm.relationship.cascade` which provides options on how certain persistence operations may cascade. The term "cascades" as well as the general architecture of this system @@ -294,7 +294,7 @@ Glossary an attribute that is populated with its database-side value at the same time as when the object itself is loaded from the database. In SQLAlchemy, "eager loading" usually refers to related collections - of objects that are mapped using the :func:`.relationship` construct. + of objects that are mapped using the :func:`_orm.relationship` construct. Eager loading is the opposite of :term:`lazy loading`. .. seealso:: @@ -305,7 +305,7 @@ Glossary mapping mapped We say a class is "mapped" when it has been passed through the - :func:`.orm.mapper` function. This process associates the + :func:`_orm.mapper` function. This process associates the class with a database table or other :term:`selectable` construct, so that instances of it can be persisted using a :class:`.Session` as well as loaded using a @@ -356,12 +356,12 @@ Glossary additional state added to the object. The two SQLAlchemy objects that make the most use of - method chaining are the :class:`~.expression.Select` + method chaining are the :class:`_expression.Select` object and the :class:`.orm.query.Query` object. - For example, a :class:`~.expression.Select` object can + For example, a :class:`_expression.Select` object can be assigned two expressions to its WHERE clause as well - as an ORDER BY clause by calling upon the :meth:`~.Select.where` - and :meth:`~.Select.order_by` methods:: + as an ORDER BY clause by calling upon the :meth:`_expression.Select.where` + and :meth:`_expression.Select.order_by` methods:: stmt = select([user.c.name]).\ where(user.c.id > 5).\ @@ -369,7 +369,7 @@ Glossary order_by(user.c.name) Each method call above returns a copy of the original - :class:`~.expression.Select` object with additional qualifiers + :class:`_expression.Select` object with additional qualifiers added. .. seealso:: diff --git a/doc/build/orm/backref.rst b/doc/build/orm/backref.rst index b221e75e78..80b395930b 100644 --- a/doc/build/orm/backref.rst +++ b/doc/build/orm/backref.rst @@ -3,7 +3,7 @@ Linking Relationships with Backref ---------------------------------- -The :paramref:`~.relationship.backref` keyword argument was first introduced in :ref:`ormtutorial_toplevel`, and has been +The :paramref:`_orm.relationship.backref` keyword argument was first introduced in :ref:`ormtutorial_toplevel`, and has been mentioned throughout many of the examples here. What does it actually do ? Let's start with the canonical ``User`` and ``Address`` scenario:: @@ -30,8 +30,8 @@ The above configuration establishes a collection of ``Address`` objects on ``Use ``User.addresses``. It also establishes a ``.user`` attribute on ``Address`` which will refer to the parent ``User`` object. -In fact, the :paramref:`~.relationship.backref` keyword is only a common shortcut for placing a second -:func:`.relationship` onto the ``Address`` mapping, including the establishment +In fact, the :paramref:`_orm.relationship.backref` keyword is only a common shortcut for placing a second +:func:`_orm.relationship` onto the ``Address`` mapping, including the establishment of an event listener on both sides which will mirror attribute operations in both directions. The above configuration is equivalent to:: @@ -57,7 +57,7 @@ in both directions. The above configuration is equivalent to:: user = relationship("User", back_populates="addresses") Above, we add a ``.user`` relationship to ``Address`` explicitly. On -both relationships, the :paramref:`~.relationship.back_populates` directive tells each relationship +both relationships, the :paramref:`_orm.relationship.back_populates` directive tells each relationship about the other one, indicating that they should establish "bidirectional" behavior between each other. The primary effect of this configuration is that the relationship adds event handlers to both attributes @@ -96,27 +96,27 @@ The manipulation of the ``.addresses`` collection and the ``.user`` attribute occurs entirely in Python without any interaction with the SQL database. Without this behavior, the proper state would be apparent on both sides once the data has been flushed to the database, and later reloaded after a commit or -expiration operation occurs. The :paramref:`~.relationship.backref`/:paramref:`~.relationship.back_populates` behavior has the advantage +expiration operation occurs. The :paramref:`_orm.relationship.backref`/:paramref:`_orm.relationship.back_populates` behavior has the advantage that common bidirectional operations can reflect the correct state without requiring a database round trip. -Remember, when the :paramref:`~.relationship.backref` keyword is used on a single relationship, it's +Remember, when the :paramref:`_orm.relationship.backref` keyword is used on a single relationship, it's exactly the same as if the above two relationships were created individually -using :paramref:`~.relationship.back_populates` on each. +using :paramref:`_orm.relationship.back_populates` on each. Backref Arguments ~~~~~~~~~~~~~~~~~ -We've established that the :paramref:`~.relationship.backref` keyword is merely a shortcut for building -two individual :func:`.relationship` constructs that refer to each other. Part of +We've established that the :paramref:`_orm.relationship.backref` keyword is merely a shortcut for building +two individual :func:`_orm.relationship` constructs that refer to each other. Part of the behavior of this shortcut is that certain configurational arguments applied to -the :func:`.relationship` +the :func:`_orm.relationship` will also be applied to the other direction - namely those arguments that describe the relationship at a schema level, and are unlikely to be different in the reverse direction. The usual case -here is a many-to-many :func:`.relationship` that has a :paramref:`~.relationship.secondary` argument, -or a one-to-many or many-to-one which has a :paramref:`~.relationship.primaryjoin` argument (the -:paramref:`~.relationship.primaryjoin` argument is discussed in :ref:`relationship_primaryjoin`). Such +here is a many-to-many :func:`_orm.relationship` that has a :paramref:`_orm.relationship.secondary` argument, +or a one-to-many or many-to-one which has a :paramref:`_orm.relationship.primaryjoin` argument (the +:paramref:`_orm.relationship.primaryjoin` argument is discussed in :ref:`relationship_primaryjoin`). Such as if we limited the list of ``Address`` objects to those which start with "tony":: from sqlalchemy import Integer, ForeignKey, String, Column @@ -154,18 +154,18 @@ of the relationship have this join condition applied:: This reuse of arguments should pretty much do the "right thing" - it uses only arguments that are applicable, and in the case of a many-to- many relationship, will reverse the usage of -:paramref:`~.relationship.primaryjoin` and -:paramref:`~.relationship.secondaryjoin` to correspond to the other +:paramref:`_orm.relationship.primaryjoin` and +:paramref:`_orm.relationship.secondaryjoin` to correspond to the other direction (see the example in :ref:`self_referential_many_to_many` for this). It's very often the case however that we'd like to specify arguments that are specific to just the side where we happened to place the -"backref". This includes :func:`.relationship` arguments like -:paramref:`~.relationship.lazy`, -:paramref:`~.relationship.remote_side`, -:paramref:`~.relationship.cascade` and -:paramref:`~.relationship.cascade_backrefs`. For this case we use +"backref". This includes :func:`_orm.relationship` arguments like +:paramref:`_orm.relationship.lazy`, +:paramref:`_orm.relationship.remote_side`, +:paramref:`_orm.relationship.cascade` and +:paramref:`_orm.relationship.cascade_backrefs`. For this case we use the :func:`.backref` function in place of a string:: # @@ -183,7 +183,7 @@ Where above, we placed a ``lazy="joined"`` directive only on the ``Address.user` side, indicating that when a query against ``Address`` is made, a join to the ``User`` entity should be made automatically which will populate the ``.user`` attribute of each returned ``Address``. The :func:`.backref` function formatted the arguments we gave -it into a form that is interpreted by the receiving :func:`.relationship` as additional +it into a form that is interpreted by the receiving :func:`_orm.relationship` as additional arguments to be applied to the new relationship it creates. Setting cascade for backrefs @@ -221,7 +221,7 @@ operation which indicates that this ``Address`` should be placed into the :class:`.Session` as a :term:`pending` object. Since this behavior has been identified as counter-intuitive to most people, -it can be disabled by setting :paramref:`~.relationship.cascade_backrefs` +it can be disabled by setting :paramref:`_orm.relationship.cascade_backrefs` to False, as in:: @@ -243,7 +243,7 @@ One Way Backrefs An unusual case is that of the "one way backref". This is where the "back-populating" behavior of the backref is only desirable in one direction. An example of this is a collection which contains a -filtering :paramref:`~.relationship.primaryjoin` condition. We'd +filtering :paramref:`_orm.relationship.primaryjoin` condition. We'd like to append items to this collection as needed, and have them populate the "parent" object on the incoming object. However, we'd also like to have items that are not part of the collection, but still @@ -251,7 +251,7 @@ have the same "parent" association - these items should never be in the collection. Taking our previous example, where we established a -:paramref:`~.relationship.primaryjoin` that limited the collection +:paramref:`_orm.relationship.primaryjoin` that limited the collection only to ``Address`` objects whose email address started with the word ``tony``, the usual backref behavior is that all items populate in both directions. We wouldn't want this behavior for a case like the @@ -268,8 +268,8 @@ is present in the ``addresses`` collection of ``u1``. After these objects are the transaction committed and their attributes expired for a re-load, the ``addresses`` collection will hit the database on next access and no longer have this ``Address`` object present, due to the filtering condition. But we can do away with this unwanted side -of the "backref" behavior on the Python side by using two separate :func:`.relationship` constructs, -placing :paramref:`~.relationship.back_populates` only on one side:: +of the "backref" behavior on the Python side by using two separate :func:`_orm.relationship` constructs, +placing :paramref:`_orm.relationship.back_populates` only on one side:: from sqlalchemy import Integer, ForeignKey, String, Column from sqlalchemy.ext.declarative import declarative_base @@ -312,7 +312,7 @@ will not append the ``Address`` object to the collection:: False Of course, we've disabled some of the usefulness of -:paramref:`~.relationship.backref` here, in that when we do append an +:paramref:`_orm.relationship.backref` here, in that when we do append an ``Address`` that corresponds to the criteria of ``email.startswith('tony')``, it won't show up in the ``User.addresses`` collection until the session is flushed, and the diff --git a/doc/build/orm/basic_relationships.rst b/doc/build/orm/basic_relationships.rst index 0f098d4cd6..a837dd6317 100644 --- a/doc/build/orm/basic_relationships.rst +++ b/doc/build/orm/basic_relationships.rst @@ -18,7 +18,7 @@ One To Many ~~~~~~~~~~~ A one to many relationship places a foreign key on the child table referencing -the parent. :func:`.relationship` is then specified on the parent, as referencing +the parent. :func:`_orm.relationship` is then specified on the parent, as referencing a collection of items represented by the child:: class Parent(Base): @@ -32,8 +32,8 @@ a collection of items represented by the child:: parent_id = Column(Integer, ForeignKey('parent.id')) To establish a bidirectional relationship in one-to-many, where the "reverse" -side is a many to one, specify an additional :func:`.relationship` and connect -the two using the :paramref:`.relationship.back_populates` parameter:: +side is a many to one, specify an additional :func:`_orm.relationship` and connect +the two using the :paramref:`_orm.relationship.back_populates` parameter:: class Parent(Base): __tablename__ = 'parent' @@ -48,9 +48,9 @@ the two using the :paramref:`.relationship.back_populates` parameter:: ``Child`` will get a ``parent`` attribute with many-to-one semantics. -Alternatively, the :paramref:`~.relationship.backref` option may be used -on a single :func:`.relationship` instead of using -:paramref:`~.relationship.back_populates`:: +Alternatively, the :paramref:`_orm.relationship.backref` option may be used +on a single :func:`_orm.relationship` instead of using +:paramref:`_orm.relationship.back_populates`:: class Parent(Base): __tablename__ = 'parent' @@ -62,7 +62,7 @@ Many To One ~~~~~~~~~~~ Many to one places a foreign key in the parent table referencing the child. -:func:`.relationship` is declared on the parent, where a new scalar-holding +:func:`_orm.relationship` is declared on the parent, where a new scalar-holding attribute will be created:: class Parent(Base): @@ -75,8 +75,8 @@ attribute will be created:: __tablename__ = 'child' id = Column(Integer, primary_key=True) -Bidirectional behavior is achieved by adding a second :func:`.relationship` -and applying the :paramref:`.relationship.back_populates` parameter +Bidirectional behavior is achieved by adding a second :func:`_orm.relationship` +and applying the :paramref:`_orm.relationship.back_populates` parameter in both directions:: class Parent(Base): @@ -90,8 +90,8 @@ in both directions:: id = Column(Integer, primary_key=True) parents = relationship("Parent", back_populates="child") -Alternatively, the :paramref:`~.relationship.backref` parameter -may be applied to a single :func:`.relationship`, such as ``Parent.child``:: +Alternatively, the :paramref:`_orm.relationship.backref` parameter +may be applied to a single :func:`_orm.relationship`, such as ``Parent.child``:: class Parent(Base): __tablename__ = 'parent' @@ -105,7 +105,7 @@ One To One ~~~~~~~~~~ One To One is essentially a bidirectional relationship with a scalar -attribute on both sides. To achieve this, the :paramref:`~.relationship.uselist` flag indicates +attribute on both sides. To achieve this, the :paramref:`_orm.relationship.uselist` flag indicates the placement of a scalar attribute instead of a collection on the "many" side of the relationship. To convert one-to-many into one-to-one:: @@ -133,8 +133,8 @@ Or for many-to-one:: id = Column(Integer, primary_key=True) parent = relationship("Parent", back_populates="child", uselist=False) -As always, the :paramref:`.relationship.backref` and :func:`.backref` functions -may be used in lieu of the :paramref:`.relationship.back_populates` approach; +As always, the :paramref:`_orm.relationship.backref` and :func:`.backref` functions +may be used in lieu of the :paramref:`_orm.relationship.back_populates` approach; to specify ``uselist`` on a backref, use the :func:`.backref` function:: from sqlalchemy.orm import backref @@ -152,9 +152,9 @@ Many To Many ~~~~~~~~~~~~ Many to Many adds an association table between two classes. The association -table is indicated by the :paramref:`~.relationship.secondary` argument to -:func:`.relationship`. Usually, the :class:`.Table` uses the :class:`.MetaData` -object associated with the declarative base class, so that the :class:`.ForeignKey` +table is indicated by the :paramref:`_orm.relationship.secondary` argument to +:func:`_orm.relationship`. Usually, the :class:`_schema.Table` uses the :class:`_schema.MetaData` +object associated with the declarative base class, so that the :class:`_schema.ForeignKey` directives can locate the remote tables with which to link:: association_table = Table('association', Base.metadata, @@ -173,8 +173,8 @@ directives can locate the remote tables with which to link:: id = Column(Integer, primary_key=True) For a bidirectional relationship, both sides of the relationship contain a -collection. Specify using :paramref:`.relationship.back_populates`, and -for each :func:`.relationship` specify the common association table:: +collection. Specify using :paramref:`_orm.relationship.back_populates`, and +for each :func:`_orm.relationship` specify the common association table:: association_table = Table('association', Base.metadata, Column('left_id', Integer, ForeignKey('left.id')), @@ -197,9 +197,9 @@ for each :func:`.relationship` specify the common association table:: secondary=association_table, back_populates="children") -When using the :paramref:`~.relationship.backref` parameter instead of -:paramref:`.relationship.back_populates`, the backref will automatically use -the same :paramref:`~.relationship.secondary` argument for the reverse relationship:: +When using the :paramref:`_orm.relationship.backref` parameter instead of +:paramref:`_orm.relationship.back_populates`, the backref will automatically use +the same :paramref:`_orm.relationship.secondary` argument for the reverse relationship:: association_table = Table('association', Base.metadata, Column('left_id', Integer, ForeignKey('left.id')), @@ -217,7 +217,7 @@ the same :paramref:`~.relationship.secondary` argument for the reverse relations __tablename__ = 'right' id = Column(Integer, primary_key=True) -The :paramref:`~.relationship.secondary` argument of :func:`.relationship` also accepts a callable +The :paramref:`_orm.relationship.secondary` argument of :func:`_orm.relationship` also accepts a callable that returns the ultimate argument, which is evaluated only when mappers are first used. Using this, we can define the ``association_table`` at a later point, as long as it's available to the callable after all module initialization @@ -241,10 +241,10 @@ is accepted as well, matching the name of the table as stored in ``Base.metadata backref="parents") .. warning:: When passed as a Python-evaluable string, the - :paramref:`.relationship.secondary` argument is interpreted using Python's + :paramref:`_orm.relationship.secondary` argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on declarative - evaluation of :func:`.relationship` arguments. + evaluation of :func:`_orm.relationship` arguments. .. _relationships_many_to_many_deletion: @@ -252,8 +252,8 @@ is accepted as well, matching the name of the table as stored in ``Base.metadata Deleting Rows from the Many to Many Table ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -A behavior which is unique to the :paramref:`~.relationship.secondary` argument to :func:`.relationship` -is that the :class:`.Table` which is specified here is automatically subject +A behavior which is unique to the :paramref:`_orm.relationship.secondary` argument to :func:`_orm.relationship` +is that the :class:`_schema.Table` which is specified here is automatically subject to INSERT and DELETE statements, as objects are added or removed from the collection. There is **no need to delete from this table manually**. The act of removing a record from the collection will have the effect of the row being deleted on flush:: @@ -269,7 +269,7 @@ when the child object is handed directly to :meth:`.Session.delete`:: There are several possibilities here: -* If there is a :func:`.relationship` from ``Parent`` to ``Child``, but there is +* If there is a :func:`_orm.relationship` from ``Parent`` to ``Child``, but there is **not** a reverse-relationship that links a particular ``Child`` to each ``Parent``, SQLAlchemy will not have any awareness that when deleting this particular ``Child`` object, it needs to maintain the "secondary" table that links it to @@ -279,21 +279,21 @@ There are several possibilities here: the ``Child.parents`` collection to locate all ``Parent`` objects, and remove each row from the "secondary" table which establishes this link. Note that this relationship does not need to be bidirectional; SQLAlchemy is strictly - looking at every :func:`.relationship` associated with the ``Child`` object + looking at every :func:`_orm.relationship` associated with the ``Child`` object being deleted. * A higher performing option here is to use ON DELETE CASCADE directives with the foreign keys used by the database. Assuming the database supports this feature, the database itself can be made to automatically delete rows in the "secondary" table as referencing rows in "child" are deleted. SQLAlchemy can be instructed to forego actively loading in the ``Child.parents`` - collection in this case using the :paramref:`~.relationship.passive_deletes` - directive on :func:`.relationship`; see :ref:`passive_deletes` for more details + collection in this case using the :paramref:`_orm.relationship.passive_deletes` + directive on :func:`_orm.relationship`; see :ref:`passive_deletes` for more details on this. -Note again, these behaviors are *only* relevant to the :paramref:`~.relationship.secondary` option -used with :func:`.relationship`. If dealing with association tables that -are mapped explicitly and are *not* present in the :paramref:`~.relationship.secondary` option -of a relevant :func:`.relationship`, cascade rules can be used instead +Note again, these behaviors are *only* relevant to the :paramref:`_orm.relationship.secondary` option +used with :func:`_orm.relationship`. If dealing with association tables that +are mapped explicitly and are *not* present in the :paramref:`_orm.relationship.secondary` option +of a relevant :func:`_orm.relationship`, cascade rules can be used instead to automatically delete entities in reaction to a related entity being deleted - see :ref:`unitofwork_cascades` for information on this feature. @@ -306,7 +306,7 @@ Association Object The association object pattern is a variant on many-to-many: it's used when your association table contains additional columns beyond those which are foreign keys to the left and right tables. Instead of using -the :paramref:`~.relationship.secondary` argument, you map a new class +the :paramref:`_orm.relationship.secondary` argument, you map a new class directly to the association table. The left side of the relationship references the association object via one-to-many, and the association class references the right side via many-to-one. Below we illustrate @@ -331,8 +331,8 @@ is stored along with each association between ``Parent`` and __tablename__ = 'right' id = Column(Integer, primary_key=True) -As always, the bidirectional version makes use of :paramref:`.relationship.back_populates` -or :paramref:`.relationship.backref`:: +As always, the bidirectional version makes use of :paramref:`_orm.relationship.back_populates` +or :paramref:`_orm.relationship.backref`:: class Association(Base): __tablename__ = 'association' diff --git a/doc/build/orm/cascades.rst b/doc/build/orm/cascades.rst index 8886621ae9..d6b1be1873 100644 --- a/doc/build/orm/cascades.rst +++ b/doc/build/orm/cascades.rst @@ -8,7 +8,7 @@ Mappers support the concept of configurable :term:`cascade` behavior on to how operations performed on a "parent" object relative to a particular :class:`.Session` should be propagated to items referred to by that relationship (e.g. "child" objects), and is -affected by the :paramref:`.relationship.cascade` option. +affected by the :paramref:`_orm.relationship.cascade` option. The default behavior of cascade is limited to cascades of the so-called :ref:`cascade_save_update` and :ref:`cascade_merge` settings. @@ -18,7 +18,7 @@ these settings are appropriate for related objects which only exist as long as they are attached to their parent, and are otherwise deleted. Cascade behavior is configured using the -:paramref:`~.relationship.cascade` option on +:paramref:`_orm.relationship.cascade` option on :func:`~sqlalchemy.orm.relationship`:: class Order(Base): @@ -49,7 +49,7 @@ its arguments back into :func:`~sqlalchemy.orm.relationship`:: stating "The sections we have just covered can be a bit confusing. However, in practice, it all works out nicely." -The default value of :paramref:`~.relationship.cascade` is ``save-update, merge``. +The default value of :paramref:`_orm.relationship.cascade` is ``save-update, merge``. The typical alternative setting for this parameter is either ``all`` or more commonly ``all, delete-orphan``. The ``all`` symbol is a synonym for ``save-update, merge, refresh-expire, expunge, delete``, @@ -58,7 +58,7 @@ object should follow along with its parent in all cases, and be deleted once it is no longer associated with that parent. The list of available values which can be specified for -the :paramref:`~.relationship.cascade` parameter are described in the following subsections. +the :paramref:`_orm.relationship.cascade` parameter are described in the following subsections. .. _cascade_save_update: @@ -67,7 +67,7 @@ save-update ``save-update`` cascade indicates that when an object is placed into a :class:`.Session` via :meth:`.Session.add`, all the objects associated -with it via this :func:`.relationship` should also be added to that +with it via this :func:`_orm.relationship` should also be added to that same :class:`.Session`. Suppose we have an object ``user1`` with two related objects ``address1``, ``address2``:: @@ -121,7 +121,7 @@ it takes place in both directions for bi-directional relationships, e.g. backrefs, meaning that the association of a child object with a particular parent can have the effect of the parent object being implicitly associated with that child object's :class:`.Session`; this pattern, as well as how to modify its -behavior using the :paramref:`~.relationship.cascade_backrefs` flag, +behavior using the :paramref:`_orm.relationship.cascade_backrefs` flag, is discussed in the section :ref:`backref_cascade`. .. _cascade_delete: @@ -198,7 +198,7 @@ deleting the row entirely. cascade is not specified. Database level "ON DELETE" cascades are specific to the "FOREIGN KEY" construct of the relational database; SQLAlchemy allows configuration of these schema-level constructs at the :term:`DDL` level - using options on :class:`.ForeignKeyConstraint` which are described + using options on :class:`_schema.ForeignKeyConstraint` which are described at :ref:`on_update_on_delete`. It is important to note the differences between the ORM and the relational @@ -225,7 +225,7 @@ deleting the row entirely. level. An attempt by SQLAlchemy to set the column to NULL will fail with a simple NOT NULL constraint exception. - * The other, more special case way is to set the :paramref:`~.relationship.passive_deletes` + * The other, more special case way is to set the :paramref:`_orm.relationship.passive_deletes` flag to the string ``"all"``. This has the effect of entirely disabling SQLAlchemy's behavior of setting the foreign key column to NULL, and a DELETE will be emitted for the parent row without @@ -247,7 +247,7 @@ deleting the row entirely. * SQLAlchemy doesn't **need** to be this sophisticated, as we instead provide smooth integration with the database's own ``ON DELETE`` functionality, - by using the :paramref:`~.relationship.passive_deletes` option in conjunction + by using the :paramref:`_orm.relationship.passive_deletes` option in conjunction with properly configured foreign key constraints. Under this behavior, SQLAlchemy only emits DELETE for those rows that are already locally present in the :class:`.Session`; for any collections that are unloaded, @@ -262,12 +262,12 @@ deleting the row entirely. this can easily result in constraint violations if there are other objects referring to this "one" side from the "many", so it typically is only useful when a relationship is in fact a "one to one". The - :paramref:`~.relationship.single_parent` flag should be used to establish + :paramref:`_orm.relationship.single_parent` flag should be used to establish an in-Python assertion for this case. -When using a :func:`.relationship` that also includes a many-to-many -table using the :paramref:`~.relationship.secondary` option, SQLAlchemy's +When using a :func:`_orm.relationship` that also includes a many-to-many +table using the :paramref:`_orm.relationship.secondary` option, SQLAlchemy's delete cascade handles the rows in this many-to-many table automatically. Just like, as described in :ref:`relationships_many_to_many_deletion`, the addition or removal of an object from a many-to-many collection @@ -294,7 +294,7 @@ have one parent at a time, so is configured in the vast majority of cases on a one-to-many relationship. Setting it on a many-to-one or many-to-many relationship is more awkward; for this use case, SQLAlchemy requires that the :func:`~sqlalchemy.orm.relationship` -be configured with the :paramref:`~.relationship.single_parent` argument, +be configured with the :paramref:`_orm.relationship.single_parent` argument, establishes Python-side validation that ensures the object is associated with only one parent at a time. @@ -357,7 +357,7 @@ place:: >>> i1 in session True -This behavior can be disabled using the :paramref:`~.relationship.cascade_backrefs` flag:: +This behavior can be disabled using the :paramref:`_orm.relationship.cascade_backrefs` flag:: mapper(Order, order_table, properties={ 'items' : relationship(Item, backref='order', diff --git a/doc/build/orm/collections.rst b/doc/build/orm/collections.rst index cba82ef00d..15e9e6fe79 100644 --- a/doc/build/orm/collections.rst +++ b/doc/build/orm/collections.rst @@ -6,7 +6,7 @@ Collection Configuration and Techniques ======================================= -The :func:`.relationship` function defines a linkage between two classes. +The :func:`_orm.relationship` function defines a linkage between two classes. When the linkage defines a one-to-many or many-to-many relationship, it's represented as a Python collection when objects are loaded and manipulated. This section presents additional information about collection configuration @@ -17,7 +17,7 @@ and techniques. Working with Large Collections ============================== -The default behavior of :func:`.relationship` is to fully load +The default behavior of :func:`_orm.relationship` is to fully load the collection of items in, as according to the loading strategy of the relationship. Additionally, the :class:`.Session` by default only knows how to delete objects which are actually present within the session. When a parent instance @@ -66,7 +66,7 @@ enabled on the :class:`.Session` in use, this will occur automatically each time the collection is about to emit a query. -To place a dynamic relationship on a backref, use the :func:`~.orm.backref` +To place a dynamic relationship on a backref, use the :func:`_orm.backref` function in conjunction with ``lazy='dynamic'``:: class Post(Base): @@ -80,8 +80,8 @@ Note that eager/lazy loading options cannot be used in conjunction dynamic relat .. note:: - The :func:`~.orm.dynamic_loader` function is essentially the same - as :func:`~.orm.relationship` with the ``lazy='dynamic'`` argument specified. + The :func:`_orm.dynamic_loader` function is essentially the same + as :func:`_orm.relationship` with the ``lazy='dynamic'`` argument specified. .. warning:: @@ -108,7 +108,7 @@ be persisted to the database as well as locally available for reading at the time they are added. However when instances of ``MyClass`` are freshly loaded from the database, the ``children`` collection stays empty. The noload strategy is also available on a query option basis using the -:func:`.orm.noload` loader option. +:func:`_orm.noload` loader option. Alternatively, a "raise"-loaded relationship will raise an :exc:`~sqlalchemy.exc.InvalidRequestError` where the attribute would normally @@ -127,7 +127,7 @@ application is not emitting any unexpected lazy loads within a certain context. Rather than having to read through SQL logs to determine that all necessary attributes were eager loaded, the "raise" strategy will cause unloaded attributes to raise immediately if accessed. The raise strategy is -also available on a query option basis using the :func:`.orm.raiseload` +also available on a query option basis using the :func:`_orm.raiseload` loader option. .. versionadded:: 1.1 added the "raise" loader strategy. @@ -141,7 +141,7 @@ loader option. Using Passive Deletes --------------------- -Use :paramref:`~.relationship.passive_deletes` to disable child object loading on a DELETE +Use :paramref:`_orm.relationship.passive_deletes` to disable child object loading on a DELETE operation, in conjunction with "ON DELETE (CASCADE|SET NULL)" on your database to automatically cascade deletes to child objects:: @@ -171,7 +171,7 @@ to automatically cascade deletes to child objects:: * When using SQLite, foreign key support must be enabled explicitly. See :ref:`sqlite_foreign_keys` for details. -When :paramref:`~.relationship.passive_deletes` is applied, the ``children`` relationship will not be +When :paramref:`_orm.relationship.passive_deletes` is applied, the ``children`` relationship will not be loaded into memory when an instance of ``MyClass`` is marked for deletion. The ``cascade="all, delete-orphan"`` *will* take effect for instances of ``MyOtherClass`` which are currently present in the session; however for @@ -206,7 +206,7 @@ this collection is a ``list``:: Collections are not limited to lists. Sets, mutable sequences and almost any other Python object that can act as a container can be used in place of the -default list, by specifying the :paramref:`~.relationship.collection_class` option on +default list, by specifying the :paramref:`_orm.relationship.collection_class` option on :func:`~sqlalchemy.orm.relationship`:: class Parent(Base): @@ -314,7 +314,7 @@ is added to the ``Item.notes`` dictionary and the key is generated for us automa {('a', 'atext'): <__main__.Note object at 0x2eaaf0>} Other built-in dictionary types include :func:`.column_mapped_collection`, -which is almost like :func:`.attribute_mapped_collection` except given the :class:`.Column` +which is almost like :func:`.attribute_mapped_collection` except given the :class:`_schema.Column` object directly:: from sqlalchemy.orm.collections import column_mapped_collection @@ -365,7 +365,7 @@ about how the collection operates. step beyond and represents the data internally in some fashion, presenting a "view" of that data on the outside of a different form. - For the first use case, the :func:`.orm.validates` decorator is by far + For the first use case, the :func:`_orm.validates` decorator is by far the simplest way to intercept incoming values in all cases for the purposes of validation and simple marshaling. See :ref:`simple_validators` for an example of this. diff --git a/doc/build/orm/composites.rst b/doc/build/orm/composites.rst index 786a6b5be8..f6eec6f2cd 100644 --- a/doc/build/orm/composites.rst +++ b/doc/build/orm/composites.rst @@ -39,7 +39,7 @@ also should supply adequate ``__eq__()`` and ``__ne__()`` methods which test the equality of two instances. We will create a mapping to a table ``vertices``, which represents two points -as ``x1/y1`` and ``x2/y2``. These are created normally as :class:`.Column` +as ``x1/y1`` and ``x2/y2``. These are created normally as :class:`_schema.Column` objects. Then, the :func:`.composite` function is used to assign new attributes that will represent sets of columns via the ``Point`` class:: diff --git a/doc/build/orm/constructors.rst b/doc/build/orm/constructors.rst index ded70a9720..0d8ed471c7 100644 --- a/doc/build/orm/constructors.rst +++ b/doc/build/orm/constructors.rst @@ -20,7 +20,7 @@ then quietly restoring attributes directly on the instance rather than calling If you need to do some setup on database-loaded instances before they're ready to use, there is an event hook known as :meth:`.InstanceEvents.load` which can achieve this; it is also available via a class-specific decorator called -:func:`.orm.reconstructor`. When using :func:`.orm.reconstructor`, +:func:`_orm.reconstructor`. When using :func:`_orm.reconstructor`, the mapper will invoke the decorated method with no arguments every time it loads or reconstructs an instance of the class. This is @@ -44,7 +44,7 @@ is invoked normally and the ``data`` argument is required. When instances are loaded during a :class:`~sqlalchemy.orm.query.Query` operation as in ``query(MyMappedClass).one()``, ``init_on_load`` is called. -Any method may be tagged as the :func:`.orm.reconstructor`, even +Any method may be tagged as the :func:`_orm.reconstructor`, even the ``__init__`` method itself. It is invoked after all immediate column-level attributes are loaded as well as after eagerly-loaded scalar relationships. Eagerly loaded collections may be only partially populated @@ -54,7 +54,7 @@ ORM state changes made to objects at this stage will not be recorded for the next flush operation, so the activity within a reconstructor should be conservative. -:func:`.orm.reconstructor` is a shortcut into a larger system +:func:`_orm.reconstructor` is a shortcut into a larger system of "instance level" events, which can be subscribed to using the event API - see :class:`.InstanceEvents` for the full API description of these events. diff --git a/doc/build/orm/extensions/associationproxy.rst b/doc/build/orm/extensions/associationproxy.rst index 2afbf73780..6d124cc9cd 100644 --- a/doc/build/orm/extensions/associationproxy.rst +++ b/doc/build/orm/extensions/associationproxy.rst @@ -445,7 +445,7 @@ Querying with Association Proxies --------------------------------- The :class:`.AssociationProxy` features simple SQL construction capabilities -which relate down to the underlying :func:`.relationship` in use as well +which relate down to the underlying :func:`_orm.relationship` in use as well as the target attribute. For example, the :meth:`.RelationshipProperty.Comparator.any` and :meth:`.RelationshipProperty.Comparator.has` operations are available, and will produce a "nested" EXISTS clause, such as in our basic association object example:: @@ -479,7 +479,7 @@ and ``.contains()`` is available for a proxy to a scalar collection:: AND keyword.id = userkeywords.keyword_id AND keyword.keyword = :keyword_1) -:class:`.AssociationProxy` can be used with :meth:`.Query.join` somewhat manually +:class:`.AssociationProxy` can be used with :meth:`_query.Query.join` somewhat manually using the :attr:`~.AssociationProxy.attr` attribute in a star-args context:: q = session.query(User).join(*User.keywords.attr) diff --git a/doc/build/orm/extensions/baked.rst b/doc/build/orm/extensions/baked.rst index 10a0bbe3d6..d44a0a3bdc 100644 --- a/doc/build/orm/extensions/baked.rst +++ b/doc/build/orm/extensions/baked.rst @@ -188,10 +188,10 @@ The above approach gets us a very minimal performance benefit. By re-using a :class:`~.query.Query`, we save on the Python work within the ``session.query(Model)`` constructor as well as calling upon ``filter(Model.id == bindparam('id'))``, which will skip for us the building -up of the Core expression as well as sending it to :meth:`.Query.filter`. -However, the approach still regenerates the full :class:`.Select` -object every time when :meth:`.Query.all` is called and additionally this -brand new :class:`.Select` is sent off to the string compilation step every +up of the Core expression as well as sending it to :meth:`_query.Query.filter`. +However, the approach still regenerates the full :class:`_expression.Select` +object every time when :meth:`_query.Query.all` is called and additionally this +brand new :class:`_expression.Select` is sent off to the string compilation step every time, which for a simple case like the above is probably about 70% of the overhead. @@ -241,7 +241,7 @@ uses two fewer lines of code, does not need to manufacture a cache key of "my_key", and also includes the same feature as our custom "bake" function that caches 100% of the Python invocation work from the constructor of the query, to the filter call, to the production -of the :class:`.Select` object, to the string compilation step. +of the :class:`_expression.Select` object, to the string compilation step. From the above, if we ask ourselves, "what if lookup needs to make conditional decisions as to the structure of the query?", this is where hopefully it becomes apparent @@ -369,11 +369,11 @@ statement compilation time:: Using Subqueries ^^^^^^^^^^^^^^^^ -When using :class:`.Query` objects, it is often needed that one :class:`.Query` +When using :class:`_query.Query` objects, it is often needed that one :class:`_query.Query` object is used to generate a subquery within another. In the case where the -:class:`.Query` is currently in baked form, an interim method may be used to -retrieve the :class:`.Query` object, using the :meth:`.BakedQuery.to_query` -method. This method is passed the :class:`.Session` or :class:`.Query` that is +:class:`_query.Query` is currently in baked form, an interim method may be used to +retrieve the :class:`_query.Query` object, using the :meth:`.BakedQuery.to_query` +method. This method is passed the :class:`.Session` or :class:`_query.Query` that is the argument to the lambda callable used to generate a particular step of the baked query:: @@ -400,13 +400,13 @@ Using the before_compile event ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ As of SQLAlchemy 1.3.11, the use of the :meth:`.QueryEvents.before_compile` -event against a particular :class:`.Query` will disallow the baked query -system from caching the query, if the event hook returns a new :class:`.Query` +event against a particular :class:`_query.Query` will disallow the baked query +system from caching the query, if the event hook returns a new :class:`_query.Query` object that is different from the one passed in. This is so that the :meth:`.QueryEvents.before_compile` hook may be invoked against a particular -:class:`.Query` every time it is used, to accommodate for hooks that +:class:`_query.Query` every time it is used, to accommodate for hooks that alter the query differently each time. To allow a -:meth:`.QueryEvents.before_compile` to alter a :meth:`.Query` object, but +:meth:`.QueryEvents.before_compile` to alter a :meth:`_query.Query` object, but still to allow the result to be cached, the event can be registered passing the ``bake_ok=True`` flag:: @@ -420,13 +420,13 @@ passing the ``bake_ok=True`` flag:: return query The above strategy is appropriate for an event that will modify a -given :class:`.Query` in exactly the same way every time, not dependent +given :class:`_query.Query` in exactly the same way every time, not dependent on specific parameters or external state that changes. .. versionadded:: 1.3.11 - added the "bake_ok" flag to the :meth:`.QueryEvents.before_compile` event and disallowed caching via the "baked" extension from occurring for event handlers that - return a new :class:`.Query` object if this flag is not set. + return a new :class:`_query.Query` object if this flag is not set. Disabling Baked Queries Session-wide @@ -454,20 +454,20 @@ Lazy Loading Integration ------------------------ The baked query system is integrated into SQLAlchemy's lazy loader feature -as used by :func:`.relationship`, and will cache queries for most lazy +as used by :func:`_orm.relationship`, and will cache queries for most lazy load conditions. A small subset of "lazy loads" may not be cached; these involve query options in conjunction with ad-hoc :obj:`.aliased` structures that cannot produce a repeatable cache key. .. versionchanged:: 1.2 "baked" queries are now the foundation of the - lazy-loader feature of :func:`.relationship`. + lazy-loader feature of :func:`_orm.relationship`. Opting out with the bake_queries flag ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The :func:`.relationship` construct includes a flag -:paramref:`.relationship.bake_queries` which when set to False will cause +The :func:`_orm.relationship` construct includes a flag +:paramref:`_orm.relationship.bake_queries` which when set to False will cause that relationship to opt out of caching queries. Additionally, the :paramref:`.Session.enable_baked_queries` setting can be used to disable all "baked query" use. These flags can be useful to conserve memory, diff --git a/doc/build/orm/extensions/declarative/api.rst b/doc/build/orm/extensions/declarative/api.rst index 828c538a7b..9998965c40 100644 --- a/doc/build/orm/extensions/declarative/api.rst +++ b/doc/build/orm/extensions/declarative/api.rst @@ -85,7 +85,7 @@ subclasses to extend just from the special class:: "" One possible use of ``__abstract__`` is to use a distinct -:class:`.MetaData` for different bases:: +:class:`_schema.MetaData` for different bases:: Base = declarative_base() @@ -98,7 +98,7 @@ One possible use of ``__abstract__`` is to use a distinct metadata = MetaData() Above, classes which inherit from ``DefaultBase`` will use one -:class:`.MetaData` as the registry of tables, and those which inherit from +:class:`_schema.MetaData` as the registry of tables, and those which inherit from ``OtherBase`` will use a different one. The tables themselves can then be created perhaps within distinct databases:: @@ -109,9 +109,9 @@ created perhaps within distinct databases:: ``__table_cls__`` ~~~~~~~~~~~~~~~~~ -Allows the callable / class used to generate a :class:`.Table` to be customized. +Allows the callable / class used to generate a :class:`_schema.Table` to be customized. This is a very open-ended hook that can allow special customizations -to a :class:`.Table` that one generates here:: +to a :class:`_schema.Table` that one generates here:: class MyMixin(object): @classmethod @@ -121,7 +121,7 @@ to a :class:`.Table` that one generates here:: metadata, *arg, **kw ) -The above mixin would cause all :class:`.Table` objects generated to include +The above mixin would cause all :class:`_schema.Table` objects generated to include the prefix ``"my_"``, followed by the name normally specified using the ``__tablename__`` attribute. diff --git a/doc/build/orm/extensions/declarative/basic_use.rst b/doc/build/orm/extensions/declarative/basic_use.rst index 02f64b0645..b939f7e393 100644 --- a/doc/build/orm/extensions/declarative/basic_use.rst +++ b/doc/build/orm/extensions/declarative/basic_use.rst @@ -10,7 +10,7 @@ Basic Use :ref:`mapper_config_toplevel`. SQLAlchemy object-relational configuration involves the -combination of :class:`.Table`, :func:`.mapper`, and class +combination of :class:`_schema.Table`, :func:`.mapper`, and class objects to define a mapped class. :mod:`~sqlalchemy.ext.declarative` allows all three to be expressed at once within the class declaration. As much as @@ -32,7 +32,7 @@ As a simple example:: Above, the :func:`declarative_base` callable returns a new base class from which all mapped classes should inherit. When the class definition is -completed, a new :class:`.Table` and :func:`.mapper` will have been generated. +completed, a new :class:`_schema.Table` and :func:`.mapper` will have been generated. The resulting table and mapper are accessible via ``__table__`` and ``__mapper__`` attributes on the @@ -47,7 +47,7 @@ The resulting table and mapper are accessible via Defining Attributes =================== -In the previous example, the :class:`.Column` objects are +In the previous example, the :class:`_schema.Column` objects are automatically named with the name of the attribute to which they are assigned. @@ -61,7 +61,7 @@ just give the column a name. Below, column "some_table_id" is mapped to the id = Column("some_table_id", Integer, primary_key=True) Attributes may be added to the class after its construction, and they will be -added to the underlying :class:`.Table` and +added to the underlying :class:`_schema.Table` and :func:`.mapper` definitions as appropriate:: SomeClass.data = Column('data', Unicode) @@ -88,17 +88,17 @@ Accessing the MetaData ====================== The :func:`declarative_base` base class contains a -:class:`.MetaData` object where newly defined -:class:`.Table` objects are collected. This object is +:class:`_schema.MetaData` object where newly defined +:class:`_schema.Table` objects are collected. This object is intended to be accessed directly for -:class:`.MetaData`-specific operations. Such as, to issue +:class:`_schema.MetaData`-specific operations. Such as, to issue CREATE statements for all tables:: engine = create_engine('sqlite://') Base.metadata.create_all(engine) :func:`declarative_base` can also receive a pre-existing -:class:`.MetaData` object, which allows a +:class:`_schema.MetaData` object, which allows a declarative setup to be associated with an already existing traditional collection of :class:`~sqlalchemy.schema.Table` objects:: @@ -119,9 +119,9 @@ to the named attributes:: Mapper Configuration ==================== -Declarative makes use of the :func:`~.orm.mapper` function internally +Declarative makes use of the :func:`_orm.mapper` function internally when it creates the mapping to the declared table. The options -for :func:`~.orm.mapper` are passed directly through via the +for :func:`_orm.mapper` are passed directly through via the ``__mapper_args__`` class attribute. As always, arguments which reference locally mapped columns can reference them directly from within the class declaration:: diff --git a/doc/build/orm/extensions/declarative/index.rst b/doc/build/orm/extensions/declarative/index.rst index dc4f392f39..43972b03e1 100644 --- a/doc/build/orm/extensions/declarative/index.rst +++ b/doc/build/orm/extensions/declarative/index.rst @@ -11,7 +11,7 @@ extensions that ride on top of the SQLAlchemy :func:`.mapper` construct. While the documentation typically refers to Declarative for most examples, the following sections will provide detailed information on how the -Declarative API interacts with the basic :func:`.mapper` and Core :class:`.Table` +Declarative API interacts with the basic :func:`.mapper` and Core :class:`_schema.Table` systems, as well as how sophisticated patterns can be built using systems such as mixins. diff --git a/doc/build/orm/extensions/declarative/inheritance.rst b/doc/build/orm/extensions/declarative/inheritance.rst index b988438165..fcbdc0a949 100644 --- a/doc/build/orm/extensions/declarative/inheritance.rst +++ b/doc/build/orm/extensions/declarative/inheritance.rst @@ -122,7 +122,7 @@ will result in an error:: In a situation like this, Declarative can't be sure of the intent, especially if the ``start_date`` columns had, for example, different types. A situation like this can be resolved by using -:class:`.declared_attr` to define the :class:`.Column` conditionally, taking +:class:`.declared_attr` to define the :class:`_schema.Column` conditionally, taking care to return the **existing column** via the parent ``__table__`` if it already exists:: @@ -152,13 +152,13 @@ already exists:: Above, when ``Manager`` is mapped, the ``start_date`` column is already present on the ``Person`` class. Declarative lets us return -that :class:`.Column` as a result in this case, where it knows to skip +that :class:`_schema.Column` as a result in this case, where it knows to skip re-assigning the same column. If the mapping is mis-configured such that the ``start_date`` column is accidentally re-assigned to a different table (such as, if we changed ``Manager`` to be joined inheritance without fixing ``start_date``), an error is raised which -indicates an existing :class:`.Column` is trying to be re-assigned to -a different owning :class:`.Table`. +indicates an existing :class:`_schema.Column` is trying to be re-assigned to +a different owning :class:`_schema.Table`. The same concept can be used with mixin classes (see :ref:`declarative_mixins`):: @@ -184,7 +184,7 @@ The above mixin checks the local ``__table__`` attribute for the column. Because we're using single table inheritance, we're sure that in this case, ``cls.__table__`` refers to ``Person.__table__``. If we were mixing joined- and single-table inheritance, we might want our mixin to check more carefully -if ``cls.__table__`` is really the :class:`.Table` we're looking for. +if ``cls.__table__`` is really the :class:`_schema.Table` we're looking for. .. _declarative_concrete_table: @@ -208,7 +208,7 @@ Concrete is defined as a subclass which has its own table and sets the Usage of an abstract base class is a little less straightforward as it requires usage of :func:`~sqlalchemy.orm.util.polymorphic_union`, -which needs to be created with the :class:`.Table` objects +which needs to be created with the :class:`_schema.Table` objects before the class is built:: engineers = Table('engineers', Base.metadata, diff --git a/doc/build/orm/extensions/declarative/mixins.rst b/doc/build/orm/extensions/declarative/mixins.rst index 52907ac7c9..509b1d34c6 100644 --- a/doc/build/orm/extensions/declarative/mixins.rst +++ b/doc/build/orm/extensions/declarative/mixins.rst @@ -108,14 +108,14 @@ and ``b.c.id`` are two distinct Python objects, referencing their parent tables ``a`` and ``b`` respectively. In the case of the mixin column, it seems that only one -:class:`.Column` object is explicitly created, yet the ultimate +:class:`_schema.Column` object is explicitly created, yet the ultimate ``created_at`` column above must exist as a distinct Python object for each separate destination class. To accomplish this, the declarative -extension creates a **copy** of each :class:`.Column` object encountered on +extension creates a **copy** of each :class:`_schema.Column` object encountered on a class that is detected as a mixin. This copy mechanism is limited to simple columns that have no foreign -keys, as a :class:`.ForeignKey` itself contains references to columns +keys, as a :class:`_schema.ForeignKey` itself contains references to columns which can't be properly recreated at this level. For columns that have foreign keys, as well as for the variety of mapper-level constructs that require destination-explicit context, the @@ -135,7 +135,7 @@ patterns common to many classes can be defined as callables:: Where above, the ``address_id`` class-level callable is executed at the point at which the ``User`` class is constructed, and the declarative -extension can use the resulting :class:`.Column` object as returned by +extension can use the resulting :class:`_schema.Column` object as returned by the method without the need to copy it. Columns generated by :class:`~.declared_attr` can also be @@ -195,12 +195,12 @@ Using Advanced Relationship Arguments (e.g. ``primaryjoin``, etc.) primaryjoin, order_by etc. expressions should in all but the most simplistic cases use **late bound** forms for these arguments, meaning, using either the string form or a lambda. -The reason for this is that the related :class:`.Column` objects which are to +The reason for this is that the related :class:`_schema.Column` objects which are to be configured using ``@declared_attr`` are not available to another ``@declared_attr`` attribute; while the methods will work and return new -:class:`.Column` objects, those are not the :class:`.Column` objects that +:class:`_schema.Column` objects, those are not the :class:`_schema.Column` objects that Declarative will be using as it calls the methods on its own, thus using -*different* :class:`.Column` objects. +*different* :class:`_schema.Column` objects. The canonical example is the primaryjoin condition that depends upon another mixed-in column:: @@ -221,8 +221,8 @@ Mapping a class using the above mixin, we will get an error like:: sqlalchemy.exc.InvalidRequestError: this ForeignKey's parent column is not yet associated with a Table. -This is because the ``target_id`` :class:`.Column` we've called upon in our -``target()`` method is not the same :class:`.Column` that declarative is +This is because the ``target_id`` :class:`_schema.Column` we've called upon in our +``target()`` method is not the same :class:`_schema.Column` that declarative is actually going to map to our table. The condition above is resolved using a lambda:: @@ -336,9 +336,9 @@ string values to an implementing class:: string_table_name = 'type_b_strings' id = Column(Integer(), primary_key=True) -Above, the ``HasStringCollection`` mixin produces a :func:`.relationship` +Above, the ``HasStringCollection`` mixin produces a :func:`_orm.relationship` which refers to a newly generated class called ``StringAttribute``. The -``StringAttribute`` class is generated with its own :class:`.Table` +``StringAttribute`` class is generated with its own :class:`_schema.Table` definition which is local to the parent class making usage of the ``HasStringCollection`` mixin. It also produces an :func:`.association_proxy` object which proxies references to the ``strings`` attribute onto the ``value`` diff --git a/doc/build/orm/extensions/declarative/relationships.rst b/doc/build/orm/extensions/declarative/relationships.rst index 07b6ed5bfd..d33d442454 100644 --- a/doc/build/orm/extensions/declarative/relationships.rst +++ b/doc/build/orm/extensions/declarative/relationships.rst @@ -71,25 +71,25 @@ package, including expression functions like The strings accepted by the following parameters: - :paramref:`.relationship.order_by` + :paramref:`_orm.relationship.order_by` - :paramref:`.relationship.primaryjoin` + :paramref:`_orm.relationship.primaryjoin` - :paramref:`.relationship.secondaryjoin` + :paramref:`_orm.relationship.secondaryjoin` - :paramref:`.relationship.secondary` + :paramref:`_orm.relationship.secondary` - :paramref:`.relationship.remote_side` + :paramref:`_orm.relationship.remote_side` - :paramref:`.relationship.foreign_keys` + :paramref:`_orm.relationship.foreign_keys` - :paramref:`.relationship._user_defined_foreign_keys` + :paramref:`_orm.relationship._user_defined_foreign_keys` Are **evaluated as Python code expressions using eval(). DO NOT PASS UNTRUSTED INPUT TO THESE ARGUMENTS.** In addition, prior to version 1.3.16 of SQLAlchemy, the main - "argument" to :func:`.relationship` is also evaluated as Python + "argument" to :func:`_orm.relationship` is also evaluated as Python code. **DO NOT PASS UNTRUSTED INPUT TO THIS ARGUMENT.** .. versionchanged:: 1.3.16 @@ -147,10 +147,10 @@ Configuring Many-to-Many Relationships Many-to-many relationships are also declared in the same way with declarative as with traditional mappings. The ``secondary`` argument to -:func:`.relationship` is as usual passed a -:class:`.Table` object, which is typically declared in the -traditional way. The :class:`.Table` usually shares -the :class:`.MetaData` object used by the declarative base:: +:func:`_orm.relationship` is as usual passed a +:class:`_schema.Table` object, which is typically declared in the +traditional way. The :class:`_schema.Table` usually shares +the :class:`_schema.MetaData` object used by the declarative base:: keywords = Table( 'keywords', Base.metadata, @@ -173,8 +173,8 @@ as well, passing the string name of the table as defined in the keywords = relationship("Keyword", secondary="keywords") As with traditional mapping, its generally not a good idea to use -a :class:`.Table` as the "secondary" argument which is also mapped to -a class, unless the :func:`.relationship` is declared with ``viewonly=True``. +a :class:`_schema.Table` as the "secondary" argument which is also mapped to +a class, unless the :func:`_orm.relationship` is declared with ``viewonly=True``. Otherwise, the unit-of-work system may attempt duplicate INSERT and DELETE statements against the underlying table. diff --git a/doc/build/orm/extensions/declarative/table_config.rst b/doc/build/orm/extensions/declarative/table_config.rst index d2ae572b2e..b35f54d7d4 100644 --- a/doc/build/orm/extensions/declarative/table_config.rst +++ b/doc/build/orm/extensions/declarative/table_config.rst @@ -7,8 +7,8 @@ Table Configuration .. seealso:: This section describes specifics about how the Declarative system - defines :class:`.Table` objects that are to be mapped with the - SQLAlchemy ORM. For general information on :class:`.Table` objects + defines :class:`_schema.Table` objects that are to be mapped with the + SQLAlchemy ORM. For general information on :class:`_schema.Table` objects see :ref:`metadata_describing_toplevel`. Table arguments other than the name, metadata, and mapped Column @@ -77,13 +77,13 @@ and pass it to declarative classes:: Some configuration schemes may find it more appropriate to use ``__table__``, such as those which already take advantage of the data-driven nature of -:class:`.Table` to customize and/or automate schema definition. +:class:`_schema.Table` to customize and/or automate schema definition. Note that when the ``__table__`` approach is used, the object is immediately -usable as a plain :class:`.Table` within the class declaration body itself, +usable as a plain :class:`_schema.Table` within the class declaration body itself, as a Python class is only another syntactical block. Below this is illustrated by using the ``id`` column in the ``primaryjoin`` condition of a -:func:`.relationship`:: +:func:`_orm.relationship`:: class MyClass(Base): __table__ = Table('my_table', Base.metadata, @@ -115,7 +115,7 @@ generating a synonym for ``name``:: Using Reflection with Declarative ================================= -It's easy to set up a :class:`.Table` that uses ``autoload=True`` +It's easy to set up a :class:`_schema.Table` that uses ``autoload=True`` in conjunction with a mapped class:: class MyClass(Base): @@ -123,7 +123,7 @@ in conjunction with a mapped class:: autoload=True, autoload_with=some_engine) However, one improvement that can be made here is to not -require the :class:`.Engine` to be available when classes are +require the :class:`_engine.Engine` to be available when classes are being first declared. To achieve this, use the :class:`.DeferredReflection` mixin, which sets up mappings only after a special ``prepare(engine)`` step is called:: diff --git a/doc/build/orm/inheritance.rst b/doc/build/orm/inheritance.rst index e401236d61..ccda5f20b2 100644 --- a/doc/build/orm/inheritance.rst +++ b/doc/build/orm/inheritance.rst @@ -258,9 +258,9 @@ discriminator column is also required on the base table so that classes can be differentiated from each other. Even though subclasses share the base table for all of their attributes, -when using Declarative, :class:`.Column` objects may still be specified on +when using Declarative, :class:`_schema.Column` objects may still be specified on subclasses, indicating that the column is to be mapped only to that subclass; -the :class:`.Column` will be applied to the same base :class:`.Table` object:: +the :class:`_schema.Column` will be applied to the same base :class:`_schema.Table` object:: class Employee(Base): __tablename__ = 'employee' @@ -483,13 +483,13 @@ constructed using a SQLAlchemy helper :func:`.polymorphic_union`. As discussed in :ref:`inheritance_loading_toplevel`, mapper inheritance configurations of any type can be configured to load from a special selectable by default using the :paramref:`.mapper.with_polymorphic` argument. Current -public API requires that this argument is set on a :class:`.Mapper` when +public API requires that this argument is set on a :class:`_orm.Mapper` when it is first constructed. -However, in the case of Declarative, both the mapper and the :class:`.Table` +However, in the case of Declarative, both the mapper and the :class:`_schema.Table` that is mapped are created at once, the moment the mapped class is defined. This means that the :paramref:`.mapper.with_polymorphic` argument cannot -be provided yet, since the :class:`.Table` objects that correspond to the +be provided yet, since the :class:`_schema.Table` objects that correspond to the subclasses haven't yet been defined. There are a few strategies available to resolve this cycle, however @@ -631,8 +631,8 @@ domain of concrete inheritance, and we must build a special mapper against .. topic:: Mappers can always SELECT In SQLAlchemy, a mapper for a class always has to refer to some - "selectable", which is normally a :class:`.Table` but may also refer to any - :func:`~.sql.expression.select` object as well. While it may appear that a "single table + "selectable", which is normally a :class:`_schema.Table` but may also refer to any + :func:`_expression.select` object as well. While it may appear that a "single table inheritance" mapper does not map to a table, these mappers in fact implicitly refer to the table that is mapped by a superclass. @@ -690,13 +690,13 @@ Classical and Semi-Classical Concrete Polymorphic Configuration The Declarative configurations illustrated with :class:`.ConcreteBase` and :class:`.AbstractConcreteBase` are equivalent to two other forms of configuration that make use of :func:`.polymorphic_union` explicitly. -These configurational forms make use of the :class:`.Table` object explicitly +These configurational forms make use of the :class:`_schema.Table` object explicitly so that the "polymorphic union" can be created first, then applied to the mappings. These are illustrated here to clarify the role of the :func:`.polymorphic_union` function in terms of mapping. A **semi-classical mapping** for example makes use of Declarative, but -establishes the :class:`.Table` objects separately:: +establishes the :class:`_schema.Table` objects separately:: metadata = Base.metadata @@ -730,7 +730,7 @@ Next, the UNION is produced using :func:`.polymorphic_union`:: 'engineer': engineers_table }, 'type', 'pjoin') -With the above :class:`.Table` objects, the mappings can be produced using "semi-classical" style, +With the above :class:`_schema.Table` objects, the mappings can be produced using "semi-classical" style, where we use Declarative in conjunction with the ``__table__`` argument; our polymorphic union above is passed via ``__mapper_args__`` to the :paramref:`.mapper.with_polymorphic` parameter:: @@ -755,7 +755,7 @@ the :paramref:`.mapper.with_polymorphic` parameter:: 'polymorphic_identity': 'manager', 'concrete': True} -Alternatively, the same :class:`.Table` objects can be used in +Alternatively, the same :class:`_schema.Table` objects can be used in fully "classical" style, without using Declarative at all. A constructor similar to that supplied by Declarative is illustrated:: @@ -891,14 +891,14 @@ such a configuration is as follows:: The next complexity with concrete inheritance and relationships involves when we'd like one or all of ``Employee``, ``Manager`` and ``Engineer`` to themselves refer back to ``Company``. For this case, SQLAlchemy has -special behavior in that a :func:`.relationship` placed on ``Employee`` +special behavior in that a :func:`_orm.relationship` placed on ``Employee`` which links to ``Company`` **does not work** against the ``Manager`` and ``Engineer`` classes, when exercised at the instance level. Instead, a distinct -:func:`.relationship` must be applied to each class. In order to achieve +:func:`_orm.relationship` must be applied to each class. In order to achieve bi-directional behavior in terms of three separate relationships which serve as the opposite of ``Company.employees``, the -:paramref:`.relationship.back_populates` parameter is used between +:paramref:`_orm.relationship.back_populates` parameter is used between each of the relationships:: from sqlalchemy.ext.declarative import ConcreteBase @@ -961,7 +961,7 @@ Loading Concrete Inheritance Mappings The options for loading with concrete inheritance are limited; generally, if polymorphic loading is configured on the mapper using one of the declarative concrete mixins, it can't be modified at query time -in current SQLAlchemy versions. Normally, the :func:`.orm.with_polymorphic` +in current SQLAlchemy versions. Normally, the :func:`_orm.with_polymorphic` function would be able to override the style of loading used by concrete, however due to current limitations this is not yet supported. diff --git a/doc/build/orm/inheritance_loading.rst b/doc/build/orm/inheritance_loading.rst index 7b88b25a5c..7e5675c146 100644 --- a/doc/build/orm/inheritance_loading.rst +++ b/doc/build/orm/inheritance_loading.rst @@ -20,10 +20,10 @@ of a particular subclass is queried up front, we can use it in our query as something to filter on, and it also will be loaded when we get our objects back. If it's not queried up front, it gets loaded later when we first need to access it. Basic control of this behavior is provided using the -:func:`.orm.with_polymorphic` function, as well as two variants, the mapper +:func:`_orm.with_polymorphic` function, as well as two variants, the mapper configuration :paramref:`.mapper.with_polymorphic` in conjunction with -the :paramref:`.mapper.polymorphic_load` option, and the :class:`.Query` --level :meth:`.Query.with_polymorphic` method. The "with_polymorphic" family +the :paramref:`.mapper.polymorphic_load` option, and the :class:`_query.Query` +-level :meth:`_query.Query.with_polymorphic` method. The "with_polymorphic" family each provide a means of specifying which specific subclasses of a particular base class should be included within a query, which implies what columns and tables will be available in the SELECT. @@ -36,7 +36,7 @@ Using with_polymorphic For the following sections, assume the ``Employee`` / ``Engineer`` / ``Manager`` examples introduced in :ref:`inheritance_toplevel`. -Normally, when a :class:`.Query` specifies the base class of an +Normally, when a :class:`_query.Query` specifies the base class of an inheritance hierarchy, only the columns that are local to that base class are queried:: @@ -55,9 +55,9 @@ inheritance case, since the ``Employee`` entity does not refer to these columns (note that for single-table inheritance, this is common if Declarative is used, but not for a classical mapping). -To solve both of these issues, the :func:`.orm.with_polymorphic` function +To solve both of these issues, the :func:`_orm.with_polymorphic` function provides a special :class:`.AliasedClass` that represents a range of -columns across subclasses. This object can be used in a :class:`.Query` +columns across subclasses. This object can be used in a :class:`_query.Query` like any other alias. When queried, it represents all the columns present in the classes given:: @@ -91,7 +91,7 @@ statement for the above would be: Where above, the additional tables / columns for "engineer" and "manager" are included. Similar behavior occurs in the case of single table inheritance. -:func:`.orm.with_polymorphic` accepts a single class or +:func:`_orm.with_polymorphic` accepts a single class or mapper, a list of classes/mappers, or the string ``'*'`` to indicate all subclasses: @@ -109,8 +109,8 @@ subclasses: Using aliasing with with_polymorphic ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :func:`.orm.with_polymorphic` function also provides "aliasing" of the -polymorphic selectable itself, meaning, two different :func:`.orm.with_polymorphic` +The :func:`_orm.with_polymorphic` function also provides "aliasing" of the +polymorphic selectable itself, meaning, two different :func:`_orm.with_polymorphic` entities, referring to the same class hierarchy, can be used together. This is available using the :paramref:`.orm.with_polymorphic.aliased` flag. For a polymorphic selectable that is across multiple tables, the default behavior @@ -171,7 +171,7 @@ with the same name: The creation of subqueries above is very verbose. While it creates the best encapsulation of the two distinct queries, it may be inefficient. -:func:`.orm.with_polymorphic` includes an additional flag to help with this +:func:`_orm.with_polymorphic` includes an additional flag to help with this situation, :paramref:`.orm.with_polymorphic.flat`, which will "flatten" the subquery / join combination into straight joins, applying aliasing to the individual tables instead. Setting :paramref:`.orm.with_polymorphic.flat` @@ -232,8 +232,8 @@ modern database versions now support this syntax. Referring to Specific Subclass Attributes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The entity returned by :func:`.orm.with_polymorphic` is an :class:`.AliasedClass` -object, which can be used in a :class:`.Query` like any other alias, including +The entity returned by :func:`_orm.with_polymorphic` is an :class:`.AliasedClass` +object, which can be used in a :class:`_query.Query` like any other alias, including named attributes for those attributes on the ``Employee`` class. In our previous example, ``eng_plus_manager`` becomes the entity that we use to refer to the three-way outer join above. It also includes namespaces for each class named @@ -254,7 +254,7 @@ specific to ``Engineer`` as well as ``Manager`` in terms of ``eng_plus_manager`` Setting with_polymorphic at mapper configuration time ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :func:`.orm.with_polymorphic` function serves the purpose of allowing +The :func:`_orm.with_polymorphic` function serves the purpose of allowing "eager" loading of attributes from subclass tables, as well as the ability to refer to the attributes from subclass tables at query time. Historically, the "eager loading" of columns has been the more important part of the @@ -285,11 +285,11 @@ efficient from a SQL perspective. For single table inheritance, specifying the asterisk is often a good idea as the load is still against a single table only, but an additional lazy load of subclass-mapped columns will be prevented. -Using :func:`.orm.with_polymorphic` or :meth:`.Query.with_polymorphic` +Using :func:`_orm.with_polymorphic` or :meth:`_query.Query.with_polymorphic` will override the mapper-level :paramref:`.mapper.with_polymorphic` setting. The :paramref:`.mapper.with_polymorphic` option also accepts a list of -classes just like :func:`.orm.with_polymorphic` to polymorphically load among +classes just like :func:`_orm.with_polymorphic` to polymorphically load among a subset of classes. However, when using Declarative, providing classes to this list is not directly possible as the subclasses we'd like to add are not available yet. Instead, we can specify on each subclass @@ -323,11 +323,11 @@ exactly as though they had been appended to the Setting with_polymorphic against a query ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :func:`.orm.with_polymorphic` function evolved from a query-level -method :meth:`.Query.with_polymorphic`. This method has the same purpose -as :func:`.orm.with_polymorphic`, except is not as +The :func:`_orm.with_polymorphic` function evolved from a query-level +method :meth:`_query.Query.with_polymorphic`. This method has the same purpose +as :func:`_orm.with_polymorphic`, except is not as flexible in its usage patterns in that it only applies to the first entity -of the :class:`.Query`. It then takes effect for all occurrences of +of the :class:`_query.Query`. It then takes effect for all occurrences of that entity, so that the entity (and its subclasses) can be referred to directly, rather than using an alias object. For simple cases it might be considered to be more succinct:: @@ -341,25 +341,25 @@ considered to be more succinct:: ) ) -The :meth:`.Query.with_polymorphic` method has a more complicated job -than the :func:`.orm.with_polymorphic` function, as it needs to correctly +The :meth:`_query.Query.with_polymorphic` method has a more complicated job +than the :func:`_orm.with_polymorphic` function, as it needs to correctly transform entities like ``Engineer`` and ``Manager`` appropriately, but not interfere with other entities. If its flexibility is lacking, switch -to using :func:`.orm.with_polymorphic`. +to using :func:`_orm.with_polymorphic`. .. _polymorphic_selectin: Polymorphic Selectin Loading ---------------------------- -An alternative to using the :func:`.orm.with_polymorphic` family of +An alternative to using the :func:`_orm.with_polymorphic` family of functions to "eagerly" load the additional subclasses on an inheritance mapping, primarily when using joined table inheritance, is to use polymorphic "selectin" loading. This is an eager loading feature which works similarly to the :ref:`selectin_eager_loading` feature of relationship loading. Given our example mapping, we can instruct a load of ``Employee`` to emit an extra SELECT per subclass by using -the :func:`.orm.selectin_polymorphic` loader option:: +the :func:`_orm.selectin_polymorphic` loader option:: from sqlalchemy.orm import selectin_polymorphic @@ -434,8 +434,8 @@ using the value ``"selectin"`` on a per-subclass basis:: } -Unlike when using :func:`.orm.with_polymorphic`, when using the -:func:`.orm.selectin_polymorphic` style of loading, we do **not** have the +Unlike when using :func:`_orm.with_polymorphic`, when using the +:func:`_orm.selectin_polymorphic` style of loading, we do **not** have the ability to refer to the ``Engineer`` or ``Manager`` entities within our main query as filter, order by, or other criteria, as these entities are not present in the initial query that is used to locate results. However, we can apply @@ -443,7 +443,7 @@ loader options that apply towards ``Engineer`` or ``Manager``, which will take effect when the secondary SELECT is emitted. Below we assume ``Manager`` has an additional relationship ``Manager.paperwork``, that we'd like to eagerly load as well. We can use any type of eager loading, such as joined eager -loading via the :func:`.joinedload` function:: +loading via the :func:`_orm.joinedload` function:: from sqlalchemy.orm import joinedload from sqlalchemy.orm import selectin_polymorphic @@ -542,7 +542,7 @@ similarly to the following: (1,) Combining "selectin" polymorhic loading with query-time -:func:`.orm.with_polymorphic` usage is also possible (though this is very +:func:`_orm.with_polymorphic` usage is also possible (though this is very outer-space stuff!); assuming the above mappings had no ``polymorphic_load`` set up, we could get the same result as follows:: @@ -558,14 +558,14 @@ set up, we could get the same result as follows:: Referring to specific subtypes on relationships ----------------------------------------------- -Mapped attributes which correspond to a :func:`.relationship` are used +Mapped attributes which correspond to a :func:`_orm.relationship` are used in querying in order to refer to the linkage between two mappings. Common -uses for this are to refer to a :func:`.relationship` in :meth:`.Query.join` -as well as in loader options like :func:`.joinedload`. When using -:func:`.relationship` where the target class is an inheritance hierarchy, +uses for this are to refer to a :func:`_orm.relationship` in :meth:`_query.Query.join` +as well as in loader options like :func:`_orm.joinedload`. When using +:func:`_orm.relationship` where the target class is an inheritance hierarchy, the API allows that the join, eager load, or other linkage should target a specific -subclass, alias, or :func:`.orm.with_polymorphic` alias, of that class hierarchy, -rather than the class directly targeted by the :func:`.relationship`. +subclass, alias, or :func:`_orm.with_polymorphic` alias, of that class hierarchy, +rather than the class directly targeted by the :func:`_orm.relationship`. The :func:`~sqlalchemy.orm.interfaces.PropComparator.of_type` method allows the construction of joins along :func:`~sqlalchemy.orm.relationship` paths while @@ -606,7 +606,7 @@ with a ``Company`` object. We'll add a ``company_id`` column to the __mapper_args__ = {'polymorphic_identity':'manager'} When querying from ``Company`` onto the ``Employee`` relationship, the -:meth:`.Query.join` method as well as operators like :meth:`.PropComparator.any` +:meth:`_query.Query.join` method as well as operators like :meth:`.PropComparator.any` and :meth:`.PropComparator.has` will create a join from ``company`` to ``employee``, without including ``engineer`` or ``manager`` in the mix. If we wish to have criterion which is specifically @@ -648,7 +648,7 @@ such as when the embedded criterion is in terms of a subclass:: Eager Loading of Specific or Polymorphic Subtypes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :func:`.joinedload`, :func:`.subqueryload`, :func:`.contains_eager` and +The :func:`_orm.joinedload`, :func:`.subqueryload`, :func:`.contains_eager` and other eagerloader options support paths which make use of :func:`~.PropComparator.of_type`. Below, we load ``Company`` rows while eagerly loading related ``Engineer`` @@ -661,8 +661,8 @@ objects, querying the ``employee`` and ``engineer`` tables simultaneously:: ) ) -As is the case with :meth:`.Query.join`, :meth:`~.PropComparator.of_type` -can be used to combine eager loading and :func:`.orm.with_polymorphic`, +As is the case with :meth:`_query.Query.join`, :meth:`~.PropComparator.of_type` +can be used to combine eager loading and :func:`_orm.with_polymorphic`, so that all sub-attributes of all referenced subtypes can be loaded:: @@ -680,8 +680,8 @@ can be loaded:: .. note:: When using :func:`.with_polymorphic` in conjunction with - :func:`.joinedload`, the :func:`.with_polymorphic` object must be against - an "aliased" object, that is an instance of :class:`.Alias`, so that the + :func:`_orm.joinedload`, the :func:`.with_polymorphic` object must be against + an "aliased" object, that is an instance of :class:`_expression.Alias`, so that the polymorphic selectable is aliased (an informative error message is raised otherwise). @@ -689,7 +689,7 @@ can be loaded:: :paramref:`.with_polymorphic.aliased` or :paramref:`.flat` flag, which will apply this aliasing automatically. However, if the :paramref:`.with_polymorphic.selectable` argument is being used to pass an - object that is already an :class:`.Alias` object then this flag should + object that is already an :class:`_expression.Alias` object then this flag should **not** be set. The "flat" option implies the "aliased" option and is an alternate form of aliasing against join objects that produces fewer subqueries. @@ -698,7 +698,7 @@ Once :meth:`~.PropComparator.of_type` is the target of the eager load, that's the entity we would use for subsequent chaining, not the original class or derived class. If we wanted to further eager load a collection on the eager-loaded ``Engineer`` class, we access this class from the namespace of the -:func:`.orm.with_polymorphic` object:: +:func:`_orm.with_polymorphic` object:: session.query(Company).\ options( @@ -732,7 +732,7 @@ The above query will emit SQL like: We will then get a collection of ``Engineer`` objects back, which will contain all columns from ``employee`` and ``engineer`` loaded. -However, when emitting a :class:`.Query` against a base class, the behavior +However, when emitting a :class:`_query.Query` against a base class, the behavior is to load only from the base table:: session.query(Employee).all() @@ -770,7 +770,7 @@ issued along the lines of: WHERE ? = engineer.id [2] -The :func:`.orm.with_polymorphic` +The :func:`_orm.with_polymorphic` function and related configuration options allow us to instead emit a JOIN up front which will conditionally load against ``employee``, ``engineer``, or ``manager``, very much like joined eager loading works for relationships, @@ -803,7 +803,7 @@ The above produces a query which joins the ``employee`` table to both the ON employee.id = manager.id [] -The section :ref:`with_polymorphic` discusses the :func:`.orm.with_polymorphic` +The section :ref:`with_polymorphic` discusses the :func:`_orm.with_polymorphic` function and its configurational variants. .. seealso:: @@ -815,11 +815,11 @@ function and its configurational variants. Loading objects with single table inheritance --------------------------------------------- -In modern Declarative, single inheritance mappings produce :class:`.Column` +In modern Declarative, single inheritance mappings produce :class:`_schema.Column` objects that are mapped only to a subclass, and not available from the superclass, even though they are present on the same table. In our example from :ref:`single_inheritance`, the ``Manager`` mapping for example had a -:class:`.Column` specified:: +:class:`_schema.Column` specified:: class Manager(Employee): manager_data = Column(String(50)) @@ -867,7 +867,7 @@ for those columns, in a similar way to joined inheritance:: FROM employee WHERE employee.id = ? AND employee.type IN (?) -The :func:`.orm.with_polymorphic` function serves a similar role as joined +The :func:`_orm.with_polymorphic` function serves a similar role as joined inheritance in the case of single inheritance; it allows both for eager loading of subclass attributes as well as specification of subclasses in a query, just without the overhead of using OUTER JOIN:: diff --git a/doc/build/orm/internals.rst b/doc/build/orm/internals.rst index 20ddc2b234..d0e7c1ce46 100644 --- a/doc/build/orm/internals.rst +++ b/doc/build/orm/internals.rst @@ -59,7 +59,7 @@ sections, are listed here. The dictionary is generated when first accessed. Alternatively, it can be specified as a constructor argument to the - :func:`.column_property`, :func:`.relationship`, or :func:`.composite` + :func:`.column_property`, :func:`_orm.relationship`, or :func:`.composite` functions. .. versionchanged:: 1.0.0 :attr:`.InspectionAttr.info` moved diff --git a/doc/build/orm/join_conditions.rst b/doc/build/orm/join_conditions.rst index 68a2949ffa..11d7cf6d9e 100644 --- a/doc/build/orm/join_conditions.rst +++ b/doc/build/orm/join_conditions.rst @@ -3,7 +3,7 @@ Configuring how Relationship Joins ---------------------------------- -:func:`.relationship` will normally create a join between two tables +:func:`_orm.relationship` will normally create a join between two tables by examining the foreign key relationship between the two tables to determine which columns should be compared. There are a variety of situations where this behavior needs to be customized. @@ -54,12 +54,12 @@ The above mapping, when we attempt to use it, will produce the error:: counted as containing a foreign key reference to the parent table. The above message is pretty long. There are many potential messages -that :func:`.relationship` can return, which have been carefully tailored +that :func:`_orm.relationship` can return, which have been carefully tailored to detect a variety of common configurational issues; most will suggest the additional configuration that's needed to resolve the ambiguity or other missing information. -In this case, the message wants us to qualify each :func:`.relationship` +In this case, the message wants us to qualify each :func:`_orm.relationship` by instructing for each one which foreign key column should be considered, and the appropriate form is as follows:: @@ -74,8 +74,8 @@ the appropriate form is as follows:: billing_address = relationship("Address", foreign_keys=[billing_address_id]) shipping_address = relationship("Address", foreign_keys=[shipping_address_id]) -Above, we specify the ``foreign_keys`` argument, which is a :class:`.Column` or list -of :class:`.Column` objects which indicate those columns to be considered "foreign", +Above, we specify the ``foreign_keys`` argument, which is a :class:`_schema.Column` or list +of :class:`_schema.Column` objects which indicate those columns to be considered "foreign", or in other words, the columns that contain a value referring to a parent table. Loading the ``Customer.billing_address`` relationship from a ``Customer`` object will use the value present in ``billing_address_id`` in order to @@ -92,15 +92,15 @@ is part of the string**:: billing_address = relationship("Address", foreign_keys="[Customer.billing_address_id]") In this specific example, the list is not necessary in any case as there's only -one :class:`.Column` we need:: +one :class:`_schema.Column` we need:: billing_address = relationship("Address", foreign_keys="Customer.billing_address_id") .. warning:: When passed as a Python-evaluable string, the - :paramref:`.relationship.foreign_keys` argument is interpreted using Python's + :paramref:`_orm.relationship.foreign_keys` argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on declarative - evaluation of :func:`.relationship` arguments. + evaluation of :func:`_orm.relationship` arguments. .. _relationship_primaryjoin: @@ -108,12 +108,12 @@ one :class:`.Column` we need:: Specifying Alternate Join Conditions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The default behavior of :func:`.relationship` when constructing a join +The default behavior of :func:`_orm.relationship` when constructing a join is that it equates the value of primary key columns on one side to that of foreign-key-referring columns on the other. We can change this criterion to be anything we'd like using the -:paramref:`~.relationship.primaryjoin` -argument, as well as the :paramref:`~.relationship.secondaryjoin` +:paramref:`_orm.relationship.primaryjoin` +argument, as well as the :paramref:`_orm.relationship.secondaryjoin` argument in the case when a "secondary" table is used. In the example below, using the ``User`` class @@ -150,23 +150,23 @@ construct to establish two distinct predicates for the join condition - joining both the ``User.id`` and ``Address.user_id`` columns to each other, as well as limiting rows in ``Address`` to just ``city='Boston'``. When using Declarative, rudimentary SQL functions like :func:`.and_` are automatically -available in the evaluated namespace of a string :func:`.relationship` +available in the evaluated namespace of a string :func:`_orm.relationship` argument. .. warning:: When passed as a Python-evaluable string, the - :paramref:`.relationship.primaryjoin` argument is interpreted using + :paramref:`_orm.relationship.primaryjoin` argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on declarative - evaluation of :func:`.relationship` arguments. + evaluation of :func:`_orm.relationship` arguments. -The custom criteria we use in a :paramref:`~.relationship.primaryjoin` +The custom criteria we use in a :paramref:`_orm.relationship.primaryjoin` is generally only significant when SQLAlchemy is rendering SQL in order to load or represent this relationship. That is, it's used in the SQL statement that's emitted in order to perform a per-attribute lazy load, or when a join is constructed at query time, such as via -:meth:`.Query.join`, or via the eager "joined" or "subquery" styles of +:meth:`_query.Query.join`, or via the eager "joined" or "subquery" styles of loading. When in-memory objects are being manipulated, we can place any ``Address`` object we'd like into the ``boston_addresses`` collection, regardless of what the value of the ``.city`` attribute @@ -186,13 +186,13 @@ Creating Custom Foreign Conditions Another element of the primary join condition is how those columns considered "foreign" are determined. Usually, some subset -of :class:`.Column` objects will specify :class:`.ForeignKey`, or otherwise -be part of a :class:`.ForeignKeyConstraint` that's relevant to the join condition. -:func:`.relationship` looks to this foreign key status as it decides +of :class:`_schema.Column` objects will specify :class:`_schema.ForeignKey`, or otherwise +be part of a :class:`_schema.ForeignKeyConstraint` that's relevant to the join condition. +:func:`_orm.relationship` looks to this foreign key status as it decides how it should load and persist data for this relationship. However, the -:paramref:`~.relationship.primaryjoin` argument can be used to create a join condition that -doesn't involve any "schema" level foreign keys. We can combine :paramref:`~.relationship.primaryjoin` -along with :paramref:`~.relationship.foreign_keys` and :paramref:`~.relationship.remote_side` explicitly in order to +:paramref:`_orm.relationship.primaryjoin` argument can be used to create a join condition that +doesn't involve any "schema" level foreign keys. We can combine :paramref:`_orm.relationship.primaryjoin` +along with :paramref:`_orm.relationship.foreign_keys` and :paramref:`_orm.relationship.remote_side` explicitly in order to establish such a join. Below, a class ``HostEntry`` joins to itself, equating the string ``content`` @@ -230,10 +230,10 @@ The above relationship will produce a join like:: An alternative syntax to the above is to use the :func:`.foreign` and :func:`.remote` :term:`annotations`, -inline within the :paramref:`~.relationship.primaryjoin` expression. -This syntax represents the annotations that :func:`.relationship` normally -applies by itself to the join condition given the :paramref:`~.relationship.foreign_keys` and -:paramref:`~.relationship.remote_side` arguments. These functions may +inline within the :paramref:`_orm.relationship.primaryjoin` expression. +This syntax represents the annotations that :func:`_orm.relationship` normally +applies by itself to the join condition given the :paramref:`_orm.relationship.foreign_keys` and +:paramref:`_orm.relationship.remote_side` arguments. These functions may be more succinct when an explicit join condition is present, and additionally serve to mark exactly the column that is "foreign" or "remote" independent of whether that column is stated multiple times or within complex @@ -263,13 +263,13 @@ Using custom operators in join conditions Another use case for relationships is the use of custom operators, such as PostgreSQL's "is contained within" ``<<`` operator when joining with -types such as :class:`.postgresql.INET` and :class:`.postgresql.CIDR`. +types such as :class:`_postgresql.INET` and :class:`_postgresql.CIDR`. For custom operators we use the :meth:`.Operators.op` function:: inet_column.op("<<")(cidr_column) -However, if we construct a :paramref:`~.relationship.primaryjoin` using this -operator, :func:`.relationship` will still need more information. This is because +However, if we construct a :paramref:`_orm.relationship.primaryjoin` using this +operator, :func:`_orm.relationship` will still need more information. This is because when it examines our primaryjoin condition, it specifically looks for operators used for **comparisons**, and this is typically a fixed list containing known comparison operators such as ``==``, ``<``, etc. So for our custom operator @@ -307,7 +307,7 @@ Will render as:: FROM ip_address JOIN network ON ip_address.v4address << network.v4representation .. versionadded:: 0.9.2 - Added the :paramref:`.Operators.op.is_comparison` - flag to assist in the creation of :func:`.relationship` constructs using + flag to assist in the creation of :func:`_orm.relationship` constructs using custom operators. Custom operators based on SQL functions @@ -456,9 +456,9 @@ However, this has the effect of ``Article.writer`` not taking Therefore, to get at all of #1, #2, and #3, we express the join condition as well as which columns to be written by combining -:paramref:`~.relationship.primaryjoin` fully, along with either the -:paramref:`~.relationship.foreign_keys` argument, or more succinctly by -annotating with :func:`~.orm.foreign`:: +:paramref:`_orm.relationship.primaryjoin` fully, along with either the +:paramref:`_orm.relationship.foreign_keys` argument, or more succinctly by +annotating with :func:`_orm.foreign`:: class Article(Base): # ... @@ -520,10 +520,10 @@ we seek for a load of ``Element.descendants`` to look like:: Self-Referential Many-to-Many Relationship ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Many to many relationships can be customized by one or both of :paramref:`~.relationship.primaryjoin` -and :paramref:`~.relationship.secondaryjoin` - the latter is significant for a relationship that -specifies a many-to-many reference using the :paramref:`~.relationship.secondary` argument. -A common situation which involves the usage of :paramref:`~.relationship.primaryjoin` and :paramref:`~.relationship.secondaryjoin` +Many to many relationships can be customized by one or both of :paramref:`_orm.relationship.primaryjoin` +and :paramref:`_orm.relationship.secondaryjoin` - the latter is significant for a relationship that +specifies a many-to-many reference using the :paramref:`_orm.relationship.secondary` argument. +A common situation which involves the usage of :paramref:`_orm.relationship.primaryjoin` and :paramref:`_orm.relationship.secondaryjoin` is when establishing a many-to-many relationship from a class to itself, as shown below:: from sqlalchemy import Integer, ForeignKey, String, Column, Table @@ -549,18 +549,18 @@ is when establishing a many-to-many relationship from a class to itself, as show ) Where above, SQLAlchemy can't know automatically which columns should connect -to which for the ``right_nodes`` and ``left_nodes`` relationships. The :paramref:`~.relationship.primaryjoin` -and :paramref:`~.relationship.secondaryjoin` arguments establish how we'd like to join to the association table. +to which for the ``right_nodes`` and ``left_nodes`` relationships. The :paramref:`_orm.relationship.primaryjoin` +and :paramref:`_orm.relationship.secondaryjoin` arguments establish how we'd like to join to the association table. In the Declarative form above, as we are declaring these conditions within the Python block that corresponds to the ``Node`` class, the ``id`` variable is available directly -as the :class:`.Column` object we wish to join with. +as the :class:`_schema.Column` object we wish to join with. -Alternatively, we can define the :paramref:`~.relationship.primaryjoin` -and :paramref:`~.relationship.secondaryjoin` arguments using strings, which is suitable +Alternatively, we can define the :paramref:`_orm.relationship.primaryjoin` +and :paramref:`_orm.relationship.secondaryjoin` arguments using strings, which is suitable in the case that our configuration does not have either the ``Node.id`` column object available yet or the ``node_to_node`` table perhaps isn't yet available. -When referring to a plain :class:`.Table` object in a declarative string, we -use the string name of the table as it is present in the :class:`.MetaData`:: +When referring to a plain :class:`_schema.Table` object in a declarative string, we +use the string name of the table as it is present in the :class:`_schema.MetaData`:: class Node(Base): __tablename__ = 'node' @@ -574,11 +574,11 @@ use the string name of the table as it is present in the :class:`.MetaData`:: ) .. warning:: When passed as a Python-evaluable string, the - :paramref:`.relationship.primaryjoin` and - :paramref:`.relationship.secondaryjoin` arguments are interpreted using + :paramref:`_orm.relationship.primaryjoin` and + :paramref:`_orm.relationship.secondaryjoin` arguments are interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THESE STRINGS**. See :ref:`declarative_relationship_eval` for details on - declarative evaluation of :func:`.relationship` arguments. + declarative evaluation of :func:`_orm.relationship` arguments. A classical mapping situation here is similar, where ``node_to_node`` can be joined @@ -610,12 +610,12 @@ to ``node.c.id``:: )}) -Note that in both examples, the :paramref:`~.relationship.backref` +Note that in both examples, the :paramref:`_orm.relationship.backref` keyword specifies a ``left_nodes`` backref - when -:func:`.relationship` creates the second relationship in the reverse +:func:`_orm.relationship` creates the second relationship in the reverse direction, it's smart enough to reverse the -:paramref:`~.relationship.primaryjoin` and -:paramref:`~.relationship.secondaryjoin` arguments. +:paramref:`_orm.relationship.primaryjoin` and +:paramref:`_orm.relationship.secondaryjoin` arguments. .. _composite_secondary_join: @@ -629,14 +629,14 @@ Composite "Secondary" Joins in simpler ways whenever possible, by using reasonable relational layouts and / or :ref:`in-Python attributes `. -Sometimes, when one seeks to build a :func:`.relationship` between two tables +Sometimes, when one seeks to build a :func:`_orm.relationship` between two tables there is a need for more than just two or three tables to be involved in -order to join them. This is an area of :func:`.relationship` where one seeks +order to join them. This is an area of :func:`_orm.relationship` where one seeks to push the boundaries of what's possible, and often the ultimate solution to many of these exotic use cases needs to be hammered out on the SQLAlchemy mailing list. -In more recent versions of SQLAlchemy, the :paramref:`~.relationship.secondary` +In more recent versions of SQLAlchemy, the :paramref:`_orm.relationship.secondary` parameter can be used in some of these cases in order to provide a composite target consisting of multiple tables. Below is an example of such a join condition (requires version 0.9.2 at least to function as is):: @@ -674,8 +674,8 @@ join condition (requires version 0.9.2 at least to function as is):: id = Column(Integer, primary_key=True) -In the above example, we provide all three of :paramref:`~.relationship.secondary`, -:paramref:`~.relationship.primaryjoin`, and :paramref:`~.relationship.secondaryjoin`, +In the above example, we provide all three of :paramref:`_orm.relationship.secondary`, +:paramref:`_orm.relationship.primaryjoin`, and :paramref:`_orm.relationship.secondaryjoin`, in the declarative style referring to the named tables ``a``, ``b``, ``c``, ``d`` directly. A query from ``A`` to ``D`` looks like: @@ -691,7 +691,7 @@ directly. A query from ``A`` to ``D`` looks like: In the above example, we take advantage of being able to stuff multiple tables into a "secondary" container, so that we can join across many -tables while still keeping things "simple" for :func:`.relationship`, in that +tables while still keeping things "simple" for :func:`_orm.relationship`, in that there's just "one" table on both the "left" and the "right" side; the complexity is kept within the middle. @@ -709,23 +709,23 @@ Relationship to Aliased Class .. versionadded:: 1.3 The :class:`.AliasedClass` construct can now be specified as the - target of a :func:`.relationship`, replacing the previous approach + target of a :func:`_orm.relationship`, replacing the previous approach of using non-primary mappers, which had limitations such that they did not inherit sub-relationships of the mapped entity as well as that they required complex configuration against an alternate selectable. The recipes in this section are now updated to use :class:`.AliasedClass`. In the previous section, we illustrated a technique where we used -:paramref:`~.relationship.secondary` in order to place additional +:paramref:`_orm.relationship.secondary` in order to place additional tables within a join condition. There is one complex join case where even this technique is not sufficient; when we seek to join from ``A`` to ``B``, making use of any number of ``C``, ``D``, etc. in between, however there are also join conditions between ``A`` and ``B`` *directly*. In this case, the join from ``A`` to ``B`` may be difficult to express with just a complex -:paramref:`~.relationship.primaryjoin` condition, as the intermediary +:paramref:`_orm.relationship.primaryjoin` condition, as the intermediary tables may need special handling, and it is also not expressible with -a :paramref:`~.relationship.secondary` object, since the +a :paramref:`_orm.relationship.secondary` object, since the ``A->secondary->B`` pattern does not support any references between ``A`` and ``B`` directly. When this **extremely advanced** case arises, we can resort to creating a second mapping as a target for the @@ -733,10 +733,10 @@ relationship. This is where we use :class:`.AliasedClass` in order to make a mapping to a class that includes all the additional tables we need for this join. In order to produce this mapper as an "alternative" mapping for our class, we use the :func:`.aliased` function to produce the new -construct, then use :func:`.relationship` against the object as though it +construct, then use :func:`_orm.relationship` against the object as though it were a plain mapped class. -Below illustrates a :func:`.relationship` with a simple join from ``A`` to +Below illustrates a :func:`_orm.relationship` with a simple join from ``A`` to ``B``, however the primaryjoin condition is augmented with two additional entities ``C`` and ``D``, which also must have rows that line up with the rows in both ``A`` and ``B`` simultaneously:: @@ -858,11 +858,11 @@ Building Query-Enabled Properties Very ambitious custom join conditions may fail to be directly persistable, and in some cases may not even load correctly. To remove the persistence part of -the equation, use the flag :paramref:`~.relationship.viewonly` on the +the equation, use the flag :paramref:`_orm.relationship.viewonly` on the :func:`~sqlalchemy.orm.relationship`, which establishes it as a read-only attribute (data written to the collection will be ignored on flush()). However, in extreme cases, consider using a regular Python property in -conjunction with :class:`.Query` as follows: +conjunction with :class:`_query.Query` as follows: .. sourcecode:: python diff --git a/doc/build/orm/loading_columns.rst b/doc/build/orm/loading_columns.rst index d226ad670c..a0759e768d 100644 --- a/doc/build/orm/loading_columns.rst +++ b/doc/build/orm/loading_columns.rst @@ -13,10 +13,10 @@ Deferred Column Loading Deferred column loading allows particular columns of a table be loaded only upon direct access, instead of when the entity is queried using -:class:`.Query`. This feature is useful when one wants to avoid +:class:`_query.Query`. This feature is useful when one wants to avoid loading a large text or binary field into memory when it's not needed. Individual columns can be lazy loaded by themselves or placed into groups that -lazy-load together, using the :func:`.orm.deferred` function to +lazy-load together, using the :func:`_orm.deferred` function to mark them as "deferred". In the example below, we define a mapping that will load each of ``.excerpt`` and ``.photo`` in separate, individual-row SELECT statements when each attribute is first referenced on the individual object instance:: @@ -33,8 +33,8 @@ attribute is first referenced on the individual object instance:: excerpt = deferred(Column(Text)) photo = deferred(Column(Binary)) -Classical mappings as always place the usage of :func:`.orm.deferred` in the -``properties`` dictionary against the table-bound :class:`.Column`:: +Classical mappings as always place the usage of :func:`_orm.deferred` in the +``properties`` dictionary against the table-bound :class:`_schema.Column`:: mapper(Book, book_table, properties={ 'photo':deferred(book_table.c.photo) @@ -63,9 +63,9 @@ Deferred Column Loader Query Options ------------------------------------ Columns can be marked as "deferred" or reset to "undeferred" at query time -using options which are passed to the :meth:`.Query.options` method; the most -basic query options are :func:`.orm.defer` and -:func:`.orm.undefer`:: +using options which are passed to the :meth:`_query.Query.options` method; the most +basic query options are :func:`_orm.defer` and +:func:`_orm.undefer`:: from sqlalchemy.orm import defer from sqlalchemy.orm import undefer @@ -77,8 +77,8 @@ basic query options are :func:`.orm.defer` and Above, the "summary" column will not load until accessed, and the "excerpt" column will load immediately even if it was mapped as a "deferred" column. -:func:`.orm.deferred` attributes which are marked with a "group" can be undeferred -using :func:`.orm.undefer_group`, sending in the group name:: +:func:`_orm.deferred` attributes which are marked with a "group" can be undeferred +using :func:`_orm.undefer_group`, sending in the group name:: from sqlalchemy.orm import undefer_group @@ -90,7 +90,7 @@ using :func:`.orm.undefer_group`, sending in the group name:: Deferred Loading across Multiple Entities ----------------------------------------- -To specify column deferral for a :class:`.Query` that loads multiple types of +To specify column deferral for a :class:`_query.Query` that loads multiple types of entities at once, the deferral options may be specified more explicitly using class-bound attributes, rather than string names:: @@ -107,7 +107,7 @@ further levels of relationships, as well as onto column-oriented attributes at that path. Such as, to load ``Author`` instances, then joined-eager-load the ``Author.books`` collection for each author, then apply deferral options to column-oriented attributes onto each ``Book`` entity from that relationship, -the :func:`.joinedload` loader option can be combined with the :func:`.load_only` +the :func:`_orm.joinedload` loader option can be combined with the :func:`.load_only` option (described later in this section) to defer all ``Book`` columns except those explicitly specified:: @@ -119,7 +119,7 @@ those explicitly specified:: ) Option structures as above can also be organized in more complex ways, such -as hierarchically using the :meth:`.Load.options` +as hierarchically using the :meth:`_orm.Load.options` method, which allows multiple sub-options to be chained to a common parent option at once. Any mixture of string names and class-bound attribute objects may be used:: @@ -139,14 +139,14 @@ may be used:: ) ) -.. versionadded:: 1.3.6 Added :meth:`.Load.options` to allow easier +.. versionadded:: 1.3.6 Added :meth:`_orm.Load.options` to allow easier construction of hierarchies of loader options. -Another way to apply options to a path is to use the :func:`.orm.defaultload` +Another way to apply options to a path is to use the :func:`_orm.defaultload` function. This function is used to indicate a particular path within a loader option structure without actually setting any options at that level, so that further -sub-options may be applied. The :func:`.orm.defaultload` function can be used -to create the same structure as we did above using :meth:`.Load.options` as:: +sub-options may be applied. The :func:`_orm.defaultload` function can be used +to create the same structure as we did above using :meth:`_orm.Load.options` as:: query = session.query(Author) query = query.options( @@ -182,7 +182,7 @@ and "excerpt" fields in the SELECT, along with the primary key columns which are always used by the ORM. A similar function is available with less verbosity by using the -:func:`.orm.load_only` option. This is a so-called **exclusionary** option +:func:`_orm.load_only` option. This is a so-called **exclusionary** option which will apply deferred behavior to all column attributes except those that are named:: @@ -194,14 +194,14 @@ Wildcard and Exclusionary Options with Multiple-Entity Queries ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Wildcard options and exclusionary options such as :func:`.load_only` may -only be applied to a single entity at a time within a :class:`.Query`. To -suit the less common case where a :class:`.Query` is returning multiple +only be applied to a single entity at a time within a :class:`_query.Query`. To +suit the less common case where a :class:`_query.Query` is returning multiple primary entities at once, a special calling style may be required in order to apply a wildcard or exclusionary option, which is to use the -:class:`.Load` object to indicate the starting entity for a deferral option. -Such as, if we were loading ``Book`` and ``Author`` at once, the :class:`.Query` +:class:`_orm.Load` object to indicate the starting entity for a deferral option. +Such as, if we were loading ``Book`` and ``Author`` at once, the :class:`_query.Query` will raise an informative error if we try to apply :func:`.load_only` to -both at once. Using :class:`.Load` looks like:: +both at once. Using :class:`_orm.Load` looks like:: from sqlalchemy.orm import Load @@ -210,12 +210,12 @@ both at once. Using :class:`.Load` looks like:: Load(Book).load_only("summary", "excerpt") ) -Above, :class:`.Load` is used in conjunction with the exclusionary option +Above, :class:`_orm.Load` is used in conjunction with the exclusionary option :func:`.load_only` so that the deferral of all other columns only takes place for the ``Book`` class and not the ``Author`` class. Again, -the :class:`.Query` object should raise an informative error message when +the :class:`_query.Query` object should raise an informative error message when the above calling style is actually required that describes those cases -where explicit use of :class:`.Load` is needed. +where explicit use of :class:`_orm.Load` is needed. .. _deferred_raiseload: @@ -292,7 +292,7 @@ The bundle allows columns to be grouped together:: The bundle can be subclassed to provide custom behaviors when results are fetched. The method :meth:`.Bundle.create_row_processor` is given -the :class:`.Query` and a set of "row processor" functions at query execution +the :class:`_query.Query` and a set of "row processor" functions at query execution time; these processor functions when given a result row will return the individual attribute value, which can then be adapted into any kind of return data structure. Below illustrates replacing the usual :class:`.Row` diff --git a/doc/build/orm/loading_relationships.rst b/doc/build/orm/loading_relationships.rst index 7d6c72a805..a53ad1d3d5 100644 --- a/doc/build/orm/loading_relationships.rst +++ b/doc/build/orm/loading_relationships.rst @@ -7,10 +7,10 @@ Relationship Loading Techniques A big part of SQLAlchemy is providing a wide range of control over how related objects get loaded when querying. By "related objects" we refer to collections -or scalar associations configured on a mapper using :func:`.relationship`. +or scalar associations configured on a mapper using :func:`_orm.relationship`. This behavior can be configured at mapper construction time using the -:paramref:`.relationship.lazy` parameter to the :func:`.relationship` -function, as well as by using options with the :class:`.Query` object. +:paramref:`_orm.relationship.lazy` parameter to the :func:`_orm.relationship` +function, as well as by using options with the :class:`_query.Query` object. The loading of relationships falls into three categories; **lazy** loading, **eager** loading, and **no** loading. Lazy loading refers to objects are returned @@ -20,7 +20,7 @@ first accessed on a particular object, an additional SELECT statement is emitted such that the requested collection is loaded. Eager loading refers to objects returned from a query with the related -collection or scalar reference already loaded up front. The :class:`.Query` +collection or scalar reference already loaded up front. The :class:`_query.Query` achieves this either by augmenting the SELECT statement it would normally emit with a JOIN to load in related rows simultaneously, or by emitting additional SELECT statements after the primary one to load collections @@ -37,7 +37,7 @@ The primary forms of relationship loading are: attribute access time to lazily load a related reference on a single object at a time. Lazy loading is detailed at :ref:`lazy_loading`. -* **joined loading** - available via ``lazy='joined'`` or the :func:`.joinedload` +* **joined loading** - available via ``lazy='joined'`` or the :func:`_orm.joinedload` option, this form of loading applies a JOIN to the given SELECT statement so that related rows are loaded in the same result set. Joined eager loading is detailed at :ref:`joined_eager_loading`. @@ -73,8 +73,8 @@ Configuring Loader Strategies at Mapping Time The loader strategy for a particular relationship can be configured at mapping time to take place in all cases where an object of the mapped type is loaded, in the absence of any query-level options that modify it. -This is configured using the :paramref:`.relationship.lazy` parameter to -:func:`.relationship`; common values for this parameter +This is configured using the :paramref:`_orm.relationship.lazy` parameter to +:func:`_orm.relationship`; common values for this parameter include ``select``, ``joined``, ``subquery`` and ``selectin``. For example, to configure a relationship to use joined eager loading when @@ -91,7 +91,7 @@ Above, whenever a collection of ``Parent`` objects are loaded, each rows fetched by adding a JOIN to the query for ``Parent`` objects. See :ref:`joined_eager_loading` for background on this style of loading. -The default value of the :paramref:`.relationship.lazy` argument is +The default value of the :paramref:`_orm.relationship.lazy` argument is ``"select"``, which indicates lazy loading. See :ref:`lazy_loading` for further background. @@ -102,7 +102,7 @@ Relationship Loading with Loader Options The other, and possibly more common way to configure loading strategies is to set them up on a per-query basis against specific attributes using the -:meth:`.Query.options` method. Very detailed +:meth:`_query.Query.options` method. Very detailed control over relationship loading is available using loader options; the most common are :func:`~sqlalchemy.orm.joinedload`, @@ -150,7 +150,7 @@ of a particular attribute, the :func:`.defaultload` method/function may be used: joinedload(B.btoc)).all() A similar approach can be used to specify multiple sub-options at once, using -the :meth:`.Load.options` method:: +the :meth:`_orm.Load.options` method:: session.query(A).options( defaultload(A.atob).options( @@ -158,7 +158,7 @@ the :meth:`.Load.options` method:: joinedload(B.btod) )).all() -.. versionadded:: 1.3.6 added :meth:`.Load.options` +.. versionadded:: 1.3.6 added :meth:`_orm.Load.options` .. seealso:: @@ -185,7 +185,7 @@ the :meth:`.Load.options` method:: object is accessed from a subsequent query that specifies a different set of options.To change the options on an existing object without expunging it and re-loading, they must be set explicitly in conjunction with the - :meth:`.Query.populate_existing` method:: + :meth:`_query.Query.populate_existing` method:: # change the options on Parent objects that were already loaded session.query(Parent).populate_existing().options( @@ -257,7 +257,7 @@ accessing their lazy-loaded attributes means there will be N+1 SELECT statements emitted. In SQLAlchemy, the usual mitigation for the N+1 problem is to make use of its very capable eager load system. However, eager loading requires that the attributes which are to be loaded be specified with the -:class:`.Query` up front. The problem of code that may access other attributes +:class:`_query.Query` up front. The problem of code that may access other attributes that were not eagerly loaded, where lazy loading is not desired, may be addressed using the :func:`.raiseload` strategy; this loader strategy replaces the behavior of lazy loading with an informative error being @@ -280,7 +280,7 @@ to set up only one attribute as eager loading, and all the rest as raise:: The above wildcard will apply to **all** relationships not just on ``Order`` besides ``items``, but all those on the ``Item`` objects as well. To set up :func:`.raiseload` for only the ``Order`` objects, specify a full -path with :class:`.orm.Load`:: +path with :class:`_orm.Load`:: from sqlalchemy.orm import Load @@ -310,7 +310,7 @@ Joined Eager Loading Joined eager loading is the most fundamental style of eager loading in the ORM. It works by connecting a JOIN (by default -a LEFT OUTER join) to the SELECT statement emitted by a :class:`.Query` +a LEFT OUTER join) to the SELECT statement emitted by a :class:`_query.Query` and populates the target scalar/collection from the same result set as that of the parent. @@ -324,7 +324,7 @@ At the mapping level, this looks like:: Joined eager loading is usually applied as an option to a query, rather than as a default loading option on the mapping, in particular when used for collections rather than many-to-one-references. This is achieved -using the :func:`.joinedload` loader option: +using the :func:`_orm.joinedload` loader option: .. sourcecode:: python+sql @@ -350,7 +350,7 @@ that does not refer to a related row. For an attribute that is guaranteed to have an element, such as a many-to-one reference to a related object where the referencing foreign key is NOT NULL, the query can be made more efficient by using an inner join; this is available -at the mapping level via the :paramref:`.relationship.innerjoin` flag:: +at the mapping level via the :paramref:`_orm.relationship.innerjoin` flag:: class Address(Base): # ... @@ -358,7 +358,7 @@ at the mapping level via the :paramref:`.relationship.innerjoin` flag:: user_id = Column(ForeignKey('users.id'), nullable=False) user = relationship(User, lazy="joined", innerjoin=True) -At the query option level, via the :paramref:`.joinedload.innerjoin` flag:: +At the query option level, via the :paramref:`_orm.joinedload.innerjoin` flag:: session.query(Address).options( joinedload(Address.user, innerjoin=True)) @@ -394,10 +394,10 @@ Joined eager loading and result set batching ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A central concept of joined eager loading when applied to collections is that -the :class:`.Query` object must de-duplicate rows against the leading +the :class:`_query.Query` object must de-duplicate rows against the leading entity being queried. Such as above, if the ``User`` object we loaded referred to three ``Address`` objects, the -result of the SQL statement would have had three rows; yet the :class:`.Query` +result of the SQL statement would have had three rows; yet the :class:`_query.Query` returns only one ``User`` object. As additional rows are received for a ``User`` object just loaded in a previous row, the additional columns that refer to new ``Address`` objects are directed into additional results within @@ -405,9 +405,9 @@ the ``User.addresses`` collection of that particular object. This process is very transparent, however does imply that joined eager loading is incompatible with "batched" query results, provided by the -:meth:`.Query.yield_per` method, when used for collection loading. Joined +:meth:`_query.Query.yield_per` method, when used for collection loading. Joined eager loading used for scalar references is however compatible with -:meth:`.Query.yield_per`. The :meth:`.Query.yield_per` method will result +:meth:`_query.Query.yield_per`. The :meth:`_query.Query.yield_per` method will result in an exception thrown if a collection based joined eager loader is in play. @@ -415,7 +415,7 @@ To "batch" queries with arbitrarily large sets of result data while maintaining compatibility with collection-based joined eager loading, emit multiple SELECT statements, each referring to a subset of rows using the WHERE clause, e.g. windowing. Alternatively, consider using "select IN" eager loading -which is **potentially** compatible with :meth:`.Query.yield_per`, provided +which is **potentially** compatible with :meth:`_query.Query.yield_per`, provided that the database driver in use supports multiple, simultaneous cursors (SQLite, PostgreSQL drivers, not MySQL drivers or SQL Server ODBC drivers). @@ -426,9 +426,9 @@ The Zen of Joined Eager Loading ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Since joined eager loading seems to have many resemblances to the use of -:meth:`.Query.join`, it often produces confusion as to when and how it should +:meth:`_query.Query.join`, it often produces confusion as to when and how it should be used. It is critical to understand the distinction that while -:meth:`.Query.join` is used to alter the results of a query, :func:`.joinedload` +:meth:`_query.Query.join` is used to alter the results of a query, :func:`_orm.joinedload` goes through great lengths to **not** alter the results of the query, and instead hide the effects of the rendered join to only allow for related objects to be present. @@ -442,13 +442,13 @@ are always accessed, and that it would be more efficient to change the loader strategy for these. The strategy can be changed with no other modifications to the query, the results will remain identical, but fewer SQL statements would be emitted. In theory (and pretty much in practice), nothing you can do to the -:class:`.Query` would make it load a different set of primary or related +:class:`_query.Query` would make it load a different set of primary or related objects based on a change in loader strategy. How :func:`joinedload` in particular achieves this result of not impacting entity rows returned in any way is that it creates an anonymous alias of the joins it adds to your query, so that they can't be referenced by other parts of -the query. For example, the query below uses :func:`.joinedload` to create a +the query. For example, the query below uses :func:`_orm.joinedload` to create a LEFT OUTER JOIN from ``users`` to ``addresses``, however the ``ORDER BY`` added against ``Address.email_address`` is not valid - the ``Address`` entity is not named in the query: @@ -476,7 +476,7 @@ named in the query: Above, ``ORDER BY addresses.email_address`` is not valid since ``addresses`` is not in the FROM list. The correct way to load the ``User`` records and order by email -address is to use :meth:`.Query.join`: +address is to use :meth:`_query.Query.join`: .. sourcecode:: python+sql @@ -498,7 +498,7 @@ address is to use :meth:`.Query.join`: The statement above is of course not the same as the previous one, in that the columns from ``addresses`` are not included in the result at all. We can add -:func:`.joinedload` back in, so that there are two joins - one is that which we +:func:`_orm.joinedload` back in, so that there are two joins - one is that which we are ordering on, the other is used anonymously to load the contents of the ``User.addresses`` collection: @@ -524,9 +524,9 @@ are ordering on, the other is used anonymously to load the contents of the ORDER BY addresses.email_address ['jack'] -What we see above is that our usage of :meth:`.Query.join` is to supply JOIN +What we see above is that our usage of :meth:`_query.Query.join` is to supply JOIN clauses we'd like to use in subsequent query criterion, whereas our usage of -:func:`.joinedload` only concerns itself with the loading of the +:func:`_orm.joinedload` only concerns itself with the loading of the ``User.addresses`` collection, for each ``User`` in the result. In this case, the two joins most probably appear redundant - which they are. If we wanted to use just one JOIN for collection loading as well as ordering, we use the @@ -563,9 +563,9 @@ will match *all* ``Address`` rows related to ``User``, and is only used to populate the ``User.addresses`` collection, for those ``User`` objects that are returned. -By changing the usage of :func:`.joinedload` to another style of loading, we +By changing the usage of :func:`_orm.joinedload` to another style of loading, we can change how the collection is loaded completely independently of SQL used to -retrieve the actual ``User`` rows we want. Below we change :func:`.joinedload` +retrieve the actual ``User`` rows we want. Below we change :func:`_orm.joinedload` into :func:`.subqueryload`: .. sourcecode:: python+sql @@ -610,10 +610,10 @@ Subquery Eager Loading ---------------------- Subqueryload eager loading is configured in the same manner as that of -joined eager loading; for the :paramref:`.relationship.lazy` parameter, +joined eager loading; for the :paramref:`_orm.relationship.lazy` parameter, we would specify ``"subquery"`` rather than ``"joined"``, and for the option we use the :func:`.subqueryload` option rather than the -:func:`.joinedload` option. +:func:`_orm.joinedload` option. The operation of subquery eager loading is to emit a second SELECT statement for each relationship to be loaded, across all result objects at once. @@ -663,7 +663,7 @@ query is transferred to the relationship queries, which when combined with the use of a subquery, can on some backends in some cases (notably MySQL) produce significantly slow queries. Additionally, the subqueryload strategy can only load the full contents of all collections at once, is therefore incompatible -with "batched" loading supplied by :meth:`.Query.yield_per`, both for collection +with "batched" loading supplied by :meth:`_query.Query.yield_per`, both for collection and scalar relationships. The newer style of loading provided by :func:`.selectinload` solves these @@ -680,8 +680,8 @@ The Importance of Ordering ^^^^^^^^^^^^^^^^^^^^^^^^^^ A query which makes use of :func:`.subqueryload` in conjunction with a -limiting modifier such as :meth:`.Query.first`, :meth:`.Query.limit`, -or :meth:`.Query.offset` should **always** include :meth:`.Query.order_by` +limiting modifier such as :meth:`_query.Query.first`, :meth:`_query.Query.limit`, +or :meth:`_query.Query.offset` should **always** include :meth:`_query.Query.order_by` against unique column(s) such as the primary key, so that the additional queries emitted by :func:`.subqueryload` include the same ordering as used by the parent query. Without it, there is a chance @@ -715,7 +715,7 @@ the SELECT statement which is emitted has a much simpler structure than that of subquery eager loading. Additionally, select IN loading applies itself to subsets of the load result at a time, so unlike joined and subquery eager loading, is compatible with batching of results using -:meth:`.Query.yield_per`, provided the database driver supports simultaneous +:meth:`_query.Query.yield_per`, provided the database driver supports simultaneous cursors. Overall, especially as of the 1.3 series of SQLAlchemy, selectin loading @@ -728,7 +728,7 @@ SQL Server. .. versionadded:: 1.2 "Select IN" eager loading is provided using the ``"selectin"`` argument to -:paramref:`.relationship.lazy` or by using the :func:`.selectinload` loader +:paramref:`_orm.relationship.lazy` or by using the :func:`.selectinload` loader option. This style of loading emits a SELECT that refers to the primary key values of the parent object, or in the case of a simple many-to-one relationship to the those of the child objects, inside of an IN clause, in @@ -835,11 +835,11 @@ as of the 1.2 series. Things to know about this kind of loading include: SQL overhead as they query against primary key directly. * "selectin" loading is the only eager loading that can work in conjunction with - the "batching" feature provided by :meth:`.Query.yield_per`, provided + the "batching" feature provided by :meth:`_query.Query.yield_per`, provided the database driver supports simultaneous cursors. As it only queries for related items against specific result objects, "selectin" loading allows for eagerly loaded collections against arbitrarily large result sets - with a top limit on memory use when used with :meth:`.Query.yield_per`. + with a top limit on memory use when used with :meth:`_query.Query.yield_per`. Current database drivers that support simultaneous cursors include SQLite, PostgreSQL. The MySQL drivers mysqlclient and pymysql currently @@ -921,7 +921,7 @@ references a scalar many-to-one reference. * selectin loading, unlike joined (when using collections) and subquery eager loading (all kinds of relationships), is potentially compatible with result - set batching provided by :meth:`.Query.yield_per` assuming an appropriate + set batching provided by :meth:`_query.Query.yield_per` assuming an appropriate database driver, so may be able to allow batching for large result sets. * Many to One Reference @@ -929,7 +929,7 @@ references a scalar many-to-one reference. * When using the default lazy loading, a load of 100 objects will like in the case of the collection emit as many as 101 SQL statements. However - there is a significant exception to this, in that if the many-to-one reference is a simple foreign key reference to the target's primary key, each - reference will be checked first in the current identity map using :meth:`.Query.get`. So here, + reference will be checked first in the current identity map using :meth:`_query.Query.get`. So here, if the collection of objects references a relatively small set of target objects, or the full set of possible target objects have already been loaded into the session and are strongly referenced, using the default of `lazy='select'` is by far the most efficient way to go. @@ -938,7 +938,7 @@ references a scalar many-to-one reference. will be a LEFT OUTER JOIN, and the total number of rows will be equal to 100 in all cases. If you know that each parent definitely has a child (i.e. the foreign key reference is NOT NULL), the joined load can be configured with - :paramref:`~.relationship.innerjoin` set to ``True``, which is + :paramref:`_orm.relationship.innerjoin` set to ``True``, which is usually specified within the :func:`~sqlalchemy.orm.relationship`. For a load of objects where there are many possible target references which may have not been loaded already, joined loading with an INNER JOIN is extremely efficient. @@ -961,26 +961,26 @@ Polymorphic Eager Loading Specification of polymorphic options on a per-eager-load basis is supported. See the section :ref:`eagerloading_polymorphic_subtypes` for examples of the :meth:`.PropComparator.of_type` method in conjunction with the -:func:`.orm.with_polymorphic` function. +:func:`_orm.with_polymorphic` function. .. _wildcard_loader_strategies: Wildcard Loading Strategies --------------------------- -Each of :func:`.joinedload`, :func:`.subqueryload`, :func:`.lazyload`, +Each of :func:`_orm.joinedload`, :func:`.subqueryload`, :func:`.lazyload`, :func:`.selectinload`, :func:`.noload`, and :func:`.raiseload` can be used to set the default -style of :func:`.relationship` loading -for a particular query, affecting all :func:`.relationship` -mapped +style of :func:`_orm.relationship` loading +for a particular query, affecting all :func:`_orm.relationship` -mapped attributes not otherwise -specified in the :class:`.Query`. This feature is available by passing +specified in the :class:`_query.Query`. This feature is available by passing the string ``'*'`` as the argument to any of these options:: session.query(MyClass).options(lazyload('*')) Above, the ``lazyload('*')`` option will supersede the ``lazy`` setting -of all :func:`.relationship` constructs in use for that query, +of all :func:`_orm.relationship` constructs in use for that query, except for those which use the ``'dynamic'`` style of loading. If some relationships specify ``lazy='joined'`` or ``lazy='subquery'``, for example, @@ -1007,7 +1007,7 @@ Per-Entity Wildcard Loading Strategies A variant of the wildcard loader strategy is the ability to set the strategy on a per-entity basis. For example, if querying for ``User`` and ``Address``, we can instruct all relationships on ``Address`` only to use lazy loading -by first applying the :class:`.Load` object, then specifying the ``*`` as a +by first applying the :class:`_orm.Load` object, then specifying the ``*`` as a chained option:: session.query(User, Address).options( @@ -1053,7 +1053,7 @@ and additionally establish this as the basis for eager loading of ``User.address If the "eager" portion of the statement is "aliased", the ``alias`` keyword argument to :func:`~sqlalchemy.orm.contains_eager` may be used to indicate it. -This is sent as a reference to an :func:`.aliased` or :class:`.Alias` +This is sent as a reference to an :func:`.aliased` or :class:`_expression.Alias` construct: .. sourcecode:: python+sql @@ -1142,7 +1142,7 @@ Advanced Usage with Arbitrary Statements The ``alias`` argument can be more creatively used, in that it can be made to represent any set of arbitrary names to match up into a statement. -Below it is linked to a :func:`~.sql.expression.select` which links a set of column objects +Below it is linked to a :func:`_expression.select` which links a set of column objects to a string SQL statement:: # label the columns of the addresses table diff --git a/doc/build/orm/mapped_attributes.rst b/doc/build/orm/mapped_attributes.rst index 535c075c94..b8a0f89c94 100644 --- a/doc/build/orm/mapped_attributes.rst +++ b/doc/build/orm/mapped_attributes.rst @@ -107,7 +107,7 @@ Using Custom Datatypes at the Core Level A non-ORM means of affecting the value of a column in a way that suits converting data between how it is represented in Python, vs. how it is represented in the database, can be achieved by using a custom datatype that is -applied to the mapped :class:`.Table` metadata. This is more common in the +applied to the mapped :class:`_schema.Table` metadata. This is more common in the case of some style of encoding / decoding that occurs both as data goes to the database and as it is returned; read more about this in the Core documentation at :ref:`types_typedecorator`. @@ -147,7 +147,7 @@ The approach above will work, but there's more we can add. While our ``EmailAddress`` object will shuttle the value through the ``email`` descriptor and into the ``_email`` mapped attribute, the class level ``EmailAddress.email`` attribute does not have the usual expression semantics -usable with :class:`.Query`. To provide these, we instead use the +usable with :class:`_query.Query`. To provide these, we instead use the :mod:`~sqlalchemy.ext.hybrid` extension as follows:: from sqlalchemy.ext.hybrid import hybrid_property @@ -343,7 +343,7 @@ which take place for column expressions are most directly redefined at the type level - see the section :ref:`types_operators` for a description. -ORM level functions like :func:`.column_property`, :func:`.relationship`, +ORM level functions like :func:`.column_property`, :func:`_orm.relationship`, and :func:`.composite` also provide for operator redefinition at the ORM level, by passing a :class:`.PropComparator` subclass to the ``comparator_factory`` argument of each function. Customization of operators at this level is a diff --git a/doc/build/orm/mapped_sql_expr.rst b/doc/build/orm/mapped_sql_expr.rst index 367139d197..f7ee2020ec 100644 --- a/doc/build/orm/mapped_sql_expr.rst +++ b/doc/build/orm/mapped_sql_expr.rst @@ -46,7 +46,7 @@ can be dual purposed at the instance and class level. Often, the SQL expression must be distinguished from the Python expression, which can be achieved using :meth:`.hybrid_property.expression`. Below we illustrate the case where a conditional needs to be present inside the hybrid, using the ``if`` statement in Python and the -:func:`.sql.expression.case` construct for SQL expressions:: +:func:`_expression.case` construct for SQL expressions:: from sqlalchemy.ext.hybrid import hybrid_property from sqlalchemy.sql import case @@ -75,8 +75,8 @@ needs to be present inside the hybrid, using the ``if`` statement in Python and Using column_property --------------------- -The :func:`.orm.column_property` function can be used to map a SQL -expression in a manner similar to a regularly mapped :class:`.Column`. +The :func:`_orm.column_property` function can be used to map a SQL +expression in a manner similar to a regularly mapped :class:`_schema.Column`. With this technique, the attribute is loaded along with all other column-mapped attributes at load time. This is in some cases an advantage over the usage of hybrids, as the value can be loaded @@ -85,12 +85,12 @@ the expression is one which links to other tables (typically as a correlated subquery) to access data that wouldn't normally be available on an already loaded object. -Disadvantages to using :func:`.orm.column_property` for SQL expressions include that +Disadvantages to using :func:`_orm.column_property` for SQL expressions include that the expression must be compatible with the SELECT statement emitted for the class as a whole, and there are also some configurational quirks which can occur -when using :func:`.orm.column_property` from declarative mixins. +when using :func:`_orm.column_property` from declarative mixins. -Our "fullname" example can be expressed using :func:`.orm.column_property` as +Our "fullname" example can be expressed using :func:`_orm.column_property` as follows:: from sqlalchemy.orm import column_property @@ -102,7 +102,7 @@ follows:: lastname = Column(String(50)) fullname = column_property(firstname + " " + lastname) -Correlated subqueries may be used as well. Below we use the :func:`~.sql.expression.select` +Correlated subqueries may be used as well. Below we use the :func:`_expression.select` construct to create a SELECT that links together the count of ``Address`` objects available for a particular ``User``:: @@ -128,7 +128,7 @@ objects available for a particular ``User``:: correlate_except(Address) ) -In the above example, we define a :func:`~.sql.expression.select` construct like the following:: +In the above example, we define a :func:`_expression.select` construct like the following:: select([func.count(Address.id)]).\ where(Address.user_id==id).\ @@ -136,12 +136,12 @@ In the above example, we define a :func:`~.sql.expression.select` construct like The meaning of the above statement is, select the count of ``Address.id`` rows where the ``Address.user_id`` column is equated to ``id``, which in the context -of the ``User`` class is the :class:`.Column` named ``id`` (note that ``id`` is +of the ``User`` class is the :class:`_schema.Column` named ``id`` (note that ``id`` is also the name of a Python built in function, which is not what we want to use here - if we were outside of the ``User`` class definition, we'd use ``User.id``). -The :meth:`.select.correlate_except` directive indicates that each element in the -FROM clause of this :func:`~.sql.expression.select` may be omitted from the FROM list (that is, correlated +The :meth:`_expression.select.correlate_except` directive indicates that each element in the +FROM clause of this :func:`_expression.select` may be omitted from the FROM list (that is, correlated to the enclosing SELECT statement against ``User``) except for the one corresponding to ``Address``. This isn't strictly necessary, but prevents ``Address`` from being inadvertently omitted from the FROM list in the case of a long string @@ -150,7 +150,7 @@ of joins between ``User`` and ``Address`` tables where SELECT statements against If import issues prevent the :func:`.column_property` from being defined inline with the class, it can be assigned to the class after both -are configured. In Declarative this has the effect of calling :meth:`.Mapper.add_property` +are configured. In Declarative this has the effect of calling :meth:`_orm.Mapper.add_property` to add an additional property after the fact:: User.address_count = column_property( @@ -217,7 +217,7 @@ the :class:`.ColumnProperty` directly within the mapping definition:: Using a plain descriptor ------------------------ -In cases where a SQL query more elaborate than what :func:`.orm.column_property` +In cases where a SQL query more elaborate than what :func:`_orm.column_property` or :class:`.hybrid_property` can provide must be emitted, a regular Python function accessed as an attribute can be used, assuming the expression only needs to be available on an already-loaded instance. The function @@ -295,7 +295,7 @@ The :func:`.query_expression` mapping has these caveats: expired**. Once the object is expired, either via :meth:`.Session.expire` or via the expire_on_commit behavior of :meth:`.Session.commit`, the value is removed from the attribute and will return ``None`` on subsequent access. - Only by running a new :class:`.Query` that touches the object which includes + Only by running a new :class:`_query.Query` that touches the object which includes a new :func:`.with_expression` directive will the attribute be set to a non-None value. diff --git a/doc/build/orm/mapping_columns.rst b/doc/build/orm/mapping_columns.rst index 71e145747c..5423a84eb7 100644 --- a/doc/build/orm/mapping_columns.rst +++ b/doc/build/orm/mapping_columns.rst @@ -3,10 +3,10 @@ Mapping Table Columns ===================== -The default behavior of :func:`~.orm.mapper` is to assemble all the columns in -the mapped :class:`.Table` into mapped object attributes, each of which are +The default behavior of :func:`_orm.mapper` is to assemble all the columns in +the mapped :class:`_schema.Table` into mapped object attributes, each of which are named according to the name of the column itself (specifically, the ``key`` -attribute of :class:`.Column`). This behavior can be +attribute of :class:`_schema.Column`). This behavior can be modified in several ways. .. _mapper_column_distinct_names: @@ -15,12 +15,12 @@ Naming Columns Distinctly from Attribute Names ---------------------------------------------- A mapping by default shares the same name for a -:class:`.Column` as that of the mapped attribute - specifically -it matches the :attr:`.Column.key` attribute on :class:`.Column`, which -by default is the same as the :attr:`.Column.name`. +:class:`_schema.Column` as that of the mapped attribute - specifically +it matches the :attr:`_schema.Column.key` attribute on :class:`_schema.Column`, which +by default is the same as the :attr:`_schema.Column.name`. The name assigned to the Python attribute which maps to -:class:`.Column` can be different from either :attr:`.Column.name` or :attr:`.Column.key` +:class:`_schema.Column` can be different from either :attr:`_schema.Column.name` or :attr:`_schema.Column.key` just by assigning it that way, as we illustrate here in a Declarative mapping:: class User(Base): @@ -31,7 +31,7 @@ just by assigning it that way, as we illustrate here in a Declarative mapping:: Where above ``User.id`` resolves to a column named ``user_id`` and ``User.name`` resolves to a column named ``user_name``. -When mapping to an existing table, the :class:`.Column` object +When mapping to an existing table, the :class:`_schema.Column` object can be referenced directly:: class User(Base): @@ -55,27 +55,27 @@ Automating Column Naming Schemes from Reflected Tables ------------------------------------------------------ In the previous section :ref:`mapper_column_distinct_names`, we showed how -a :class:`.Column` explicitly mapped to a class can have a different attribute -name than the column. But what if we aren't listing out :class:`.Column` -objects explicitly, and instead are automating the production of :class:`.Table` +a :class:`_schema.Column` explicitly mapped to a class can have a different attribute +name than the column. But what if we aren't listing out :class:`_schema.Column` +objects explicitly, and instead are automating the production of :class:`_schema.Table` objects using reflection (e.g. as described in :ref:`metadata_reflection_toplevel`)? In this case we can make use of the :meth:`.DDLEvents.column_reflect` event -to intercept the production of :class:`.Column` objects and provide them -with the :attr:`.Column.key` of our choice:: +to intercept the production of :class:`_schema.Column` objects and provide them +with the :attr:`_schema.Column.key` of our choice:: @event.listens_for(Table, "column_reflect") def column_reflect(inspector, table, column_info): # set column.key = "attr_" column_info['key'] = "attr_%s" % column_info['name'].lower() -With the above event, the reflection of :class:`.Column` objects will be intercepted +With the above event, the reflection of :class:`_schema.Column` objects will be intercepted with our event that adds a new ".key" element, such as in a mapping as below:: class MyClass(Base): __table__ = Table("some_table", Base.metadata, autoload=True, autoload_with=some_engine) -If we want to qualify our event to only react for the specific :class:`.MetaData` +If we want to qualify our event to only react for the specific :class:`_schema.MetaData` object above, we can check for it in our event:: @event.listens_for(Table, "column_reflect") @@ -90,7 +90,7 @@ Naming All Columns with a Prefix -------------------------------- A quick approach to prefix column names, typically when mapping -to an existing :class:`.Table` object, is to use ``column_prefix``:: +to an existing :class:`_schema.Table` object, is to use ``column_prefix``:: class User(Base): __table__ = user_table @@ -108,12 +108,12 @@ tables, a more flexible approach is to use that described in Using column_property for column level options ---------------------------------------------- -Options can be specified when mapping a :class:`.Column` using the +Options can be specified when mapping a :class:`_schema.Column` using the :func:`.column_property` function. This function explicitly creates the :class:`.ColumnProperty` used by the -:func:`.mapper` to keep track of the :class:`.Column`; normally, the +:func:`.mapper` to keep track of the :class:`_schema.Column`; normally, the :func:`.mapper` creates this automatically. Using :func:`.column_property`, -we can pass additional arguments about how we'd like the :class:`.Column` +we can pass additional arguments about how we'd like the :class:`_schema.Column` to be mapped. Below, we pass an option ``active_history``, which specifies that a change to this column's value should result in the former value being loaded first:: @@ -127,7 +127,7 @@ result in the former value being loaded first:: name = column_property(Column(String(50)), active_history=True) :func:`.column_property` is also used to map a single attribute to -multiple columns. This use case arises when mapping to a :func:`~.expression.join` +multiple columns. This use case arises when mapping to a :func:`_expression.join` which has attributes which are equated to each other:: class User(Base): @@ -160,7 +160,7 @@ See examples of this usage at :ref:`mapper_sql_expressions`. Mapping a Subset of Table Columns --------------------------------- -Sometimes, a :class:`.Table` object was made available using the +Sometimes, a :class:`_schema.Table` object was made available using the reflection process described at :ref:`metadata_reflection` to load the table's structure from the database. For such a table that has lots of columns that don't need to be referenced @@ -188,7 +188,7 @@ Similarly:: all columns present except ``street``, ``city``, ``state``, and ``zip``. When this mapping is used, the columns that are not included will not be -referenced in any SELECT statements emitted by :class:`.Query`, nor will there +referenced in any SELECT statements emitted by :class:`_query.Query`, nor will there be any mapped attribute on the mapped class which represents the column; assigning an attribute of that name will have no effect beyond that of a normal Python attribute assignment. @@ -196,7 +196,7 @@ a normal Python attribute assignment. In some cases, multiple columns may have the same name, such as when mapping to a join of two or more tables that share some column name. ``include_properties`` and ``exclude_properties`` can also accommodate -:class:`.Column` objects to more accurately describe which columns +:class:`_schema.Column` objects to more accurately describe which columns should be included or excluded:: class UserAddress(Base): @@ -208,17 +208,17 @@ should be included or excluded:: .. note:: - insert and update defaults configured on individual :class:`.Column` + insert and update defaults configured on individual :class:`_schema.Column` objects, i.e. those described at :ref:`metadata_defaults` including those - configured by the :paramref:`.Column.default`, - :paramref:`.Column.onupdate`, :paramref:`.Column.server_default` and - :paramref:`.Column.server_onupdate` parameters, will continue to function - normally even if those :class:`.Column` objects are not mapped. This is - because in the case of :paramref:`.Column.default` and - :paramref:`.Column.onupdate`, the :class:`.Column` object is still present - on the underlying :class:`.Table`, thus allowing the default functions to + configured by the :paramref:`_schema.Column.default`, + :paramref:`_schema.Column.onupdate`, :paramref:`_schema.Column.server_default` and + :paramref:`_schema.Column.server_onupdate` parameters, will continue to function + normally even if those :class:`_schema.Column` objects are not mapped. This is + because in the case of :paramref:`_schema.Column.default` and + :paramref:`_schema.Column.onupdate`, the :class:`_schema.Column` object is still present + on the underlying :class:`_schema.Table`, thus allowing the default functions to take place when the ORM emits an INSERT or UPDATE, and in the case of - :paramref:`.Column.server_default` and :paramref:`.Column.server_onupdate`, + :paramref:`_schema.Column.server_default` and :paramref:`_schema.Column.server_onupdate`, the relational database itself emits these defaults as a server side behavior. diff --git a/doc/build/orm/mapping_styles.rst b/doc/build/orm/mapping_styles.rst index b8cb2797b7..f76e452116 100644 --- a/doc/build/orm/mapping_styles.rst +++ b/doc/build/orm/mapping_styles.rst @@ -7,7 +7,7 @@ The "Classical" style is SQLAlchemy's original mapping API, whereas "Declarative" is the richer and more succinct system that builds on top of "Classical". Both styles may be used interchangeably, as the end result of each is exactly the same - a user-defined class mapped by the -:func:`.mapper` function onto a selectable unit, typically a :class:`.Table`. +:func:`.mapper` function onto a selectable unit, typically a :class:`_schema.Table`. Declarative Mapping =================== @@ -16,7 +16,7 @@ The *Declarative Mapping* is the typical way that mappings are constructed in modern SQLAlchemy. Making use of the :ref:`declarative_toplevel` system, the components of the user-defined class as well as the -:class:`.Table` metadata to which the class is mapped are defined +:class:`_schema.Table` metadata to which the class is mapped are defined at once:: from sqlalchemy.ext.declarative import declarative_base @@ -68,7 +68,7 @@ SQLAlchemy's original class mapping API, and is still the base mapping system provided by the ORM. In "classical" form, the table metadata is created separately with the -:class:`.Table` construct, then associated with the ``User`` class via +:class:`_schema.Table` construct, then associated with the ``User`` class via the :func:`.mapper` function:: from sqlalchemy import Table, MetaData, Column, Integer, String, ForeignKey @@ -92,8 +92,8 @@ the :func:`.mapper` function:: mapper(User, user) Information about mapped attributes, such as relationships to other classes, are provided -via the ``properties`` dictionary. The example below illustrates a second :class:`.Table` -object, mapped to a class called ``Address``, then linked to ``User`` via :func:`.relationship`:: +via the ``properties`` dictionary. The example below illustrates a second :class:`_schema.Table` +object, mapped to a class called ``Address``, then linked to ``User`` via :func:`_orm.relationship`:: address = Table('address', metadata, Column('id', Integer, primary_key=True), @@ -109,13 +109,13 @@ object, mapped to a class called ``Address``, then linked to ``User`` via :func: When using classical mappings, classes must be provided directly without the benefit of the "string lookup" system provided by Declarative. SQL expressions are typically -specified in terms of the :class:`.Table` objects, i.e. ``address.c.id`` above +specified in terms of the :class:`_schema.Table` objects, i.e. ``address.c.id`` above for the ``Address`` relationship, and not ``Address.id``, as ``Address`` may not yet be linked to table metadata, nor can we specify a string here. Some examples in the documentation still use the classical approach, but note that the classical as well as Declarative approaches are **fully interchangeable**. Both -systems ultimately create the same configuration, consisting of a :class:`.Table`, +systems ultimately create the same configuration, consisting of a :class:`_schema.Table`, user-defined class, linked together with a :func:`.mapper`. When we talk about "the behavior of :func:`.mapper`", this includes when using the Declarative system as well - it's still used, just behind the scenes. @@ -123,15 +123,15 @@ as well - it's still used, just behind the scenes. Runtime Introspection of Mappings, Objects ========================================== -The :class:`.Mapper` object is available from any mapped class, regardless +The :class:`_orm.Mapper` object is available from any mapped class, regardless of method, using the :ref:`core_inspection_toplevel` system. Using the -:func:`.inspect` function, one can acquire the :class:`.Mapper` from a +:func:`_sa.inspect` function, one can acquire the :class:`_orm.Mapper` from a mapped class:: >>> from sqlalchemy import inspect >>> insp = inspect(User) -Detailed information is available including :attr:`.Mapper.columns`:: +Detailed information is available including :attr:`_orm.Mapper.columns`:: >>> insp.columns @@ -144,7 +144,7 @@ via individual names:: >>> insp.columns.name Column('name', String(length=50), table=) -Other namespaces include :attr:`.Mapper.all_orm_descriptors`, which includes all mapped +Other namespaces include :attr:`_orm.Mapper.all_orm_descriptors`, which includes all mapped attributes as well as hybrids, association proxies:: >>> insp.all_orm_descriptors @@ -152,7 +152,7 @@ attributes as well as hybrids, association proxies:: >>> insp.all_orm_descriptors.keys() ['fullname', 'nickname', 'name', 'id'] -As well as :attr:`.Mapper.column_attrs`:: +As well as :attr:`_orm.Mapper.column_attrs`:: >>> list(insp.column_attrs) [, , , ] @@ -165,6 +165,6 @@ As well as :attr:`.Mapper.column_attrs`:: :ref:`core_inspection_toplevel` - :class:`.Mapper` + :class:`_orm.Mapper` :class:`.InstanceState` diff --git a/doc/build/orm/nonstandard_mappings.rst b/doc/build/orm/nonstandard_mappings.rst index 5223598546..01a615ae23 100644 --- a/doc/build/orm/nonstandard_mappings.rst +++ b/doc/build/orm/nonstandard_mappings.rst @@ -8,10 +8,10 @@ Mapping a Class against Multiple Tables ======================================= Mappers can be constructed against arbitrary relational units (called -*selectables*) in addition to plain tables. For example, the :func:`~.expression.join` +*selectables*) in addition to plain tables. For example, the :func:`_expression.join` function creates a selectable unit comprised of multiple tables, complete with its own composite primary key, which can be -mapped in the same way as a :class:`.Table`:: +mapped in the same way as a :class:`_schema.Table`:: from sqlalchemy import Table, Column, Integer, \ String, MetaData, join, ForeignKey @@ -95,8 +95,8 @@ is represented from an ``AddressUser`` object as connection.execute(q_table.insert(), {"id": target.id}) where above, a row is INSERTed into the ``q_table`` table by creating an - INSERT construct with :meth:`.Table.insert`, then executing it using the - given :class:`.Connection` which is the same one being used to emit other + INSERT construct with :meth:`_schema.Table.insert`, then executing it using the + given :class:`_engine.Connection` which is the same one being used to emit other SQL for the flush process. The user-supplied logic would have to detect that the LEFT OUTER JOIN from "p" to "q" does not have an entry for the "q" side. @@ -105,9 +105,9 @@ is represented from an ``AddressUser`` object as Mapping a Class against Arbitrary Selects ========================================= -Similar to mapping against a join, a plain :func:`~.expression.select` object can be used with a +Similar to mapping against a join, a plain :func:`_expression.select` object can be used with a mapper as well. The example fragment below illustrates mapping a class -called ``Customer`` to a :func:`~.expression.select` which includes a join to a +called ``Customer`` to a :func:`_expression.select` which includes a join to a subquery:: from sqlalchemy import select, func @@ -149,7 +149,7 @@ key. by direct query construction. The practice is to some degree based on the very early history of SQLAlchemy where the :func:`.mapper` construct was meant to represent the primary querying interface; - in modern usage, the :class:`.Query` object can be used to construct + in modern usage, the :class:`_query.Query` object can be used to construct virtually any SELECT statement, including complex composites, and should be favored over the "map-to-selectable" approach. @@ -161,7 +161,7 @@ In modern SQLAlchemy, a particular class is mapped by only one so-called functionality: querying, persistence, and instrumentation of the mapped class. The rationale of the primary mapper relates to the fact that the :func:`.mapper` modifies the class itself, not only persisting it towards a -particular :class:`.Table`, but also :term:`instrumenting` attributes upon the +particular :class:`_schema.Table`, but also :term:`instrumenting` attributes upon the class which are structured specifically according to the table metadata. It's not possible for more than one mapper to be associated with a class in equal measure, since only one mapper can actually instrument the class. diff --git a/doc/build/orm/persistence_techniques.rst b/doc/build/orm/persistence_techniques.rst index 6d41f90aa0..f0a01d7ea1 100644 --- a/doc/build/orm/persistence_techniques.rst +++ b/doc/build/orm/persistence_techniques.rst @@ -177,7 +177,7 @@ hold as an assumption. So what if we want to actually put NULL into this column, even though the column has a default value? There are two approaches. One is that on a per-instance level, we assign the attribute using the -:obj:`~.expression.null` SQL construct:: +:obj:`_expression.null` SQL construct:: from sqlalchemy import null @@ -188,7 +188,7 @@ on a per-instance level, we assign the attribute using the # and server-side defaults, and the database will # persist this as the NULL value -The :obj:`~.expression.null` SQL construct always translates into the SQL +The :obj:`_expression.null` SQL construct always translates into the SQL NULL value being directly present in the target INSERT statement. If we'd like to be able to use the Python value ``None`` and have this @@ -245,7 +245,7 @@ SQLAlchemy Core supports a method of retrieving these primary key values which is often native to the Python DBAPI, and in general this process is automatic, with the exception of a database like Oracle that requires us to specify a :class:`.Sequence` explicitly. There is more documentation regarding this -at :paramref:`.Column.autoincrement`. +at :paramref:`_schema.Column.autoincrement`. For server-generating columns that are not primary key columns or that are not simple autoincrementing integer columns, the ORM requires that these columns @@ -263,7 +263,7 @@ Case 1: non primary key, RETURNING or equivalent is supported ------------------------------------------------------------- In this case, columns should be marked as :class:`.FetchedValue` or with an -explicit :paramref:`.Column.server_default`. The +explicit :paramref:`_schema.Column.server_default`. The :paramref:`.orm.mapper.eager_defaults` flag may be used to indicate that these columns should be fetched immediately upon INSERT and sometimes UPDATE:: @@ -417,10 +417,10 @@ to the column. The SQL generated by the above is: MySQL with TIMESTAMP primary key ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When using the :class:`.TIMESTAMP` datatype with MySQL, MySQL ordinarily +When using the :class:`_types.TIMESTAMP` datatype with MySQL, MySQL ordinarily associates a server-side default with this datatype automatically. However when we use one as a primary key, the Core cannot retrieve the newly generated -value unless we execute the function ourselves. As :class:`.TIMESTAMP` on +value unless we execute the function ourselves. As :class:`_types.TIMESTAMP` on MySQL actually stores a binary value, we need to add an additional "CAST" to our usage of "NOW()" so that we retrieve a binary value that can be persisted into the column:: @@ -495,9 +495,9 @@ or mapped tables, across multiple databases, by configuring the :class:`.Session` with the :paramref:`.Session.binds` argument. This argument receives a dictionary that contains any combination of ORM-mapped classes, arbitrary classes within a mapped hierarchy (such -as declarative base classes or mixins), :class:`.Table` objects, -and :class:`.Mapper` objects as keys, which then refer typically to -:class:`.Engine` or less typically :class:`.Connection` objects as targets. +as declarative base classes or mixins), :class:`_schema.Table` objects, +and :class:`_orm.Mapper` objects as keys, which then refer typically to +:class:`_engine.Engine` or less typically :class:`_engine.Connection` objects as targets. The dictionary is consulted whenever the :class:`.Session` needs to emit SQL on behalf of a particular kind of mapped class in order to locate the appropriate source of database connectivity:: @@ -512,9 +512,9 @@ the appropriate source of database connectivity:: session = Session() -Above, SQL operations against either class will make usage of the :class:`.Engine` +Above, SQL operations against either class will make usage of the :class:`_engine.Engine` linked to that class. The functionality is comprehensive across both -read and write operations; a :class:`.Query` that is against entities +read and write operations; a :class:`_query.Query` that is against entities mapped to ``engine1`` (determined by looking at the first entity in the list of items requested) will make use of ``engine1`` to run the query. A flush operation will make use of **both** engines on a per-class basis as it @@ -627,7 +627,7 @@ argument to :class:`.sessionmaker`:: Session = sessionmaker(class_=RoutingSession) -This approach can be combined with multiple :class:`.MetaData` objects, +This approach can be combined with multiple :class:`_schema.MetaData` objects, using an approach such as that of using the declarative ``__abstract__`` keyword, described at :ref:`declarative_abstract`. @@ -641,7 +641,7 @@ Horizontal Partitioning Horizontal partitioning partitions the rows of a single table (or a set of tables) across multiple databases. The SQLAlchemy :class:`.Session` contains support for this concept, however to use it fully requires that -:class:`.Session` and :class:`.Query` subclasses are used. A basic version +:class:`.Session` and :class:`_query.Query` subclasses are used. A basic version of these subclasses are available in the :ref:`horizontal_sharding_toplevel` ORM extension. An example of use is at: :ref:`examples_sharding`. @@ -669,7 +669,7 @@ to this approach is strictly one of reduced Python overhead: * The flush() process, including the survey of all objects, their state, their cascade status, the status of all objects associated with them - via :func:`.relationship`, and the topological sort of all operations to + via :func:`_orm.relationship`, and the topological sort of all operations to be performed is completely bypassed. This reduces a great amount of Python overhead. @@ -746,8 +746,8 @@ Comparison to Core Insert / Update Constructs --------------------------------------------- The bulk methods offer performance that under particular circumstances -can be close to that of using the core :class:`~.sql.expression.Insert` and -:class:`.Update` constructs in an "executemany" context (for a description +can be close to that of using the core :class:`_expression.Insert` and +:class:`_expression.Update` constructs in an "executemany" context (for a description of "executemany", see :ref:`execute_multiple` in the Core tutorial). In order to achieve this, the :paramref:`.Session.bulk_insert_mappings.return_defaults` @@ -762,7 +762,7 @@ The bulk insert / update methods lose a significant amount of functionality versus traditional ORM use. The following is a listing of features that are **not available** when using these methods: -* persistence along :func:`.relationship` linkages +* persistence along :func:`_orm.relationship` linkages * sorting of rows within order of dependency; rows are inserted or updated directly in the order in which they are passed to the methods diff --git a/doc/build/orm/query.rst b/doc/build/orm/query.rst index 0c1af27bca..694405d630 100644 --- a/doc/build/orm/query.rst +++ b/doc/build/orm/query.rst @@ -6,17 +6,17 @@ Query API ========= -This section presents the API reference for the ORM :class:`.Query` object. For a walkthrough +This section presents the API reference for the ORM :class:`_query.Query` object. For a walkthrough of how to use this object, see :ref:`ormtutorial_toplevel`. The Query Object ================ -:class:`~.Query` is produced in terms of a given :class:`~.Session`, using the :meth:`~.Session.query` method:: +:class:`_query.Query` is produced in terms of a given :class:`~.Session`, using the :meth:`~.Session.query` method:: q = session.query(SomeMappedClass) -Following is the full interface for the :class:`.Query` object. +Following is the full interface for the :class:`_query.Query` object. .. autoclass:: sqlalchemy.orm.query.Query :members: diff --git a/doc/build/orm/relationship_persistence.rst b/doc/build/orm/relationship_persistence.rst index 225d26a16c..f843764741 100644 --- a/doc/build/orm/relationship_persistence.rst +++ b/doc/build/orm/relationship_persistence.rst @@ -49,14 +49,14 @@ identifiers were populated manually (again essentially bypassing :func:`~sqlalchemy.orm.relationship`). To enable the usage of a supplementary UPDATE statement, -we use the :paramref:`~.relationship.post_update` option -of :func:`.relationship`. This specifies that the linkage between the +we use the :paramref:`_orm.relationship.post_update` option +of :func:`_orm.relationship`. This specifies that the linkage between the two rows should be created using an UPDATE statement after both rows have been INSERTED; it also causes the rows to be de-associated with each other via UPDATE before a DELETE is emitted. The flag should be placed on just *one* of the relationships, preferably the many-to-one side. Below we illustrate -a complete example, including two :class:`.ForeignKey` constructs:: +a complete example, including two :class:`_schema.ForeignKey` constructs:: from sqlalchemy import Integer, ForeignKey, Column from sqlalchemy.ext.declarative import declarative_base @@ -156,12 +156,12 @@ as illustrated below:: foreign_keys=favorite_entry_id, post_update=True) -The above mapping features a composite :class:`.ForeignKeyConstraint` +The above mapping features a composite :class:`_schema.ForeignKeyConstraint` bridging the ``widget_id`` and ``favorite_entry_id`` columns. To ensure that ``Widget.widget_id`` remains an "autoincrementing" column we specify -:paramref:`~.Column.autoincrement` to the value ``"ignore_fk"`` -on :class:`.Column`, and additionally on each -:func:`.relationship` we must limit those columns considered as part of +:paramref:`_schema.Column.autoincrement` to the value ``"ignore_fk"`` +on :class:`_schema.Column`, and additionally on each +:func:`_orm.relationship` we must limit those columns considered as part of the foreign key for the purposes of joining and cross-population. .. _passive_updates: @@ -202,7 +202,7 @@ illustrates this is:: ForeignKey('user.username', onupdate="cascade") ) -Above, we illustrate ``onupdate="cascade"`` on the :class:`.ForeignKey` +Above, we illustrate ``onupdate="cascade"`` on the :class:`_schema.ForeignKey` object, and we also illustrate the ``mysql_engine='InnoDB'`` setting which, on a MySQL backend, ensures that the ``InnoDB`` engine supporting referential integrity is used. When using SQLite, referential integrity @@ -233,9 +233,9 @@ referential integrity, needs constraints to be marked as deferrable so that SQLAlchemy can emit UPDATE statements. The feature is enabled by setting the -:paramref:`~.relationship.passive_updates` flag to ``False``, +:paramref:`_orm.relationship.passive_updates` flag to ``False``, most preferably on a one-to-many or -many-to-many :func:`.relationship`. When "updates" are no longer +many-to-many :func:`_orm.relationship`. When "updates" are no longer "passive" this indicates that SQLAlchemy will issue UPDATE statements individually for objects referenced in the collection referred to by the parent object diff --git a/doc/build/orm/self_referential.rst b/doc/build/orm/self_referential.rst index b87b87dac0..4f656e44b9 100644 --- a/doc/build/orm/self_referential.rst +++ b/doc/build/orm/self_referential.rst @@ -42,13 +42,13 @@ Would be represented with data such as:: 5 3 subchild2 6 1 child3 -The :func:`.relationship` configuration here works in the +The :func:`_orm.relationship` configuration here works in the same way as a "normal" one-to-many relationship, with the exception that the "direction", i.e. whether the relationship is one-to-many or many-to-one, is assumed by default to be one-to-many. To establish the relationship as many-to-one, -an extra directive is added known as :paramref:`~.relationship.remote_side`, which -is a :class:`.Column` or collection of :class:`.Column` objects +an extra directive is added known as :paramref:`_orm.relationship.remote_side`, which +is a :class:`_schema.Column` or collection of :class:`_schema.Column` objects that indicate those which should be considered to be "remote":: class Node(Base): @@ -58,8 +58,8 @@ that indicate those which should be considered to be "remote":: data = Column(String(50)) parent = relationship("Node", remote_side=[id]) -Where above, the ``id`` column is applied as the :paramref:`~.relationship.remote_side` -of the ``parent`` :func:`.relationship`, thus establishing +Where above, the ``id`` column is applied as the :paramref:`_orm.relationship.remote_side` +of the ``parent`` :func:`_orm.relationship`, thus establishing ``parent_id`` as the "local" side, and the relationship then behaves as a many-to-one. @@ -108,8 +108,8 @@ to a specific folder within that account:: remote_side=[account_id, folder_id] ) -Above, we pass ``account_id`` into the :paramref:`~.relationship.remote_side` list. -:func:`.relationship` recognizes that the ``account_id`` column here +Above, we pass ``account_id`` into the :paramref:`_orm.relationship.remote_side` list. +:func:`_orm.relationship` recognizes that the ``account_id`` column here is on both sides, and aligns the "remote" column along with the ``folder_id`` column, which it recognizes as uniquely present on the "remote" side. @@ -128,7 +128,7 @@ a join from a table to itself requires that at least one side of the expression be "aliased" so that it can be unambiguously referred to. Recall from :ref:`ormtutorial_aliases` in the ORM tutorial that the -:func:`.orm.aliased` construct is normally used to provide an "alias" of +:func:`_orm.aliased` construct is normally used to provide an "alias" of an ORM entity. Joining from ``Node`` to itself using this technique looks like: @@ -150,11 +150,11 @@ looks like: AND node_1.data = ? ['subchild1', 'child2'] -:meth:`.Query.join` also includes a feature known as +:meth:`_query.Query.join` also includes a feature known as :paramref:`.Query.join.aliased` that can shorten the verbosity self- referential joins, at the expense of query flexibility. This feature performs a similar "aliasing" step to that above, without the need for -an explicit entity. Calls to :meth:`.Query.filter` and similar +an explicit entity. Calls to :meth:`_query.Query.filter` and similar subsequent to the aliased join will **adapt** the ``Node`` entity to be that of the alias: @@ -174,7 +174,7 @@ be that of the alias: To add criterion to multiple points along a longer join, add :paramref:`.Query.join.from_joinpoint` to the additional -:meth:`~.Query.join` calls: +:meth:`_query.Query.join` calls: .. sourcecode:: python+sql @@ -198,7 +198,7 @@ To add criterion to multiple points along a longer join, add AND node_2.data = ? ['subchild1', 'child2', 'root'] -:meth:`.Query.reset_joinpoint` will also remove the "aliasing" from filtering +:meth:`_query.Query.reset_joinpoint` will also remove the "aliasing" from filtering calls:: session.query(Node).\ diff --git a/doc/build/orm/session.rst b/doc/build/orm/session.rst index 79ea701377..0e84bf446c 100644 --- a/doc/build/orm/session.rst +++ b/doc/build/orm/session.rst @@ -6,7 +6,7 @@ Using the Session .. module:: sqlalchemy.orm.session -The :func:`.orm.mapper` function and :mod:`~sqlalchemy.ext.declarative` extensions +The :func:`_orm.mapper` function and :mod:`~sqlalchemy.ext.declarative` extensions are the primary configurational interface for the ORM. Once mappings are configured, the primary usage interface for persistence operations is the :class:`.Session`. diff --git a/doc/build/orm/session_api.rst b/doc/build/orm/session_api.rst index 11e37a2c87..e247a8de78 100644 --- a/doc/build/orm/session_api.rst +++ b/doc/build/orm/session_api.rst @@ -65,7 +65,7 @@ those described in :doc:`/orm/events`. This function is the internal version of :func:`.object_state`. The :func:`.object_state` and/or the - :func:`.inspect` function is preferred here + :func:`_sa.inspect` function is preferred here as they each emit an informative exception if the given object is not mapped. diff --git a/doc/build/orm/session_basics.rst b/doc/build/orm/session_basics.rst index a4c82e6f1e..bf57ac6862 100644 --- a/doc/build/orm/session_basics.rst +++ b/doc/build/orm/session_basics.rst @@ -8,7 +8,7 @@ What does the Session do ? In the most general sense, the :class:`~.Session` establishes all conversations with the database and represents a "holding zone" for all the objects which you've loaded or associated with it during its lifespan. It -provides the entrypoint to acquire a :class:`.Query` object, which sends +provides the entrypoint to acquire a :class:`_query.Query` object, which sends queries to the database using the :class:`~.Session` object's current database connection, populating result rows into objects that are then stored in the :class:`.Session`, inside a structure called the `Identity Map @@ -18,8 +18,8 @@ object with a particular primary key". The :class:`.Session` begins in an essentially stateless form. Once queries are issued or other objects are persisted with it, it requests a connection -resource from an :class:`.Engine` that is associated either with the -:class:`.Session` itself or with the mapped :class:`.Table` objects being +resource from an :class:`_engine.Engine` that is associated either with the +:class:`.Session` itself or with the mapped :class:`_schema.Table` objects being operated upon. This connection represents an ongoing transaction, which remains in effect until the :class:`.Session` is instructed to commit or roll back its pending state. @@ -77,11 +77,11 @@ Above, the :class:`.sessionmaker` call creates a factory for us, which we assign to the name ``Session``. This factory, when called, will create a new :class:`.Session` object using the configurational arguments we've given the factory. In this case, as is typical, -we've configured the factory to specify a particular :class:`.Engine` for +we've configured the factory to specify a particular :class:`_engine.Engine` for connection resources. -A typical setup will associate the :class:`.sessionmaker` with an :class:`.Engine`, -so that each :class:`.Session` generated will use this :class:`.Engine` +A typical setup will associate the :class:`.sessionmaker` with an :class:`_engine.Engine`, +so that each :class:`.Session` generated will use this :class:`_engine.Engine` to acquire connection resources. This association can be set up as in the example above, using the ``bind`` argument. @@ -101,7 +101,7 @@ Adding Additional Configuration to an Existing sessionmaker() ------------------------------------------------------------- A common scenario is where the :class:`.sessionmaker` is invoked -at module import time, however the generation of one or more :class:`.Engine` +at module import time, however the generation of one or more :class:`_engine.Engine` instances to be associated with the :class:`.sessionmaker` has not yet proceeded. For this use case, the :class:`.sessionmaker` construct offers the :meth:`.sessionmaker.configure` method, which will place additional configuration @@ -136,7 +136,7 @@ what most of the application wants, specific arguments can be passed to the :class:`.sessionmaker` factory's :meth:`.sessionmaker.__call__` method. These arguments will override whatever configurations have already been placed, such as below, where a new :class:`.Session` -is constructed against a specific :class:`.Connection`:: +is constructed against a specific :class:`_engine.Connection`:: # at the module level, the global sessionmaker, # bound to a specific Engine @@ -148,7 +148,7 @@ is constructed against a specific :class:`.Connection`:: session = Session(bind=conn) The typical rationale for the association of a :class:`.Session` with a specific -:class:`.Connection` is that of a test fixture that maintains an external +:class:`_engine.Connection` is that of a test fixture that maintains an external transaction - see :ref:`session_external_transaction` for an example of this. @@ -514,7 +514,7 @@ expires all instances along transaction boundaries, so that with a normally isolated transaction, there shouldn't be any issue of instances representing data which is stale with regards to the current transaction. -The :class:`.Query` object is introduced in great detail in +The :class:`_query.Query` object is introduced in great detail in :ref:`ormtutorial_toplevel`, and further documented in :ref:`query_api_toplevel`. @@ -566,7 +566,7 @@ Deleting Objects Referenced from Collections and Scalar Relationships The ORM in general never modifies the contents of a collection or scalar relationship during the flush process. This means, if your class has a -:func:`.relationship` that refers to a collection of objects, or a reference +:func:`_orm.relationship` that refers to a collection of objects, or a reference to a single object such as many-to-one, the contents of this attribute will not be modified when the flush process occurs. Instead, if the :class:`.Session` is expired afterwards, either through the expire-on-commit behavior of @@ -588,7 +588,7 @@ A common confusion that arises regarding this behavior involves the use of the :meth:`~.Session.delete` method. When :meth:`.Session.delete` is invoked upon an object and the :class:`.Session` is flushed, the row is deleted from the database. Rows that refer to the target row via foreign key, assuming they -are tracked using a :func:`.relationship` between the two mapped object types, +are tracked using a :func:`_orm.relationship` between the two mapped object types, will also see their foreign key attributes UPDATED to null, or if delete cascade is set up, the related rows will be deleted as well. However, even though rows related to the deleted object might be themselves modified as well, @@ -647,7 +647,7 @@ The ``delete-orphan`` cascade can also be applied to a many-to-one or one-to-one relationship, so that when an object is de-associated from its parent, it is also automatically marked for deletion. Using ``delete-orphan`` cascade on a many-to-one or one-to-one requires an additional flag -:paramref:`.relationship.single_parent` which invokes an assertion +:paramref:`_orm.relationship.single_parent` which invokes an assertion that this related object is not to shared with any other parent simultaneously:: class User(Base): diff --git a/doc/build/orm/session_events.rst b/doc/build/orm/session_events.rst index 30336c000b..066fe7c24a 100644 --- a/doc/build/orm/session_events.rst +++ b/doc/build/orm/session_events.rst @@ -102,8 +102,8 @@ The events are: * :meth:`.MapperEvents.before_delete` * :meth:`.MapperEvents.after_delete` -Each event is passed the :class:`.Mapper`, -the mapped object itself, and the :class:`.Connection` which is being +Each event is passed the :class:`_orm.Mapper`, +the mapped object itself, and the :class:`_engine.Connection` which is being used to emit an INSERT, UPDATE or DELETE statement. The appeal of these events is clear, in that if an application wants to tie some activity to when a specific type of object is persisted with an INSERT, the hook is @@ -127,10 +127,10 @@ events include: * Mapped relationship attribute set/del events, i.e. ``someobject.related = someotherobject`` -The reason the :class:`.Connection` is passed is that it is encouraged that -**simple SQL operations take place here**, directly on the :class:`.Connection`, +The reason the :class:`_engine.Connection` is passed is that it is encouraged that +**simple SQL operations take place here**, directly on the :class:`_engine.Connection`, such as incrementing counters or inserting extra rows within log tables. -When dealing with the :class:`.Connection`, it is expected that Core-level +When dealing with the :class:`_engine.Connection`, it is expected that Core-level SQL operations will be used; e.g. those described in :ref:`sqlexpression_toplevel`. There are also many per-object operations that don't need to be handled @@ -392,7 +392,7 @@ Transaction Events Transaction events allow an application to be notified when transaction boundaries occur at the :class:`.Session` level as well as when the -:class:`.Session` changes the transactional state on :class:`.Connection` +:class:`.Session` changes the transactional state on :class:`_engine.Connection` objects. * :meth:`.SessionEvents.after_transaction_create`, diff --git a/doc/build/orm/session_state_management.rst b/doc/build/orm/session_state_management.rst index 8b4d7a572f..1a5168eb63 100644 --- a/doc/build/orm/session_state_management.rst +++ b/doc/build/orm/session_state_management.rst @@ -50,7 +50,7 @@ Getting the Current State of an Object ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The actual state of any mapped object can be viewed at any time using -the :func:`.inspect` system:: +the :func:`_sa.inspect` system:: >>> from sqlalchemy import inspect >>> insp = inspect(my_object) @@ -254,8 +254,8 @@ new session. Here's some examples: In the caching use case, it's common to use the ``load=False`` flag to remove the overhead of reconciling the object's state with the database. There's also a "bulk" version of - :meth:`~.Session.merge` called :meth:`~.Query.merge_result` - that was designed to work with cache-extended :class:`.Query` + :meth:`~.Session.merge` called :meth:`_query.Query.merge_result` + that was designed to work with cache-extended :class:`_query.Query` objects - see the section :ref:`examples_caching`. * An application wants to transfer the state of a series of objects @@ -332,15 +332,15 @@ and made our ``a1`` object pending, as though we had added it. Now we have Above, our ``a1`` is already pending in the session. The subsequent :meth:`~.Session.merge` operation essentially -does nothing. Cascade can be configured via the :paramref:`~.relationship.cascade` -option on :func:`.relationship`, although in this case it +does nothing. Cascade can be configured via the :paramref:`_orm.relationship.cascade` +option on :func:`_orm.relationship`, although in this case it would mean removing the ``save-update`` cascade from the ``User.addresses`` relationship - and usually, that behavior is extremely convenient. The solution here would usually be to not assign ``a1.user`` to an object already persistent in the target session. -The ``cascade_backrefs=False`` option of :func:`.relationship` +The ``cascade_backrefs=False`` option of :func:`_orm.relationship` will also prevent the ``Address`` from being added to the session via the ``a1.user = u1`` assignment. @@ -439,7 +439,7 @@ where ``id`` and ``name`` refer to those columns in the database. ``_sa_instance_state`` is a non-database-persisted value used by SQLAlchemy internally (it refers to the :class:`.InstanceState` for the instance. While not directly relevant to this section, if we want to get at it, -we should use the :func:`.inspect` function to access it). +we should use the :func:`_sa.inspect` function to access it). At this point, the state in our ``User`` object matches that of the loaded database row. But upon expiring the object using a method such as @@ -533,24 +533,24 @@ or loaded with :meth:`~.Session.refresh` varies based on several factors, includ * The load of expired attributes is triggered from **column-mapped attributes only**. While any kind of attribute can be marked as expired, including a - :func:`.relationship` - mapped attribute, accessing an expired :func:`.relationship` + :func:`_orm.relationship` - mapped attribute, accessing an expired :func:`_orm.relationship` attribute will emit a load only for that attribute, using standard relationship-oriented lazy loading. Column-oriented attributes, even if expired, will not load as part of this operation, and instead will load when any column-oriented attribute is accessed. -* :func:`.relationship`- mapped attributes will not load in response to +* :func:`_orm.relationship`- mapped attributes will not load in response to expired column-based attributes being accessed. * Regarding relationships, :meth:`~.Session.refresh` is more restrictive than :meth:`.Session.expire` with regards to attributes that aren't column-mapped. Calling :meth:`.Session.refresh` and passing a list of names that only includes relationship-mapped attributes will actually raise an error. - In any case, non-eager-loading :func:`.relationship` attributes will not be + In any case, non-eager-loading :func:`_orm.relationship` attributes will not be included in any refresh operation. -* :func:`.relationship` attributes configured as "eager loading" via the - :paramref:`~.relationship.lazy` parameter will load in the case of +* :func:`_orm.relationship` attributes configured as "eager loading" via the + :paramref:`_orm.relationship.lazy` parameter will load in the case of :meth:`~.Session.refresh`, if either no attribute names are specified, or if their names are included in the list of attributes to be refreshed. @@ -608,7 +608,7 @@ database, in those cases when it is known that the current state of data is possibly stale. Reasons for this might include: * some SQL has been emitted within the transaction outside of the - scope of the ORM's object handling, such as if a :meth:`.Table.update` construct + scope of the ORM's object handling, such as if a :meth:`_schema.Table.update` construct were emitted using the :meth:`.Session.execute` method; * if the application diff --git a/doc/build/orm/session_transaction.rst b/doc/build/orm/session_transaction.rst index 5bba243cc2..f0c5b43938 100644 --- a/doc/build/orm/session_transaction.rst +++ b/doc/build/orm/session_transaction.rst @@ -9,38 +9,38 @@ Managing Transactions A newly constructed :class:`.Session` may be said to be in the "begin" state. In this state, the :class:`.Session` has not established any connection or -transactional state with any of the :class:`.Engine` objects that may be associated +transactional state with any of the :class:`_engine.Engine` objects that may be associated with it. The :class:`.Session` then receives requests to operate upon a database connection. Typically, this means it is called upon to execute SQL statements using a particular -:class:`.Engine`, which may be via :meth:`.Session.query`, :meth:`.Session.execute`, +:class:`_engine.Engine`, which may be via :meth:`.Session.query`, :meth:`.Session.execute`, or within a flush operation of pending data, which occurs when such state exists and :meth:`.Session.commit` or :meth:`.Session.flush` is called. -As these requests are received, each new :class:`.Engine` encountered is associated +As these requests are received, each new :class:`_engine.Engine` encountered is associated with an ongoing transactional state maintained by the :class:`.Session`. -When the first :class:`.Engine` is operated upon, the :class:`.Session` can be said +When the first :class:`_engine.Engine` is operated upon, the :class:`.Session` can be said to have left the "begin" state and entered "transactional" state. For each -:class:`.Engine` encountered, a :class:`.Connection` is associated with it, -which is acquired via the :meth:`.Engine.connect` method. If a -:class:`.Connection` was directly associated with the :class:`.Session` (see :ref:`session_external_transaction` +:class:`_engine.Engine` encountered, a :class:`_engine.Connection` is associated with it, +which is acquired via the :meth:`_engine.Engine.connect` method. If a +:class:`_engine.Connection` was directly associated with the :class:`.Session` (see :ref:`session_external_transaction` for an example of this), it is added to the transactional state directly. -For each :class:`.Connection`, the :class:`.Session` also maintains a :class:`.Transaction` object, -which is acquired by calling :meth:`.Connection.begin` on each :class:`.Connection`, +For each :class:`_engine.Connection`, the :class:`.Session` also maintains a :class:`.Transaction` object, +which is acquired by calling :meth:`_engine.Connection.begin` on each :class:`_engine.Connection`, or if the :class:`.Session` object has been established using the flag ``twophase=True``, a :class:`.TwoPhaseTransaction` -object acquired via :meth:`.Connection.begin_twophase`. These transactions are all committed or +object acquired via :meth:`_engine.Connection.begin_twophase`. These transactions are all committed or rolled back corresponding to the invocation of the :meth:`.Session.commit` and :meth:`.Session.rollback` methods. A commit operation will also call the :meth:`.TwoPhaseTransaction.prepare` method on all transactions if applicable. When the transactional state is completed after a rollback or commit, the :class:`.Session` -:term:`releases` all :class:`.Transaction` and :class:`.Connection` resources, +:term:`releases` all :class:`.Transaction` and :class:`_engine.Connection` resources, and goes back to the "begin" state, which -will again invoke new :class:`.Connection` and :class:`.Transaction` objects as new +will again invoke new :class:`_engine.Connection` and :class:`.Transaction` objects as new requests to emit SQL statements are received. The example below illustrates this lifecycle:: @@ -223,7 +223,7 @@ as well as within a block that has already demarcated a transaction. ``subtransactions=True`` is generally only useful in conjunction with autocommit, and is equivalent to the pattern described at :ref:`connections_nested_transactions`, -where any number of functions can call :meth:`.Connection.begin` and :meth:`.Transaction.commit` +where any number of functions can call :meth:`_engine.Connection.begin` and :meth:`.Transaction.commit` as though they are the initiator of the transaction, but in fact may be participating in an already ongoing transaction:: @@ -302,15 +302,15 @@ are four well-known modes of isolation, and typically the Python DBAPI allows these to be set on a per-connection basis, either through explicit APIs or via database-specific calls. -SQLAlchemy's dialects support settable isolation modes on a per-:class:`.Engine` -or per-:class:`.Connection` basis, using flags at both the -:func:`.create_engine` level as well as at the :meth:`.Connection.execution_options` +SQLAlchemy's dialects support settable isolation modes on a per-:class:`_engine.Engine` +or per-:class:`_engine.Connection` basis, using flags at both the +:func:`.create_engine` level as well as at the :meth:`_engine.Connection.execution_options` level. When using the ORM :class:`.Session`, it acts as a *facade* for engines and connections, but does not expose transaction isolation directly. So in order to affect transaction isolation level, we need to act upon the -:class:`.Engine` or :class:`.Connection` as appropriate. +:class:`_engine.Engine` or :class:`_engine.Connection` as appropriate. .. seealso:: @@ -347,8 +347,8 @@ Setting Isolation for Individual Sessions When we make a new :class:`.Session`, either using the constructor directly or when we call upon the callable produced by a :class:`.sessionmaker`, we can pass the ``bind`` argument directly, overriding the pre-existing bind. -We can combine this with the :meth:`.Engine.execution_options` method -in order to produce a copy of the original :class:`.Engine` that will +We can combine this with the :meth:`_engine.Engine.execution_options` method +in order to produce a copy of the original :class:`_engine.Engine` that will add this option:: session = maker( @@ -370,14 +370,14 @@ Setting Isolation for Individual Transactions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A key caveat regarding isolation level is that the setting cannot be -safely modified on a :class:`.Connection` where a transaction has already +safely modified on a :class:`_engine.Connection` where a transaction has already started. Databases cannot change the isolation level of a transaction in progress, and some DBAPIs and SQLAlchemy dialects have inconsistent behaviors in this area. Some may implicitly emit a ROLLBACK and some may implicitly emit a COMMIT, others may ignore the setting until the next transaction. Therefore SQLAlchemy emits a warning if this option is set when a transaction is already in play. The :class:`.Session` -object does not provide for us a :class:`.Connection` for use in a transaction +object does not provide for us a :class:`_engine.Connection` for use in a transaction where the transaction is not already begun. So here, we need to pass execution options to the :class:`.Session` at the start of a transaction by passing :paramref:`.Session.connection.execution_options` @@ -444,10 +444,10 @@ of the available event hooks for session transaction state changes. Joining a Session into an External Transaction (such as for test suites) ======================================================================== -If a :class:`.Connection` is being used which is already in a transactional +If a :class:`_engine.Connection` is being used which is already in a transactional state (i.e. has a :class:`.Transaction` established), a :class:`.Session` can be made to participate within that transaction by just binding the -:class:`.Session` to that :class:`.Connection`. The usual rationale for this +:class:`.Session` to that :class:`_engine.Connection`. The usual rationale for this is a test suite that allows ORM code to work freely with a :class:`.Session`, including the ability to call :meth:`.Session.commit`, where afterwards the entire database interaction is rolled back:: @@ -491,7 +491,7 @@ entire database interaction is rolled back:: Above, we issue :meth:`.Session.commit` as well as :meth:`.Transaction.rollback`. This is an example of where we take advantage -of the :class:`.Connection` object's ability to maintain *subtransactions*, or +of the :class:`_engine.Connection` object's ability to maintain *subtransactions*, or nested begin/commit-or-rollback pairs where only the outermost begin/commit pair actually commits the transaction, or if the outermost block rolls back, everything is rolled back. diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst index 19fdd09bcd..6958693dba 100644 --- a/doc/build/orm/tutorial.rst +++ b/doc/build/orm/tutorial.rst @@ -63,7 +63,7 @@ the SQL behind a popup window so it doesn't get in our way; just click the "SQL" links to see what's being generated. The return value of :func:`.create_engine` is an instance of -:class:`.Engine`, and it represents the core interface to the +:class:`_engine.Engine`, and it represents the core interface to the database, adapted through a :term:`dialect` that handles the details of the database and :term:`DBAPI` in use. In this case the SQLite dialect will interpret instructions to the Python built-in ``sqlite3`` @@ -71,14 +71,14 @@ module. .. sidebar:: Lazy Connecting - The :class:`.Engine`, when first returned by :func:`.create_engine`, + The :class:`_engine.Engine`, when first returned by :func:`.create_engine`, has not actually tried to connect to the database yet; that happens only the first time it is asked to perform a task against the database. -The first time a method like :meth:`.Engine.execute` or :meth:`.Engine.connect` -is called, the :class:`.Engine` establishes a real :term:`DBAPI` connection to the +The first time a method like :meth:`_engine.Engine.execute` or :meth:`_engine.Engine.connect` +is called, the :class:`_engine.Engine` establishes a real :term:`DBAPI` connection to the database, which is then used to emit the SQL. When using the ORM, we typically -don't use the :class:`.Engine` directly once created; instead, it's used +don't use the :class:`_engine.Engine` directly once created; instead, it's used behind the scenes by the ORM as we'll see shortly. .. seealso:: @@ -137,7 +137,7 @@ the table name, and names and datatypes of columns:: A class using Declarative at a minimum needs a ``__tablename__`` attribute, and at least one -:class:`.Column` which is part of a primary key [#]_. SQLAlchemy never makes any +:class:`_schema.Column` which is part of a primary key [#]_. SQLAlchemy never makes any assumptions by itself about the table to which a class refers, including that it has no built-in conventions for names, datatypes, or constraints. But this doesn't mean @@ -145,7 +145,7 @@ boilerplate is required; instead, you're encouraged to create your own automated conventions using helper functions and mixin classes, which is described in detail at :ref:`declarative_mixins`. -When our class is constructed, Declarative replaces all the :class:`.Column` +When our class is constructed, Declarative replaces all the :class:`_schema.Column` objects with special Python accessors known as :term:`descriptors`; this is a process known as :term:`instrumentation`. The "instrumented" mapped class will provide us with the means to refer to our table in a SQL context as well @@ -164,7 +164,7 @@ Create a Schema With our ``User`` class constructed via the Declarative system, we have defined information about our table, known as :term:`table metadata`. The object used by SQLAlchemy to represent -this information for a specific table is called the :class:`.Table` object, and here Declarative has made +this information for a specific table is called the :class:`_schema.Table` object, and here Declarative has made one for us. We can see this object by inspecting the ``__table__`` attribute:: >>> User.__table__ # doctest: +NORMALIZE_WHITESPACE @@ -179,29 +179,29 @@ one for us. We can see this object by inspecting the ``__table__`` attribute:: The Declarative system, though highly recommended, is not required in order to use SQLAlchemy's ORM. Outside of Declarative, any - plain Python class can be mapped to any :class:`.Table` + plain Python class can be mapped to any :class:`_schema.Table` using the :func:`.mapper` function directly; this less common usage is described at :ref:`classical_mapping`. When we declared our class, Declarative used a Python metaclass in order to perform additional activities once the class declaration was complete; within -this phase, it then created a :class:`.Table` object according to our +this phase, it then created a :class:`_schema.Table` object according to our specifications, and associated it with the class by constructing -a :class:`.Mapper` object. This object is a behind-the-scenes object we normally +a :class:`_orm.Mapper` object. This object is a behind-the-scenes object we normally don't need to deal with directly (though it can provide plenty of information about our mapping when we need it). -The :class:`.Table` object is a member of a larger collection -known as :class:`.MetaData`. When using Declarative, +The :class:`_schema.Table` object is a member of a larger collection +known as :class:`_schema.MetaData`. When using Declarative, this object is available using the ``.metadata`` attribute of our declarative base class. -The :class:`.MetaData` +The :class:`_schema.MetaData` is a :term:`registry` which includes the ability to emit a limited set of schema generation commands to the database. As our SQLite database -does not actually have a ``users`` table present, we can use :class:`.MetaData` +does not actually have a ``users`` table present, we can use :class:`_schema.MetaData` to issue CREATE TABLE statements to the database for all tables that don't yet exist. -Below, we call the :meth:`.MetaData.create_all` method, passing in our :class:`.Engine` +Below, we call the :meth:`_schema.MetaData.create_all` method, passing in our :class:`_engine.Engine` as a source of database connectivity. We will see that special commands are first emitted to check for the presence of the ``users`` table, and following that the actual ``CREATE TABLE`` statement: @@ -342,9 +342,9 @@ instantiate a :class:`~sqlalchemy.orm.session.Session`:: >>> session = Session() The above :class:`~sqlalchemy.orm.session.Session` is associated with our -SQLite-enabled :class:`.Engine`, but it hasn't opened any connections yet. When it's first +SQLite-enabled :class:`_engine.Engine`, but it hasn't opened any connections yet. When it's first used, it retrieves a connection from a pool of connections maintained by the -:class:`.Engine`, and holds onto it until we commit all changes and/or close the +:class:`_engine.Engine`, and holds onto it until we commit all changes and/or close the session object. @@ -638,8 +638,8 @@ class: fred You can control the names of individual column expressions using the -:meth:`~.ColumnElement.label` construct, which is available from -any :class:`.ColumnElement`-derived object, as well as any class attribute which +:meth:`_expression.ColumnElement.label` construct, which is available from +any :class:`_expression.ColumnElement`-derived object, as well as any class attribute which is mapped to one (such as ``User.name``): .. sourcecode:: python+sql @@ -846,11 +846,11 @@ Here's a rundown of some of the most common operators used in Returning Lists and Scalars --------------------------- -A number of methods on :class:`.Query` +A number of methods on :class:`_query.Query` immediately issue SQL and return a value containing loaded database results. Here's a brief tour: -* :meth:`~.Query.all()` returns a list: +* :meth:`_query.Query.all()` returns a list: .. sourcecode:: python+sql @@ -868,7 +868,7 @@ database results. Here's a brief tour: .. warning:: - When the :class:`.Query` object returns lists of ORM-mapped objects + When the :class:`_query.Query` object returns lists of ORM-mapped objects such as the ``User`` object above, the entries are **deduplicated** based on primary key, as the results are interpreted from the SQL result set. That is, if SQL query returns a row with ``id=7`` twice, @@ -881,7 +881,7 @@ database results. Here's a brief tour: :ref:`faq_query_deduplicating` -* :meth:`~.Query.first()` applies a limit of one and returns +* :meth:`_query.Query.first()` applies a limit of one and returns the first result as a scalar: .. sourcecode:: python+sql @@ -897,7 +897,7 @@ database results. Here's a brief tour: ('%ed', 1, 0) {stop} -* :meth:`~.Query.one()` fully fetches all rows, and if not +* :meth:`_query.Query.one()` fully fetches all rows, and if not exactly one object identity or composite row is present in the result, raises an error. With multiple rows found: @@ -917,17 +917,17 @@ database results. Here's a brief tour: ... NoResultFound: No row was found for one() - The :meth:`~.Query.one` method is great for systems that expect to handle + The :meth:`_query.Query.one` method is great for systems that expect to handle "no items found" versus "multiple items found" differently; such as a RESTful web service, which may want to raise a "404 not found" when no results are found, but raise an application error when multiple results are found. -* :meth:`~.Query.one_or_none` is like :meth:`~.Query.one`, except that if no +* :meth:`_query.Query.one_or_none` is like :meth:`_query.Query.one`, except that if no results are found, it doesn't raise an error; it just returns ``None``. Like - :meth:`~.Query.one`, however, it does raise an error if multiple results are + :meth:`_query.Query.one`, however, it does raise an error if multiple results are found. -* :meth:`~.Query.scalar` invokes the :meth:`~.Query.one` method, and upon +* :meth:`_query.Query.scalar` invokes the :meth:`_query.Query.one` method, and upon success returns the first column of the row: .. sourcecode:: python+sql @@ -948,7 +948,7 @@ Using Textual SQL Literal strings can be used flexibly with :class:`~sqlalchemy.orm.query.Query`, by specifying their use -with the :func:`~.expression.text` construct, which is accepted +with the :func:`_expression.text` construct, which is accepted by most applicable methods. For example, :meth:`~sqlalchemy.orm.query.Query.filter()` and :meth:`~sqlalchemy.orm.query.Query.order_by()`: @@ -989,7 +989,7 @@ method: (224, 'fred') {stop} -To use an entirely string-based statement, a :func:`.text` construct +To use an entirely string-based statement, a :func:`_expression.text` construct representing a complete statement can be passed to :meth:`~sqlalchemy.orm.query.Query.from_statement()`. Without further specification, the ORM will match columns in the ORM mapping to the result @@ -1005,7 +1005,7 @@ returned by the SQL statement based on column name:: For better targeting of mapped columns to a textual SELECT, as well as to match on a specific subset of columns in arbitrary order, individual mapped -columns are passed in the desired order to :meth:`.TextClause.columns`: +columns are passed in the desired order to :meth:`_expression.TextClause.columns`: .. sourcecode:: python+sql @@ -1017,7 +1017,7 @@ columns are passed in the desired order to :meth:`.TextClause.columns`: ('ed',) {stop}[] -When selecting from a :func:`~.expression.text` construct, the :class:`.Query` +When selecting from a :func:`_expression.text` construct, the :class:`_query.Query` may still specify what columns and entities are to be returned; instead of ``query(User)`` we can also ask for the columns individually, as in any other case: @@ -1034,7 +1034,7 @@ any other case: .. seealso:: - :ref:`sqlexpression_text` - The :func:`.text` construct explained + :ref:`sqlexpression_text` - The :func:`_expression.text` construct explained from the perspective of Core-only queries. Counting @@ -1058,7 +1058,7 @@ counting called :meth:`~sqlalchemy.orm.query.Query.count()`: .. sidebar:: Counting on ``count()`` - :meth:`.Query.count` used to be a very complicated method + :meth:`_query.Query.count` used to be a very complicated method when it would try to guess whether or not a subquery was needed around the existing query, and in some exotic cases it wouldn't do the right thing. @@ -1066,7 +1066,7 @@ counting called :meth:`~sqlalchemy.orm.query.Query.count()`: and always returns the right answer. Use ``func.count()`` if a particular statement absolutely cannot tolerate the subquery being present. -The :meth:`~.Query.count()` method is used to determine +The :meth:`_query.Query.count()` method is used to determine how many rows the SQL statement would return. Looking at the generated SQL above, SQLAlchemy always places whatever it is we are querying into a subquery, then counts the rows from that. In some cases @@ -1099,7 +1099,7 @@ To achieve our simple ``SELECT count(*) FROM table``, we can apply it as: ('*',) {stop}4 -The usage of :meth:`~.Query.select_from` can be removed if we express the count in terms +The usage of :meth:`_query.Query.select_from` can be removed if we express the count in terms of the ``User`` primary key directly: .. sourcecode:: python+sql @@ -1141,26 +1141,26 @@ declarative, we define this table along with its mapped class, ``Address``: >>> User.addresses = relationship( ... "Address", order_by=Address.id, back_populates="user") -The above class introduces the :class:`.ForeignKey` construct, which is a -directive applied to :class:`.Column` that indicates that values in this +The above class introduces the :class:`_schema.ForeignKey` construct, which is a +directive applied to :class:`_schema.Column` that indicates that values in this column should be :term:`constrained` to be values present in the named remote column. This is a core feature of relational databases, and is the "glue" that transforms an otherwise unconnected collection of tables to have rich -overlapping relationships. The :class:`.ForeignKey` above expresses that +overlapping relationships. The :class:`_schema.ForeignKey` above expresses that values in the ``addresses.user_id`` column should be constrained to those values in the ``users.id`` column, i.e. its primary key. -A second directive, known as :func:`.relationship`, +A second directive, known as :func:`_orm.relationship`, tells the ORM that the ``Address`` class itself should be linked to the ``User`` class, using the attribute ``Address.user``. -:func:`.relationship` uses the foreign key +:func:`_orm.relationship` uses the foreign key relationships between the two tables to determine the nature of this linkage, determining that ``Address.user`` will be :term:`many to one`. -An additional :func:`.relationship` directive is placed on the +An additional :func:`_orm.relationship` directive is placed on the ``User`` mapped class under the attribute ``User.addresses``. In both -:func:`.relationship` directives, the parameter -:paramref:`.relationship.back_populates` is assigned to refer to the -complementary attribute names; by doing so, each :func:`.relationship` +:func:`_orm.relationship` directives, the parameter +:paramref:`_orm.relationship.back_populates` is assigned to refer to the +complementary attribute names; by doing so, each :func:`_orm.relationship` can make intelligent decision about the same relationship as expressed in reverse; on one side, ``Address.user`` refers to a ``User`` instance, and on the other side, ``User.addresses`` refers to a list of @@ -1168,16 +1168,16 @@ and on the other side, ``User.addresses`` refers to a list of .. note:: - The :paramref:`.relationship.back_populates` parameter is a newer + The :paramref:`_orm.relationship.back_populates` parameter is a newer version of a very common SQLAlchemy feature called - :paramref:`.relationship.backref`. The :paramref:`.relationship.backref` + :paramref:`_orm.relationship.backref`. The :paramref:`_orm.relationship.backref` parameter hasn't gone anywhere and will always remain available! - The :paramref:`.relationship.back_populates` is the same thing, except + The :paramref:`_orm.relationship.back_populates` is the same thing, except a little more verbose and easier to manipulate. For an overview of the entire topic, see the section :ref:`relationships_backref`. The reverse side of a many-to-one relationship is always :term:`one to many`. -A full catalog of available :func:`.relationship` configurations +A full catalog of available :func:`_orm.relationship` configurations is at :ref:`relationship_patterns`. The two complementing relationships ``Address.user`` and ``User.addresses`` @@ -1185,7 +1185,7 @@ are referred to as a :term:`bidirectional relationship`, and is a key feature of the SQLAlchemy ORM. The section :ref:`relationships_backref` discusses the "backref" feature in detail. -Arguments to :func:`.relationship` which concern the remote class +Arguments to :func:`_orm.relationship` which concern the remote class can be specified using strings, assuming the Declarative system is in use. Once all mappings are complete, these strings are evaluated as Python expressions in order to produce the actual argument, in the @@ -1193,7 +1193,7 @@ above case the ``User`` class. The names which are allowed during this evaluation include, among other things, the names of all classes which have been created in terms of the declared base. -See the docstring for :func:`.relationship` for more detail on argument style. +See the docstring for :func:`_orm.relationship` for more detail on argument style. .. topic:: Did you know ? @@ -1322,14 +1322,14 @@ to optimize the loading of this collection in a bit. Querying with Joins =================== -Now that we have two tables, we can show some more features of :class:`.Query`, +Now that we have two tables, we can show some more features of :class:`_query.Query`, specifically how to create queries that deal with both tables at the same time. The `Wikipedia page on SQL JOIN `_ offers a good introduction to join techniques, several of which we'll illustrate here. To construct a simple implicit join between ``User`` and ``Address``, -we can use :meth:`.Query.filter()` to equate their related columns together. +we can use :meth:`_query.Query.filter()` to equate their related columns together. Below we load the ``User`` and ``Address`` entities at once using this method: .. sourcecode:: python+sql @@ -1355,7 +1355,7 @@ Below we load the ``User`` and ``Address`` entities at once using this method: The actual SQL JOIN syntax, on the other hand, is most easily achieved -using the :meth:`.Query.join` method: +using the :meth:`_query.Query.join` method: .. sourcecode:: python+sql @@ -1371,9 +1371,9 @@ using the :meth:`.Query.join` method: ('jack@google.com',) {stop}[] -:meth:`.Query.join` knows how to join between ``User`` +:meth:`_query.Query.join` knows how to join between ``User`` and ``Address`` because there's only one foreign key between them. If there -were no foreign keys, or several, :meth:`.Query.join` +were no foreign keys, or several, :meth:`_query.Query.join` works better when one of the following forms are used:: query.join(Address, User.id==Address.user_id) # explicit condition @@ -1382,20 +1382,20 @@ works better when one of the following forms are used:: query.join('addresses') # same, using a string As you would expect, the same idea is used for "outer" joins, using the -:meth:`~.Query.outerjoin` function:: +:meth:`_query.Query.outerjoin` function:: query.outerjoin(User.addresses) # LEFT OUTER JOIN -The reference documentation for :meth:`~.Query.join` contains detailed information -and examples of the calling styles accepted by this method; :meth:`~.Query.join` +The reference documentation for :meth:`_query.Query.join` contains detailed information +and examples of the calling styles accepted by this method; :meth:`_query.Query.join` is an important method at the center of usage for any SQL-fluent application. -.. topic:: What does :class:`.Query` select from if there's multiple entities? +.. topic:: What does :class:`_query.Query` select from if there's multiple entities? - The :meth:`.Query.join` method will **typically join from the leftmost + The :meth:`_query.Query.join` method will **typically join from the leftmost item** in the list of entities, when the ON clause is omitted, or if the ON clause is a plain SQL expression. To control the first entity in the list - of JOINs, use the :meth:`.Query.select_from` method:: + of JOINs, use the :meth:`_query.Query.select_from` method:: query = session.query(User, Address).select_from(Address).join(User) @@ -1455,7 +1455,7 @@ get rows back for those users who don't have any addresses, e.g.:: Using the :class:`~sqlalchemy.orm.query.Query`, we build a statement like this from the inside out. The ``statement`` accessor returns a SQL expression representing the statement generated by a particular -:class:`~sqlalchemy.orm.query.Query` - this is an instance of a :func:`~.expression.select` +:class:`~sqlalchemy.orm.query.Query` - this is an instance of a :func:`_expression.select` construct, which are described in :ref:`sqlexpression_toplevel`:: >>> from sqlalchemy.sql import func @@ -1638,7 +1638,7 @@ and behavior: query.filter(Address.user.has(name='ed')) -* :meth:`.Query.with_parent` (used for any relationship):: +* :meth:`_query.Query.with_parent` (used for any relationship):: session.query(Address).with_parent(someuser, 'addresses') @@ -1651,15 +1651,15 @@ was emitted. If you want to reduce the number of queries (dramatically, in many we can apply an :term:`eager load` to the query operation. SQLAlchemy offers three types of eager loading, two of which are automatic, and a third which involves custom criterion. All three are usually invoked via functions known -as query options which give additional instructions to the :class:`.Query` on how -we would like various attributes to be loaded, via the :meth:`.Query.options` method. +as query options which give additional instructions to the :class:`_query.Query` on how +we would like various attributes to be loaded, via the :meth:`_query.Query.options` method. Selectin Load ------------- In this case we'd like to indicate that ``User.addresses`` should load eagerly. A good choice for loading a set of objects as well as their related collections -is the :func:`.orm.selectinload` option, which emits a second SELECT statement +is the :func:`_orm.selectinload` option, which emits a second SELECT statement that fully loads the collections associated with the results just loaded. The name "selectin" originates from the fact that the SELECT statement uses an IN clause in order to locate related rows for multiple objects @@ -1696,7 +1696,7 @@ Joined Load ----------- The other automatic eager loading function is more well known and is called -:func:`.orm.joinedload`. This style of loading emits a JOIN, by default +:func:`_orm.joinedload`. This style of loading emits a JOIN, by default a LEFT OUTER JOIN, so that the lead object as well as the related object or collection is loaded in one step. We illustrate loading the same ``addresses`` collection in this way - note that even though the ``User.addresses`` @@ -1729,13 +1729,13 @@ will emit the extra join regardless: [, ] Note that even though the OUTER JOIN resulted in two rows, we still only got -one instance of ``User`` back. This is because :class:`.Query` applies a "uniquing" +one instance of ``User`` back. This is because :class:`_query.Query` applies a "uniquing" strategy, based on object identity, to the returned entities. This is specifically so that joined eager loading can be applied without affecting the query results. -While :func:`.joinedload` has been around for a long time, :func:`.selectinload` +While :func:`_orm.joinedload` has been around for a long time, :func:`.selectinload` is a newer form of eager loading. :func:`.selectinload` tends to be more appropriate -for loading related collections while :func:`.joinedload` tends to be better suited +for loading related collections while :func:`_orm.joinedload` tends to be better suited for many-to-one relationships, due to the fact that only one row is loaded for both the lead and the related object. Another form of loading, :func:`.subqueryload`, also exists, which can be used in place of @@ -1744,11 +1744,11 @@ backends. .. topic:: ``joinedload()`` is not a replacement for ``join()`` - The join created by :func:`.joinedload` is anonymously aliased such that - it **does not affect the query results**. An :meth:`.Query.order_by` - or :meth:`.Query.filter` call **cannot** reference these aliased + The join created by :func:`_orm.joinedload` is anonymously aliased such that + it **does not affect the query results**. An :meth:`_query.Query.order_by` + or :meth:`_query.Query.filter` call **cannot** reference these aliased tables - so-called "user space" joins are constructed using - :meth:`.Query.join`. The rationale for this is that :func:`.joinedload` is only + :meth:`_query.Query.join`. The rationale for this is that :func:`_orm.joinedload` is only applied in order to affect how related objects or collections are loaded as an optimizing detail - it can be added or removed with no impact on actual results. See the section :ref:`zen_of_eager_loading` for @@ -1760,11 +1760,11 @@ Explicit Join + Eagerload A third style of eager loading is when we are constructing a JOIN explicitly in order to locate the primary rows, and would like to additionally apply the extra table to a related object or collection on the primary object. This feature -is supplied via the :func:`.orm.contains_eager` function, and is most +is supplied via the :func:`_orm.contains_eager` function, and is most typically useful for pre-loading the many-to-one object on a query that needs to filter on that same object. Below we illustrate loading an ``Address`` row as well as the related ``User`` object, filtering on the ``User`` named -"jack" and using :func:`.orm.contains_eager` to apply the "user" columns to the ``Address.user`` +"jack" and using :func:`_orm.contains_eager` to apply the "user" columns to the ``Address.user`` attribute: .. sourcecode:: python+sql @@ -1890,7 +1890,7 @@ the ``Address.user`` relationship via the ``User`` class already:: ... def __repr__(self): ... return "" % self.email_address -Now when we load the user ``jack`` (below using :meth:`~.Query.get`, +Now when we load the user ``jack`` (below using :meth:`_query.Query.get`, which loads by primary key), removing an address from the corresponding ``addresses`` collection will result in that ``Address`` being deleted: @@ -1985,7 +1985,7 @@ relationship. We'll sneak in some other features too, just to take a tour. We'll make our application a blog application, where users can write ``BlogPost`` items, which have ``Keyword`` items associated with them. -For a plain many-to-many, we need to create an un-mapped :class:`.Table` construct +For a plain many-to-many, we need to create an un-mapped :class:`_schema.Table` construct to serve as the association table. This looks like the following:: >>> from sqlalchemy import Table, Text @@ -1995,14 +1995,14 @@ to serve as the association table. This looks like the following:: ... Column('keyword_id', ForeignKey('keywords.id'), primary_key=True) ... ) -Above, we can see declaring a :class:`.Table` directly is a little different -than declaring a mapped class. :class:`.Table` is a constructor function, so -each individual :class:`.Column` argument is separated by a comma. The -:class:`.Column` object is also given its name explicitly, rather than it being +Above, we can see declaring a :class:`_schema.Table` directly is a little different +than declaring a mapped class. :class:`_schema.Table` is a constructor function, so +each individual :class:`_schema.Column` argument is separated by a comma. The +:class:`_schema.Column` object is also given its name explicitly, rather than it being taken from an assigned attribute name. Next we define ``BlogPost`` and ``Keyword``, using complementary -:func:`.relationship` constructs, each referring to the ``post_keywords`` +:func:`_orm.relationship` constructs, each referring to the ``post_keywords`` table as an association table:: >>> class BlogPost(Base): diff --git a/doc/build/orm/versioning.rst b/doc/build/orm/versioning.rst index f9ad0c5d5f..2697884f0d 100644 --- a/doc/build/orm/versioning.rst +++ b/doc/build/orm/versioning.rst @@ -3,7 +3,7 @@ Configuring a Version Counter ============================= -The :class:`.Mapper` supports management of a :term:`version id column`, which +The :class:`_orm.Mapper` supports management of a :term:`version id column`, which is a single table column that increments or otherwise updates its value each time an ``UPDATE`` to the mapped table occurs. This value is checked each time the ORM emits an ``UPDATE`` or ``DELETE`` against the row to ensure that @@ -15,7 +15,7 @@ the value held in memory matches the database value. record of an object, the feature only applies to the :meth:`.Session.flush` process, where the ORM flushes individual in-memory rows to the database. It does **not** take effect when performing - a multirow UPDATE or DELETE using :meth:`.Query.update` or :meth:`.Query.delete` + a multirow UPDATE or DELETE using :meth:`_query.Query.update` or :meth:`_query.Query.delete` methods, as these methods only emit an UPDATE or DELETE statement but otherwise do not have direct access to the contents of those rows being affected. diff --git a/doc/build/replacments/fix_xref_state.txt b/doc/build/replacments/fix_xref_state.txt deleted file mode 100644 index 380657df2e..0000000000 --- a/doc/build/replacments/fix_xref_state.txt +++ /dev/null @@ -1,93 +0,0 @@ -.MetaData _schema.MetaData -.ForeignKey _schema.ForeignKey -.ForeignKeyConstraint _schema.ForeignKeyConstraint -.PoolEvents _events.PoolEvents -.DisconnectionError _exc.DisconnectionError -.SADeprecationWarning _exc.SADeprecationWarning -.Engine _engine.Engine -.Pool _pool.Pool -.future _future -.inspect _sa.inspect -.Inspector _reflection.Inspector -.orm _orm -.Mapper _orm.Mapper -.engine _engine -.JSON _types.JSON -.postgresql _postgresql -.types _types -._mysql _mysql -.sqlite _sqlite -.array_agg _functions.array_agg -.TIMESTAMP _types.TIMESTAMP -.JSONB _postgresql.JSONB -.ARRAY _types.ARRAY -.mssql _mssql -.sqltypes _types -.functions _functions -.INTERVAL _postgresql.INTERVAL -.INTERVAL _oracle.INTERVAL -.oracle _oracle -.NCHAR _types.NCHAR -.Query _query.Query -.relationship _orm.relationship -.FromClause _expression.FromClause -.join _expression.join -.SelectBase _expression.SelectBase -.Load _orm.Load -.joinedload _orm.joinedload -.sql _expression -.sql.expression _expression -.INTEGER _types.INTEGER -.VARBINARY _types.VARBINARY -.joinedload_all _orm.joinedload_all -.Insert _expression.Insert -.Update _expression.Update -.Delete _expression.Delete -.insert _expression.insert -.update _expression.update -.delete _expression.delete -.select _expression.select -.expression _expression -.future _future.Subquery _expression.Subquery -.Select _expression.Select -.ReturnsRows _expression.ReturnsRows -.ColumnCollection _expression.ColumnCollection -.ColumnElement _expression.ColumnElement -.Selectable expression.Selectable -.Lateral _expression.Lateral -.HasPrefixes _expression.HasPrefixes -.prefix_with _expression.HasPrefixes.prefix_with -.ClauseElement _expression.ClauseElement -.HasSuffixes _expression.HasSuffixes -.suffix_with _expression.HasSuffixes.suffix_with -.Table _schema.Table -.Join _expression.Join -.Alias _expression.Alias -.TableSample _expression.TableSample -.CTE _expression.CTE -.HasCte _expression.HasCTE -.HasCTE _expression.HasCTE -.CompoundSelect _selectable.CompoundSelect -.TextualSelect _expression.TextualSelect -.TableClause _expression.TableClause -.schema _schema -.Values _expression.Values -.column _expression.column -.GenerativeSelect _expression.GenerativeSelect -.Column _schema.Column -.union _expression.union -.union_all _expression.union_all -.intersect _expression.intersect -.intersect_all _expression.intersect_all -.except _expression.except -.except_all _expression.except_all -.Text _expression.TextClause -.text _expression.text -.literal_column _expression.literal_column -.Connection _engine.Connection -.Engine _engine.Engine -.apply_labels _expression.Select.apply_labels -.BooleanClauseList _expression.BooleanClauseList -.ScalarSelect _expression.ScalarSelect -.Exists _expression.Exists -.TextClause _expression.TextClause diff --git a/lib/sqlalchemy/dialects/firebird/fdb.py b/lib/sqlalchemy/dialects/firebird/fdb.py index 46acd05595..7a7b875365 100644 --- a/lib/sqlalchemy/dialects/firebird/fdb.py +++ b/lib/sqlalchemy/dialects/firebird/fdb.py @@ -38,7 +38,7 @@ accept every argument that Kinterbasdb does. of Firebird, and setting this flag to False will also cause the SQLAlchemy ORM to ignore its usage. The behavior can also be controlled on a per-execution basis using the ``enable_rowcount`` option with - :meth:`.Connection.execution_options`:: + :meth:`_engine.Connection.execution_options`:: conn = engine.connect().execution_options(enable_rowcount=True) r = conn.execute(stmt) diff --git a/lib/sqlalchemy/dialects/mssql/base.py b/lib/sqlalchemy/dialects/mssql/base.py index 43f3aeb040..b5c49246fb 100644 --- a/lib/sqlalchemy/dialects/mssql/base.py +++ b/lib/sqlalchemy/dialects/mssql/base.py @@ -18,8 +18,10 @@ SQL Server provides so-called "auto incrementing" behavior using the ``IDENTITY`` construct, which can be placed on any single integer column in a table. SQLAlchemy considers ``IDENTITY`` within its default "autoincrement" behavior for an integer primary key column, described at -:paramref:`.Column.autoincrement`. This means that by default, the first -integer primary key column in a :class:`.Table` will be considered to be the +:paramref:`_schema.Column.autoincrement`. This means that by default, +the first +integer primary key column in a :class:`_schema.Table` +will be considered to be the identity column and will generate DDL as such:: from sqlalchemy import Table, MetaData, Column, Integer @@ -41,7 +43,7 @@ The above example will generate DDL as: ) For the case where this default generation of ``IDENTITY`` is not desired, -specify ``False`` for the :paramref:`.Column.autoincrement` flag, +specify ``False`` for the :paramref:`_schema.Column.autoincrement` flag, on the first integer primary key column:: m = MetaData() @@ -51,8 +53,9 @@ on the first integer primary key column:: m.create_all(engine) To add the ``IDENTITY`` keyword to a non-primary key column, specify -``True`` for the :paramref:`.Column.autoincrement` flag on the desired -:class:`.Column` object, and ensure that :paramref:`.Column.autoincrement` +``True`` for the :paramref:`_schema.Column.autoincrement` flag on the desired +:class:`_schema.Column` object, and ensure that +:paramref:`_schema.Column.autoincrement` is set to ``False`` on any integer primary key column:: m = MetaData() @@ -62,7 +65,8 @@ is set to ``False`` on any integer primary key column:: m.create_all(engine) .. versionchanged:: 1.3 Added ``mssql_identity_start`` and - ``mssql_identity_increment`` parameters to :class:`.Column`. These replace + ``mssql_identity_increment`` parameters to :class:`_schema.Column`. + These replace the use of the :class:`.Sequence` object in order to specify these values. .. deprecated:: 1.3 @@ -85,7 +89,8 @@ is set to ``False`` on any integer primary key column:: marked with IDENTITY will be rejected by SQL Server. In order for the value to be accepted, a session-level option "SET IDENTITY_INSERT" must be enabled. The SQLAlchemy SQL Server dialect will perform this operation - automatically when using a core :class:`~.sql.expression.Insert` construct; if the + automatically when using a core :class:`_expression.Insert` + construct; if the execution specifies a value for the IDENTITY column, the "IDENTITY_INSERT" option will be enabled for the span of that statement's invocation.However, this scenario is not high performing and should not be relied upon for @@ -99,7 +104,7 @@ Controlling "Start" and "Increment" Specific control over the "start" and "increment" values for the ``IDENTITY`` generator are provided using the ``mssql_identity_start`` and ``mssql_identity_increment`` parameters -passed to the :class:`.Column` object:: +passed to the :class:`_schema.Column` object:: from sqlalchemy import Table, Integer, Column @@ -112,7 +117,7 @@ passed to the :class:`.Column` object:: Column('name', String(20)) ) -The CREATE TABLE for the above :class:`.Table` object would be: +The CREATE TABLE for the above :class:`_schema.Table` object would be: .. sourcecode:: sql @@ -123,7 +128,7 @@ The CREATE TABLE for the above :class:`.Table` object would be: .. versionchanged:: 1.3 The ``mssql_identity_start`` and ``mssql_identity_increment`` parameters are now used to affect the - ``IDENTITY`` generator for a :class:`.Column` under SQL Server. + ``IDENTITY`` generator for a :class:`_schema.Column` under SQL Server. Previously, the :class:`.Sequence` object was used. As SQL Server now supports real sequences as a separate construct, :class:`.Sequence` will be functional in the normal way in a future SQLAlchemy version. @@ -171,7 +176,8 @@ The process for fetching this value has several variants: A table that contains an ``IDENTITY`` column will prohibit an INSERT statement that refers to the identity column explicitly. The SQLAlchemy dialect will -detect when an INSERT construct, created using a core :func:`~.sql.expression.insert` +detect when an INSERT construct, created using a core +:func:`_expression.insert` construct (not a plain string SQL), refers to the identity column, and in this case will emit ``SET IDENTITY_INSERT ON`` prior to the insert statement proceeding, and ``SET IDENTITY_INSERT OFF`` subsequent to the @@ -213,7 +219,7 @@ MAX on VARCHAR / NVARCHAR ------------------------- SQL Server supports the special string "MAX" within the -:class:`.sqltypes.VARCHAR` and :class:`.sqltypes.NVARCHAR` datatypes, +:class:`_types.VARCHAR` and :class:`_types.NVARCHAR` datatypes, to indicate "maximum length possible". The dialect currently handles this as a length of "None" in the base type, rather than supplying a dialect-specific version of these types, so that a base type @@ -238,7 +244,7 @@ specified by the string argument "collation":: from sqlalchemy import VARCHAR Column('login', VARCHAR(32, collation='Latin1_General_CI_AS')) -When such a column is associated with a :class:`.Table`, the +When such a column is associated with a :class:`_schema.Table`, the CREATE TABLE statement for this column will yield:: login VARCHAR(32) COLLATE Latin1_General_CI_AS NULL @@ -291,7 +297,8 @@ both via a dialect-specific parameter accepted by :func:`.create_engine`, as well as the :paramref:`.Connection.execution_options.isolation_level` argument as passed to -:meth:`.Connection.execution_options`. This feature works by issuing the +:meth:`_engine.Connection.execution_options`. +This feature works by issuing the command ``SET TRANSACTION ISOLATION LEVEL `` for each new connection. @@ -358,19 +365,22 @@ Per `SQL Server 2012/2014 Documentation `_, the ``NTEXT``, ``TEXT`` and ``IMAGE`` datatypes are to be removed from SQL Server in a future release. SQLAlchemy normally relates these types to the -:class:`.UnicodeText`, :class:`.Text` and :class:`.LargeBinary` datatypes. +:class:`.UnicodeText`, :class:`_expression.TextClause` and +:class:`.LargeBinary` datatypes. In order to accommodate this change, a new flag ``deprecate_large_types`` is added to the dialect, which will be automatically set based on detection of the server version in use, if not otherwise set by the user. The behavior of this flag is as follows: -* When this flag is ``True``, the :class:`.UnicodeText`, :class:`.Text` and +* When this flag is ``True``, the :class:`.UnicodeText`, + :class:`_expression.TextClause` and :class:`.LargeBinary` datatypes, when used to render DDL, will render the types ``NVARCHAR(max)``, ``VARCHAR(max)``, and ``VARBINARY(max)``, respectively. This is a new behavior as of the addition of this flag. -* When this flag is ``False``, the :class:`.UnicodeText`, :class:`.Text` and +* When this flag is ``False``, the :class:`.UnicodeText`, + :class:`_expression.TextClause` and :class:`.LargeBinary` datatypes, when used to render DDL, will render the types ``NTEXT``, ``TEXT``, and ``IMAGE``, respectively. This is the long-standing behavior of these types. @@ -391,9 +401,10 @@ behavior of this flag is as follows: * Complete control over whether the "old" or "new" types are rendered is available in all SQLAlchemy versions by using the UPPERCASE type objects - instead: :class:`.types.NVARCHAR`, :class:`.types.VARCHAR`, - :class:`.types.VARBINARY`, :class:`.types.TEXT`, :class:`.mssql.NTEXT`, - :class:`.mssql.IMAGE` will always remain fixed and always output exactly that + instead: :class:`_types.NVARCHAR`, :class:`_types.VARCHAR`, + :class:`_types.VARBINARY`, :class:`_types.TEXT`, :class:`_mssql.NTEXT`, + :class:`_mssql.IMAGE` + will always remain fixed and always output exactly that type. .. versionadded:: 1.0.0 @@ -406,7 +417,8 @@ Multipart Schema Names SQL Server schemas sometimes require multiple parts to their "schema" qualifier, that is, including the database name and owner name as separate tokens, such as ``mydatabase.dbo.some_table``. These multipart names can be set -at once using the :paramref:`.Table.schema` argument of :class:`.Table`:: +at once using the :paramref:`_schema.Table.schema` argument of +:class:`_schema.Table`:: Table( "some_table", metadata, @@ -609,7 +621,7 @@ generated primary key values via IDENTITY columns or other server side defaults. MS-SQL does not allow the usage of OUTPUT INSERTED on tables that have triggers. To disable the usage of OUTPUT INSERTED on a per-table basis, -specify ``implicit_returning=False`` for each :class:`.Table` +specify ``implicit_returning=False`` for each :class:`_schema.Table` which has triggers:: Table('mytable', metadata, @@ -645,8 +657,8 @@ verifies that the version identifier matched. When this condition occurs, a warning will be emitted but the operation will proceed. The use of OUTPUT INSERTED can be disabled by setting the -:paramref:`.Table.implicit_returning` flag to ``False`` on a particular -:class:`.Table`, which in declarative looks like:: +:paramref:`_schema.Table.implicit_returning` flag to ``False`` on a particular +:class:`_schema.Table`, which in declarative looks like:: class MyTable(Base): __tablename__ = 'mytable' @@ -1072,7 +1084,7 @@ class TIMESTAMP(sqltypes._Binary): .. seealso:: - :class:`.mssql.ROWVERSION` + :class:`_mssql.ROWVERSION` """ @@ -1117,7 +1129,7 @@ class ROWVERSION(TIMESTAMP): The ROWVERSION datatype does **not** reflect (e.g. introspect) from the database as itself; the returned datatype will be - :class:`.mssql.TIMESTAMP`. + :class:`_mssql.TIMESTAMP`. This is a read-only datatype that does not support INSERT of values. @@ -1125,7 +1137,7 @@ class ROWVERSION(TIMESTAMP): .. seealso:: - :class:`.mssql.TIMESTAMP` + :class:`_mssql.TIMESTAMP` """ @@ -1145,7 +1157,7 @@ class VARBINARY(sqltypes.VARBINARY, sqltypes.LargeBinary): This type is present to support "deprecate_large_types" mode where either ``VARBINARY(max)`` or IMAGE is rendered. Otherwise, this type - object is redundant vs. :class:`.types.VARBINARY`. + object is redundant vs. :class:`_types.VARBINARY`. .. versionadded:: 1.0.0 diff --git a/lib/sqlalchemy/dialects/mysql/base.py b/lib/sqlalchemy/dialects/mysql/base.py index a075b4d6bd..e44dfa8296 100644 --- a/lib/sqlalchemy/dialects/mysql/base.py +++ b/lib/sqlalchemy/dialects/mysql/base.py @@ -79,7 +79,8 @@ to ``MyISAM`` for this value, although newer versions may be defaulting to ``InnoDB``. The ``InnoDB`` engine is typically preferred for its support of transactions and foreign keys. -A :class:`.Table` that is created in a MySQL database with a storage engine +A :class:`_schema.Table` +that is created in a MySQL database with a storage engine of ``MyISAM`` will be essentially non-transactional, meaning any INSERT/UPDATE/DELETE statement referring to this table will be invoked as autocommit. It also will have no support for foreign key constraints; while @@ -122,7 +123,8 @@ All MySQL dialects support setting of transaction isolation level both via a dialect-specific parameter :paramref:`.create_engine.isolation_level` accepted by :func:`.create_engine`, as well as the :paramref:`.Connection.execution_options.isolation_level` argument as passed to -:meth:`.Connection.execution_options`. This feature works by issuing the +:meth:`_engine.Connection.execution_options`. +This feature works by issuing the command ``SET SESSION TRANSACTION ISOLATION LEVEL `` for each new connection. For the special AUTOCOMMIT isolation level, DBAPI-specific techniques are used. @@ -174,7 +176,8 @@ foreign key:: ) You can disable this behavior by passing ``False`` to the -:paramref:`~.Column.autoincrement` argument of :class:`.Column`. This flag +:paramref:`_schema.Column.autoincrement` argument of :class:`_schema.Column`. +This flag can also be used to enable auto-increment on a secondary column in a multi-column key for some storage engines:: @@ -301,7 +304,8 @@ MySQL features two varieties of identifier "quoting style", one using backticks and the other using quotes, e.g. ```some_identifier``` vs. ``"some_identifier"``. All MySQL dialects detect which version is in use by checking the value of ``sql_mode`` when a connection is first -established with a particular :class:`.Engine`. This quoting style comes +established with a particular :class:`_engine.Engine`. +This quoting style comes into play when rendering table and column names as well as when reflecting existing database structures. The detection is entirely automatic and no special configuration is needed to use either quoting style. @@ -323,7 +327,8 @@ available. * INSERT..ON DUPLICATE KEY UPDATE: See :ref:`mysql_insert_on_duplicate_key_update` -* SELECT pragma, use :meth:`.Select.prefix_with` and :meth:`.Query.prefix_with`:: +* SELECT pragma, use :meth:`_expression.Select.prefix_with` and + :meth:`_query.Query.prefix_with`:: select(...).prefix_with(['HIGH_PRIORITY', 'SQL_SMALL_RESULT']) @@ -331,11 +336,13 @@ available. update(..., mysql_limit=10) -* optimizer hints, use :meth:`.Select.prefix_with` and :meth:`.Query.prefix_with`:: +* optimizer hints, use :meth:`_expression.Select.prefix_with` and + :meth:`_query.Query.prefix_with`:: select(...).prefix_with("/*+ NO_RANGE_OPTIMIZATION(t4 PRIMARY) */") -* index hints, use :meth:`.Select.with_hint` and :meth:`.Query.with_hint`:: +* index hints, use :meth:`_expression.Select.with_hint` and + :meth:`_query.Query.with_hint`:: select(...).with_hint(some_table, "USE INDEX xyz") @@ -379,7 +386,8 @@ from the proposed insertion. These values are normally specified using keyword arguments passed to the :meth:`~.mysql.Insert.on_duplicate_key_update` given column key values (usually the name of the column, unless it -specifies :paramref:`.Column.key`) as keys and literal or SQL expressions +specifies :paramref:`_schema.Column.key` +) as keys and literal or SQL expressions as values:: on_duplicate_key_stmt = insert_stmt.on_duplicate_key_update( @@ -396,7 +404,8 @@ forms are accepted, including a single dictionary:: as well as a list of 2-tuples, which will automatically provide a parameter-ordered UPDATE statement in a manner similar to that described -at :ref:`updates_order_parameters`. Unlike the :class:`.Update` object, +at :ref:`updates_order_parameters`. Unlike the :class:`_expression.Update` +object, no special flag is needed to specify the intent since the argument form is this context is unambiguous:: @@ -412,9 +421,10 @@ this context is unambiguous:: .. warning:: - The :meth:`.Insert.on_duplicate_key_update` method does **not** take into + The :meth:`_expression.Insert.on_duplicate_key_update` + method does **not** take into account Python-side default UPDATE values or generation functions, e.g. - e.g. those specified using :paramref:`.Column.onupdate`. + e.g. those specified using :paramref:`_schema.Column.onupdate`. These values will not be exercised for an ON DUPLICATE KEY style of UPDATE, unless they are manually specified explicitly in the parameters. @@ -423,7 +433,7 @@ this context is unambiguous:: In order to refer to the proposed insertion row, the special alias :attr:`~.mysql.Insert.inserted` is available as an attribute on the :class:`.mysql.Insert` object; this object is a -:class:`.ColumnCollection` which contains all columns of the target +:class:`_expression.ColumnCollection` which contains all columns of the target table:: from sqlalchemy.dialects.mysql import insert @@ -586,7 +596,8 @@ Foreign Key Arguments to Avoid MySQL does not support the foreign key arguments "DEFERRABLE", "INITIALLY", or "MATCH". Using the ``deferrable`` or ``initially`` keyword argument with -:class:`.ForeignKeyConstraint` or :class:`.ForeignKey` will have the effect of +:class:`_schema.ForeignKeyConstraint` or :class:`_schema.ForeignKey` +will have the effect of these keywords being rendered in a DDL expression, which will then raise an error on MySQL. In order to use these keywords on a foreign key while having them ignored on a MySQL backend, use a custom compile rule:: @@ -601,7 +612,7 @@ them ignored on a MySQL backend, use a custom compile rule:: .. versionchanged:: 0.9.0 - the MySQL backend no longer silently ignores the ``deferrable`` or ``initially`` keyword arguments of - :class:`.ForeignKeyConstraint` and :class:`.ForeignKey`. + :class:`_schema.ForeignKeyConstraint` and :class:`_schema.ForeignKey`. The "MATCH" keyword is in fact more insidious, and is explicitly disallowed by SQLAlchemy in conjunction with the MySQL backend. This argument is @@ -613,7 +624,7 @@ ForeignKeyConstraint at DDL definition time. .. versionadded:: 0.9.0 - the MySQL backend will raise a :class:`.CompileError` when the ``match`` keyword is used with - :class:`.ForeignKeyConstraint` or :class:`.ForeignKey`. + :class:`_schema.ForeignKeyConstraint` or :class:`_schema.ForeignKey`. Reflection of Foreign Key Constraints ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -645,14 +656,16 @@ these constraints. However, MySQL does not have a unique constraint construct that is separate from a unique index; that is, the "UNIQUE" constraint on MySQL is equivalent to creating a "UNIQUE INDEX". -When reflecting these constructs, the :meth:`.Inspector.get_indexes` -and the :meth:`.Inspector.get_unique_constraints` methods will **both** +When reflecting these constructs, the +:meth:`_reflection.Inspector.get_indexes` +and the :meth:`_reflection.Inspector.get_unique_constraints` +methods will **both** return an entry for a UNIQUE index in MySQL. However, when performing full table reflection using ``Table(..., autoload=True)``, the :class:`.UniqueConstraint` construct is -**not** part of the fully reflected :class:`.Table` construct under any +**not** part of the fully reflected :class:`_schema.Table` construct under any circumstances; this construct is always represented by a :class:`.Index` -with the ``unique=True`` setting present in the :attr:`.Table.indexes` +with the ``unique=True`` setting present in the :attr:`_schema.Table.indexes` collection. @@ -1438,7 +1451,7 @@ class MySQLCompiler(compiler.SQLCompiler): .. note:: - this usage is deprecated. :meth:`.Select.prefix_with` + this usage is deprecated. :meth:`_expression.Select.prefix_with` should be used for special keywords at the start of a SELECT. diff --git a/lib/sqlalchemy/dialects/mysql/dml.py b/lib/sqlalchemy/dialects/mysql/dml.py index 531b31bc33..c19ed6c0ba 100644 --- a/lib/sqlalchemy/dialects/mysql/dml.py +++ b/lib/sqlalchemy/dialects/mysql/dml.py @@ -31,12 +31,13 @@ class Insert(StandardInsert): This attribute provides all columns in this row to be referenceable such that they will render within a ``VALUES()`` function inside the ON DUPLICATE KEY UPDATE clause. The attribute is named ``.inserted`` - so as not to conflict with the existing :meth:`.Insert.values` method. + so as not to conflict with the existing + :meth:`_expression.Insert.values` method. .. seealso:: :ref:`mysql_insert_on_duplicate_key_update` - example of how - to use :attr:`.Insert.inserted` + to use :attr:`_expression.Insert.inserted` """ return self.inserted_alias.columns @@ -56,7 +57,7 @@ class Insert(StandardInsert): .. warning:: This dictionary does **not** take into account Python-specified default UPDATE values or generation functions, - e.g. those specified using :paramref:`.Column.onupdate`. + e.g. those specified using :paramref:`_schema.Column.onupdate`. These values will not be exercised for an ON DUPLICATE KEY UPDATE style of UPDATE, unless values are manually specified here. @@ -71,7 +72,8 @@ class Insert(StandardInsert): Passing a list of 2-tuples indicates that the parameter assignments in the UPDATE clause should be ordered as sent, in a manner similar - to that described for the :class:`.Update` construct overall + to that described for the :class:`_expression.Update` + construct overall in :ref:`updates_order_parameters`:: insert().on_duplicate_key_update( diff --git a/lib/sqlalchemy/dialects/mysql/json.py b/lib/sqlalchemy/dialects/mysql/json.py index 10354842fd..733a4d696b 100644 --- a/lib/sqlalchemy/dialects/mysql/json.py +++ b/lib/sqlalchemy/dialects/mysql/json.py @@ -17,7 +17,7 @@ class JSON(sqltypes.JSON): support JSON at the time of this writing. The :class:`.mysql.JSON` type supports persistence of JSON values - as well as the core index operations provided by :class:`.types.JSON` + as well as the core index operations provided by :class:`_types.JSON` datatype, by adapting the operations to render the ``JSON_EXTRACT`` function at the database level. diff --git a/lib/sqlalchemy/dialects/oracle/base.py b/lib/sqlalchemy/dialects/oracle/base.py index ae869b9214..bbf65371c5 100644 --- a/lib/sqlalchemy/dialects/oracle/base.py +++ b/lib/sqlalchemy/dialects/oracle/base.py @@ -61,7 +61,7 @@ of isolation, however the SQLAlchemy Oracle dialect currently only has explicit support for "READ COMMITTED". It is possible to emit a "SET TRANSACTION" statement on a connection in order to use SERIALIZABLE isolation, however the SQLAlchemy dialect will remain unaware of this setting, -such as if the :meth:`.Connection.get_isolation_level` method is used; +such as if the :meth:`_engine.Connection.get_isolation_level` method is used; this method is hardcoded to return "READ COMMITTED" right now. The AUTOCOMMIT isolation level is also supported by the cx_Oracle dialect. @@ -304,7 +304,7 @@ Synonym/DBLINK Reflection When using reflection with Table objects, the dialect can optionally search for tables indicated by synonyms, either in local or remote schemas or accessed over DBLINK, by passing the flag ``oracle_resolve_synonyms=True`` as -a keyword argument to the :class:`.Table` construct:: +a keyword argument to the :class:`_schema.Table` construct:: some_table = Table('some_table', autoload=True, autoload_with=some_engine, @@ -318,8 +318,8 @@ knows how to locate the table's information using DBLINK syntax(e.g. ``@dblink``). ``oracle_resolve_synonyms`` is accepted wherever reflection arguments are -accepted, including methods such as :meth:`.MetaData.reflect` and -:meth:`.Inspector.get_columns`. +accepted, including methods such as :meth:`_schema.MetaData.reflect` and +:meth:`_reflection.Inspector.get_columns`. If synonyms are not in use, this flag should be left disabled. @@ -332,18 +332,22 @@ The Oracle dialect can return information about foreign key, unique, and CHECK constraints, as well as indexes on tables. Raw information regarding these constraints can be acquired using -:meth:`.Inspector.get_foreign_keys`, :meth:`.Inspector.get_unique_constraints`, -:meth:`.Inspector.get_check_constraints`, and :meth:`.Inspector.get_indexes`. +:meth:`_reflection.Inspector.get_foreign_keys`, +:meth:`_reflection.Inspector.get_unique_constraints`, +:meth:`_reflection.Inspector.get_check_constraints`, and +:meth:`_reflection.Inspector.get_indexes`. .. versionchanged:: 1.2 The Oracle dialect can now reflect UNIQUE and CHECK constraints. -When using reflection at the :class:`.Table` level, the :class:`.Table` +When using reflection at the :class:`_schema.Table` level, the +:class:`_schema.Table` will also include these constraints. Note the following caveats: -* When using the :meth:`.Inspector.get_check_constraints` method, Oracle +* When using the :meth:`_reflection.Inspector.get_check_constraints` method, + Oracle builds a special "IS NOT NULL" constraint for columns that specify "NOT NULL". This constraint is **not** returned by default; to include the "IS NOT NULL" constraints, pass the flag ``include_all=True``:: @@ -355,11 +359,13 @@ Note the following caveats: all_check_constraints = inspector.get_check_constraints( "some_table", include_all=True) -* in most cases, when reflecting a :class:`.Table`, a UNIQUE constraint will +* in most cases, when reflecting a :class:`_schema.Table`, + a UNIQUE constraint will **not** be available as a :class:`.UniqueConstraint` object, as Oracle mirrors unique constraints with a UNIQUE index in most cases (the exception seems to be when two or more unique constraints represent the same columns); - the :class:`.Table` will instead represent these using :class:`.Index` + the :class:`_schema.Table` will instead represent these using + :class:`.Index` with the ``unique=True`` flag set. * Oracle creates an implicit index for the primary key of a table; this index @@ -371,11 +377,12 @@ Note the following caveats: Table names with SYSTEM/SYSAUX tablespaces ------------------------------------------- -The :meth:`.Inspector.get_table_names` and -:meth:`.Inspector.get_temp_table_names` +The :meth:`_reflection.Inspector.get_table_names` and +:meth:`_reflection.Inspector.get_temp_table_names` methods each return a list of table names for the current engine. These methods are also part of the reflection which occurs within an operation such as -:meth:`.MetaData.reflect`. By default, these operations exclude the ``SYSTEM`` +:meth:`_schema.MetaData.reflect`. By default, +these operations exclude the ``SYSTEM`` and ``SYSAUX`` tablespaces from the operation. In order to change this, the default list of tablespaces excluded can be changed at the engine level using the ``exclude_tablespaces`` parameter:: @@ -392,15 +399,15 @@ DateTime Compatibility Oracle has no datatype known as ``DATETIME``, it instead has only ``DATE``, which can actually store a date and time value. For this reason, the Oracle -dialect provides a type :class:`.oracle.DATE` which is a subclass of +dialect provides a type :class:`_oracle.DATE` which is a subclass of :class:`.DateTime`. This type has no special behavior, and is only present as a "marker" for this type; additionally, when a database column is reflected and the type is reported as ``DATE``, the time-supporting -:class:`.oracle.DATE` type is used. +:class:`_oracle.DATE` type is used. -.. versionchanged:: 0.9.4 Added :class:`.oracle.DATE` to subclass +.. versionchanged:: 0.9.4 Added :class:`_oracle.DATE` to subclass :class:`.DateTime`. This is a change as previous versions - would reflect a ``DATE`` column as :class:`.types.DATE`, which subclasses + would reflect a ``DATE`` column as :class:`_types.DATE`, which subclasses :class:`.Date`. The only significance here is for schemes that are examining the type of column for use in special Python translations or for migrating schemas to other database backends. @@ -411,7 +418,7 @@ Oracle Table Options ------------------------- The CREATE TABLE phrase supports the following options with Oracle -in conjunction with the :class:`.Table` construct: +in conjunction with the :class:`_schema.Table` construct: * ``ON COMMIT``:: @@ -584,7 +591,7 @@ class DATE(sqltypes.DateTime): """Provide the oracle DATE type. This type has no special Python behavior, except that it subclasses - :class:`.types.DateTime`; this is to suit the fact that the Oracle + :class:`_types.DateTime`; this is to suit the fact that the Oracle ``DATE`` type supports a time value. .. versionadded:: 0.9.4 diff --git a/lib/sqlalchemy/dialects/oracle/cx_oracle.py b/lib/sqlalchemy/dialects/oracle/cx_oracle.py index 0f41d7ed85..2cbf5b04a7 100644 --- a/lib/sqlalchemy/dialects/oracle/cx_oracle.py +++ b/lib/sqlalchemy/dialects/oracle/cx_oracle.py @@ -97,8 +97,8 @@ as that the ``NLS_LANG`` environment variable is set appropriately, so that the VARCHAR2 and CLOB datatypes can accommodate the data. In the case that the Oracle database is not configured with a Unicode character -set, the two options are to use the :class:`.oracle.NCHAR` and -:class:`.oracle.NCLOB` datatypes explicitly, or to pass the flag +set, the two options are to use the :class:`_oracle.NCHAR` and +:class:`_oracle.NCLOB` datatypes explicitly, or to pass the flag ``use_nchar_for_unicode=True`` to :func:`.create_engine`, which will cause the SQLAlchemy dialect to use NCHAR/NCLOB for the :class:`.Unicode` / :class:`.UnicodeText` datatypes instead of VARCHAR/CLOB. @@ -260,12 +260,12 @@ Precision Numerics SQLAlchemy's numeric types can handle receiving and returning values as Python ``Decimal`` objects or float objects. When a :class:`.Numeric` object, or a -subclass such as :class:`.Float`, :class:`.oracle.DOUBLE_PRECISION` etc. is in +subclass such as :class:`.Float`, :class:`_oracle.DOUBLE_PRECISION` etc. is in use, the :paramref:`.Numeric.asdecimal` flag determines if values should be coerced to ``Decimal`` upon return, or returned as float objects. To make matters more complicated under Oracle, Oracle's ``NUMBER`` type can also represent integer values if the "scale" is zero, so the Oracle-specific -:class:`.oracle.NUMBER` type takes this into account as well. +:class:`_oracle.NUMBER` type takes this into account as well. The cx_Oracle dialect makes extensive use of connection- and cursor-level "outputtypehandler" callables in order to coerce numeric values as requested. diff --git a/lib/sqlalchemy/dialects/postgresql/array.py b/lib/sqlalchemy/dialects/postgresql/array.py index 9f0f676cd4..a3537ba601 100644 --- a/lib/sqlalchemy/dialects/postgresql/array.py +++ b/lib/sqlalchemy/dialects/postgresql/array.py @@ -25,7 +25,7 @@ def Any(other, arrexpr, operator=operators.eq): .. seealso:: - :func:`.expression.any_` + :func:`_expression.any_` """ @@ -39,7 +39,7 @@ def All(other, arrexpr, operator=operators.eq): .. seealso:: - :func:`.expression.all_` + :func:`_expression.all_` """ @@ -68,14 +68,16 @@ class array(expression.Tuple): ARRAY[%(param_3)s, %(param_4)s, %(param_5)s]) AS anon_1 An instance of :class:`.array` will always have the datatype - :class:`.ARRAY`. The "inner" type of the array is inferred from + :class:`_types.ARRAY`. The "inner" type of the array is inferred from the values present, unless the ``type_`` keyword argument is passed:: array(['foo', 'bar'], type_=CHAR) Multidimensional arrays are produced by nesting :class:`.array` constructs. - The dimensionality of the final :class:`.ARRAY` type is calculated by - recursively adding the dimensions of the inner :class:`.ARRAY` type:: + The dimensionality of the final :class:`_types.ARRAY` + type is calculated by + recursively adding the dimensions of the inner :class:`_types.ARRAY` + type:: stmt = select([ array([ @@ -93,7 +95,7 @@ class array(expression.Tuple): .. seealso:: - :class:`.postgresql.ARRAY` + :class:`_postgresql.ARRAY` """ @@ -150,11 +152,11 @@ class ARRAY(sqltypes.ARRAY): """PostgreSQL ARRAY type. - .. versionchanged:: 1.1 The :class:`.postgresql.ARRAY` type is now - a subclass of the core :class:`.types.ARRAY` type. + .. versionchanged:: 1.1 The :class:`_postgresql.ARRAY` type is now + a subclass of the core :class:`_types.ARRAY` type. - The :class:`.postgresql.ARRAY` type is constructed in the same way - as the core :class:`.types.ARRAY` type; a member type is required, and a + The :class:`_postgresql.ARRAY` type is constructed in the same way + as the core :class:`_types.ARRAY` type; a member type is required, and a number of dimensions is recommended if the type is to be used for more than one dimension:: @@ -164,11 +166,12 @@ class ARRAY(sqltypes.ARRAY): Column("data", postgresql.ARRAY(Integer, dimensions=2)) ) - The :class:`.postgresql.ARRAY` type provides all operations defined on the - core :class:`.types.ARRAY` type, including support for "dimensions", + The :class:`_postgresql.ARRAY` type provides all operations defined on the + core :class:`_types.ARRAY` type, including support for "dimensions", indexed access, and simple matching such as :meth:`.types.ARRAY.Comparator.any` and - :meth:`.types.ARRAY.Comparator.all`. :class:`.postgresql.ARRAY` class also + :meth:`.types.ARRAY.Comparator.all`. :class:`_postgresql.ARRAY` + class also provides PostgreSQL-specific methods for containment operations, including :meth:`.postgresql.ARRAY.Comparator.contains` :meth:`.postgresql.ARRAY.Comparator.contained_by`, and @@ -176,24 +179,25 @@ class ARRAY(sqltypes.ARRAY): mytable.c.data.contains([1, 2]) - The :class:`.postgresql.ARRAY` type may not be supported on all + The :class:`_postgresql.ARRAY` type may not be supported on all PostgreSQL DBAPIs; it is currently known to work on psycopg2 only. - Additionally, the :class:`.postgresql.ARRAY` type does not work directly in + Additionally, the :class:`_postgresql.ARRAY` + type does not work directly in conjunction with the :class:`.ENUM` type. For a workaround, see the special type at :ref:`postgresql_array_of_enum`. .. seealso:: - :class:`.types.ARRAY` - base array type + :class:`_types.ARRAY` - base array type - :class:`.postgresql.array` - produces a literal array value. + :class:`_postgresql.array` - produces a literal array value. """ class Comparator(sqltypes.ARRAY.Comparator): - """Define comparison operations for :class:`.ARRAY`. + """Define comparison operations for :class:`_types.ARRAY`. Note that these operations are in addition to those provided by the base :class:`.types.ARRAY.Comparator` class, including diff --git a/lib/sqlalchemy/dialects/postgresql/base.py b/lib/sqlalchemy/dialects/postgresql/base.py index cb41a8f65f..670de4ebf6 100644 --- a/lib/sqlalchemy/dialects/postgresql/base.py +++ b/lib/sqlalchemy/dialects/postgresql/base.py @@ -86,7 +86,7 @@ All PostgreSQL dialects support setting of transaction isolation level both via a dialect-specific parameter :paramref:`.create_engine.isolation_level` accepted by :func:`.create_engine`, as well as the :paramref:`.Connection.execution_options.isolation_level` -argument as passed to :meth:`.Connection.execution_options`. +argument as passed to :meth:`_engine.Connection.execution_options`. When using a non-psycopg2 dialect, this feature works by issuing the command ``SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL `` for each new connection. For the special AUTOCOMMIT isolation level, @@ -129,11 +129,13 @@ Remote-Schema Table Introspection and PostgreSQL search_path name schemas **other** than ``public`` explicitly within ``Table`` definitions. The PostgreSQL dialect can reflect tables from any schema. The -:paramref:`.Table.schema` argument, or alternatively the +:paramref:`_schema.Table.schema` argument, or alternatively the :paramref:`.MetaData.reflect.schema` argument determines which schema will -be searched for the table or tables. The reflected :class:`.Table` objects +be searched for the table or tables. The reflected :class:`_schema.Table` +objects will in all cases retain this ``.schema`` attribute as was specified. -However, with regards to tables which these :class:`.Table` objects refer to +However, with regards to tables which these :class:`_schema.Table` +objects refer to via foreign key constraint, a decision must be made as to how the ``.schema`` is represented in those remote tables, in the case where that remote schema name is also a member of the current @@ -205,7 +207,8 @@ reflection process as follows:: ... -The above process would deliver to the :attr:`.MetaData.tables` collection +The above process would deliver to the :attr:`_schema.MetaData.tables` +collection ``referred`` table named **without** the schema:: >>> meta.tables['referred'].schema is None @@ -214,8 +217,8 @@ The above process would deliver to the :attr:`.MetaData.tables` collection To alter the behavior of reflection such that the referred schema is maintained regardless of the ``search_path`` setting, use the ``postgresql_ignore_search_path`` option, which can be specified as a -dialect-specific argument to both :class:`.Table` as well as -:meth:`.MetaData.reflect`:: +dialect-specific argument to both :class:`_schema.Table` as well as +:meth:`_schema.MetaData.reflect`:: >>> with engine.connect() as conn: ... conn.execute(text("SET search_path TO test_schema, public")) @@ -239,7 +242,7 @@ We will now have ``test_schema.referred`` stored as schema-qualified:: you just stick to the simplest use pattern: leave the ``search_path`` set to its default of ``public`` only, never refer to the name ``public`` as an explicit schema name otherwise, and refer to all other schema names - explicitly when building up a :class:`.Table` object. The options + explicitly when building up a :class:`_schema.Table` object. The options described here are only for those users who can't, or prefer not to, stay within these guidelines. @@ -251,8 +254,8 @@ which is in the ``public`` (i.e. default) schema will always have the ``.schema`` attribute set to ``None``. .. versionadded:: 0.9.2 Added the ``postgresql_ignore_search_path`` - dialect-level option accepted by :class:`.Table` and - :meth:`.MetaData.reflect`. + dialect-level option accepted by :class:`_schema.Table` and + :meth:`_schema.MetaData.reflect`. .. seealso:: @@ -304,7 +307,7 @@ or they may be *inferred* by stating the columns and conditions that comprise the indexes. SQLAlchemy provides ``ON CONFLICT`` support via the PostgreSQL-specific -:func:`.postgresql.insert()` function, which provides +:func:`_postgresql.insert()` function, which provides the generative methods :meth:`~.postgresql.Insert.on_conflict_do_update` and :meth:`~.postgresql.Insert.on_conflict_do_nothing`:: @@ -331,7 +334,7 @@ Both methods supply the "target" of the conflict using either the named constraint or by column inference: * The :paramref:`.Insert.on_conflict_do_update.index_elements` argument - specifies a sequence containing string column names, :class:`.Column` + specifies a sequence containing string column names, :class:`_schema.Column` objects, and/or SQL expression elements, which would identify a unique index:: @@ -381,8 +384,9 @@ named constraint or by column inference: constraint is unnamed, then inference will be used, where the expressions and optional WHERE clause of the constraint will be spelled out in the construct. This use is especially convenient - to refer to the named or unnamed primary key of a :class:`.Table` using the - :attr:`.Table.primary_key` attribute:: + to refer to the named or unnamed primary key of a :class:`_schema.Table` + using the + :attr:`_schema.Table.primary_key` attribute:: do_update_stmt = insert_stmt.on_conflict_do_update( constraint=my_table.primary_key, @@ -407,17 +411,19 @@ for UPDATE:: .. warning:: - The :meth:`.Insert.on_conflict_do_update` method does **not** take into + The :meth:`_expression.Insert.on_conflict_do_update` + method does **not** take into account Python-side default UPDATE values or generation functions, e.g. - those specified using :paramref:`.Column.onupdate`. + those specified using :paramref:`_schema.Column.onupdate`. These values will not be exercised for an ON CONFLICT style of UPDATE, unless they are manually specified in the :paramref:`.Insert.on_conflict_do_update.set_` dictionary. In order to refer to the proposed insertion row, the special alias :attr:`~.postgresql.Insert.excluded` is available as an attribute on -the :class:`.postgresql.Insert` object; this object is a -:class:`.ColumnCollection` which alias contains all columns of the target +the :class:`_postgresql.Insert` object; this object is a +:class:`_expression.ColumnCollection` +which alias contains all columns of the target table:: from sqlalchemy.dialects.postgresql import insert @@ -432,7 +438,7 @@ table:: ) conn.execute(do_update_stmt) -The :meth:`.Insert.on_conflict_do_update` method also accepts +The :meth:`_expression.Insert.on_conflict_do_update` method also accepts a WHERE clause using the :paramref:`.Insert.on_conflict_do_update.where` parameter, which will limit those rows which receive an UPDATE:: @@ -484,7 +490,8 @@ Full Text Search ---------------- SQLAlchemy makes available the PostgreSQL ``@@`` operator via the -:meth:`.ColumnElement.match` method on any textual column expression. +:meth:`_expression.ColumnElement.match` +method on any textual column expression. On a PostgreSQL dialect, an expression like the following:: select([sometable.c.text.match("search string")]) @@ -505,7 +512,7 @@ Emits the equivalent of:: SELECT to_tsvector('fat cats ate rats') @@ to_tsquery('cat & rat') -The :class:`.postgresql.TSVECTOR` type can provide for explicit CAST:: +The :class:`_postgresql.TSVECTOR` type can provide for explicit CAST:: from sqlalchemy.dialects.postgresql import TSVECTOR from sqlalchemy import select, cast @@ -613,8 +620,9 @@ The :class:`.Index` construct allows these to be specified via the }) Note that the keys in the ``postgresql_ops`` dictionary are the "key" name of -the :class:`.Column`, i.e. the name used to access it from the ``.c`` -collection of :class:`.Table`, which can be configured to be different than +the :class:`_schema.Column`, i.e. the name used to access it from the ``.c`` +collection of :class:`_schema.Table`, +which can be configured to be different than the actual name of the column as expressed in the database. If ``postgresql_ops`` is to be used against a complex SQL expression such @@ -666,7 +674,7 @@ The tablespace can be specified on :class:`.Index` using the .. versionadded:: 1.1 -Note that the same option is available on :class:`.Table` as well. +Note that the same option is available on :class:`_schema.Table` as well. .. _postgresql_index_concurrently: @@ -722,25 +730,30 @@ PostgreSQL Index Reflection The PostgreSQL database creates a UNIQUE INDEX implicitly whenever the UNIQUE CONSTRAINT construct is used. When inspecting a table using -:class:`.Inspector`, the :meth:`.Inspector.get_indexes` -and the :meth:`.Inspector.get_unique_constraints` will report on these +:class:`_reflection.Inspector`, the :meth:`_reflection.Inspector.get_indexes` +and the :meth:`_reflection.Inspector.get_unique_constraints` +will report on these two constructs distinctly; in the case of the index, the key ``duplicates_constraint`` will be present in the index entry if it is detected as mirroring a constraint. When performing reflection using ``Table(..., autoload=True)``, the UNIQUE INDEX is **not** returned -in :attr:`.Table.indexes` when it is detected as mirroring a -:class:`.UniqueConstraint` in the :attr:`.Table.constraints` collection. +in :attr:`_schema.Table.indexes` when it is detected as mirroring a +:class:`.UniqueConstraint` in the :attr:`_schema.Table.constraints` collection +. -.. versionchanged:: 1.0.0 - :class:`.Table` reflection now includes - :class:`.UniqueConstraint` objects present in the :attr:`.Table.constraints` +.. versionchanged:: 1.0.0 - :class:`_schema.Table` reflection now includes + :class:`.UniqueConstraint` objects present in the + :attr:`_schema.Table.constraints` collection; the PostgreSQL backend will no longer include a "mirrored" - :class:`.Index` construct in :attr:`.Table.indexes` if it is detected + :class:`.Index` construct in :attr:`_schema.Table.indexes` + if it is detected as corresponding to a unique constraint. Special Reflection Options -------------------------- -The :class:`.Inspector` used for the PostgreSQL backend is an instance +The :class:`_reflection.Inspector` +used for the PostgreSQL backend is an instance of :class:`.PGInspector`, which offers additional methods:: from sqlalchemy import create_engine, inspect @@ -759,7 +772,7 @@ PostgreSQL Table Options ------------------------ Several options for CREATE TABLE are supported directly by the PostgreSQL -dialect in conjunction with the :class:`.Table` construct: +dialect in conjunction with the :class:`_schema.Table` construct: * ``TABLESPACE``:: @@ -805,13 +818,13 @@ ARRAY Types The PostgreSQL dialect supports arrays, both as multidimensional column types as well as array literals: -* :class:`.postgresql.ARRAY` - ARRAY datatype +* :class:`_postgresql.ARRAY` - ARRAY datatype -* :class:`.postgresql.array` - array literal +* :class:`_postgresql.array` - array literal -* :func:`.postgresql.array_agg` - ARRAY_AGG SQL function +* :func:`_postgresql.array_agg` - ARRAY_AGG SQL function -* :class:`.postgresql.aggregate_order_by` - helper for PG's ORDER BY aggregate +* :class:`_postgresql.aggregate_order_by` - helper for PG's ORDER BY aggregate function syntax. JSON Types @@ -821,18 +834,18 @@ The PostgreSQL dialect supports both JSON and JSONB datatypes, including psycopg2's native support and support for all of PostgreSQL's special operators: -* :class:`.postgresql.JSON` +* :class:`_postgresql.JSON` -* :class:`.postgresql.JSONB` +* :class:`_postgresql.JSONB` HSTORE Type ----------- The PostgreSQL HSTORE type as well as hstore literals are supported: -* :class:`.postgresql.HSTORE` - HSTORE datatype +* :class:`_postgresql.HSTORE` - HSTORE datatype -* :class:`.postgresql.hstore` - hstore literal +* :class:`_postgresql.hstore` - hstore literal ENUM Types ---------- @@ -843,7 +856,7 @@ complexity on the SQLAlchemy side in terms of when this type should be CREATED and DROPPED. The type object is also an independently reflectable entity. The following sections should be consulted: -* :class:`.postgresql.ENUM` - DDL and typing support for ENUM. +* :class:`_postgresql.ENUM` - DDL and typing support for ENUM. * :meth:`.PGInspector.get_enums` - retrieve a listing of current ENUM types @@ -858,7 +871,7 @@ Using ENUM with ARRAY The combination of ENUM and ARRAY is not directly supported by backend DBAPIs at this time. In order to send and receive an ARRAY of ENUM, use the following workaround type, which decorates the -:class:`.postgresql.ARRAY` datatype. +:class:`_postgresql.ARRAY` datatype. .. sourcecode:: python @@ -1268,7 +1281,7 @@ PGUuid = UUID class TSVECTOR(sqltypes.TypeEngine): - """The :class:`.postgresql.TSVECTOR` type implements the PostgreSQL + """The :class:`_postgresql.TSVECTOR` type implements the PostgreSQL text search type TSVECTOR. It can be used to do full text queries on natural language @@ -1289,12 +1302,12 @@ class ENUM(sqltypes.NativeForEmulated, sqltypes.Enum): """PostgreSQL ENUM type. - This is a subclass of :class:`.types.Enum` which includes + This is a subclass of :class:`_types.Enum` which includes support for PG's ``CREATE TYPE`` and ``DROP TYPE``. - When the builtin type :class:`.types.Enum` is used and the + When the builtin type :class:`_types.Enum` is used and the :paramref:`.Enum.native_enum` flag is left at its default of - True, the PostgreSQL backend will use a :class:`.postgresql.ENUM` + True, the PostgreSQL backend will use a :class:`_postgresql.ENUM` type as the implementation, so the special create/drop rules will be used. @@ -1303,9 +1316,10 @@ class ENUM(sqltypes.NativeForEmulated, sqltypes.Enum): parent table, in that it may be "owned" by just a single table, or may be shared among many tables. - When using :class:`.types.Enum` or :class:`.postgresql.ENUM` + When using :class:`_types.Enum` or :class:`_postgresql.ENUM` in an "inline" fashion, the ``CREATE TYPE`` and ``DROP TYPE`` is emitted - corresponding to when the :meth:`.Table.create` and :meth:`.Table.drop` + corresponding to when the :meth:`_schema.Table.create` and + :meth:`_schema.Table.drop` methods are called:: table = Table('sometable', metadata, @@ -1316,9 +1330,9 @@ class ENUM(sqltypes.NativeForEmulated, sqltypes.Enum): table.drop(engine) # will emit DROP TABLE and DROP ENUM To use a common enumerated type between multiple tables, the best - practice is to declare the :class:`.types.Enum` or - :class:`.postgresql.ENUM` independently, and associate it with the - :class:`.MetaData` object itself:: + practice is to declare the :class:`_types.Enum` or + :class:`_postgresql.ENUM` independently, and associate it with the + :class:`_schema.MetaData` object itself:: my_enum = ENUM('a', 'b', 'c', name='myenum', metadata=metadata) @@ -1353,7 +1367,7 @@ class ENUM(sqltypes.NativeForEmulated, sqltypes.Enum): my_enum.create(engine) my_enum.drop(engine) - .. versionchanged:: 1.0.0 The PostgreSQL :class:`.postgresql.ENUM` type + .. versionchanged:: 1.0.0 The PostgreSQL :class:`_postgresql.ENUM` type now behaves more strictly with regards to CREATE/DROP. A metadata-level ENUM type will only be created and dropped at the metadata level, not the table level, with the exception of @@ -1366,10 +1380,10 @@ class ENUM(sqltypes.NativeForEmulated, sqltypes.Enum): native_enum = True def __init__(self, *enums, **kw): - """Construct an :class:`~.postgresql.ENUM`. + """Construct an :class:`_postgresql.ENUM`. Arguments are the same as that of - :class:`.types.Enum`, but also including + :class:`_types.Enum`, but also including the following parameters. :param create_type: Defaults to True. @@ -1397,7 +1411,7 @@ class ENUM(sqltypes.NativeForEmulated, sqltypes.Enum): @classmethod def adapt_emulated_to_native(cls, impl, **kw): - """Produce a PostgreSQL native :class:`.postgresql.ENUM` from plain + """Produce a PostgreSQL native :class:`_postgresql.ENUM` from plain :class:`.Enum`. """ @@ -1412,13 +1426,13 @@ class ENUM(sqltypes.NativeForEmulated, sqltypes.Enum): def create(self, bind=None, checkfirst=True): """Emit ``CREATE TYPE`` for this - :class:`~.postgresql.ENUM`. + :class:`_postgresql.ENUM`. If the underlying dialect does not support PostgreSQL CREATE TYPE, no action is taken. - :param bind: a connectable :class:`.Engine`, - :class:`.Connection`, or similar object to emit + :param bind: a connectable :class:`_engine.Engine`, + :class:`_engine.Connection`, or similar object to emit SQL. :param checkfirst: if ``True``, a query against the PG catalog will be first performed to see @@ -1436,13 +1450,13 @@ class ENUM(sqltypes.NativeForEmulated, sqltypes.Enum): def drop(self, bind=None, checkfirst=True): """Emit ``DROP TYPE`` for this - :class:`~.postgresql.ENUM`. + :class:`_postgresql.ENUM`. If the underlying dialect does not support PostgreSQL DROP TYPE, no action is taken. - :param bind: a connectable :class:`.Engine`, - :class:`.Connection`, or similar object to emit + :param bind: a connectable :class:`_engine.Engine`, + :class:`_engine.Connection`, or similar object to emit SQL. :param checkfirst: if ``True``, a query against the PG catalog will be first performed to see @@ -2276,7 +2290,8 @@ class PGInspector(reflection.Inspector): def get_foreign_table_names(self, schema=None): """Return a list of FOREIGN TABLE names. - Behavior is similar to that of :meth:`.Inspector.get_table_names`, + Behavior is similar to that of + :meth:`_reflection.Inspector.get_table_names`, except that the list is limited to those tables that report a ``relkind`` value of ``f``. diff --git a/lib/sqlalchemy/dialects/postgresql/dml.py b/lib/sqlalchemy/dialects/postgresql/dml.py index 626f810186..70d26a94bc 100644 --- a/lib/sqlalchemy/dialects/postgresql/dml.py +++ b/lib/sqlalchemy/dialects/postgresql/dml.py @@ -23,7 +23,7 @@ class Insert(StandardInsert): Adds methods for PG-specific syntaxes such as ON CONFLICT. - The :class:`.postgresql.Insert` object is created using the + The :class:`_postgresql.Insert` object is created using the :func:`sqlalchemy.dialects.postgresql.insert` function. .. versionadded:: 1.1 @@ -41,7 +41,7 @@ class Insert(StandardInsert): .. seealso:: :ref:`postgresql_insert_on_conflict` - example of how - to use :attr:`.Insert.excluded` + to use :attr:`_expression.Insert.excluded` """ return alias(self.table, name="excluded").columns @@ -66,7 +66,7 @@ class Insert(StandardInsert): or the constraint object itself if it has a .name attribute. :param index_elements: - A sequence consisting of string column names, :class:`.Column` + A sequence consisting of string column names, :class:`_schema.Column` objects, or other column expression objects that will be used to infer a target index. @@ -78,12 +78,13 @@ class Insert(StandardInsert): Required argument. A dictionary or other mapping object with column names as keys and expressions or literals as values, specifying the ``SET`` actions to take. - If the target :class:`.Column` specifies a ".key" attribute distinct + If the target :class:`_schema.Column` specifies a ". + key" attribute distinct from the column name, that key should be used. .. warning:: This dictionary does **not** take into account Python-specified default UPDATE values or generation functions, - e.g. those specified using :paramref:`.Column.onupdate`. + e.g. those specified using :paramref:`_schema.Column.onupdate`. These values will not be exercised for an ON CONFLICT style of UPDATE, unless they are manually specified in the :paramref:`.Insert.on_conflict_do_update.set_` dictionary. @@ -122,7 +123,7 @@ class Insert(StandardInsert): or the constraint object itself if it has a .name attribute. :param index_elements: - A sequence consisting of string column names, :class:`.Column` + A sequence consisting of string column names, :class:`_schema.Column` objects, or other column expression objects that will be used to infer a target index. diff --git a/lib/sqlalchemy/dialects/postgresql/ext.py b/lib/sqlalchemy/dialects/postgresql/ext.py index f11919b4be..e649207191 100644 --- a/lib/sqlalchemy/dialects/postgresql/ext.py +++ b/lib/sqlalchemy/dialects/postgresql/ext.py @@ -46,7 +46,7 @@ class aggregate_order_by(expression.ColumnElement): .. seealso:: - :class:`.array_agg` + :class:`_functions.array_agg` """ @@ -113,7 +113,8 @@ class ExcludeConstraint(ColumnCollectionConstraint): where=(Column('group') != 'some group') ) - The constraint is normally embedded into the :class:`.Table` construct + The constraint is normally embedded into the :class:`_schema.Table` + construct directly, or added later using :meth:`.append_constraint`:: some_table = Table( @@ -136,11 +137,14 @@ class ExcludeConstraint(ColumnCollectionConstraint): A sequence of two tuples of the form ``(column, operator)`` where "column" is a SQL expression element or a raw SQL string, most - typically a :class:`.Column` object, and "operator" is a string + typically a :class:`_schema.Column` object, + and "operator" is a string containing the operator to use. In order to specify a column name - when a :class:`.Column` object is not available, while ensuring + when a :class:`_schema.Column` object is not available, + while ensuring that any necessary quoting rules take effect, an ad-hoc - :class:`.Column` or :func:`.sql.expression.column` object should be + :class:`_schema.Column` or :func:`_expression.column` + object should be used. :param name: @@ -230,9 +234,9 @@ class ExcludeConstraint(ColumnCollectionConstraint): def array_agg(*arg, **kw): - """PostgreSQL-specific form of :class:`.array_agg`, ensures - return type is :class:`.postgresql.ARRAY` and not - the plain :class:`.types.ARRAY`, unless an explicit ``type_`` + """PostgreSQL-specific form of :class:`_functions.array_agg`, ensures + return type is :class:`_postgresql.ARRAY` and not + the plain :class:`_types.ARRAY`, unless an explicit ``type_`` is passed. .. versionadded:: 1.1 diff --git a/lib/sqlalchemy/dialects/postgresql/hstore.py b/lib/sqlalchemy/dialects/postgresql/hstore.py index 7f90ffa0ea..6798051836 100644 --- a/lib/sqlalchemy/dialects/postgresql/hstore.py +++ b/lib/sqlalchemy/dialects/postgresql/hstore.py @@ -141,7 +141,7 @@ class HSTORE(sqltypes.Indexable, sqltypes.Concatenable, sqltypes.TypeEngine): """Construct a new :class:`.HSTORE`. :param text_type: the type that should be used for indexed values. - Defaults to :class:`.types.Text`. + Defaults to :class:`_types.Text`. .. versionadded:: 1.1.0 diff --git a/lib/sqlalchemy/dialects/postgresql/json.py b/lib/sqlalchemy/dialects/postgresql/json.py index 9661634c28..8111599538 100644 --- a/lib/sqlalchemy/dialects/postgresql/json.py +++ b/lib/sqlalchemy/dialects/postgresql/json.py @@ -102,14 +102,14 @@ colspecs[sqltypes.JSON.JSONPathType] = JSONPathType class JSON(sqltypes.JSON): """Represent the PostgreSQL JSON type. - This type is a specialization of the Core-level :class:`.types.JSON` - type. Be sure to read the documentation for :class:`.types.JSON` for + This type is a specialization of the Core-level :class:`_types.JSON` + type. Be sure to read the documentation for :class:`_types.JSON` for important tips regarding treatment of NULL values and ORM use. - .. versionchanged:: 1.1 :class:`.postgresql.JSON` is now a PostgreSQL- - specific specialization of the new :class:`.types.JSON` type. + .. versionchanged:: 1.1 :class:`_postgresql.JSON` is now a PostgreSQL- + specific specialization of the new :class:`_types.JSON` type. - The operators provided by the PostgreSQL version of :class:`.JSON` + The operators provided by the PostgreSQL version of :class:`_types.JSON` include: * Index operations (the ``->`` operator):: @@ -142,13 +142,15 @@ class JSON(sqltypes.JSON): data_table.c.data[('key_1', 'key_2', 5, ..., 'key_n')].astext == 'some value' - .. versionchanged:: 1.1 The :meth:`.ColumnElement.cast` operator on + .. versionchanged:: 1.1 The :meth:`_expression.ColumnElement.cast` + operator on JSON objects now requires that the :attr:`.JSON.Comparator.astext` modifier be called explicitly, if the cast works only from a textual string. Index operations return an expression object whose type defaults to - :class:`.JSON` by default, so that further JSON-oriented instructions + :class:`_types.JSON` by default, + so that further JSON-oriented instructions may be called upon the result type. Custom serializers and deserializers are specified at the dialect level, @@ -166,16 +168,16 @@ class JSON(sqltypes.JSON): .. seealso:: - :class:`.types.JSON` - Core level JSON type + :class:`_types.JSON` - Core level JSON type - :class:`.JSONB` + :class:`_postgresql.JSONB` """ # noqa astext_type = sqltypes.Text() def __init__(self, none_as_null=False, astext_type=None): - """Construct a :class:`.JSON` type. + """Construct a :class:`_types.JSON` type. :param none_as_null: if True, persist the value ``None`` as a SQL NULL value, not the JSON encoding of ``null``. Note that @@ -190,11 +192,11 @@ class JSON(sqltypes.JSON): .. seealso:: - :attr:`.JSON.NULL` + :attr:`_types.JSON.NULL` :param astext_type: the type to use for the :attr:`.JSON.Comparator.astext` - accessor on indexed attributes. Defaults to :class:`.types.Text`. + accessor on indexed attributes. Defaults to :class:`_types.Text`. .. versionadded:: 1.1 @@ -204,7 +206,7 @@ class JSON(sqltypes.JSON): self.astext_type = astext_type class Comparator(sqltypes.JSON.Comparator): - """Define comparison operations for :class:`.JSON`.""" + """Define comparison operations for :class:`_types.JSON`.""" @property def astext(self): @@ -217,7 +219,7 @@ class JSON(sqltypes.JSON): .. seealso:: - :meth:`.ColumnElement.cast` + :meth:`_expression.ColumnElement.cast` """ if isinstance(self.expr.right.type, sqltypes.JSON.JSONPathType): @@ -241,7 +243,8 @@ ischema_names["json"] = JSON class JSONB(JSON): """Represent the PostgreSQL JSONB type. - The :class:`.JSONB` type stores arbitrary JSONB format data, e.g.:: + The :class:`_postgresql.JSONB` type stores arbitrary JSONB format data, e. + g.:: data_table = Table('data_table', metadata, Column('id', Integer, primary_key=True), @@ -254,19 +257,22 @@ class JSONB(JSON): data = {"key1": "value1", "key2": "value2"} ) - The :class:`.JSONB` type includes all operations provided by - :class:`.JSON`, including the same behaviors for indexing operations. + The :class:`_postgresql.JSONB` type includes all operations provided by + :class:`_types.JSON`, including the same behaviors for indexing operations + . It also adds additional operators specific to JSONB, including :meth:`.JSONB.Comparator.has_key`, :meth:`.JSONB.Comparator.has_all`, :meth:`.JSONB.Comparator.has_any`, :meth:`.JSONB.Comparator.contains`, and :meth:`.JSONB.Comparator.contained_by`. - Like the :class:`.JSON` type, the :class:`.JSONB` type does not detect + Like the :class:`_types.JSON` type, the :class:`_postgresql.JSONB` + type does not detect in-place changes when used with the ORM, unless the :mod:`sqlalchemy.ext.mutable` extension is used. Custom serializers and deserializers - are shared with the :class:`.JSON` class, using the ``json_serializer`` + are shared with the :class:`_types.JSON` class, + using the ``json_serializer`` and ``json_deserializer`` keyword arguments. These must be specified at the dialect level using :func:`.create_engine`. When using psycopg2, the serializers are associated with the jsonb type using @@ -278,14 +284,14 @@ class JSONB(JSON): .. seealso:: - :class:`.JSON` + :class:`_types.JSON` """ __visit_name__ = "JSONB" class Comparator(JSON.Comparator): - """Define comparison operations for :class:`.JSON`.""" + """Define comparison operations for :class:`_types.JSON`.""" def has_key(self, other): """Boolean expression. Test for presence of a key. Note that the diff --git a/lib/sqlalchemy/dialects/postgresql/psycopg2.py b/lib/sqlalchemy/dialects/postgresql/psycopg2.py index 89a63fd47d..6d2672bbe5 100644 --- a/lib/sqlalchemy/dialects/postgresql/psycopg2.py +++ b/lib/sqlalchemy/dialects/postgresql/psycopg2.py @@ -119,18 +119,21 @@ Per-Statement/Connection Execution Options ------------------------------------------- The following DBAPI-specific options are respected when used with -:meth:`.Connection.execution_options`, :meth:`.Executable.execution_options`, -:meth:`.Query.execution_options`, in addition to those not specific to DBAPIs: +:meth:`_engine.Connection.execution_options`, +:meth:`.Executable.execution_options`, +:meth:`_query.Query.execution_options`, +in addition to those not specific to DBAPIs: * ``isolation_level`` - Set the transaction isolation level for the lifespan - of a :class:`.Connection` (can only be set on a connection, not a statement + of a :class:`_engine.Connection` (can only be set on a connection, + not a statement or query). See :ref:`psycopg2_isolation_level`. * ``stream_results`` - Enable or disable usage of psycopg2 server side cursors - this feature makes use of "named" cursors in combination with special result handling methods so that result rows are not fully buffered. If ``None`` or not set, the ``server_side_cursors`` option of the - :class:`.Engine` is used. + :class:`_engine.Engine` is used. * ``max_row_buffer`` - when using ``stream_results``, an integer value that specifies the maximum number of rows to buffer at a time. This is @@ -153,7 +156,8 @@ Modern versions of psycopg2 include a feature known as have been shown in benchmarking to improve psycopg2's executemany() performance, primarily with INSERT statements, by multiple orders of magnitude. SQLAlchemy allows this extension to be used for all ``executemany()`` style -calls invoked by an :class:`.Engine` when used with :ref:`multiple parameter +calls invoked by an :class:`_engine.Engine` +when used with :ref:`multiple parameter sets `, which includes the use of this feature both by the Core as well as by the ORM for inserts of objects with non-autogenerated primary key values, by adding the ``executemany_mode`` flag to @@ -180,13 +184,15 @@ Possible options for ``executemany_mode`` include: semicolon. This is the same behavior as was provided by the ``use_batch_mode=True`` flag. -* ``'values'``- For Core :func:`~.sql.expression.insert` constructs only (including those +* ``'values'``- For Core :func:`_expression.insert` + constructs only (including those emitted by the ORM automatically), the ``psycopg2.extras.execute_values`` extension is used so that multiple parameter sets are grouped into a single INSERT statement and joined together with multiple VALUES expressions. This method requires that the string text of the VALUES clause inside the INSERT statement is manipulated, so is only supported with a compiled - :func:`~.sql.expression.insert` construct where the format is predictable. For all other + :func:`_expression.insert` construct where the format is predictable. + For all other constructs, including plain textual INSERT statements not rendered by the SQLAlchemy expression language compiler, the ``psycopg2.extras.execute_batch`` method is used. It is therefore important @@ -213,7 +219,8 @@ more appropriate:: .. seealso:: :ref:`execute_multiple` - General information on using the - :class:`.Connection` object to execute statements in such a way as to make + :class:`_engine.Connection` + object to execute statements in such a way as to make use of the DBAPI ``.executemany()`` method. .. versionchanged:: 1.3.7 - Added support for @@ -299,7 +306,8 @@ actually contain percent or parenthesis symbols; as SQLAlchemy in many cases generates bound parameter names based on the name of a column, the presence of these characters in a column name can lead to problems. -There are two solutions to the issue of a :class:`.schema.Column` that contains +There are two solutions to the issue of a :class:`_schema.Column` +that contains one of these characters in its name. One is to specify the :paramref:`.schema.Column.key` for columns that have such names:: @@ -312,10 +320,12 @@ Above, an INSERT statement such as ``measurement.insert()`` will use ``measurement.c.size_meters > 10`` will derive the bound parameter name from the ``size_meters`` key as well. -.. versionchanged:: 1.0.0 - SQL expressions will use :attr:`.Column.key` +.. versionchanged:: 1.0.0 - SQL expressions will use + :attr:`_schema.Column.key` as the source of naming when anonymous bound parameters are created in SQL expressions; previously, this behavior only applied to - :meth:`.Table.insert` and :meth:`.Table.update` parameter names. + :meth:`_schema.Table.insert` and :meth:`_schema.Table.update` + parameter names. The other solution is to use a positional format; psycopg2 allows use of the "format" paramstyle, which can be passed to @@ -352,7 +362,8 @@ As discussed in :ref:`postgresql_isolation_level`, all PostgreSQL dialects support setting of transaction isolation level both via the ``isolation_level`` parameter passed to :func:`.create_engine`, as well as the ``isolation_level`` argument used by -:meth:`.Connection.execution_options`. When using the psycopg2 dialect, these +:meth:`_engine.Connection.execution_options`. When using the psycopg2 dialect +, these options make use of psycopg2's ``set_isolation_level()`` connection method, rather than emitting a PostgreSQL directive; this is because psycopg2's API-level setting is always emitted at the start of each transaction in any diff --git a/lib/sqlalchemy/dialects/sqlite/base.py b/lib/sqlalchemy/dialects/sqlite/base.py index d3105f268b..1e265a9ebd 100644 --- a/lib/sqlalchemy/dialects/sqlite/base.py +++ b/lib/sqlalchemy/dialects/sqlite/base.py @@ -19,7 +19,7 @@ not provide out of the box functionality for translating values between Python `datetime` objects and a SQLite-supported format. SQLAlchemy's own :class:`~sqlalchemy.types.DateTime` and related types provide date formatting and parsing functionality when SQLite is used. The implementation classes are -:class:`~.sqlite.DATETIME`, :class:`~.sqlite.DATE` and :class:`~.sqlite.TIME`. +:class:`_sqlite.DATETIME`, :class:`_sqlite.DATE` and :class:`_sqlite.TIME`. These types represent dates and times as ISO formatted strings, which also nicely support ordering. There's no reliance on typical "libc" internals for these functions so historical dates are fully supported. @@ -216,7 +216,7 @@ SAVEPOINT Support SQLite supports SAVEPOINTs, which only function once a transaction is begun. SQLAlchemy's SAVEPOINT support is available using the -:meth:`.Connection.begin_nested` method at the Core level, and +:meth:`_engine.Connection.begin_nested` method at the Core level, and :meth:`.Session.begin_nested` at the ORM level. However, SAVEPOINTs won't work at all with pysqlite unless workarounds are taken. @@ -303,11 +303,12 @@ itself depending on the location of the target constraint. To render this clause within DDL, the extension parameter ``sqlite_on_conflict`` can be specified with a string conflict resolution algorithm within the :class:`.PrimaryKeyConstraint`, :class:`.UniqueConstraint`, -:class:`.CheckConstraint` objects. Within the :class:`.Column` object, there +:class:`.CheckConstraint` objects. Within the :class:`_schema.Column` object, +there are individual parameters ``sqlite_on_conflict_not_null``, ``sqlite_on_conflict_primary_key``, ``sqlite_on_conflict_unique`` which each correspond to the three types of relevant constraint types that can be -indicated from a :class:`.Column` object. +indicated from a :class:`_schema.Column` object. .. seealso:: @@ -339,9 +340,10 @@ The above renders CREATE TABLE DDL as:: ) -When using the :paramref:`.Column.unique` flag to add a UNIQUE constraint +When using the :paramref:`_schema.Column.unique` +flag to add a UNIQUE constraint to a single column, the ``sqlite_on_conflict_unique`` parameter can -be added to the :class:`.Column` as well, which will be added to the +be added to the :class:`_schema.Column` as well, which will be added to the UNIQUE constraint in the DDL:: some_table = Table( @@ -417,30 +419,30 @@ http://www.sqlite.org/datatype3.html section 2.1. The provided typemap will make direct associations from an exact string name match for the following types: -:class:`~.types.BIGINT`, :class:`~.types.BLOB`, -:class:`~.types.BOOLEAN`, :class:`~.types.BOOLEAN`, -:class:`~.types.CHAR`, :class:`~.types.DATE`, -:class:`~.types.DATETIME`, :class:`~.types.FLOAT`, -:class:`~.types.DECIMAL`, :class:`~.types.FLOAT`, -:class:`~.types.INTEGER`, :class:`~.types.INTEGER`, -:class:`~.types.NUMERIC`, :class:`~.types.REAL`, -:class:`~.types.SMALLINT`, :class:`~.types.TEXT`, -:class:`~.types.TIME`, :class:`~.types.TIMESTAMP`, -:class:`~.types.VARCHAR`, :class:`~.types.NVARCHAR`, -:class:`~.types.NCHAR` +:class:`_types.BIGINT`, :class:`_types.BLOB`, +:class:`_types.BOOLEAN`, :class:`_types.BOOLEAN`, +:class:`_types.CHAR`, :class:`_types.DATE`, +:class:`_types.DATETIME`, :class:`_types.FLOAT`, +:class:`_types.DECIMAL`, :class:`_types.FLOAT`, +:class:`_types.INTEGER`, :class:`_types.INTEGER`, +:class:`_types.NUMERIC`, :class:`_types.REAL`, +:class:`_types.SMALLINT`, :class:`_types.TEXT`, +:class:`_types.TIME`, :class:`_types.TIMESTAMP`, +:class:`_types.VARCHAR`, :class:`_types.NVARCHAR`, +:class:`_types.NCHAR` When a type name does not match one of the above types, the "type affinity" lookup is used instead: -* :class:`~.types.INTEGER` is returned if the type name includes the +* :class:`_types.INTEGER` is returned if the type name includes the string ``INT`` -* :class:`~.types.TEXT` is returned if the type name includes the +* :class:`_types.TEXT` is returned if the type name includes the string ``CHAR``, ``CLOB`` or ``TEXT`` -* :class:`~.types.NullType` is returned if the type name includes the +* :class:`_types.NullType` is returned if the type name includes the string ``BLOB`` -* :class:`~.types.REAL` is returned if the type name includes the string +* :class:`_types.REAL` is returned if the type name includes the string ``REAL``, ``FLOA`` or ``DOUB``. -* Otherwise, the :class:`~.types.NUMERIC` type is used. +* Otherwise, the :class:`_types.NUMERIC` type is used. .. versionadded:: 0.9.3 Support for SQLite type affinity rules when reflecting columns. @@ -560,7 +562,7 @@ the very specific case where an application is forced to use column names that contain dots, and the functionality of :meth:`.ResultProxy.keys` and :meth:`.Row.keys()` is required to return these dotted names unmodified, the ``sqlite_raw_colnames`` execution option may be provided, either on a -per-:class:`.Connection` basis:: +per-:class:`_engine.Connection` basis:: result = conn.execution_options(sqlite_raw_colnames=True).exec_driver_sql(''' select x.a, x.b from x where a=1 @@ -569,11 +571,11 @@ per-:class:`.Connection` basis:: ''') assert result.keys() == ["x.a", "x.b"] -or on a per-:class:`.Engine` basis:: +or on a per-:class:`_engine.Engine` basis:: engine = create_engine("sqlite://", execution_options={"sqlite_raw_colnames": True}) -When using the per-:class:`.Engine` execution option, note that +When using the per-:class:`_engine.Engine` execution option, note that **Core and ORM queries that use UNION may not function properly**. """ # noqa diff --git a/lib/sqlalchemy/dialects/sqlite/json.py b/lib/sqlalchemy/dialects/sqlite/json.py index db185dd4d2..775f557f84 100644 --- a/lib/sqlalchemy/dialects/sqlite/json.py +++ b/lib/sqlalchemy/dialects/sqlite/json.py @@ -9,8 +9,8 @@ class JSON(sqltypes.JSON): `loadable extension `_ and as such may not be available, or may require run-time loading. - The :class:`.sqlite.JSON` type supports persistence of JSON values - as well as the core index operations provided by :class:`.types.JSON` + The :class:`_sqlite.JSON` type supports persistence of JSON values + as well as the core index operations provided by :class:`_types.JSON` datatype, by adapting the operations to render the ``JSON_EXTRACT`` function wrapped in the ``JSON_QUOTE`` function at the database level. Extracted values are quoted in order to ensure that the results are diff --git a/lib/sqlalchemy/dialects/sqlite/pysqlite.py b/lib/sqlalchemy/dialects/sqlite/pysqlite.py index 72bbd01773..307114c033 100644 --- a/lib/sqlalchemy/dialects/sqlite/pysqlite.py +++ b/lib/sqlalchemy/dialects/sqlite/pysqlite.py @@ -326,7 +326,8 @@ ourselves. This is achieved using two event listeners:: .. warning:: When using the above recipe, it is advised to not use the :paramref:`.Connection.execution_options.isolation_level` setting on - :class:`.Connection` and :func:`.create_engine` with the SQLite driver, + :class:`_engine.Connection` and :func:`.create_engine` + with the SQLite driver, as this function necessarily will also alter the ".isolation_level" setting. diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index 1a5562a9b2..014d433a74 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -20,7 +20,7 @@ from ..sql import compiler from ..sql import util as sql_util -"""Defines :class:`.Connection` and :class:`.Engine`. +"""Defines :class:`_engine.Connection` and :class:`_engine.Engine`. """ @@ -29,7 +29,8 @@ class Connection(Connectable): """Provides high-level functionality for a wrapped DB-API connection. Provides execution support for string-based SQL statements as well as - :class:`.ClauseElement`, :class:`.Compiled` and :class:`.DefaultGenerator` + :class:`_expression.ClauseElement`, :class:`.Compiled` and + :class:`.DefaultGenerator` objects. Provides a :meth:`begin` method to return :class:`.Transaction` objects. @@ -185,10 +186,12 @@ class Connection(Connectable): r""" Set non-SQL options for the connection which take effect during execution. - The method returns a copy of this :class:`.Connection` which references + The method returns a copy of this :class:`_engine.Connection` + which references the same underlying DBAPI connection, but also defines the given execution options which will take effect for a call to - :meth:`execute`. As the new :class:`.Connection` references the same + :meth:`execute`. As the new :class:`_engine.Connection` + references the same underlying resource, it's usually a good idea to ensure that the copies will be discarded immediately, which is implicit if used as in:: @@ -196,14 +199,16 @@ class Connection(Connectable): execute(stmt) Note that any key/value can be passed to - :meth:`.Connection.execution_options`, and it will be stored in the - ``_execution_options`` dictionary of the :class:`.Connection`. It + :meth:`_engine.Connection.execution_options`, + and it will be stored in the + ``_execution_options`` dictionary of the :class:`_engine.Connection`. + It is suitable for usage by end-user schemes to communicate with event listeners, for example. The keywords that are currently recognized by SQLAlchemy itself include all those listed under :meth:`.Executable.execution_options`, - as well as others that are specific to :class:`.Connection`. + as well as others that are specific to :class:`_engine.Connection`. :param autocommit: Available on: Connection, statement. When True, a COMMIT will be invoked after execution @@ -221,7 +226,8 @@ class Connection(Connectable): :param compiled_cache: Available on: Connection. A dictionary where :class:`.Compiled` objects - will be cached when the :class:`.Connection` compiles a clause + will be cached when the :class:`_engine.Connection` + compiles a clause expression into a :class:`.Compiled` object. It is the user's responsibility to manage the size of this dictionary, which will have keys @@ -236,10 +242,11 @@ class Connection(Connectable): used by the ORM internally supersedes a cache dictionary specified here. - :param isolation_level: Available on: :class:`.Connection`. + :param isolation_level: Available on: :class:`_engine.Connection`. Set the transaction isolation level for the lifespan of this - :class:`.Connection` object. Valid values include those string + :class:`_engine.Connection` object. + Valid values include those string values accepted by the :paramref:`.create_engine.isolation_level` parameter passed to :func:`.create_engine`. These levels are semi-database specific; see individual dialect documentation for @@ -248,25 +255,27 @@ class Connection(Connectable): The isolation level option applies the isolation level by emitting statements on the DBAPI connection, and **necessarily affects the original Connection object overall**, not just the copy that is - returned by the call to :meth:`.Connection.execution_options` + returned by the call to :meth:`_engine.Connection.execution_options` method. The isolation level will remain at the given setting until the DBAPI connection itself is returned to the connection pool, i.e. - the :meth:`.Connection.close` method on the original - :class:`.Connection` is called, where an event handler will emit + the :meth:`_engine.Connection.close` method on the original + :class:`_engine.Connection` is called, + where an event handler will emit additional statements on the DBAPI connection in order to revert the isolation level change. .. warning:: The ``isolation_level`` execution option should **not** be used when a transaction is already established, that - is, the :meth:`.Connection.begin` method or similar has been + is, the :meth:`_engine.Connection.begin` + method or similar has been called. A database cannot change the isolation level on a transaction in progress, and different DBAPIs and/or SQLAlchemy dialects may implicitly roll back or commit the transaction, or not affect the connection at all. .. note:: The ``isolation_level`` execution option is implicitly - reset if the :class:`.Connection` is invalidated, e.g. via - the :meth:`.Connection.invalidate` method, or if a + reset if the :class:`_engine.Connection` is invalidated, e.g. via + the :meth:`_engine.Connection.invalidate` method, or if a disconnection error occurs. The new connection produced after the invalidation will not have the isolation level re-applied to it automatically. @@ -274,9 +283,10 @@ class Connection(Connectable): .. seealso:: :paramref:`.create_engine.isolation_level` - - set per :class:`.Engine` isolation level + - set per :class:`_engine.Engine` isolation level - :meth:`.Connection.get_isolation_level` - view current level + :meth:`_engine.Connection.get_isolation_level` + - view current level :ref:`SQLite Transaction Isolation ` @@ -308,8 +318,9 @@ class Connection(Connectable): :param schema_translate_map: Available on: Connection, Engine. A dictionary mapping schema names to schema names, that will be - applied to the :paramref:`.Table.schema` element of each - :class:`.Table` encountered when SQL or DDL expression elements + applied to the :paramref:`_schema.Table.schema` element of each + :class:`_schema.Table` + encountered when SQL or DDL expression elements are compiled into strings; the resulting schema name will be converted based on presence in the map of the original name. @@ -321,11 +332,11 @@ class Connection(Connectable): .. seealso:: - :meth:`.Engine.execution_options` + :meth:`_engine.Engine.execution_options` :meth:`.Executable.execution_options` - :meth:`.Connection.get_execution_options` + :meth:`_engine.Connection.get_execution_options` """ # noqa @@ -343,7 +354,7 @@ class Connection(Connectable): .. seealso:: - :meth:`.Connection.execution_options` + :meth:`_engine.Connection.execution_options` """ return self._execution_options @@ -386,19 +397,19 @@ class Connection(Connectable): def get_isolation_level(self): """Return the current isolation level assigned to this - :class:`.Connection`. + :class:`_engine.Connection`. This will typically be the default isolation level as determined by the dialect, unless if the :paramref:`.Connection.execution_options.isolation_level` feature has been used to alter the isolation level on a - per-:class:`.Connection` basis. + per-:class:`_engine.Connection` basis. This attribute will typically perform a live SQL operation in order to procure the current isolation level, so the value returned is the actual level on the underlying DBAPI connection regardless of how this state was set. Compare to the - :attr:`.Connection.default_isolation_level` accessor + :attr:`_engine.Connection.default_isolation_level` accessor which returns the dialect-level setting without performing a SQL query. @@ -406,13 +417,14 @@ class Connection(Connectable): .. seealso:: - :attr:`.Connection.default_isolation_level` - view default level + :attr:`_engine.Connection.default_isolation_level` + - view default level :paramref:`.create_engine.isolation_level` - - set per :class:`.Engine` isolation level + - set per :class:`_engine.Engine` isolation level :paramref:`.Connection.execution_options.isolation_level` - - set per :class:`.Connection` isolation level + - set per :class:`_engine.Connection` isolation level """ try: @@ -422,15 +434,18 @@ class Connection(Connectable): @property def default_isolation_level(self): - """The default isolation level assigned to this :class:`.Connection`. + """The default isolation level assigned to this + :class:`_engine.Connection`. - This is the isolation level setting that the :class:`.Connection` - has when first procured via the :meth:`.Engine.connect` method. + This is the isolation level setting that the + :class:`_engine.Connection` + has when first procured via the :meth:`_engine.Engine.connect` method. This level stays in place until the :paramref:`.Connection.execution_options.isolation_level` is used - to change the setting on a per-:class:`.Connection` basis. + to change the setting on a per-:class:`_engine.Connection` basis. - Unlike :meth:`.Connection.get_isolation_level`, this attribute is set + Unlike :meth:`_engine.Connection.get_isolation_level`, + this attribute is set ahead of time from the first connection procured by the dialect, so SQL query is not invoked when this accessor is called. @@ -438,13 +453,14 @@ class Connection(Connectable): .. seealso:: - :meth:`.Connection.get_isolation_level` - view current level + :meth:`_engine.Connection.get_isolation_level` + - view current level :paramref:`.create_engine.isolation_level` - - set per :class:`.Engine` isolation level + - set per :class:`_engine.Engine` isolation level :paramref:`.Connection.execution_options.isolation_level` - - set per :class:`.Connection` isolation level + - set per :class:`_engine.Connection` isolation level """ return self.dialect.default_isolation_level @@ -482,12 +498,12 @@ class Connection(Connectable): @property def info(self): """Info dictionary associated with the underlying DBAPI connection - referred to by this :class:`.Connection`, allowing user-defined + referred to by this :class:`_engine.Connection`, allowing user-defined data to be associated with the connection. The data here will follow along with the DBAPI connection including after it is returned to the connection pool and used again - in subsequent instances of :class:`.Connection`. + in subsequent instances of :class:`_engine.Connection`. """ @@ -495,14 +511,14 @@ class Connection(Connectable): @util.deprecated_20(":meth:`.Connection.connect`") def connect(self, close_with_result=False): - """Returns a branched version of this :class:`.Connection`. + """Returns a branched version of this :class:`_engine.Connection`. - The :meth:`.Connection.close` method on the returned - :class:`.Connection` can be called and this - :class:`.Connection` will remain open. + The :meth:`_engine.Connection.close` method on the returned + :class:`_engine.Connection` can be called and this + :class:`_engine.Connection` will remain open. This method provides usage symmetry with - :meth:`.Engine.connect`, including for usage + :meth:`_engine.Engine.connect`, including for usage with context managers. """ @@ -511,36 +527,38 @@ class Connection(Connectable): def invalidate(self, exception=None): """Invalidate the underlying DBAPI connection associated with - this :class:`.Connection`. + this :class:`_engine.Connection`. The underlying DBAPI connection is literally closed (if possible), and is discarded. Its source connection pool will typically lazily create a new connection to replace it. Upon the next use (where "use" typically means using the - :meth:`.Connection.execute` method or similar), - this :class:`.Connection` will attempt to + :meth:`_engine.Connection.execute` method or similar), + this :class:`_engine.Connection` will attempt to procure a new DBAPI connection using the services of the - :class:`.Pool` as a source of connectivity (e.g. a "reconnection"). + :class:`_pool.Pool` as a source of connectivity (e.g. + a "reconnection"). If a transaction was in progress (e.g. the - :meth:`.Connection.begin` method has been called) when - :meth:`.Connection.invalidate` method is called, at the DBAPI + :meth:`_engine.Connection.begin` method has been called) when + :meth:`_engine.Connection.invalidate` method is called, at the DBAPI level all state associated with this transaction is lost, as - the DBAPI connection is closed. The :class:`.Connection` + the DBAPI connection is closed. The :class:`_engine.Connection` will not allow a reconnection to proceed until the :class:`.Transaction` object is ended, by calling the :meth:`.Transaction.rollback` method; until that point, any attempt at - continuing to use the :class:`.Connection` will raise an + continuing to use the :class:`_engine.Connection` will raise an :class:`~sqlalchemy.exc.InvalidRequestError`. This is to prevent applications from accidentally continuing an ongoing transactional operations despite the fact that the transaction has been lost due to an invalidation. - The :meth:`.Connection.invalidate` method, just like auto-invalidation, + The :meth:`_engine.Connection.invalidate` method, + just like auto-invalidation, will at the connection pool level invoke the - :meth:`.PoolEvents.invalidate` event. + :meth:`_events.PoolEvents.invalidate` event. .. seealso:: @@ -573,7 +591,8 @@ class Connection(Connectable): # connection is fully closed (since we used "with:", can # also call .close()) - This :class:`.Connection` instance will remain usable. When closed + This :class:`_engine.Connection` instance will remain usable. + When closed (or exited from a context manager context as above), the DB-API connection will be literally closed and not returned to its originating pool. @@ -594,7 +613,7 @@ class Connection(Connectable): which completes when either the :meth:`.Transaction.rollback` or :meth:`.Transaction.commit` method is called. - Nested calls to :meth:`.begin` on the same :class:`.Connection` + Nested calls to :meth:`.begin` on the same :class:`_engine.Connection` will return new :class:`.Transaction` objects that represent an emulated transaction within the scope of the enclosing transaction, that is:: @@ -612,13 +631,13 @@ class Connection(Connectable): .. seealso:: - :meth:`.Connection.begin_nested` - use a SAVEPOINT + :meth:`_engine.Connection.begin_nested` - use a SAVEPOINT - :meth:`.Connection.begin_twophase` - + :meth:`_engine.Connection.begin_twophase` - use a two phase /XID transaction - :meth:`.Engine.begin` - context manager available from - :class:`.Engine` + :meth:`_engine.Engine.begin` - context manager available from + :class:`_engine.Engine` """ if self.__branch_from: @@ -643,9 +662,9 @@ class Connection(Connectable): .. seealso:: - :meth:`.Connection.begin` + :meth:`_engine.Connection.begin` - :meth:`.Connection.begin_twophase` + :meth:`_engine.Connection.begin_twophase` """ if self.__branch_from: @@ -671,9 +690,9 @@ class Connection(Connectable): .. seealso:: - :meth:`.Connection.begin` + :meth:`_engine.Connection.begin` - :meth:`.Connection.begin_twophase` + :meth:`_engine.Connection.begin_twophase` """ @@ -870,21 +889,21 @@ class Connection(Connectable): self._root._rollback_impl() def close(self): - """Close this :class:`.Connection`. + """Close this :class:`_engine.Connection`. This results in a release of the underlying database resources, that is, the DBAPI connection referenced internally. The DBAPI connection is typically restored - back to the connection-holding :class:`.Pool` referenced - by the :class:`.Engine` that produced this - :class:`.Connection`. Any transactional state present on + back to the connection-holding :class:`_pool.Pool` referenced + by the :class:`_engine.Engine` that produced this + :class:`_engine.Connection`. Any transactional state present on the DBAPI connection is also unconditionally released via the DBAPI connection's ``rollback()`` method, regardless of any :class:`.Transaction` object that may be - outstanding with regards to this :class:`.Connection`. + outstanding with regards to this :class:`_engine.Connection`. - After :meth:`~.Connection.close` is called, the - :class:`.Connection` is permanently in a closed state, + After :meth:`_engine.Connection.close` is called, the + :class:`_engine.Connection` is permanently in a closed state, and will allow no further operations. """ @@ -937,9 +956,9 @@ class Connection(Connectable): one of: * a plain string (deprecated) - * any :class:`.ClauseElement` construct that is also + * any :class:`_expression.ClauseElement` construct that is also a subclass of :class:`.Executable`, such as a - :func:`~.expression.select` construct + :func:`_expression.select` construct * a :class:`.FunctionElement`, such as that generated by :data:`.func`, will be automatically wrapped in a SELECT statement, which is then executed. @@ -947,11 +966,13 @@ class Connection(Connectable): * a :class:`.DefaultGenerator` object * a :class:`.Compiled` object - .. deprecated:: 2.0 passing a string to :meth:`.Connection.execute` is + .. deprecated:: 2.0 passing a string to + :meth:`_engine.Connection.execute` is deprecated and will be removed in version 2.0. Use the - :func:`~.expression.text` construct with - :meth:`.Connection.execute`, or the - :meth:`.Connection.exec_driver_sql` method to invoke a driver-level + :func:`_expression.text` construct with + :meth:`_engine.Connection.execute`, or the + :meth:`_engine.Connection.exec_driver_sql` + method to invoke a driver-level SQL string. :param \*multiparams/\**params: represent bound parameter @@ -992,7 +1013,7 @@ class Connection(Connectable): for details on paramstyle. To execute a textual SQL statement which uses bound parameters in a - DBAPI-agnostic way, use the :func:`~.expression.text` construct. + DBAPI-agnostic way, use the :func:`_expression.text` construct. .. deprecated:: 2.0 use of tuple or scalar positional parameters is deprecated. All params should be dicts or sequences of dicts. @@ -1653,14 +1674,15 @@ class Connection(Connectable): @util.deprecated( "1.4", - "The :meth:`.Connection.transaction` method is deprecated and will be " - "removed in a future release. Use the :meth:`.Engine.begin` " + "The :meth:`_engine.Connection.transaction` " + "method is deprecated and will be " + "removed in a future release. Use the :meth:`_engine.Engine.begin` " "context manager instead.", ) def transaction(self, callable_, *args, **kwargs): r"""Execute the given function within a transaction boundary. - The function is passed this :class:`.Connection` + The function is passed this :class:`_engine.Connection` as the first argument, followed by the given \*args and \**kwargs, e.g.:: @@ -1679,23 +1701,23 @@ class Connection(Connectable): The :meth:`.transaction` method is superseded by the usage of the Python ``with:`` statement, which can - be used with :meth:`.Connection.begin`:: + be used with :meth:`_engine.Connection.begin`:: with conn.begin(): conn.execute(text("some statement"), {'x':5, 'y':10}) - As well as with :meth:`.Engine.begin`:: + As well as with :meth:`_engine.Engine.begin`:: with engine.begin() as conn: conn.execute(text("some statement"), {'x':5, 'y':10}) .. seealso:: - :meth:`.Engine.begin` - engine-level transactional + :meth:`_engine.Engine.begin` - engine-level transactional context - :meth:`.Engine.transaction` - engine-level version of - :meth:`.Connection.transaction` + :meth:`_engine.Engine.transaction` - engine-level version of + :meth:`_engine.Connection.transaction` """ @@ -1711,19 +1733,20 @@ class Connection(Connectable): @util.deprecated( "1.4", - "The :meth:`.Connection.run_callable` method is deprecated and will " + "The :meth:`_engine.Connection.run_callable` " + "method is deprecated and will " "be removed in a future release. Use a context manager instead.", ) def run_callable(self, callable_, *args, **kwargs): r"""Given a callable object or function, execute it, passing - a :class:`.Connection` as the first argument. + a :class:`_engine.Connection` as the first argument. The given \*args and \**kwargs are passed subsequent - to the :class:`.Connection` argument. + to the :class:`_engine.Connection` argument. - This function, along with :meth:`.Engine.run_callable`, - allows a function to be run with a :class:`.Connection` - or :class:`.Engine` object without the need to know + This function, along with :meth:`_engine.Engine.run_callable`, + allows a function to be run with a :class:`_engine.Connection` + or :class:`_engine.Engine` object without the need to know which one is being dealt with. """ @@ -1761,8 +1784,8 @@ class Transaction(object): """Represent a database transaction in progress. The :class:`.Transaction` object is procured by - calling the :meth:`~.Connection.begin` method of - :class:`.Connection`:: + calling the :meth:`_engine.Connection.begin` method of + :class:`_engine.Connection`:: from sqlalchemy import create_engine engine = create_engine("postgresql://scott:tiger@localhost/test") @@ -1775,7 +1798,7 @@ class Transaction(object): methods in order to control transaction boundaries. It also implements a context manager interface so that the Python ``with`` statement can be used with the - :meth:`.Connection.begin` method:: + :meth:`_engine.Connection.begin` method:: with connection.begin(): connection.execute(text("insert into x (a, b) values (1, 2)")) @@ -1784,11 +1807,11 @@ class Transaction(object): .. seealso:: - :meth:`.Connection.begin` + :meth:`_engine.Connection.begin` - :meth:`.Connection.begin_twophase` + :meth:`_engine.Connection.begin_twophase` - :meth:`.Connection.begin_nested` + :meth:`_engine.Connection.begin_nested` .. index:: single: thread safety; Transaction @@ -1886,7 +1909,7 @@ class NestedTransaction(Transaction): """Represent a 'nested', or SAVEPOINT transaction. A new :class:`.NestedTransaction` object may be procured - using the :meth:`.Connection.begin_nested` method. + using the :meth:`_engine.Connection.begin_nested` method. The interface is the same as that of :class:`.Transaction`. @@ -1917,7 +1940,7 @@ class TwoPhaseTransaction(Transaction): """Represent a two-phase transaction. A new :class:`.TwoPhaseTransaction` object may be procured - using the :meth:`.Connection.begin_twophase` method. + using the :meth:`_engine.Connection.begin_twophase` method. The interface is the same as that of :class:`.Transaction` with the addition of the :meth:`prepare` method. @@ -1954,7 +1977,7 @@ class Engine(Connectable, log.Identified): :class:`~sqlalchemy.engine.interfaces.Dialect` together to provide a source of database connectivity and behavior. - An :class:`.Engine` object is instantiated publicly using the + An :class:`_engine.Engine` object is instantiated publicly using the :func:`~sqlalchemy.create_engine` function. .. seealso:: @@ -1998,7 +2021,7 @@ class Engine(Connectable, log.Identified): def update_execution_options(self, **opt): r"""Update the default execution_options dictionary - of this :class:`.Engine`. + of this :class:`_engine.Engine`. The given keys/values in \**opt are added to the default execution options that will be used for @@ -2008,9 +2031,9 @@ class Engine(Connectable, log.Identified): .. seealso:: - :meth:`.Connection.execution_options` + :meth:`_engine.Connection.execution_options` - :meth:`.Engine.execution_options` + :meth:`_engine.Engine.execution_options` """ self._execution_options = self._execution_options.union(opt) @@ -2018,25 +2041,28 @@ class Engine(Connectable, log.Identified): self.dialect.set_engine_execution_options(self, opt) def execution_options(self, **opt): - """Return a new :class:`.Engine` that will provide - :class:`.Connection` objects with the given execution options. + """Return a new :class:`_engine.Engine` that will provide + :class:`_engine.Connection` objects with the given execution options. - The returned :class:`.Engine` remains related to the original - :class:`.Engine` in that it shares the same connection pool and + The returned :class:`_engine.Engine` remains related to the original + :class:`_engine.Engine` in that it shares the same connection pool and other state: - * The :class:`.Pool` used by the new :class:`.Engine` is the - same instance. The :meth:`.Engine.dispose` method will replace + * The :class:`_pool.Pool` used by the new :class:`_engine.Engine` + is the + same instance. The :meth:`_engine.Engine.dispose` + method will replace the connection pool instance for the parent engine as well as this one. - * Event listeners are "cascaded" - meaning, the new :class:`.Engine` + * Event listeners are "cascaded" - meaning, the new + :class:`_engine.Engine` inherits the events of the parent, and new events can be associated - with the new :class:`.Engine` individually. + with the new :class:`_engine.Engine` individually. * The logging configuration and logging_name is copied from the parent - :class:`.Engine`. + :class:`_engine.Engine`. - The intent of the :meth:`.Engine.execution_options` method is - to implement "sharding" schemes where multiple :class:`.Engine` + The intent of the :meth:`_engine.Engine.execution_options` method is + to implement "sharding" schemes where multiple :class:`_engine.Engine` objects refer to the same connection pool, but are differentiated by options that would be consumed by a custom event:: @@ -2045,15 +2071,18 @@ class Engine(Connectable, log.Identified): shard2 = primary_engine.execution_options(shard_id="shard2") Above, the ``shard1`` engine serves as a factory for - :class:`.Connection` objects that will contain the execution option - ``shard_id=shard1``, and ``shard2`` will produce :class:`.Connection` + :class:`_engine.Connection` + objects that will contain the execution option + ``shard_id=shard1``, and ``shard2`` will produce + :class:`_engine.Connection` objects that contain the execution option ``shard_id=shard2``. An event handler can consume the above execution option to perform a schema switch or other operation, given a connection. Below we emit a MySQL ``use`` statement to switch databases, at the same time keeping track of which database we've established using the - :attr:`.Connection.info` dictionary, which gives us a persistent + :attr:`_engine.Connection.info` dictionary, + which gives us a persistent storage space that follows the DBAPI connection:: from sqlalchemy import event @@ -2073,13 +2102,15 @@ class Engine(Connectable, log.Identified): .. seealso:: - :meth:`.Connection.execution_options` - update execution options - on a :class:`.Connection` object. + :meth:`_engine.Connection.execution_options` + - update execution options + on a :class:`_engine.Connection` object. - :meth:`.Engine.update_execution_options` - update the execution - options for a given :class:`.Engine` in place. + :meth:`_engine.Engine.update_execution_options` + - update the execution + options for a given :class:`_engine.Engine` in place. - :meth:`.Engine.get_execution_options` + :meth:`_engine.Engine.get_execution_options` """ @@ -2092,7 +2123,7 @@ class Engine(Connectable, log.Identified): .. seealso:: - :meth:`.Engine.execution_options` + :meth:`_engine.Engine.execution_options` """ return self._execution_options @@ -2116,20 +2147,23 @@ class Engine(Connectable, log.Identified): return "Engine(%r)" % self.url def dispose(self): - """Dispose of the connection pool used by this :class:`.Engine`. + """Dispose of the connection pool used by this :class:`_engine.Engine` + . This has the effect of fully closing all **currently checked in** database connections. Connections that are still checked out will **not** be closed, however they will no longer be associated - with this :class:`.Engine`, so when they are closed individually, - eventually the :class:`.Pool` which they are associated with will + with this :class:`_engine.Engine`, + so when they are closed individually, + eventually the :class:`_pool.Pool` which they are associated with will be garbage collected and they will be closed out fully, if not already closed on checkin. A new connection pool is created immediately after the old one has been disposed. This new pool, like all SQLAlchemy connection pools, does not make any actual connections to the database until one is - first requested, so as long as the :class:`.Engine` isn't used again, + first requested, so as long as the :class:`_engine.Engine` + isn't used again, no new connections will be made. .. seealso:: @@ -2171,7 +2205,7 @@ class Engine(Connectable, log.Identified): self.conn.close() def begin(self, close_with_result=False): - """Return a context manager delivering a :class:`.Connection` + """Return a context manager delivering a :class:`_engine.Connection` with a :class:`.Transaction` established. E.g.:: @@ -2187,20 +2221,22 @@ class Engine(Connectable, log.Identified): is rolled back. The ``close_with_result`` flag is normally ``False``, and indicates - that the :class:`.Connection` will be closed when the operation + that the :class:`_engine.Connection` will be closed when the operation is complete. When set to ``True``, it indicates the - :class:`.Connection` is in "single use" mode, where the + :class:`_engine.Connection` is in "single use" mode, where the :class:`.ResultProxy` returned by the first call to - :meth:`.Connection.execute` will close the :class:`.Connection` when + :meth:`_engine.Connection.execute` will close the + :class:`_engine.Connection` when that :class:`.ResultProxy` has exhausted all result rows. .. seealso:: - :meth:`.Engine.connect` - procure a :class:`.Connection` from - an :class:`.Engine`. + :meth:`_engine.Engine.connect` - procure a + :class:`_engine.Connection` from + an :class:`_engine.Engine`. - :meth:`.Connection.begin` - start a :class:`.Transaction` - for a particular :class:`.Connection`. + :meth:`_engine.Connection.begin` - start a :class:`.Transaction` + for a particular :class:`_engine.Connection`. """ conn = self.connect(close_with_result=close_with_result) @@ -2213,15 +2249,17 @@ class Engine(Connectable, log.Identified): @util.deprecated( "1.4", - "The :meth:`.Engine.transaction` method is deprecated and will be " - "removed in a future release. Use the :meth:`.Engine.begin` context " + "The :meth:`_engine.Engine.transaction` " + "method is deprecated and will be " + "removed in a future release. Use the :meth:`_engine.Engine.begin` " + "context " "manager instead.", ) def transaction(self, callable_, *args, **kwargs): r"""Execute the given function within a transaction boundary. - The function is passed a :class:`.Connection` newly procured - from :meth:`.Engine.connect` as the first argument, + The function is passed a :class:`_engine.Connection` newly procured + from :meth:`_engine.Engine.connect` as the first argument, followed by the given \*args and \**kwargs. e.g.:: @@ -2241,18 +2279,19 @@ class Engine(Connectable, log.Identified): The :meth:`.transaction` method is superseded by the usage of the Python ``with:`` statement, which can - be used with :meth:`.Engine.begin`:: + be used with :meth:`_engine.Engine.begin`:: with engine.begin() as conn: conn.execute(text("some statement"), {'x':5, 'y':10}) .. seealso:: - :meth:`.Engine.begin` - engine-level transactional + :meth:`_engine.Engine.begin` - engine-level transactional context - :meth:`.Connection.transaction` - connection-level version of - :meth:`.Engine.transaction` + :meth:`_engine.Connection.transaction` + - connection-level version of + :meth:`_engine.Engine.transaction` """ kwargs["_sa_skip_warning"] = True @@ -2261,20 +2300,21 @@ class Engine(Connectable, log.Identified): @util.deprecated( "1.4", - "The :meth:`.Engine.run_callable` method is deprecated and will be " - "removed in a future release. Use the :meth:`.Engine.connect` " + "The :meth:`_engine.Engine.run_callable` " + "method is deprecated and will be " + "removed in a future release. Use the :meth:`_engine.Engine.connect` " "context manager instead.", ) def run_callable(self, callable_, *args, **kwargs): r"""Given a callable object or function, execute it, passing - a :class:`.Connection` as the first argument. + a :class:`_engine.Connection` as the first argument. The given \*args and \**kwargs are passed subsequent - to the :class:`.Connection` argument. + to the :class:`_engine.Connection` argument. - This function, along with :meth:`.Connection.run_callable`, - allows a function to be run with a :class:`.Connection` - or :class:`.Engine` object without the need to know + This function, along with :meth:`_engine.Connection.run_callable`, + allows a function to be run with a :class:`_engine.Connection` + or :class:`_engine.Engine` object without the need to know which one is being dealt with. """ @@ -2287,9 +2327,10 @@ class Engine(Connectable, log.Identified): conn._run_ddl_visitor(visitorcallable, element, **kwargs) @util.deprecated_20( - ":meth:`.Engine.execute`", + ":meth:`_engine.Engine.execute`", alternative="All statement execution in SQLAlchemy 2.0 is performed " - "by the :meth:`.Connection.execute` method of :class:`.Connection`, " + "by the :meth:`_engine.Connection.execute` method of " + ":class:`_engine.Connection`, " "or in the ORM by the :meth:`.Session.execute` method of " ":class:`.Session`.", ) @@ -2297,13 +2338,14 @@ class Engine(Connectable, log.Identified): """Executes the given construct and returns a :class:`.ResultProxy`. The arguments are the same as those used by - :meth:`.Connection.execute`. + :meth:`_engine.Connection.execute`. - Here, a :class:`.Connection` is acquired using the - :meth:`~.Engine.connect` method, and the statement executed + Here, a :class:`_engine.Connection` is acquired using the + :meth:`_engine.Engine.connect` method, and the statement executed with that connection. The returned :class:`.ResultProxy` is flagged such that when the :class:`.ResultProxy` is exhausted and its - underlying cursor is closed, the :class:`.Connection` created here + underlying cursor is closed, the :class:`_engine.Connection` + created here will also be closed, which allows its associated DBAPI connection resource to be returned to the connection pool. @@ -2312,9 +2354,10 @@ class Engine(Connectable, log.Identified): return connection.execute(statement, *multiparams, **params) @util.deprecated_20( - ":meth:`.Engine.scalar`", + ":meth:`_engine.Engine.scalar`", alternative="All statement execution in SQLAlchemy 2.0 is performed " - "by the :meth:`.Connection.execute` method of :class:`.Connection`, " + "by the :meth:`_engine.Connection.execute` method of " + ":class:`_engine.Connection`, " "or in the ORM by the :meth:`.Session.execute` method of " ":class:`.Session`; the :meth:`.Result.scalar` method can then be " "used to return a scalar result.", @@ -2335,16 +2378,17 @@ class Engine(Connectable, log.Identified): return connection._execute_compiled(compiled, multiparams, params) def connect(self, close_with_result=False): - """Return a new :class:`.Connection` object. + """Return a new :class:`_engine.Connection` object. - The :class:`.Connection` object is a facade that uses a DBAPI + The :class:`_engine.Connection` object is a facade that uses a DBAPI connection internally in order to communicate with the database. This - connection is procured from the connection-holding :class:`.Pool` - referenced by this :class:`.Engine`. When the - :meth:`~.Connection.close` method of the :class:`.Connection` object + connection is procured from the connection-holding :class:`_pool.Pool` + referenced by this :class:`_engine.Engine`. When the + :meth:`_engine.Connection.close` method of the + :class:`_engine.Connection` object is called, the underlying DBAPI connection is then returned to the connection pool, where it may be used again in a subsequent call to - :meth:`~.Engine.connect`. + :meth:`_engine.Engine.connect`. """ @@ -2352,9 +2396,10 @@ class Engine(Connectable, log.Identified): @util.deprecated( "1.4", - "The :meth:`.Engine.table_names` method is deprecated and will be " + "The :meth:`_engine.Engine.table_names` " + "method is deprecated and will be " "removed in a future release. Please refer to " - ":meth:`.Inspector.get_table_names`.", + ":meth:`_reflection.Inspector.get_table_names`.", ) def table_names(self, schema=None, connection=None): """Return a list of all table names available in the database. @@ -2369,9 +2414,10 @@ class Engine(Connectable, log.Identified): @util.deprecated( "1.4", - "The :meth:`.Engine.has_table` method is deprecated and will be " + "The :meth:`_engine.Engine.has_table` " + "method is deprecated and will be " "removed in a future release. Please refer to " - ":meth:`.Inspector.has_table`.", + ":meth:`_reflection.Inspector.has_table`.", ) def has_table(self, table_name, schema=None): """Return True if the given backend has a table of the given name. @@ -2379,7 +2425,7 @@ class Engine(Connectable, log.Identified): .. seealso:: :ref:`metadata_reflection_inspector` - detailed schema inspection - using the :class:`.Inspector` interface. + using the :class:`_reflection.Inspector` interface. :class:`.quoted_name` - used to pass quoting information along with a schema identifier. @@ -2414,10 +2460,11 @@ class Engine(Connectable, log.Identified): for real. This method provides direct DBAPI connection access for - special situations when the API provided by :class:`.Connection` - is not needed. When a :class:`.Connection` object is already + special situations when the API provided by + :class:`_engine.Connection` + is not needed. When a :class:`_engine.Connection` object is already present, the DBAPI connection is available using - the :attr:`.Connection.connection` accessor. + the :attr:`_engine.Connection.connection` accessor. .. seealso:: diff --git a/lib/sqlalchemy/engine/create.py b/lib/sqlalchemy/engine/create.py index 2831f5e7d5..3c1345c631 100644 --- a/lib/sqlalchemy/engine/create.py +++ b/lib/sqlalchemy/engine/create.py @@ -43,7 +43,7 @@ from ..sql import compiler ), ) def create_engine(url, **kwargs): - """Create a new :class:`.Engine` instance. + """Create a new :class:`_engine.Engine` instance. The standard calling form is to send the URL as the first positional argument, usually a string @@ -53,8 +53,8 @@ def create_engine(url, **kwargs): engine = create_engine("postgresql://scott:tiger@localhost/test") Additional keyword arguments may then follow it which - establish various options on the resulting :class:`.Engine` - and its underlying :class:`.Dialect` and :class:`.Pool` + establish various options on the resulting :class:`_engine.Engine` + and its underlying :class:`.Dialect` and :class:`_pool.Pool` constructs:: engine = create_engine("mysql://scott:tiger@hostname/dbname", @@ -69,15 +69,17 @@ def create_engine(url, **kwargs): ``**kwargs`` takes a wide variety of options which are routed towards their appropriate components. Arguments may be specific to - the :class:`.Engine`, the underlying :class:`.Dialect`, as well as the - :class:`.Pool`. Specific dialects also accept keyword arguments that + the :class:`_engine.Engine`, the underlying :class:`.Dialect`, + as well as the + :class:`_pool.Pool`. Specific dialects also accept keyword arguments that are unique to that dialect. Here, we describe the parameters that are common to most :func:`.create_engine()` usage. - Once established, the newly resulting :class:`.Engine` will - request a connection from the underlying :class:`.Pool` once - :meth:`.Engine.connect` is called, or a method which depends on it - such as :meth:`.Engine.execute` is invoked. The :class:`.Pool` in turn + Once established, the newly resulting :class:`_engine.Engine` will + request a connection from the underlying :class:`_pool.Pool` once + :meth:`_engine.Engine.connect` is called, or a method which depends on it + such as :meth:`_engine.Engine.execute` is invoked. The + :class:`_pool.Pool` in turn will establish the first actual DBAPI connection when this request is received. The :func:`.create_engine` call itself does **not** establish any actual DBAPI connections directly. @@ -233,16 +235,17 @@ def create_engine(url, **kwargs): individual dialects should be consulted directly. Note that the isolation level can also be set on a - per-:class:`.Connection` basis as well, using the + per-:class:`_engine.Connection` basis as well, using the :paramref:`.Connection.execution_options.isolation_level` feature. .. seealso:: - :attr:`.Connection.default_isolation_level` - view default level + :attr:`_engine.Connection.default_isolation_level` + - view default level :paramref:`.Connection.execution_options.isolation_level` - - set per :class:`.Connection` isolation level + - set per :class:`_engine.Connection` isolation level :ref:`SQLite Transaction Isolation ` @@ -252,7 +255,8 @@ def create_engine(url, **kwargs): :ref:`session_transaction_isolation` - for the ORM - :param json_deserializer: for dialects that support the :class:`.JSON` + :param json_deserializer: for dialects that support the + :class:`_types.JSON` datatype, this is a Python callable that will convert a JSON string to a Python object. By default, the Python ``json.loads`` function is used. @@ -260,7 +264,7 @@ def create_engine(url, **kwargs): .. versionchanged:: 1.3.7 The SQLite dialect renamed this from ``_json_deserializer``. - :param json_serializer: for dialects that support the :class:`.JSON` + :param json_serializer: for dialects that support the :class:`_types.JSON` datatype, this is a Python callable that will render a given object as JSON. By default, the Python ``json.dumps`` function is used. @@ -317,7 +321,7 @@ def create_engine(url, **kwargs): specific DBAPI which will be imported before first connect. This parameter causes the import to be bypassed, and the given module to be used instead. Can be used for testing of DBAPIs as well as to - inject "mock" DBAPI implementations into the :class:`.Engine`. + inject "mock" DBAPI implementations into the :class:`_engine.Engine`. :param paramstyle=None: The `paramstyle `_ to use when rendering bound parameters. This style defaults to the @@ -382,13 +386,13 @@ def create_engine(url, **kwargs): :ref:`pool_setting_recycle` :param pool_reset_on_return='rollback': set the - :paramref:`.Pool.reset_on_return` parameter of the underlying - :class:`.Pool` object, which can be set to the values + :paramref:`_pool.Pool.reset_on_return` parameter of the underlying + :class:`_pool.Pool` object, which can be set to the values ``"rollback"``, ``"commit"``, or ``None``. .. seealso:: - :paramref:`.Pool.reset_on_return` + :paramref:`_pool.Pool.reset_on_return` :param pool_timeout=30: number of seconds to wait before giving up on getting a connection from the pool. This is only used diff --git a/lib/sqlalchemy/engine/default.py b/lib/sqlalchemy/engine/default.py index 43ebce83af..5b8cb635c7 100644 --- a/lib/sqlalchemy/engine/default.py +++ b/lib/sqlalchemy/engine/default.py @@ -446,7 +446,7 @@ class DefaultDialect(interfaces.Dialect): This method looks for a dictionary called ``colspecs`` as a class or instance-level variable, - and passes on to :func:`.types.adapt_type`. + and passes on to :func:`_types.adapt_type`. """ return sqltypes.adapt_type(typeobj, self.colspecs) @@ -1446,12 +1446,13 @@ class DefaultExecutionContext(interfaces.ExecutionContext): generation function, e.g. as described at :ref:`context_default_functions`. It consists of a dictionary which includes entries for each column/value pair that is to be part of the INSERT or UPDATE statement. The keys of the - dictionary will be the key value of each :class:`.Column`, which is usually + dictionary will be the key value of each :class:`_schema.Column`, + which is usually synonymous with the name. Note that the :attr:`.DefaultExecutionContext.current_parameters` attribute does not accommodate for the "multi-values" feature of the - :meth:`.Insert.values` method. The + :meth:`_expression.Insert.values` method. The :meth:`.DefaultExecutionContext.get_current_parameters` method should be preferred. @@ -1471,11 +1472,13 @@ class DefaultExecutionContext(interfaces.ExecutionContext): :ref:`context_default_functions`. When invoked, a dictionary is returned which includes entries for each column/value pair that is part of the INSERT or UPDATE statement. The keys of the dictionary will be - the key value of each :class:`.Column`, which is usually synonymous + the key value of each :class:`_schema.Column`, + which is usually synonymous with the name. :param isolate_multiinsert_groups=True: indicates that multi-valued - INSERT constructs created using :meth:`.Insert.values` should be + INSERT constructs created using :meth:`_expression.Insert.values` + should be handled by returning only the subset of parameters that are local to the current column default invocation. When ``False``, the raw parameters of the statement are returned including the diff --git a/lib/sqlalchemy/engine/events.py b/lib/sqlalchemy/engine/events.py index 32292c826c..46459cf73f 100644 --- a/lib/sqlalchemy/engine/events.py +++ b/lib/sqlalchemy/engine/events.py @@ -15,13 +15,13 @@ from .. import exc class ConnectionEvents(event.Events): """Available events for :class:`.Connectable`, which includes - :class:`.Connection` and :class:`.Engine`. + :class:`_engine.Connection` and :class:`_engine.Engine`. The methods here define the name of an event as well as the names of members that are passed to listener functions. An event listener can be associated with any :class:`.Connectable` - class or instance, such as an :class:`.Engine`, e.g.:: + class or instance, such as an :class:`_engine.Engine`, e.g.:: from sqlalchemy import event, create_engine @@ -32,7 +32,7 @@ class ConnectionEvents(event.Events): engine = create_engine('postgresql://scott:tiger@localhost/test') event.listen(engine, "before_cursor_execute", before_cursor_execute) - or with a specific :class:`.Connection`:: + or with a specific :class:`_engine.Connection`:: with engine.begin() as conn: @event.listens_for(conn, 'before_cursor_execute') @@ -62,19 +62,23 @@ class ConnectionEvents(event.Events): return statement, parameters .. note:: :class:`.ConnectionEvents` can be established on any - combination of :class:`.Engine`, :class:`.Connection`, as well + combination of :class:`_engine.Engine`, :class:`_engine.Connection`, + as well as instances of each of those classes. Events across all four scopes will fire off for a given instance of - :class:`.Connection`. However, for performance reasons, the - :class:`.Connection` object determines at instantiation time - whether or not its parent :class:`.Engine` has event listeners - established. Event listeners added to the :class:`.Engine` - class or to an instance of :class:`.Engine` *after* the instantiation - of a dependent :class:`.Connection` instance will usually - *not* be available on that :class:`.Connection` instance. The newly - added listeners will instead take effect for :class:`.Connection` + :class:`_engine.Connection`. However, for performance reasons, the + :class:`_engine.Connection` object determines at instantiation time + whether or not its parent :class:`_engine.Engine` has event listeners + established. Event listeners added to the :class:`_engine.Engine` + class or to an instance of :class:`_engine.Engine` + *after* the instantiation + of a dependent :class:`_engine.Connection` instance will usually + *not* be available on that :class:`_engine.Connection` instance. + The newly + added listeners will instead take effect for + :class:`_engine.Connection` instances created subsequent to those event listeners being - established on the parent :class:`.Engine` class or instance. + established on the parent :class:`_engine.Engine` class or instance. :param retval=False: Applies to the :meth:`.before_execute` and :meth:`.before_cursor_execute` events only. When True, the @@ -156,9 +160,10 @@ class ConnectionEvents(event.Events): # do something with clauseelement, multiparams, params return clauseelement, multiparams, params - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object :param clauseelement: SQL expression construct, :class:`.Compiled` - instance, or string statement passed to :meth:`.Connection.execute`. + instance, or string statement passed to + :meth:`_engine.Connection.execute`. :param multiparams: Multiple parameter sets, a list of dictionaries. :param params: Single parameter set, a single dictionary. @@ -172,9 +177,10 @@ class ConnectionEvents(event.Events): """Intercept high level execute() events after execute. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object :param clauseelement: SQL expression construct, :class:`.Compiled` - instance, or string statement passed to :meth:`.Connection.execute`. + instance, or string statement passed to + :meth:`_engine.Connection.execute`. :param multiparams: Multiple parameter sets, a list of dictionaries. :param params: Single parameter set, a single dictionary. :param result: :class:`.ResultProxy` generated by the execution. @@ -204,7 +210,7 @@ class ConnectionEvents(event.Events): See the example at :class:`.ConnectionEvents`. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object :param cursor: DBAPI cursor object :param statement: string SQL statement, as to be passed to the DBAPI :param parameters: Dictionary, tuple, or list of parameters being @@ -228,7 +234,7 @@ class ConnectionEvents(event.Events): ): """Intercept low-level cursor execute() events after execution. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object :param cursor: DBAPI cursor object. Will have results pending if the statement was a SELECT, but these should not be consumed as they will be needed by the :class:`.ResultProxy`. @@ -244,7 +250,8 @@ class ConnectionEvents(event.Events): """ def handle_error(self, exception_context): - r"""Intercept all exceptions processed by the :class:`.Connection`. + r"""Intercept all exceptions processed by the + :class:`_engine.Connection`. This includes all exceptions emitted by the DBAPI as well as within SQLAlchemy's statement invocation process, including @@ -362,9 +369,9 @@ class ConnectionEvents(event.Events): ``False``. .. versionchanged:: 1.0.0 The :meth:`.handle_error` event is now - invoked when an :class:`.Engine` fails during the initial - call to :meth:`.Engine.connect`, as well as when a - :class:`.Connection` object encounters an error during a + invoked when an :class:`_engine.Engine` fails during the initial + call to :meth:`_engine.Engine.connect`, as well as when a + :class:`_engine.Connection` object encounters an error during a reconnect operation. .. versionchanged:: 1.0.0 The :meth:`.handle_error` event is @@ -380,32 +387,39 @@ class ConnectionEvents(event.Events): """ def engine_connect(self, conn, branch): - """Intercept the creation of a new :class:`.Connection`. + """Intercept the creation of a new :class:`_engine.Connection`. This event is called typically as the direct result of calling - the :meth:`.Engine.connect` method. + the :meth:`_engine.Engine.connect` method. - It differs from the :meth:`.PoolEvents.connect` method, which + It differs from the :meth:`_events.PoolEvents.connect` method, which refers to the actual connection to a database at the DBAPI level; a DBAPI connection may be pooled and reused for many operations. In contrast, this event refers only to the production of a higher level - :class:`.Connection` wrapper around such a DBAPI connection. + :class:`_engine.Connection` wrapper around such a DBAPI connection. - It also differs from the :meth:`.PoolEvents.checkout` event - in that it is specific to the :class:`.Connection` object, not the - DBAPI connection that :meth:`.PoolEvents.checkout` deals with, although + It also differs from the :meth:`_events.PoolEvents.checkout` event + in that it is specific to the :class:`_engine.Connection` object, + not the + DBAPI connection that :meth:`_events.PoolEvents.checkout` deals with, + although this DBAPI connection is available here via the - :attr:`.Connection.connection` attribute. But note there can in fact - be multiple :meth:`.PoolEvents.checkout` events within the lifespan - of a single :class:`.Connection` object, if that :class:`.Connection` + :attr:`_engine.Connection.connection` attribute. + But note there can in fact + be multiple :meth:`_events.PoolEvents.checkout` + events within the lifespan + of a single :class:`_engine.Connection` object, if that + :class:`_engine.Connection` is invalidated and re-established. There can also be multiple - :class:`.Connection` objects generated for the same already-checked-out - DBAPI connection, in the case that a "branch" of a :class:`.Connection` + :class:`_engine.Connection` + objects generated for the same already-checked-out + DBAPI connection, in the case that a "branch" of a + :class:`_engine.Connection` is produced. - :param conn: :class:`.Connection` object. + :param conn: :class:`_engine.Connection` object. :param branch: if True, this is a "branch" of an existing - :class:`.Connection`. A branch is generated within the course + :class:`_engine.Connection`. A branch is generated within the course of a statement execution to invoke supplemental statements, most typically to pre-execute a SELECT of a default value for the purposes of an INSERT statement. @@ -419,81 +433,91 @@ class ConnectionEvents(event.Events): to transparently ensure pooled connections are connected to the database. - :meth:`.PoolEvents.checkout` the lower-level pool checkout event + :meth:`_events.PoolEvents.checkout` + the lower-level pool checkout event for an individual DBAPI connection :meth:`.ConnectionEvents.set_connection_execution_options` - a copy - of a :class:`.Connection` is also made when the - :meth:`.Connection.execution_options` method is called. + of a :class:`_engine.Connection` is also made when the + :meth:`_engine.Connection.execution_options` method is called. """ def set_connection_execution_options(self, conn, opts): - """Intercept when the :meth:`.Connection.execution_options` + """Intercept when the :meth:`_engine.Connection.execution_options` method is called. - This method is called after the new :class:`.Connection` has been + This method is called after the new :class:`_engine.Connection` + has been produced, with the newly updated execution options collection, but before the :class:`.Dialect` has acted upon any of those new options. - Note that this method is not called when a new :class:`.Connection` + Note that this method is not called when a new + :class:`_engine.Connection` is produced which is inheriting execution options from its parent - :class:`.Engine`; to intercept this condition, use the + :class:`_engine.Engine`; to intercept this condition, use the :meth:`.ConnectionEvents.engine_connect` event. - :param conn: The newly copied :class:`.Connection` object + :param conn: The newly copied :class:`_engine.Connection` object :param opts: dictionary of options that were passed to the - :meth:`.Connection.execution_options` method. + :meth:`_engine.Connection.execution_options` method. .. versionadded:: 0.9.0 .. seealso:: :meth:`.ConnectionEvents.set_engine_execution_options` - event - which is called when :meth:`.Engine.execution_options` is called. + which is called when :meth:`_engine.Engine.execution_options` + is called. """ def set_engine_execution_options(self, engine, opts): - """Intercept when the :meth:`.Engine.execution_options` + """Intercept when the :meth:`_engine.Engine.execution_options` method is called. - The :meth:`.Engine.execution_options` method produces a shallow - copy of the :class:`.Engine` which stores the new options. That new - :class:`.Engine` is passed here. A particular application of this + The :meth:`_engine.Engine.execution_options` method produces a shallow + copy of the :class:`_engine.Engine` which stores the new options. + That new + :class:`_engine.Engine` is passed here. + A particular application of this method is to add a :meth:`.ConnectionEvents.engine_connect` event - handler to the given :class:`.Engine` which will perform some per- - :class:`.Connection` task specific to these execution options. + handler to the given :class:`_engine.Engine` + which will perform some per- + :class:`_engine.Connection` task specific to these execution options. - :param conn: The newly copied :class:`.Engine` object + :param conn: The newly copied :class:`_engine.Engine` object :param opts: dictionary of options that were passed to the - :meth:`.Connection.execution_options` method. + :meth:`_engine.Connection.execution_options` method. .. versionadded:: 0.9.0 .. seealso:: :meth:`.ConnectionEvents.set_connection_execution_options` - event - which is called when :meth:`.Connection.execution_options` is + which is called when :meth:`_engine.Connection.execution_options` + is called. """ def engine_disposed(self, engine): - """Intercept when the :meth:`.Engine.dispose` method is called. + """Intercept when the :meth:`_engine.Engine.dispose` method is called. - The :meth:`.Engine.dispose` method instructs the engine to - "dispose" of it's connection pool (e.g. :class:`.Pool`), and + The :meth:`_engine.Engine.dispose` method instructs the engine to + "dispose" of it's connection pool (e.g. :class:`_pool.Pool`), and replaces it with a new one. Disposing of the old pool has the effect that existing checked-in connections are closed. The new pool does not establish any new connections until it is first used. This event can be used to indicate that resources related to the - :class:`.Engine` should also be cleaned up, keeping in mind that the - :class:`.Engine` can still be used for new requests in which case + :class:`_engine.Engine` should also be cleaned up, + keeping in mind that the + :class:`_engine.Engine` + can still be used for new requests in which case it re-acquires connection resources. .. versionadded:: 1.0.5 @@ -503,7 +527,7 @@ class ConnectionEvents(event.Events): def begin(self, conn): """Intercept begin() events. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object """ @@ -511,17 +535,17 @@ class ConnectionEvents(event.Events): """Intercept rollback() events, as initiated by a :class:`.Transaction`. - Note that the :class:`.Pool` also "auto-rolls back" + Note that the :class:`_pool.Pool` also "auto-rolls back" a DBAPI connection upon checkin, if the ``reset_on_return`` flag is set to its default value of ``'rollback'``. To intercept this - rollback, use the :meth:`.PoolEvents.reset` hook. + rollback, use the :meth:`_events.PoolEvents.reset` hook. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object .. seealso:: - :meth:`.PoolEvents.reset` + :meth:`_events.PoolEvents.reset` """ @@ -529,18 +553,18 @@ class ConnectionEvents(event.Events): """Intercept commit() events, as initiated by a :class:`.Transaction`. - Note that the :class:`.Pool` may also "auto-commit" + Note that the :class:`_pool.Pool` may also "auto-commit" a DBAPI connection upon checkin, if the ``reset_on_return`` flag is set to the value ``'commit'``. To intercept this - commit, use the :meth:`.PoolEvents.reset` hook. + commit, use the :meth:`_events.PoolEvents.reset` hook. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object """ def savepoint(self, conn, name): """Intercept savepoint() events. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object :param name: specified name used for the savepoint. """ @@ -548,7 +572,7 @@ class ConnectionEvents(event.Events): def rollback_savepoint(self, conn, name, context): """Intercept rollback_savepoint() events. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object :param name: specified name used for the savepoint. :param context: :class:`.ExecutionContext` in use. May be ``None``. @@ -557,7 +581,7 @@ class ConnectionEvents(event.Events): def release_savepoint(self, conn, name, context): """Intercept release_savepoint() events. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object :param name: specified name used for the savepoint. :param context: :class:`.ExecutionContext` in use. May be ``None``. @@ -566,7 +590,7 @@ class ConnectionEvents(event.Events): def begin_twophase(self, conn, xid): """Intercept begin_twophase() events. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object :param xid: two-phase XID identifier """ @@ -574,14 +598,14 @@ class ConnectionEvents(event.Events): def prepare_twophase(self, conn, xid): """Intercept prepare_twophase() events. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object :param xid: two-phase XID identifier """ def rollback_twophase(self, conn, xid, is_prepared): """Intercept rollback_twophase() events. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object :param xid: two-phase XID identifier :param is_prepared: boolean, indicates if :meth:`.TwoPhaseTransaction.prepare` was called. @@ -591,7 +615,7 @@ class ConnectionEvents(event.Events): def commit_twophase(self, conn, xid, is_prepared): """Intercept commit_twophase() events. - :param conn: :class:`.Connection` object + :param conn: :class:`_engine.Connection` object :param xid: two-phase XID identifier :param is_prepared: boolean, indicates if :meth:`.TwoPhaseTransaction.prepare` was called. diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py index 6cf4d7dbda..224d4f693a 100644 --- a/lib/sqlalchemy/engine/interfaces.py +++ b/lib/sqlalchemy/engine/interfaces.py @@ -185,7 +185,7 @@ class Dialect(object): """Transform a generic type to a dialect-specific type. Dialect classes will usually use the - :func:`.types.adapt_type` function in the types module to + :func:`_types.adapt_type` function in the types module to accomplish this. The returned result is cached *per dialect class* so can @@ -215,7 +215,7 @@ class Dialect(object): def get_columns(self, connection, table_name, schema=None, **kw): """Return information about columns in `table_name`. - Given a :class:`.Connection`, a string + Given a :class:`_engine.Connection`, a string `table_name`, and an optional string `schema`, return column information as a list of dictionaries with these keys: @@ -249,7 +249,7 @@ class Dialect(object): """Return information about the primary key constraint on table_name`. - Given a :class:`.Connection`, a string + Given a :class:`_engine.Connection`, a string `table_name`, and an optional string `schema`, return primary key information as a dictionary with these keys: @@ -265,7 +265,7 @@ class Dialect(object): def get_foreign_keys(self, connection, table_name, schema=None, **kw): """Return information about foreign_keys in `table_name`. - Given a :class:`.Connection`, a string + Given a :class:`_engine.Connection`, a string `table_name`, and an optional string `schema`, return foreign key information as a list of dicts with these keys: @@ -321,7 +321,7 @@ class Dialect(object): def get_view_definition(self, connection, view_name, schema=None, **kw): """Return view definition. - Given a :class:`.Connection`, a string + Given a :class:`_engine.Connection`, a string `view_name`, and an optional string `schema`, return the view definition. """ @@ -331,7 +331,7 @@ class Dialect(object): def get_indexes(self, connection, table_name, schema=None, **kw): """Return information about indexes in `table_name`. - Given a :class:`.Connection`, a string + Given a :class:`_engine.Connection`, a string `table_name` and an optional string `schema`, return index information as a list of dictionaries with these keys: @@ -434,7 +434,7 @@ class Dialect(object): def has_table(self, connection, table_name, schema=None, **kw): """Check the existence of a particular table in the database. - Given a :class:`.Connection` object and a string + Given a :class:`_engine.Connection` object and a string `table_name`, return True if the given table (possibly within the specified `schema`) exists in the database, False otherwise. @@ -445,7 +445,7 @@ class Dialect(object): def has_index(self, connection, table_name, index_name, schema=None): """Check the existence of a particular index name in the database. - Given a :class:`.Connection` object, a string + Given a :class:`_engine.Connection` object, a string `table_name` and stiring index name, return True if an index of the given name on the given table exists, false otherwise. @@ -463,7 +463,7 @@ class Dialect(object): def has_sequence(self, connection, sequence_name, schema=None, **kw): """Check the existence of a particular sequence in the database. - Given a :class:`.Connection` object and a string + Given a :class:`_engine.Connection` object and a string `sequence_name`, return True if the given sequence exists in the database, False otherwise. """ @@ -506,7 +506,8 @@ class Dialect(object): :meth:`.Dialect.do_autocommit` hook is provided for DBAPIs that need some extra commands emitted after a commit in order to enter the next transaction, when the - SQLAlchemy :class:`.Connection` is used in its default "autocommit" + SQLAlchemy :class:`_engine.Connection` + is used in its default "autocommit" mode. :param dbapi_connection: a DBAPI connection, typically @@ -542,7 +543,8 @@ class Dialect(object): """Provide an implementation of ``connection.close()``, given a DBAPI connection. - This hook is called by the :class:`.Pool` when a connection has been + This hook is called by the :class:`_pool.Pool` + when a connection has been detached from the pool, or is being returned beyond the normal capacity of the pool. @@ -563,7 +565,7 @@ class Dialect(object): def do_savepoint(self, connection, name): """Create a savepoint with the given name. - :param connection: a :class:`.Connection`. + :param connection: a :class:`_engine.Connection`. :param name: savepoint name. """ @@ -573,7 +575,7 @@ class Dialect(object): def do_rollback_to_savepoint(self, connection, name): """Rollback a connection to the named savepoint. - :param connection: a :class:`.Connection`. + :param connection: a :class:`_engine.Connection`. :param name: savepoint name. """ @@ -583,7 +585,7 @@ class Dialect(object): def do_release_savepoint(self, connection, name): """Release the named savepoint on a connection. - :param connection: a :class:`.Connection`. + :param connection: a :class:`_engine.Connection`. :param name: savepoint name. """ @@ -592,7 +594,7 @@ class Dialect(object): def do_begin_twophase(self, connection, xid): """Begin a two phase transaction on the given connection. - :param connection: a :class:`.Connection`. + :param connection: a :class:`_engine.Connection`. :param xid: xid """ @@ -602,7 +604,7 @@ class Dialect(object): def do_prepare_twophase(self, connection, xid): """Prepare a two phase transaction on the given connection. - :param connection: a :class:`.Connection`. + :param connection: a :class:`_engine.Connection`. :param xid: xid """ @@ -614,7 +616,7 @@ class Dialect(object): ): """Rollback a two phase transaction on the given connection. - :param connection: a :class:`.Connection`. + :param connection: a :class:`_engine.Connection`. :param xid: xid :param is_prepared: whether or not :meth:`.TwoPhaseTransaction.prepare` was called. @@ -630,7 +632,7 @@ class Dialect(object): """Commit a two phase transaction on the given connection. - :param connection: a :class:`.Connection`. + :param connection: a :class:`_engine.Connection`. :param xid: xid :param is_prepared: whether or not :meth:`.TwoPhaseTransaction.prepare` was called. @@ -644,7 +646,7 @@ class Dialect(object): """Recover list of uncommitted prepared two phase transaction identifiers on the given connection. - :param connection: a :class:`.Connection`. + :param connection: a :class:`_engine.Connection`. """ @@ -734,11 +736,13 @@ class Dialect(object): isolation modes, Unicode modes, etc. The "do_on_connect" callable is invoked by using the - :meth:`.PoolEvents.first_connect` and :meth:`.PoolEvents.connect` event + :meth:`_events.PoolEvents.first_connect` and + :meth:`_events.PoolEvents.connect` event hooks, then unwrapping the DBAPI connection and passing it into the callable. The reason it is invoked for both events is so that any dialect-level initialization that occurs upon first connection, which - also makes use of the :meth:`.PoolEvents.first_connect` method, will + also makes use of the :meth:`_events.PoolEvents.first_connect` method, + will proceed after this hook has been called. This currently means the hook is in fact called twice for the very first connection in which a dialect creates; and once per connection afterwards. @@ -760,22 +764,24 @@ class Dialect(object): """Given a DBAPI connection, revert its isolation to the default. Note that this is a dialect-level method which is used as part - of the implementation of the :class:`.Connection` and - :class:`.Engine` + of the implementation of the :class:`_engine.Connection` and + :class:`_engine.Engine` isolation level facilities; these APIs should be preferred for most typical use cases. .. seealso:: - :meth:`.Connection.get_isolation_level` - view current level + :meth:`_engine.Connection.get_isolation_level` + - view current level - :attr:`.Connection.default_isolation_level` - view default level + :attr:`_engine.Connection.default_isolation_level` + - view default level :paramref:`.Connection.execution_options.isolation_level` - - set per :class:`.Connection` isolation level + set per :class:`_engine.Connection` isolation level :paramref:`.create_engine.isolation_level` - - set per :class:`.Engine` isolation level + set per :class:`_engine.Engine` isolation level """ @@ -785,22 +791,24 @@ class Dialect(object): """Given a DBAPI connection, set its isolation level. Note that this is a dialect-level method which is used as part - of the implementation of the :class:`.Connection` and - :class:`.Engine` + of the implementation of the :class:`_engine.Connection` and + :class:`_engine.Engine` isolation level facilities; these APIs should be preferred for most typical use cases. .. seealso:: - :meth:`.Connection.get_isolation_level` - view current level + :meth:`_engine.Connection.get_isolation_level` + - view current level - :attr:`.Connection.default_isolation_level` - view default level + :attr:`_engine.Connection.default_isolation_level` + - view default level :paramref:`.Connection.execution_options.isolation_level` - - set per :class:`.Connection` isolation level + set per :class:`_engine.Connection` isolation level :paramref:`.create_engine.isolation_level` - - set per :class:`.Engine` isolation level + set per :class:`_engine.Engine` isolation level """ @@ -809,27 +817,30 @@ class Dialect(object): def get_isolation_level(self, dbapi_conn): """Given a DBAPI connection, return its isolation level. - When working with a :class:`.Connection` object, the corresponding + When working with a :class:`_engine.Connection` object, + the corresponding DBAPI connection may be procured using the - :attr:`.Connection.connection` accessor. + :attr:`_engine.Connection.connection` accessor. Note that this is a dialect-level method which is used as part - of the implementation of the :class:`.Connection` and - :class:`.Engine` isolation level facilities; + of the implementation of the :class:`_engine.Connection` and + :class:`_engine.Engine` isolation level facilities; these APIs should be preferred for most typical use cases. .. seealso:: - :meth:`.Connection.get_isolation_level` - view current level + :meth:`_engine.Connection.get_isolation_level` + - view current level - :attr:`.Connection.default_isolation_level` - view default level + :attr:`_engine.Connection.default_isolation_level` + - view default level :paramref:`.Connection.execution_options.isolation_level` - - set per :class:`.Connection` isolation level + set per :class:`_engine.Connection` isolation level :paramref:`.create_engine.isolation_level` - - set per :class:`.Engine` isolation level + set per :class:`_engine.Engine` isolation level """ @@ -883,7 +894,8 @@ class Dialect(object): @classmethod def engine_created(cls, engine): - """A convenience hook called before returning the final :class:`.Engine`. + """A convenience hook called before returning the final + :class:`_engine.Engine`. If the dialect returned a different class from the :meth:`.get_dialect_cls` @@ -903,7 +915,7 @@ class Dialect(object): class CreateEnginePlugin(object): """A set of hooks intended to augment the construction of an - :class:`.Engine` object based on entrypoint names in a URL. + :class:`_engine.Engine` object based on entrypoint names in a URL. The purpose of :class:`.CreateEnginePlugin` is to allow third-party systems to apply engine, pool and dialect level event listeners without @@ -979,7 +991,7 @@ class CreateEnginePlugin(object): arguments afterwards. When the engine creation process completes and produces the - :class:`.Engine` object, it is again passed to the plugin via the + :class:`_engine.Engine` object, it is again passed to the plugin via the :meth:`.CreateEnginePlugin.engine_created` hook. In this hook, additional changes can be made to the engine, most typically involving setup of events (e.g. those defined in :ref:`core_event_toplevel`). @@ -992,7 +1004,7 @@ class CreateEnginePlugin(object): """Construct a new :class:`.CreateEnginePlugin`. The plugin object is instantiated individually for each call - to :func:`.create_engine`. A single :class:`.Engine` will be + to :func:`.create_engine`. A single :class:`_engine.Engine` will be passed to the :meth:`.CreateEnginePlugin.engine_created` method corresponding to this URL. @@ -1015,7 +1027,8 @@ class CreateEnginePlugin(object): """parse and modify pool kwargs""" def engine_created(self, engine): - """Receive the :class:`.Engine` object when it is fully constructed. + """Receive the :class:`_engine.Engine` + object when it is fully constructed. The plugin may make additional changes to the engine, such as registering engine or connection pool events. @@ -1246,9 +1259,9 @@ class ExecutionContext(object): @util.deprecated_20_cls( ":class:`.Connectable`", alternative=( - "The :class:`.Engine` will be the only Core " + "The :class:`_engine.Engine` will be the only Core " "object that features a .connect() method, and the " - ":class:`.Connection` will be the only object that features " + ":class:`_engine.Connection` will be the only object that features " "an .execute() method." ), constructor=None, @@ -1257,7 +1270,7 @@ class Connectable(object): """Interface for an object which supports execution of SQL constructs. The two implementations of :class:`.Connectable` are - :class:`.Connection` and :class:`.Engine`. + :class:`_engine.Connection` and :class:`_engine.Engine`. Connectable must also implement the 'dialect' member which references a :class:`.Dialect` instance. @@ -1265,19 +1278,20 @@ class Connectable(object): """ def connect(self, **kwargs): - """Return a :class:`.Connection` object. + """Return a :class:`_engine.Connection` object. Depending on context, this may be ``self`` if this object - is already an instance of :class:`.Connection`, or a newly - procured :class:`.Connection` if this object is an instance - of :class:`.Engine`. + is already an instance of :class:`_engine.Connection`, or a newly + procured :class:`_engine.Connection` if this object is an instance + of :class:`_engine.Engine`. """ engine = None - """The :class:`.Engine` instance referred to by this :class:`.Connectable`. + """The :class:`_engine.Engine` instance referred to by this + :class:`.Connectable`. - May be ``self`` if this is already an :class:`.Engine`. + May be ``self`` if this is already an :class:`_engine.Engine`. """ @@ -1311,7 +1325,7 @@ class ExceptionContext(object): """ connection = None - """The :class:`.Connection` in use during the exception. + """The :class:`_engine.Connection` in use during the exception. This member is present, except in the case of a failure when first connecting. @@ -1324,7 +1338,7 @@ class ExceptionContext(object): """ engine = None - """The :class:`.Engine` in use during the exception. + """The :class:`_engine.Engine` in use during the exception. This member should always be present, even in the case of a failure when first connecting. diff --git a/lib/sqlalchemy/engine/mock.py b/lib/sqlalchemy/engine/mock.py index bda9e91b5d..19a3b8e6c8 100644 --- a/lib/sqlalchemy/engine/mock.py +++ b/lib/sqlalchemy/engine/mock.py @@ -62,7 +62,8 @@ def create_mock_engine(url, executor, **kw): """Create a "mock" engine used for echoing DDL. This is a utility function used for debugging or storing the output of DDL - sequences as generated by :meth:`.MetaData.create_all` and related methods. + sequences as generated by :meth:`_schema.MetaData.create_all` + and related methods. The function accepts a URL which is used only to determine the kind of dialect to be used, as well as an "executor" callable function which diff --git a/lib/sqlalchemy/engine/reflection.py b/lib/sqlalchemy/engine/reflection.py index 1a34e9c72e..344d5511d1 100644 --- a/lib/sqlalchemy/engine/reflection.py +++ b/lib/sqlalchemy/engine/reflection.py @@ -66,38 +66,43 @@ class Inspector(object): consistent interface as well as caching support for previously fetched metadata. - A :class:`.Inspector` object is usually created via the - :func:`.inspect` function, which may be passed an :class:`.Engine` - or a :class:`.Connection`:: + A :class:`_reflection.Inspector` object is usually created via the + :func:`_sa.inspect` function, which may be passed an + :class:`_engine.Engine` + or a :class:`_engine.Connection`:: from sqlalchemy import inspect, create_engine engine = create_engine('...') insp = inspect(engine) Where above, the :class:`~sqlalchemy.engine.interfaces.Dialect` associated - with the engine may opt to return an :class:`.Inspector` subclass that + with the engine may opt to return an :class:`_reflection.Inspector` + subclass that provides additional methods specific to the dialect's target database. """ @util.deprecated( "1.4", - "The __init__() method on :class:`.Inspector` is deprecated and " + "The __init__() method on :class:`_reflection.Inspector` " + "is deprecated and " "will be removed in a future release. Please use the " ":func:`.sqlalchemy.inspect` " - "function on an :class:`.Engine` or :class:`.Connection` in order to " - "acquire an :class:`.Inspector`.", + "function on an :class:`_engine.Engine` or " + ":class:`_engine.Connection` " + "in order to " + "acquire an :class:`_reflection.Inspector`.", ) def __init__(self, bind): - """Initialize a new :class:`.Inspector`. + """Initialize a new :class:`_reflection.Inspector`. :param bind: a :class:`~sqlalchemy.engine.Connectable`, which is typically an instance of :class:`~sqlalchemy.engine.Engine` or :class:`~sqlalchemy.engine.Connection`. - For a dialect-specific instance of :class:`.Inspector`, see - :meth:`.Inspector.from_engine` + For a dialect-specific instance of :class:`_reflection.Inspector`, see + :meth:`_reflection.Inspector.from_engine` """ return self._init_legacy(bind) @@ -135,11 +140,14 @@ class Inspector(object): @classmethod @util.deprecated( "1.4", - "The from_engine() method on :class:`.Inspector` is deprecated and " + "The from_engine() method on :class:`_reflection.Inspector` " + "is deprecated and " "will be removed in a future release. Please use the " ":func:`.sqlalchemy.inspect` " - "function on an :class:`.Engine` or :class:`.Connection` in order to " - "acquire an :class:`.Inspector`.", + "function on an :class:`_engine.Engine` or " + ":class:`_engine.Connection` " + "in order to " + "acquire an :class:`_reflection.Inspector`.", ) def from_engine(cls, bind): """Construct a new dialect-specific Inspector object from the given @@ -151,12 +159,13 @@ class Inspector(object): :class:`~sqlalchemy.engine.Connection`. This method differs from direct a direct constructor call of - :class:`.Inspector` in that the + :class:`_reflection.Inspector` in that the :class:`~sqlalchemy.engine.interfaces.Dialect` is given a chance to - provide a dialect-specific :class:`.Inspector` instance, which may + provide a dialect-specific :class:`_reflection.Inspector` instance, + which may provide additional methods. - See the example at :class:`.Inspector`. + See the example at :class:`_reflection.Inspector`. """ return cls._construct(cls._init_legacy, bind) @@ -182,7 +191,8 @@ class Inspector(object): transaction. This essentially allows connect()/close() to be called if we detected - that we're against an :class:`.Engine` and not a :class:`.Connection`. + that we're against an :class:`_engine.Engine` and not a + :class:`_engine.Connection`. """ if self._op_context_requires_connect: @@ -197,7 +207,8 @@ class Inspector(object): @contextlib.contextmanager def _inspection_context(self): - """Return an :class:`.Inspector` from this one that will run all + """Return an :class:`_reflection.Inspector` + from this one that will run all operations on a single connection. """ @@ -233,7 +244,8 @@ class Inspector(object): """Return all table names in referred to within a particular schema. The names are expected to be real tables only, not views. - Views are instead returned using the :meth:`.Inspector.get_view_names` + Views are instead returned using the + :meth:`_reflection.Inspector.get_view_names` method. @@ -250,9 +262,9 @@ class Inspector(object): .. seealso:: - :meth:`.Inspector.get_sorted_table_and_fkc_names` + :meth:`_reflection.Inspector.get_sorted_table_and_fkc_names` - :attr:`.MetaData.sorted_tables` + :attr:`_schema.MetaData.sorted_tables` """ @@ -289,10 +301,10 @@ class Inspector(object): .. seealso:: - :meth:`.Inspector.get_table_names` + :meth:`_reflection.Inspector.get_table_names` :func:`.sort_tables_and_constraints` - similar method which works - with an already-given :class:`.MetaData`. + with an already-given :class:`_schema.MetaData`. """ @@ -646,9 +658,10 @@ class Inspector(object): ) @util.deprecated_20( - ":meth:`.Inspector.reflecttable`", - "The :meth:`.Inspector.reflecttable` method was renamed to " - ":meth:`.Inspector.reflect_table`. This deprecated alias " + ":meth:`_reflection.Inspector.reflecttable`", + "The :meth:`_reflection.Inspector.reflecttable` " + "method was renamed to " + ":meth:`_reflection.Inspector.reflect_table`. This deprecated alias " "will be removed in a future release.", ) def reflecttable(self, *args, **kwargs): diff --git a/lib/sqlalchemy/engine/result.py b/lib/sqlalchemy/engine/result.py index be44f67e73..6944e0c67b 100644 --- a/lib/sqlalchemy/engine/result.py +++ b/lib/sqlalchemy/engine/result.py @@ -327,7 +327,8 @@ class CursorResultMetaData(ResultMetaData): The remaining fairly common case is that of the textual SQL that includes at least partial column information; this is when - we use a :class:`.TextualSelect` construct. This construct may have + we use a :class:`_expression.TextualSelect` construct. + This construct may have unordered or ordered column information. In the ordered case, we merge the cursor.description and the compiled construct's information positionally, and warn if there are additional description names @@ -350,7 +351,8 @@ class CursorResultMetaData(ResultMetaData): SQLAlchemy for all cases up through te 0.9 series. Positional matching for compiled SQL expressions was introduced in 1.0 as a major performance feature, and positional matching for textual - :class:`.TextualSelect` objects in 1.1. As name matching is no longer + :class:`_expression.TextualSelect` objects in 1.1. + As name matching is no longer a common case, it was acceptable to factor it into smaller generator- oriented methods that are easier to understand, but incur slightly more performance overhead. @@ -1245,14 +1247,14 @@ class BaseResult(object): corresponding to the list of primary key columns in the target table. - This only applies to single row :func:`~.sql.expression.insert` + This only applies to single row :func:`_expression.insert` constructs which did not explicitly specify - :meth:`.Insert.returning`. + :meth:`_expression.Insert.returning`. Note that primary key columns which specify a server_default clause, or otherwise do not qualify as "autoincrement" - columns (see the notes at :class:`.Column`), and were + columns (see the notes at :class:`_schema.Column`), and were generated using the database-side default, will appear in this list as ``None`` unless the backend supports "returning" and the insert statement executed @@ -1504,7 +1506,7 @@ class BaseResult(object): def is_insert(self): """True if this :class:`.ResultProxy` is the result of a executing an expression language compiled - :func:`.expression.insert` construct. + :func:`_expression.insert` construct. When True, this implies that the :attr:`inserted_primary_key` attribute is accessible, @@ -1562,7 +1564,8 @@ class ResultProxy(BaseResult): In the case of a result that is the product of :ref:`connectionless execution `, - the underlying :class:`.Connection` object is also closed, which + the underlying :class:`_engine.Connection` object is also closed, + which :term:`releases` DBAPI connection resources. .. deprecated:: 2.0 "connectionless" execution is deprecated and will diff --git a/lib/sqlalchemy/exc.py b/lib/sqlalchemy/exc.py index a6da844dcb..aef8598a9d 100644 --- a/lib/sqlalchemy/exc.py +++ b/lib/sqlalchemy/exc.py @@ -127,8 +127,9 @@ class CircularDependencyError(SQLAlchemyError): or pre-deassociate one of the foreign key constrained values. The ``post_update`` flag described at :ref:`post_update` can resolve this cycle. - * In a :attr:`.MetaData.sorted_tables` operation, two :class:`.ForeignKey` - or :class:`.ForeignKeyConstraint` objects mutually refer to each + * In a :attr:`_schema.MetaData.sorted_tables` operation, two + :class:`_schema.ForeignKey` + or :class:`_schema.ForeignKeyConstraint` objects mutually refer to each other. Apply the ``use_alter=True`` flag to one or both, see :ref:`use_alter`. @@ -178,7 +179,8 @@ class DisconnectionError(SQLAlchemyError): """A disconnect is detected on a raw DB-API connection. This error is raised and consumed internally by a connection pool. It can - be raised by the :meth:`.PoolEvents.checkout` event so that the host pool + be raised by the :meth:`_events.PoolEvents.checkout` + event so that the host pool forces a retry; the exception will be caught three times in a row before the pool gives up and raises :class:`~sqlalchemy.exc.InvalidRequestError` regarding the connection attempt. @@ -191,12 +193,12 @@ class DisconnectionError(SQLAlchemyError): class InvalidatePoolError(DisconnectionError): """Raised when the connection pool should invalidate all stale connections. - A subclass of :class:`.DisconnectionError` that indicates that the + A subclass of :class:`_exc.DisconnectionError` that indicates that the disconnect situation encountered on the connection probably means the entire pool should be invalidated, as the database has been restarted. This exception will be handled otherwise the same way as - :class:`.DisconnectionError`, allowing three attempts to reconnect + :class:`_exc.DisconnectionError`, allowing three attempts to reconnect before giving up. .. versionadded:: 1.2 @@ -607,7 +609,7 @@ class RemovedIn20Warning(SADeprecationWarning): class SAPendingDeprecationWarning(PendingDeprecationWarning): - """A similar warning as :class:`.SADeprecationWarning`, this warning + """A similar warning as :class:`_exc.SADeprecationWarning`, this warning is not used in modern versions of SQLAlchemy. """ diff --git a/lib/sqlalchemy/ext/associationproxy.py b/lib/sqlalchemy/ext/associationproxy.py index 599bf966da..fc10cb88d9 100644 --- a/lib/sqlalchemy/ext/associationproxy.py +++ b/lib/sqlalchemy/ext/associationproxy.py @@ -114,7 +114,7 @@ class AssociationProxy(interfaces.InspectionAttrInfo): and/or subclassed directly. :param target_collection: Name of the collection we'll proxy to, - usually created with :func:`.relationship`. + usually created with :func:`_orm.relationship`. :param attr: Attribute on the collected instances we'll proxy for. For example, given a target collection of [obj1, obj2], a @@ -216,7 +216,7 @@ class AssociationProxy(interfaces.InspectionAttrInfo): keywords = association_proxy('kws', 'keyword') If we access this :class:`.AssociationProxy` from - :attr:`.Mapper.all_orm_descriptors`, and we want to view the + :attr:`_orm.Mapper.all_orm_descriptors`, and we want to view the target class for this proxy as mapped by ``User``:: inspect(User).all_orm_descriptors["keywords"].for_class(User).target_class @@ -467,7 +467,7 @@ class AssociationProxyInstance(object): """Return a tuple of ``(local_attr, remote_attr)``. This attribute is convenient when specifying a join - using :meth:`.Query.join` across two relationships:: + using :meth:`_query.Query.join` across two relationships:: sess.query(Parent).join(*Parent.proxied.attr) diff --git a/lib/sqlalchemy/ext/automap.py b/lib/sqlalchemy/ext/automap.py index e409cf38c0..4ae3a415e4 100644 --- a/lib/sqlalchemy/ext/automap.py +++ b/lib/sqlalchemy/ext/automap.py @@ -60,12 +60,16 @@ asking it to reflect the schema and produce mappings:: Above, calling :meth:`.AutomapBase.prepare` while passing along the :paramref:`.AutomapBase.prepare.reflect` parameter indicates that the -:meth:`.MetaData.reflect` method will be called on this declarative base -classes' :class:`.MetaData` collection; then, each **viable** -:class:`.Table` within the :class:`.MetaData` will get a new mapped class -generated automatically. The :class:`.ForeignKeyConstraint` objects which +:meth:`_schema.MetaData.reflect` +method will be called on this declarative base +classes' :class:`_schema.MetaData` collection; then, each **viable** +:class:`_schema.Table` within the :class:`_schema.MetaData` +will get a new mapped class +generated automatically. The :class:`_schema.ForeignKeyConstraint` +objects which link the various tables together will be used to produce new, bidirectional -:func:`.relationship` objects between classes. The classes and relationships +:func:`_orm.relationship` objects between classes. +The classes and relationships follow along a default naming scheme that we can customize. At this point, our basic mapping consisting of related ``User`` and ``Address`` classes is ready to use in the traditional way. @@ -79,10 +83,12 @@ ready to use in the traditional way. Generating Mappings from an Existing MetaData ============================================= -We can pass a pre-declared :class:`.MetaData` object to :func:`.automap_base`. +We can pass a pre-declared :class:`_schema.MetaData` object to +:func:`.automap_base`. This object can be constructed in any way, including programmatically, from a serialized file, or from itself being reflected using -:meth:`.MetaData.reflect`. Below we illustrate a combination of reflection and +:meth:`_schema.MetaData.reflect`. +Below we illustrate a combination of reflection and explicit table declaration:: from sqlalchemy import create_engine, MetaData, Table, Column, ForeignKey @@ -160,7 +166,7 @@ established based on the table name we use. If our schema contains tables print (a1.user) Above, one of the more intricate details is that we illustrated overriding -one of the :func:`.relationship` objects that automap would have created. +one of the :func:`_orm.relationship` objects that automap would have created. To do this, we needed to make sure the names match up with what automap would normally generate, in that the relationship name would be ``User.address_collection`` and the name of the class referred to, from @@ -226,39 +232,43 @@ Relationship Detection ====================== The vast majority of what automap accomplishes is the generation of -:func:`.relationship` structures based on foreign keys. The mechanism +:func:`_orm.relationship` structures based on foreign keys. The mechanism by which this works for many-to-one and one-to-many relationships is as follows: -1. A given :class:`.Table`, known to be mapped to a particular class, - is examined for :class:`.ForeignKeyConstraint` objects. +1. A given :class:`_schema.Table`, known to be mapped to a particular class, + is examined for :class:`_schema.ForeignKeyConstraint` objects. -2. From each :class:`.ForeignKeyConstraint`, the remote :class:`.Table` +2. From each :class:`_schema.ForeignKeyConstraint`, the remote + :class:`_schema.Table` object present is matched up to the class to which it is to be mapped, if any, else it is skipped. -3. As the :class:`.ForeignKeyConstraint` we are examining corresponds to a +3. As the :class:`_schema.ForeignKeyConstraint` + we are examining corresponds to a reference from the immediate mapped class, the relationship will be set up as a many-to-one referring to the referred class; a corresponding one-to-many backref will be created on the referred class referring to this class. -4. If any of the columns that are part of the :class:`.ForeignKeyConstraint` +4. If any of the columns that are part of the + :class:`_schema.ForeignKeyConstraint` are not nullable (e.g. ``nullable=False``), a - :paramref:`~.relationship.cascade` keyword argument + :paramref:`_orm.relationship.cascade` keyword argument of ``all, delete-orphan`` will be added to the keyword arguments to be passed to the relationship or backref. If the - :class:`.ForeignKeyConstraint` reports that - :paramref:`.ForeignKeyConstraint.ondelete` + :class:`_schema.ForeignKeyConstraint` reports that + :paramref:`_schema.ForeignKeyConstraint.ondelete` is set to ``CASCADE`` for a not null or ``SET NULL`` for a nullable - set of columns, the option :paramref:`~.relationship.passive_deletes` + set of columns, the option :paramref:`_orm.relationship.passive_deletes` flag is set to ``True`` in the set of relationship keyword arguments. Note that not all backends support reflection of ON DELETE. .. versionadded:: 1.0.0 - automap will detect non-nullable foreign key constraints when producing a one-to-many relationship and establish a default cascade of ``all, delete-orphan`` if so; additionally, - if the constraint specifies :paramref:`.ForeignKeyConstraint.ondelete` + if the constraint specifies + :paramref:`_schema.ForeignKeyConstraint.ondelete` of ``CASCADE`` for non-nullable or ``SET NULL`` for nullable columns, the ``passive_deletes=True`` option is also added. @@ -274,18 +284,20 @@ follows: 6. The classes are inspected for an existing mapped property matching these names. If one is detected on one side, but none on the other side, :class:`.AutomapBase` attempts to create a relationship on the missing side, - then uses the :paramref:`.relationship.back_populates` parameter in order to + then uses the :paramref:`_orm.relationship.back_populates` + parameter in order to point the new relationship to the other side. 7. In the usual case where no relationship is on either side, - :meth:`.AutomapBase.prepare` produces a :func:`.relationship` on the + :meth:`.AutomapBase.prepare` produces a :func:`_orm.relationship` on the "many-to-one" side and matches it to the other using the - :paramref:`.relationship.backref` parameter. + :paramref:`_orm.relationship.backref` parameter. -8. Production of the :func:`.relationship` and optionally the :func:`.backref` +8. Production of the :func:`_orm.relationship` and optionally the + :func:`.backref` is handed off to the :paramref:`.AutomapBase.prepare.generate_relationship` function, which can be supplied by the end-user in order to augment - the arguments passed to :func:`.relationship` or :func:`.backref` or to + the arguments passed to :func:`_orm.relationship` or :func:`.backref` or to make use of custom implementations of these functions. Custom Relationship Arguments @@ -298,8 +310,8 @@ the object, after augmenting the given keyword dictionary with our own arguments. Below is an illustration of how to send -:paramref:`.relationship.cascade` and -:paramref:`.relationship.passive_deletes` +:paramref:`_orm.relationship.cascade` and +:paramref:`_orm.relationship.passive_deletes` options along to all one-to-many relationships:: from sqlalchemy.ext.automap import generate_relationship @@ -331,20 +343,24 @@ Many-to-Many relationships those which contain a ``secondary`` argument. The process for producing these is as follows: -1. A given :class:`.Table` is examined for :class:`.ForeignKeyConstraint` +1. A given :class:`_schema.Table` is examined for + :class:`_schema.ForeignKeyConstraint` objects, before any mapped class has been assigned to it. -2. If the table contains two and exactly two :class:`.ForeignKeyConstraint` +2. If the table contains two and exactly two + :class:`_schema.ForeignKeyConstraint` objects, and all columns within this table are members of these two - :class:`.ForeignKeyConstraint` objects, the table is assumed to be a + :class:`_schema.ForeignKeyConstraint` objects, the table is assumed to be a "secondary" table, and will **not be mapped directly**. 3. The two (or one, for self-referential) external tables to which the - :class:`.Table` refers to are matched to the classes to which they will be + :class:`_schema.Table` + refers to are matched to the classes to which they will be mapped, if any. 4. If mapped classes for both sides are located, a many-to-many bi-directional - :func:`.relationship` / :func:`.backref` pair is created between the two + :func:`_orm.relationship` / :func:`.backref` + pair is created between the two classes. 5. The override logic for many-to-many works the same as that of one-to-many/ @@ -469,7 +485,8 @@ Using Automap with Explicit Declarations ======================================== As noted previously, automap has no dependency on reflection, and can make -use of any collection of :class:`.Table` objects within a :class:`.MetaData` +use of any collection of :class:`_schema.Table` objects within a +:class:`_schema.MetaData` collection. From this, it follows that automap can also be used generate missing relationships given an otherwise complete model that fully defines table metadata:: @@ -503,7 +520,7 @@ defines table metadata:: assert a1.user is u1 Above, given mostly complete ``User`` and ``Address`` mappings, the -:class:`.ForeignKey` which we defined on ``Address.user_id`` allowed a +:class:`_schema.ForeignKey` which we defined on ``Address.user_id`` allowed a bidirectional relationship pair ``Address.user`` and ``User.address_collection`` to be generated on the mapped classes. @@ -539,9 +556,9 @@ def classname_for_table(base, tablename, table): :param base: the :class:`.AutomapBase` class doing the prepare. - :param tablename: string name of the :class:`.Table`. + :param tablename: string name of the :class:`_schema.Table`. - :param table: the :class:`.Table` object itself. + :param table: the :class:`_schema.Table` object itself. :return: a string class name. @@ -549,7 +566,8 @@ def classname_for_table(base, tablename, table): In Python 2, the string used for the class name **must** be a non-Unicode object, e.g. a ``str()`` object. The ``.name`` attribute - of :class:`.Table` is typically a Python unicode subclass, so the + of :class:`_schema.Table` is typically a Python unicode subclass, + so the ``str()`` function should be applied to this name, after accounting for any non-ASCII characters. @@ -575,7 +593,7 @@ def name_for_scalar_relationship(base, local_cls, referred_cls, constraint): :param referred_cls: the class to be mapped on the referring side. - :param constraint: the :class:`.ForeignKeyConstraint` that is being + :param constraint: the :class:`_schema.ForeignKeyConstraint` that is being inspected to produce this relationship. """ @@ -603,7 +621,7 @@ def name_for_collection_relationship( :param referred_cls: the class to be mapped on the referring side. - :param constraint: the :class:`.ForeignKeyConstraint` that is being + :param constraint: the :class:`_schema.ForeignKeyConstraint` that is being inspected to produce this relationship. """ @@ -613,7 +631,8 @@ def name_for_collection_relationship( def generate_relationship( base, direction, return_fn, attrname, local_cls, referred_cls, **kw ): - r"""Generate a :func:`.relationship` or :func:`.backref` on behalf of two + r"""Generate a :func:`_orm.relationship` or :func:`.backref` + on behalf of two mapped classes. An alternate implementation of this function can be specified using the @@ -634,9 +653,10 @@ def generate_relationship( be one of :data:`.ONETOMANY`, :data:`.MANYTOONE`, :data:`.MANYTOMANY`. :param return_fn: the function that is used by default to create the - relationship. This will be either :func:`.relationship` or + relationship. This will be either :func:`_orm.relationship` or :func:`.backref`. The :func:`.backref` function's result will be used to - produce a new :func:`.relationship` in a second step, so it is critical + produce a new :func:`_orm.relationship` in a second step, + so it is critical that user-defined implementations correctly differentiate between the two functions, if a custom relationship function is being used. @@ -654,7 +674,8 @@ def generate_relationship( :param \**kw: all additional keyword arguments are passed along to the function. - :return: a :func:`.relationship` or :func:`.backref` construct, as dictated + :return: a :func:`_orm.relationship` or :func:`.backref` construct, + as dictated by the :paramref:`.generate_relationship.return_fn` parameter. """ @@ -710,19 +731,24 @@ class AutomapBase(object): name_for_collection_relationship=name_for_collection_relationship, generate_relationship=generate_relationship, ): - """Extract mapped classes and relationships from the :class:`.MetaData` and + """Extract mapped classes and relationships from the + :class:`_schema.MetaData` and perform mappings. - :param engine: an :class:`.Engine` or :class:`.Connection` with which + :param engine: an :class:`_engine.Engine` or + :class:`_engine.Connection` with which to perform schema reflection, if specified. If the :paramref:`.AutomapBase.prepare.reflect` argument is False, this object is not used. - :param reflect: if True, the :meth:`.MetaData.reflect` method is called - on the :class:`.MetaData` associated with this :class:`.AutomapBase`. - The :class:`.Engine` passed via + :param reflect: if True, the :meth:`_schema.MetaData.reflect` + method is called + on the :class:`_schema.MetaData` associated with this + :class:`.AutomapBase`. + The :class:`_engine.Engine` passed via :paramref:`.AutomapBase.prepare.engine` will be used to perform the - reflection if present; else, the :class:`.MetaData` should already be + reflection if present; else, the :class:`_schema.MetaData` + should already be bound to some engine else the operation will fail. :param classname_for_table: callable function which will be used to @@ -738,16 +764,18 @@ class AutomapBase(object): relationships. Defaults to :func:`.name_for_collection_relationship`. :param generate_relationship: callable function which will be used to - actually generate :func:`.relationship` and :func:`.backref` + actually generate :func:`_orm.relationship` and :func:`.backref` constructs. Defaults to :func:`.generate_relationship`. :param collection_class: the Python collection class that will be used - when a new :func:`.relationship` object is created that represents a + when a new :func:`_orm.relationship` + object is created that represents a collection. Defaults to ``list``. :param schema: When present in conjunction with the :paramref:`.AutomapBase.prepare.reflect` flag, is passed to - :meth:`.MetaData.reflect` to indicate the primary schema where tables + :meth:`_schema.MetaData.reflect` + to indicate the primary schema where tables should be reflected from. When omitted, the default schema in use by the database connection is used. diff --git a/lib/sqlalchemy/ext/baked.py b/lib/sqlalchemy/ext/baked.py index ff741db32c..839aae730f 100644 --- a/lib/sqlalchemy/ext/baked.py +++ b/lib/sqlalchemy/ext/baked.py @@ -147,7 +147,7 @@ class BakedQuery(object): :class:`.BakedQuery` object subsequent to the spoil step will be non-cached; the state of the :class:`.BakedQuery` up until this point will be pulled from the cache. If True, then the - entire :class:`.Query` object is built from scratch each + entire :class:`_query.Query` object is built from scratch each time, with all creational functions being called on each invocation. @@ -165,8 +165,8 @@ class BakedQuery(object): :class:`.Session`. This basically means we also will include the session's query_class, - as the actual :class:`.Query` object is part of what's cached - and needs to match the type of :class:`.Query` that a later + as the actual :class:`_query.Query` object is part of what's cached + and needs to match the type of :class:`_query.Query` that a later session will want to use. """ @@ -255,11 +255,11 @@ class BakedQuery(object): return context def to_query(self, query_or_session): - """Return the :class:`.Query` object for use as a subquery. + """Return the :class:`_query.Query` object for use as a subquery. This method should be used within the lambda callable being used to generate a step of an enclosing :class:`.BakedQuery`. The - parameter should normally be the :class:`.Query` object that + parameter should normally be the :class:`_query.Query` object that is passed to the lambda:: sub_bq = self.bakery(lambda s: s.query(User.name)) @@ -282,7 +282,7 @@ class BakedQuery(object): Address.id, sub_bq.to_query(q).scalar_subquery()) ) - :param query_or_session: a :class:`.Query` object or a class + :param query_or_session: a :class:`_query.Query` object or a class :class:`.Session` object, that is assumed to be within the context of an enclosing :class:`.BakedQuery` callable. @@ -394,13 +394,14 @@ class Result(object): """Add a criteria function that will be applied post-cache. This adds a function that will be run against the - :class:`.Query` object after it is retrieved from the + :class:`_query.Query` object after it is retrieved from the cache. Functions here can be used to alter the query in ways that **do not affect the SQL output**, such as execution options and shard identifiers (when using a shard-enabled query object) .. warning:: :meth:`.Result.with_post_criteria` functions are applied - to the :class:`.Query` object **after** the query's SQL statement + to the :class:`_query.Query` + object **after** the query's SQL statement object has been retrieved from the cache. Any operations here which intend to modify the SQL should ensure that :meth:`.BakedQuery.spoil` was called first. @@ -449,7 +450,7 @@ class Result(object): def count(self): """return the 'count'. - Equivalent to :meth:`.Query.count`. + Equivalent to :meth:`_query.Query.count`. Note this uses a subquery to ensure an accurate count regardless of the structure of the original statement. @@ -467,7 +468,7 @@ class Result(object): if no rows present. If multiple rows are returned, raises MultipleResultsFound. - Equivalent to :meth:`.Query.scalar`. + Equivalent to :meth:`_query.Query.scalar`. .. versionadded:: 1.1.6 @@ -483,7 +484,7 @@ class Result(object): def first(self): """Return the first row. - Equivalent to :meth:`.Query.first`. + Equivalent to :meth:`_query.Query.first`. """ bq = self.bq.with_criteria(lambda q: q.slice(0, 1)) @@ -500,7 +501,7 @@ class Result(object): def one(self): """Return exactly one result or raise an exception. - Equivalent to :meth:`.Query.one`. + Equivalent to :meth:`_query.Query.one`. """ try: @@ -521,7 +522,7 @@ class Result(object): """Return one or zero results, or raise an exception for multiple rows. - Equivalent to :meth:`.Query.one_or_none`. + Equivalent to :meth:`_query.Query.one_or_none`. .. versionadded:: 1.0.9 @@ -541,7 +542,7 @@ class Result(object): def all(self): """Return all rows. - Equivalent to :meth:`.Query.all`. + Equivalent to :meth:`_query.Query.all`. """ return list(self) @@ -549,7 +550,7 @@ class Result(object): def get(self, ident): """Retrieve an object based on identity. - Equivalent to :meth:`.Query.get`. + Equivalent to :meth:`_query.Query.get`. """ @@ -646,7 +647,7 @@ def unbake_lazy_loaders(): This method now raises NotImplementedError() as the "baked" implementation is the only lazy load implementation. The - :paramref:`.relationship.bake_queries` flag may be used to disable + :paramref:`_orm.relationship.bake_queries` flag may be used to disable the caching of queries on a per-relationship basis. """ diff --git a/lib/sqlalchemy/ext/compiler.py b/lib/sqlalchemy/ext/compiler.py index b8b6f8dc0d..32975a9495 100644 --- a/lib/sqlalchemy/ext/compiler.py +++ b/lib/sqlalchemy/ext/compiler.py @@ -101,7 +101,7 @@ Produces:: The above ``InsertFromSelect`` construct is only an example, this actual functionality is already available using the - :meth:`.Insert.from_select` method. + :meth:`_expression.Insert.from_select` method. .. note:: @@ -140,7 +140,8 @@ supported. Enabling Autocommit on a Construct ================================== -Recall from the section :ref:`autocommit` that the :class:`.Engine`, when +Recall from the section :ref:`autocommit` that the :class:`_engine.Engine`, +when asked to execute a construct in the absence of a user-defined transaction, detects if the given construct represents DML or DDL, that is, a data modification or data definition statement, which requires (or may require, @@ -165,7 +166,7 @@ is a "frozen" dictionary which supplies a generative ``union()`` method):: More succinctly, if the construct is truly similar to an INSERT, UPDATE, or DELETE, :class:`.UpdateBase` can be used, which already is a subclass -of :class:`.Executable`, :class:`.ClauseElement` and includes the +of :class:`.Executable`, :class:`_expression.ClauseElement` and includes the ``autocommit`` flag:: from sqlalchemy.sql.expression import UpdateBase @@ -405,7 +406,7 @@ from ..sql import visitors def compiles(class_, *specs): """Register a function as a compiler for a - given :class:`.ClauseElement` type.""" + given :class:`_expression.ClauseElement` type.""" def decorate(fn): # get an existing @compiles handler @@ -455,7 +456,7 @@ def compiles(class_, *specs): def deregister(class_): """Remove all custom compilers associated with a given - :class:`.ClauseElement` type.""" + :class:`_expression.ClauseElement` type.""" if hasattr(class_, "_compiler_dispatcher"): # regenerate default _compiler_dispatch diff --git a/lib/sqlalchemy/ext/declarative/api.py b/lib/sqlalchemy/ext/declarative/api.py index 825c1d3f35..65d100bc75 100644 --- a/lib/sqlalchemy/ext/declarative/api.py +++ b/lib/sqlalchemy/ext/declarative/api.py @@ -82,10 +82,11 @@ class DeclarativeMeta(type): def synonym_for(name, map_column=False): - """Decorator that produces an :func:`.orm.synonym` attribute in conjunction + """Decorator that produces an :func:`_orm.synonym` + attribute in conjunction with a Python descriptor. - The function being decorated is passed to :func:`.orm.synonym` as the + The function being decorated is passed to :func:`_orm.synonym` as the :paramref:`.orm.synonym.descriptor` parameter:: class MyClass(Base): @@ -107,7 +108,7 @@ def synonym_for(name, map_column=False): :ref:`synonyms` - Overview of synonyms - :func:`.orm.synonym` - the mapper-level function + :func:`_orm.synonym` - the mapper-level function :ref:`mapper_hybrids` - The Hybrid Attribute extension provides an updated approach to augmenting attribute behavior more flexibly than @@ -323,7 +324,7 @@ def declarative_base( :param class_registry: optional dictionary that will serve as the registry of class names-> mapped classes when string names - are used to identify classes inside of :func:`.relationship` + are used to identify classes inside of :func:`_orm.relationship` and others. Allows two or more declarative base classes to share the same registry of class names for simplified inter-base relationships. @@ -505,7 +506,7 @@ class AbstractConcreteBase(ConcreteBase): .. seealso:: - :func:`.orm.configure_mappers` + :func:`_orm.configure_mappers` Example:: @@ -656,17 +657,17 @@ class DeferredReflection(object): a deferred reflection step. Normally, declarative can be used with reflection by - setting a :class:`.Table` object using autoload=True + setting a :class:`_schema.Table` object using autoload=True as the ``__table__`` attribute on a declarative class. - The caveat is that the :class:`.Table` must be fully + The caveat is that the :class:`_schema.Table` must be fully reflected, or at the very least have a primary key column, at the point at which a normal declarative mapping is - constructed, meaning the :class:`.Engine` must be available + constructed, meaning the :class:`_engine.Engine` must be available at class declaration time. The :class:`.DeferredReflection` mixin moves the construction of mappers to be at a later point, after a specific - method is called which first reflects all :class:`.Table` + method is called which first reflects all :class:`_schema.Table` objects created so far. Classes can define it as such:: from sqlalchemy.ext.declarative import declarative_base @@ -720,7 +721,7 @@ class DeferredReflection(object): @classmethod def prepare(cls, engine): - """Reflect all :class:`.Table` objects for all current + """Reflect all :class:`_schema.Table` objects for all current :class:`.DeferredReflection` subclasses""" to_map = _DeferredMapperConfig.classes_for_base(cls) diff --git a/lib/sqlalchemy/ext/declarative/clsregistry.py b/lib/sqlalchemy/ext/declarative/clsregistry.py index 219c4ba2e4..20de3c6364 100644 --- a/lib/sqlalchemy/ext/declarative/clsregistry.py +++ b/lib/sqlalchemy/ext/declarative/clsregistry.py @@ -7,7 +7,7 @@ """Routines to handle the string class registry used by declarative. This system allows specification of classes and expressions used in -:func:`.relationship` using strings. +:func:`_orm.relationship` using strings. """ import weakref diff --git a/lib/sqlalchemy/ext/horizontal_shard.py b/lib/sqlalchemy/ext/horizontal_shard.py index 56553c83d3..cfb2fd6873 100644 --- a/lib/sqlalchemy/ext/horizontal_shard.py +++ b/lib/sqlalchemy/ext/horizontal_shard.py @@ -197,7 +197,7 @@ class ShardedSession(Session): possible identity tokens (e.g. shard ids). .. versionchanged:: 1.4 Moved :meth:`.Session._identity_lookup` from - the :class:`.Query` object to the :class:`.Session`. + the :class:`_query.Query` object to the :class:`.Session`. """ diff --git a/lib/sqlalchemy/ext/hybrid.py b/lib/sqlalchemy/ext/hybrid.py index 7c523edbd3..9f73b5d31b 100644 --- a/lib/sqlalchemy/ext/hybrid.py +++ b/lib/sqlalchemy/ext/hybrid.py @@ -75,7 +75,8 @@ returns a new SQL expression:: FROM interval WHERE interval."end" - interval.start > :param_1 -ORM methods such as :meth:`~.Query.filter_by` generally use ``getattr()`` to +ORM methods such as :meth:`_query.Query.filter_by` +generally use ``getattr()`` to locate attributes, so can also be used with hybrid attributes:: >>> print(Session().query(Interval).filter_by(length=5)) @@ -213,10 +214,10 @@ Allowing Bulk ORM Update ------------------------ A hybrid can define a custom "UPDATE" handler for when using the -:meth:`.Query.update` method, allowing the hybrid to be used in the +:meth:`_query.Query.update` method, allowing the hybrid to be used in the SET clause of the update. -Normally, when using a hybrid with :meth:`.Query.update`, the SQL +Normally, when using a hybrid with :meth:`_query.Query.update`, the SQL expression is used as the column that's the target of the SET. If our ``Interval`` class had a hybrid ``start_point`` that linked to ``Interval.start``, this could be substituted directly:: @@ -225,7 +226,7 @@ expression is used as the column that's the target of the SET. If our However, when using a composite hybrid like ``Interval.length``, this hybrid represents more than one column. We can set up a handler that will -accommodate a value passed to :meth:`.Query.update` which can affect +accommodate a value passed to :meth:`_query.Query.update` which can affect this, using the :meth:`.hybrid_property.update_expression` decorator. A handler that works similarly to our setter would be:: @@ -628,9 +629,11 @@ measurement, currencies and encrypted passwords. Building Transformers ---------------------- -A *transformer* is an object which can receive a :class:`.Query` object and -return a new one. The :class:`.Query` object includes a method -:meth:`.with_transformation` that returns a new :class:`.Query` transformed by +A *transformer* is an object which can receive a :class:`_query.Query` +object and +return a new one. The :class:`_query.Query` object includes a method +:meth:`.with_transformation` that returns a new :class:`_query.Query` +transformed by the given function. We can combine this with the :class:`.Comparator` class to produce one type @@ -665,10 +668,11 @@ simple:: return self.parent.parent For the expression, things are not so clear. We'd need to construct a -:class:`.Query` where we :meth:`~.Query.join` twice along ``Node.parent`` to +:class:`_query.Query` where we :meth:`_query.Query.join` twice along ``Node. +parent`` to get to the ``grandparent``. We can instead return a transforming callable that we'll combine with the :class:`.Comparator` class to receive any -:class:`.Query` object, and return a new one that's joined to the +:class:`_query.Query` object, and return a new one that's joined to the ``Node.parent`` attribute and filtered based on the given criterion:: from sqlalchemy.ext.hybrid import Comparator @@ -704,9 +708,10 @@ transforming callable, which then runs the given comparison operation in a particular context. Such as, in the example above, the ``operate`` method is called, given the :attr:`.Operators.eq` callable as well as the right side of the comparison ``Node(id=5)``. A function ``transform`` is then returned which -will transform a :class:`.Query` first to join to ``Node.parent``, then to +will transform a :class:`_query.Query` first to join to ``Node.parent``, +then to compare ``parent_alias`` using :attr:`.Operators.eq` against the left and right -sides, passing into :class:`.Query.filter`: +sides, passing into :class:`_query.Query.filter`: .. sourcecode:: pycon+sql @@ -783,7 +788,7 @@ HYBRID_METHOD = util.symbol("HYBRID_METHOD") .. seealso:: - :attr:`.Mapper.all_orm_attributes` + :attr:`_orm.Mapper.all_orm_attributes` """ @@ -796,7 +801,7 @@ HYBRID_PROPERTY = util.symbol("HYBRID_PROPERTY") .. seealso:: - :attr:`.Mapper.all_orm_attributes` + :attr:`_orm.Mapper.all_orm_attributes` """ diff --git a/lib/sqlalchemy/ext/indexable.py b/lib/sqlalchemy/ext/indexable.py index 6eb7e11850..f58acceebf 100644 --- a/lib/sqlalchemy/ext/indexable.py +++ b/lib/sqlalchemy/ext/indexable.py @@ -6,20 +6,20 @@ # the MIT License: http://www.opensource.org/licenses/mit-license.php """Define attributes on ORM-mapped classes that have "index" attributes for -columns with :class:`~.types.Indexable` types. +columns with :class:`_types.Indexable` types. "index" means the attribute is associated with an element of an -:class:`~.types.Indexable` column with the predefined index to access it. -The :class:`~.types.Indexable` types include types such as -:class:`~.types.ARRAY`, :class:`~.types.JSON` and -:class:`~.postgresql.HSTORE`. +:class:`_types.Indexable` column with the predefined index to access it. +The :class:`_types.Indexable` types include types such as +:class:`_types.ARRAY`, :class:`_types.JSON` and +:class:`_postgresql.HSTORE`. The :mod:`~sqlalchemy.ext.indexable` extension provides -:class:`~.schema.Column`-like interface for any element of an -:class:`~.types.Indexable` typed column. In simple cases, it can be -treated as a :class:`~.schema.Column` - mapped attribute. +:class:`_schema.Column`-like interface for any element of an +:class:`_types.Indexable` typed column. In simple cases, it can be +treated as a :class:`_schema.Column` - mapped attribute. .. versionadded:: 1.1 @@ -192,7 +192,7 @@ where we want to also include automatic casting plus ``astext()``:: return expr.astext.cast(self.cast_type) The above subclass can be used with the PostgreSQL-specific -version of :class:`.postgresql.JSON`:: +version of :class:`_postgresql.JSON`:: from sqlalchemy import Column, Integer from sqlalchemy.ext.declarative import declarative_base @@ -234,7 +234,7 @@ __all__ = ["index_property"] class index_property(hybrid_property): # noqa """A property generator. The generated property describes an object - attribute that corresponds to an :class:`~.types.Indexable` + attribute that corresponds to an :class:`_types.Indexable` column. .. versionadded:: 1.1 diff --git a/lib/sqlalchemy/ext/mutable.py b/lib/sqlalchemy/ext/mutable.py index 5523fe75db..32a22a4950 100644 --- a/lib/sqlalchemy/ext/mutable.py +++ b/lib/sqlalchemy/ext/mutable.py @@ -39,7 +39,7 @@ JSON strings before being persisted:: The usage of ``json`` is only for the purposes of example. The :mod:`sqlalchemy.ext.mutable` extension can be used with any type whose target Python type may be mutable, including -:class:`.PickleType`, :class:`.postgresql.ARRAY`, etc. +:class:`.PickleType`, :class:`_postgresql.ARRAY`, etc. When using the :mod:`sqlalchemy.ext.mutable` extension, the value itself tracks all parents which reference it. Below, we illustrate a simple @@ -270,7 +270,7 @@ and to also route attribute set events via ``__setattr__`` to the return not self.__eq__(other) The :class:`.MutableComposite` class uses a Python metaclass to automatically -establish listeners for any usage of :func:`.orm.composite` that specifies our +establish listeners for any usage of :func:`_orm.composite` that specifies our ``Point`` type. Below, when ``Point`` is mapped to the ``Vertex`` class, listeners are established which will route change events from ``Point`` objects to each of the ``Vertex.start`` and ``Vertex.end`` attributes:: diff --git a/lib/sqlalchemy/ext/orderinglist.py b/lib/sqlalchemy/ext/orderinglist.py index ac430c6b85..7b6b779977 100644 --- a/lib/sqlalchemy/ext/orderinglist.py +++ b/lib/sqlalchemy/ext/orderinglist.py @@ -11,7 +11,7 @@ elements. :author: Jason Kirtland ``orderinglist`` is a helper for mutable ordered relationships. It will -intercept list operations performed on a :func:`.relationship`-managed +intercept list operations performed on a :func:`_orm.relationship`-managed collection and automatically synchronize changes in list position onto a target scalar attribute. @@ -86,7 +86,7 @@ With the above mapping the ``Bullet.position`` attribute is managed:: The :class:`.OrderingList` construct only works with **changes** to a collection, and not the initial load from the database, and requires that the list be sorted when loaded. Therefore, be sure to specify ``order_by`` on the -:func:`.relationship` against the target ordering attribute, so that the +:func:`_orm.relationship` against the target ordering attribute, so that the ordering is correct when first loaded. .. warning:: @@ -212,7 +212,7 @@ class OrderingList(list): The :class:`.OrderingList` object is normally set up using the :func:`.ordering_list` factory function, used in conjunction with - the :func:`.relationship` function. + the :func:`_orm.relationship` function. """ diff --git a/lib/sqlalchemy/inspection.py b/lib/sqlalchemy/inspection.py index 5013d1c4d1..270f189bef 100644 --- a/lib/sqlalchemy/inspection.py +++ b/lib/sqlalchemy/inspection.py @@ -5,23 +5,24 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""The inspection module provides the :func:`.inspect` function, +"""The inspection module provides the :func:`_sa.inspect` function, which delivers runtime information about a wide variety of SQLAlchemy objects, both within the Core as well as the ORM. -The :func:`.inspect` function is the entry point to SQLAlchemy's +The :func:`_sa.inspect` function is the entry point to SQLAlchemy's public API for viewing the configuration and construction of in-memory objects. Depending on the type of object -passed to :func:`.inspect`, the return value will either be +passed to :func:`_sa.inspect`, the return value will either be a related object which provides a known interface, or in many cases it will return the object itself. -The rationale for :func:`.inspect` is twofold. One is that +The rationale for :func:`_sa.inspect` is twofold. One is that it replaces the need to be aware of a large variety of "information -getting" functions in SQLAlchemy, such as :meth:`.Inspector.from_engine`, -:func:`.orm.attributes.instance_state`, :func:`.orm.class_mapper`, -and others. The other is that the return value of :func:`.inspect` +getting" functions in SQLAlchemy, such as +:meth:`_reflection.Inspector.from_engine`, +:func:`.orm.attributes.instance_state`, :func:`_orm.class_mapper`, +and others. The other is that the return value of :func:`_sa.inspect` is guaranteed to obey a documented API, thus allowing third party tools which build on top of SQLAlchemy configurations to be constructed in a forwards-compatible way. @@ -40,11 +41,11 @@ def inspect(subject, raiseerr=True): The returned value in some cases may be the same object as the one given, such as if a - :class:`.Mapper` object is passed. In other + :class:`_orm.Mapper` object is passed. In other cases, it will be an instance of the registered inspection type for the given object, such as - if an :class:`.engine.Engine` is passed, an - :class:`.Inspector` object is returned. + if an :class:`_engine.Engine` is passed, an + :class:`_reflection.Inspector` object is returned. :param subject: the subject to be inspected. :param raiseerr: When ``True``, if the given subject diff --git a/lib/sqlalchemy/log.py b/lib/sqlalchemy/log.py index a6d6cb4f1a..42c8a2c290 100644 --- a/lib/sqlalchemy/log.py +++ b/lib/sqlalchemy/log.py @@ -12,8 +12,8 @@ Control of logging for SA can be performed from the regular python logging module. The regular dotted module namespace is used, starting at 'sqlalchemy'. For class-level logging, the class name is appended. -The "echo" keyword parameter, available on SQLA :class:`.Engine` -and :class:`.Pool` objects, corresponds to a logger specific to that +The "echo" keyword parameter, available on SQLA :class:`_engine.Engine` +and :class:`_pool.Pool` objects, corresponds to a logger specific to that instance only. """ diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py index 53118c5735..24945ef52b 100644 --- a/lib/sqlalchemy/orm/__init__.py +++ b/lib/sqlalchemy/orm/__init__.py @@ -153,7 +153,8 @@ def deferred(*columns, **kw): not load unless accessed. :param \*columns: columns to be mapped. This is typically a single - :class:`.Column` object, however a collection is supported in order + :class:`_schema.Column` object, + however a collection is supported in order to support multiple columns mapped under the same attribute. :param raiseload: boolean, if True, indicates an exception should be raised diff --git a/lib/sqlalchemy/orm/attributes.py b/lib/sqlalchemy/orm/attributes.py index 82979b188d..ec706d4d8a 100644 --- a/lib/sqlalchemy/orm/attributes.py +++ b/lib/sqlalchemy/orm/attributes.py @@ -72,9 +72,9 @@ class QueryableAttribute( :class:`.MapperProperty` - :attr:`.Mapper.all_orm_descriptors` + :attr:`_orm.Mapper.all_orm_descriptors` - :attr:`.Mapper.attrs` + :attr:`_orm.Mapper.attrs` """ is_attribute = True @@ -134,12 +134,13 @@ class QueryableAttribute( * If the attribute is a column-mapped property, i.e. :class:`.ColumnProperty`, which is mapped directly - to a schema-level :class:`.Column` object, this attribute + to a schema-level :class:`_schema.Column` object, this attribute will return the :attr:`.SchemaItem.info` dictionary associated - with the core-level :class:`.Column` object. + with the core-level :class:`_schema.Column` object. * If the attribute is a :class:`.ColumnProperty` but is mapped to - any other kind of SQL expression other than a :class:`.Column`, + any other kind of SQL expression other than a + :class:`_schema.Column`, the attribute will refer to the :attr:`.MapperProperty.info` dictionary associated directly with the :class:`.ColumnProperty`, assuming the SQL expression itself does not have its own ``.info`` @@ -154,7 +155,7 @@ class QueryableAttribute( * To access the :attr:`.MapperProperty.info` dictionary of the :class:`.MapperProperty` unconditionally, including for a :class:`.ColumnProperty` that's associated directly with a - :class:`.schema.Column`, the attribute can be referred to using + :class:`_schema.Column`, the attribute can be referred to using :attr:`.QueryableAttribute.property` attribute, as ``MyClass.someattribute.property.info``. @@ -171,7 +172,7 @@ class QueryableAttribute( def parent(self): """Return an inspection instance representing the parent. - This will be either an instance of :class:`.Mapper` + This will be either an instance of :class:`_orm.Mapper` or :class:`.AliasedInsp`, depending upon the nature of the parent entity which this attribute is associated with. @@ -1608,7 +1609,7 @@ class History(util.namedtuple("History", ["added", "unchanged", "deleted"])): attribute. The easiest way to get a :class:`.History` object for a particular - attribute on an object is to use the :func:`.inspect` function:: + attribute on an object is to use the :func:`_sa.inspect` function:: from sqlalchemy import inspect diff --git a/lib/sqlalchemy/orm/base.py b/lib/sqlalchemy/orm/base.py index 6df8acf1ee..07809282b5 100644 --- a/lib/sqlalchemy/orm/base.py +++ b/lib/sqlalchemy/orm/base.py @@ -166,7 +166,7 @@ EXT_SKIP = util.symbol("EXT_SKIP") ONETOMANY = util.symbol( "ONETOMANY", - """Indicates the one-to-many direction for a :func:`.relationship`. + """Indicates the one-to-many direction for a :func:`_orm.relationship`. This symbol is typically used by the internals but may be exposed within certain API features. @@ -176,7 +176,7 @@ ONETOMANY = util.symbol( MANYTOONE = util.symbol( "MANYTOONE", - """Indicates the many-to-one direction for a :func:`.relationship`. + """Indicates the many-to-one direction for a :func:`_orm.relationship`. This symbol is typically used by the internals but may be exposed within certain API features. @@ -186,7 +186,7 @@ MANYTOONE = util.symbol( MANYTOMANY = util.symbol( "MANYTOMANY", - """Indicates the many-to-many direction for a :func:`.relationship`. + """Indicates the many-to-many direction for a :func:`_orm.relationship`. This symbol is typically used by the internals but may be exposed within certain API features. @@ -298,7 +298,7 @@ def object_state(instance): Raises :class:`sqlalchemy.orm.exc.UnmappedInstanceError` if no mapping is configured. - Equivalent functionality is available via the :func:`.inspect` + Equivalent functionality is available via the :func:`_sa.inspect` function as:: inspect(instance) @@ -336,7 +336,7 @@ def _class_to_mapper(class_or_mapper): def _mapper_or_none(entity): - """Return the :class:`.Mapper` for the given class or None if the + """Return the :class:`_orm.Mapper` for the given class or None if the class is not mapped. """ @@ -349,7 +349,7 @@ def _mapper_or_none(entity): def _is_mapped_class(entity): """Return True if the given object is a mapped class, - :class:`.Mapper`, or :class:`.AliasedClass`. + :class:`_orm.Mapper`, or :class:`.AliasedClass`. """ insp = inspection.inspect(entity, False) @@ -422,14 +422,14 @@ def _inspect_mapped_class(class_, configure=False): def class_mapper(class_, configure=True): - """Given a class, return the primary :class:`.Mapper` associated + """Given a class, return the primary :class:`_orm.Mapper` associated with the key. Raises :exc:`.UnmappedClassError` if no mapping is configured on the given class, or :exc:`.ArgumentError` if a non-class object is passed. - Equivalent functionality is available via the :func:`.inspect` + Equivalent functionality is available via the :func:`_sa.inspect` function as:: inspect(some_mapped_class) @@ -451,7 +451,7 @@ def class_mapper(class_, configure=True): class InspectionAttr(object): """A base class applied to all ORM objects that can be returned - by the :func:`.inspect` function. + by the :func:`_sa.inspect` function. The attributes defined here allow the usage of simple boolean checks to test basic facts about the object returned. @@ -467,7 +467,8 @@ class InspectionAttr(object): __slots__ = () is_selectable = False - """Return True if this object is an instance of :class:`.Selectable`.""" + """Return True if this object is an instance of """ + """:class:`expression.Selectable`.""" is_aliased_class = False """True if this object is an instance of :class:`.AliasedClass`.""" @@ -476,7 +477,7 @@ class InspectionAttr(object): """True if this object is an instance of :class:`.InstanceState`.""" is_mapper = False - """True if this object is an instance of :class:`.Mapper`.""" + """True if this object is an instance of :class:`_orm.Mapper`.""" is_property = False """True if this object is an instance of :class:`.MapperProperty`.""" @@ -493,7 +494,7 @@ class InspectionAttr(object): .. seealso:: - :attr:`.Mapper.all_orm_descriptors` + :attr:`_orm.Mapper.all_orm_descriptors` """ @@ -505,7 +506,8 @@ class InspectionAttr(object): """ is_clause_element = False - """True if this object is an instance of :class:`.ClauseElement`.""" + """True if this object is an instance of """ + """:class:`_expression.ClauseElement`.""" extension_type = NOT_EXTENSION """The extension type, if any. @@ -538,7 +540,8 @@ class InspectionAttrInfo(InspectionAttr): The dictionary is generated when first accessed. Alternatively, it can be specified as a constructor argument to the - :func:`.column_property`, :func:`.relationship`, or :func:`.composite` + :func:`.column_property`, :func:`_orm.relationship`, or + :func:`.composite` functions. .. versionchanged:: 1.0.0 :attr:`.MapperProperty.info` is also diff --git a/lib/sqlalchemy/orm/descriptor_props.py b/lib/sqlalchemy/orm/descriptor_props.py index 3bc009da8b..7fff131016 100644 --- a/lib/sqlalchemy/orm/descriptor_props.py +++ b/lib/sqlalchemy/orm/descriptor_props.py @@ -550,14 +550,18 @@ class SynonymProperty(DescriptorProperty): :param map_column: **For classical mappings and mappings against an existing Table object only**. if ``True``, the :func:`.synonym` - construct will locate the :class:`.Column` object upon the mapped + construct will locate the :class:`_schema.Column` + object upon the mapped table that would normally be associated with the attribute name of this synonym, and produce a new :class:`.ColumnProperty` that instead - maps this :class:`.Column` to the alternate name given as the "name" + maps this :class:`_schema.Column` + to the alternate name given as the "name" argument of the synonym; in this way, the usual step of redefining - the mapping of the :class:`.Column` to be under a different name is + the mapping of the :class:`_schema.Column` + to be under a different name is unnecessary. This is usually intended to be used when a - :class:`.Column` is to be replaced with an attribute that also uses a + :class:`_schema.Column` + is to be replaced with an attribute that also uses a descriptor, that is, in conjunction with the :paramref:`.synonym.descriptor` parameter:: diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py index a41ea49e8e..f08ef085bd 100644 --- a/lib/sqlalchemy/orm/events.py +++ b/lib/sqlalchemy/orm/events.py @@ -143,8 +143,8 @@ class InstanceEvents(event.Events): * mapped classes * unmapped superclasses of mapped or to-be-mapped classes (using the ``propagate=True`` flag) - * :class:`.Mapper` objects - * the :class:`.Mapper` class itself and the :func:`.mapper` + * :class:`_orm.Mapper` objects + * the :class:`_orm.Mapper` class itself and the :func:`.mapper` function indicate listening for all mappers. Instance events are closely related to mapper events, but @@ -369,15 +369,15 @@ class InstanceEvents(event.Events): The :meth:`.InstanceEvents.load` event is also available in a - class-method decorator format called :func:`.orm.reconstructor`. + class-method decorator format called :func:`_orm.reconstructor`. :param target: the mapped instance. If the event is configured with ``raw=True``, this will instead be the :class:`.InstanceState` state-management object associated with the instance. :param context: the :class:`.QueryContext` corresponding to the - current :class:`.Query` in progress. This argument may be - ``None`` if the load does not correspond to a :class:`.Query`, + current :class:`_query.Query` in progress. This argument may be + ``None`` if the load does not correspond to a :class:`_query.Query`, such as during :meth:`.Session.merge`. .. seealso:: @@ -413,7 +413,7 @@ class InstanceEvents(event.Events): instead be the :class:`.InstanceState` state-management object associated with the instance. :param context: the :class:`.QueryContext` corresponding to the - current :class:`.Query` in progress. + current :class:`_query.Query` in progress. :param attrs: sequence of attribute names which were populated, or None if all column-mapped, non-deferred attributes were populated. @@ -617,8 +617,8 @@ class MapperEvents(event.Events): * mapped classes * unmapped superclasses of mapped or to-be-mapped classes (using the ``propagate=True`` flag) - * :class:`.Mapper` objects - * the :class:`.Mapper` class itself and the :func:`.mapper` + * :class:`_orm.Mapper` objects + * the :class:`_orm.Mapper` class itself and the :func:`.mapper` function indicate listening for all mappers. Mapper events provide hooks into critical sections of the @@ -747,7 +747,7 @@ class MapperEvents(event.Events): This event is the earliest phase of mapper construction. Most attributes of the mapper are not yet initialized. - This listener can either be applied to the :class:`.Mapper` + This listener can either be applied to the :class:`_orm.Mapper` class overall, or to any un-mapped class which serves as a base for classes that will be mapped (using the ``propagate=True`` flag):: @@ -757,7 +757,7 @@ class MapperEvents(event.Events): def on_new_class(mapper, cls_): " ... " - :param mapper: the :class:`.Mapper` which is the target + :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param class\_: the mapped class. @@ -817,9 +817,9 @@ class MapperEvents(event.Events): The :meth:`.MapperEvents.mapper_configured` event is invoked for each mapper that is encountered when the - :func:`.orm.configure_mappers` function proceeds through the current + :func:`_orm.configure_mappers` function proceeds through the current list of not-yet-configured mappers. - :func:`.orm.configure_mappers` is typically invoked + :func:`_orm.configure_mappers` is typically invoked automatically as mappings are first used, as well as each time new mappers have been made available and new mapper use is detected. @@ -850,7 +850,7 @@ class MapperEvents(event.Events): on a specific mapper basis, which don't require that "backref" configurations are necessarily ready yet. - :param mapper: the :class:`.Mapper` which is the target + :param mapper: the :class:`_orm.Mapper` which is the target of this event. :param class\_: the mapped class. @@ -869,14 +869,14 @@ class MapperEvents(event.Events): """Called before a series of mappers have been configured. The :meth:`.MapperEvents.before_configured` event is invoked - each time the :func:`.orm.configure_mappers` function is + each time the :func:`_orm.configure_mappers` function is invoked, before the function has done any of its work. - :func:`.orm.configure_mappers` is typically invoked + :func:`_orm.configure_mappers` is typically invoked automatically as mappings are first used, as well as each time new mappers have been made available and new mapper use is detected. - This event can **only** be applied to the :class:`.Mapper` class + This event can **only** be applied to the :class:`_orm.Mapper` class or :func:`.mapper` function, and not to individual mappings or mapped classes. It is only invoked for all mappings as a whole:: @@ -894,7 +894,7 @@ class MapperEvents(event.Events): Theoretically this event is called once per application, but is actually called any time new mappers - are to be affected by a :func:`.orm.configure_mappers` + are to be affected by a :func:`_orm.configure_mappers` call. If new mappings are constructed after existing ones have already been used, this event will likely be called again. To ensure that a particular event is only called once and no further, the @@ -924,9 +924,9 @@ class MapperEvents(event.Events): """Called after a series of mappers have been configured. The :meth:`.MapperEvents.after_configured` event is invoked - each time the :func:`.orm.configure_mappers` function is + each time the :func:`_orm.configure_mappers` function is invoked, after the function has completed its work. - :func:`.orm.configure_mappers` is typically invoked + :func:`_orm.configure_mappers` is typically invoked automatically as mappings are first used, as well as each time new mappers have been made available and new mapper use is detected. @@ -939,7 +939,7 @@ class MapperEvents(event.Events): Also contrast to :meth:`.MapperEvents.before_configured`, which is invoked before the series of mappers has been configured. - This event can **only** be applied to the :class:`.Mapper` class + This event can **only** be applied to the :class:`_orm.Mapper` class or :func:`.mapper` function, and not to individual mappings or mapped classes. It is only invoked for all mappings as a whole:: @@ -951,7 +951,7 @@ class MapperEvents(event.Events): Theoretically this event is called once per application, but is actually called any time new mappers - have been affected by a :func:`.orm.configure_mappers` + have been affected by a :func:`_orm.configure_mappers` call. If new mappings are constructed after existing ones have already been used, this event will likely be called again. To ensure that a particular event is only called once and no further, the @@ -996,14 +996,14 @@ class MapperEvents(event.Events): Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given - :class:`.Connection`. **Please read fully** the notes + :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. - :param mapper: the :class:`.Mapper` which is the target + :param mapper: the :class:`_orm.Mapper` which is the target of this event. - :param connection: the :class:`.Connection` being used to + :param connection: the :class:`_engine.Connection` being used to emit INSERT statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. @@ -1042,14 +1042,14 @@ class MapperEvents(event.Events): Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given - :class:`.Connection`. **Please read fully** the notes + :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. - :param mapper: the :class:`.Mapper` which is the target + :param mapper: the :class:`_orm.Mapper` which is the target of this event. - :param connection: the :class:`.Connection` being used to + :param connection: the :class:`_engine.Connection` being used to emit INSERT statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. @@ -1107,14 +1107,14 @@ class MapperEvents(event.Events): Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given - :class:`.Connection`. **Please read fully** the notes + :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. - :param mapper: the :class:`.Mapper` which is the target + :param mapper: the :class:`_orm.Mapper` which is the target of this event. - :param connection: the :class:`.Connection` being used to + :param connection: the :class:`_engine.Connection` being used to emit UPDATE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. @@ -1171,14 +1171,14 @@ class MapperEvents(event.Events): Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given - :class:`.Connection`. **Please read fully** the notes + :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. - :param mapper: the :class:`.Mapper` which is the target + :param mapper: the :class:`_orm.Mapper` which is the target of this event. - :param connection: the :class:`.Connection` being used to + :param connection: the :class:`_engine.Connection` being used to emit UPDATE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. @@ -1211,14 +1211,14 @@ class MapperEvents(event.Events): Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given - :class:`.Connection`. **Please read fully** the notes + :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. - :param mapper: the :class:`.Mapper` which is the target + :param mapper: the :class:`_orm.Mapper` which is the target of this event. - :param connection: the :class:`.Connection` being used to + :param connection: the :class:`_engine.Connection` being used to emit DELETE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. @@ -1251,14 +1251,14 @@ class MapperEvents(event.Events): Mapper-level flush events only allow **very limited operations**, on attributes local to the row being operated upon only, as well as allowing any SQL to be emitted on the given - :class:`.Connection`. **Please read fully** the notes + :class:`_engine.Connection`. **Please read fully** the notes at :ref:`session_persistence_mapper` for guidelines on using these methods; generally, the :meth:`.SessionEvents.before_flush` method should be preferred for general on-flush changes. - :param mapper: the :class:`.Mapper` which is the target + :param mapper: the :class:`_orm.Mapper` which is the target of this event. - :param connection: the :class:`.Connection` being used to + :param connection: the :class:`_engine.Connection` being used to emit DELETE statements for this instance. This provides a handle into the current transaction on the target database specific to this instance. @@ -1666,7 +1666,7 @@ class SessionEvents(event.Events): :param session: The target :class:`.Session`. :param transaction: The :class:`.SessionTransaction`. - :param connection: The :class:`~.engine.Connection` object + :param connection: The :class:`_engine.Connection` object which will be used for SQL statements. .. seealso:: @@ -1734,16 +1734,17 @@ class SessionEvents(event.Events): def after_bulk_update(self, update_context): """Execute after a bulk update operation to the session. - This is called as a result of the :meth:`.Query.update` method. + This is called as a result of the :meth:`_query.Query.update` method. :param update_context: an "update context" object which contains details about the update, including these attributes: * ``session`` - the :class:`.Session` involved - * ``query`` -the :class:`.Query` object that this update operation + * ``query`` -the :class:`_query.Query` + object that this update operation was called upon. * ``values`` The "values" dictionary that was passed to - :meth:`.Query.update`. + :meth:`_query.Query.update`. * ``context`` The :class:`.QueryContext` object, corresponding to the invocation of an ORM query. * ``result`` the :class:`.ResultProxy` returned as a result of the @@ -1770,13 +1771,14 @@ class SessionEvents(event.Events): def after_bulk_delete(self, delete_context): """Execute after a bulk delete operation to the session. - This is called as a result of the :meth:`.Query.delete` method. + This is called as a result of the :meth:`_query.Query.delete` method. :param delete_context: a "delete context" object which contains details about the update, including these attributes: * ``session`` - the :class:`.Session` involved - * ``query`` -the :class:`.Query` object that this update operation + * ``query`` -the :class:`_query.Query` + object that this update operation was called upon. * ``context`` The :class:`.QueryContext` object, corresponding to the invocation of an ORM query. @@ -2098,7 +2100,7 @@ class AttributeEvents(event.Events): replaced unconditionally, even if this requires firing off database loads. Note that ``active_history`` can also be set directly via :func:`.column_property` and - :func:`.relationship`. + :func:`_orm.relationship`. :param propagate=False: When True, the listener function will be established not just for the class attribute given, but @@ -2338,10 +2340,12 @@ class AttributeEvents(event.Events): Python's usual behavior of raising ``AttributeError``. The event here can be used to customize what value is actually returned, with the assumption that the event listener would be mirroring - a default generator that is configured on the Core :class:`.Column` + a default generator that is configured on the Core + :class:`_schema.Column` object as well. - Since a default generator on a :class:`.Column` might also produce + Since a default generator on a :class:`_schema.Column` + might also produce a changing value such as a timestamp, the :meth:`.AttributeEvents.init_scalar` event handler can also be used to **set** the newly returned value, so @@ -2375,7 +2379,7 @@ class AttributeEvents(event.Events): * By setting the value ``SOME_CONSTANT`` in the given ``dict_``, we indicate that this value is to be persisted to the database. This supersedes the use of ``SOME_CONSTANT`` in the default generator - for the :class:`.Column`. The ``active_column_defaults.py`` + for the :class:`_schema.Column`. The ``active_column_defaults.py`` example given at :ref:`examples_instrumentation` illustrates using the same approach for a changing default, e.g. a timestamp generator. In this particular example, it is not strictly @@ -2394,7 +2398,7 @@ class AttributeEvents(event.Events): In the above example, the attribute set event :meth:`.AttributeEvents.set` as well as the related validation feature - provided by :obj:`.orm.validates` is **not** invoked when we apply our + provided by :obj:`_orm.validates` is **not** invoked when we apply our value to the given ``dict_``. To have these events to invoke in response to our newly generated value, apply the value to the given object as a normal attribute set operation:: @@ -2467,7 +2471,7 @@ class AttributeEvents(event.Events): be the :class:`.InstanceState` object. :param collection: the new collection. This will always be generated from what was specified as - :paramref:`.relationship.collection_class`, and will always + :paramref:`_orm.relationship.collection_class`, and will always be empty. :param collection_adapter: the :class:`.CollectionAdapter` that will mediate internal access to the collection. @@ -2537,10 +2541,11 @@ class AttributeEvents(event.Events): class QueryEvents(event.Events): - """Represent events within the construction of a :class:`.Query` object. + """Represent events within the construction of a :class:`_query.Query` + object. The events here are intended to be used with an as-yet-unreleased - inspection system for :class:`.Query`. Some very basic operations + inspection system for :class:`_query.Query`. Some very basic operations are possible now, however the inspection system is intended to allow complex query manipulations to be automated. @@ -2552,8 +2557,9 @@ class QueryEvents(event.Events): _dispatch_target = Query def before_compile(self, query): - """Receive the :class:`.Query` object before it is composed into a - core :class:`.Select` object. + """Receive the :class:`_query.Query` + object before it is composed into a + core :class:`_expression.Select` object. This event is intended to allow changes to the query given:: @@ -2570,7 +2576,8 @@ class QueryEvents(event.Events): The :meth:`.QueryEvents.before_compile` event by default will disallow "baked" queries from caching a query, if the event - hook returns a new :class:`.Query` object. This affects both direct + hook returns a new :class:`_query.Query` object. + This affects both direct use of the baked query extension as well as its operation within lazy loaders and eager loaders for relationships. In order to re-establish the query being cached, apply the event adding the @@ -2592,7 +2599,7 @@ class QueryEvents(event.Events): .. versionadded:: 1.3.11 - added the "bake_ok" flag to the :meth:`.QueryEvents.before_compile` event and disallowed caching via the "baked" extension from occurring for event handlers that - return a new :class:`.Query` object if this flag is not set. + return a new :class:`_query.Query` object if this flag is not set. .. seealso:: @@ -2605,13 +2612,13 @@ class QueryEvents(event.Events): """ def before_compile_update(self, query, update_context): - """Allow modifications to the :class:`.Query` object within - :meth:`.Query.update`. + """Allow modifications to the :class:`_query.Query` object within + :meth:`_query.Query.update`. Like the :meth:`.QueryEvents.before_compile` event, if the event - is to be used to alter the :class:`.Query` object, it should + is to be used to alter the :class:`_query.Query` object, it should be configured with ``retval=True``, and the modified - :class:`.Query` object returned, as in :: + :class:`_query.Query` object returned, as in :: @event.listens_for(Query, "before_compile_update", retval=True) def no_deleted(query, update_context): @@ -2626,7 +2633,7 @@ class QueryEvents(event.Events): The ``.values`` dictionary of the "update context" object can also be modified in place as illustrated above. - :param query: a :class:`.Query` instance; this is also + :param query: a :class:`_query.Query` instance; this is also the ``.query`` attribute of the given "update context" object. @@ -2634,7 +2641,8 @@ class QueryEvents(event.Events): the same kind of object as described in :paramref:`.QueryEvents.after_bulk_update.update_context`. The object has a ``.values`` attribute in an UPDATE context which is - the dictionary of parameters passed to :meth:`.Query.update`. This + the dictionary of parameters passed to :meth:`_query.Query.update`. + This dictionary can be modified to alter the VALUES clause of the resulting UPDATE statement. @@ -2650,12 +2658,12 @@ class QueryEvents(event.Events): """ def before_compile_delete(self, query, delete_context): - """Allow modifications to the :class:`.Query` object within - :meth:`.Query.delete`. + """Allow modifications to the :class:`_query.Query` object within + :meth:`_query.Query.delete`. Like the :meth:`.QueryEvents.before_compile` event, this event should be configured with ``retval=True``, and the modified - :class:`.Query` object returned, as in :: + :class:`_query.Query` object returned, as in :: @event.listens_for(Query, "before_compile_delete", retval=True) def no_deleted(query, delete_context): @@ -2665,7 +2673,7 @@ class QueryEvents(event.Events): query = query.filter(entity.deleted == False) return query - :param query: a :class:`.Query` instance; this is also + :param query: a :class:`_query.Query` instance; this is also the ``.query`` attribute of the given "delete context" object. diff --git a/lib/sqlalchemy/orm/exc.py b/lib/sqlalchemy/orm/exc.py index 0c25654876..b04b844b3a 100644 --- a/lib/sqlalchemy/orm/exc.py +++ b/lib/sqlalchemy/orm/exc.py @@ -111,7 +111,7 @@ class ObjectDeletedError(sa_exc.InvalidRequestError): row corresponding to an object's known primary key identity. A refresh operation proceeds when an expired attribute is - accessed on an object, or when :meth:`.Query.get` is + accessed on an object, or when :meth:`_query.Query.get` is used to retrieve an object which is, upon retrieval, detected as expired. A SELECT is emitted for the target row based on primary key; if no row is returned, this diff --git a/lib/sqlalchemy/orm/interfaces.py b/lib/sqlalchemy/orm/interfaces.py index 57c192a5d3..6127243578 100644 --- a/lib/sqlalchemy/orm/interfaces.py +++ b/lib/sqlalchemy/orm/interfaces.py @@ -65,12 +65,12 @@ __all__ = ( class MapperProperty( HasCacheKey, _MappedAttribute, InspectionAttr, util.MemoizedSlots ): - """Represent a particular class attribute mapped by :class:`.Mapper`. + """Represent a particular class attribute mapped by :class:`_orm.Mapper`. The most common occurrences of :class:`.MapperProperty` are the - mapped :class:`.Column`, which is represented in a mapping as + mapped :class:`_schema.Column`, which is represented in a mapping as an instance of :class:`.ColumnProperty`, - and a reference to another class produced by :func:`.relationship`, + and a reference to another class produced by :func:`_orm.relationship`, represented in the mapping as an instance of :class:`.RelationshipProperty`. @@ -110,7 +110,8 @@ class MapperProperty( The dictionary is generated when first accessed. Alternatively, it can be specified as a constructor argument to the - :func:`.column_property`, :func:`.relationship`, or :func:`.composite` + :func:`.column_property`, :func:`_orm.relationship`, or + :func:`.composite` functions. .. versionchanged:: 1.0.0 :attr:`.MapperProperty.info` is also @@ -389,7 +390,8 @@ class PropComparator(operators.ColumnOperators): """Receive a SQL expression that represents a value in the SET clause of an UPDATE statement. - Return a tuple that can be passed to a :class:`.Update` construct. + Return a tuple that can be passed to a :class:`_expression.Update` + construct. """ @@ -655,7 +657,7 @@ class MapperOption(object): """ def process_query(self, query): - """Apply a modification to the given :class:`.Query`.""" + """Apply a modification to the given :class:`_query.Query`.""" def process_query_conditionally(self, query): """same as process_query(), except that this option may not @@ -673,14 +675,15 @@ class MapperOption(object): def _generate_path_cache_key(self, path): """Used by the "baked lazy loader" to see if this option can be cached. - The "baked lazy loader" refers to the :class:`.Query` that is + The "baked lazy loader" refers to the :class:`_query.Query` that is produced during a lazy load operation for a mapped relationship. It does not yet apply to the "lazy" load operation for deferred or expired column attributes, however this may change in the future. This loader generates SQL for a query only once and attempts to cache it; from that point on, if the SQL has been cached it will no longer - run the :meth:`.Query.options` method of the :class:`.Query`. The + run the :meth:`_query.Query.options` method of the + :class:`_query.Query`. The :class:`.MapperOption` object that wishes to participate within a lazy load operation therefore needs to tell the baked loader that it either needs to forego this caching, or that it needs to include the state of @@ -694,7 +697,7 @@ class MapperOption(object): not cache the SQL when this :class:`.MapperOption` is present. This is the safest option and ensures both that the option is invoked every time, and also that the cache isn't filled up with - an unlimited number of :class:`.Query` objects for an unlimited + an unlimited number of :class:`_query.Query` objects for an unlimited number of :class:`.MapperOption` objects. .. versionchanged:: 1.2.8 the default return value of @@ -702,7 +705,8 @@ class MapperOption(object): was ``None`` indicating "safe to cache, don't include as part of the cache key" - To enable caching of :class:`.Query` objects within lazy loaders, a + To enable caching of :class:`_query.Query` objects within lazy loaders + , a given :class:`.MapperOption` that returns a cache key must return a key that uniquely identifies the complete state of this option, which will match any other :class:`.MapperOption` that itself retains the @@ -712,7 +716,7 @@ class MapperOption(object): If the :class:`.MapperOption` does not apply to the given path and would not affect query results on such a path, it should return None, - indicating the :class:`.Query` is safe to cache for this given + indicating the :class:`_query.Query` is safe to cache for this given loader path and that this :class:`.MapperOption` need not be part of the cache key. diff --git a/lib/sqlalchemy/orm/loading.py b/lib/sqlalchemy/orm/loading.py index b7ef96e1a4..5ef2f10eca 100644 --- a/lib/sqlalchemy/orm/loading.py +++ b/lib/sqlalchemy/orm/loading.py @@ -106,7 +106,7 @@ def instances(query, cursor, context): @util.preload_module("sqlalchemy.orm.query") def merge_result(query, iterator, load=True): - """Merge a result into this :class:`.Query` object's Session.""" + """Merge a result into this :class:`_query.Query` object's Session.""" querylib = util.preloaded.orm_query session = query.session diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py index 3e4c3a5d59..31f005769b 100644 --- a/lib/sqlalchemy/orm/mapper.py +++ b/lib/sqlalchemy/orm/mapper.py @@ -74,9 +74,9 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """Define the correlation of class attributes to database table columns. - The :class:`.Mapper` object is instantiated using the + The :class:`_orm.Mapper` object is instantiated using the :func:`~sqlalchemy.orm.mapper` function. For information - about instantiating new :class:`.Mapper` objects, see + about instantiating new :class:`_orm.Mapper` objects, see that function's documentation. @@ -89,8 +89,8 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): makes usage of :func:`.mapper` behind the scenes. Given a particular class known to be mapped by the ORM, - the :class:`.Mapper` which maintains it can be acquired - using the :func:`.inspect` function:: + the :class:`_orm.Mapper` which maintains it can be acquired + using the :func:`_sa.inspect` function:: from sqlalchemy import inspect @@ -113,7 +113,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): "and will be removed in a future release. The functionality " "of non primary mappers is now better suited using the " ":class:`.AliasedClass` construct, which can also be used " - "as the target of a :func:`.relationship` in 1.3.", + "as the target of a :func:`_orm.relationship` in 1.3.", ), ) def __init__( @@ -147,7 +147,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): legacy_is_orphan=False, _compiled_cache_size=100, ): - r"""Return a new :class:`~.Mapper` object. + r"""Return a new :class:`_orm.Mapper` object. This function is typically used behind the scenes via the Declarative extension. When using Declarative, @@ -196,21 +196,22 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): this argument is automatically passed as the declared class itself. - :param local_table: The :class:`.Table` or other selectable + :param local_table: The :class:`_schema.Table` or other selectable to which the class is mapped. May be ``None`` if this mapper inherits from another mapper using single-table inheritance. When using Declarative, this argument is automatically passed by the extension, based on what is configured via the ``__table__`` argument or via the - :class:`.Table` produced as a result of the ``__tablename__`` - and :class:`.Column` arguments present. + :class:`_schema.Table` + produced as a result of the ``__tablename__`` + and :class:`_schema.Column` arguments present. :param always_refresh: If True, all query operations for this mapped class will overwrite all data within object instances that already exist within the session, erasing any in-memory changes with whatever information was loaded from the database. Usage of this flag is highly discouraged; as an alternative, see the method - :meth:`.Query.populate_existing`. + :meth:`_query.Query.populate_existing`. :param allow_partial_pks: Defaults to True. Indicates that a composite primary key with some NULL values should be considered as @@ -229,7 +230,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): in between individual row persistence operations. :param column_prefix: A string which will be prepended - to the mapped attribute name when :class:`.Column` + to the mapped attribute name when :class:`_schema.Column` objects are automatically assigned as attributes to the mapped class. Does not affect explicitly specified column-based properties. @@ -283,8 +284,9 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): See :ref:`include_exclude_cols` for an example. - :param inherits: A mapped class or the corresponding :class:`.Mapper` - of one indicating a superclass to which this :class:`.Mapper` + :param inherits: A mapped class or the corresponding + :class:`_orm.Mapper` + of one indicating a superclass to which this :class:`_orm.Mapper` should *inherit* from. The mapped class here must be a subclass of the other mapper's class. When using Declarative, this argument is passed automatically as a result of the natural class @@ -300,7 +302,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): between the two tables. :param inherit_foreign_keys: When ``inherit_condition`` is used and - the columns present are missing a :class:`.ForeignKey` + the columns present are missing a :class:`_schema.ForeignKey` configuration, this parameter can be used to specify which columns are "foreign". In most cases can be left as ``None``. @@ -320,14 +322,15 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): See the change note and example at :ref:`legacy_is_orphan_addition` for more detail on this change. - :param non_primary: Specify that this :class:`.Mapper` is in addition + :param non_primary: Specify that this :class:`_orm.Mapper` + is in addition to the "primary" mapper, that is, the one used for persistence. - The :class:`.Mapper` created here may be used for ad-hoc + The :class:`_orm.Mapper` created here may be used for ad-hoc mapping of the class to an alternate selectable, for loading only. - :paramref:`.Mapper.non_primary` is not an often used option, but - is useful in some specific :func:`.relationship` cases. + :paramref:`_orm.Mapper.non_primary` is not an often used option, but + is useful in some specific :func:`_orm.relationship` cases. .. seealso:: @@ -362,7 +365,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): .. seealso:: :ref:`passive_deletes` - description of similar feature as - used with :func:`.relationship` + used with :func:`_orm.relationship` :paramref:`.mapper.passive_updates` - supporting ON UPDATE CASCADE for joined-table inheritance mappers @@ -385,7 +388,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): .. seealso:: :ref:`passive_updates` - description of a similar feature as - used with :func:`.relationship` + used with :func:`_orm.relationship` :paramref:`.mapper.passive_deletes` - supporting ON DELETE CASCADE for joined-table inheritance mappers @@ -415,8 +418,8 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): SQL expression used to determine the target class for an incoming row, when inheriting classes are present. - This value is commonly a :class:`.Column` object that's - present in the mapped :class:`.Table`:: + This value is commonly a :class:`_schema.Column` object that's + present in the mapped :class:`_schema.Table`:: class Employee(Base): __tablename__ = 'employee' @@ -471,7 +474,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): When setting ``polymorphic_on`` to reference an attribute or expression that's not present in the - locally mapped :class:`.Table`, yet the value + locally mapped :class:`_schema.Table`, yet the value of the discriminator should be persisted to the database, the value of the discriminator is not automatically set on new @@ -513,20 +516,22 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): :param properties: A dictionary mapping the string names of object attributes to :class:`.MapperProperty` instances, which define the - persistence behavior of that attribute. Note that :class:`.Column` + persistence behavior of that attribute. Note that + :class:`_schema.Column` objects present in - the mapped :class:`.Table` are automatically placed into + the mapped :class:`_schema.Table` are automatically placed into ``ColumnProperty`` instances upon mapping, unless overridden. When using Declarative, this argument is passed automatically, based on all those :class:`.MapperProperty` instances declared in the declared class body. - :param primary_key: A list of :class:`.Column` objects which define + :param primary_key: A list of :class:`_schema.Column` + objects which define the primary key to be used against this mapper's selectable unit. This is normally simply the primary key of the ``local_table``, but can be overridden here. - :param version_id_col: A :class:`.Column` + :param version_id_col: A :class:`_schema.Column` that will be used to keep a running version id of rows in the table. This is used to detect concurrent updates or the presence of stale data in a flush. The methodology is to @@ -721,34 +726,38 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): return self.class_ local_table = None - """The :class:`.Selectable` which this :class:`.Mapper` manages. + """The :class:`expression.Selectable` which this :class:`_orm.Mapper` + manages. - Typically is an instance of :class:`.Table` or :class:`.Alias`. + Typically is an instance of :class:`_schema.Table` or + :class:`_expression.Alias`. May also be ``None``. The "local" table is the - selectable that the :class:`.Mapper` is directly responsible for + selectable that the :class:`_orm.Mapper` is directly responsible for managing from an attribute access and flush perspective. For non-inheriting mappers, the local table is the same as the "mapped" table. For joined-table inheritance mappers, local_table will be the particular sub-table of the overall "join" which - this :class:`.Mapper` represents. If this mapper is a + this :class:`_orm.Mapper` represents. If this mapper is a single-table inheriting mapper, local_table will be ``None``. .. seealso:: - :attr:`~.Mapper.persist_selectable`. + :attr:`_orm.Mapper.persist_selectable`. """ persist_selectable = None - """The :class:`.Selectable` to which this :class:`.Mapper` is mapped. + """The :class:`expression.Selectable` to which this :class:`_orm.Mapper` + is mapped. - Typically an instance of :class:`.Table`, :class:`.Join`, or - :class:`.Alias`. + Typically an instance of :class:`_schema.Table`, :class:`_expression.Join` + , or + :class:`_expression.Alias`. - The :attr:`.Mapper.persist_selectable` is separate from - :attr:`.Mapper.selectable` in that the former represents columns + The :attr:`_orm.Mapper.persist_selectable` is separate from + :attr:`_orm.Mapper.selectable` in that the former represents columns that are mapped on this class or its superclasses, whereas the latter may be a "polymorphic" selectable that contains additional columns which are in fact mapped on subclasses only. @@ -756,21 +765,21 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): "persist selectable" is the "thing the mapper writes to" and "selectable" is the "thing the mapper selects from". - :attr:`.Mapper.persist_selectable` is also separate from - :attr:`.Mapper.local_table`, which represents the set of columns that + :attr:`_orm.Mapper.persist_selectable` is also separate from + :attr:`_orm.Mapper.local_table`, which represents the set of columns that are locally mapped on this class directly. .. seealso:: - :attr:`~.Mapper.selectable`. + :attr:`_orm.Mapper.selectable`. - :attr:`~.Mapper.local_table`. + :attr:`_orm.Mapper.local_table`. """ inherits = None - """References the :class:`.Mapper` which this :class:`.Mapper` + """References the :class:`_orm.Mapper` which this :class:`_orm.Mapper` inherits from, if any. This is a *read only* attribute determined during mapper construction. @@ -779,7 +788,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ configured = None - """Represent ``True`` if this :class:`.Mapper` has been configured. + """Represent ``True`` if this :class:`_orm.Mapper` has been configured. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. @@ -791,7 +800,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ concrete = None - """Represent ``True`` if this :class:`.Mapper` is a concrete + """Represent ``True`` if this :class:`_orm.Mapper` is a concrete inheritance mapper. This is a *read only* attribute determined during mapper construction. @@ -800,11 +809,13 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ tables = None - """An iterable containing the collection of :class:`.Table` objects - which this :class:`.Mapper` is aware of. + """An iterable containing the collection of :class:`_schema.Table` objects + which this :class:`_orm.Mapper` is aware of. - If the mapper is mapped to a :class:`.Join`, or an :class:`.Alias` - representing a :class:`.Select`, the individual :class:`.Table` + If the mapper is mapped to a :class:`_expression.Join`, or an + :class:`_expression.Alias` + representing a :class:`_expression.Select`, the individual + :class:`_schema.Table` objects that comprise the full construct will be represented here. This is a *read only* attribute determined during mapper construction. @@ -813,20 +824,23 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ primary_key = None - """An iterable containing the collection of :class:`.Column` objects + """An iterable containing the collection of :class:`_schema.Column` + objects which comprise the 'primary key' of the mapped table, from the - perspective of this :class:`.Mapper`. + perspective of this :class:`_orm.Mapper`. - This list is against the selectable in :attr:`~.Mapper.persist_selectable`. + This list is against the selectable in + :attr:`_orm.Mapper.persist_selectable`. In the case of inheriting mappers, some columns may be managed by a - superclass mapper. For example, in the case of a :class:`.Join`, the + superclass mapper. For example, in the case of a + :class:`_expression.Join`, the primary key is determined by all of the primary key columns across all - tables referenced by the :class:`.Join`. + tables referenced by the :class:`_expression.Join`. The list is also not necessarily the same as the primary key column - collection associated with the underlying tables; the :class:`.Mapper` + collection associated with the underlying tables; the :class:`_orm.Mapper` features a ``primary_key`` argument that can override what the - :class:`.Mapper` considers as primary key columns. + :class:`_orm.Mapper` considers as primary key columns. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. @@ -834,7 +848,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ class_ = None - """The Python class which this :class:`.Mapper` maps. + """The Python class which this :class:`_orm.Mapper` maps. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. @@ -843,7 +857,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): class_manager = None """The :class:`.ClassManager` which maintains event listeners - and class-bound descriptors for this :class:`.Mapper`. + and class-bound descriptors for this :class:`_orm.Mapper`. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. @@ -851,10 +865,10 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ single = None - """Represent ``True`` if this :class:`.Mapper` is a single table + """Represent ``True`` if this :class:`_orm.Mapper` is a single table inheritance mapper. - :attr:`~.Mapper.local_table` will be ``None`` if this flag is set. + :attr:`_orm.Mapper.local_table` will be ``None`` if this flag is set. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. @@ -862,7 +876,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ non_primary = None - """Represent ``True`` if this :class:`.Mapper` is a "non-primary" + """Represent ``True`` if this :class:`_orm.Mapper` is a "non-primary" mapper, e.g. a mapper that is used only to select rows but not for persistence management. @@ -872,11 +886,11 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ polymorphic_on = None - """The :class:`.Column` or SQL expression specified as the + """The :class:`_schema.Column` or SQL expression specified as the ``polymorphic_on`` argument - for this :class:`.Mapper`, within an inheritance scenario. + for this :class:`_orm.Mapper`, within an inheritance scenario. - This attribute is normally a :class:`.Column` instance but + This attribute is normally a :class:`_schema.Column` instance but may also be an expression, such as one derived from :func:`.cast`. @@ -887,10 +901,10 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): polymorphic_map = None """A mapping of "polymorphic identity" identifiers mapped to - :class:`.Mapper` instances, within an inheritance scenario. + :class:`_orm.Mapper` instances, within an inheritance scenario. The identifiers can be of any type which is comparable to the - type of column represented by :attr:`~.Mapper.polymorphic_on`. + type of column represented by :attr:`_orm.Mapper.polymorphic_on`. An inheritance chain of mappers will all reference the same polymorphic map object. The object is used to correlate incoming @@ -903,11 +917,11 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): polymorphic_identity = None """Represent an identifier which is matched against the - :attr:`~.Mapper.polymorphic_on` column during result row loading. + :attr:`_orm.Mapper.polymorphic_on` column during result row loading. Used only with inheritance, this object can be of any type which is comparable to the type of column represented by - :attr:`~.Mapper.polymorphic_on`. + :attr:`_orm.Mapper.polymorphic_on`. This is a *read only* attribute determined during mapper construction. Behavior is undefined if directly modified. @@ -915,11 +929,11 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ base_mapper = None - """The base-most :class:`.Mapper` in an inheritance chain. + """The base-most :class:`_orm.Mapper` in an inheritance chain. In a non-inheriting scenario, this attribute will always be this - :class:`.Mapper`. In an inheritance scenario, it references - the :class:`.Mapper` which is parent to all other :class:`.Mapper` + :class:`_orm.Mapper`. In an inheritance scenario, it references + the :class:`_orm.Mapper` which is parent to all other :class:`_orm.Mapper` objects in the inheritance chain. This is a *read only* attribute determined during mapper construction. @@ -928,14 +942,15 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ columns = None - """A collection of :class:`.Column` or other scalar expression - objects maintained by this :class:`.Mapper`. + """A collection of :class:`_schema.Column` or other scalar expression + objects maintained by this :class:`_orm.Mapper`. The collection behaves the same as that of the ``c`` attribute on - any :class:`.Table` object, except that only those columns included in + any :class:`_schema.Table` object, + except that only those columns included in this mapping are present, and are keyed based on the attribute name defined in the mapping, not necessarily the ``key`` attribute of the - :class:`.Column` itself. Additionally, scalar expressions mapped + :class:`_schema.Column` itself. Additionally, scalar expressions mapped by :func:`.column_property` are also present here. This is a *read only* attribute determined during mapper construction. @@ -945,7 +960,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): validators = None """An immutable dictionary of attributes which have been decorated - using the :func:`~.orm.validates` decorator. + using the :func:`_orm.validates` decorator. The dictionary contains string attribute names as keys mapped to the actual validation method. @@ -953,7 +968,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): """ c = None - """A synonym for :attr:`~.Mapper.columns`.""" + """A synonym for :attr:`_orm.Mapper.columns`.""" @property @util.deprecated("1.3", "Use .persist_selectable") @@ -1139,8 +1154,8 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): ) def _set_concrete_base(self, mapper): - """Set the given :class:`.Mapper` as the 'inherits' for this - :class:`.Mapper`, assuming this :class:`.Mapper` is concrete + """Set the given :class:`_orm.Mapper` as the 'inherits' for this + :class:`_orm.Mapper`, assuming this :class:`_orm.Mapper` is concrete and does not already have an inherits.""" assert self.concrete @@ -1778,7 +1793,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): @util.preload_module("sqlalchemy.orm.descriptor_props") def _property_from_column(self, key, prop): """generate/update a :class:`.ColumnProperty` given a - :class:`.Column` object. """ + :class:`_schema.Column` object. """ descriptor_props = util.preloaded.orm_descriptor_props # we were passed a Column or a list of Columns; # generate a properties.ColumnProperty @@ -1979,7 +1994,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): ) def get_property_by_column(self, column): - """Given a :class:`.Column` object, return the + """Given a :class:`_schema.Column` object, return the :class:`.MapperProperty` which maps this column.""" return self._columntoproperty[column] @@ -2083,7 +2098,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): ) with_polymorphic_mappers = _with_polymorphic_mappers - """The list of :class:`.Mapper` objects included in the + """The list of :class:`_orm.Mapper` objects included in the default "polymorphic" query. """ @@ -2201,8 +2216,8 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): @property def selectable(self): - """The :func:`~.sql.expression.select` construct this - :class:`.Mapper` selects from by default. + """The :func:`_expression.select` construct this + :class:`_orm.Mapper` selects from by default. Normally, this is equivalent to :attr:`.persist_selectable`, unless the ``with_polymorphic`` feature is in use, in which case the @@ -2281,14 +2296,14 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): column. The namespace object can also be iterated, which would yield each :class:`.MapperProperty`. - :class:`.Mapper` has several pre-filtered views + :class:`_orm.Mapper` has several pre-filtered views of this attribute which limit the types of properties returned, including :attr:`.synonyms`, :attr:`.column_attrs`, :attr:`.relationships`, and :attr:`.composites`. .. warning:: - The :attr:`.Mapper.attrs` accessor namespace is an + The :attr:`_orm.Mapper.attrs` accessor namespace is an instance of :class:`.OrderedProperties`. This is a dictionary-like object which includes a small number of named methods such as :meth:`.OrderedProperties.items` @@ -2299,7 +2314,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): .. seealso:: - :attr:`.Mapper.all_orm_descriptors` + :attr:`_orm.Mapper.all_orm_descriptors` """ if Mapper._new_mappers: @@ -2330,11 +2345,12 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): :attr:`.QueryableAttribute.property` attribute refers to the :class:`.MapperProperty` property, which is what you get when referring to the collection of mapped properties via - :attr:`.Mapper.attrs`. + :attr:`_orm.Mapper.attrs`. .. warning:: - The :attr:`.Mapper.all_orm_descriptors` accessor namespace is an + The :attr:`_orm.Mapper.all_orm_descriptors` + accessor namespace is an instance of :class:`.OrderedProperties`. This is a dictionary-like object which includes a small number of named methods such as :meth:`.OrderedProperties.items` @@ -2346,7 +2362,7 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): .. seealso:: - :attr:`.Mapper.attrs` + :attr:`_orm.Mapper.attrs` """ return util.ImmutableProperties( @@ -2357,11 +2373,12 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): @util.preload_module("sqlalchemy.orm.descriptor_props") def synonyms(self): """Return a namespace of all :class:`.SynonymProperty` - properties maintained by this :class:`.Mapper`. + properties maintained by this :class:`_orm.Mapper`. .. seealso:: - :attr:`.Mapper.attrs` - namespace of all :class:`.MapperProperty` + :attr:`_orm.Mapper.attrs` - namespace of all + :class:`.MapperProperty` objects. """ @@ -2372,11 +2389,12 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): @HasMemoized.memoized_attribute def column_attrs(self): """Return a namespace of all :class:`.ColumnProperty` - properties maintained by this :class:`.Mapper`. + properties maintained by this :class:`_orm.Mapper`. .. seealso:: - :attr:`.Mapper.attrs` - namespace of all :class:`.MapperProperty` + :attr:`_orm.Mapper.attrs` - namespace of all + :class:`.MapperProperty` objects. """ @@ -2386,11 +2404,11 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): @HasMemoized.memoized_attribute def relationships(self): """A namespace of all :class:`.RelationshipProperty` properties - maintained by this :class:`.Mapper`. + maintained by this :class:`_orm.Mapper`. .. warning:: - the :attr:`.Mapper.relationships` accessor namespace is an + the :attr:`_orm.Mapper.relationships` accessor namespace is an instance of :class:`.OrderedProperties`. This is a dictionary-like object which includes a small number of named methods such as :meth:`.OrderedProperties.items` @@ -2402,7 +2420,8 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): .. seealso:: - :attr:`.Mapper.attrs` - namespace of all :class:`.MapperProperty` + :attr:`_orm.Mapper.attrs` - namespace of all + :class:`.MapperProperty` objects. """ @@ -2414,11 +2433,12 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): @util.preload_module("sqlalchemy.orm.descriptor_props") def composites(self): """Return a namespace of all :class:`.CompositeProperty` - properties maintained by this :class:`.Mapper`. + properties maintained by this :class:`_orm.Mapper`. .. seealso:: - :attr:`.Mapper.attrs` - namespace of all :class:`.MapperProperty` + :attr:`_orm.Mapper.attrs` - namespace of all + :class:`.MapperProperty` objects. """ @@ -2638,9 +2658,10 @@ class Mapper(sql_base.HasCacheKey, InspectionAttr): item from the identity map. :param row: A :class:`.Row` instance. The columns which are - mapped by this :class:`.Mapper` should be locatable in the row, - preferably via the :class:`.Column` object directly (as is the case - when a :func:`~.sql.expression.select` construct is executed), or + mapped by this :class:`_orm.Mapper` should be locatable in the row, + preferably via the :class:`_schema.Column` + object directly (as is the case + when a :func:`_expression.select` construct is executed), or via string names of the form ``_``. """ @@ -3157,13 +3178,13 @@ def configure_mappers(): proceeds. * :meth:`.MapperEvents.mapper_configured` - called as each individual - :class:`.Mapper` is configured within the process; will include all + :class:`_orm.Mapper` is configured within the process; will include all mapper state except for backrefs set up by other mappers that are still to be configured. * :meth:`.MapperEvents.after_configured` - called once after :func:`.configure_mappers` is complete; at this stage, all - :class:`.Mapper` objects that are known to SQLAlchemy will be fully + :class:`_orm.Mapper` objects that are known to SQLAlchemy will be fully configured. Note that the calling application may still have other mappings that haven't been produced yet, such as if they are in modules as yet unimported. diff --git a/lib/sqlalchemy/orm/persistence.py b/lib/sqlalchemy/orm/persistence.py index 1460ae2089..87bc8ea1d6 100644 --- a/lib/sqlalchemy/orm/persistence.py +++ b/lib/sqlalchemy/orm/persistence.py @@ -6,7 +6,7 @@ # the MIT License: http://www.opensource.org/licenses/mit-license.php """private module containing functions used to emit INSERT, UPDATE -and DELETE statements on behalf of a :class:`.Mapper` and its descending +and DELETE statements on behalf of a :class:`_orm.Mapper` and its descending mappers. The functions here are called only by the unit of work functions @@ -1649,7 +1649,7 @@ def _sort_states(mapper, states): class BulkUD(object): - """Handle bulk update and deletes via a :class:`.Query`.""" + """Handle bulk update and deletes via a :class:`_query.Query`.""" def __init__(self, query): self.query = query.enable_eagerloads(False) diff --git a/lib/sqlalchemy/orm/properties.py b/lib/sqlalchemy/orm/properties.py index 05904d1a92..1022f4ef69 100644 --- a/lib/sqlalchemy/orm/properties.py +++ b/lib/sqlalchemy/orm/properties.py @@ -40,7 +40,7 @@ __all__ = [ class ColumnProperty(StrategizedProperty): """Describes an object attribute that corresponds to a table column. - Public constructor is the :func:`.orm.column_property` function. + Public constructor is the :func:`_orm.column_property` function. """ @@ -71,12 +71,13 @@ class ColumnProperty(StrategizedProperty): r"""Provide a column-level property for use with a mapping. Column-based properties can normally be applied to the mapper's - ``properties`` dictionary using the :class:`.Column` element directly. + ``properties`` dictionary using the :class:`_schema.Column` + element directly. Use this function when the given column is not directly present within the mapper's selectable; examples include SQL expressions, functions, and scalar SELECT queries. - The :func:`.orm.column_property` function returns an instance of + The :func:`_orm.column_property` function returns an instance of :class:`.ColumnProperty`. Columns that aren't present in the mapper's selectable won't be diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py index e131a4aa3a..ce051cdcb5 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -7,11 +7,11 @@ """The Query class and support. -Defines the :class:`.Query` class, the central +Defines the :class:`_query.Query` class, the central construct used by the ORM to construct database queries. -The :class:`.Query` class should not be confused with the -:class:`.Select` class, which defines database +The :class:`_query.Query` class should not be confused with the +:class:`_expression.Select` class, which defines database SELECT operations at the SQL (non-ORM) level. ``Query`` differs from ``Select`` in that it returns ORM-mapped objects and interacts with an ORM session, whereas the ``Select`` construct interacts directly with the @@ -70,20 +70,22 @@ _path_registry = PathRegistry.root class Query(Generative): """ORM-level SQL construction object. - :class:`.Query` is the source of all SELECT statements generated by the + :class:`_query.Query` + is the source of all SELECT statements generated by the ORM, both those formulated by end-user query operations as well as by high level internal operations such as related collection loading. It features a generative interface whereby successive calls return a new - :class:`.Query` object, a copy of the former with additional + :class:`_query.Query` object, a copy of the former with additional criteria and options associated with it. - :class:`.Query` objects are normally initially generated using the + :class:`_query.Query` objects are normally initially generated using the :meth:`~.Session.query` method of :class:`.Session`, and in - less common cases by instantiating the :class:`.Query` directly and - associating with a :class:`.Session` using the :meth:`.Query.with_session` + less common cases by instantiating the :class:`_query.Query` directly and + associating with a :class:`.Session` using the + :meth:`_query.Query.with_session` method. - For a full walkthrough of :class:`.Query` usage, see the + For a full walkthrough of :class:`_query.Query` usage, see the :ref:`ormtutorial_toplevel`. """ @@ -131,7 +133,8 @@ class Query(Generative): _bake_ok = True lazy_loaded_from = None - """An :class:`.InstanceState` that is using this :class:`.Query` for a + """An :class:`.InstanceState` that is using this :class:`_query.Query` + for a lazy load operation. The primary rationale for this attribute is to support the horizontal @@ -143,7 +146,8 @@ class Query(Generative): .. note:: - Within the realm of regular :class:`.Query` usage, this attribute is + Within the realm of regular :class:`_query.Query` usage, + this attribute is set by the lazy loader strategy before the query is invoked. However there is no established hook that is available to reliably intercept this value programmatically. It is set by the lazy loading strategy @@ -152,12 +156,14 @@ class Query(Generative): cache SQL compilation, the :meth:`.QueryEvents.before_compile` hook is also not reliable. - Currently, setting the :paramref:`.relationship.bake_queries` to - ``False`` on the target :func:`.relationship`, and then making use of + Currently, setting the :paramref:`_orm.relationship.bake_queries` to + ``False`` on the target :func:`_orm.relationship`, + and then making use of the :meth:`.QueryEvents.before_compile` event hook, is the only available programmatic path to intercepting this attribute. In future releases, there will be new hooks available that allow interception of - the :class:`.Query` before it is executed, rather than before it is + the :class:`_query.Query` before it is executed, + rather than before it is compiled. .. versionadded:: 1.2.9 @@ -165,7 +171,7 @@ class Query(Generative): """ def __init__(self, entities, session=None): - """Construct a :class:`.Query` directly. + """Construct a :class:`_query.Query` directly. E.g.:: @@ -177,16 +183,18 @@ class Query(Generative): :param entities: a sequence of entities and/or SQL expressions. - :param session: a :class:`.Session` with which the :class:`.Query` - will be associated. Optional; a :class:`.Query` can be associated + :param session: a :class:`.Session` with which the + :class:`_query.Query` + will be associated. Optional; a :class:`_query.Query` + can be associated with a :class:`.Session` generatively via the - :meth:`.Query.with_session` method as well. + :meth:`_query.Query.with_session` method as well. .. seealso:: :meth:`.Session.query` - :meth:`.Query.with_session` + :meth:`_query.Query.with_session` """ self.session = session @@ -535,21 +543,23 @@ class Query(Generative): def subquery(self, name=None, with_labels=False, reduce_columns=False): """return the full SELECT statement represented by - this :class:`.Query`, embedded within an :class:`.Alias`. + this :class:`_query.Query`, embedded within an + :class:`_expression.Alias`. Eager JOIN generation within the query is disabled. :param name: string name to be assigned as the alias; - this is passed through to :meth:`.FromClause.alias`. + this is passed through to :meth:`_expression.FromClause.alias`. If ``None``, a name will be deterministically generated at compile time. :param with_labels: if True, :meth:`.with_labels` will be called - on the :class:`.Query` first to apply table-qualified labels + on the :class:`_query.Query` first to apply table-qualified labels to all columns. - :param reduce_columns: if True, :meth:`.Select.reduce_columns` will - be called on the resulting :func:`~.sql.expression.select` construct, + :param reduce_columns: if True, + :meth:`_expression.Select.reduce_columns` will + be called on the resulting :func:`_expression.select` construct, to remove same-named columns where one also refers to the other via foreign key or WHERE clause equivalence. @@ -565,10 +575,10 @@ class Query(Generative): def cte(self, name=None, recursive=False): r"""Return the full SELECT statement represented by this - :class:`.Query` represented as a common table expression (CTE). + :class:`_query.Query` represented as a common table expression (CTE). Parameters and usage are the same as those of the - :meth:`.SelectBase.cte` method; see that method for + :meth:`_expression.SelectBase.cte` method; see that method for further details. Here is the `PostgreSQL WITH @@ -577,7 +587,7 @@ class Query(Generative): Note that, in this example, the ``included_parts`` cte and the ``incl_alias`` alias of it are Core selectables, which means the columns are accessed via the ``.c.`` attribute. The - ``parts_alias`` object is an :func:`.orm.aliased` instance of the + ``parts_alias`` object is an :func:`_orm.aliased` instance of the ``Part`` entity, so column-mapped attributes are available directly:: @@ -615,7 +625,7 @@ class Query(Generative): .. seealso:: - :meth:`.HasCTE.cte` + :meth:`_expression.HasCTE.cte` """ return self.enable_eagerloads(False).statement.cte( @@ -624,7 +634,7 @@ class Query(Generative): def label(self, name): """Return the full SELECT statement represented by this - :class:`.Query`, converted + :class:`_query.Query`, converted to a scalar subquery with a label of the given name. Analogous to :meth:`sqlalchemy.sql.expression.SelectBase.label`. @@ -635,26 +645,27 @@ class Query(Generative): @util.deprecated( "1.4", - "The :meth:`.Query.as_scalar` method is deprecated and will be " + "The :meth:`_query.Query.as_scalar` method is deprecated and will be " "removed in a future release. Please refer to " - ":meth:`.Query.scalar_subquery`.", + ":meth:`_query.Query.scalar_subquery`.", ) def as_scalar(self): """Return the full SELECT statement represented by this - :class:`.Query`, converted to a scalar subquery. + :class:`_query.Query`, converted to a scalar subquery. """ return self.scalar_subquery() def scalar_subquery(self): """Return the full SELECT statement represented by this - :class:`.Query`, converted to a scalar subquery. + :class:`_query.Query`, converted to a scalar subquery. Analogous to :meth:`sqlalchemy.sql.expression.SelectBase.scalar_subquery`. - .. versionchanged:: 1.4 the :meth:`.Query.scalar_subquery` method - replaces the :meth:`.Query.as_scalar` method. + .. versionchanged:: 1.4 the :meth:`_query.Query.scalar_subquery` + method + replaces the :meth:`_query.Query.as_scalar` method. """ return self.enable_eagerloads(False).statement.scalar_subquery() @@ -672,14 +683,15 @@ class Query(Generative): .. seealso:: - :meth:`.Query.is_single_entity` + :meth:`_query.Query.is_single_entity` """ self._only_return_tuples = value @property def is_single_entity(self): - """Indicates if this :class:`.Query` returns tuples or single entities. + """Indicates if this :class:`_query.Query` + returns tuples or single entities. Returns True if this query returns a single entity for each instance in its result list, and False if this query returns a tuple of entities @@ -689,7 +701,7 @@ class Query(Generative): .. seealso:: - :meth:`.Query.only_return_tuples` + :meth:`_query.Query.only_return_tuples` """ return ( @@ -711,7 +723,7 @@ class Query(Generative): This is used primarily when nesting the Query's statement into a subquery or other - selectable, or when using :meth:`.Query.yield_per`. + selectable, or when using :meth:`_query.Query.yield_per`. """ self._enable_eagerloads = value @@ -738,12 +750,14 @@ class Query(Generative): When the `Query` actually issues SQL to load rows, it always uses column labeling. - .. note:: The :meth:`.Query.with_labels` method *only* applies - the output of :attr:`.Query.statement`, and *not* to any of - the result-row invoking systems of :class:`.Query` itself, e.g. - :meth:`.Query.first`, :meth:`.Query.all`, etc. To execute - a query using :meth:`.Query.with_labels`, invoke the - :attr:`.Query.statement` using :meth:`.Session.execute`:: + .. note:: The :meth:`_query.Query.with_labels` method *only* applies + the output of :attr:`_query.Query.statement`, and *not* to any of + the result-row invoking systems of :class:`_query.Query` itself, e. + g. + :meth:`_query.Query.first`, :meth:`_query.Query.all`, etc. + To execute + a query using :meth:`_query.Query.with_labels`, invoke the + :attr:`_query.Query.statement` using :meth:`.Session.execute`:: result = session.execute(query.with_labels().statement) @@ -803,9 +817,9 @@ class Query(Generative): ): """Load columns for inheriting classes. - :meth:`.Query.with_polymorphic` applies transformations - to the "main" mapped class represented by this :class:`.Query`. - The "main" mapped class here means the :class:`.Query` + :meth:`_query.Query.with_polymorphic` applies transformations + to the "main" mapped class represented by this :class:`_query.Query`. + The "main" mapped class here means the :class:`_query.Query` object's first argument is a full class, i.e. ``session.query(SomeClass)``. These transformations allow additional tables to be present in the FROM clause so that columns for a @@ -849,7 +863,7 @@ class Query(Generative): (e.g. approximately 1000) is used, even with DBAPIs that buffer rows (which are most). - The :meth:`.Query.yield_per` method **is not compatible + The :meth:`_query.Query.yield_per` method **is not compatible subqueryload eager loading or joinedload eager loading when using collections**. It is potentially compatible with "select in" eager loading, **provided the database driver supports multiple, @@ -858,7 +872,7 @@ class Query(Generative): Therefore in some cases, it may be helpful to disable eager loads, either unconditionally with - :meth:`.Query.enable_eagerloads`:: + :meth:`_query.Query.enable_eagerloads`:: q = sess.query(Object).yield_per(100).enable_eagerloads(False) @@ -898,7 +912,7 @@ class Query(Generative): .. seealso:: - :meth:`.Query.enable_eagerloads` + :meth:`_query.Query.enable_eagerloads` """ self._yield_per = count @@ -919,7 +933,7 @@ class Query(Generative): some_object = session.query(VersionedFoo).get( {"id": 5, "version_id": 10}) - :meth:`~.Query.get` is special in that it provides direct + :meth:`_query.Query.get` is special in that it provides direct access to the identity map of the owning :class:`.Session`. If the given primary key identifier is present in the local identity map, the object is returned @@ -928,28 +942,28 @@ class Query(Generative): If not present, a SELECT is performed in order to locate the object. - :meth:`~.Query.get` also will perform a check if + :meth:`_query.Query.get` also will perform a check if the object is present in the identity map and marked as expired - a SELECT is emitted to refresh the object as well as to ensure that the row is still present. If not, :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised. - :meth:`~.Query.get` is only used to return a single + :meth:`_query.Query.get` is only used to return a single mapped instance, not multiple instances or individual column constructs, and strictly on a single primary key value. The originating - :class:`.Query` must be constructed in this way, + :class:`_query.Query` must be constructed in this way, i.e. against a single mapped entity, with no additional filtering criterion. Loading - options via :meth:`~.Query.options` may be applied + options via :meth:`_query.Query.options` may be applied however, and will be used if the object is not yet locally present. A lazy-loading, many-to-one attribute configured - by :func:`.relationship`, using a simple + by :func:`_orm.relationship`, using a simple foreign-key-to-primary-key criterion, will also use an - operation equivalent to :meth:`~.Query.get` in order to retrieve + operation equivalent to :meth:`_query.Query.get` in order to retrieve the target value from the local identity map before querying the database. See :doc:`/orm/loading_relationships` for further details on relationship loading. @@ -965,9 +979,11 @@ class Query(Generative): my_object = query.get(5) The tuple form contains primary key values typically in - the order in which they correspond to the mapped :class:`.Table` + the order in which they correspond to the mapped + :class:`_schema.Table` object's primary key columns, or if the - :paramref:`.Mapper.primary_key` configuration parameter were used, in + :paramref:`_orm.Mapper.primary_key` configuration parameter were used + , in the order used for that parameter. For example, if the primary key of a row is represented by the integer digits "5, 10" the call would look like:: @@ -981,7 +997,8 @@ class Query(Generative): my_object = query.get({"id": 5, "version_id": 10}) - .. versionadded:: 1.3 the :meth:`.Query.get` method now optionally + .. versionadded:: 1.3 the :meth:`_query.Query.get` + method now optionally accepts a dictionary of attribute names to values in order to indicate a primary key identifier. @@ -1056,9 +1073,10 @@ class Query(Generative): @_generative def correlate(self, *args): - """Return a :class:`.Query` construct which will correlate the given - FROM clauses to that of an enclosing :class:`.Query` or - :func:`~.expression.select`. + """Return a :class:`_query.Query` + construct which will correlate the given + FROM clauses to that of an enclosing :class:`_query.Query` or + :func:`_expression.select`. The method here accepts mapped classes, :func:`.aliased` constructs, and :func:`.mapper` constructs as arguments, which are resolved into @@ -1066,12 +1084,13 @@ class Query(Generative): constructs. The correlation arguments are ultimately passed to - :meth:`.Select.correlate` after coercion to expression constructs. + :meth:`_expression.Select.correlate` + after coercion to expression constructs. The correlation arguments take effect in such cases - as when :meth:`.Query.from_self` is used, or when - a subquery as returned by :meth:`.Query.subquery` is - embedded in another :func:`~.expression.select` construct. + as when :meth:`_query.Query.from_self` is used, or when + a subquery as returned by :meth:`_query.Query.subquery` is + embedded in another :func:`_expression.select` construct. """ @@ -1099,7 +1118,8 @@ class Query(Generative): @_generative def populate_existing(self): - """Return a :class:`.Query` that will expire and refresh all instances + """Return a :class:`_query.Query` + that will expire and refresh all instances as they are loaded, or reused from the current :class:`.Session`. :meth:`.populate_existing` does not improve behavior when @@ -1117,7 +1137,7 @@ class Query(Generative): subquery loaders to traverse into already-loaded related objects and collections. - Default is that of :attr:`.Query._invoke_all_eagers`. + Default is that of :attr:`_query.Query._invoke_all_eagers`. """ self._invoke_all_eagers = value @@ -1126,18 +1146,19 @@ class Query(Generative): def with_parent(self, instance, property=None, from_entity=None): # noqa """Add filtering criterion that relates the given instance to a child object or collection, using its attribute state - as well as an established :func:`.relationship()` + as well as an established :func:`_orm.relationship()` configuration. The method uses the :func:`.with_parent` function to generate - the clause, the result of which is passed to :meth:`.Query.filter`. + the clause, the result of which is passed to + :meth:`_query.Query.filter`. Parameters are the same as :func:`.with_parent`, with the exception that the given property can be None, in which case a search is - performed against this :class:`.Query` object's target mapper. + performed against this :class:`_query.Query` object's target mapper. :param instance: - An instance which has some :func:`.relationship`. + An instance which has some :func:`_orm.relationship`. :param property: String property name, or class-bound attribute, which indicates @@ -1146,7 +1167,7 @@ class Query(Generative): :param from_entity: Entity in which to consider as the left side. This defaults to the - "zero" entity of the :class:`.Query` itself. + "zero" entity of the :class:`_query.Query` itself. """ relationships = util.preloaded.orm_relationships @@ -1191,13 +1212,18 @@ class Query(Generative): @_generative def with_session(self, session): - """Return a :class:`.Query` that will use the given :class:`.Session`. + """Return a :class:`_query.Query` that will use the given + :class:`.Session`. - While the :class:`.Query` object is normally instantiated using the - :meth:`.Session.query` method, it is legal to build the :class:`.Query` + While the :class:`_query.Query` + object is normally instantiated using the + :meth:`.Session.query` method, it is legal to build the + :class:`_query.Query` directly without necessarily using a :class:`.Session`. Such a - :class:`.Query` object, or any :class:`.Query` already associated - with a different :class:`.Session`, can produce a new :class:`.Query` + :class:`_query.Query` object, or any :class:`_query.Query` + already associated + with a different :class:`.Session`, can produce a new + :class:`_query.Query` object associated with a target session using this method:: from sqlalchemy.orm import Query @@ -1211,7 +1237,7 @@ class Query(Generative): self.session = session @util.deprecated_20( - ":meth:`.Query.from_self`", + ":meth:`_query.Query.from_self`", alternative="The new approach is to use the :func:`.orm.aliased` " "construct in conjunction with a subquery. See the section " ":ref:`Selecting from the query itself as a subquery " @@ -1222,12 +1248,12 @@ class Query(Generative): r"""return a Query that selects from this Query's SELECT statement. - :meth:`.Query.from_self` essentially turns the SELECT statement + :meth:`_query.Query.from_self` essentially turns the SELECT statement into a SELECT of itself. Given a query such as:: q = session.query(User).filter(User.name.like('e%')) - Given the :meth:`.Query.from_self` version:: + Given the :meth:`_query.Query.from_self` version:: q = session.query(User).filter(User.name.like('e%')).from_self() @@ -1241,7 +1267,8 @@ class Query(Generative): FROM "user" WHERE "user".name LIKE :name_1) AS anon_1 - There are lots of cases where :meth:`.Query.from_self` may be useful. + There are lots of cases where :meth:`_query.Query.from_self` + may be useful. A simple one is where above, we may want to apply a row LIMIT to the set of user objects we query against, and then apply additional joins against that row-limited set:: @@ -1266,7 +1293,8 @@ class Query(Generative): **Automatic Aliasing** - Another key behavior of :meth:`.Query.from_self` is that it applies + Another key behavior of :meth:`_query.Query.from_self` + is that it applies **automatic aliasing** to the entities inside the subquery, when they are referenced on the outside. Above, if we continue to refer to the ``User`` entity without any additional aliasing applied @@ -1295,13 +1323,15 @@ class Query(Generative): for simple filters and orderings. More ambitious constructions such as referring to the entity in joins should prefer to use explicit subquery objects, typically making use of the - :meth:`.Query.subquery` method to produce an explicit subquery object. + :meth:`_query.Query.subquery` + method to produce an explicit subquery object. Always test the structure of queries by viewing the SQL to ensure a particular structure does what's expected! **Changing the Entities** - :meth:`.Query.from_self` also includes the ability to modify what + :meth:`_query.Query.from_self` + also includes the ability to modify what columns are being queried. In our example, we want ``User.id`` to be queried by the inner query, so that we can join to the ``Address`` entity on the outside, but we only wanted the outer @@ -1340,8 +1370,9 @@ class Query(Generative): q = q.add_entity(User).from_self().\ options(contains_eager(Address.user)) - We use :meth:`.Query.add_entity` above **before** we call - :meth:`.Query.from_self` so that the ``User`` columns are present + We use :meth:`_query.Query.add_entity` above **before** we call + :meth:`_query.Query.from_self` + so that the ``User`` columns are present in the inner subquery, so that they are available to the :func:`.contains_eager` modifier we are using on the outside, producing: @@ -1457,7 +1488,8 @@ class Query(Generative): @_generative def with_entities(self, *entities): - r"""Return a new :class:`.Query` replacing the SELECT list with the + r"""Return a new :class:`_query.Query` + replacing the SELECT list with the given entities. e.g.:: @@ -1493,8 +1525,9 @@ class Query(Generative): @util.deprecated( "1.4", - ":meth:`.Query.add_column` is deprecated and will be removed in a " - "future release. Please use :meth:`.Query.add_columns`", + ":meth:`_query.Query.add_column` " + "is deprecated and will be removed in a " + "future release. Please use :meth:`_query.Query.add_columns`", ) def add_column(self, column): """Add a column expression to the list of result columns to be @@ -1504,7 +1537,8 @@ class Query(Generative): return self.add_columns(column) def options(self, *args): - """Return a new :class:`.Query` object, applying the given list of + """Return a new :class:`_query.Query` object, + applying the given list of mapper options. Most supplied options regard changing how column- and @@ -1539,7 +1573,7 @@ class Query(Generative): opt.process_query(self) def with_transformation(self, fn): - """Return a new :class:`.Query` object transformed by + """Return a new :class:`_query.Query` object transformed by the given function. E.g.:: @@ -1551,7 +1585,7 @@ class Query(Generative): q = q.with_transformation(filter_something(x==5)) - This allows ad-hoc recipes to be created for :class:`.Query` + This allows ad-hoc recipes to be created for :class:`_query.Query` objects. See the example at :ref:`hybrid_transformers`. """ @@ -1561,17 +1595,18 @@ class Query(Generative): def with_hint(self, selectable, text, dialect_name="*"): """Add an indexing or other executional context hint for the given entity or selectable to - this :class:`.Query`. + this :class:`_query.Query`. Functionality is passed straight through to :meth:`~sqlalchemy.sql.expression.Select.with_hint`, with the addition that ``selectable`` can be a - :class:`.Table`, :class:`.Alias`, or ORM entity / mapped class + :class:`_schema.Table`, :class:`_expression.Alias`, + or ORM entity / mapped class /etc. .. seealso:: - :meth:`.Query.with_statement_hint` + :meth:`_query.Query.with_statement_hint` :meth:.`.Query.prefix_with` - generic SELECT prefixing which also can suit some database-specific HINT syntaxes such as MySQL @@ -1584,19 +1619,21 @@ class Query(Generative): self._with_hints += ((selectable, text, dialect_name),) def with_statement_hint(self, text, dialect_name="*"): - """add a statement hint to this :class:`.Select`. + """add a statement hint to this :class:`_expression.Select`. - This method is similar to :meth:`.Select.with_hint` except that + This method is similar to :meth:`_expression.Select.with_hint` + except that it does not require an individual table, and instead applies to the statement as a whole. - This feature calls down into :meth:`.Select.with_statement_hint`. + This feature calls down into + :meth:`_expression.Select.with_statement_hint`. .. versionadded:: 1.0.0 .. seealso:: - :meth:`.Query.with_hint` + :meth:`_query.Query.with_hint` """ return self.with_hint(None, text, dialect_name) @@ -1608,7 +1645,7 @@ class Query(Generative): .. seealso:: - :meth:`.Query.execution_options` + :meth:`_query.Query.execution_options` """ return self._execution_options @@ -1617,7 +1654,7 @@ class Query(Generative): """ Set non-SQL options which take effect during execution. The options are the same as those accepted by - :meth:`.Connection.execution_options`. + :meth:`_engine.Connection.execution_options`. Note that the ``stream_results`` execution option is enabled automatically if the :meth:`~sqlalchemy.orm.query.Query.yield_per()` @@ -1625,7 +1662,7 @@ class Query(Generative): .. seealso:: - :meth:`.Query.get_execution_options` + :meth:`_query.Query.get_execution_options` """ self._execution_options = self._execution_options.union(kwargs) @@ -1639,11 +1676,13 @@ class Query(Generative): skip_locked=False, key_share=False, ): - """return a new :class:`.Query` with the specified options for the + """return a new :class:`_query.Query` + with the specified options for the ``FOR UPDATE`` clause. The behavior of this method is identical to that of - :meth:`.SelectBase.with_for_update`. When called with no arguments, + :meth:`_expression.SelectBase.with_for_update`. + When called with no arguments, the resulting ``SELECT`` statement will have a ``FOR UPDATE`` clause appended. When additional arguments are specified, backend-specific options such as ``FOR UPDATE NOWAIT`` or ``LOCK IN SHARE MODE`` @@ -1659,7 +1698,8 @@ class Query(Generative): .. seealso:: - :meth:`.GenerativeSelect.with_for_update` - Core level method with + :meth:`_expression.GenerativeSelect.with_for_update` + - Core level method with full argument and behavioral description. """ @@ -1696,7 +1736,7 @@ class Query(Generative): @_assertions(_no_statement_condition, _no_limit_offset) def filter(self, *criterion): r"""apply the given filtering criterion to a copy - of this :class:`.Query`, using SQL expressions. + of this :class:`_query.Query`, using SQL expressions. e.g.:: @@ -1711,11 +1751,12 @@ class Query(Generative): The criterion is any SQL expression object applicable to the WHERE clause of a select. String expressions are coerced - into SQL expression constructs via the :func:`.text` construct. + into SQL expression constructs via the :func:`_expression.text` + construct. .. seealso:: - :meth:`.Query.filter_by` - filter on keyword expressions. + :meth:`_query.Query.filter_by` - filter on keyword expressions. """ for criterion in list(criterion): @@ -1729,7 +1770,7 @@ class Query(Generative): def filter_by(self, **kwargs): r"""apply the given filtering criterion to a copy - of this :class:`.Query`, using keyword expressions. + of this :class:`_query.Query`, using keyword expressions. e.g.:: @@ -1744,11 +1785,11 @@ class Query(Generative): The keyword expressions are extracted from the primary entity of the query, or the last entity that was the - target of a call to :meth:`.Query.join`. + target of a call to :meth:`_query.Query.join`. .. seealso:: - :meth:`.Query.filter` - filter on SQL expressions. + :meth:`_query.Query.filter` - filter on SQL expressions. """ @@ -1788,7 +1829,7 @@ class Query(Generative): @_assertions(_no_statement_condition, _no_limit_offset) def group_by(self, *criterion): """apply one or more GROUP BY criterion to the query and return - the newly resulting :class:`.Query` + the newly resulting :class:`_query.Query` All existing GROUP BY settings can be suppressed by passing ``None`` - this will suppress any GROUP BY configured @@ -1816,10 +1857,10 @@ class Query(Generative): @_assertions(_no_statement_condition, _no_limit_offset) def having(self, criterion): r"""apply a HAVING criterion to the query and return the - newly resulting :class:`.Query`. + newly resulting :class:`_query.Query`. - :meth:`~.Query.having` is used in conjunction with - :meth:`~.Query.group_by`. + :meth:`_query.Query.having` is used in conjunction with + :meth:`_query.Query.group_by`. HAVING criterion makes it possible to use filters on aggregate functions like COUNT, SUM, AVG, MAX, and MIN, eg.:: @@ -1884,7 +1925,7 @@ class Query(Generative): be rendered on a query called within UNION, EXCEPT, etc. To disable all ORDER BY clauses including those configured on mappers, issue ``query.order_by(None)`` - the resulting - :class:`.Query` object will not render ORDER BY within + :class:`_query.Query` object will not render ORDER BY within its SELECT statement. """ @@ -1936,27 +1977,31 @@ class Query(Generative): return self._set_op(expression.except_all, *q) def join(self, *props, **kwargs): - r"""Create a SQL JOIN against this :class:`.Query` object's criterion - and apply generatively, returning the newly resulting :class:`.Query`. + r"""Create a SQL JOIN against this :class:`_query.Query` + object's criterion + and apply generatively, returning the newly resulting + :class:`_query.Query`. **Simple Relationship Joins** Consider a mapping between two classes ``User`` and ``Address``, with a relationship ``User.addresses`` representing a collection of ``Address`` objects associated with each ``User``. The most - common usage of :meth:`~.Query.join` is to create a JOIN along this + common usage of :meth:`_query.Query.join` + is to create a JOIN along this relationship, using the ``User.addresses`` attribute as an indicator for how this should occur:: q = session.query(User).join(User.addresses) - Where above, the call to :meth:`~.Query.join` along ``User.addresses`` + Where above, the call to :meth:`_query.Query.join` along ``User. + addresses`` will result in SQL equivalent to:: SELECT user.* FROM user JOIN address ON user.id = address.user_id In the above example we refer to ``User.addresses`` as passed to - :meth:`~.Query.join` as the *on clause*, that is, it indicates + :meth:`_query.Query.join` as the *on clause*, that is, it indicates how the "ON" portion of the JOIN should be constructed. For a single-entity query such as the one above (i.e. we start by selecting only from ``User`` and nothing else), the relationship can also be @@ -1964,14 +2009,15 @@ class Query(Generative): q = session.query(User).join("addresses") - :meth:`~.Query.join` can also accommodate multiple + :meth:`_query.Query.join` can also accommodate multiple "on clause" arguments to produce a chain of joins, such as below where a join across four related entities is constructed:: q = session.query(User).join("orders", "items", "keywords") The above would be shorthand for three separate calls to - :meth:`~.Query.join`, each using an explicit attribute to indicate + :meth:`_query.Query.join`, + each using an explicit attribute to indicate the source entity:: q = session.query(User).\ @@ -1981,20 +2027,21 @@ class Query(Generative): **Joins to a Target Entity or Selectable** - A second form of :meth:`~.Query.join` allows any mapped entity + A second form of :meth:`_query.Query.join` allows any mapped entity or core selectable construct as a target. In this usage, - :meth:`~.Query.join` will attempt + :meth:`_query.Query.join` will attempt to create a JOIN along the natural foreign key relationship between two entities:: q = session.query(User).join(Address) - The above calling form of :meth:`~.Query.join` will raise an error if + The above calling form of :meth:`_query.Query.join` + will raise an error if either there are no foreign keys between the two entities, or if there are multiple foreign key linkages between them. In the - above calling form, :meth:`~.Query.join` is called upon to + above calling form, :meth:`_query.Query.join` is called upon to create the "on clause" automatically for us. The target can - be any mapped entity or selectable, such as a :class:`.Table`:: + be any mapped entity or selectable, such as a :class:`_schema.Table`:: q = session.query(User).join(addresses_table) @@ -2025,7 +2072,7 @@ class Query(Generative): WHERE address.email_address = :email_address_1 AND address_1.email_address = :email_address_2 - The two-argument calling form of :meth:`~.Query.join` + The two-argument calling form of :meth:`_query.Query.join` also allows us to construct arbitrary joins with SQL-oriented "on clause" expressions, not relying upon configured relationships at all. Any SQL expression can be passed as the ON clause @@ -2037,9 +2084,10 @@ class Query(Generative): **Advanced Join Targeting and Adaption** There is a lot of flexibility in what the "target" can be when using - :meth:`~.Query.join`. As noted previously, it also accepts - :class:`.Table` constructs and other selectables such as :func:`.alias` - and :func:`~.sql.expression.select` constructs, with either the one or + :meth:`_query.Query.join`. As noted previously, it also accepts + :class:`_schema.Table` constructs and other selectables such as + :func:`.alias` + and :func:`_expression.select` constructs, with either the one or two-argument forms:: addresses_q = select([Address.user_id]).\ @@ -2049,7 +2097,7 @@ class Query(Generative): q = session.query(User).\ join(addresses_q, addresses_q.c.user_id==User.id) - :meth:`~.Query.join` also features the ability to *adapt* a + :meth:`_query.Query.join` also features the ability to *adapt* a :meth:`~sqlalchemy.orm.relationship` -driven ON clause to the target selectable. Below we construct a JOIN from ``User`` to a subquery against ``Address``, allowing the relationship denoted by @@ -2080,12 +2128,12 @@ class Query(Generative): **Controlling what to Join From** - While :meth:`~.Query.join` exclusively deals with the "right" + While :meth:`_query.Query.join` exclusively deals with the "right" side of the JOIN, we can also control the "left" side, in those - cases where it's needed, using :meth:`~.Query.select_from`. + cases where it's needed, using :meth:`_query.Query.select_from`. Below we construct a query against ``Address`` but can still make usage of ``User.addresses`` as our ON clause by instructing - the :class:`.Query` to select first from the ``User`` + the :class:`_query.Query` to select first from the ``User`` entity:: q = session.query(Address).select_from(User).\ @@ -2100,7 +2148,7 @@ class Query(Generative): **Constructing Aliases Anonymously** - :meth:`~.Query.join` can construct anonymous aliases + :meth:`_query.Query.join` can construct anonymous aliases using the ``aliased=True`` flag. This feature is useful when a query is being joined algorithmically, such as when querying self-referentially to an arbitrary depth:: @@ -2110,7 +2158,7 @@ class Query(Generative): When ``aliased=True`` is used, the actual "alias" construct is not explicitly available. To work with it, methods such as - :meth:`.Query.filter` will adapt the incoming entity to + :meth:`_query.Query.filter` will adapt the incoming entity to the last join point:: q = session.query(Node).\ @@ -2119,7 +2167,7 @@ class Query(Generative): When using automatic aliasing, the ``from_joinpoint=True`` argument can allow a multi-node join to be broken into - multiple calls to :meth:`~.Query.join`, so that + multiple calls to :meth:`_query.Query.join`, so that each path along the way can be further filtered:: q = session.query(Node).\ @@ -2129,7 +2177,7 @@ class Query(Generative): filter(Node.name == 'grandchild 1') The filtering aliases above can then be reset back to the - original ``Node`` entity using :meth:`~.Query.reset_joinpoint`:: + original ``Node`` entity using :meth:`_query.Query.reset_joinpoint`:: q = session.query(Node).\ join("children", "children", aliased=True).\ @@ -2148,13 +2196,14 @@ class Query(Generative): A special two-argument calling form of the form ``target, onclause`` is also accepted. :param aliased=False: If True, indicate that the JOIN target should be - anonymously aliased. Subsequent calls to :meth:`~.Query.filter` + anonymously aliased. Subsequent calls to :meth:`_query.Query.filter` and similar will adapt the incoming criterion to the target - alias, until :meth:`~.Query.reset_joinpoint` is called. + alias, until :meth:`_query.Query.reset_joinpoint` is called. :param isouter=False: If True, the join used will be a left outer join, - just as if the :meth:`.Query.outerjoin` method were called. This + just as if the :meth:`_query.Query.outerjoin` method were called. + This flag is here to maintain consistency with the same flag as accepted - by :meth:`.FromClause.join` and other Core constructs. + by :meth:`_expression.FromClause.join` and other Core constructs. .. versionadded:: 1.0.0 @@ -2173,10 +2222,10 @@ class Query(Generative): :ref:`ormtutorial_joins` in the ORM tutorial. :ref:`inheritance_toplevel` for details on how - :meth:`~.Query.join` is used for inheritance relationships. + :meth:`_query.Query.join` is used for inheritance relationships. - :func:`.orm.join` - a standalone ORM-level join function, - used internally by :meth:`.Query.join`, which in previous + :func:`_orm.join` - a standalone ORM-level join function, + used internally by :meth:`_query.Query.join`, which in previous SQLAlchemy versions was the primary ORM-level joining interface. """ @@ -2809,12 +2858,12 @@ class Query(Generative): @_generative @_assertions(_no_statement_condition) def reset_joinpoint(self): - """Return a new :class:`.Query`, where the "join point" has + """Return a new :class:`_query.Query`, where the "join point" has been reset back to the base FROM entities of the query. This method is usually used in conjunction with the - ``aliased=True`` feature of the :meth:`~.Query.join` - method. See the example in :meth:`~.Query.join` for how + ``aliased=True`` feature of the :meth:`_query.Query.join` + method. See the example in :meth:`_query.Query.join` for how this is used. """ @@ -2823,16 +2872,16 @@ class Query(Generative): @_generative @_assertions(_no_clauseelement_condition) def select_from(self, *from_obj): - r"""Set the FROM clause of this :class:`.Query` explicitly. + r"""Set the FROM clause of this :class:`_query.Query` explicitly. - :meth:`.Query.select_from` is often used in conjunction with - :meth:`.Query.join` in order to control which entity is selected + :meth:`_query.Query.select_from` is often used in conjunction with + :meth:`_query.Query.join` in order to control which entity is selected from on the "left" side of the join. The entity or selectable object here effectively replaces the - "left edge" of any calls to :meth:`~.Query.join`, when no + "left edge" of any calls to :meth:`_query.Query.join`, when no joinpoint is otherwise established - usually, the default "join - point" is the leftmost entity in the :class:`~.Query` object's + point" is the leftmost entity in the :class:`_query.Query` object's list of entities to be selected. A typical example:: @@ -2849,8 +2898,9 @@ class Query(Generative): :param \*from_obj: collection of one or more entities to apply to the FROM clause. Entities can be mapped classes, - :class:`.AliasedClass` objects, :class:`.Mapper` objects - as well as core :class:`.FromClause` elements like subqueries. + :class:`.AliasedClass` objects, :class:`_orm.Mapper` objects + as well as core :class:`_expression.FromClause` + elements like subqueries. .. versionchanged:: 0.9 This method no longer applies the given FROM object @@ -2861,9 +2911,9 @@ class Query(Generative): .. seealso:: - :meth:`~.Query.join` + :meth:`_query.Query.join` - :meth:`.Query.select_entity_from` + :meth:`_query.Query.select_entity_from` """ @@ -2872,15 +2922,16 @@ class Query(Generative): @_generative @_assertions(_no_clauseelement_condition) def select_entity_from(self, from_obj): - r"""Set the FROM clause of this :class:`.Query` to a + r"""Set the FROM clause of this :class:`_query.Query` to a core selectable, applying it as a replacement FROM clause for corresponding mapped entities. - The :meth:`.Query.select_entity_from` method supplies an alternative + The :meth:`_query.Query.select_entity_from` + method supplies an alternative approach to the use case of applying an :func:`.aliased` construct explicitly throughout a query. Instead of referring to the :func:`.aliased` construct explicitly, - :meth:`.Query.select_entity_from` automatically *adapts* all + :meth:`_query.Query.select_entity_from` automatically *adapts* all occurrences of the entity to the target selectable. Given a case for :func:`.aliased` such as selecting ``User`` @@ -2894,7 +2945,8 @@ class Query(Generative): Above, we apply the ``user_alias`` object explicitly throughout the query. When it's not feasible for ``user_alias`` to be referenced - explicitly in many places, :meth:`.Query.select_entity_from` may be + explicitly in many places, :meth:`_query.Query.select_entity_from` + may be used at the start of the query to adapt the existing ``User`` entity:: q = session.query(User).\ @@ -2912,11 +2964,12 @@ class Query(Generative): WHERE "user".id = :id_1) AS anon_1 WHERE anon_1.name = :name_1 - The :meth:`.Query.select_entity_from` method is similar to the - :meth:`.Query.select_from` method, in that it sets the FROM clause + The :meth:`_query.Query.select_entity_from` method is similar to the + :meth:`_query.Query.select_from` method, + in that it sets the FROM clause of the query. The difference is that it additionally applies adaptation to the other parts of the query that refer to the - primary entity. If above we had used :meth:`.Query.select_from` + primary entity. If above we had used :meth:`_query.Query.select_from` instead, the SQL generated would have been: .. sourcecode:: sql @@ -2928,24 +2981,30 @@ class Query(Generative): WHERE "user".id = :id_1) AS anon_1 WHERE "user".name = :name_1 - To supply textual SQL to the :meth:`.Query.select_entity_from` method, - we can make use of the :func:`.text` construct. However, the - :func:`.text` construct needs to be aligned with the columns of our + To supply textual SQL to the :meth:`_query.Query.select_entity_from` + method, + we can make use of the :func:`_expression.text` construct. However, + the + :func:`_expression.text` + construct needs to be aligned with the columns of our entity, which is achieved by making use of the - :meth:`.TextClause.columns` method:: + :meth:`_expression.TextClause.columns` method:: text_stmt = text("select id, name from user").columns( User.id, User.name).subquery() q = session.query(User).select_entity_from(text_stmt) - :meth:`.Query.select_entity_from` itself accepts an :func:`.aliased` + :meth:`_query.Query.select_entity_from` itself accepts an + :func:`.aliased` object, so that the special options of :func:`.aliased` such as :paramref:`.aliased.adapt_on_names` may be used within the - scope of the :meth:`.Query.select_entity_from` method's adaptation + scope of the :meth:`_query.Query.select_entity_from` + method's adaptation services. Suppose a view ``user_view`` also returns rows from ``user``. If - we reflect this view into a :class:`.Table`, this view has no - relationship to the :class:`.Table` to which we are mapped, however + we reflect this view into a :class:`_schema.Table`, this view has no + relationship to the :class:`_schema.Table` to which we are mapped, + however we can use name matching to select from it:: user_view = Table('user_view', metadata, @@ -2956,19 +3015,21 @@ class Query(Generative): select_entity_from(user_view_alias).\ order_by(User.name) - .. versionchanged:: 1.1.7 The :meth:`.Query.select_entity_from` + .. versionchanged:: 1.1.7 The :meth:`_query.Query.select_entity_from` method now accepts an :func:`.aliased` object as an alternative - to a :class:`.FromClause` object. + to a :class:`_expression.FromClause` object. - :param from_obj: a :class:`.FromClause` object that will replace - the FROM clause of this :class:`.Query`. It also may be an instance + :param from_obj: a :class:`_expression.FromClause` + object that will replace + the FROM clause of this :class:`_query.Query`. + It also may be an instance of :func:`.aliased`. .. seealso:: - :meth:`.Query.select_from` + :meth:`_query.Query.select_from` """ @@ -3006,8 +3067,8 @@ class Query(Generative): @_generative @_assertions(_no_statement_condition) def slice(self, start, stop): - """Computes the "slice" of the :class:`.Query` represented by - the given indices and returns the resulting :class:`.Query`. + """Computes the "slice" of the :class:`_query.Query` represented by + the given indices and returns the resulting :class:`_query.Query`. The start and stop indices behave like the argument to Python's built-in :func:`range` function. This method provides an @@ -3030,9 +3091,9 @@ class Query(Generative): .. seealso:: - :meth:`.Query.limit` + :meth:`_query.Query.limit` - :meth:`.Query.offset` + :meth:`_query.Query.offset` """ if start is not None and stop is not None: @@ -3082,9 +3143,10 @@ class Query(Generative): columns clause of the SELECT statement, to satisfy the common need of the database backend that ORDER BY columns be part of the SELECT list when DISTINCT is used. These columns *are not* added to the - list of columns actually fetched by the :class:`.Query`, however, + list of columns actually fetched by the :class:`_query.Query`, + however, so would not affect results. The columns are passed through when - using the :attr:`.Query.statement` accessor, however. + using the :attr:`_query.Query.statement` accessor, however. .. deprecated:: 2.0 This logic is deprecated and will be removed in SQLAlchemy 2.0. See :ref:`migration_20_query_distinct` @@ -3127,7 +3189,7 @@ class Query(Generative): .. seealso:: - :meth:`.HasPrefixes.prefix_with` + :meth:`_expression.HasPrefixes.prefix_with` """ if self._prefixes: @@ -3147,9 +3209,9 @@ class Query(Generative): .. seealso:: - :meth:`.Query.prefix_with` + :meth:`_query.Query.prefix_with` - :meth:`.HasSuffixes.suffix_with` + :meth:`_expression.HasSuffixes.suffix_with` """ if self._suffixes: @@ -3158,11 +3220,13 @@ class Query(Generative): self._suffixes = suffixes def all(self): - """Return the results represented by this :class:`.Query` as a list. + """Return the results represented by this :class:`_query.Query` + as a list. This results in an execution of the underlying SQL statement. - .. warning:: The :class:`.Query` object, when asked to return either + .. warning:: The :class:`_query.Query` object, + when asked to return either a sequence or iterator that consists of full ORM-mapped entities, will **deduplicate entries based on primary key**. See the FAQ for more details. @@ -3181,10 +3245,11 @@ class Query(Generative): This method bypasses all internal statement compilation, and the statement is executed without modification. - The statement is typically either a :func:`~.expression.text` - or :func:`~.expression.select` construct, and should return the set + The statement is typically either a :func:`_expression.text` + or :func:`_expression.select` construct, and should return the set of columns - appropriate to the entity class represented by this :class:`.Query`. + appropriate to the entity class represented by this + :class:`_query.Query`. .. seealso:: @@ -3204,14 +3269,15 @@ class Query(Generative): (note this may consist of multiple result rows if join-loaded collections are present). - Calling :meth:`.Query.first` results in an execution of the underlying + Calling :meth:`_query.Query.first` + results in an execution of the underlying query. .. seealso:: - :meth:`.Query.one` + :meth:`_query.Query.one` - :meth:`.Query.one_or_none` + :meth:`_query.Query.one_or_none` """ if self._statement is not None: @@ -3232,18 +3298,19 @@ class Query(Generative): rows are returned for a query that returns only scalar values as opposed to full identity-mapped entities. - Calling :meth:`.Query.one_or_none` results in an execution of the + Calling :meth:`_query.Query.one_or_none` + results in an execution of the underlying query. .. versionadded:: 1.0.9 - Added :meth:`.Query.one_or_none` + Added :meth:`_query.Query.one_or_none` .. seealso:: - :meth:`.Query.first` + :meth:`_query.Query.first` - :meth:`.Query.one` + :meth:`_query.Query.one` """ ret = list(self) @@ -3271,9 +3338,9 @@ class Query(Generative): .. seealso:: - :meth:`.Query.first` + :meth:`_query.Query.first` - :meth:`.Query.one_or_none` + :meth:`_query.Query.one_or_none` """ try: @@ -3365,7 +3432,7 @@ class Query(Generative): @property def column_descriptions(self): """Return metadata about the columns which would be - returned by this :class:`.Query`. + returned by this :class:`_query.Query`. Format is a list of dictionaries:: @@ -3435,7 +3502,7 @@ class Query(Generative): util.warn_deprecated( "Using the Query.instances() method without a context " "is deprecated and will be disallowed in a future release. " - "Please make use of :meth:`.Query.from_statement` " + "Please make use of :meth:`_query.Query.from_statement` " "for linking ORM results to arbitrary select constructs.", version="1.4", ) @@ -3444,9 +3511,10 @@ class Query(Generative): return loading.instances(self, result_proxy, context) def merge_result(self, iterator, load=True): - """Merge a result into this :class:`.Query` object's Session. + """Merge a result into this :class:`_query.Query` object's Session. - Given an iterator returned by a :class:`.Query` of the same structure + Given an iterator returned by a :class:`_query.Query` + of the same structure as this one, return an identical iterator of results, with all mapped instances merged into the session using :meth:`.Session.merge`. This is an optimized method which will merge all mapped instances, @@ -3455,14 +3523,15 @@ class Query(Generative): explicitly for each value. The structure of the results is determined based on the column list of - this :class:`.Query` - if these do not correspond, unchecked errors + this :class:`_query.Query` - if these do not correspond, + unchecked errors will occur. The 'load' argument is the same as that of :meth:`.Session.merge`. - For an example of how :meth:`~.Query.merge_result` is used, see + For an example of how :meth:`_query.Query.merge_result` is used, see the source code for the example :ref:`examples_caching`, where - :meth:`~.Query.merge_result` is used to efficiently restore state + :meth:`_query.Query.merge_result` is used to efficiently restore state from a cache back into a target :class:`.Session`. """ @@ -3544,7 +3613,8 @@ class Query(Generative): ) AS anon_1 The above SQL returns a single row, which is the aggregate value - of the count function; the :meth:`.Query.count` method then returns + of the count function; the :meth:`_query.Query.count` + method then returns that single integer value. .. warning:: @@ -3552,7 +3622,8 @@ class Query(Generative): It is important to note that the value returned by count() is **not the same as the number of ORM objects that this Query would return from a method such as the .all() method**. - The :class:`.Query` object, when asked to return full entities, + The :class:`_query.Query` object, + when asked to return full entities, will **deduplicate entries based on primary key**, meaning if the same primary key value would appear in the results more than once, only one object of that primary key would be present. This does @@ -3602,7 +3673,8 @@ class Query(Generative): sess.query(User).filter(User.age == 25).\ delete(synchronize_session='evaluate') - .. warning:: The :meth:`.Query.delete` method is a "bulk" operation, + .. warning:: The :meth:`_query.Query.delete` + method is a "bulk" operation, which bypasses ORM unit-of-work automation in favor of greater performance. **Please read all caveats and warnings below.** @@ -3702,7 +3774,7 @@ class Query(Generative): .. seealso:: - :meth:`.Query.update` + :meth:`_query.Query.update` :ref:`inserts_and_updates` - Core SQL tutorial @@ -3726,7 +3798,8 @@ class Query(Generative): update({"age": User.age - 10}, synchronize_session='evaluate') - .. warning:: The :meth:`.Query.update` method is a "bulk" operation, + .. warning:: The :meth:`_query.Query.update` + method is a "bulk" operation, which bypasses ORM unit-of-work automation in favor of greater performance. **Please read all caveats and warnings below.** @@ -3768,7 +3841,8 @@ class Query(Generative): string collations between the database and Python. :param update_args: Optional dictionary, if present will be passed - to the underlying :func:`.update` construct as the ``**kw`` for + to the underlying :func:`_expression.update` + construct as the ``**kw`` for the object. May be used to pass dialect-specific arguments such as ``mysql_limit``, as well as other special arguments such as :paramref:`~sqlalchemy.sql.expression.update.preserve_parameter_order`. @@ -3834,7 +3908,7 @@ class Query(Generative): .. seealso:: - :meth:`.Query.delete` + :meth:`_query.Query.delete` :ref:`inserts_and_updates` - Core SQL tutorial @@ -4272,11 +4346,13 @@ class _MapperEntity(_QueryEntity): @inspection._self_inspects class Bundle(InspectionAttr): - """A grouping of SQL expressions that are returned by a :class:`.Query` + """A grouping of SQL expressions that are returned by a + :class:`_query.Query` under one namespace. The :class:`.Bundle` essentially allows nesting of the tuple-based - results returned by a column-oriented :class:`.Query` object. It also + results returned by a column-oriented :class:`_query.Query` object. + It also is extensible via simple subclassing, where the primary capability to override is that of how the set of expressions should be returned, allowing post-processing as well as custom return types, without @@ -4765,7 +4841,8 @@ class QueryContext(object): class AliasOption(interfaces.MapperOption): def __init__(self, alias): - r"""Return a :class:`.MapperOption` that will indicate to the :class:`.Query` + r"""Return a :class:`.MapperOption` that will indicate to the + :class:`_query.Query` that the main table has been aliased. This is a seldom-used option to suit the @@ -4793,7 +4870,7 @@ class AliasOption(interfaces.MapperOption): results = query.from_statement(statement).all() :param alias: is the string name of an alias, or a - :class:`~.sql.expression.Alias` object representing + :class:`_expression.Alias` object representing the alias. """ diff --git a/lib/sqlalchemy/orm/relationships.py b/lib/sqlalchemy/orm/relationships.py index c6f3bc30ab..7d33c46498 100644 --- a/lib/sqlalchemy/orm/relationships.py +++ b/lib/sqlalchemy/orm/relationships.py @@ -6,11 +6,11 @@ # the MIT License: http://www.opensource.org/licenses/mit-license.php """Heuristics related to join conditions as used in -:func:`.relationship`. +:func:`_orm.relationship`. Provides the :class:`.JoinCondition` object, which encapsulates SQL annotation and aliasing behavior focused on the `primaryjoin` -and `secondaryjoin` aspects of :func:`.relationship`. +and `secondaryjoin` aspects of :func:`_orm.relationship`. """ from __future__ import absolute_import @@ -98,7 +98,7 @@ class RelationshipProperty(StrategizedProperty): """Describes an object property that holds a single item or list of items that correspond to a related database table. - Public constructor is the :func:`.orm.relationship` function. + Public constructor is the :func:`_orm.relationship` function. .. seealso:: @@ -160,15 +160,16 @@ class RelationshipProperty(StrategizedProperty): The constructed class is an instance of :class:`.RelationshipProperty`. - A typical :func:`.relationship`, used in a classical mapping:: + A typical :func:`_orm.relationship`, used in a classical mapping:: mapper(Parent, properties={ 'children': relationship(Child) }) - Some arguments accepted by :func:`.relationship` optionally accept a + Some arguments accepted by :func:`_orm.relationship` + optionally accept a callable function, which when called produces the desired value. - The callable is invoked by the parent :class:`.Mapper` at "mapper + The callable is invoked by the parent :class:`_orm.Mapper` at "mapper initialization" time, which happens only when mappers are first used, and is assumed to be after all mappings have been constructed. This can be used to resolve order-of-declaration and other dependency @@ -182,7 +183,7 @@ class RelationshipProperty(StrategizedProperty): When using the :ref:`declarative_toplevel` extension, the Declarative initializer allows string arguments to be passed to - :func:`.relationship`. These string arguments are converted into + :func:`_orm.relationship`. These string arguments are converted into callables that evaluate the string as Python code, using the Declarative class-registry as a namespace. This allows the lookup of related classes to be automatic via their string name, and removes the @@ -191,7 +192,8 @@ class RelationshipProperty(StrategizedProperty): that the modules in which these related classes appear are imported anywhere in the application at some point before the related mappings are actually used, else a lookup error will be raised when the - :func:`.relationship` attempts to resolve the string reference to the + :func:`_orm.relationship` + attempts to resolve the string reference to the related class. An example of a string- resolved class is as follows:: @@ -207,15 +209,17 @@ class RelationshipProperty(StrategizedProperty): .. seealso:: :ref:`relationship_config_toplevel` - Full introductory and - reference documentation for :func:`.relationship`. + reference documentation for :func:`_orm.relationship`. :ref:`orm_tutorial_relationship` - ORM tutorial introduction. :param argument: - a mapped class, or actual :class:`.Mapper` instance, representing + a mapped class, or actual :class:`_orm.Mapper` instance, + representing the target of the relationship. - :paramref:`~.relationship.argument` may also be passed as a callable + :paramref:`_orm.relationship.argument` + may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a string name when using Declarative. @@ -223,7 +227,7 @@ class RelationshipProperty(StrategizedProperty): using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on - declarative evaluation of :func:`.relationship` arguments. + declarative evaluation of :func:`_orm.relationship` arguments. .. versionchanged 1.3.16:: @@ -238,30 +242,35 @@ class RelationshipProperty(StrategizedProperty): :param secondary: for a many-to-many relationship, specifies the intermediary - table, and is typically an instance of :class:`.Table`. + table, and is typically an instance of :class:`_schema.Table`. In less common circumstances, the argument may also be specified - as an :class:`.Alias` construct, or even a :class:`.Join` construct. + as an :class:`_expression.Alias` construct, or even a + :class:`_expression.Join` construct. - :paramref:`~.relationship.secondary` may + :paramref:`_orm.relationship.secondary` may also be passed as a callable function which is evaluated at mapper initialization time. When using Declarative, it may also - be a string argument noting the name of a :class:`.Table` that is - present in the :class:`.MetaData` collection associated with the - parent-mapped :class:`.Table`. + be a string argument noting the name of a :class:`_schema.Table` + that is + present in the :class:`_schema.MetaData` + collection associated with the + parent-mapped :class:`_schema.Table`. .. warning:: When passed as a Python-evaluable string, the argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on - declarative evaluation of :func:`.relationship` arguments. + declarative evaluation of :func:`_orm.relationship` arguments. - The :paramref:`~.relationship.secondary` keyword argument is - typically applied in the case where the intermediary :class:`.Table` + The :paramref:`_orm.relationship.secondary` keyword argument is + typically applied in the case where the intermediary + :class:`_schema.Table` is not otherwise expressed in any direct class mapping. If the "secondary" table is also explicitly mapped elsewhere (e.g. as in :ref:`association_pattern`), one should consider applying the - :paramref:`~.relationship.viewonly` flag so that this - :func:`.relationship` is not used for persistence operations which + :paramref:`_orm.relationship.viewonly` flag so that this + :func:`_orm.relationship` + is not used for persistence operations which may conflict with those of the association object pattern. .. seealso:: @@ -279,16 +288,19 @@ class RelationshipProperty(StrategizedProperty): Declarative. :ref:`association_pattern` - an alternative to - :paramref:`~.relationship.secondary` when composing association + :paramref:`_orm.relationship.secondary` + when composing association table relationships, allowing additional attributes to be specified on the association table. :ref:`composite_secondary_join` - a lesser-used pattern which - in some cases can enable complex :func:`.relationship` SQL + in some cases can enable complex :func:`_orm.relationship` SQL conditions to be used. - .. versionadded:: 0.9.2 :paramref:`~.relationship.secondary` works - more effectively when referring to a :class:`.Join` instance. + .. versionadded:: 0.9.2 :paramref:`_orm.relationship.secondary` + works + more effectively when referring to a :class:`_expression.Join` + instance. :param active_history=False: When ``True``, indicates that the "previous" value for a @@ -313,20 +325,20 @@ class RelationshipProperty(StrategizedProperty): :ref:`relationships_backref` - Introductory documentation and examples. - :paramref:`~.relationship.back_populates` - alternative form + :paramref:`_orm.relationship.back_populates` - alternative form of backref specification. - :func:`.backref` - allows control over :func:`.relationship` - configuration when using :paramref:`~.relationship.backref`. + :func:`.backref` - allows control over :func:`_orm.relationship` + configuration when using :paramref:`_orm.relationship.backref`. :param back_populates: Takes a string name and has the same meaning as - :paramref:`~.relationship.backref`, except the complementing + :paramref:`_orm.relationship.backref`, except the complementing property is **not** created automatically, and instead must be configured explicitly on the other mapper. The complementing property should also indicate - :paramref:`~.relationship.back_populates` to this relationship to + :paramref:`_orm.relationship.back_populates` to this relationship to ensure proper functioning. .. seealso:: @@ -334,7 +346,7 @@ class RelationshipProperty(StrategizedProperty): :ref:`relationships_backref` - Introductory documentation and examples. - :paramref:`~.relationship.backref` - alternative form + :paramref:`_orm.relationship.backref` - alternative form of backref specification. :param overlaps: @@ -397,7 +409,7 @@ class RelationshipProperty(StrategizedProperty): .. seealso:: :ref:`backref_cascade` - Full discussion and examples on how - the :paramref:`~.relationship.cascade_backrefs` option is used. + the :paramref:`_orm.relationship.cascade_backrefs` option is used. :param collection_class: a class or callable that returns a new list-holding object. will @@ -434,7 +446,7 @@ class RelationshipProperty(StrategizedProperty): duplicate innermost rows may be causing. .. versionchanged:: 0.9.0 - - :paramref:`~.relationship.distinct_target_key` now defaults to + :paramref:`_orm.relationship.distinct_target_key` now defaults to ``None``, so that the feature enables itself automatically for those cases where the innermost query targets a non-unique key. @@ -451,51 +463,55 @@ class RelationshipProperty(StrategizedProperty): a list of columns which are to be used as "foreign key" columns, or columns which refer to the value in a remote - column, within the context of this :func:`.relationship` - object's :paramref:`~.relationship.primaryjoin` condition. - That is, if the :paramref:`~.relationship.primaryjoin` - condition of this :func:`.relationship` is ``a.id == + column, within the context of this :func:`_orm.relationship` + object's :paramref:`_orm.relationship.primaryjoin` condition. + That is, if the :paramref:`_orm.relationship.primaryjoin` + condition of this :func:`_orm.relationship` is ``a.id == b.a_id``, and the values in ``b.a_id`` are required to be present in ``a.id``, then the "foreign key" column of this - :func:`.relationship` is ``b.a_id``. + :func:`_orm.relationship` is ``b.a_id``. - In normal cases, the :paramref:`~.relationship.foreign_keys` - parameter is **not required.** :func:`.relationship` will + In normal cases, the :paramref:`_orm.relationship.foreign_keys` + parameter is **not required.** :func:`_orm.relationship` will automatically determine which columns in the - :paramref:`~.relationship.primaryjoin` condition are to be + :paramref:`_orm.relationship.primaryjoin` condition are to be considered "foreign key" columns based on those - :class:`.Column` objects that specify :class:`.ForeignKey`, + :class:`_schema.Column` objects that specify + :class:`_schema.ForeignKey`, or are otherwise listed as referencing columns in a - :class:`.ForeignKeyConstraint` construct. - :paramref:`~.relationship.foreign_keys` is only needed when: + :class:`_schema.ForeignKeyConstraint` construct. + :paramref:`_orm.relationship.foreign_keys` is only needed when: 1. There is more than one way to construct a join from the local table to the remote table, as there are multiple foreign key references present. Setting ``foreign_keys`` will limit the - :func:`.relationship` to consider just those columns specified + :func:`_orm.relationship` + to consider just those columns specified here as "foreign". - 2. The :class:`.Table` being mapped does not actually have - :class:`.ForeignKey` or :class:`.ForeignKeyConstraint` + 2. The :class:`_schema.Table` being mapped does not actually have + :class:`_schema.ForeignKey` or + :class:`_schema.ForeignKeyConstraint` constructs present, often because the table was reflected from a database that does not support foreign key reflection (MySQL MyISAM). - 3. The :paramref:`~.relationship.primaryjoin` argument is used to + 3. The :paramref:`_orm.relationship.primaryjoin` + argument is used to construct a non-standard join condition, which makes use of columns or expressions that do not normally refer to their "parent" column, such as a join condition expressed by a complex comparison using a SQL function. - The :func:`.relationship` construct will raise informative + The :func:`_orm.relationship` construct will raise informative error messages that suggest the use of the - :paramref:`~.relationship.foreign_keys` parameter when + :paramref:`_orm.relationship.foreign_keys` parameter when presented with an ambiguous condition. In typical cases, - if :func:`.relationship` doesn't raise any exceptions, the - :paramref:`~.relationship.foreign_keys` parameter is usually + if :func:`_orm.relationship` doesn't raise any exceptions, the + :paramref:`_orm.relationship.foreign_keys` parameter is usually not needed. - :paramref:`~.relationship.foreign_keys` may also be passed as a + :paramref:`_orm.relationship.foreign_keys` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. @@ -504,7 +520,7 @@ class RelationshipProperty(StrategizedProperty): argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on - declarative evaluation of :func:`.relationship` arguments. + declarative evaluation of :func:`_orm.relationship` arguments. .. seealso:: @@ -513,7 +529,8 @@ class RelationshipProperty(StrategizedProperty): :ref:`relationship_custom_foreign` :func:`.foreign` - allows direct annotation of the "foreign" - columns within a :paramref:`~.relationship.primaryjoin` condition. + columns within a :paramref:`_orm.relationship.primaryjoin` + condition. :param info: Optional data dictionary which will be populated into the :attr:`.MapperProperty.info` attribute of this object. @@ -530,12 +547,12 @@ class RelationshipProperty(StrategizedProperty): is guaranteed to have one or at least one entry. The option supports the same "nested" and "unnested" options as - that of :paramref:`.joinedload.innerjoin`. See that flag + that of :paramref:`_orm.joinedload.innerjoin`. See that flag for details on nested / unnested behaviors. .. seealso:: - :paramref:`.joinedload.innerjoin` - the option as specified by + :paramref:`_orm.joinedload.innerjoin` - the option as specified by loader option, including detail on nesting behavior. :ref:`what_kind_of_loading` - Discussion of some details of @@ -572,7 +589,7 @@ class RelationshipProperty(StrategizedProperty): * ``joined`` - items should be loaded "eagerly" in the same query as that of the parent, using a JOIN or LEFT OUTER JOIN. Whether the join is "outer" or not is determined by the - :paramref:`~.relationship.innerjoin` parameter. + :paramref:`_orm.relationship.innerjoin` parameter. * ``subquery`` - items should be loaded "eagerly" as the parents are loaded, using one additional SQL statement, which issues a JOIN to @@ -611,7 +628,7 @@ class RelationshipProperty(StrategizedProperty): .. versionadded:: 1.1 * ``dynamic`` - the attribute will return a pre-configured - :class:`.Query` object for all read + :class:`_query.Query` object for all read operations, onto which further filtering operations can be applied before iterating the results. See the section :ref:`dynamic_relationship` for more details. @@ -641,7 +658,8 @@ class RelationshipProperty(StrategizedProperty): "attached" to a :class:`.Session` but is not part of its pending collection. - The :paramref:`~.relationship.load_on_pending` flag does not improve + The :paramref:`_orm.relationship.load_on_pending` + flag does not improve behavior when the ORM is used normally - object references should be constructed at the object level, not at the foreign key level, so that they are present in an ordinary way before a flush proceeds. @@ -656,12 +674,15 @@ class RelationshipProperty(StrategizedProperty): :param order_by: indicates the ordering that should be applied when loading these - items. :paramref:`~.relationship.order_by` is expected to refer to - one of the :class:`.Column` objects to which the target class is + items. :paramref:`_orm.relationship.order_by` + is expected to refer to + one of the :class:`_schema.Column` + objects to which the target class is mapped, or the attribute itself bound to the target class which refers to the column. - :paramref:`~.relationship.order_by` may also be passed as a callable + :paramref:`_orm.relationship.order_by` + may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. @@ -669,7 +690,7 @@ class RelationshipProperty(StrategizedProperty): argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on - declarative evaluation of :func:`.relationship` arguments. + declarative evaluation of :func:`_orm.relationship` arguments. :param passive_deletes=False: Indicates loading behavior during delete operations. @@ -706,7 +727,8 @@ class RelationshipProperty(StrategizedProperty): When True, it is assumed that ``ON UPDATE CASCADE`` is configured on the foreign key in the database, and that the database will handle propagation of an UPDATE from a source column to - dependent rows. When False, the SQLAlchemy :func:`.relationship` + dependent rows. When False, the SQLAlchemy + :func:`_orm.relationship` construct will attempt to emit its own UPDATE statements to modify related targets. However note that SQLAlchemy **cannot** emit an UPDATE for more than one level of cascade. Also, @@ -744,7 +766,7 @@ class RelationshipProperty(StrategizedProperty): list (i.e. both tables contain a foreign key to each other). If a flush operation returns an error that a "cyclical dependency" was detected, this is a cue that you might want to - use :paramref:`~.relationship.post_update` to "break" the cycle. + use :paramref:`_orm.relationship.post_update` to "break" the cycle. .. seealso:: @@ -758,7 +780,7 @@ class RelationshipProperty(StrategizedProperty): foreign key relationships of the parent and child tables (or association table). - :paramref:`~.relationship.primaryjoin` may also be passed as a + :paramref:`_orm.relationship.primaryjoin` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. @@ -767,7 +789,7 @@ class RelationshipProperty(StrategizedProperty): argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on - declarative evaluation of :func:`.relationship` arguments. + declarative evaluation of :func:`_orm.relationship` arguments. .. seealso:: @@ -777,7 +799,7 @@ class RelationshipProperty(StrategizedProperty): used for self-referential relationships, indicates the column or list of columns that form the "remote side" of the relationship. - :paramref:`.relationship.remote_side` may also be passed as a + :paramref:`_orm.relationship.remote_side` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. @@ -786,24 +808,26 @@ class RelationshipProperty(StrategizedProperty): argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on - declarative evaluation of :func:`.relationship` arguments. + declarative evaluation of :func:`_orm.relationship` arguments. .. seealso:: :ref:`self_referential` - in-depth explanation of how - :paramref:`~.relationship.remote_side` + :paramref:`_orm.relationship.remote_side` is used to configure self-referential relationships. :func:`.remote` - an annotation function that accomplishes the - same purpose as :paramref:`~.relationship.remote_side`, typically - when a custom :paramref:`~.relationship.primaryjoin` condition + same purpose as :paramref:`_orm.relationship.remote_side`, + typically + when a custom :paramref:`_orm.relationship.primaryjoin` condition is used. :param query_class: - a :class:`.Query` subclass that will be used as the base of the + a :class:`_query.Query` + subclass that will be used as the base of the "appender query" returned by a "dynamic" relationship, that is, a relationship that specifies ``lazy="dynamic"`` or was - otherwise constructed using the :func:`.orm.dynamic_loader` + otherwise constructed using the :func:`_orm.dynamic_loader` function. .. seealso:: @@ -817,7 +841,7 @@ class RelationshipProperty(StrategizedProperty): computed based on the foreign key relationships of the association and child tables. - :paramref:`~.relationship.secondaryjoin` may also be passed as a + :paramref:`_orm.relationship.secondaryjoin` may also be passed as a callable function which is evaluated at mapper initialization time, and may be passed as a Python-evaluable string when using Declarative. @@ -826,7 +850,7 @@ class RelationshipProperty(StrategizedProperty): argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See :ref:`declarative_relationship_eval` for details on - declarative evaluation of :func:`.relationship` arguments. + declarative evaluation of :func:`_orm.relationship` arguments. .. seealso:: @@ -837,31 +861,36 @@ class RelationshipProperty(StrategizedProperty): from being associated with more than one parent at a time. This is used for many-to-one or many-to-many relationships that should be treated either as one-to-one or one-to-many. Its usage - is optional, except for :func:`.relationship` constructs which + is optional, except for :func:`_orm.relationship` constructs which are many-to-one or many-to-many and also specify the ``delete-orphan`` cascade option. The - :func:`.relationship` construct itself will raise an error + :func:`_orm.relationship` construct itself will raise an error instructing when this option is required. .. seealso:: :ref:`unitofwork_cascades` - includes detail on when the - :paramref:`~.relationship.single_parent` flag may be appropriate. + :paramref:`_orm.relationship.single_parent` + flag may be appropriate. :param uselist: a boolean that indicates if this property should be loaded as a list or a scalar. In most cases, this value is determined - automatically by :func:`.relationship` at mapper configuration + automatically by :func:`_orm.relationship` at mapper configuration time, based on the type and direction of the relationship - one to many forms a list, many to one forms a scalar, many to many is a list. If a scalar is desired where normally a list would be present, such as a bi-directional - one-to-one relationship, set :paramref:`~.relationship.uselist` to + one-to-one relationship, set :paramref:`_orm.relationship.uselist` + to False. - The :paramref:`~.relationship.uselist` flag is also available on an - existing :func:`.relationship` construct as a read-only attribute, - which can be used to determine if this :func:`.relationship` deals + The :paramref:`_orm.relationship.uselist` + flag is also available on an + existing :func:`_orm.relationship` + construct as a read-only attribute, + which can be used to determine if this :func:`_orm.relationship` + deals with collections or scalar attributes:: >>> User.addresses.property.uselist @@ -871,18 +900,20 @@ class RelationshipProperty(StrategizedProperty): :ref:`relationships_one_to_one` - Introduction to the "one to one" relationship pattern, which is typically when the - :paramref:`~.relationship.uselist` flag is needed. + :paramref:`_orm.relationship.uselist` flag is needed. :param viewonly=False: when set to True, the relationship is used only for loading objects, - and not for any persistence operation. A :func:`.relationship` - which specifies :paramref:`~.relationship.viewonly` can work + and not for any persistence operation. A :func:`_orm.relationship` + which specifies :paramref:`_orm.relationship.viewonly` can work with a wider range of SQL operations within the - :paramref:`~.relationship.primaryjoin` condition, including + :paramref:`_orm.relationship.primaryjoin` condition, including operations that feature the use of a variety of comparison operators - as well as SQL functions such as :func:`~.sql.expression.cast`. The - :paramref:`~.relationship.viewonly` flag is also of general use when - defining any kind of :func:`~.relationship` that doesn't represent + as well as SQL functions such as :func:`_expression.cast`. The + :paramref:`_orm.relationship.viewonly` + flag is also of general use when + defining any kind of :func:`_orm.relationship` + that doesn't represent the full set of related objects, to prevent modifications of the collection from resulting in persistence operations. @@ -893,8 +924,8 @@ class RelationshipProperty(StrategizedProperty): be accessed via read. Towards this behavior, it is also not appropriate for the viewonly=True relationship to have any kind of persistence cascade settings, nor should it be the target of - either :paramref:`.relationship.backref` or - :paramref:`.relationship.back_populates`, as backrefs imply + either :paramref:`_orm.relationship.backref` or + :paramref:`_orm.relationship.back_populates`, as backrefs imply in-Python mutation of the attribute. SQLAlchemy may emit warnings for some or all of these conditions as of the 1.3 and 1.4 series of SQLAlchemy and will eventually be disallowed. @@ -1077,22 +1108,22 @@ class RelationshipProperty(StrategizedProperty): """The target entity referred to by this :class:`.RelationshipProperty.Comparator`. - This is either a :class:`.Mapper` or :class:`.AliasedInsp` + This is either a :class:`_orm.Mapper` or :class:`.AliasedInsp` object. This is the "target" or "remote" side of the - :func:`.relationship`. + :func:`_orm.relationship`. """ return self.property.entity @util.memoized_property def mapper(self): - """The target :class:`.Mapper` referred to by this + """The target :class:`_orm.Mapper` referred to by this :class:`.RelationshipProperty.Comparator`. This is the "target" or "remote" side of the - :func:`.relationship`. + :func:`_orm.relationship`. """ return self.property.mapper @@ -1147,7 +1178,7 @@ class RelationshipProperty(StrategizedProperty): def in_(self, other): """Produce an IN clause - this is not implemented - for :func:`~.orm.relationship`-based attributes at this time. + for :func:`_orm.relationship`-based attributes at this time. """ raise NotImplementedError( @@ -1337,7 +1368,7 @@ class RelationshipProperty(StrategizedProperty): related.my_id=my_table.id)) :meth:`~.RelationshipProperty.Comparator.any` is only - valid for collections, i.e. a :func:`.relationship` + valid for collections, i.e. a :func:`_orm.relationship` that has ``uselist=True``. For scalar references, use :meth:`~.RelationshipProperty.Comparator.has`. @@ -1373,7 +1404,7 @@ class RelationshipProperty(StrategizedProperty): using a join. :meth:`~.RelationshipProperty.Comparator.has` is only - valid for scalar references, i.e. a :func:`.relationship` + valid for scalar references, i.e. a :func:`_orm.relationship` that has ``uselist=False``. For collection references, use :meth:`~.RelationshipProperty.Comparator.any`. @@ -1390,7 +1421,7 @@ class RelationshipProperty(StrategizedProperty): :meth:`~.RelationshipProperty.Comparator.contains` is only valid for a collection, i.e. a - :func:`~.orm.relationship` that implements + :func:`_orm.relationship` that implements one-to-many or many-to-many with ``uselist=True``. When used in a simple one-to-many context, an @@ -1436,7 +1467,8 @@ class RelationshipProperty(StrategizedProperty): explicit "outer joins" will need to be used instead. See :meth:`~.RelationshipProperty.Comparator.any` for a less-performant alternative using EXISTS, or refer - to :meth:`.Query.outerjoin` as well as :ref:`ormtutorial_joins` + to :meth:`_query.Query.outerjoin` + as well as :ref:`ormtutorial_joins` for more details on constructing outer joins. """ @@ -1521,7 +1553,7 @@ class RelationshipProperty(StrategizedProperty): * Comparisons against collections are not supported. Use :meth:`~.RelationshipProperty.Comparator.contains` - in conjunction with :func:`~.expression.not_`. + in conjunction with :func:`_expression.not_`. * Compared to a scalar one-to-many, will produce a clause that compares the target columns in the parent to the given target. @@ -1533,7 +1565,7 @@ class RelationshipProperty(StrategizedProperty): comparisons, such as those which use OR. Use explicit joins, outerjoins, or :meth:`~.RelationshipProperty.Comparator.has` in - conjunction with :func:`~.expression.not_` for + conjunction with :func:`_expression.not_` for more comprehensive non-many-to-one scalar membership tests. * Comparisons against ``None`` given in a one-to-many @@ -1984,7 +2016,7 @@ class RelationshipProperty(StrategizedProperty): @util.memoized_property def mapper(self): - """Return the targeted :class:`.Mapper` for this + """Return the targeted :class:`_orm.Mapper` for this :class:`.RelationshipProperty`. This is a lazy-initializing static attribute. @@ -2210,7 +2242,7 @@ class RelationshipProperty(StrategizedProperty): def _generate_backref(self): """Interpret the 'backref' instruction to create a - :func:`.relationship` complementary to this one.""" + :func:`_orm.relationship` complementary to this one.""" if self.parent.non_primary: return diff --git a/lib/sqlalchemy/orm/scoping.py b/lib/sqlalchemy/orm/scoping.py index 0d1e2a965b..1090501ca1 100644 --- a/lib/sqlalchemy/orm/scoping.py +++ b/lib/sqlalchemy/orm/scoping.py @@ -27,7 +27,7 @@ class scoped_session(object): session_factory = None """The `session_factory` provided to `__init__` is stored in this attribute and may be accessed at a later time. This can be useful when - a new non-scoped :class:`.Session` or :class:`.Connection` to the + a new non-scoped :class:`.Session` or :class:`_engine.Connection` to the database is needed.""" def __init__(self, session_factory, scopefunc=None): @@ -112,7 +112,8 @@ class scoped_session(object): self.session_factory.configure(**kwargs) def query_property(self, query_cls=None): - """return a class property which produces a :class:`.Query` object + """return a class property which produces a :class:`_query.Query` + object against the class and the current :class:`.Session` when called. e.g.:: diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index 98fa819b1d..61442756d9 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -103,7 +103,7 @@ class SessionTransaction(object): :class:`.SessionTransaction` is a mostly behind-the-scenes object not normally referenced directly by application code. It coordinates - among multiple :class:`.Connection` objects, maintaining a database + among multiple :class:`_engine.Connection` objects, maintaining a database transaction for each one individually, committing or rolling them back all at once. It also provides optional two-phase commit behavior which can augment this coordination operation. @@ -127,8 +127,10 @@ class SessionTransaction(object): its default mode of ``autocommit=False`` whenever the "autobegin" process takes place, associated with no database connections. As the :class:`.Session` is called upon to emit SQL on behalf of various - :class:`.Engine` or :class:`.Connection` objects, a corresponding - :class:`.Connection` and associated :class:`.Transaction` is added to a + :class:`_engine.Engine` or :class:`_engine.Connection` objects, + a corresponding + :class:`_engine.Connection` and associated :class:`.Transaction` + is added to a collection within the :class:`.SessionTransaction` object, becoming one of the connection/transaction pairs maintained by the :class:`.SessionTransaction`. The start of a :class:`.SessionTransaction` @@ -698,22 +700,27 @@ class Session(_SessionClassMethods): :meth:`~.Session.flush` are rarely needed; you usually only need to call :meth:`~.Session.commit` (which flushes) to finalize changes. - :param bind: An optional :class:`.Engine` or :class:`.Connection` to + :param bind: An optional :class:`_engine.Engine` or + :class:`_engine.Connection` to which this ``Session`` should be bound. When specified, all SQL operations performed by this session will execute via this connectable. :param binds: A dictionary which may specify any number of - :class:`.Engine` or :class:`.Connection` objects as the source of + :class:`_engine.Engine` or :class:`_engine.Connection` + objects as the source of connectivity for SQL operations on a per-entity basis. The keys of the dictionary consist of any series of mapped classes, arbitrary Python classes that are bases for mapped classes, - :class:`.Table` objects and :class:`.Mapper` objects. The - values of the dictionary are then instances of :class:`.Engine` - or less commonly :class:`.Connection` objects. Operations which + :class:`_schema.Table` objects and :class:`_orm.Mapper` objects. + The + values of the dictionary are then instances of + :class:`_engine.Engine` + or less commonly :class:`_engine.Connection` objects. + Operations which proceed relative to a particular mapped class will consult this dictionary for the closest matching entity in order to determine - which :class:`.Engine` should be used for a particular SQL + which :class:`_engine.Engine` should be used for a particular SQL operation. The complete heuristics for resolution are described at :meth:`.Session.get_bind`. Usage looks like:: @@ -772,7 +779,7 @@ class Session(_SessionClassMethods): :param query_cls: Class which should be used to create new Query objects, as returned by the :meth:`~.Session.query` method. - Defaults to :class:`.Query`. + Defaults to :class:`_query.Query`. :param twophase: When ``True``, all transactions will be started as a "two phase" transaction, i.e. using the "two phase" semantics @@ -1023,27 +1030,28 @@ class Session(_SessionClassMethods): execution_options=None, **kw ): - r"""Return a :class:`.Connection` object corresponding to this + r"""Return a :class:`_engine.Connection` object corresponding to this :class:`.Session` object's transactional state. If this :class:`.Session` is configured with ``autocommit=False``, - either the :class:`.Connection` corresponding to the current + either the :class:`_engine.Connection` corresponding to the current transaction is returned, or if no transaction is in progress, a new - one is begun and the :class:`.Connection` returned (note that no + one is begun and the :class:`_engine.Connection` + returned (note that no transactional state is established with the DBAPI until the first SQL statement is emitted). Alternatively, if this :class:`.Session` is configured with - ``autocommit=True``, an ad-hoc :class:`.Connection` is returned - using :meth:`.Engine.connect` on the underlying - :class:`.Engine`. + ``autocommit=True``, an ad-hoc :class:`_engine.Connection` is returned + using :meth:`_engine.Engine.connect` on the underlying + :class:`_engine.Engine`. Ambiguity in multi-bind or unbound :class:`.Session` objects can be resolved through any of the optional keyword arguments. This ultimately makes usage of the :meth:`.get_bind` method for resolution. :param bind: - Optional :class:`.Engine` to be used as the bind. If + Optional :class:`_engine.Engine` to be used as the bind. If this engine is already involved in an ongoing transaction, that connection will be used. This argument takes precedence over ``mapper``, ``clause``. @@ -1054,20 +1062,21 @@ class Session(_SessionClassMethods): ``clause``. :param clause: - A :class:`.ClauseElement` (i.e. :func:`~.sql.expression.select`, - :func:`~.sql.expression.text`, + A :class:`_expression.ClauseElement` (i.e. + :func:`_expression.select`, + :func:`_expression.text`, etc.) which will be used to locate a bind, if a bind cannot otherwise be identified. - :param close_with_result: Passed to :meth:`.Engine.connect`, - indicating the :class:`.Connection` should be considered + :param close_with_result: Passed to :meth:`_engine.Engine.connect`, + indicating the :class:`_engine.Connection` should be considered "single use", automatically closing when the first result set is closed. This flag only has an effect if this :class:`.Session` is configured with ``autocommit=True`` and does not already have a transaction in progress. :param execution_options: a dictionary of execution options that will - be passed to :meth:`.Connection.execution_options`, **when the + be passed to :meth:`_engine.Connection.execution_options`, **when the connection is first procured only**. If the connection is already present within the :class:`.Session`, a warning is emitted and the arguments are ignored. @@ -1112,8 +1121,8 @@ class Session(_SessionClassMethods): Returns a :class:`.ResultProxy` representing results of the statement execution, in the same manner as that of an - :class:`.Engine` or - :class:`.Connection`. + :class:`_engine.Engine` or + :class:`_engine.Connection`. E.g.:: @@ -1122,14 +1131,14 @@ class Session(_SessionClassMethods): ) :meth:`~.Session.execute` accepts any executable clause construct, - such as :func:`~.sql.expression.select`, - :func:`~.sql.expression.insert`, - :func:`~.sql.expression.update`, - :func:`~.sql.expression.delete`, and - :func:`~.sql.expression.text`. Plain SQL strings can be passed + such as :func:`_expression.select`, + :func:`_expression.insert`, + :func:`_expression.update`, + :func:`_expression.delete`, and + :func:`_expression.text`. Plain SQL strings can be passed as well, which in the case of :meth:`.Session.execute` only will be interpreted the same as if it were passed via a - :func:`~.expression.text` construct. That is, the following usage:: + :func:`_expression.text` construct. That is, the following usage:: result = session.execute( "SELECT * FROM user WHERE id=:param", @@ -1146,7 +1155,7 @@ class Session(_SessionClassMethods): The second positional argument to :meth:`.Session.execute` is an optional parameter set. Similar to that of - :meth:`.Connection.execute`, whether this is passed as a single + :meth:`_engine.Connection.execute`, whether this is passed as a single dictionary, or a sequence of dictionaries, determines whether the DBAPI cursor's ``execute()`` or ``executemany()`` is used to execute the statement. An INSERT construct may be invoked for a single row:: @@ -1163,14 +1172,16 @@ class Session(_SessionClassMethods): ]) The statement is executed within the current transactional context of - this :class:`.Session`. The :class:`.Connection` which is used + this :class:`.Session`. The :class:`_engine.Connection` + which is used to execute the statement can also be acquired directly by calling the :meth:`.Session.connection` method. Both methods use a rule-based resolution scheme in order to determine the - :class:`.Connection`, which in the average case is derived directly + :class:`_engine.Connection`, + which in the average case is derived directly from the "bind" of the :class:`.Session` itself, and in other cases can be based on the :func:`.mapper` - and :class:`.Table` objects passed to the method; see the + and :class:`_schema.Table` objects passed to the method; see the documentation for :meth:`.Session.get_bind` for a full description of this scheme. @@ -1180,7 +1191,8 @@ class Session(_SessionClassMethods): method is returned with the "close_with_result" flag set to true; the significance of this flag is that if this :class:`.Session` is autocommitting and does not have a transaction-dedicated - :class:`.Connection` available, a temporary :class:`.Connection` is + :class:`_engine.Connection` available, a temporary + :class:`_engine.Connection` is established for the statement execution, which is closed (meaning, returned to the connection pool) when the :class:`.ResultProxy` has consumed all available data. This applies *only* when the @@ -1189,7 +1201,7 @@ class Session(_SessionClassMethods): :param clause: An executable statement (i.e. an :class:`.Executable` expression - such as :func:`.expression.select`) or string SQL statement + such as :func:`_expression.select`) or string SQL statement to be executed. :param params: @@ -1206,7 +1218,7 @@ class Session(_SessionClassMethods): for more details. :param bind: - Optional :class:`.Engine` to be used as the bind. If + Optional :class:`_engine.Engine` to be used as the bind. If this engine is already involved in an ongoing transaction, that connection will be used. This argument takes precedence over ``mapper`` and ``clause`` when locating @@ -1224,7 +1236,8 @@ class Session(_SessionClassMethods): :ref:`connections_toplevel` - Further information on direct statement execution. - :meth:`.Connection.execute` - core level statement execution + :meth:`_engine.Connection.execute` + - core level statement execution method, which is :meth:`.Session.execute` ultimately uses in order to execute the statement. @@ -1266,8 +1279,9 @@ class Session(_SessionClassMethods): """Close this Session, using connection invalidation. This is a variant of :meth:`.Session.close` that will additionally - ensure that the :meth:`.Connection.invalidate` method will be called - on all :class:`.Connection` objects. This can be called when + ensure that the :meth:`_engine.Connection.invalidate` + method will be called + on all :class:`_engine.Connection` objects. This can be called when the database is known to be in a state where the connections are no longer safe to be used. @@ -1342,17 +1356,20 @@ class Session(_SessionClassMethods): ) def bind_mapper(self, mapper, bind): - """Associate a :class:`.Mapper` or arbitrary Python class with a - "bind", e.g. an :class:`.Engine` or :class:`.Connection`. + """Associate a :class:`_orm.Mapper` or arbitrary Python class with a + "bind", e.g. an :class:`_engine.Engine` or :class:`_engine.Connection` + . The given entity is added to a lookup used by the :meth:`.Session.get_bind` method. - :param mapper: a :class:`.Mapper` object, or an instance of a mapped + :param mapper: a :class:`_orm.Mapper` object, + or an instance of a mapped class, or any Python class that is the base of a set of mapped classes. - :param bind: an :class:`.Engine` or :class:`.Connection` object. + :param bind: an :class:`_engine.Engine` or :class:`_engine.Connection` + object. .. seealso:: @@ -1367,17 +1384,20 @@ class Session(_SessionClassMethods): self._add_bind(mapper, bind) def bind_table(self, table, bind): - """Associate a :class:`.Table` with a "bind", e.g. an :class:`.Engine` - or :class:`.Connection`. + """Associate a :class:`_schema.Table` with a "bind", e.g. an + :class:`_engine.Engine` + or :class:`_engine.Connection`. - The given :class:`.Table` is added to a lookup used by the + The given :class:`_schema.Table` is added to a lookup used by the :meth:`.Session.get_bind` method. - :param table: a :class:`.Table` object, which is typically the target + :param table: a :class:`_schema.Table` object, + which is typically the target of an ORM mapping, or is present within a selectable that is mapped. - :param bind: an :class:`.Engine` or :class:`.Connection` object. + :param bind: an :class:`_engine.Engine` or :class:`_engine.Connection` + object. .. seealso:: @@ -1394,9 +1414,9 @@ class Session(_SessionClassMethods): def get_bind(self, mapper=None, clause=None): """Return a "bind" to which this :class:`.Session` is bound. - The "bind" is usually an instance of :class:`.Engine`, + The "bind" is usually an instance of :class:`_engine.Engine`, except in the case where the :class:`.Session` has been - explicitly bound directly to a :class:`.Connection`. + explicitly bound directly to a :class:`_engine.Connection`. For a multiply-bound or unbound :class:`.Session`, the ``mapper`` or ``clause`` arguments are used to determine the @@ -1416,15 +1436,15 @@ class Session(_SessionClassMethods): present in the ``__mro__`` of the mapped class, from more specific superclasses to more general. 2. if clause given and session.binds is present, - locate a bind based on :class:`.Table` objects + locate a bind based on :class:`_schema.Table` objects found in the given clause present in session.binds. 3. if session.bind is present, return that. 4. if clause given, attempt to return a bind - linked to the :class:`.MetaData` ultimately + linked to the :class:`_schema.MetaData` ultimately associated with the clause. 5. if mapper given, attempt to return a bind - linked to the :class:`.MetaData` ultimately - associated with the :class:`.Table` or other + linked to the :class:`_schema.MetaData` ultimately + associated with the :class:`_schema.Table` or other selectable to which the mapper is mapped. 6. No bind can be found, :exc:`~sqlalchemy.exc.UnboundExecutionError` is raised. @@ -1436,19 +1456,24 @@ class Session(_SessionClassMethods): :param mapper: Optional :func:`.mapper` mapped class or instance of - :class:`.Mapper`. The bind can be derived from a :class:`.Mapper` + :class:`_orm.Mapper`. The bind can be derived from a + :class:`_orm.Mapper` first by consulting the "binds" map associated with this - :class:`.Session`, and secondly by consulting the :class:`.MetaData` - associated with the :class:`.Table` to which the :class:`.Mapper` + :class:`.Session`, and secondly by consulting the + :class:`_schema.MetaData` + associated with the :class:`_schema.Table` to which the + :class:`_orm.Mapper` is mapped for a bind. :param clause: - A :class:`.ClauseElement` (i.e. :func:`~.sql.expression.select`, - :func:`~.sql.expression.text`, + A :class:`_expression.ClauseElement` (i.e. + :func:`_expression.select`, + :func:`_expression.text`, etc.). If the ``mapper`` argument is not present or could not produce a bind, the given expression construct will be searched - for a bound element, typically a :class:`.Table` associated with - bound :class:`.MetaData`. + for a bound element, typically a :class:`_schema.Table` + associated with + bound :class:`_schema.MetaData`. .. seealso:: @@ -1517,7 +1542,7 @@ class Session(_SessionClassMethods): ) def query(self, *entities, **kwargs): - """Return a new :class:`.Query` object corresponding to this + """Return a new :class:`_query.Query` object corresponding to this :class:`.Session`.""" return self._query_cls(entities, self, **kwargs) @@ -1564,9 +1589,9 @@ class Session(_SessionClassMethods): PASSIVE_NO_RESULT. In all other cases the instance is returned. .. versionchanged:: 1.4.0 - the :meth:`.Session._identity_lookup` - method was moved from :class:`.Query` to + method was moved from :class:`_query.Query` to :class:`.Session`, to avoid having to instantiate the - :class:`.Query` object. + :class:`_query.Query` object. """ @@ -1647,7 +1672,8 @@ class Session(_SessionClassMethods): :param with_for_update: optional boolean ``True`` indicating FOR UPDATE should be used, or may be a dictionary containing flags to indicate a more specific set of FOR UPDATE flags for the SELECT; - flags should match the parameters of :meth:`.Query.with_for_update`. + flags should match the parameters of + :meth:`_query.Query.with_for_update`. Supersedes the :paramref:`.Session.refresh.lockmode` parameter. .. versionadded:: 1.2 @@ -2342,7 +2368,7 @@ class Session(_SessionClassMethods): :meth:`.enable_relationship_loading` exists to serve special use cases and is not recommended for general use. - Accesses of attributes mapped with :func:`.relationship` + Accesses of attributes mapped with :func:`_orm.relationship` will attempt to load a value from the database using this :class:`.Session` as the source of connectivity. The values will be loaded based on foreign key and primary key values @@ -2360,7 +2386,7 @@ class Session(_SessionClassMethods): is what was already loaded from a foreign-key-holding value. The :meth:`.Session.enable_relationship_loading` method is - similar to the ``load_on_pending`` flag on :func:`.relationship`. + similar to the ``load_on_pending`` flag on :func:`_orm.relationship`. Unlike that flag, :meth:`.Session.enable_relationship_loading` allows an object to remain transient while still being able to load related items. @@ -2379,7 +2405,7 @@ class Session(_SessionClassMethods): .. seealso:: - ``load_on_pending`` at :func:`.relationship` - this flag + ``load_on_pending`` at :func:`_orm.relationship` - this flag allows per-relationship loading of many-to-ones on items that are pending. @@ -2743,7 +2769,8 @@ class Session(_SessionClassMethods): large numbers of simple rows. The values within the dictionaries as given are typically passed - without modification into Core :meth:`.Insert` constructs, after + without modification into Core :meth:`_expression.Insert` constructs, + after organizing the values within them across the tables to which the given mapper is mapped. @@ -2761,7 +2788,8 @@ class Session(_SessionClassMethods): **before using this method, and fully test and confirm the functionality of all code developed using these systems.** - :param mapper: a mapped class, or the actual :class:`.Mapper` object, + :param mapper: a mapped class, or the actual :class:`_orm.Mapper` + object, representing the single kind of object represented within the mapping list. @@ -2852,7 +2880,8 @@ class Session(_SessionClassMethods): **before using this method, and fully test and confirm the functionality of all code developed using these systems.** - :param mapper: a mapped class, or the actual :class:`.Mapper` object, + :param mapper: a mapped class, or the actual :class:`_orm.Mapper` + object, representing the single kind of object represented within the mapping list. @@ -3014,7 +3043,7 @@ class Session(_SessionClassMethods): :class:`.Session` has actually begun to use DBAPI resources is to implement a listener using the :meth:`.SessionEvents.after_begin` method, which will deliver both the :class:`.Session` as well as the - target :class:`.Connection` to a user-defined event listener. + target :class:`_engine.Connection` to a user-defined event listener. The "partial rollback" state refers to when an "inner" transaction, typically used during a flush, encounters an error and emits a @@ -3147,7 +3176,8 @@ class sessionmaker(_SessionClassMethods): The class also includes a method :meth:`.configure`, which can be used to specify additional keyword arguments to the factory, which will take effect for subsequent :class:`.Session` objects generated. - This is usually used to associate one or more :class:`.Engine` objects + This is usually used to associate one or more :class:`_engine.Engine` + objects with an existing :class:`.sessionmaker` factory before it is first used:: @@ -3183,7 +3213,8 @@ class sessionmaker(_SessionClassMethods): accepted by :class:`.Session` directly. See the :meth:`.Session.__init__` docstring for more details on parameters. - :param bind: a :class:`.Engine` or other :class:`.Connectable` with + :param bind: a :class:`_engine.Engine` or other :class:`.Connectable` + with which newly created :class:`.Session` objects will be associated. :param class\_: class to use in order to create new :class:`.Session` objects. Defaults to :class:`.Session`. diff --git a/lib/sqlalchemy/orm/state.py b/lib/sqlalchemy/orm/state.py index 5a885b118d..48546f24ea 100644 --- a/lib/sqlalchemy/orm/state.py +++ b/lib/sqlalchemy/orm/state.py @@ -47,7 +47,7 @@ class InstanceState(interfaces.InspectionAttrInfo): status within a particular :class:`.Session` and details about data on individual attributes. The public API in order to acquire a :class:`.InstanceState` object - is to use the :func:`.inspect` system:: + is to use the :func:`_sa.inspect` system:: >>> from sqlalchemy import inspect >>> insp = inspect(some_mapped_object) @@ -273,7 +273,7 @@ class InstanceState(interfaces.InspectionAttrInfo): """Return the mapped identity of the mapped object. This is the primary key identity as persisted by the ORM which can always be passed directly to - :meth:`.Query.get`. + :meth:`_query.Query.get`. Returns ``None`` if the object has no primary key identity. @@ -316,7 +316,7 @@ class InstanceState(interfaces.InspectionAttrInfo): @util.memoized_property def mapper(self): - """Return the :class:`.Mapper` used for this mapped object.""" + """Return the :class:`_orm.Mapper` used for this mapped object.""" return self.manager.mapper @property @@ -894,7 +894,8 @@ class AttributeState(object): The attribute history system tracks changes on a **per flush basis**. Each time the :class:`.Session` is flushed, the history of each attribute is reset to empty. The :class:`.Session` by - default autoflushes each time a :class:`.Query` is invoked. For + default autoflushes each time a :class:`_query.Query` is invoked. + For options on how to control this, see :ref:`session_flushing`. @@ -920,7 +921,8 @@ class AttributeState(object): The attribute history system tracks changes on a **per flush basis**. Each time the :class:`.Session` is flushed, the history of each attribute is reset to empty. The :class:`.Session` by - default autoflushes each time a :class:`.Query` is invoked. For + default autoflushes each time a :class:`_query.Query` is invoked. + For options on how to control this, see :ref:`session_flushing`. .. seealso:: diff --git a/lib/sqlalchemy/orm/strategies.py b/lib/sqlalchemy/orm/strategies.py index bb08d31ea1..2e9b2f3169 100644 --- a/lib/sqlalchemy/orm/strategies.py +++ b/lib/sqlalchemy/orm/strategies.py @@ -1374,7 +1374,7 @@ class SubqueryLoader(PostLoader): return q class _SubqCollections(object): - """Given a :class:`.Query` used to emit the "subquery load", + """Given a :class:`_query.Query` used to emit the "subquery load", provide a load interface that executes the query at the first moment a value is needed. diff --git a/lib/sqlalchemy/orm/strategy_options.py b/lib/sqlalchemy/orm/strategy_options.py index 6475f79de9..2fd628d0b6 100644 --- a/lib/sqlalchemy/orm/strategy_options.py +++ b/lib/sqlalchemy/orm/strategy_options.py @@ -34,26 +34,29 @@ from ..sql.traversals import HasCacheKey class Load(HasCacheKey, Generative, MapperOption): """Represents loader options which modify the state of a - :class:`.Query` in order to affect how various mapped attributes are + :class:`_query.Query` in order to affect how various mapped attributes are loaded. - The :class:`.Load` object is in most cases used implicitly behind the - scenes when one makes use of a query option like :func:`.joinedload`, - :func:`.defer`, or similar. However, the :class:`.Load` object + The :class:`_orm.Load` object is in most cases used implicitly behind the + scenes when one makes use of a query option like :func:`_orm.joinedload`, + :func:`.defer`, or similar. However, the :class:`_orm.Load` object can also be used directly, and in some cases can be useful. - To use :class:`.Load` directly, instantiate it with the target mapped + To use :class:`_orm.Load` directly, instantiate it with the target mapped class as the argument. This style of usage is - useful when dealing with a :class:`.Query` that has multiple entities:: + useful when dealing with a :class:`_query.Query` + that has multiple entities:: myopt = Load(MyClass).joinedload("widgets") - The above ``myopt`` can now be used with :meth:`.Query.options`, where it + The above ``myopt`` can now be used with :meth:`_query.Query.options`, + where it will only take effect for the ``MyClass`` entity:: session.query(MyClass, MyOtherClass).options(myopt) - One case where :class:`.Load` is useful as public API is when specifying + One case where :class:`_orm.Load` + is useful as public API is when specifying "wildcard" options that only take effect for a certain class:: session.query(Order).options(Load(Order).lazyload('*')) @@ -363,7 +366,8 @@ class Load(HasCacheKey, Generative, MapperOption): @_generative def options(self, *opts): - r"""Apply a series of options as sub-options to this :class:`.Load` + r"""Apply a series of options as sub-options to this + :class:`_orm.Load` object. E.g.:: @@ -379,8 +383,8 @@ class Load(HasCacheKey, Generative, MapperOption): ) :param \*opts: A series of loader option objects (ultimately - :class:`.Load` objects) which should be applied to the path - specified by this :class:`.Load` object. + :class:`_orm.Load` objects) which should be applied to the path + specified by this :class:`_orm.Load` object. .. versionadded:: 1.3.6 @@ -555,8 +559,8 @@ class Load(HasCacheKey, Generative, MapperOption): class _UnboundLoad(Load): """Represent a loader option that isn't tied to a root entity. - The loader option will produce an entity-linked :class:`.Load` - object when it is passed :meth:`.Query.options`. + The loader option will produce an entity-linked :class:`_orm.Load` + object when it is passed :meth:`_query.Query.options`. This provides compatibility with the traditional system of freestanding options, e.g. ``joinedload('x.y.z')``. @@ -981,7 +985,7 @@ class loader_option(object): def _add_unbound_fn(self, fn): self._unbound_fn = fn fn_doc = self.fn.__doc__ - self.fn.__doc__ = """Produce a new :class:`.Load` object with the + self.fn.__doc__ = """Produce a new :class:`_orm.Load` object with the :func:`_orm.%(name)s` option applied. See :func:`_orm.%(name)s` for usage examples. @@ -1029,7 +1033,7 @@ def contains_eager(loadopt, attr, alias=None): r"""Indicate that the given attribute should be eagerly loaded from columns stated manually in the query. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. The option is used in conjunction with an explicit join that loads @@ -1123,7 +1127,7 @@ def load_only(loadopt, *attrs): of column-based attribute names should be loaded; all others will be deferred. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. Example - given a class ``User``, load only the ``name`` and ``fullname`` @@ -1139,8 +1143,9 @@ def load_only(loadopt, *attrs): subqueryload("addresses").load_only("email_address") ) - For a :class:`.Query` that has multiple entities, the lead entity can be - specifically referred to using the :class:`.Load` constructor:: + For a :class:`_query.Query` that has multiple entities, + the lead entity can be + specifically referred to using the :class:`_orm.Load` constructor:: session.query(User, Address).join(User.addresses).options( Load(User).load_only("name", "fullname"), @@ -1170,7 +1175,7 @@ def joinedload(loadopt, attr, innerjoin=None): """Indicate that the given attribute should be loaded using joined eager loading. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. examples:: @@ -1221,7 +1226,7 @@ def joinedload(loadopt, attr, innerjoin=None): .. note:: The "unnested" flag does **not** affect the JOIN rendered from a many-to-many association table, e.g. a table configured - as :paramref:`.relationship.secondary`, to the target table; for + as :paramref:`_orm.relationship.secondary`, to the target table; for correctness of results, these joins are always INNER and are therefore right-nested if linked to an OUTER join. @@ -1233,15 +1238,17 @@ def joinedload(loadopt, attr, innerjoin=None): .. note:: - The joins produced by :func:`.orm.joinedload` are **anonymously + The joins produced by :func:`_orm.joinedload` are **anonymously aliased**. The criteria by which the join proceeds cannot be - modified, nor can the :class:`.Query` refer to these joins in any way, + modified, nor can the :class:`_query.Query` + refer to these joins in any way, including ordering. See :ref:`zen_of_eager_loading` for further detail. To produce a specific SQL JOIN which is explicitly available, use - :meth:`.Query.join`. To combine explicit JOINs with eager loading - of collections, use :func:`.orm.contains_eager`; see + :meth:`_query.Query.join`. + To combine explicit JOINs with eager loading + of collections, use :func:`_orm.contains_eager`; see :ref:`contains_eager`. .. seealso:: @@ -1267,7 +1274,7 @@ def subqueryload(loadopt, attr): """Indicate that the given attribute should be loaded using subquery eager loading. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. examples:: @@ -1305,7 +1312,7 @@ def selectinload(loadopt, attr): """Indicate that the given attribute should be loaded using SELECT IN eager loading. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. examples:: @@ -1344,7 +1351,7 @@ def lazyload(loadopt, attr): """Indicate that the given attribute should be loaded using "lazy" loading. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. .. seealso:: @@ -1371,7 +1378,7 @@ def immediateload(loadopt, attr): by the :func:`.selectinload` option, which performs the same task more efficiently by emitting a SELECT for all loaded objects. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. .. seealso:: @@ -1394,11 +1401,11 @@ def immediateload(*keys): def noload(loadopt, attr): """Indicate that the given relationship attribute should remain unloaded. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. - :func:`.orm.noload` applies to :func:`.relationship` attributes; for - column-based attributes, see :func:`.orm.defer`. + :func:`_orm.noload` applies to :func:`_orm.relationship` attributes; for + column-based attributes, see :func:`_orm.defer`. .. seealso:: @@ -1418,7 +1425,7 @@ def noload(*keys): def raiseload(loadopt, attr, sql_only=False): """Indicate that the given attribute should raise an error if accessed. - A relationship attribute configured with :func:`.orm.raiseload` will + A relationship attribute configured with :func:`_orm.raiseload` will raise an :exc:`~sqlalchemy.exc.InvalidRequestError` upon access. The typical way this is useful is when an application is attempting to ensure that all relationship attributes that are accessed in a particular context @@ -1426,7 +1433,8 @@ def raiseload(loadopt, attr, sql_only=False): to read through SQL logs to ensure lazy loads aren't occurring, this strategy will cause them to raise immediately. - :func:`.orm.raiseload` applies to :func:`.relationship` attributes only. + :func:`_orm.raiseload` applies to :func:`_orm.relationship` + attributes only. In order to apply raise-on-SQL behavior to a column-based attribute, use the :paramref:`.orm.defer.raiseload` parameter on the :func:`.defer` loader option. @@ -1436,7 +1444,7 @@ def raiseload(loadopt, attr, sql_only=False): related value should just be None due to missing keys. When False, the strategy will raise for all varieties of relationship loading. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. @@ -1487,7 +1495,7 @@ def defaultload(loadopt, attr): .. seealso:: - :meth:`.Load.options` - allows for complex hierarchical + :meth:`_orm.Load.options` - allows for complex hierarchical loader option structures with less verbosity than with individual :func:`.defaultload` directives. @@ -1509,7 +1517,7 @@ def defer(loadopt, key, raiseload=False): r"""Indicate that the given column-oriented attribute should be deferred, e.g. not loaded until accessed. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. e.g.:: @@ -1527,12 +1535,13 @@ def defer(loadopt, key, raiseload=False): To specify a deferred load of an attribute on a related class, the path can be specified one token at a time, specifying the loading style for each link along the chain. To leave the loading style - for a link unchanged, use :func:`.orm.defaultload`:: + for a link unchanged, use :func:`_orm.defaultload`:: session.query(MyClass).options(defaultload("someattr").defer("some_column")) - A :class:`.Load` object that is present on a certain path can have - :meth:`.Load.defer` called multiple times, each will operate on the same + A :class:`_orm.Load` object that is present on a certain path can have + :meth:`_orm.Load.defer` called multiple times, + each will operate on the same parent entity:: @@ -1559,7 +1568,7 @@ def defer(loadopt, key, raiseload=False): of specifying a path as a series of attributes, which is now superseded by the method-chained style. - .. deprecated:: 0.9 The \*addl_attrs on :func:`.orm.defer` is + .. deprecated:: 0.9 The \*addl_attrs on :func:`_orm.defer` is deprecated and will be removed in a future release. Please use method chaining in conjunction with defaultload() to indicate a path. @@ -1569,7 +1578,7 @@ def defer(loadopt, key, raiseload=False): :ref:`deferred` - :func:`.orm.undefer` + :func:`_orm.undefer` """ strategy = {"deferred": True, "instrument": True} @@ -1600,7 +1609,7 @@ def undefer(loadopt, key): The column being undeferred is typically set up on the mapping as a :func:`.deferred` attribute. - This function is part of the :class:`.Load` interface and supports + This function is part of the :class:`_orm.Load` interface and supports both method-chained and standalone operation. Examples:: @@ -1622,7 +1631,7 @@ def undefer(loadopt, key): of specifying a path as a series of attributes, which is now superseded by the method-chained style. - .. deprecated:: 0.9 The \*addl_attrs on :func:`.orm.undefer` is + .. deprecated:: 0.9 The \*addl_attrs on :func:`_orm.undefer` is deprecated and will be removed in a future release. Please use method chaining in conjunction with defaultload() to indicate a path. @@ -1631,9 +1640,9 @@ def undefer(loadopt, key): :ref:`deferred` - :func:`.orm.defer` + :func:`_orm.defer` - :func:`.orm.undefer_group` + :func:`_orm.undefer_group` """ return loadopt.set_column_strategy( @@ -1669,21 +1678,21 @@ def undefer_group(loadopt, name): To undefer a group of attributes on a related entity, the path can be spelled out using relationship loader options, such as - :func:`.orm.defaultload`:: + :func:`_orm.defaultload`:: session.query(MyClass).options( defaultload("someattr").undefer_group("large_attrs")) - .. versionchanged:: 0.9.0 :func:`.orm.undefer_group` is now specific to a + .. versionchanged:: 0.9.0 :func:`_orm.undefer_group` is now specific to a particular entity load path. .. seealso:: :ref:`deferred` - :func:`.orm.defer` + :func:`_orm.defer` - :func:`.orm.undefer` + :func:`_orm.undefer` """ return loadopt.set_column_strategy( @@ -1700,7 +1709,7 @@ def undefer_group(name): def with_expression(loadopt, key, expression): r"""Apply an ad-hoc SQL expression to a "deferred expression" attribute. - This option is used in conjunction with the :func:`.orm.query_expression` + This option is used in conjunction with the :func:`_orm.query_expression` mapper-level construct that indicates an attribute which should be the target of an ad-hoc SQL expression. diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py index 48e9b19bfe..37d3c99cfa 100644 --- a/lib/sqlalchemy/orm/util.py +++ b/lib/sqlalchemy/orm/util.py @@ -193,7 +193,7 @@ def polymorphic_union( this is used. :param table_map: mapping of polymorphic identities to - :class:`.Table` objects. + :class:`_schema.Table` objects. :param typecolname: string name of a "discriminator" column, which will be derived from the query, producing the polymorphic identity for each row. If ``None``, no polymorphic discriminator is generated. @@ -293,7 +293,7 @@ def identity_key(*args, **kwargs): (, (1, 2), None) In this form, the given instance is ultimately run though - :meth:`.Mapper.identity_key_from_instance`, which will have the + :meth:`_orm.Mapper.identity_key_from_instance`, which will have the effect of performing a database check for the corresponding row if the object is expired. @@ -420,12 +420,12 @@ class AliasedClass(object): :class:`.AliasedClass` is also capable of mapping an existing mapped class to an entirely new selectable, provided this selectable is column- compatible with the existing mapped selectable, and it can also be - configured in a mapping as the target of a :func:`.relationship`. + configured in a mapping as the target of a :func:`_orm.relationship`. See the links below for examples. The :class:`.AliasedClass` object is constructed typically using the - :func:`.orm.aliased` function. It also is produced with additional - configuration when using the :func:`.orm.with_polymorphic` function. + :func:`_orm.aliased` function. It also is produced with additional + configuration when using the :func:`_orm.with_polymorphic` function. The resulting object is an instance of :class:`.AliasedClass`. This object implements an attribute scheme which produces the @@ -435,8 +435,8 @@ class AliasedClass(object): including hybrid attributes (see :ref:`hybrids_toplevel`). The :class:`.AliasedClass` can be inspected for its underlying - :class:`.Mapper`, aliased selectable, and other information - using :func:`.inspect`:: + :class:`_orm.Mapper`, aliased selectable, and other information + using :func:`_sa.inspect`:: from sqlalchemy import inspect my_alias = aliased(MyClass) @@ -542,7 +542,7 @@ class AliasedInsp(sql_base.HasCacheKey, InspectionAttr): The :class:`.AliasedInsp` object is returned given an :class:`.AliasedClass` using the - :func:`.inspect` function:: + :func:`_sa.inspect` function:: from sqlalchemy import inspect from sqlalchemy.orm import aliased @@ -554,13 +554,16 @@ class AliasedInsp(sql_base.HasCacheKey, InspectionAttr): include: * ``entity`` - the :class:`.AliasedClass` represented. - * ``mapper`` - the :class:`.Mapper` mapping the underlying class. - * ``selectable`` - the :class:`.Alias` construct which ultimately - represents an aliased :class:`.Table` or :class:`.Select` + * ``mapper`` - the :class:`_orm.Mapper` mapping the underlying class. + * ``selectable`` - the :class:`_expression.Alias` + construct which ultimately + represents an aliased :class:`_schema.Table` or + :class:`_expression.Select` construct. * ``name`` - the name of the alias. Also is used as the attribute - name when returned in a result tuple from :class:`.Query`. - * ``with_polymorphic_mappers`` - collection of :class:`.Mapper` objects + name when returned in a result tuple from :class:`_query.Query`. + * ``with_polymorphic_mappers`` - collection of :class:`_orm.Mapper` + objects indicating all those mappers expressed in the select construct for the :class:`.AliasedClass`. * ``polymorphic_on`` - an alternate column or SQL expression which @@ -769,37 +772,45 @@ def aliased(element, alias=None, name=None, flat=False, adapt_on_names=False): The :func:`.aliased` function is used to create an ad-hoc mapping of a mapped class to a new selectable. By default, a selectable is generated - from the normally mapped selectable (typically a :class:`.Table`) using the - :meth:`.FromClause.alias` method. However, :func:`.aliased` can also be - used to link the class to a new :func:`~.sql.expression.select` statement. + from the normally mapped selectable (typically a :class:`_schema.Table` + ) using the + :meth:`_expression.FromClause.alias` method. However, :func:`.aliased` + can also be + used to link the class to a new :func:`_expression.select` statement. Also, the :func:`.with_polymorphic` function is a variant of :func:`.aliased` that is intended to specify a so-called "polymorphic selectable", that corresponds to the union of several joined-inheritance subclasses at once. For convenience, the :func:`.aliased` function also accepts plain - :class:`.FromClause` constructs, such as a :class:`.Table` or - :func:`~.sql.expression.select` construct. In those cases, the - :meth:`.FromClause.alias` method is called on the object and the new - :class:`.Alias` object returned. The returned :class:`.Alias` is not + :class:`_expression.FromClause` constructs, such as a + :class:`_schema.Table` or + :func:`_expression.select` construct. In those cases, the + :meth:`_expression.FromClause.alias` + method is called on the object and the new + :class:`_expression.Alias` object returned. The returned + :class:`_expression.Alias` is not ORM-mapped in this case. :param element: element to be aliased. Is normally a mapped class, - but for convenience can also be a :class:`.FromClause` element. + but for convenience can also be a :class:`_expression.FromClause` element + . :param alias: Optional selectable unit to map the element to. This should - normally be a :class:`.Alias` object corresponding to the :class:`.Table` - to which the class is mapped, or to a :func:`~.sql.expression.select` + normally be a :class:`_expression.Alias` object corresponding to the + :class:`_schema.Table` + to which the class is mapped, or to a :func:`_expression.select` construct that is compatible with the mapping. By default, a simple anonymous alias of the mapped table is generated. :param name: optional string name to use for the alias, if not specified by the ``alias`` parameter. The name, among other things, forms the attribute name that will be accessible via tuples returned by a - :class:`.Query` object. + :class:`_query.Query` object. :param flat: Boolean, will be passed through to the - :meth:`.FromClause.alias` call so that aliases of :class:`.Join` objects + :meth:`_expression.FromClause.alias` call so that aliases of + :class:`_expression.Join` objects don't include an enclosing SELECT. This can lead to more efficient queries in many circumstances. A JOIN against a nested JOIN will be rewritten as a JOIN against an aliased SELECT subquery on backends that @@ -807,7 +818,7 @@ def aliased(element, alias=None, name=None, flat=False, adapt_on_names=False): .. versionadded:: 0.9.0 - .. seealso:: :meth:`.Join.alias` + .. seealso:: :meth:`_expression.Join.alias` :param adapt_on_names: if True, more liberal "matching" will be used when mapping the mapped columns of the ORM entity to those of the @@ -879,7 +890,7 @@ def with_polymorphic( .. seealso:: :ref:`with_polymorphic` - full discussion of - :func:`.orm.with_polymorphic`. + :func:`_orm.with_polymorphic`. :param base: Base class to be aliased. @@ -895,11 +906,13 @@ def with_polymorphic( support parenthesized joins, such as SQLite and older versions of MySQL. However if the :paramref:`.with_polymorphic.selectable` parameter is in use - with an existing :class:`.Alias` construct, then you should not + with an existing :class:`_expression.Alias` construct, + then you should not set this flag. :param flat: Boolean, will be passed through to the - :meth:`.FromClause.alias` call so that aliases of :class:`.Join` + :meth:`_expression.FromClause.alias` call so that aliases of + :class:`_expression.Join` objects don't include an enclosing SELECT. This can lead to more efficient queries in many circumstances. A JOIN against a nested JOIN will be rewritten as a JOIN against an aliased SELECT subquery on @@ -910,7 +923,7 @@ def with_polymorphic( .. versionadded:: 0.9.0 - .. seealso:: :meth:`.Join.alias` + .. seealso:: :meth:`_expression.Join.alias` :param selectable: a table or subquery that will be used in place of the generated FROM clause. This argument is @@ -971,7 +984,7 @@ def _orm_deannotate(element): """Remove annotations that link a column to a particular mapping. Note this doesn't affect "remote" and "foreign" annotations - passed by the :func:`.orm.foreign` and :func:`.orm.remote` + passed by the :func:`_orm.foreign` and :func:`_orm.remote` annotators. """ @@ -1121,21 +1134,21 @@ def join( ): r"""Produce an inner join between left and right clauses. - :func:`.orm.join` is an extension to the core join interface - provided by :func:`.sql.expression.join()`, where the + :func:`_orm.join` is an extension to the core join interface + provided by :func:`_expression.join()`, where the left and right selectables may be not only core selectable - objects such as :class:`.Table`, but also mapped classes or + objects such as :class:`_schema.Table`, but also mapped classes or :class:`.AliasedClass` instances. The "on" clause can be a SQL expression, or an attribute or string name - referencing a configured :func:`.relationship`. + referencing a configured :func:`_orm.relationship`. - :func:`.orm.join` is not commonly needed in modern usage, + :func:`_orm.join` is not commonly needed in modern usage, as its functionality is encapsulated within that of the - :meth:`.Query.join` method, which features a - significant amount of automation beyond :func:`.orm.join` - by itself. Explicit usage of :func:`.orm.join` - with :class:`.Query` involves usage of the - :meth:`.Query.select_from` method, as in:: + :meth:`_query.Query.join` method, which features a + significant amount of automation beyond :func:`_orm.join` + by itself. Explicit usage of :func:`_orm.join` + with :class:`_query.Query` involves usage of the + :meth:`_query.Query.select_from` method, as in:: from sqlalchemy.orm import join session.query(User).\ @@ -1149,7 +1162,7 @@ def join( join(User.addresses).\ filter(Address.email_address=='foo@bar.com') - See :meth:`.Query.join` for information on modern usage + See :meth:`_query.Query.join` for information on modern usage of ORM level joins. .. deprecated:: 0.8 @@ -1164,7 +1177,7 @@ def join( def outerjoin(left, right, onclause=None, full=False, join_to_left=None): """Produce a left outer join between left and right clauses. - This is the "outer join" version of the :func:`.orm.join` function, + This is the "outer join" version of the :func:`_orm.join` function, featuring the same behavior except that an OUTER JOIN is generated. See that function's documentation for other usage details. @@ -1174,7 +1187,8 @@ def outerjoin(left, right, onclause=None, full=False, join_to_left=None): def with_parent(instance, prop, from_entity=None): """Create filtering criterion that relates this query's primary entity - to the given related instance, using established :func:`.relationship()` + to the given related instance, using established + :func:`_orm.relationship()` configuration. The SQL rendered is the same as that rendered when a lazy loader @@ -1184,7 +1198,7 @@ def with_parent(instance, prop, from_entity=None): in the rendered statement. :param instance: - An instance which has some :func:`.relationship`. + An instance which has some :func:`_orm.relationship`. :param property: String property name, or class-bound attribute, which indicates @@ -1193,7 +1207,7 @@ def with_parent(instance, prop, from_entity=None): :param from_entity: Entity in which to consider as the left side. This defaults to the - "zero" entity of the :class:`.Query` itself. + "zero" entity of the :class:`_query.Query` itself. .. versionadded:: 1.2 diff --git a/lib/sqlalchemy/pool/base.py b/lib/sqlalchemy/pool/base.py index 17d5ba15fd..7da6e2c4a1 100644 --- a/lib/sqlalchemy/pool/base.py +++ b/lib/sqlalchemy/pool/base.py @@ -31,8 +31,8 @@ class _ConnDialect(object): """partial implementation of :class:`.Dialect` which provides DBAPI connection methods. - When a :class:`.Pool` is combined with an :class:`.Engine`, - the :class:`.Engine` replaces this with its own + When a :class:`_pool.Pool` is combined with an :class:`_engine.Engine`, + the :class:`_engine.Engine` replaces this with its own :class:`.Dialect`. """ @@ -94,7 +94,7 @@ class Pool(log.Identified): which defaults to ``sys.stdout`` for output.. If set to the string ``"debug"``, the logging will include pool checkouts and checkins. - The :paramref:`.Pool.echo` parameter can also be set from the + The :paramref:`_pool.Pool.echo` parameter can also be set from the :func:`.create_engine` call by using the :paramref:`.create_engine.echo_pool` parameter. @@ -151,7 +151,7 @@ class Pool(log.Identified): as it is handled by the engine creation strategy. .. versionadded:: 1.1 - ``dialect`` is now a public parameter - to the :class:`.Pool`. + to the :class:`_pool.Pool`. :param pre_ping: if True, the pool will emit a "ping" (typically "SELECT 1", but is dialect-specific) on the connection @@ -264,11 +264,11 @@ class Pool(log.Identified): connection.invalidate(exception) def recreate(self): - """Return a new :class:`.Pool`, of the same class as this one + """Return a new :class:`_pool.Pool`, of the same class as this one and configured with identical creation arguments. This method is used in conjunction with :meth:`dispose` - to close out an entire :class:`.Pool` and create a new one in + to close out an entire :class:`_pool.Pool` and create a new one in its place. """ @@ -301,7 +301,7 @@ class Pool(log.Identified): return _ConnectionFairy._checkout(self) def _return_conn(self, record): - """Given a _ConnectionRecord, return it to the :class:`.Pool`. + """Given a _ConnectionRecord, return it to the :class:`_pool.Pool`. This method is called when an instrumented DBAPI connection has its ``close()`` method called. @@ -326,7 +326,7 @@ class Pool(log.Identified): class _ConnectionRecord(object): """Internal object which maintains an individual DBAPI connection - referenced by a :class:`.Pool`. + referenced by a :class:`_pool.Pool`. The :class:`._ConnectionRecord` object always exists for any particular DBAPI connection whether or not that DBAPI connection has been @@ -340,12 +340,14 @@ class _ConnectionRecord(object): method is called, the DBAPI connection associated with this :class:`._ConnectionRecord` will be discarded, but the :class:`._ConnectionRecord` may be used again, - in which case a new DBAPI connection is produced when the :class:`.Pool` + in which case a new DBAPI connection is produced when the + :class:`_pool.Pool` next uses this record. The :class:`._ConnectionRecord` is delivered along with connection - pool events, including :meth:`.PoolEvents.connect` and - :meth:`.PoolEvents.checkout`, however :class:`._ConnectionRecord` still + pool events, including :meth:`_events.PoolEvents.connect` and + :meth:`_events.PoolEvents.checkout`, however :class:`._ConnectionRecord` + still remains an internal object whose API and internals may change. .. seealso:: @@ -382,7 +384,7 @@ class _ConnectionRecord(object): """The ``.info`` dictionary associated with the DBAPI connection. This dictionary is shared among the :attr:`._ConnectionFairy.info` - and :attr:`.Connection.info` accessors. + and :attr:`_engine.Connection.info` accessors. .. note:: @@ -468,7 +470,8 @@ class _ConnectionRecord(object): This method is called for all connection invalidations, including when the :meth:`._ConnectionFairy.invalidate` or - :meth:`.Connection.invalidate` methods are called, as well as when any + :meth:`_engine.Connection.invalidate` methods are called, + as well as when any so-called "automatic invalidation" condition occurs. :param e: an exception object indicating a reason for the invalidation. @@ -639,9 +642,9 @@ class _ConnectionFairy(object): """Proxies a DBAPI connection and provides return-on-dereference support. - This is an internal object used by the :class:`.Pool` implementation + This is an internal object used by the :class:`_pool.Pool` implementation to provide context management to a DBAPI connection delivered by - that :class:`.Pool`. + that :class:`_pool.Pool`. The name "fairy" is inspired by the fact that the :class:`._ConnectionFairy` object's lifespan is transitory, as it lasts @@ -677,10 +680,11 @@ class _ConnectionFairy(object): rather than directly against the dialect-level do_rollback() and do_commit() methods. - In practice, a :class:`.Connection` assigns a :class:`.Transaction` object + In practice, a :class:`_engine.Connection` assigns a :class:`.Transaction` + object to this variable when one is in scope so that the :class:`.Transaction` takes the job of committing or rolling back on return if - :meth:`.Connection.close` is called while the :class:`.Transaction` + :meth:`_engine.Connection.close` is called while the :class:`.Transaction` still exists. This is essentially an "event handler" of sorts but is simplified as an @@ -838,7 +842,8 @@ class _ConnectionFairy(object): The data here will follow along with the DBAPI connection including after it is returned to the connection pool and used again in subsequent instances of :class:`._ConnectionFairy`. It is shared - with the :attr:`._ConnectionRecord.info` and :attr:`.Connection.info` + with the :attr:`._ConnectionRecord.info` and + :attr:`_engine.Connection.info` accessors. The dictionary associated with a particular DBAPI connection is @@ -869,7 +874,7 @@ class _ConnectionFairy(object): """Mark this connection as invalidated. This method can be called directly, and is also called as a result - of the :meth:`.Connection.invalidate` method. When invoked, + of the :meth:`_engine.Connection.invalidate` method. When invoked, the DBAPI connection is immediately closed and discarded from further use by the pool. The invalidation mechanism proceeds via the :meth:`._ConnectionRecord.invalidate` internal method. diff --git a/lib/sqlalchemy/pool/events.py b/lib/sqlalchemy/pool/events.py index 7a3a0910af..8adfa267c3 100644 --- a/lib/sqlalchemy/pool/events.py +++ b/lib/sqlalchemy/pool/events.py @@ -11,7 +11,7 @@ from ..engine.base import Engine class PoolEvents(event.Events): - """Available events for :class:`.Pool`. + """Available events for :class:`_pool.Pool`. The methods here define the name of an event as well as the names of members that are passed to listener @@ -26,11 +26,11 @@ class PoolEvents(event.Events): event.listen(Pool, 'checkout', my_on_checkout) - In addition to accepting the :class:`.Pool` class and - :class:`.Pool` instances, :class:`.PoolEvents` also accepts - :class:`.Engine` objects and the :class:`.Engine` class as + In addition to accepting the :class:`_pool.Pool` class and + :class:`_pool.Pool` instances, :class:`_events.PoolEvents` also accepts + :class:`_engine.Engine` objects and the :class:`_engine.Engine` class as targets, which will be resolved to the ``.pool`` attribute of the - given engine or the :class:`.Pool` class:: + given engine or the :class:`_pool.Pool` class:: engine = create_engine("postgresql://scott:tiger@localhost/test") @@ -56,7 +56,7 @@ class PoolEvents(event.Events): def connect(self, dbapi_connection, connection_record): """Called at the moment a particular DBAPI connection is first - created for a given :class:`.Pool`. + created for a given :class:`_pool.Pool`. This event allows one to capture the point directly after which the DBAPI module-level ``.connect()`` method has been used in order @@ -71,13 +71,16 @@ class PoolEvents(event.Events): def first_connect(self, dbapi_connection, connection_record): """Called exactly once for the first time a DBAPI connection is - checked out from a particular :class:`.Pool`. + checked out from a particular :class:`_pool.Pool`. - The rationale for :meth:`.PoolEvents.first_connect` is to determine + The rationale for :meth:`_events.PoolEvents.first_connect` + is to determine information about a particular series of database connections based on the settings used for all connections. Since a particular - :class:`.Pool` refers to a single "creator" function (which in terms - of a :class:`.Engine` refers to the URL and connection options used), + :class:`_pool.Pool` + refers to a single "creator" function (which in terms + of a :class:`_engine.Engine` + refers to the URL and connection options used), it is typically valid to make observations about a single connection that can be safely assumed to be valid about all subsequent connections, such as the database version, the server and client @@ -108,7 +111,7 @@ class PoolEvents(event.Events): using the new connection. .. seealso:: :meth:`.ConnectionEvents.engine_connect` - a similar event - which occurs upon creation of a new :class:`.Connection`. + which occurs upon creation of a new :class:`_engine.Connection`. """ @@ -136,8 +139,8 @@ class PoolEvents(event.Events): pool argument. - The :meth:`.PoolEvents.reset` event is usually followed by the - :meth:`.PoolEvents.checkin` event is called, except in those + The :meth:`_events.PoolEvents.reset` event is usually followed by the + :meth:`_events.PoolEvents.checkin` event is called, except in those cases where the connection is discarded immediately after reset. :param dbapi_connection: a DBAPI connection. diff --git a/lib/sqlalchemy/pool/impl.py b/lib/sqlalchemy/pool/impl.py index fe87dbb8e3..0fe7612b92 100644 --- a/lib/sqlalchemy/pool/impl.py +++ b/lib/sqlalchemy/pool/impl.py @@ -25,10 +25,11 @@ from ..util import threading class QueuePool(Pool): - """A :class:`.Pool` that imposes a limit on the number of open connections. + """A :class:`_pool.Pool` + that imposes a limit on the number of open connections. :class:`.QueuePool` is the default pooling implementation used for - all :class:`.Engine` objects, unless the SQLite dialect is in use. + all :class:`_engine.Engine` objects, unless the SQLite dialect is in use. """ @@ -45,7 +46,7 @@ class QueuePool(Pool): Construct a QueuePool. :param creator: a callable function that returns a DB-API - connection object, same as that of :paramref:`.Pool.creator`. + connection object, same as that of :paramref:`_pool.Pool.creator`. :param pool_size: The size of the pool to be maintained, defaults to 5. This is the largest number of connections that @@ -88,9 +89,9 @@ class QueuePool(Pool): :ref:`pool_disconnects` :param \**kw: Other keyword arguments including - :paramref:`.Pool.recycle`, :paramref:`.Pool.echo`, - :paramref:`.Pool.reset_on_return` and others are passed to the - :class:`.Pool` constructor. + :paramref:`_pool.Pool.recycle`, :paramref:`_pool.Pool.echo`, + :paramref:`_pool.Pool.reset_on_return` and others are passed to the + :class:`_pool.Pool` constructor. """ Pool.__init__(self, creator, **kw) @@ -273,7 +274,7 @@ class SingletonThreadPool(Pool): for production use. - Options are the same as those of :class:`.Pool`, as well as: + Options are the same as those of :class:`_pool.Pool`, as well as: :param pool_size: The number of threads in which to maintain connections at once. Defaults to five. @@ -417,7 +418,7 @@ class StaticPool(Pool): class AssertionPool(Pool): - """A :class:`.Pool` that allows at most one checked out connection at + """A :class:`_pool.Pool` that allows at most one checked out connection at any given time. This will raise an exception if more than one connection is checked out diff --git a/lib/sqlalchemy/sql/annotation.py b/lib/sqlalchemy/sql/annotation.py index d895e730c1..891b8ae098 100644 --- a/lib/sqlalchemy/sql/annotation.py +++ b/lib/sqlalchemy/sql/annotation.py @@ -64,7 +64,8 @@ class SupportsCloneAnnotations(SupportsAnnotations): return new def _deannotate(self, values=None, clone=False): - """return a copy of this :class:`.ClauseElement` with annotations + """return a copy of this :class:`_expression.ClauseElement` + with annotations removed. :param values: optional tuple of individual values @@ -98,7 +99,8 @@ class SupportsWrappingAnnotations(SupportsAnnotations): return Annotated(self, values) def _deannotate(self, values=None, clone=False): - """return a copy of this :class:`.ClauseElement` with annotations + """return a copy of this :class:`_expression.ClauseElement` + with annotations removed. :param values: optional tuple of individual values diff --git a/lib/sqlalchemy/sql/base.py b/lib/sqlalchemy/sql/base.py index a02955c8c6..1b9b20b324 100644 --- a/lib/sqlalchemy/sql/base.py +++ b/lib/sqlalchemy/sql/base.py @@ -519,8 +519,9 @@ class Executable(Generative): execution. Execution options can be set on a per-statement or - per :class:`.Connection` basis. Additionally, the - :class:`.Engine` and ORM :class:`~.orm.query.Query` objects provide + per :class:`_engine.Connection` basis. Additionally, the + :class:`_engine.Engine` and ORM :class:`~.orm.query.Query` + objects provide access to execution options which they in turn configure upon connections. @@ -533,14 +534,14 @@ class Executable(Generative): Note that only a subset of possible execution options can be applied to a statement - these include "autocommit" and "stream_results", but not "isolation_level" or "compiled_cache". - See :meth:`.Connection.execution_options` for a full list of + See :meth:`_engine.Connection.execution_options` for a full list of possible options. .. seealso:: - :meth:`.Connection.execution_options` + :meth:`_engine.Connection.execution_options` - :meth:`.Query.execution_options` + :meth:`_query.Query.execution_options` :meth:`.Executable.get_execution_options` @@ -573,7 +574,8 @@ class Executable(Generative): @util.deprecated_20( ":meth:`.Executable.execute`", alternative="All statement execution in SQLAlchemy 2.0 is performed " - "by the :meth:`.Connection.execute` method of :class:`.Connection`, " + "by the :meth:`_engine.Connection.execute` method of " + ":class:`_engine.Connection`, " "or in the ORM by the :meth:`.Session.execute` method of " ":class:`.Session`.", ) @@ -595,7 +597,8 @@ class Executable(Generative): @util.deprecated_20( ":meth:`.Executable.scalar`", alternative="All statement execution in SQLAlchemy 2.0 is performed " - "by the :meth:`.Connection.execute` method of :class:`.Connection`, " + "by the :meth:`_engine.Connection.execute` method of " + ":class:`_engine.Connection`, " "or in the ORM by the :meth:`.Session.execute` method of " ":class:`.Session`; the :meth:`.Result.scalar` method can then be " "used to return a scalar result.", @@ -609,7 +612,8 @@ class Executable(Generative): @property def bind(self): - """Returns the :class:`.Engine` or :class:`.Connection` to + """Returns the :class:`_engine.Engine` or :class:`_engine.Connection` + to which this :class:`.Executable` is bound, or None if none found. This is a traversal which checks locally, then @@ -675,14 +679,19 @@ class SchemaVisitor(ClauseVisitor): class ColumnCollection(object): - """Collection of :class:`.ColumnElement` instances, typically for + """Collection of :class:`_expression.ColumnElement` instances, + typically for selectables. - The :class:`.ColumnCollection` has both mapping- and sequence- like - behaviors. A :class:`.ColumnCollection` usually stores :class:`.Column` + The :class:`_expression.ColumnCollection` + has both mapping- and sequence- like + behaviors. A :class:`_expression.ColumnCollection` usually stores + :class:`_schema.Column` objects, which are then accessible both via mapping style access as well - as attribute access style. The name for which a :class:`.Column` would - be present is normally that of the :paramref:`.Column.key` parameter, + as attribute access style. The name for which a :class:`_schema.Column` + would + be present is normally that of the :paramref:`_schema.Column.key` + parameter, however depending on the context, it may be stored under a special label name:: @@ -706,7 +715,8 @@ class ColumnCollection(object): >>> cc[1] Column('y', Integer(), table=None) - .. versionadded:: 1.4 :class:`.ColumnCollection` allows integer-based + .. versionadded:: 1.4 :class:`_expression.ColumnCollection` + allows integer-based index access to the collection. Iterating the collection yields the column expressions in order:: @@ -715,7 +725,8 @@ class ColumnCollection(object): [Column('x', Integer(), table=None), Column('y', Integer(), table=None)] - The base :class:`.ColumnCollection` object can store duplicates, which can + The base :class:`_expression.ColumnCollection` object can store duplicates + , which can mean either two columns with the same key, in which case the column returned by key access is **arbitrary**:: @@ -730,18 +741,21 @@ class ColumnCollection(object): True Or it can also mean the same column multiple times. These cases are - supported as :class:`.ColumnCollection` is used to represent the columns in + supported as :class:`_expression.ColumnCollection` + is used to represent the columns in a SELECT statement which may include duplicates. A special subclass :class:`.DedupeColumnCollection` exists which instead maintains SQLAlchemy's older behavior of not allowing duplicates; this - collection is used for schema level objects like :class:`.Table` and + collection is used for schema level objects like :class:`_schema.Table` + and :class:`.PrimaryKeyConstraint` where this deduping is helpful. The :class:`.DedupeColumnCollection` class also has additional mutation methods as the schema constructs have more use cases that require removal and replacement of columns. - .. versionchanged:: 1.4 :class:`.ColumnCollection` now stores duplicate + .. versionchanged:: 1.4 :class:`_expression.ColumnCollection` + now stores duplicate column keys as well as the same column in multiple positions. The :class:`.DedupeColumnCollection` class is added to maintain the former behavior in those cases where deduplication as well as @@ -884,28 +898,34 @@ class ColumnCollection(object): return ImmutableColumnCollection(self) def corresponding_column(self, column, require_embedded=False): - """Given a :class:`.ColumnElement`, return the exported - :class:`.ColumnElement` object from this :class:`.ColumnCollection` - which corresponds to that original :class:`.ColumnElement` via a common + """Given a :class:`_expression.ColumnElement`, return the exported + :class:`_expression.ColumnElement` object from this + :class:`_expression.ColumnCollection` + which corresponds to that original :class:`_expression.ColumnElement` + via a common ancestor column. - :param column: the target :class:`.ColumnElement` to be matched + :param column: the target :class:`_expression.ColumnElement` + to be matched :param require_embedded: only return corresponding columns for - the given :class:`.ColumnElement`, if the given - :class:`.ColumnElement` is actually present within a sub-element - of this :class:`.Selectable`. Normally the column will match if + the given :class:`_expression.ColumnElement`, if the given + :class:`_expression.ColumnElement` + is actually present within a sub-element + of this :class:`expression.Selectable`. + Normally the column will match if it merely shares a common ancestor with one of the exported - columns of this :class:`.Selectable`. + columns of this :class:`expression.Selectable`. .. seealso:: - :meth:`.Selectable.corresponding_column` - invokes this method + :meth:`expression.Selectable.corresponding_column` + - invokes this method against the collection returned by - :attr:`.Selectable.exported_columns`. + :attr:`expression.Selectable.exported_columns`. .. versionchanged:: 1.4 the implementation for ``corresponding_column`` - was moved onto the :class:`.ColumnCollection` itself. + was moved onto the :class:`_expression.ColumnCollection` itself. """ @@ -976,9 +996,10 @@ class ColumnCollection(object): class DedupeColumnCollection(ColumnCollection): - """A :class:`.ColumnCollection` that maintains deduplicating behavior. + """A :class:`_expression.ColumnCollection` + that maintains deduplicating behavior. - This is useful by schema level objects such as :class:`.Table` and + This is useful by schema level objects such as :class:`_schema.Table` and :class:`.PrimaryKeyConstraint`. The collection includes more sophisticated mutator methods as well to suit schema objects which require mutable column collections. diff --git a/lib/sqlalchemy/sql/compiler.py b/lib/sqlalchemy/sql/compiler.py index 23b15b1580..7ef9f7e6df 100644 --- a/lib/sqlalchemy/sql/compiler.py +++ b/lib/sqlalchemy/sql/compiler.py @@ -393,7 +393,7 @@ class Compiled(object): :param dialect: :class:`.Dialect` to compile against. - :param statement: :class:`.ClauseElement` to be compiled. + :param statement: :class:`_expression.ClauseElement` to be compiled. :param bind: Optional Engine or Connection to compile this statement against. @@ -533,7 +533,7 @@ class _CompileLabel(elements.ColumnElement): class SQLCompiler(Compiled): """Default implementation of :class:`.Compiled`. - Compiles :class:`.ClauseElement` objects into SQL strings. + Compiles :class:`_expression.ClauseElement` objects into SQL strings. """ @@ -637,8 +637,9 @@ class SQLCompiler(Compiled): """Optional :class:`.CompileState` object that maintains additional state used by the compiler. - Major executable objects such as :class:`~.sql.expression.Insert`, - :class:`.Update`, :class:`.Delete`, :class:`.Select` will generate this + Major executable objects such as :class:`_expression.Insert`, + :class:`_expression.Update`, :class:`_expression.Delete`, + :class:`_expression.Select` will generate this state when compiled in order to calculate additional information about the object. For the top level object that is to be executed, the state can be stored here where it can also have applicability towards result set @@ -662,7 +663,7 @@ class SQLCompiler(Compiled): :param dialect: :class:`.Dialect` to be used - :param statement: :class:`.ClauseElement` to be compiled + :param statement: :class:`_expression.ClauseElement` to be compiled :param column_keys: a list of column names to be compiled into an INSERT or UPDATE statement. @@ -3351,10 +3352,12 @@ class StrSQLCompiler(SQLCompiler): The :class:`.StrSQLCompiler` is invoked whenever a Core expression element is directly stringified without calling upon the - :meth:`.ClauseElement.compile` method. It can render a limited set + :meth:`_expression.ClauseElement.compile` method. + It can render a limited set of non-standard SQL constructs to assist in basic stringification, however for more substantial custom or dialect-specific SQL constructs, - it will be necessary to make use of :meth:`.ClauseElement.compile` + it will be necessary to make use of + :meth:`_expression.ClauseElement.compile` directly. .. seealso:: diff --git a/lib/sqlalchemy/sql/crud.py b/lib/sqlalchemy/sql/crud.py index 114dbec9eb..4d14497c1c 100644 --- a/lib/sqlalchemy/sql/crud.py +++ b/lib/sqlalchemy/sql/crud.py @@ -24,10 +24,10 @@ REQUIRED = util.symbol( """ Placeholder for the value within a :class:`.BindParameter` which is required to be present when the statement is passed -to :meth:`.Connection.execute`. +to :meth:`_engine.Connection.execute`. -This symbol is typically used when a :func:`.expression.insert` -or :func:`.expression.update` statement is compiled without parameter +This symbol is typically used when a :func:`_expression.insert` +or :func:`_expression.update` statement is compiled without parameter values present. """, diff --git a/lib/sqlalchemy/sql/ddl.py b/lib/sqlalchemy/sql/ddl.py index 5a2095604c..4c8250e983 100644 --- a/lib/sqlalchemy/sql/ddl.py +++ b/lib/sqlalchemy/sql/ddl.py @@ -138,12 +138,13 @@ class DDLElement(roles.DDLRole, Executable, _DDLCompiles): This DDL element. :target: - The :class:`.Table` or :class:`.MetaData` object which is the + The :class:`_schema.Table` or :class:`_schema.MetaData` + object which is the target of this event. May be None if the DDL is executed explicitly. :bind: - The :class:`.Connection` being used for DDL execution + The :class:`_engine.Connection` being used for DDL execution :tables: Optional keyword argument - a list of Table objects which are to @@ -216,8 +217,9 @@ class DDL(DDLElement): Specifies literal SQL DDL to be executed by the database. DDL objects function as DDL event listeners, and can be subscribed to those events - listed in :class:`.DDLEvents`, using either :class:`.Table` or - :class:`.MetaData` objects as targets. Basic templating support allows + listed in :class:`.DDLEvents`, using either :class:`_schema.Table` or + :class:`_schema.MetaData` objects as targets. + Basic templating support allows a single DDL instance to handle repetitive tasks for multiple tables. Examples:: @@ -371,12 +373,12 @@ class CreateTable(_CreateDropBase): ): """Create a :class:`.CreateTable` construct. - :param element: a :class:`.Table` that's the subject + :param element: a :class:`_schema.Table` that's the subject of the CREATE :param on: See the description for 'on' in :class:`.DDL`. :param bind: See the description for 'bind' in :class:`.DDL`. :param include_foreign_key_constraints: optional sequence of - :class:`.ForeignKeyConstraint` objects that will be included + :class:`_schema.ForeignKeyConstraint` objects that will be included inline within the CREATE construct; if omitted, all foreign key constraints that do not specify use_alter=True are included. @@ -400,7 +402,8 @@ class _DropView(_CreateDropBase): class CreateColumn(_DDLCompiles): - """Represent a :class:`.Column` as rendered in a CREATE TABLE statement, + """Represent a :class:`_schema.Column` + as rendered in a CREATE TABLE statement, via the :class:`.CreateTable` construct. This is provided to support custom column DDL within the generation @@ -408,7 +411,7 @@ class CreateColumn(_DDLCompiles): compiler extension documented in :ref:`sqlalchemy.ext.compiler_toplevel` to extend :class:`.CreateColumn`. - Typical integration is to examine the incoming :class:`.Column` + Typical integration is to examine the incoming :class:`_schema.Column` object, and to redirect compilation if a particular flag or condition is found:: @@ -439,7 +442,8 @@ class CreateColumn(_DDLCompiles): for const in column.constraints) return text - The above construct can be applied to a :class:`.Table` as follows:: + The above construct can be applied to a :class:`_schema.Table` + as follows:: from sqlalchemy import Table, Metadata, Column, Integer, String from sqlalchemy import schema @@ -454,7 +458,8 @@ class CreateColumn(_DDLCompiles): metadata.create_all(conn) - Above, the directives we've added to the :attr:`.Column.info` collection + Above, the directives we've added to the :attr:`_schema.Column.info` + collection will be detected by our custom compilation scheme:: CREATE TABLE mytable ( @@ -468,10 +473,11 @@ class CreateColumn(_DDLCompiles): columns when producing a ``CREATE TABLE``. This is accomplished by creating a compilation rule that conditionally returns ``None``. This is essentially how to produce the same effect as using the - ``system=True`` argument on :class:`.Column`, which marks a column + ``system=True`` argument on :class:`_schema.Column`, which marks a column as an implicitly-present "system" column. - For example, suppose we wish to produce a :class:`.Table` which skips + For example, suppose we wish to produce a :class:`_schema.Table` + which skips rendering of the PostgreSQL ``xmin`` column against the PostgreSQL backend, but on other backends does render it, in anticipation of a triggered rule. A conditional compilation rule could skip this name only @@ -940,13 +946,16 @@ class SchemaDropper(DDLBase): def sort_tables(tables, skip_fn=None, extra_dependencies=None): - """sort a collection of :class:`.Table` objects based on dependency. + """sort a collection of :class:`_schema.Table` objects based on dependency + . - This is a dependency-ordered sort which will emit :class:`.Table` - objects such that they will follow their dependent :class:`.Table` objects. + This is a dependency-ordered sort which will emit :class:`_schema.Table` + objects such that they will follow their dependent :class:`_schema.Table` + objects. Tables are dependent on another based on the presence of - :class:`.ForeignKeyConstraint` objects as well as explicit dependencies - added by :meth:`.Table.add_is_dependent_on`. + :class:`_schema.ForeignKeyConstraint` + objects as well as explicit dependencies + added by :meth:`_schema.Table.add_is_dependent_on`. .. warning:: @@ -954,19 +963,21 @@ def sort_tables(tables, skip_fn=None, extra_dependencies=None): automatic resolution of dependency cycles between tables, which are usually caused by mutually dependent foreign key constraints. To resolve these cycles, either the - :paramref:`.ForeignKeyConstraint.use_alter` parameter may be applied + :paramref:`_schema.ForeignKeyConstraint.use_alter` + parameter may be applied to those constraints, or use the - :func:`.sql.sort_tables_and_constraints` function which will break + :func:`_expression.sort_tables_and_constraints` + function which will break out foreign key constraints involved in cycles separately. - :param tables: a sequence of :class:`.Table` objects. + :param tables: a sequence of :class:`_schema.Table` objects. :param skip_fn: optional callable which will be passed a - :class:`.ForeignKey` object; if it returns True, this + :class:`_schema.ForeignKey` object; if it returns True, this constraint will not be considered as a dependency. Note this is **different** from the same parameter in :func:`.sort_tables_and_constraints`, which is - instead passed the owning :class:`.ForeignKeyConstraint` object. + instead passed the owning :class:`_schema.ForeignKeyConstraint` object. :param extra_dependencies: a sequence of 2-tuples of tables which will also be considered as dependent on each other. @@ -975,7 +986,7 @@ def sort_tables(tables, skip_fn=None, extra_dependencies=None): :func:`.sort_tables_and_constraints` - :meth:`.MetaData.sorted_tables` - uses this function to sort + :meth:`_schema.MetaData.sorted_tables` - uses this function to sort """ @@ -1004,27 +1015,32 @@ def sort_tables(tables, skip_fn=None, extra_dependencies=None): def sort_tables_and_constraints( tables, filter_fn=None, extra_dependencies=None ): - """sort a collection of :class:`.Table` / :class:`.ForeignKeyConstraint` + """sort a collection of :class:`_schema.Table` / + :class:`_schema.ForeignKeyConstraint` objects. This is a dependency-ordered sort which will emit tuples of ``(Table, [ForeignKeyConstraint, ...])`` such that each - :class:`.Table` follows its dependent :class:`.Table` objects. - Remaining :class:`.ForeignKeyConstraint` objects that are separate due to + :class:`_schema.Table` follows its dependent :class:`_schema.Table` + objects. + Remaining :class:`_schema.ForeignKeyConstraint` + objects that are separate due to dependency rules not satisfied by the sort are emitted afterwards as ``(None, [ForeignKeyConstraint ...])``. Tables are dependent on another based on the presence of - :class:`.ForeignKeyConstraint` objects, explicit dependencies - added by :meth:`.Table.add_is_dependent_on`, as well as dependencies + :class:`_schema.ForeignKeyConstraint` objects, explicit dependencies + added by :meth:`_schema.Table.add_is_dependent_on`, + as well as dependencies stated here using the :paramref:`~.sort_tables_and_constraints.skip_fn` and/or :paramref:`~.sort_tables_and_constraints.extra_dependencies` parameters. - :param tables: a sequence of :class:`.Table` objects. + :param tables: a sequence of :class:`_schema.Table` objects. :param filter_fn: optional callable which will be passed a - :class:`.ForeignKeyConstraint` object, and returns a value based on + :class:`_schema.ForeignKeyConstraint` object, + and returns a value based on whether this constraint should definitely be included or excluded as an inline constraint, or neither. If it returns False, the constraint will definitely be included as a dependency that cannot be subject diff --git a/lib/sqlalchemy/sql/dml.py b/lib/sqlalchemy/sql/dml.py index 1ac3acd8ae..bc800de429 100644 --- a/lib/sqlalchemy/sql/dml.py +++ b/lib/sqlalchemy/sql/dml.py @@ -5,8 +5,8 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php """ -Provide :class:`~.sql.expression.Insert`, :class:`.Update` and -:class:`.Delete`. +Provide :class:`_expression.Insert`, :class:`_expression.Update` and +:class:`_expression.Delete`. """ from sqlalchemy.types import NullType @@ -303,7 +303,7 @@ class UpdateBase( def bind(self): """Return a 'bind' linked to this :class:`.UpdateBase` - or a :class:`.Table` associated with it. + or a :class:`_schema.Table` associated with it. """ return self._bind or self.table.bind @@ -330,7 +330,8 @@ class UpdateBase( The given collection of column expressions should be derived from the table that is - the target of the INSERT, UPDATE, or DELETE. While :class:`.Column` + the target of the INSERT, UPDATE, or DELETE. While + :class:`_schema.Column` objects are typical, the elements can also be expressions:: stmt = table.insert().returning( @@ -403,9 +404,9 @@ class UpdateBase( The text of the hint is rendered in the appropriate location for the database backend in use, relative - to the :class:`.Table` that is the subject of this + to the :class:`_schema.Table` that is the subject of this statement, or optionally to that of the given - :class:`.Table` passed as the ``selectable`` argument. + :class:`_schema.Table` passed as the ``selectable`` argument. The ``dialect_name`` option will limit the rendering of a particular hint to a particular backend. Such as, to add a hint @@ -414,7 +415,7 @@ class UpdateBase( mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql") :param text: Text of the hint. - :param selectable: optional :class:`.Table` that specifies + :param selectable: optional :class:`_schema.Table` that specifies an element of the FROM clause within an UPDATE or DELETE to be the subject of the hint - applies only to certain backends. :param dialect_name: defaults to ``*``, if specified as the name @@ -457,10 +458,11 @@ class ValuesBase(UpdateBase): r"""specify a fixed VALUES clause for an INSERT statement, or the SET clause for an UPDATE. - Note that the :class:`~.sql.expression.Insert` and :class:`.Update` + Note that the :class:`_expression.Insert` and + :class:`_expression.Update` constructs support per-execution time formatting of the VALUES and/or SET clauses, - based on the arguments passed to :meth:`.Connection.execute`. + based on the arguments passed to :meth:`_engine.Connection.execute`. However, the :meth:`.ValuesBase.values` method can be used to "fix" a particular set of parameters into the statement. @@ -473,7 +475,8 @@ class ValuesBase(UpdateBase): onto the existing list of values. :param \**kwargs: key value pairs representing the string key - of a :class:`.Column` mapped to the value to be rendered into the + of a :class:`_schema.Column` + mapped to the value to be rendered into the VALUES or SET clause:: users.insert().values(name="some name") @@ -484,10 +487,11 @@ class ValuesBase(UpdateBase): a dictionary, tuple, or list of dictionaries or tuples can be passed as a single positional argument in order to form the VALUES or SET clause of the statement. The forms that are accepted vary - based on whether this is an :class:`~.sql.expression.Insert` or an - :class:`.Update` construct. + based on whether this is an :class:`_expression.Insert` or an + :class:`_expression.Update` construct. - For either an :class:`~.sql.expression.Insert` or :class:`.Update` + For either an :class:`_expression.Insert` or + :class:`_expression.Update` construct, a single dictionary can be passed, which works the same as that of the kwargs form:: @@ -496,12 +500,12 @@ class ValuesBase(UpdateBase): users.update().values({"name": "some new name"}) Also for either form but more typically for the - :class:`~.sql.expression.Insert` construct, a tuple that contains an + :class:`_expression.Insert` construct, a tuple that contains an entry for every column in the table is also accepted:: users.insert().values((5, "some name")) - The :class:`~.sql.expression.Insert` construct also supports being + The :class:`_expression.Insert` construct also supports being passed a list of dictionaries or full-table-tuples, which on the server will render the less common SQL syntax of "multiple values" - this syntax is supported on backends such as SQLite, PostgreSQL, @@ -524,7 +528,8 @@ class ValuesBase(UpdateBase): NOT the same as using traditional executemany() form**. The above syntax is a **special** syntax not typically used. To emit an INSERT statement against multiple rows, the normal method is - to pass a multiple values list to the :meth:`.Connection.execute` + to pass a multiple values list to the + :meth:`_engine.Connection.execute` method, which is supported by all database backends and is generally more efficient for a very large number of parameters. @@ -536,7 +541,8 @@ class ValuesBase(UpdateBase): .. versionchanged:: 1.0.0 an INSERT that uses a multiple-VALUES clause, even a list of length one, - implies that the :paramref:`.Insert.inline` flag is set to + implies that the :paramref:`_expression.Insert.inline` + flag is set to True, indicating that the statement will not attempt to fetch the "last inserted primary key" or other defaults. The statement deals with an arbitrary number of rows, so the @@ -551,20 +557,20 @@ class ValuesBase(UpdateBase): The UPDATE construct also supports rendering the SET parameters in a specific order. For this feature refer to the - :meth:`.Update.ordered_values` method. + :meth:`_expression.Update.ordered_values` method. .. seealso:: - :meth:`.Update.ordered_values` + :meth:`_expression.Update.ordered_values` .. seealso:: :ref:`inserts_and_updates` - SQL Expression Language Tutorial - :func:`~.expression.insert` - produce an ``INSERT`` statement + :func:`_expression.insert` - produce an ``INSERT`` statement - :func:`~.expression.update` - produce an ``UPDATE`` statement + :func:`_expression.update` - produce an ``UPDATE`` statement """ if self._select_names: @@ -677,7 +683,8 @@ class ValuesBase(UpdateBase): :meth:`.UpdateBase.returning` is not used simultaneously. The column values will then be available on the result using the :attr:`.ResultProxy.returned_defaults` accessor as a dictionary, - referring to values keyed to the :class:`.Column` object as well as + referring to values keyed to the :class:`_schema.Column` + object as well as its ``.key``. This method differs from :meth:`.UpdateBase.returning` in these ways: @@ -711,7 +718,8 @@ class ValuesBase(UpdateBase): an efficient implementation for the ``eager_defaults`` feature of :func:`.mapper`. - :param cols: optional list of column key names or :class:`.Column` + :param cols: optional list of column key names or + :class:`_schema.Column` objects. If omitted, all column expressions evaluated on the server are added to the returning list. @@ -730,8 +738,8 @@ class ValuesBase(UpdateBase): class Insert(ValuesBase): """Represent an INSERT construct. - The :class:`~.sql.expression.Insert` object is created using the - :func:`~.expression.insert()` function. + The :class:`_expression.Insert` object is created using the + :func:`_expression.insert()` function. .. seealso:: @@ -787,20 +795,22 @@ class Insert(ValuesBase): return_defaults=False, **dialect_kw ): - """Construct an :class:`~.sql.expression.Insert` object. + """Construct an :class:`_expression.Insert` object. Similar functionality is available via the - :meth:`~.TableClause.insert` method on - :class:`~.schema.Table`. + :meth:`_expression.TableClause.insert` method on + :class:`_schema.Table`. - :param table: :class:`.TableClause` which is the subject of the + :param table: :class:`_expression.TableClause` + which is the subject of the insert. :param values: collection of values to be inserted; see - :meth:`.Insert.values` for a description of allowed formats here. - Can be omitted entirely; a :class:`~.sql.expression.Insert` construct + :meth:`_expression.Insert.values` + for a description of allowed formats here. + Can be omitted entirely; a :class:`_expression.Insert` construct will also dynamically render the VALUES clause at execution time - based on the parameters passed to :meth:`.Connection.execute`. + based on the parameters passed to :meth:`_engine.Connection.execute`. :param inline: if True, no attempt will be made to retrieve the SQL-generated default values to be provided within the statement; @@ -845,7 +855,7 @@ class Insert(ValuesBase): @_generative def inline(self): - """Make this :class:`~.sql.expression.Insert` construct "inline" . + """Make this :class:`_expression.Insert` construct "inline" . When set, no attempt will be made to retrieve the SQL-generated default values to be provided within the statement; @@ -856,15 +866,16 @@ class Insert(ValuesBase): returning" feature for the statement. - .. versionchanged:: 1.4 the :paramref:`.Insert.inline` parameter - is now superseded by the :meth:`.Insert.inline` method. + .. versionchanged:: 1.4 the :paramref:`_expression.Insert.inline` + parameter + is now superseded by the :meth:`_expression.Insert.inline` method. """ self._inline = True @_generative def from_select(self, names, select, include_defaults=True): - """Return a new :class:`~.sql.expression.Insert` construct which represents + """Return a new :class:`_expression.Insert` construct which represents an ``INSERT...FROM SELECT`` statement. e.g.:: @@ -872,19 +883,21 @@ class Insert(ValuesBase): sel = select([table1.c.a, table1.c.b]).where(table1.c.c > 5) ins = table2.insert().from_select(['a', 'b'], sel) - :param names: a sequence of string column names or :class:`.Column` + :param names: a sequence of string column names or + :class:`_schema.Column` objects representing the target columns. - :param select: a :func:`~.sql.expression.select` construct, - :class:`.FromClause` - or other construct which resolves into a :class:`.FromClause`, - such as an ORM :class:`.Query` object, etc. The order of + :param select: a :func:`_expression.select` construct, + :class:`_expression.FromClause` + or other construct which resolves into a + :class:`_expression.FromClause`, + such as an ORM :class:`_query.Query` object, etc. The order of columns returned from this FROM clause should correspond to the order of columns sent as the ``names`` parameter; while this is not checked before passing along to the database, the database would normally raise an exception if these column lists don't correspond. :param include_defaults: if True, non-server default values and - SQL expressions as specified on :class:`.Column` objects + SQL expressions as specified on :class:`_schema.Column` objects (as documented in :ref:`metadata_defaults_toplevel`) not otherwise specified in the list of names will be rendered into the INSERT and SELECT statements, so that these values are also @@ -894,13 +907,15 @@ class Insert(ValuesBase): will only be invoked **once** for the whole statement, and **not per row**. - .. versionadded:: 1.0.0 - :meth:`.Insert.from_select` now renders + .. versionadded:: 1.0.0 - :meth:`_expression.Insert.from_select` + now renders Python-side and SQL expression column defaults into the SELECT statement for columns otherwise not included in the list of column names. .. versionchanged:: 1.0.0 an INSERT that uses FROM SELECT - implies that the :paramref:`.insert.inline` flag is set to + implies that the :paramref:`_expression.insert.inline` + flag is set to True, indicating that the statement will not attempt to fetch the "last inserted primary key" or other defaults. The statement deals with an arbitrary number of rows, so the @@ -937,7 +952,8 @@ class DMLWhereBase(object): class Update(DMLWhereBase, ValuesBase): """Represent an Update construct. - The :class:`.Update` object is created using the :func:`update()` + The :class:`_expression.Update` + object is created using the :func:`update()` function. """ @@ -987,7 +1003,7 @@ class Update(DMLWhereBase, ValuesBase): preserve_parameter_order=False, **dialect_kw ): - r"""Construct an :class:`.Update` object. + r"""Construct an :class:`_expression.Update` object. E.g.:: @@ -997,14 +1013,15 @@ class Update(DMLWhereBase, ValuesBase): values(name='user #5') Similar functionality is available via the - :meth:`~.TableClause.update` method on - :class:`.Table`:: + :meth:`_expression.TableClause.update` method on + :class:`_schema.Table`:: stmt = users.update().\ where(users.c.id==5).\ values(name='user #5') - :param table: A :class:`.Table` object representing the database + :param table: A :class:`_schema.Table` + object representing the database table to be updated. :param whereclause: Optional SQL expression describing the ``WHERE`` @@ -1035,11 +1052,11 @@ class Update(DMLWhereBase, ValuesBase): the ``SET`` clause generates for all columns. Modern applications may prefer to use the generative - :meth:`.Update.values` method to set the values of the + :meth:`_expression.Update.values` method to set the values of the UPDATE statement. :param inline: - if True, SQL defaults present on :class:`.Column` objects via + if True, SQL defaults present on :class:`_schema.Column` objects via the ``default`` keyword will be compiled 'inline' into the statement and not pre-executed. This means that their values will not be available in the dictionary returned from @@ -1047,7 +1064,8 @@ class Update(DMLWhereBase, ValuesBase): :param preserve_parameter_order: if True, the update statement is expected to receive parameters **only** via the - :meth:`.Update.values` method, and they must be passed as a Python + :meth:`_expression.Update.values` method, + and they must be passed as a Python ``list`` of 2-tuples. The rendered UPDATE statement will emit the SET clause for each referenced column maintaining this order. @@ -1056,18 +1074,18 @@ class Update(DMLWhereBase, ValuesBase): .. seealso:: :ref:`updates_order_parameters` - illustrates the - :meth:`.Update.ordered_values` method. + :meth:`_expression.Update.ordered_values` method. If both ``values`` and compile-time bind parameters are present, the compile-time bind parameters override the information specified within ``values`` on a per-key basis. - The keys within ``values`` can be either :class:`.Column` + The keys within ``values`` can be either :class:`_schema.Column` objects or their string identifiers (specifically the "key" of the - :class:`.Column`, normally but not necessarily equivalent to + :class:`_schema.Column`, normally but not necessarily equivalent to its "name"). Normally, the - :class:`.Column` objects used here are expected to be - part of the target :class:`.Table` that is the table + :class:`_schema.Column` objects used here are expected to be + part of the target :class:`_schema.Table` that is the table to be updated. However when using MySQL, a multiple-table UPDATE statement can refer to columns from any of the tables referred to in the WHERE clause. @@ -1075,14 +1093,14 @@ class Update(DMLWhereBase, ValuesBase): The values referred to in ``values`` are typically: * a literal data value (i.e. string, number, etc.) - * a SQL expression, such as a related :class:`.Column`, - a scalar-returning :func:`~.sql.expression.select` construct, + * a SQL expression, such as a related :class:`_schema.Column`, + a scalar-returning :func:`_expression.select` construct, etc. - when combining :func:`~.sql.expression.select` constructs within the - values clause of an :func:`.update` + when combining :func:`_expression.select` constructs within the + values clause of an :func:`_expression.update` construct, the subquery represented - by the :func:`~.sql.expression.select` should be *correlated* to the + by the :func:`_expression.select` should be *correlated* to the parent table, that is, providing criterion which links the table inside the subquery to the outer table being updated:: @@ -1127,10 +1145,12 @@ class Update(DMLWhereBase, ValuesBase): .. seealso:: :ref:`updates_order_parameters` - full example of the - :meth:`.Update.ordered_values` method. + :meth:`_expression.Update.ordered_values` method. - .. versionchanged:: 1.4 The :meth:`.Update.ordered_values` method - supersedes the :paramref:`.update.preserve_parameter_order` + .. versionchanged:: 1.4 The :meth:`_expression.Update.ordered_values` + method + supersedes the + :paramref:`_expression.update.preserve_parameter_order` parameter, which will be removed in SQLAlchemy 2.0. """ @@ -1158,16 +1178,18 @@ class Update(DMLWhereBase, ValuesBase): @_generative def inline(self): - """Make this :class:`.Update` construct "inline" . + """Make this :class:`_expression.Update` construct "inline" . - When set, SQL defaults present on :class:`.Column` objects via the + When set, SQL defaults present on :class:`_schema.Column` + objects via the ``default`` keyword will be compiled 'inline' into the statement and not pre-executed. This means that their values will not be available in the dictionary returned from :meth:`.ResultProxy.last_updated_params`. - .. versionchanged:: 1.4 the :paramref:`.update.inline` parameter - is now superseded by the :meth:`.Update.inline` method. + .. versionchanged:: 1.4 the :paramref:`_expression.update.inline` + parameter + is now superseded by the :meth:`_expression.Update.inline` method. """ self._inline = True @@ -1176,7 +1198,8 @@ class Update(DMLWhereBase, ValuesBase): class Delete(DMLWhereBase, UpdateBase): """Represent a DELETE construct. - The :class:`.Delete` object is created using the :func:`delete()` + The :class:`_expression.Delete` + object is created using the :func:`delete()` function. """ @@ -1210,15 +1233,16 @@ class Delete(DMLWhereBase, UpdateBase): prefixes=None, **dialect_kw ): - r"""Construct :class:`.Delete` object. + r"""Construct :class:`_expression.Delete` object. Similar functionality is available via the - :meth:`~.TableClause.delete` method on - :class:`~.schema.Table`. + :meth:`_expression.TableClause.delete` method on + :class:`_schema.Table`. :param table: The table to delete rows from. - :param whereclause: A :class:`.ClauseElement` describing the ``WHERE`` + :param whereclause: A :class:`_expression.ClauseElement` + describing the ``WHERE`` condition of the ``DELETE`` statement. Note that the :meth:`~Delete.where()` generative method may be used instead. diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py index 9689c7a8a7..49bb08644b 100644 --- a/lib/sqlalchemy/sql/elements.py +++ b/lib/sqlalchemy/sql/elements.py @@ -5,8 +5,8 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""Core SQL expression elements, including :class:`.ClauseElement`, -:class:`.ColumnElement`, and derived classes. +"""Core SQL expression elements, including :class:`_expression.ClauseElement`, +:class:`_expression.ColumnElement`, and derived classes. """ @@ -88,14 +88,15 @@ def between(expr, lower_bound, upper_bound, symmetric=False): SELECT id, name FROM user WHERE id BETWEEN :id_1 AND :id_2 The :func:`.between` function is a standalone version of the - :meth:`.ColumnElement.between` method available on all + :meth:`_expression.ColumnElement.between` method available on all SQL expressions, as in:: stmt = select([users_table]).where(users_table.c.id.between(5, 7)) All arguments passed to :func:`.between`, including the left side column expression, are coerced from Python scalar values if a - the value is not a :class:`.ColumnElement` subclass. For example, + the value is not a :class:`_expression.ColumnElement` subclass. + For example, three fixed values can be compared as in:: print(between(5, 3, 7)) @@ -104,7 +105,8 @@ def between(expr, lower_bound, upper_bound, symmetric=False): :param_1 BETWEEN :param_2 AND :param_3 - :param expr: a column expression, typically a :class:`.ColumnElement` + :param expr: a column expression, typically a + :class:`_expression.ColumnElement` instance or alternatively a Python scalar expression to be coerced into a column expression, serving as the left side of the ``BETWEEN`` expression. @@ -122,7 +124,7 @@ def between(expr, lower_bound, upper_bound, symmetric=False): .. seealso:: - :meth:`.ColumnElement.between` + :meth:`_expression.ColumnElement.between` """ expr = coercions.expect(roles.ExpressionElementRole, expr) @@ -133,8 +135,10 @@ def literal(value, type_=None): r"""Return a literal clause, bound to a bind parameter. Literal clauses are created automatically when non- - :class:`.ClauseElement` objects (such as strings, ints, dates, etc.) are - used in a comparison operation with a :class:`.ColumnElement` subclass, + :class:`_expression.ClauseElement` objects (such as strings, ints, dates, + etc.) are + used in a comparison operation with a :class:`_expression.ColumnElement` + subclass, such as a :class:`~sqlalchemy.schema.Column` object. Use this function to force the generation of a literal clause, which will be created as a :class:`BindParameter` with a bound value. @@ -166,7 +170,7 @@ def not_(clause): """Return a negation of the given clause, i.e. ``NOT(clause)``. The ``~`` operator is also overloaded on all - :class:`.ColumnElement` subclasses to produce the + :class:`_expression.ColumnElement` subclasses to produce the same result. """ @@ -232,7 +236,7 @@ class ClauseElement( """in the context of binary expression, convert the type of this object to the one given. - applies only to :class:`.ColumnElement` classes. + applies only to :class:`_expression.ColumnElement` classes. """ return self @@ -334,7 +338,7 @@ class ClauseElement( \**kw are arguments consumed by subclass compare() methods and may be used to modify the criteria for comparison. - (see :class:`.ColumnElement`) + (see :class:`_expression.ColumnElement`) """ return traversals.compare(self, other, **kw) @@ -396,15 +400,16 @@ class ClauseElement( def self_group(self, against=None): # type: (Optional[Any]) -> ClauseElement - """Apply a 'grouping' to this :class:`.ClauseElement`. + """Apply a 'grouping' to this :class:`_expression.ClauseElement`. This method is overridden by subclasses to return a "grouping" construct, i.e. parenthesis. In particular it's used by "binary" expressions to provide a grouping around themselves when placed into a - larger expression, as well as by :func:`~.sql.expression.select` + larger expression, as well as by :func:`_expression.select` constructs when placed into the FROM clause of another - :func:`~.sql.expression.select`. (Note that subqueries should be - normally created using the :meth:`.Select.alias` method, as many + :func:`_expression.select`. (Note that subqueries should be + normally created using the :meth:`_expression.Select.alias` method, + as many platforms require nested SELECT statements to be named). As expressions are composed together, the application of @@ -415,13 +420,15 @@ class ClauseElement( an expression like ``x OR (y AND z)`` - AND takes precedence over OR. - The base :meth:`self_group` method of :class:`.ClauseElement` + The base :meth:`self_group` method of + :class:`_expression.ClauseElement` just returns self. """ return self def _ungroup(self): - """Return this :class:`.ClauseElement` without any groupings.""" + """Return this :class:`_expression.ClauseElement` """ + """without any groupings.""" return self @@ -438,7 +445,7 @@ class ClauseElement( :param bind: An ``Engine`` or ``Connection`` from which a ``Compiled`` will be acquired. This argument takes precedence over - this :class:`.ClauseElement`'s bound engine, if any. + this :class:`_expression.ClauseElement`'s bound engine, if any. :param column_keys: Used for INSERT and UPDATE statements, a list of column names which should be present in the VALUES clause of the @@ -447,7 +454,8 @@ class ClauseElement( :param dialect: A ``Dialect`` instance from which a ``Compiled`` will be acquired. This argument takes precedence over the `bind` - argument as well as this :class:`.ClauseElement`'s bound engine, + argument as well as this :class:`_expression.ClauseElement` + 's bound engine, if any. :param inline: Used for INSERT statements, for a dialect which does @@ -553,19 +561,23 @@ class ColumnElement( """Represent a column-oriented SQL expression suitable for usage in the "columns" clause, WHERE clause etc. of a statement. - While the most familiar kind of :class:`.ColumnElement` is the - :class:`.Column` object, :class:`.ColumnElement` serves as the basis + While the most familiar kind of :class:`_expression.ColumnElement` is the + :class:`_schema.Column` object, :class:`_expression.ColumnElement` + serves as the basis for any unit that may be present in a SQL expression, including the expressions themselves, SQL functions, bound parameters, literal expressions, keywords such as ``NULL``, etc. - :class:`.ColumnElement` is the ultimate base class for all such elements. + :class:`_expression.ColumnElement` + is the ultimate base class for all such elements. A wide variety of SQLAlchemy Core functions work at the SQL expression - level, and are intended to accept instances of :class:`.ColumnElement` as + level, and are intended to accept instances of + :class:`_expression.ColumnElement` as arguments. These functions will typically document that they accept a "SQL expression" as an argument. What this means in terms of SQLAlchemy usually refers to an input which is either already in the form of a - :class:`.ColumnElement` object, or a value which can be **coerced** into + :class:`_expression.ColumnElement` object, + or a value which can be **coerced** into one. The coercion rules followed by most, but not all, SQLAlchemy Core functions with regards to SQL expressions are as follows: @@ -575,7 +587,8 @@ class ColumnElement( value". This generally means that a :func:`.bindparam` will be produced featuring the given value embedded into the construct; the resulting :class:`.BindParameter` object is an instance of - :class:`.ColumnElement`. The Python value will ultimately be sent + :class:`_expression.ColumnElement`. + The Python value will ultimately be sent to the DBAPI at execution time as a parameterized argument to the ``execute()`` or ``executemany()`` methods, after SQLAlchemy type-specific converters (e.g. those provided by any associated @@ -585,25 +598,28 @@ class ColumnElement( feature an accessor called ``__clause_element__()``. The Core expression system looks for this method when an object of otherwise unknown type is passed to a function that is looking to coerce the - argument into a :class:`.ColumnElement` and sometimes a - :class:`.SelectBase` expression. It is used within the ORM to + argument into a :class:`_expression.ColumnElement` and sometimes a + :class:`_expression.SelectBase` expression. + It is used within the ORM to convert from ORM-specific objects like mapped classes and mapped attributes into Core expression objects. * The Python ``None`` value is typically interpreted as ``NULL``, which in SQLAlchemy Core produces an instance of :func:`.null`. - A :class:`.ColumnElement` provides the ability to generate new - :class:`.ColumnElement` + A :class:`_expression.ColumnElement` provides the ability to generate new + :class:`_expression.ColumnElement` objects using Python expressions. This means that Python operators such as ``==``, ``!=`` and ``<`` are overloaded to mimic SQL operations, - and allow the instantiation of further :class:`.ColumnElement` instances - which are composed from other, more fundamental :class:`.ColumnElement` + and allow the instantiation of further :class:`_expression.ColumnElement` + instances + which are composed from other, more fundamental + :class:`_expression.ColumnElement` objects. For example, two :class:`.ColumnClause` objects can be added together with the addition operator ``+`` to produce a :class:`.BinaryExpression`. Both :class:`.ColumnClause` and :class:`.BinaryExpression` are subclasses - of :class:`.ColumnElement`:: + of :class:`_expression.ColumnElement`:: >>> from sqlalchemy.sql import column >>> column('a') + column('b') @@ -613,9 +629,9 @@ class ColumnElement( .. seealso:: - :class:`.Column` + :class:`_schema.Column` - :func:`.expression.column` + :func:`_expression.column` """ @@ -801,8 +817,8 @@ class ColumnElement( return s def shares_lineage(self, othercolumn): - """Return True if the given :class:`.ColumnElement` - has a common ancestor to this :class:`.ColumnElement`.""" + """Return True if the given :class:`_expression.ColumnElement` + has a common ancestor to this :class:`_expression.ColumnElement`.""" return bool(self.proxy_set.intersection(othercolumn.proxy_set)) @@ -829,8 +845,9 @@ class ColumnElement( def _make_proxy( self, selectable, name=None, name_is_truncatable=False, **kw ): - """Create a new :class:`.ColumnElement` representing this - :class:`.ColumnElement` as it appears in the select list of a + """Create a new :class:`_expression.ColumnElement` representing this + :class:`_expression.ColumnElement` + as it appears in the select list of a descending selectable. """ @@ -854,15 +871,15 @@ class ColumnElement( def cast(self, type_): """Produce a type cast, i.e. ``CAST( AS )``. - This is a shortcut to the :func:`~.expression.cast` function. + This is a shortcut to the :func:`_expression.cast` function. .. seealso:: :ref:`coretutorial_casts` - :func:`~.expression.cast` + :func:`_expression.cast` - :func:`~.expression.type_coerce` + :func:`_expression.type_coerce` .. versionadded:: 1.0.7 @@ -872,7 +889,7 @@ class ColumnElement( def label(self, name): """Produce a column label, i.e. `` AS ``. - This is a shortcut to the :func:`~.expression.label` function. + This is a shortcut to the :func:`_expression.label` function. if 'name' is None, an anonymous label name will be generated. @@ -923,7 +940,8 @@ class ColumnElement( class WrapsColumnExpression(object): - """Mixin that defines a :class:`.ColumnElement` as a wrapper with special + """Mixin that defines a :class:`_expression.ColumnElement` + as a wrapper with special labeling behavior for an expression that already has a name. .. versionadded:: 1.4 @@ -1011,7 +1029,8 @@ class BindParameter(roles.InElementRole, ColumnElement): r"""Produce a "bound expression". The return value is an instance of :class:`.BindParameter`; this - is a :class:`.ColumnElement` subclass which represents a so-called + is a :class:`_expression.ColumnElement` + subclass which represents a so-called "placeholder" value in a SQL expression, the value of which is supplied at the point at which the statement in executed against a database connection. @@ -1041,7 +1060,7 @@ class BindParameter(roles.InElementRole, ColumnElement): In order to populate the value of ``:username`` above, the value would typically be applied at execution time to a method - like :meth:`.Connection.execute`:: + like :meth:`_engine.Connection.execute`:: result = connection.execute(stmt, username='wendy') @@ -1070,7 +1089,7 @@ class BindParameter(roles.InElementRole, ColumnElement): expr = users_table.c.name == 'Wendy' The above expression will produce a :class:`.BinaryExpression` - construct, where the left side is the :class:`.Column` object + construct, where the left side is the :class:`_schema.Column` object representing the ``name`` column, and the right side is a :class:`.BindParameter` representing the literal value:: @@ -1102,7 +1121,7 @@ class BindParameter(roles.InElementRole, ColumnElement): Similarly, :func:`.bindparam` is invoked automatically when working with :term:`CRUD` statements as far as the "VALUES" portion is - concerned. The :func:`~.sql.expression.insert` construct produces an + concerned. The :func:`_expression.insert` construct produces an ``INSERT`` expression which will, at statement execution time, generate bound placeholders based on the arguments passed, as in:: @@ -1114,10 +1133,10 @@ class BindParameter(roles.InElementRole, ColumnElement): INSERT INTO "user" (name) VALUES (%(name)s) {'name': 'Wendy'} - The :class:`~.sql.expression.Insert` construct, at + The :class:`_expression.Insert` construct, at compilation/execution time, rendered a single :func:`.bindparam` mirroring the column name ``name`` as a result of the single ``name`` - parameter we passed to the :meth:`.Connection.execute` method. + parameter we passed to the :meth:`_engine.Connection.execute` method. :param key: the key (e.g. the name) for this bind param. @@ -1440,12 +1459,13 @@ class TextClause( result = connection.execute(t) - The :class:`.Text` construct is produced using the :func:`.text` + The :class:`_expression.TextClause` construct is produced using the + :func:`_expression.text` function; see that function for full documentation. .. seealso:: - :func:`.text` + :func:`_expression.text` """ @@ -1501,7 +1521,8 @@ class TextClause( @classmethod @_document_text_coercion("text", ":func:`.text`", ":paramref:`.text.text`") def _create_text(cls, text, bind=None): - r"""Construct a new :class:`.TextClause` clause, representing + r"""Construct a new :class:`_expression.TextClause` clause, + representing a textual SQL string directly. E.g.:: @@ -1511,7 +1532,8 @@ class TextClause( t = text("SELECT * FROM users") result = connection.execute(t) - The advantages :func:`.text` provides over a plain string are + The advantages :func:`_expression.text` + provides over a plain string are backend-neutral support for bind parameters, per-statement execution options, as well as bind parameter and result-column typing behavior, allowing @@ -1531,12 +1553,15 @@ class TextClause( t = text("SELECT * FROM users WHERE name='\:username'") - The :class:`.TextClause` construct includes methods which can + The :class:`_expression.TextClause` + construct includes methods which can provide information about the bound parameters as well as the column values which would be returned from the textual statement, assuming it's an executable SELECT type of statement. The - :meth:`.TextClause.bindparams` method is used to provide bound - parameter detail, and :meth:`.TextClause.columns` method allows + :meth:`_expression.TextClause.bindparams` + method is used to provide bound + parameter detail, and :meth:`_expression.TextClause.columns` + method allows specification of return columns including names and types:: t = text("SELECT * FROM users WHERE id=:user_id").\ @@ -1546,19 +1571,20 @@ class TextClause( for id, name in connection.execute(t): print(id, name) - The :func:`.text` construct is used in cases when + The :func:`_expression.text` construct is used in cases when a literal string SQL fragment is specified as part of a larger query, such as for the WHERE clause of a SELECT statement:: s = select([users.c.id, users.c.name]).where(text("id=:user_id")) result = connection.execute(s, user_id=12) - :func:`.text` is also used for the construction + :func:`_expression.text` is also used for the construction of a full, standalone statement using plain text. As such, SQLAlchemy refers to it as an :class:`.Executable` object, and it supports the :meth:`Executable.execution_options` method. For example, - a :func:`.text` construct that should be subject to "autocommit" + a :func:`_expression.text` + construct that should be subject to "autocommit" can be set explicitly so using the :paramref:`.Connection.execution_options.autocommit` option:: @@ -1566,7 +1592,8 @@ class TextClause( execution_options(autocommit=True) Note that SQLAlchemy's usual "autocommit" behavior applies to - :func:`.text` constructs implicitly - that is, statements which begin + :func:`_expression.text` constructs implicitly - that is, + statements which begin with a phrase such as ``INSERT``, ``UPDATE``, ``DELETE``, or a variety of other phrases specific to certain backends, will be eligible for autocommit if no transaction is in progress. @@ -1591,7 +1618,7 @@ class TextClause( @_generative def bindparams(self, *binds, **names_to_values): """Establish the values and/or types of bound parameters within - this :class:`.TextClause` construct. + this :class:`_expression.TextClause` construct. Given a text construct such as:: @@ -1599,7 +1626,8 @@ class TextClause( stmt = text("SELECT id, name FROM user WHERE name=:name " "AND timestamp=:timestamp") - the :meth:`.TextClause.bindparams` method can be used to establish + the :meth:`_expression.TextClause.bindparams` + method can be used to establish the initial value of ``:name`` and ``:timestamp``, using simple keyword arguments:: @@ -1635,10 +1663,12 @@ class TextClause( result = connection.execute(stmt, timestamp=datetime.datetime(2012, 10, 8, 15, 12, 5)) - The :meth:`.TextClause.bindparams` method can be called repeatedly, + The :meth:`_expression.TextClause.bindparams` + method can be called repeatedly, where it will re-use existing :class:`.BindParameter` objects to add new information. For example, we can call - :meth:`.TextClause.bindparams` first with typing information, and a + :meth:`_expression.TextClause.bindparams` + first with typing information, and a second time with value information, and it will be combined:: stmt = text("SELECT id, name FROM user WHERE name=:name " @@ -1652,10 +1682,12 @@ class TextClause( timestamp=datetime.datetime(2012, 10, 8, 15, 12, 5) ) - The :meth:`.TextClause.bindparams` method also supports the concept of + The :meth:`_expression.TextClause.bindparams` + method also supports the concept of **unique** bound parameters. These are parameters that are "uniquified" on name at statement compilation time, so that multiple - :func:`.text` constructs may be combined together without the names + :func:`_expression.text` + constructs may be combined together without the names conflicting. To use this feature, specify the :paramref:`.BindParameter.unique` flag on each :func:`.bindparam` object:: @@ -1678,7 +1710,8 @@ class TextClause( UNION ALL select id from table where name=:name_2 .. versionadded:: 1.3.11 Added support for the - :paramref:`.BindParameter.unique` flag to work with :func:`.text` + :paramref:`.BindParameter.unique` flag to work with + :func:`_expression.text` constructs. """ @@ -1717,13 +1750,16 @@ class TextClause( @util.preload_module("sqlalchemy.sql.selectable") def columns(self, *cols, **types): - r"""Turn this :class:`.TextClause` object into a - :class:`.TextualSelect` object that serves the same role as a SELECT + r"""Turn this :class:`_expression.TextClause` object into a + :class:`_expression.TextualSelect` + object that serves the same role as a SELECT statement. - The :class:`.TextualSelect` is part of the :class:`.SelectBase` + The :class:`_expression.TextualSelect` is part of the + :class:`_expression.SelectBase` hierarchy and can be embedded into another statement by using the - :meth:`.TextualSelect.subquery` method to produce a :class:`.Subquery` + :meth:`_expression.TextualSelect.subquery` method to produce a + :class:`.Subquery` object, which can then be SELECTed from. This function essentially bridges the gap between an entirely @@ -1740,14 +1776,17 @@ class TextClause( mytable.join(stmt, mytable.c.name == stmt.c.name) ).where(stmt.c.id > 5) - Above, we pass a series of :func:`.column` elements to the - :meth:`.TextClause.columns` method positionally. These :func:`.column` + Above, we pass a series of :func:`_expression.column` elements to the + :meth:`_expression.TextClause.columns` method positionally. These + :func:`_expression.column` elements now become first class elements upon the - :attr:`.TextualSelect.selected_columns` column collection, which then + :attr:`_expression.TextualSelect.selected_columns` column collection, + which then become part of the :attr:`.Subquery.c` collection after - :meth:`.TextualSelect.subquery` is invoked. + :meth:`_expression.TextualSelect.subquery` is invoked. - The column expressions we pass to :meth:`.TextClause.columns` may + The column expressions we pass to + :meth:`_expression.TextClause.columns` may also be typed; when we do so, these :class:`.TypeEngine` objects become the effective return type of the column, so that SQLAlchemy's result-set-processing systems may be used on the return values. @@ -1777,10 +1816,12 @@ class TextClause( for id, name, timestamp in connection.execute(stmt): print(id, name, timestamp) - The positional form of :meth:`.TextClause.columns` also provides the + The positional form of :meth:`_expression.TextClause.columns` + also provides the unique feature of **positional column targeting**, which is particularly useful when using the ORM with complex textual queries. If - we specify the columns from our model to :meth:`.TextClause.columns`, + we specify the columns from our model to + :meth:`_expression.TextClause.columns`, the result set will match to those columns positionally, meaning the name or origin of the column in the textual SQL doesn't matter:: @@ -1798,20 +1839,24 @@ class TextClause( query = session.query(User).from_statement(stmt).options( contains_eager(User.addresses)) - .. versionadded:: 1.1 the :meth:`.TextClause.columns` method now + .. versionadded:: 1.1 the :meth:`_expression.TextClause.columns` + method now offers positional column targeting in the result set when the column expressions are passed purely positionally. - The :meth:`.TextClause.columns` method provides a direct - route to calling :meth:`.FromClause.subquery` as well as - :meth:`.SelectBase.cte` against a textual SELECT statement:: + The :meth:`_expression.TextClause.columns` method provides a direct + route to calling :meth:`_expression.FromClause.subquery` as well as + :meth:`_expression.SelectBase.cte` + against a textual SELECT statement:: stmt = stmt.columns(id=Integer, name=String).cte('st') stmt = select([sometable]).where(sometable.c.id == stmt.c.id) - :param \*cols: A series of :class:`.ColumnElement` objects, typically - :class:`.Column` objects from a :class:`.Table` or ORM level + :param \*cols: A series of :class:`_expression.ColumnElement` objects, + typically + :class:`_schema.Column` objects from a :class:`_schema.Table` + or ORM level column-mapped attributes, representing a set of columns that this textual string will SELECT from. @@ -2212,7 +2257,8 @@ class BooleanClauseList(ClauseList, ColumnElement): ) The :func:`.and_` operation is also implicit in some cases; - the :meth:`.Select.where` method for example can be invoked multiple + the :meth:`_expression.Select.where` + method for example can be invoked multiple times against a statement, which will have the effect of each clause being combined using :func:`.and_`:: @@ -2477,9 +2523,11 @@ class Case(ColumnElement): The values which are accepted as result values in :paramref:`.case.whens` as well as with :paramref:`.case.else_` are coerced from Python literals into :func:`.bindparam` constructs. - SQL expressions, e.g. :class:`.ColumnElement` constructs, are accepted + SQL expressions, e.g. :class:`_expression.ColumnElement` constructs, + are accepted as well. To coerce a literal string expression into a constant - expression rendered inline, use the :func:`.literal_column` construct, + expression rendered inline, use the :func:`_expression.literal_column` + construct, as in:: from sqlalchemy import case, literal_column @@ -2595,13 +2643,16 @@ class Case(ColumnElement): def literal_column(text, type_=None): r"""Produce a :class:`.ColumnClause` object that has the - :paramref:`.column.is_literal` flag set to True. + :paramref:`_expression.column.is_literal` flag set to True. - :func:`.literal_column` is similar to :func:`.column`, except that + :func:`_expression.literal_column` is similar to + :func:`_expression.column`, except that it is more often used as a "standalone" column expression that renders - exactly as stated; while :func:`.column` stores a string name that + exactly as stated; while :func:`_expression.column` + stores a string name that will be assumed to be part of a table and may be quoted as such, - :func:`.literal_column` can be that, or any other arbitrary column-oriented + :func:`_expression.literal_column` can be that, + or any other arbitrary column-oriented expression. :param text: the text of the expression; can be any SQL expression. @@ -2616,9 +2667,9 @@ def literal_column(text, type_=None): .. seealso:: - :func:`.column` + :func:`_expression.column` - :func:`.text` + :func:`_expression.text` :ref:`sqlexpression_literal_column` @@ -2695,7 +2746,8 @@ class Cast(WrapsColumnExpression, ColumnElement): with a specific type, but does not render the ``CAST`` expression in SQL. - :param expression: A SQL expression, such as a :class:`.ColumnElement` + :param expression: A SQL expression, such as a + :class:`_expression.ColumnElement` expression or a Python string which will be coerced into a bound literal value. @@ -2730,7 +2782,7 @@ class Cast(WrapsColumnExpression, ColumnElement): class TypeCoerce(WrapsColumnExpression, ColumnElement): """Represent a Python-side type-coercion wrapper. - :class:`.TypeCoerce` supplies the :func:`.expression.type_coerce` + :class:`.TypeCoerce` supplies the :func:`_expression.type_coerce` function; see that function for usage details. .. versionchanged:: 1.1 The :func:`.type_coerce` function now produces @@ -2739,7 +2791,7 @@ class TypeCoerce(WrapsColumnExpression, ColumnElement): .. seealso:: - :func:`.expression.type_coerce` + :func:`_expression.type_coerce` :func:`.cast` @@ -2776,7 +2828,7 @@ class TypeCoerce(WrapsColumnExpression, ColumnElement): column remains separate in the list of result columns vs. other type-coerced or direct values of the target column. In order to provide a named label for the expression, use - :meth:`.ColumnElement.label`:: + :meth:`_expression.ColumnElement.label`:: stmt = select([ type_coerce( @@ -2801,7 +2853,8 @@ class TypeCoerce(WrapsColumnExpression, ColumnElement): except that it does not render the ``CAST`` expression in the resulting statement. - :param expression: A SQL expression, such as a :class:`.ColumnElement` + :param expression: A SQL expression, such as a + :class:`_expression.ColumnElement` expression or a Python string which will be coerced into a bound literal value. @@ -2961,7 +3014,8 @@ class UnaryExpression(ColumnElement): Like :func:`.asc` and :func:`.desc`, :func:`.nullsfirst` is typically invoked from the column expression itself using - :meth:`.ColumnElement.nullsfirst`, rather than as its standalone + :meth:`_expression.ColumnElement.nullsfirst`, + rather than as its standalone function version, as in:: stmt = (select([users_table]). @@ -2976,7 +3030,7 @@ class UnaryExpression(ColumnElement): :func:`.nullslast` - :meth:`.Select.order_by` + :meth:`_expression.Select.order_by` """ return UnaryExpression( @@ -3005,7 +3059,8 @@ class UnaryExpression(ColumnElement): Like :func:`.asc` and :func:`.desc`, :func:`.nullslast` is typically invoked from the column expression itself using - :meth:`.ColumnElement.nullslast`, rather than as its standalone + :meth:`_expression.ColumnElement.nullslast`, + rather than as its standalone function version, as in:: stmt = select([users_table]).\ @@ -3019,7 +3074,7 @@ class UnaryExpression(ColumnElement): :func:`.nullsfirst` - :meth:`.Select.order_by` + :meth:`_expression.Select.order_by` """ return UnaryExpression( @@ -3043,13 +3098,15 @@ class UnaryExpression(ColumnElement): SELECT id, name FROM user ORDER BY name DESC The :func:`.desc` function is a standalone version of the - :meth:`.ColumnElement.desc` method available on all SQL expressions, + :meth:`_expression.ColumnElement.desc` + method available on all SQL expressions, e.g.:: stmt = select([users_table]).order_by(users_table.c.name.desc()) - :param column: A :class:`.ColumnElement` (e.g. scalar SQL expression) + :param column: A :class:`_expression.ColumnElement` (e.g. + scalar SQL expression) with which to apply the :func:`.desc` operation. .. seealso:: @@ -3060,7 +3117,7 @@ class UnaryExpression(ColumnElement): :func:`.nullslast` - :meth:`.Select.order_by` + :meth:`_expression.Select.order_by` """ return UnaryExpression( @@ -3083,13 +3140,15 @@ class UnaryExpression(ColumnElement): SELECT id, name FROM user ORDER BY name ASC The :func:`.asc` function is a standalone version of the - :meth:`.ColumnElement.asc` method available on all SQL expressions, + :meth:`_expression.ColumnElement.asc` + method available on all SQL expressions, e.g.:: stmt = select([users_table]).order_by(users_table.c.name.asc()) - :param column: A :class:`.ColumnElement` (e.g. scalar SQL expression) + :param column: A :class:`_expression.ColumnElement` (e.g. + scalar SQL expression) with which to apply the :func:`.asc` operation. .. seealso:: @@ -3100,7 +3159,7 @@ class UnaryExpression(ColumnElement): :func:`.nullslast` - :meth:`.Select.order_by` + :meth:`_expression.Select.order_by` """ return UnaryExpression( @@ -3125,12 +3184,13 @@ class UnaryExpression(ColumnElement): SELECT COUNT(DISTINCT name) FROM user The :func:`.distinct` function is also available as a column-level - method, e.g. :meth:`.ColumnElement.distinct`, as in:: + method, e.g. :meth:`_expression.ColumnElement.distinct`, as in:: stmt = select([func.count(users_table.c.name.distinct())]) The :func:`.distinct` operator is different from the - :meth:`.Select.distinct` method of :class:`.Select`, + :meth:`_expression.Select.distinct` method of + :class:`_expression.Select`, which produces a ``SELECT`` statement with ``DISTINCT`` applied to the result set as a whole, e.g. a ``SELECT DISTINCT`` expression. See that method for further @@ -3138,9 +3198,9 @@ class UnaryExpression(ColumnElement): .. seealso:: - :meth:`.ColumnElement.distinct` + :meth:`_expression.ColumnElement.distinct` - :meth:`.Select.distinct` + :meth:`_expression.Select.distinct` :data:`.func` @@ -3210,7 +3270,7 @@ class CollectionAggregate(UnaryExpression): .. seealso:: - :func:`.expression.all_` + :func:`_expression.all_` """ @@ -3241,7 +3301,7 @@ class CollectionAggregate(UnaryExpression): .. seealso:: - :func:`.expression.any_` + :func:`_expression.any_` """ @@ -3551,7 +3611,7 @@ class Over(ColumnElement): Used against aggregate or so-called "window" functions, for database backends that support window functions. - :func:`~.expression.over` is usually called using + :func:`_expression.over` is usually called using the :meth:`.FunctionElement.over` method, e.g.:: func.row_number().over(order_by=mytable.c.some_column) @@ -3623,7 +3683,7 @@ class Over(ColumnElement): :data:`.expression.func` - :func:`.expression.within_group` + :func:`_expression.within_group` """ self.element = element @@ -3739,7 +3799,7 @@ class WithinGroup(ColumnElement): set aggregate" functions, including :class:`.percentile_cont`, :class:`.rank`, :class:`.dense_rank`, etc. - :func:`~.expression.within_group` is usually called using + :func:`_expression.within_group` is usually called using the :meth:`.FunctionElement.within_group` method, e.g.:: from sqlalchemy import within_group @@ -3765,7 +3825,7 @@ class WithinGroup(ColumnElement): :data:`.expression.func` - :func:`.expression.over` + :func:`_expression.over` """ self.element = element @@ -3904,7 +3964,7 @@ class FunctionFilter(ColumnElement): from sqlalchemy import over, funcfilter over(funcfilter(func.rank(), MyClass.y > 5), order_by='x') - See :func:`~.expression.over` for a full description. + See :func:`_expression.over` for a full description. """ return Over( @@ -3956,17 +4016,18 @@ class Label(roles.LabeledColumnExprRole, ColumnElement): def __init__(self, name, element, type_=None): """Return a :class:`Label` object for the - given :class:`.ColumnElement`. + given :class:`_expression.ColumnElement`. A label changes the name of an element in the columns clause of a ``SELECT`` statement, typically via the ``AS`` SQL keyword. This functionality is more conveniently available via the - :meth:`.ColumnElement.label` method on :class:`.ColumnElement`. + :meth:`_expression.ColumnElement.label` method on + :class:`_expression.ColumnElement`. :param name: label name - :param obj: a :class:`.ColumnElement`. + :param obj: a :class:`_expression.ColumnElement`. """ @@ -4070,8 +4131,8 @@ class ColumnClause( """Represents a column expression from any textual string. The :class:`.ColumnClause`, a lightweight analogue to the - :class:`.Column` class, is typically invoked using the - :func:`.column` function, as in:: + :class:`_schema.Column` class, is typically invoked using the + :func:`_expression.column` function, as in:: from sqlalchemy import column @@ -4083,21 +4144,24 @@ class ColumnClause( SELECT id, name FROM user :class:`.ColumnClause` is the immediate superclass of the schema-specific - :class:`.Column` object. While the :class:`.Column` class has all the + :class:`_schema.Column` object. While the :class:`_schema.Column` + class has all the same capabilities as :class:`.ColumnClause`, the :class:`.ColumnClause` class is usable by itself in those cases where behavioral requirements are limited to simple SQL expression generation. The object has none of the associations with schema-level metadata or with execution-time - behavior that :class:`.Column` does, so in that sense is a "lightweight" - version of :class:`.Column`. + behavior that :class:`_schema.Column` does, + so in that sense is a "lightweight" + version of :class:`_schema.Column`. - Full details on :class:`.ColumnClause` usage is at :func:`.column`. + Full details on :class:`.ColumnClause` usage is at + :func:`_expression.column`. .. seealso:: - :func:`.column` + :func:`_expression.column` - :class:`.Column` + :class:`_schema.Column` """ @@ -4118,7 +4182,8 @@ class ColumnClause( """Produce a :class:`.ColumnClause` object. The :class:`.ColumnClause` is a lightweight analogue to the - :class:`.Column` class. The :func:`.column` function can + :class:`_schema.Column` class. The :func:`_expression.column` + function can be invoked with just a name alone, as in:: from sqlalchemy import column @@ -4130,8 +4195,9 @@ class ColumnClause( SELECT id, name FROM user - Once constructed, :func:`.column` may be used like any other SQL - expression element such as within :func:`~.sql.expression.select` + Once constructed, :func:`_expression.column` + may be used like any other SQL + expression element such as within :func:`_expression.select` constructs:: from sqlalchemy.sql import column @@ -4139,19 +4205,24 @@ class ColumnClause( id, name = column("id"), column("name") stmt = select([id, name]).select_from("user") - The text handled by :func:`.column` is assumed to be handled + The text handled by :func:`_expression.column` + is assumed to be handled like the name of a database column; if the string contains mixed case, special characters, or matches a known reserved word on the target backend, the column expression will render using the quoting behavior determined by the backend. To produce a textual SQL expression that is rendered exactly without any quoting, - use :func:`.literal_column` instead, or pass ``True`` as the - value of :paramref:`.column.is_literal`. Additionally, full SQL - statements are best handled using the :func:`.text` construct. + use :func:`_expression.literal_column` instead, + or pass ``True`` as the + value of :paramref:`_expression.column.is_literal`. Additionally, + full SQL + statements are best handled using the :func:`_expression.text` + construct. - :func:`.column` can be used in a table-like + :func:`_expression.column` can be used in a table-like fashion by combining it with the :func:`.table` function - (which is the lightweight analogue to :class:`.Table`) to produce + (which is the lightweight analogue to :class:`_schema.Table` + ) to produce a working table construct with minimal boilerplate:: from sqlalchemy import table, column, select @@ -4164,36 +4235,37 @@ class ColumnClause( stmt = select([user.c.description]).where(user.c.name == 'wendy') - A :func:`.column` / :func:`.table` construct like that illustrated + A :func:`_expression.column` / :func:`.table` + construct like that illustrated above can be created in an ad-hoc fashion and is not associated with any - :class:`.schema.MetaData`, DDL, or events, unlike its - :class:`.Table` counterpart. + :class:`_schema.MetaData`, DDL, or events, unlike its + :class:`_schema.Table` counterpart. - .. versionchanged:: 1.0.0 :func:`.expression.column` can now + .. versionchanged:: 1.0.0 :func:`_expression.column` can now be imported from the plain ``sqlalchemy`` namespace like any other SQL element. :param text: the text of the element. - :param type: :class:`.types.TypeEngine` object which can associate + :param type: :class:`_types.TypeEngine` object which can associate this :class:`.ColumnClause` with a type. :param is_literal: if True, the :class:`.ColumnClause` is assumed to be an exact expression that will be delivered to the output with no quoting rules applied regardless of case sensitive settings. the - :func:`.literal_column()` function essentially invokes - :func:`.column` while passing ``is_literal=True``. + :func:`_expression.literal_column()` function essentially invokes + :func:`_expression.column` while passing ``is_literal=True``. .. seealso:: - :class:`.Column` + :class:`_schema.Column` - :func:`.literal_column` + :func:`_expression.literal_column` :func:`.table` - :func:`.text` + :func:`_expression.text` :ref:`sqlexpression_literal_column` @@ -4418,9 +4490,11 @@ class quoted_name(util.MemoizedSlots, util.text_type): The :class:`.quoted_name` object is normally created automatically when specifying the name for key schema constructs such as - :class:`.Table`, :class:`.Column`, and others. The class can also be + :class:`_schema.Table`, :class:`_schema.Column`, and others. + The class can also be passed explicitly as the name to any function that receives a name which - can be quoted. Such as to use the :meth:`.Engine.has_table` method with + can be quoted. Such as to use the :meth:`_engine.Engine.has_table` + method with an unconditionally quoted name:: from sqlalchemy import create_engine @@ -4592,7 +4666,7 @@ class conv(_truncated_label): In some situations, such as in migration scripts, we may be rendering the above :class:`.CheckConstraint` with a name that's already been converted. In order to make sure the name isn't double-modified, the - new name is applied using the :func:`.schema.conv` marker. We can + new name is applied using the :func:`_schema.conv` marker. We can use this explicitly as follows:: @@ -4602,7 +4676,7 @@ class conv(_truncated_label): t = Table('t', m, Column('x', Integer), CheckConstraint('x > 5', name=conv('ck_t_x5'))) - Where above, the :func:`.schema.conv` marker indicates that the constraint + Where above, the :func:`_schema.conv` marker indicates that the constraint name here is final, and the name will render as ``"ck_t_x5"`` and not ``"ck_t_ck_t_x5"`` diff --git a/lib/sqlalchemy/sql/events.py b/lib/sqlalchemy/sql/events.py index cd0ba26401..51556d9291 100644 --- a/lib/sqlalchemy/sql/events.py +++ b/lib/sqlalchemy/sql/events.py @@ -13,18 +13,19 @@ class DDLEvents(event.Events): """ Define event listeners for schema objects, that is, :class:`.SchemaItem` and other :class:`.SchemaEventTarget` - subclasses, including :class:`.MetaData`, :class:`.Table`, - :class:`.Column`. + subclasses, including :class:`_schema.MetaData`, :class:`_schema.Table`, + :class:`_schema.Column`. - :class:`.MetaData` and :class:`.Table` support events + :class:`_schema.MetaData` and :class:`_schema.Table` support events specifically regarding when CREATE and DROP DDL is emitted to the database. Attachment events are also provided to customize behavior whenever a child schema element is associated - with a parent, such as, when a :class:`.Column` is associated - with its :class:`.Table`, when a :class:`.ForeignKeyConstraint` - is associated with a :class:`.Table`, etc. + with a parent, such as, when a :class:`_schema.Column` is associated + with its :class:`_schema.Table`, when a + :class:`_schema.ForeignKeyConstraint` + is associated with a :class:`_schema.Table`, etc. Example using the ``after_create`` event:: @@ -59,7 +60,8 @@ class DDLEvents(event.Events): For all :class:`.DDLEvent` events, the ``propagate=True`` keyword argument will ensure that a given event handler is propagated to copies of the - object, which are made when using the :meth:`.Table.tometadata` method:: + object, which are made when using the :meth:`_schema.Table.tometadata` + method:: from sqlalchemy import DDL event.listen( @@ -72,7 +74,7 @@ class DDLEvents(event.Events): new_table = some_table.tometadata(new_metadata) The above :class:`.DDL` object will also be associated with the - :class:`.Table` object represented by ``new_table``. + :class:`_schema.Table` object represented by ``new_table``. .. seealso:: @@ -92,9 +94,9 @@ class DDLEvents(event.Events): def before_create(self, target, connection, **kw): r"""Called before CREATE statements are emitted. - :param target: the :class:`.MetaData` or :class:`.Table` + :param target: the :class:`_schema.MetaData` or :class:`_schema.Table` object which is the target of the event. - :param connection: the :class:`.Connection` where the + :param connection: the :class:`_engine.Connection` where the CREATE statement or statements will be emitted. :param \**kw: additional keyword arguments relevant to the event. The contents of this dictionary @@ -107,16 +109,16 @@ class DDLEvents(event.Events): modifier for this event; when True, the listener function will be established for any copies made of the target object, i.e. those copies that are generated when - :meth:`.Table.tometadata` is used. + :meth:`_schema.Table.tometadata` is used. """ def after_create(self, target, connection, **kw): r"""Called after CREATE statements are emitted. - :param target: the :class:`.MetaData` or :class:`.Table` + :param target: the :class:`_schema.MetaData` or :class:`_schema.Table` object which is the target of the event. - :param connection: the :class:`.Connection` where the + :param connection: the :class:`_engine.Connection` where the CREATE statement or statements have been emitted. :param \**kw: additional keyword arguments relevant to the event. The contents of this dictionary @@ -129,16 +131,16 @@ class DDLEvents(event.Events): modifier for this event; when True, the listener function will be established for any copies made of the target object, i.e. those copies that are generated when - :meth:`.Table.tometadata` is used. + :meth:`_schema.Table.tometadata` is used. """ def before_drop(self, target, connection, **kw): r"""Called before DROP statements are emitted. - :param target: the :class:`.MetaData` or :class:`.Table` + :param target: the :class:`_schema.MetaData` or :class:`_schema.Table` object which is the target of the event. - :param connection: the :class:`.Connection` where the + :param connection: the :class:`_engine.Connection` where the DROP statement or statements will be emitted. :param \**kw: additional keyword arguments relevant to the event. The contents of this dictionary @@ -151,16 +153,16 @@ class DDLEvents(event.Events): modifier for this event; when True, the listener function will be established for any copies made of the target object, i.e. those copies that are generated when - :meth:`.Table.tometadata` is used. + :meth:`_schema.Table.tometadata` is used. """ def after_drop(self, target, connection, **kw): r"""Called after DROP statements are emitted. - :param target: the :class:`.MetaData` or :class:`.Table` + :param target: the :class:`_schema.MetaData` or :class:`_schema.Table` object which is the target of the event. - :param connection: the :class:`.Connection` where the + :param connection: the :class:`_engine.Connection` where the DROP statement or statements have been emitted. :param \**kw: additional keyword arguments relevant to the event. The contents of this dictionary @@ -173,7 +175,7 @@ class DDLEvents(event.Events): modifier for this event; when True, the listener function will be established for any copies made of the target object, i.e. those copies that are generated when - :meth:`.Table.tometadata` is used. + :meth:`_schema.Table.tometadata` is used. """ @@ -188,7 +190,7 @@ class DDLEvents(event.Events): modifier for this event; when True, the listener function will be established for any copies made of the target object, i.e. those copies that are generated when - :meth:`.Table.tometadata` is used. + :meth:`_schema.Table.tometadata` is used. """ @@ -203,13 +205,13 @@ class DDLEvents(event.Events): modifier for this event; when True, the listener function will be established for any copies made of the target object, i.e. those copies that are generated when - :meth:`.Table.tometadata` is used. + :meth:`_schema.Table.tometadata` is used. """ def column_reflect(self, inspector, table, column_info): """Called for each unit of 'column info' retrieved when - a :class:`.Table` is being reflected. + a :class:`_schema.Table` is being reflected. The dictionary of column information as returned by the dialect is passed, and can be modified. The dictionary @@ -226,13 +228,13 @@ class DDLEvents(event.Events): * ``default`` - the column's server default value. This is normally specified as a plain string SQL expression, however the event can pass a :class:`.FetchedValue`, :class:`.DefaultClause`, - or :func:`.sql.expression.text` object as well. + or :func:`_expression.text` object as well. .. versionchanged:: 1.1.6 The :meth:`.DDLEvents.column_reflect` event allows a non string :class:`.FetchedValue`, - :func:`.sql.expression.text`, or derived object to be + :func:`_expression.text`, or derived object to be specified as the value of ``default`` in the column dictionary. @@ -240,12 +242,12 @@ class DDLEvents(event.Events): The event is called before any action is taken against this dictionary, and the contents can be modified. - The :class:`.Column` specific arguments ``info``, ``key``, + The :class:`_schema.Column` specific arguments ``info``, ``key``, and ``quote`` can also be added to the dictionary and - will be passed to the constructor of :class:`.Column`. + will be passed to the constructor of :class:`_schema.Column`. Note that this event is only meaningful if either - associated with the :class:`.Table` class across the + associated with the :class:`_schema.Table` class across the board, e.g.:: from sqlalchemy.schema import Table @@ -260,7 +262,7 @@ class DDLEvents(event.Events): 'column_reflect', listen_for_reflect) - ...or with a specific :class:`.Table` instance using + ...or with a specific :class:`_schema.Table` instance using the ``listeners`` argument:: def listen_for_reflect(inspector, table, column_info): @@ -275,12 +277,13 @@ class DDLEvents(event.Events): ]) This because the reflection process initiated by ``autoload=True`` - completes within the scope of the constructor for :class:`.Table`. + completes within the scope of the constructor for + :class:`_schema.Table`. :func:`.event.listen` also accepts the ``propagate=True`` modifier for this event; when True, the listener function will be established for any copies made of the target object, i.e. those copies that are generated when - :meth:`.Table.tometadata` is used. + :meth:`_schema.Table.tometadata` is used. """ diff --git a/lib/sqlalchemy/sql/functions.py b/lib/sqlalchemy/sql/functions.py index 7973871f33..1b10df9547 100644 --- a/lib/sqlalchemy/sql/functions.py +++ b/lib/sqlalchemy/sql/functions.py @@ -127,7 +127,7 @@ class FunctionElement(Executable, ColumnElement, FromClause): an anonymously named column. An interim approach to providing named columns for a function - as a FROM clause is to build a :func:`~.sql.expression.select` with the + as a FROM clause is to build a :func:`_expression.select` with the desired columns:: from sqlalchemy.sql import column @@ -163,7 +163,7 @@ class FunctionElement(Executable, ColumnElement, FromClause): from sqlalchemy import over over(func.row_number(), order_by='x') - See :func:`~.expression.over` for a full description. + See :func:`_expression.over` for a full description. """ return Over( @@ -181,7 +181,7 @@ class FunctionElement(Executable, ColumnElement, FromClause): set aggregate" functions, including :class:`.percentile_cont`, :class:`.rank`, :class:`.dense_rank`, etc. - See :func:`~.expression.within_group` for a full description. + See :func:`_expression.within_group` for a full description. .. versionadded:: 1.1 @@ -245,7 +245,8 @@ class FunctionElement(Executable, ColumnElement, FromClause): to manipulate the "left" and "right" sides of the ON clause of a JOIN expression. The purpose of this method is to provide a SQL function construct that can also supply this information to the ORM, when used - with the :paramref:`.relationship.primaryjoin` parameter. The return + with the :paramref:`_orm.relationship.primaryjoin` parameter. + The return value is a containment object called :class:`.FunctionAsBinary`. An ORM example is as follows:: @@ -300,7 +301,7 @@ class FunctionElement(Executable, ColumnElement, FromClause): return None def alias(self, name=None, flat=False): - r"""Produce a :class:`.Alias` construct against this + r"""Produce a :class:`_expression.Alias` construct against this :class:`.FunctionElement`. This construct wraps the function in a named alias which @@ -332,7 +333,7 @@ class FunctionElement(Executable, ColumnElement, FromClause): return Alias._construct(self, name) def select(self): - """Produce a :func:`~.expression.select` construct + """Produce a :func:`_expression.select` construct against this :class:`.FunctionElement`. This is shorthand for:: @@ -353,8 +354,8 @@ class FunctionElement(Executable, ColumnElement, FromClause): produce a SELECT construct. Note that :class:`.FunctionElement` can be passed to - the :meth:`.Connectable.scalar` method of :class:`.Connection` - or :class:`.Engine`. + the :meth:`.Connectable.scalar` method of :class:`_engine.Connection` + or :class:`_engine.Engine`. """ return self.select().execute().scalar() @@ -367,8 +368,8 @@ class FunctionElement(Executable, ColumnElement, FromClause): produce a SELECT construct. Note that :class:`.FunctionElement` can be passed to - the :meth:`.Connectable.execute` method of :class:`.Connection` - or :class:`.Engine`. + the :meth:`.Connectable.execute` method of :class:`_engine.Connection` + or :class:`_engine.Engine`. """ return self.select().execute() @@ -478,7 +479,8 @@ class _FunctionGenerator(object): :class:`.Function`. This object meets the "column" interface, including comparison and labeling functions. The object can also be passed the :meth:`~.Connectable.execute` - method of a :class:`.Connection` or :class:`.Engine`, where it will be + method of a :class:`_engine.Connection` or :class:`_engine.Engine`, + where it will be wrapped inside of a SELECT statement first:: print(connection.execute(func.current_timestamp()).scalar()) @@ -919,7 +921,7 @@ class array_agg(GenericFunction): """support for the ARRAY_AGG function. The ``func.array_agg(expr)`` construct returns an expression of - type :class:`.types.ARRAY`. + type :class:`_types.ARRAY`. e.g.:: @@ -929,8 +931,8 @@ class array_agg(GenericFunction): .. seealso:: - :func:`.postgresql.array_agg` - PostgreSQL-specific version that - returns :class:`.postgresql.ARRAY`, which has PG-specific operators + :func:`_postgresql.array_agg` - PostgreSQL-specific version that + returns :class:`_postgresql.ARRAY`, which has PG-specific operators added. """ @@ -988,7 +990,7 @@ class percentile_cont(OrderedSetAgg): modifier to supply a sort expression to operate upon. The return type of this function is the same as the sort expression, - or if the arguments are an array, an :class:`.types.ARRAY` of the sort + or if the arguments are an array, an :class:`_types.ARRAY` of the sort expression's type. .. versionadded:: 1.1 @@ -1005,7 +1007,7 @@ class percentile_disc(OrderedSetAgg): modifier to supply a sort expression to operate upon. The return type of this function is the same as the sort expression, - or if the arguments are an array, an :class:`.types.ARRAY` of the sort + or if the arguments are an array, an :class:`_types.ARRAY` of the sort expression's type. .. versionadded:: 1.1 @@ -1079,7 +1081,7 @@ class cube(GenericFunction): r"""Implement the ``CUBE`` grouping operation. This function is used as part of the GROUP BY of a statement, - e.g. :meth:`.Select.group_by`:: + e.g. :meth:`_expression.Select.group_by`:: stmt = select( [func.sum(table.c.value), table.c.col_1, table.c.col_2] @@ -1095,7 +1097,7 @@ class rollup(GenericFunction): r"""Implement the ``ROLLUP`` grouping operation. This function is used as part of the GROUP BY of a statement, - e.g. :meth:`.Select.group_by`:: + e.g. :meth:`_expression.Select.group_by`:: stmt = select( [func.sum(table.c.value), table.c.col_1, table.c.col_2] @@ -1111,7 +1113,7 @@ class grouping_sets(GenericFunction): r"""Implement the ``GROUPING SETS`` grouping operation. This function is used as part of the GROUP BY of a statement, - e.g. :meth:`.Select.group_by`:: + e.g. :meth:`_expression.Select.group_by`:: stmt = select( [func.sum(table.c.value), table.c.col_1, table.c.col_2] diff --git a/lib/sqlalchemy/sql/operators.py b/lib/sqlalchemy/sql/operators.py index ae56822c22..c0699c2adc 100644 --- a/lib/sqlalchemy/sql/operators.py +++ b/lib/sqlalchemy/sql/operators.py @@ -61,7 +61,7 @@ class Operators(object): When used with SQL expressions, results in an AND operation, equivalent to - :func:`~.expression.and_`, that is:: + :func:`_expression.and_`, that is:: a & b @@ -85,7 +85,7 @@ class Operators(object): When used with SQL expressions, results in an OR operation, equivalent to - :func:`~.expression.or_`, that is:: + :func:`_expression.or_`, that is:: a | b @@ -109,7 +109,7 @@ class Operators(object): When used with SQL expressions, results in a NOT operation, equivalent to - :func:`~.expression.not_`, that is:: + :func:`_expression.not_`, that is:: ~a @@ -296,7 +296,7 @@ class custom_op(object): class ColumnOperators(Operators): """Defines boolean, comparison, and other operators for - :class:`.ColumnElement` expressions. + :class:`_expression.ColumnElement` expressions. By default, all methods call down to :meth:`.operate` or :meth:`.reverse_operate`, @@ -314,9 +314,9 @@ class ColumnOperators(Operators): def eq(a, b): return a == b - The core column expression unit :class:`.ColumnElement` + The core column expression unit :class:`_expression.ColumnElement` overrides :meth:`.Operators.operate` and others - to return further :class:`.ColumnElement` constructs, + to return further :class:`_expression.ColumnElement` constructs, so that the ``==`` operation above is replaced by a clause construct. @@ -579,7 +579,7 @@ class ColumnOperators(Operators): .. versionadded:: 1.3 "expanding" bound parameters now support empty lists - * a :func:`~.sql.expression.select` construct, which is usually a + * a :func:`_expression.select` construct, which is usually a correlated scalar select:: stmt.where( @@ -594,7 +594,7 @@ class ColumnOperators(Operators): WHERE COL IN (SELECT othertable.y FROM othertable WHERE othertable.x = table.x) - :param other: a list of literals, a :func:`~.sql.expression.select` + :param other: a list of literals, a :func:`_expression.select` construct, or a :func:`.bindparam` construct that includes the :paramref:`.bindparam.expanding` flag set to True. @@ -961,32 +961,32 @@ class ColumnOperators(Operators): return self.operate(match_op, other, **kwargs) def desc(self): - """Produce a :func:`~.expression.desc` clause against the + """Produce a :func:`_expression.desc` clause against the parent object.""" return self.operate(desc_op) def asc(self): - """Produce a :func:`~.expression.asc` clause against the + """Produce a :func:`_expression.asc` clause against the parent object.""" return self.operate(asc_op) def nullsfirst(self): - """Produce a :func:`~.expression.nullsfirst` clause against the + """Produce a :func:`_expression.nullsfirst` clause against the parent object.""" return self.operate(nullsfirst_op) def nullslast(self): - """Produce a :func:`~.expression.nullslast` clause against the + """Produce a :func:`_expression.nullslast` clause against the parent object.""" return self.operate(nullslast_op) def collate(self, collation): - """Produce a :func:`~.expression.collate` clause against + """Produce a :func:`_expression.collate` clause against the parent object, given the collation string. .. seealso:: - :func:`~.expression.collate` + :func:`_expression.collate` """ return self.operate(collate, collation) @@ -1032,21 +1032,21 @@ class ColumnOperators(Operators): return self.reverse_operate(mod, other) def between(self, cleft, cright, symmetric=False): - """Produce a :func:`~.expression.between` clause against + """Produce a :func:`_expression.between` clause against the parent object, given the lower and upper range. """ return self.operate(between_op, cleft, cright, symmetric=symmetric) def distinct(self): - """Produce a :func:`~.expression.distinct` clause against the + """Produce a :func:`_expression.distinct` clause against the parent object. """ return self.operate(distinct_op) def any_(self): - """Produce a :func:`~.expression.any_` clause against the + """Produce a :func:`_expression.any_` clause against the parent object. This operator is only appropriate against a scalar subquery @@ -1061,9 +1061,9 @@ class ColumnOperators(Operators): .. seealso:: - :func:`~.expression.any_` - standalone version + :func:`_expression.any_` - standalone version - :func:`~.expression.all_` - ALL operator + :func:`_expression.all_` - ALL operator .. versionadded:: 1.1 @@ -1071,7 +1071,7 @@ class ColumnOperators(Operators): return self.operate(any_op) def all_(self): - """Produce a :func:`~.expression.all_` clause against the + """Produce a :func:`_expression.all_` clause against the parent object. This operator is only appropriate against a scalar subquery @@ -1086,9 +1086,9 @@ class ColumnOperators(Operators): .. seealso:: - :func:`~.expression.all_` - standalone version + :func:`_expression.all_` - standalone version - :func:`~.expression.any_` - ANY operator + :func:`_expression.any_` - ANY operator .. versionadded:: 1.1 diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py index ac3fb96076..ec8d5a4585 100644 --- a/lib/sqlalchemy/sql/schema.py +++ b/lib/sqlalchemy/sql/schema.py @@ -60,9 +60,9 @@ RETAIN_SCHEMA = util.symbol("retain_schema") BLANK_SCHEMA = util.symbol( "blank_schema", - """Symbol indicating that a :class:`.Table` or :class:`.Sequence` + """Symbol indicating that a :class:`_schema.Table` or :class:`.Sequence` should have 'None' for its schema, even if the parent - :class:`.MetaData` has specified a schema. + :class:`_schema.MetaData` has specified a schema. .. versionadded:: 1.0.14 @@ -131,7 +131,7 @@ class SchemaItem(SchemaEventTarget, visitors.Visitable): The dictionary is automatically generated when first accessed. It can also be specified in the constructor of some objects, - such as :class:`.Table` and :class:`.Column`. + such as :class:`_schema.Table` and :class:`_schema.Column`. """ return {} @@ -155,12 +155,14 @@ class Table(DialectKWArgs, SchemaItem, TableClause): Column('value', String(50)) ) - The :class:`.Table` object constructs a unique instance of itself based + The :class:`_schema.Table` + object constructs a unique instance of itself based on its name and optional schema name within the given - :class:`.MetaData` object. Calling the :class:`.Table` - constructor with the same name and same :class:`.MetaData` argument - a second time will return the *same* :class:`.Table` object - in this way - the :class:`.Table` constructor acts as a registry function. + :class:`_schema.MetaData` object. Calling the :class:`_schema.Table` + constructor with the same name and same :class:`_schema.MetaData` argument + a second time will return the *same* :class:`_schema.Table` + object - in this way + the :class:`_schema.Table` constructor acts as a registry function. .. seealso:: @@ -171,10 +173,12 @@ class Table(DialectKWArgs, SchemaItem, TableClause): :param name: The name of this table as represented in the database. The table name, along with the value of the ``schema`` parameter, - forms a key which uniquely identifies this :class:`.Table` within - the owning :class:`.MetaData` collection. - Additional calls to :class:`.Table` with the same name, metadata, - and schema name will return the same :class:`.Table` object. + forms a key which uniquely identifies this :class:`_schema.Table` + within + the owning :class:`_schema.MetaData` collection. + Additional calls to :class:`_schema.Table` with the same name, + metadata, + and schema name will return the same :class:`_schema.Table` object. Names which contain no upper case characters will be treated as case insensitive names, and will not be quoted @@ -186,26 +190,34 @@ class Table(DialectKWArgs, SchemaItem, TableClause): ``quote=True`` to the constructor, or use the :class:`.quoted_name` construct to specify the name. - :param metadata: a :class:`.MetaData` object which will contain this + :param metadata: a :class:`_schema.MetaData` + object which will contain this table. The metadata is used as a point of association of this table with other tables which are referenced via foreign key. It also may be used to associate this table with a particular :class:`.Connectable`. :param \*args: Additional positional arguments are used primarily - to add the list of :class:`.Column` objects contained within this + to add the list of :class:`_schema.Column` + objects contained within this table. Similar to the style of a CREATE TABLE statement, other :class:`.SchemaItem` constructs may be added here, including - :class:`.PrimaryKeyConstraint`, and :class:`.ForeignKeyConstraint`. + :class:`.PrimaryKeyConstraint`, and + :class:`_schema.ForeignKeyConstraint`. - :param autoload: Defaults to False, unless :paramref:`.Table.autoload_with` - is set in which case it defaults to True; :class:`.Column` objects + :param autoload: Defaults to False, unless + :paramref:`_schema.Table.autoload_with` + is set in which case it defaults to True; :class:`_schema.Column` + objects for this table should be reflected from the database, possibly - augmenting or replacing existing :class:`.Column` objects that were + augmenting or replacing existing :class:`_schema.Column` + objects that were explicitly specified. - .. versionchanged:: 1.0.0 setting the :paramref:`.Table.autoload_with` - parameter implies that :paramref:`.Table.autoload` will default + .. versionchanged:: 1.0.0 setting the + :paramref:`_schema.Table.autoload_with` + parameter implies that :paramref:`_schema.Table.autoload` + will default to True. .. seealso:: @@ -213,69 +225,90 @@ class Table(DialectKWArgs, SchemaItem, TableClause): :ref:`metadata_reflection_toplevel` :param autoload_replace: Defaults to ``True``; when using - :paramref:`.Table.autoload` - in conjunction with :paramref:`.Table.extend_existing`, indicates - that :class:`.Column` objects present in the already-existing - :class:`.Table` object should be replaced with columns of the same + :paramref:`_schema.Table.autoload` + in conjunction with :paramref:`_schema.Table.extend_existing`, + indicates + that :class:`_schema.Column` objects present in the already-existing + :class:`_schema.Table` + object should be replaced with columns of the same name retrieved from the autoload process. When ``False``, columns already present under existing names will be omitted from the reflection process. - Note that this setting does not impact :class:`.Column` objects - specified programmatically within the call to :class:`.Table` that - also is autoloading; those :class:`.Column` objects will always + Note that this setting does not impact :class:`_schema.Column` objects + specified programmatically within the call to :class:`_schema.Table` + that + also is autoloading; those :class:`_schema.Column` objects will always replace existing columns of the same name when - :paramref:`.Table.extend_existing` is ``True``. + :paramref:`_schema.Table.extend_existing` is ``True``. .. seealso:: - :paramref:`.Table.autoload` + :paramref:`_schema.Table.autoload` - :paramref:`.Table.extend_existing` + :paramref:`_schema.Table.extend_existing` - :param autoload_with: An :class:`.Engine` or :class:`.Connection` object, - or a :class:`.Inspector` object as returned by :func:`.inspect` - against one, with which this :class:`.Table` object will be reflected. + :param autoload_with: An :class:`_engine.Engine` or + :class:`_engine.Connection` object, + or a :class:`_reflection.Inspector` object as returned by + :func:`_sa.inspect` + against one, with which this :class:`_schema.Table` + object will be reflected. When set to a non-None value, it implies that - :paramref:`.Table.autoload` is ``True``. If left unset, but - :paramref:`.Table.autoload` is explicitly set to ``True``, an autoload - operation will attempt to proceed by locating an :class:`.Engine` or - :class:`.Connection` bound to the underlying :class:`.MetaData` object. + :paramref:`_schema.Table.autoload` is ``True``. If left unset, but + :paramref:`_schema.Table.autoload` is explicitly set to ``True``, + an autoload + operation will attempt to proceed by locating an + :class:`_engine.Engine` or + :class:`_engine.Connection` bound to the underlying + :class:`_schema.MetaData` object. .. seealso:: - :paramref:`.Table.autoload` + :paramref:`_schema.Table.autoload` :param extend_existing: When ``True``, indicates that if this - :class:`.Table` is already present in the given :class:`.MetaData`, + :class:`_schema.Table` is already present in the given + :class:`_schema.MetaData`, apply further arguments within the constructor to the existing - :class:`.Table`. - - If :paramref:`.Table.extend_existing` or - :paramref:`.Table.keep_existing` are not set, and the given name - of the new :class:`.Table` refers to a :class:`.Table` that is - already present in the target :class:`.MetaData` collection, and - this :class:`.Table` specifies additional columns or other constructs + :class:`_schema.Table`. + + If :paramref:`_schema.Table.extend_existing` or + :paramref:`_schema.Table.keep_existing` are not set, + and the given name + of the new :class:`_schema.Table` refers to a :class:`_schema.Table` + that is + already present in the target :class:`_schema.MetaData` collection, + and + this :class:`_schema.Table` + specifies additional columns or other constructs or flags that modify the table's state, an error is raised. The purpose of these two mutually-exclusive flags - is to specify what action should be taken when a :class:`.Table` - is specified that matches an existing :class:`.Table`, yet specifies + is to specify what action should be taken when a + :class:`_schema.Table` + is specified that matches an existing :class:`_schema.Table`, + yet specifies additional constructs. - :paramref:`.Table.extend_existing` will also work in conjunction - with :paramref:`.Table.autoload` to run a new reflection - operation against the database, even if a :class:`.Table` + :paramref:`_schema.Table.extend_existing` + will also work in conjunction + with :paramref:`_schema.Table.autoload` to run a new reflection + operation against the database, even if a :class:`_schema.Table` of the same name is already present in the target - :class:`.MetaData`; newly reflected :class:`.Column` objects + :class:`_schema.MetaData`; newly reflected :class:`_schema.Column` + objects and other options will be added into the state of the - :class:`.Table`, potentially overwriting existing columns + :class:`_schema.Table`, potentially overwriting existing columns and options of the same name. - As is always the case with :paramref:`.Table.autoload`, - :class:`.Column` objects can be specified in the same :class:`.Table` + As is always the case with :paramref:`_schema.Table.autoload`, + :class:`_schema.Column` objects can be specified in the same + :class:`_schema.Table` constructor, which will take precedence. Below, the existing - table ``mytable`` will be augmented with :class:`.Column` objects - both reflected from the database, as well as the given :class:`.Column` + table ``mytable`` will be augmented with :class:`_schema.Column` + objects + both reflected from the database, as well as the given + :class:`_schema.Column` named "y":: Table("mytable", metadata, @@ -287,11 +320,11 @@ class Table(DialectKWArgs, SchemaItem, TableClause): .. seealso:: - :paramref:`.Table.autoload` + :paramref:`_schema.Table.autoload` - :paramref:`.Table.autoload_replace` + :paramref:`_schema.Table.autoload_replace` - :paramref:`.Table.keep_existing` + :paramref:`_schema.Table.keep_existing` :param implicit_returning: True by default - indicates that @@ -305,15 +338,20 @@ class Table(DialectKWArgs, SchemaItem, TableClause): ``Table`` object. Defaults to ``None`` which indicates all columns should be reflected. - :param resolve_fks: Whether or not to reflect :class:`.Table` objects - related to this one via :class:`.ForeignKey` objects, when - :paramref:`.Table.autoload` or :paramref:`.Table.autoload_with` is + :param resolve_fks: Whether or not to reflect :class:`_schema.Table` + objects + related to this one via :class:`_schema.ForeignKey` objects, when + :paramref:`_schema.Table.autoload` or + :paramref:`_schema.Table.autoload_with` is specified. Defaults to True. Set to False to disable reflection of - related tables as :class:`.ForeignKey` objects are encountered; may be + related tables as :class:`_schema.ForeignKey` + objects are encountered; may be used either to save on SQL calls or to avoid issues with related tables that can't be accessed. Note that if a related table is already present - in the :class:`.MetaData` collection, or becomes present later, a - :class:`.ForeignKey` object associated with this :class:`.Table` will + in the :class:`_schema.MetaData` collection, or becomes present later, + a + :class:`_schema.ForeignKey` object associated with this + :class:`_schema.Table` will resolve to that table normally. .. versionadded:: 1.3 @@ -327,34 +365,41 @@ class Table(DialectKWArgs, SchemaItem, TableClause): :attr:`.SchemaItem.info` attribute of this object. :param keep_existing: When ``True``, indicates that if this Table - is already present in the given :class:`.MetaData`, ignore + is already present in the given :class:`_schema.MetaData`, ignore further arguments within the constructor to the existing - :class:`.Table`, and return the :class:`.Table` object as + :class:`_schema.Table`, and return the :class:`_schema.Table` + object as originally created. This is to allow a function that wishes - to define a new :class:`.Table` on first call, but on - subsequent calls will return the same :class:`.Table`, + to define a new :class:`_schema.Table` on first call, but on + subsequent calls will return the same :class:`_schema.Table`, without any of the declarations (particularly constraints) being applied a second time. - If :paramref:`.Table.extend_existing` or - :paramref:`.Table.keep_existing` are not set, and the given name - of the new :class:`.Table` refers to a :class:`.Table` that is - already present in the target :class:`.MetaData` collection, and - this :class:`.Table` specifies additional columns or other constructs + If :paramref:`_schema.Table.extend_existing` or + :paramref:`_schema.Table.keep_existing` are not set, + and the given name + of the new :class:`_schema.Table` refers to a :class:`_schema.Table` + that is + already present in the target :class:`_schema.MetaData` collection, + and + this :class:`_schema.Table` + specifies additional columns or other constructs or flags that modify the table's state, an error is raised. The purpose of these two mutually-exclusive flags - is to specify what action should be taken when a :class:`.Table` - is specified that matches an existing :class:`.Table`, yet specifies + is to specify what action should be taken when a + :class:`_schema.Table` + is specified that matches an existing :class:`_schema.Table`, + yet specifies additional constructs. .. seealso:: - :paramref:`.Table.extend_existing` + :paramref:`_schema.Table.extend_existing` :param listeners: A list of tuples of the form ``(, )`` which will be passed to :func:`.event.listen` upon construction. This alternate hook to :func:`.event.listen` allows the establishment - of a listener function specific to this :class:`.Table` before + of a listener function specific to this :class:`_schema.Table` before the "autoload" process begins. Particularly useful for the :meth:`.DDLEvents.column_reflect` event:: @@ -370,7 +415,7 @@ class Table(DialectKWArgs, SchemaItem, TableClause): ]) :param mustexist: When ``True``, indicates that this Table must already - be present in the given :class:`.MetaData` collection, else + be present in the given :class:`_schema.MetaData` collection, else an exception is raised. :param prefixes: @@ -391,16 +436,23 @@ class Table(DialectKWArgs, SchemaItem, TableClause): the table resides in a schema other than the default selected schema for the engine's database connection. Defaults to ``None``. - If the owning :class:`.MetaData` of this :class:`.Table` specifies its - own :paramref:`.MetaData.schema` parameter, then that schema name will - be applied to this :class:`.Table` if the schema parameter here is set - to ``None``. To set a blank schema name on a :class:`.Table` that - would otherwise use the schema set on the owning :class:`.MetaData`, + If the owning :class:`_schema.MetaData` of this :class:`_schema.Table` + specifies its + own :paramref:`_schema.MetaData.schema` parameter, + then that schema name will + be applied to this :class:`_schema.Table` + if the schema parameter here is set + to ``None``. To set a blank schema name on a :class:`_schema.Table` + that + would otherwise use the schema set on the owning + :class:`_schema.MetaData`, specify the special symbol :attr:`.BLANK_SCHEMA`. .. versionadded:: 1.0.14 Added the :attr:`.BLANK_SCHEMA` symbol to - allow a :class:`.Table` to have a blank schema name even when the - parent :class:`.MetaData` specifies :paramref:`.MetaData.schema`. + allow a :class:`_schema.Table` + to have a blank schema name even when the + parent :class:`_schema.MetaData` specifies + :paramref:`_schema.MetaData.schema`. The quoting rules for the schema name are the same as those for the ``name`` parameter, in that quoting is applied for reserved words or @@ -411,8 +463,9 @@ class Table(DialectKWArgs, SchemaItem, TableClause): :param comment: Optional string that will render an SQL comment on table creation. - .. versionadded:: 1.2 Added the :paramref:`.Table.comment` parameter - to :class:`.Table`. + .. versionadded:: 1.2 Added the :paramref:`_schema.Table.comment` + parameter + to :class:`_schema.Table`. :param \**kw: Additional keyword arguments not mentioned above are dialect specific, and passed in the form ``_``. @@ -482,10 +535,10 @@ class Table(DialectKWArgs, SchemaItem, TableClause): metadata._remove_table(name, schema) def __init__(self, *args, **kw): - """Constructor for :class:`~.schema.Table`. + """Constructor for :class:`_schema.Table`. This method is a no-op. See the top-level - documentation for :class:`~.schema.Table` + documentation for :class:`_schema.Table` for constructor arguments. """ @@ -596,10 +649,11 @@ class Table(DialectKWArgs, SchemaItem, TableClause): @property def foreign_key_constraints(self): - """:class:`.ForeignKeyConstraint` objects referred to by this - :class:`.Table`. + """:class:`_schema.ForeignKeyConstraint` objects referred to by this + :class:`_schema.Table`. - This list is produced from the collection of :class:`.ForeignKey` + This list is produced from the collection of + :class:`_schema.ForeignKey` objects currently associated. .. versionadded:: 1.0.0 @@ -676,12 +730,13 @@ class Table(DialectKWArgs, SchemaItem, TableClause): @property def key(self): - """Return the 'key' for this :class:`.Table`. + """Return the 'key' for this :class:`_schema.Table`. This value is used as the dictionary key within the - :attr:`.MetaData.tables` collection. It is typically the same - as that of :attr:`.Table.name` for a table with no - :attr:`.Table.schema` set; otherwise it is typically of the form + :attr:`_schema.MetaData.tables` collection. It is typically the same + as that of :attr:`_schema.Table.name` for a table with no + :attr:`_schema.Table.schema` + set; otherwise it is typically of the form ``schemaname.tablename``. """ @@ -719,13 +774,13 @@ class Table(DialectKWArgs, SchemaItem, TableClause): self._extra_dependencies.add(table) def append_column(self, column): - """Append a :class:`~.schema.Column` to this :class:`~.schema.Table`. + """Append a :class:`_schema.Column` to this :class:`_schema.Table`. - The "key" of the newly added :class:`~.schema.Column`, i.e. the + The "key" of the newly added :class:`_schema.Column`, i.e. the value of its ``.key`` attribute, will then be available - in the ``.c`` collection of this :class:`~.schema.Table`, and the + in the ``.c`` collection of this :class:`_schema.Table`, and the column definition will be included in any CREATE TABLE, SELECT, - UPDATE, etc. statements generated from this :class:`~.schema.Table` + UPDATE, etc. statements generated from this :class:`_schema.Table` construct. Note that this does **not** change the definition of the table @@ -741,13 +796,13 @@ class Table(DialectKWArgs, SchemaItem, TableClause): column._set_parent_with_dispatch(self) def append_constraint(self, constraint): - """Append a :class:`~.schema.Constraint` to this - :class:`~.schema.Table`. + """Append a :class:`_schema.Constraint` to this + :class:`_schema.Table`. This has the effect of the constraint being included in any future CREATE TABLE statement, assuming specific DDL creation events have not been associated with the given - :class:`~.schema.Constraint` object. + :class:`_schema.Constraint` object. Note that this does **not** produce the constraint within the relational database automatically, for a table that already exists @@ -782,9 +837,9 @@ class Table(DialectKWArgs, SchemaItem, TableClause): @util.deprecated( "1.4", - "The :meth:`.Table.exists` method is deprecated and will be " + "The :meth:`_schema.Table.exists` method is deprecated and will be " "removed in a future release. Please refer to " - ":meth:`.Inspector.has_table`.", + ":meth:`_reflection.Inspector.has_table`.", ) def exists(self, bind=None): """Return True if this table exists. @@ -799,12 +854,12 @@ class Table(DialectKWArgs, SchemaItem, TableClause): def create(self, bind=None, checkfirst=False): """Issue a ``CREATE`` statement for this - :class:`.Table`, using the given :class:`.Connectable` + :class:`_schema.Table`, using the given :class:`.Connectable` for connectivity. .. seealso:: - :meth:`.MetaData.create_all`. + :meth:`_schema.MetaData.create_all`. """ @@ -814,12 +869,12 @@ class Table(DialectKWArgs, SchemaItem, TableClause): def drop(self, bind=None, checkfirst=False): """Issue a ``DROP`` statement for this - :class:`.Table`, using the given :class:`.Connectable` + :class:`_schema.Table`, using the given :class:`.Connectable` for connectivity. .. seealso:: - :meth:`.MetaData.drop_all`. + :meth:`_schema.MetaData.drop_all`. """ if bind is None: @@ -833,8 +888,9 @@ class Table(DialectKWArgs, SchemaItem, TableClause): referred_schema_fn=None, name=None, ): - """Return a copy of this :class:`.Table` associated with a different - :class:`.MetaData`. + """Return a copy of this :class:`_schema.Table` + associated with a different + :class:`_schema.MetaData`. E.g.:: @@ -845,16 +901,19 @@ class Table(DialectKWArgs, SchemaItem, TableClause): m2 = MetaData() user_copy = user.tometadata(m2) - :param metadata: Target :class:`.MetaData` object, into which the - new :class:`.Table` object will be created. + :param metadata: Target :class:`_schema.MetaData` object, + into which the + new :class:`_schema.Table` object will be created. :param schema: optional string name indicating the target schema. Defaults to the special symbol :attr:`.RETAIN_SCHEMA` which indicates that no change to the schema name should be made in the new - :class:`.Table`. If set to a string name, the new :class:`.Table` + :class:`_schema.Table`. If set to a string name, the new + :class:`_schema.Table` will have this new name as the ``.schema``. If set to ``None``, the schema will be set to that of the schema set on the target - :class:`.MetaData`, which is typically ``None`` as well, unless + :class:`_schema.MetaData`, which is typically ``None`` as well, + unless set explicitly:: m2 = MetaData(schema='newschema') @@ -869,10 +928,10 @@ class Table(DialectKWArgs, SchemaItem, TableClause): :param referred_schema_fn: optional callable which can be supplied in order to provide for the schema name that should be assigned - to the referenced table of a :class:`.ForeignKeyConstraint`. - The callable accepts this parent :class:`.Table`, the + to the referenced table of a :class:`_schema.ForeignKeyConstraint`. + The callable accepts this parent :class:`_schema.Table`, the target schema that we are changing to, the - :class:`.ForeignKeyConstraint` object, and the existing + :class:`_schema.ForeignKeyConstraint` object, and the existing "target schema" of that constraint. The function should return the string schema name that should be applied. E.g.:: @@ -891,7 +950,8 @@ class Table(DialectKWArgs, SchemaItem, TableClause): :param name: optional string name indicating the target table name. If not specified or None, the table name is retained. This allows - a :class:`.Table` to be copied to the same :class:`.MetaData` target + a :class:`_schema.Table` to be copied to the same + :class:`_schema.MetaData` target with a new name. .. versionadded:: 1.0.0 @@ -985,7 +1045,7 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause): The name field may be omitted at construction time and applied later, at any time before the Column is associated with a - :class:`.Table`. This is to support convenient + :class:`_schema.Table`. This is to support convenient usage within the :mod:`~sqlalchemy.ext.declarative` extension. :param type\_: The column's type, indicated using an instance which @@ -1004,21 +1064,24 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause): If the ``type`` is ``None`` or is omitted, it will first default to the special type :class:`.NullType`. If and when this - :class:`.Column` is made to refer to another column using - :class:`.ForeignKey` and/or :class:`.ForeignKeyConstraint`, the type + :class:`_schema.Column` is made to refer to another column using + :class:`_schema.ForeignKey` and/or + :class:`_schema.ForeignKeyConstraint`, the type of the remote-referenced column will be copied to this column as well, at the moment that the foreign key is resolved against that - remote :class:`.Column` object. + remote :class:`_schema.Column` object. .. versionchanged:: 0.9.0 - Support for propagation of type to a :class:`.Column` from its - :class:`.ForeignKey` object has been improved and should be + Support for propagation of type to a :class:`_schema.Column` + from its + :class:`_schema.ForeignKey` object has been improved and should be more reliable and timely. :param \*args: Additional positional arguments include various :class:`.SchemaItem` derived constructs which will be applied as options to the column. These include instances of - :class:`.Constraint`, :class:`.ForeignKey`, :class:`.ColumnDefault`, + :class:`.Constraint`, :class:`_schema.ForeignKey`, + :class:`.ColumnDefault`, :class:`.Sequence`, :class:`.Computed`. In some cases an equivalent keyword argument is available such as ``server_default``, ``default`` and ``unique``. @@ -1053,7 +1116,8 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause): (multi-column) primary keys, autoincrement is never implicitly enabled; as always, ``autoincrement=True`` will allow for at most one of those columns to be an "autoincrement" column. - ``autoincrement=True`` may also be set on a :class:`.Column` + ``autoincrement=True`` may also be set on a + :class:`_schema.Column` that has an explicit client-side or server-side default, subject to limitations of the backend database and dialect. @@ -1064,7 +1128,8 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause): * Part of the primary key - * Not referring to another column via :class:`.ForeignKey`, unless + * Not referring to another column via :class:`_schema.ForeignKey`, + unless the value is specified as ``'ignore_fk'``:: # turn on autoincrement for this column despite @@ -1102,14 +1167,15 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause): :param default: A scalar, Python callable, or - :class:`.ColumnElement` expression representing the + :class:`_expression.ColumnElement` expression representing the *default value* for this column, which will be invoked upon insert if this column is otherwise not specified in the VALUES clause of the insert. This is a shortcut to using :class:`.ColumnDefault` as a positional argument; see that class for full detail on the structure of the argument. - Contrast this argument to :paramref:`.Column.server_default` + Contrast this argument to + :paramref:`_schema.Column.server_default` which creates a default generator on the database side. .. seealso:: @@ -1118,11 +1184,13 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause): :param doc: optional String that can be used by the ORM or similar to document attributes on the Python side. This attribute does - **not** render SQL comments; use the :paramref:`.Column.comment` + **not** render SQL comments; use the + :paramref:`_schema.Column.comment` parameter for this purpose. :param key: An optional string identifier which will identify this - ``Column`` object on the :class:`.Table`. When a key is provided, + ``Column`` object on the :class:`_schema.Table`. + When a key is provided, this is the only identifier referencing the ``Column`` within the application, including ORM attribute mapping; the ``name`` field is used only when rendering SQL. @@ -1141,7 +1209,8 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause): ``True``, will normally generate nothing (in SQL this defaults to "NULL"), except in some very specific backend-specific edge cases where "NULL" may render explicitly. Defaults to ``True`` unless - :paramref:`~.Column.primary_key` is also ``True``, in which case it + :paramref:`_schema.Column.primary_key` is also ``True``, + in which case it defaults to ``False``. This parameter is only used when issuing CREATE TABLE statements. @@ -1160,7 +1229,7 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause): :param primary_key: If ``True``, marks this column as a primary key column. Multiple columns can have this flag set to specify composite primary keys. As an alternative, the primary key of a - :class:`.Table` can be specified via an explicit + :class:`_schema.Table` can be specified via an explicit :class:`.PrimaryKeyConstraint` object. :param server_default: A :class:`.FetchedValue` instance, str, Unicode @@ -1233,8 +1302,9 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause): :param comment: Optional string that will render an SQL comment on table creation. - .. versionadded:: 1.2 Added the :paramref:`.Column.comment` - parameter to :class:`.Column`. + .. versionadded:: 1.2 Added the + :paramref:`_schema.Column.comment` + parameter to :class:`_schema.Column`. """ @@ -1600,7 +1670,8 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause): class ForeignKey(DialectKWArgs, SchemaItem): """Defines a dependency between two columns. - ``ForeignKey`` is specified as an argument to a :class:`.Column` object, + ``ForeignKey`` is specified as an argument to a :class:`_schema.Column` + object, e.g.:: t = Table("remote_table", metadata, @@ -1609,24 +1680,26 @@ class ForeignKey(DialectKWArgs, SchemaItem): Note that ``ForeignKey`` is only a marker object that defines a dependency between two columns. The actual constraint - is in all cases represented by the :class:`.ForeignKeyConstraint` + is in all cases represented by the :class:`_schema.ForeignKeyConstraint` object. This object will be generated automatically when - a ``ForeignKey`` is associated with a :class:`.Column` which - in turn is associated with a :class:`.Table`. Conversely, - when :class:`.ForeignKeyConstraint` is applied to a :class:`.Table`, + a ``ForeignKey`` is associated with a :class:`_schema.Column` which + in turn is associated with a :class:`_schema.Table`. Conversely, + when :class:`_schema.ForeignKeyConstraint` is applied to a + :class:`_schema.Table`, ``ForeignKey`` markers are automatically generated to be - present on each associated :class:`.Column`, which are also + present on each associated :class:`_schema.Column`, which are also associated with the constraint object. Note that you cannot define a "composite" foreign key constraint, that is a constraint between a grouping of multiple parent/child columns, using ``ForeignKey`` objects. To define this grouping, - the :class:`.ForeignKeyConstraint` object must be used, and applied - to the :class:`.Table`. The associated ``ForeignKey`` objects + the :class:`_schema.ForeignKeyConstraint` object must be used, and applied + to the :class:`_schema.Table`. The associated ``ForeignKey`` objects are created automatically. The ``ForeignKey`` objects associated with an individual - :class:`.Column` object are available in the `foreign_keys` collection + :class:`_schema.Column` + object are available in the `foreign_keys` collection of that column. Further examples of foreign key configuration are in @@ -1654,12 +1727,13 @@ class ForeignKey(DialectKWArgs, SchemaItem): r""" Construct a column-level FOREIGN KEY. - The :class:`.ForeignKey` object when constructed generates a - :class:`.ForeignKeyConstraint` which is associated with the parent - :class:`.Table` object's collection of constraints. + The :class:`_schema.ForeignKey` object when constructed generates a + :class:`_schema.ForeignKeyConstraint` + which is associated with the parent + :class:`_schema.Table` object's collection of constraints. :param column: A single target column for the key relationship. A - :class:`.Column` object or a column name as a string: + :class:`_schema.Column` object or a column name as a string: ``tablename.columnkey`` or ``schema.tablename.columnkey``. ``columnkey`` is the ``key`` which has been assigned to the column (defaults to the column name itself), unless ``link_to_name`` is @@ -1687,14 +1761,15 @@ class ForeignKey(DialectKWArgs, SchemaItem): assigned ``key``. :param use_alter: passed to the underlying - :class:`.ForeignKeyConstraint` to indicate the constraint should + :class:`_schema.ForeignKeyConstraint` + to indicate the constraint should be generated/dropped externally from the CREATE TABLE/ DROP TABLE - statement. See :paramref:`.ForeignKeyConstraint.use_alter` + statement. See :paramref:`_schema.ForeignKeyConstraint.use_alter` for further description. .. seealso:: - :paramref:`.ForeignKeyConstraint.use_alter` + :paramref:`_schema.ForeignKeyConstraint.use_alter` :ref:`use_alter` @@ -1710,7 +1785,8 @@ class ForeignKey(DialectKWArgs, SchemaItem): :param \**dialect_kw: Additional keyword arguments are dialect specific, and passed in the form ``_``. The arguments are ultimately handled by a corresponding - :class:`.ForeignKeyConstraint`. See the documentation regarding + :class:`_schema.ForeignKeyConstraint`. + See the documentation regarding an individual dialect at :ref:`dialect_toplevel` for detail on documented arguments. @@ -1756,16 +1832,16 @@ class ForeignKey(DialectKWArgs, SchemaItem): return "ForeignKey(%r)" % self._get_colspec() def copy(self, schema=None): - """Produce a copy of this :class:`.ForeignKey` object. + """Produce a copy of this :class:`_schema.ForeignKey` object. - The new :class:`.ForeignKey` will not be bound - to any :class:`.Column`. + The new :class:`_schema.ForeignKey` will not be bound + to any :class:`_schema.Column`. This method is usually used by the internal - copy procedures of :class:`.Column`, :class:`.Table`, - and :class:`.MetaData`. + copy procedures of :class:`_schema.Column`, :class:`_schema.Table`, + and :class:`_schema.MetaData`. - :param schema: The returned :class:`.ForeignKey` will + :param schema: The returned :class:`_schema.ForeignKey` will reference the original table and column name, qualified by the given string schema name. @@ -1787,7 +1863,7 @@ class ForeignKey(DialectKWArgs, SchemaItem): def _get_colspec(self, schema=None, table_name=None): """Return a string based 'column specification' for this - :class:`.ForeignKey`. + :class:`_schema.ForeignKey`. This is usually the equivalent of the string-based "tablename.colname" argument first passed to the object's constructor. @@ -1829,17 +1905,20 @@ class ForeignKey(DialectKWArgs, SchemaItem): target_fullname = property(_get_colspec) def references(self, table): - """Return True if the given :class:`.Table` is referenced by this - :class:`.ForeignKey`.""" + """Return True if the given :class:`_schema.Table` + is referenced by this + :class:`_schema.ForeignKey`.""" return table.corresponding_column(self.column) is not None def get_referent(self, table): - """Return the :class:`.Column` in the given :class:`.Table` - referenced by this :class:`.ForeignKey`. + """Return the :class:`_schema.Column` in the given + :class:`_schema.Table` + referenced by this :class:`_schema.ForeignKey`. - Returns None if this :class:`.ForeignKey` does not reference the given - :class:`.Table`. + Returns None if this :class:`_schema.ForeignKey` + does not reference the given + :class:`_schema.Table`. """ @@ -1966,8 +2045,8 @@ class ForeignKey(DialectKWArgs, SchemaItem): @util.memoized_property def column(self): - """Return the target :class:`.Column` referenced by this - :class:`.ForeignKey`. + """Return the target :class:`_schema.Column` referenced by this + :class:`_schema.ForeignKey`. If no target column has been established, an exception is raised. @@ -2097,7 +2176,8 @@ class DefaultGenerator(SchemaItem): @util.deprecated_20( ":meth:`.DefaultGenerator.execute`", alternative="All statement execution in SQLAlchemy 2.0 is performed " - "by the :meth:`.Connection.execute` method of :class:`.Connection`, " + "by the :meth:`_engine.Connection.execute` method of " + ":class:`_engine.Connection`, " "or in the ORM by the :meth:`.Session.execute` method of " ":class:`.Session`.", ) @@ -2126,7 +2206,7 @@ class ColumnDefault(DefaultGenerator): :class:`.ColumnDefault` is generated automatically whenever the ``default``, ``onupdate`` arguments of - :class:`.Column` are used. A :class:`.ColumnDefault` + :class:`_schema.Column` are used. A :class:`.ColumnDefault` can be passed positionally as well. For example, the following:: @@ -2151,7 +2231,7 @@ class ColumnDefault(DefaultGenerator): string, integer, boolean, or other simple type. The default value will be used as is each time. * a SQL expression, that is one which derives from - :class:`.ColumnElement`. The SQL expression will + :class:`_expression.ColumnElement`. The SQL expression will be rendered into the INSERT or UPDATE statement, or in the case of a primary key column when RETURNING is not used may be @@ -2162,7 +2242,7 @@ class ColumnDefault(DefaultGenerator): zero or one positional arguments. The one-argument form will receive an instance of the :class:`.ExecutionContext`, which provides contextual information as to the current - :class:`.Connection` in use as well as the current + :class:`_engine.Connection` in use as well as the current statement and parameters. """ @@ -2236,8 +2316,9 @@ class Sequence(roles.StatementRole, DefaultGenerator): The :class:`.Sequence` object represents the name and configurational parameters of a database sequence. It also represents - a construct that can be "executed" by a SQLAlchemy :class:`.Engine` - or :class:`.Connection`, rendering the appropriate "next value" function + a construct that can be "executed" by a SQLAlchemy :class:`_engine.Engine` + or :class:`_engine.Connection`, + rendering the appropriate "next value" function for the target database and returning a result. The :class:`.Sequence` is typically associated with a primary key column:: @@ -2248,7 +2329,7 @@ class Sequence(roles.StatementRole, DefaultGenerator): primary_key=True) ) - When CREATE TABLE is emitted for the above :class:`.Table`, if the + When CREATE TABLE is emitted for the above :class:`_schema.Table`, if the target platform supports sequences, a CREATE SEQUENCE statement will be emitted as well. For platforms that don't support sequences, the :class:`.Sequence` construct is ignored. @@ -2348,8 +2429,9 @@ class Sequence(roles.StatementRole, DefaultGenerator): :param schema: Optional schema name for the sequence, if located in a schema other than the default. The rules for selecting the - schema name when a :class:`.MetaData` is also present are the same - as that of :paramref:`.Table.schema`. + schema name when a :class:`_schema.MetaData` + is also present are the same + as that of :paramref:`_schema.Table.schema`. :param cache: optional integer value; number of future values in the sequence which are calculated in advance. Renders the CACHE keyword @@ -2377,27 +2459,32 @@ class Sequence(roles.StatementRole, DefaultGenerator): :param quote_schema: set the quoting preferences for the ``schema`` name. - :param metadata: optional :class:`.MetaData` object which this + :param metadata: optional :class:`_schema.MetaData` object which this :class:`.Sequence` will be associated with. A :class:`.Sequence` - that is associated with a :class:`.MetaData` gains the following + that is associated with a :class:`_schema.MetaData` + gains the following capabilities: - * The :class:`.Sequence` will inherit the :paramref:`.MetaData.schema` - parameter specified to the target :class:`.MetaData`, which + * The :class:`.Sequence` will inherit the + :paramref:`_schema.MetaData.schema` + parameter specified to the target :class:`_schema.MetaData`, which affects the production of CREATE / DROP DDL, if any. * The :meth:`.Sequence.create` and :meth:`.Sequence.drop` methods - automatically use the engine bound to the :class:`.MetaData` + automatically use the engine bound to the :class:`_schema.MetaData` object, if any. - * The :meth:`.MetaData.create_all` and :meth:`.MetaData.drop_all` + * The :meth:`_schema.MetaData.create_all` and + :meth:`_schema.MetaData.drop_all` methods will emit CREATE / DROP for this :class:`.Sequence`, even if the :class:`.Sequence` is not associated with any - :class:`.Table` / :class:`.Column` that's a member of this - :class:`.MetaData`. + :class:`_schema.Table` / :class:`_schema.Column` + that's a member of this + :class:`_schema.MetaData`. The above behaviors can only occur if the :class:`.Sequence` is - explicitly associated with the :class:`.MetaData` via this parameter. + explicitly associated with the :class:`_schema.MetaData` + via this parameter. .. seealso:: @@ -2405,7 +2492,8 @@ class Sequence(roles.StatementRole, DefaultGenerator): :paramref:`.Sequence.metadata` parameter. :param for_update: Indicates this :class:`.Sequence`, when associated - with a :class:`.Column`, should be invoked for UPDATE statements + with a :class:`_schema.Column`, + should be invoked for UPDATE statements on that column's table, rather than for INSERT statements, when no value is otherwise present for that column in the statement. @@ -2555,7 +2643,7 @@ class DefaultClause(FetchedValue): :class:`.DefaultClause` is generated automatically whenever the ``server_default``, ``server_onupdate`` arguments of - :class:`.Column` are used. A :class:`.DefaultClause` + :class:`_schema.Column` are used. A :class:`.DefaultClause` can be passed positionally as well. For example, the following:: @@ -2672,7 +2760,8 @@ class Constraint(DialectKWArgs, SchemaItem): class ColumnCollectionMixin(object): columns = None - """A :class:`.ColumnCollection` of :class:`.Column` objects. + """A :class:`_expression.ColumnCollection` of :class:`_schema.Column` + objects. This collection represents the columns which are referred to by this object. @@ -2799,7 +2888,7 @@ class ColumnCollectionConstraint(ColumnCollectionMixin, Constraint): ) columns = None - """A :class:`.ColumnCollection` representing the set of columns + """A :class:`_expression.ColumnCollection` representing the set of columns for this constraint. """ @@ -2824,7 +2913,8 @@ class ColumnCollectionConstraint(ColumnCollectionMixin, Constraint): """Return True if this constraint contains the given column. Note that this object also contains an attribute ``.columns`` - which is a :class:`.ColumnCollection` of :class:`.Column` objects. + which is a :class:`_expression.ColumnCollection` of + :class:`_schema.Column` objects. """ @@ -2870,7 +2960,8 @@ class CheckConstraint(ColumnCollectionConstraint): :param sqltext: A string containing the constraint definition, which will be used verbatim, or a SQL expression construct. If given as a string, - the object is converted to a :func:`.text` object. If the textual + the object is converted to a :func:`_expression.text` object. + If the textual string includes a colon character, escape this using a backslash:: CheckConstraint(r"foo ~ E'a(?\:b|c)d") @@ -2938,9 +3029,10 @@ class ForeignKeyConstraint(ColumnCollectionConstraint): Defines a single column or composite FOREIGN KEY ... REFERENCES constraint. For a no-frills, single column foreign key, adding a - :class:`.ForeignKey` to the definition of a :class:`.Column` is a + :class:`_schema.ForeignKey` to the definition of a :class:`_schema.Column` + is a shorthand equivalent for an unnamed, single column - :class:`.ForeignKeyConstraint`. + :class:`_schema.ForeignKeyConstraint`. Examples of foreign key configuration are in :ref:`metadata_foreignkeys`. @@ -3000,16 +3092,17 @@ class ForeignKeyConstraint(ColumnCollectionConstraint): have been created, and drop it via an ALTER TABLE statement before the full collection of tables are dropped. - The use of :paramref:`.ForeignKeyConstraint.use_alter` is + The use of :paramref:`_schema.ForeignKeyConstraint.use_alter` is particularly geared towards the case where two or more tables are established within a mutually-dependent foreign key constraint - relationship; however, the :meth:`.MetaData.create_all` and - :meth:`.MetaData.drop_all` methods will perform this resolution + relationship; however, the :meth:`_schema.MetaData.create_all` and + :meth:`_schema.MetaData.drop_all` + methods will perform this resolution automatically, so the flag is normally not needed. .. versionchanged:: 1.0.0 Automatic resolution of foreign key cycles has been added, removing the need to use the - :paramref:`.ForeignKeyConstraint.use_alter` in typical use + :paramref:`_schema.ForeignKeyConstraint.use_alter` in typical use cases. .. seealso:: @@ -3097,15 +3190,16 @@ class ForeignKeyConstraint(ColumnCollectionConstraint): self.elements.append(fk) columns = None - """A :class:`.ColumnCollection` representing the set of columns + """A :class:`_expression.ColumnCollection` representing the set of columns for this constraint. """ elements = None - """A sequence of :class:`.ForeignKey` objects. + """A sequence of :class:`_schema.ForeignKey` objects. - Each :class:`.ForeignKey` represents a single referring column/referred + Each :class:`_schema.ForeignKey` + represents a single referring column/referred column pair. This collection is intended to be read-only. @@ -3126,8 +3220,8 @@ class ForeignKeyConstraint(ColumnCollectionConstraint): @property def referred_table(self): - """The :class:`.Table` object to which this - :class:`.ForeignKeyConstraint` references. + """The :class:`_schema.Table` object to which this + :class:`_schema.ForeignKeyConstraint` references. This is a dynamically calculated attribute which may not be available if the constraint and/or parent table is not yet associated with @@ -3151,11 +3245,11 @@ class ForeignKeyConstraint(ColumnCollectionConstraint): @property def column_keys(self): """Return a list of string keys representing the local - columns in this :class:`.ForeignKeyConstraint`. + columns in this :class:`_schema.ForeignKeyConstraint`. This list is either the original string arguments sent - to the constructor of the :class:`.ForeignKeyConstraint`, - or if the constraint has been initialized with :class:`.Column` + to the constructor of the :class:`_schema.ForeignKeyConstraint`, + or if the constraint has been initialized with :class:`_schema.Column` objects, is the string .key of each element. .. versionadded:: 1.0.0 @@ -3225,9 +3319,9 @@ class PrimaryKeyConstraint(ColumnCollectionConstraint): """A table-level PRIMARY KEY constraint. The :class:`.PrimaryKeyConstraint` object is present automatically - on any :class:`.Table` object; it is assigned a set of - :class:`.Column` objects corresponding to those marked with - the :paramref:`.Column.primary_key` flag:: + on any :class:`_schema.Table` object; it is assigned a set of + :class:`_schema.Column` objects corresponding to those marked with + the :paramref:`_schema.Column.primary_key` flag:: >>> my_table = Table('mytable', metadata, ... Column('id', Integer, primary_key=True), @@ -3242,7 +3336,7 @@ class PrimaryKeyConstraint(ColumnCollectionConstraint): primary_key=True, nullable=False) ) - The primary key of a :class:`.Table` can also be specified by using + The primary key of a :class:`_schema.Table` can also be specified by using a :class:`.PrimaryKeyConstraint` object explicitly; in this mode of usage, the "name" of the constraint can also be specified, as well as other options which may be recognized by dialects:: @@ -3275,7 +3369,7 @@ class PrimaryKeyConstraint(ColumnCollectionConstraint): :class:`.PrimaryKeyConstraint`, but the usual style of using ``primary_key=True`` flags is still desirable, an empty :class:`.PrimaryKeyConstraint` may be specified, which will take on the - primary key column collection from the :class:`.Table` based on the + primary key column collection from the :class:`_schema.Table` based on the flags:: my_table = Table('mytable', metadata, @@ -3289,7 +3383,7 @@ class PrimaryKeyConstraint(ColumnCollectionConstraint): .. versionadded:: 0.9.2 an empty :class:`.PrimaryKeyConstraint` may now be specified for the purposes of establishing keyword arguments with the constraint, independently of the specification of "primary key" - columns within the :class:`.Table` itself; columns marked as + columns within the :class:`_schema.Table` itself; columns marked as ``primary_key=True`` will be gathered into the empty constraint's column collection. @@ -3342,7 +3436,7 @@ class PrimaryKeyConstraint(ColumnCollectionConstraint): This is basically like putting a whole new :class:`.PrimaryKeyConstraint` object on the parent - :class:`.Table` object without actually replacing the object. + :class:`_schema.Table` object without actually replacing the object. The ordering of the given list of columns is also maintained; these columns will be appended to the list of columns after any which @@ -3457,7 +3551,7 @@ class Index(DialectKWArgs, ColumnCollectionMixin, SchemaItem): Index("some_index", sometable.c.name) For a no-frills, single column index, adding - :class:`.Column` also supports ``index=True``:: + :class:`_schema.Column` also supports ``index=True``:: sometable = Table("sometable", metadata, Column("name", String(50), index=True) @@ -3469,13 +3563,15 @@ class Index(DialectKWArgs, ColumnCollectionMixin, SchemaItem): Functional indexes are supported as well, typically by using the :data:`.func` construct in conjunction with table-bound - :class:`.Column` objects:: + :class:`_schema.Column` objects:: Index("some_index", func.lower(sometable.c.name)) - An :class:`.Index` can also be manually associated with a :class:`.Table`, + An :class:`.Index` can also be manually associated with a + :class:`_schema.Table`, either through inline declaration or using - :meth:`.Table.append_constraint`. When this approach is used, the names + :meth:`_schema.Table.append_constraint`. When this approach is used, + the names of the indexed columns can be specified as strings:: Table("sometable", metadata, @@ -3485,7 +3581,7 @@ class Index(DialectKWArgs, ColumnCollectionMixin, SchemaItem): ) To support functional or expression-based indexes in this form, the - :func:`.text` construct may be used:: + :func:`_expression.text` construct may be used:: from sqlalchemy import text @@ -3495,9 +3591,10 @@ class Index(DialectKWArgs, ColumnCollectionMixin, SchemaItem): Index("some_index", text("lower(name)")) ) - .. versionadded:: 0.9.5 the :func:`.text` construct may be used to + .. versionadded:: 0.9.5 the :func:`_expression.text` + construct may be used to specify :class:`.Index` expressions, provided the :class:`.Index` - is explicitly associated with the :class:`.Table`. + is explicitly associated with the :class:`_schema.Table`. .. seealso:: @@ -3525,9 +3622,9 @@ class Index(DialectKWArgs, ColumnCollectionMixin, SchemaItem): :param \*expressions: Column expressions to include in the index. The expressions - are normally instances of :class:`.Column`, but may also + are normally instances of :class:`_schema.Column`, but may also be arbitrary SQL expressions which ultimately refer to a - :class:`.Column`. + :class:`_schema.Column`. :param unique=False: Keyword only argument; if True, create a unique index. @@ -3535,7 +3632,7 @@ class Index(DialectKWArgs, ColumnCollectionMixin, SchemaItem): :param quote=None: Keyword only argument; whether to apply quoting to the name of the index. Works in the same manner as that of - :paramref:`.Column.quote`. + :paramref:`_schema.Column.quote`. :param info=None: Optional data dictionary which will be populated into the :attr:`.SchemaItem.info` attribute of this object. @@ -3610,7 +3707,7 @@ class Index(DialectKWArgs, ColumnCollectionMixin, SchemaItem): .. seealso:: - :meth:`.MetaData.create_all`. + :meth:`_schema.MetaData.create_all`. """ if bind is None: @@ -3625,7 +3722,7 @@ class Index(DialectKWArgs, ColumnCollectionMixin, SchemaItem): .. seealso:: - :meth:`.MetaData.drop_all`. + :meth:`_schema.MetaData.drop_all`. """ if bind is None: @@ -3646,20 +3743,22 @@ DEFAULT_NAMING_CONVENTION = util.immutabledict({"ix": "ix_%(column_0_label)s"}) class MetaData(SchemaItem): - """A collection of :class:`.Table` objects and their associated schema + """A collection of :class:`_schema.Table` + objects and their associated schema constructs. - Holds a collection of :class:`.Table` objects as well as - an optional binding to an :class:`.Engine` or - :class:`.Connection`. If bound, the :class:`.Table` objects + Holds a collection of :class:`_schema.Table` objects as well as + an optional binding to an :class:`_engine.Engine` or + :class:`_engine.Connection`. If bound, the :class:`_schema.Table` objects in the collection and their columns may participate in implicit SQL execution. - The :class:`.Table` objects themselves are stored in the - :attr:`.MetaData.tables` dictionary. + The :class:`_schema.Table` objects themselves are stored in the + :attr:`_schema.MetaData.tables` dictionary. - :class:`.MetaData` is a thread-safe object for read operations. - Construction of new tables within a single :class:`.MetaData` object, + :class:`_schema.MetaData` is a thread-safe object for read operations. + Construction of new tables within a single :class:`_schema.MetaData` + object, either explicitly or via reflection, may not be completely thread-safe. .. seealso:: @@ -3690,37 +3789,46 @@ class MetaData(SchemaItem): Defaults to False. ``bind`` is required when this option is set. :param schema: - The default schema to use for the :class:`.Table`, + The default schema to use for the :class:`_schema.Table`, :class:`.Sequence`, and potentially other objects associated with - this :class:`.MetaData`. Defaults to ``None``. + this :class:`_schema.MetaData`. Defaults to ``None``. - When this value is set, any :class:`.Table` or :class:`.Sequence` + When this value is set, any :class:`_schema.Table` or + :class:`.Sequence` which specifies ``None`` for the schema parameter will instead - have this schema name defined. To build a :class:`.Table` + have this schema name defined. To build a :class:`_schema.Table` or :class:`.Sequence` that still has ``None`` for the schema even when this parameter is present, use the :attr:`.BLANK_SCHEMA` symbol. .. note:: - As referred above, the :paramref:`.MetaData.schema` parameter + As referred above, the :paramref:`_schema.MetaData.schema` + parameter only refers to the **default value** that will be applied to - the :paramref:`.Table.schema` parameter of an incoming - :class:`.Table` object. It does not refer to how the - :class:`.Table` is catalogued within the :class:`.MetaData`, - which remains consistent vs. a :class:`.MetaData` collection - that does not define this parameter. The :class:`.Table` - within the :class:`.MetaData` will still be keyed based on its + the :paramref:`_schema.Table.schema` parameter of an incoming + :class:`_schema.Table` object. It does not refer to how the + :class:`_schema.Table` is catalogued within the + :class:`_schema.MetaData`, + which remains consistent vs. a :class:`_schema.MetaData` + collection + that does not define this parameter. The + :class:`_schema.Table` + within the :class:`_schema.MetaData` + will still be keyed based on its schema-qualified name, e.g. ``my_metadata.tables["some_schema.my_table"]``. - The current behavior of the :class:`.ForeignKey` object is to + The current behavior of the :class:`_schema.ForeignKey` + object is to circumvent this restriction, where it can locate a table given the table name alone, where the schema will be assumed to be present from this value as specified on the owning - :class:`.MetaData` collection. However, this implies that a + :class:`_schema.MetaData` collection. However, + this implies that a table qualified with BLANK_SCHEMA cannot currently be referred - to by string name from :class:`.ForeignKey`. Other parts of + to by string name from :class:`_schema.ForeignKey`. + Other parts of SQLAlchemy such as Declarative may not have similar behaviors built in, however may do so in a future release, along with a consistent method of referring to a table in BLANK_SCHEMA. @@ -3728,12 +3836,12 @@ class MetaData(SchemaItem): .. seealso:: - :paramref:`.Table.schema` + :paramref:`_schema.Table.schema` :paramref:`.Sequence.schema` :param quote_schema: - Sets the ``quote_schema`` flag for those :class:`.Table`, + Sets the ``quote_schema`` flag for those :class:`_schema.Table`, :class:`.Sequence`, and other objects which make usage of the local ``schema`` name. @@ -3750,7 +3858,8 @@ class MetaData(SchemaItem): The keys of this dictionary may be: * a constraint or Index class, e.g. the :class:`.UniqueConstraint`, - :class:`.ForeignKeyConstraint` class, the :class:`.Index` class + :class:`_schema.ForeignKeyConstraint` class, the :class:`.Index` + class * a string mnemonic for one of the known constraint classes; ``"fk"``, ``"pk"``, ``"ix"``, ``"ck"``, ``"uq"`` for foreign key, @@ -3765,45 +3874,49 @@ class MetaData(SchemaItem): which describe how the name should be composed. The values associated with user-defined "token" keys should be callables of the form ``fn(constraint, table)``, which accepts the constraint/index - object and :class:`.Table` as arguments, returning a string + object and :class:`_schema.Table` as arguments, returning a string result. The built-in names are as follows, some of which may only be available for certain types of constraint: - * ``%(table_name)s`` - the name of the :class:`.Table` object + * ``%(table_name)s`` - the name of the :class:`_schema.Table` + object associated with the constraint. - * ``%(referred_table_name)s`` - the name of the :class:`.Table` + * ``%(referred_table_name)s`` - the name of the + :class:`_schema.Table` object associated with the referencing target of a - :class:`.ForeignKeyConstraint`. + :class:`_schema.ForeignKeyConstraint`. - * ``%(column_0_name)s`` - the name of the :class:`.Column` at + * ``%(column_0_name)s`` - the name of the :class:`_schema.Column` + at index position "0" within the constraint. - * ``%(column_0N_name)s`` - the name of all :class:`.Column` + * ``%(column_0N_name)s`` - the name of all :class:`_schema.Column` objects in order within the constraint, joined without a separator. - * ``%(column_0_N_name)s`` - the name of all :class:`.Column` + * ``%(column_0_N_name)s`` - the name of all + :class:`_schema.Column` objects in order within the constraint, joined with an underscore as a separator. * ``%(column_0_label)s``, ``%(column_0N_label)s``, ``%(column_0_N_label)s`` - the label of either the zeroth - :class:`.Column` or all :class:`.Columns`, separated with + :class:`_schema.Column` or all :class:`.Columns`, separated with or without an underscore * ``%(column_0_key)s``, ``%(column_0N_key)s``, ``%(column_0_N_key)s`` - the key of either the zeroth - :class:`.Column` or all :class:`.Columns`, separated with + :class:`_schema.Column` or all :class:`.Columns`, separated with or without an underscore * ``%(referred_column_0_name)s``, ``%(referred_column_0N_name)s`` ``%(referred_column_0_N_name)s``, ``%(referred_column_0_key)s``, ``%(referred_column_0N_key)s``, ... column tokens which render the names/keys/labels of columns that are referenced - by a :class:`.ForeignKeyConstraint`. + by a :class:`_schema.ForeignKeyConstraint`. * ``%(constraint_name)s`` - a special key that refers to the existing name given to the constraint. When this key is @@ -3843,16 +3956,20 @@ class MetaData(SchemaItem): self.bind = bind tables = None - """A dictionary of :class:`.Table` objects keyed to their name or "table key". - - The exact key is that determined by the :attr:`.Table.key` attribute; - for a table with no :attr:`.Table.schema` attribute, this is the same - as :attr:`.Table.name`. For a table with a schema, it is typically of the + """A dictionary of :class:`_schema.Table` + objects keyed to their name or "table key". + + The exact key is that determined by the :attr:`_schema.Table.key` + attribute; + for a table with no :attr:`_schema.Table.schema` attribute, + this is the same + as :attr:`_schema.Table.name`. For a table with a schema, + it is typically of the form ``schemaname.tablename``. .. seealso:: - :attr:`.MetaData.sorted_tables` + :attr:`_schema.MetaData.sorted_tables` """ @@ -3910,10 +4027,11 @@ class MetaData(SchemaItem): return self._bind is not None def bind(self): - """An :class:`.Engine` or :class:`.Connection` to which this - :class:`.MetaData` is bound. + """An :class:`_engine.Engine` or :class:`_engine.Connection` + to which this + :class:`_schema.MetaData` is bound. - Typically, a :class:`.Engine` is assigned to this attribute + Typically, a :class:`_engine.Engine` is assigned to this attribute so that "implicit execution" may be used, or alternatively as a means of providing engine binding information to an ORM :class:`.Session` object:: @@ -3953,10 +4071,11 @@ class MetaData(SchemaItem): @property def sorted_tables(self): - """Returns a list of :class:`.Table` objects sorted in order of + """Returns a list of :class:`_schema.Table` objects sorted in order of foreign key dependency. - The sorting will place :class:`.Table` objects that have dependencies + The sorting will place :class:`_schema.Table` + objects that have dependencies first, before the dependencies themselves, representing the order in which they can be created. To get the order in which the tables would be dropped, use the ``reversed()`` Python built-in. @@ -3967,22 +4086,23 @@ class MetaData(SchemaItem): automatic resolution of dependency cycles between tables, which are usually caused by mutually dependent foreign key constraints. To resolve these cycles, either the - :paramref:`.ForeignKeyConstraint.use_alter` parameter may be + :paramref:`_schema.ForeignKeyConstraint.use_alter` + parameter may be applied to those constraints, or use the - :func:`.schema.sort_tables_and_constraints` function which will + :func:`_schema.sort_tables_and_constraints` function which will break out foreign key constraints involved in cycles separately. .. seealso:: - :func:`.schema.sort_tables` + :func:`_schema.sort_tables` - :func:`.schema.sort_tables_and_constraints` + :func:`_schema.sort_tables_and_constraints` - :attr:`.MetaData.tables` + :attr:`_schema.MetaData.tables` - :meth:`.Inspector.get_table_names` + :meth:`_reflection.Inspector.get_table_names` - :meth:`.Inspector.get_sorted_table_and_fkc_names` + :meth:`_reflection.Inspector.get_sorted_table_and_fkc_names` """ @@ -4015,7 +4135,7 @@ class MetaData(SchemaItem): :param schema: Optional, query and reflect tables from an alternate schema. - If None, the schema associated with this :class:`.MetaData` + If None, the schema associated with this :class:`_schema.MetaData` is used, if any. :param views: @@ -4035,35 +4155,41 @@ class MetaData(SchemaItem): with a table name and this ``MetaData`` instance as positional arguments and should return a true value for any table to reflect. - :param extend_existing: Passed along to each :class:`.Table` as - :paramref:`.Table.extend_existing`. + :param extend_existing: Passed along to each :class:`_schema.Table` as + :paramref:`_schema.Table.extend_existing`. .. versionadded:: 0.9.1 - :param autoload_replace: Passed along to each :class:`.Table` as - :paramref:`.Table.autoload_replace`. + :param autoload_replace: Passed along to each :class:`_schema.Table` + as + :paramref:`_schema.Table.autoload_replace`. .. versionadded:: 0.9.1 - :param resolve_fks: if True, reflect :class:`.Table` objects linked - to :class:`.ForeignKey` objects located in each :class:`.Table`. - For :meth:`.MetaData.reflect`, this has the effect of reflecting + :param resolve_fks: if True, reflect :class:`_schema.Table` + objects linked + to :class:`_schema.ForeignKey` objects located in each + :class:`_schema.Table`. + For :meth:`_schema.MetaData.reflect`, + this has the effect of reflecting related tables that might otherwise not be in the list of tables being reflected, for example if the referenced table is in a different schema or is omitted via the :paramref:`.MetaData.reflect.only` parameter. When False, - :class:`.ForeignKey` objects are not followed to the :class:`.Table` + :class:`_schema.ForeignKey` objects are not followed to the + :class:`_schema.Table` in which they link, however if the related table is also part of the list of tables that would be reflected in any case, the - :class:`.ForeignKey` object will still resolve to its related - :class:`.Table` after the :meth:`.MetaData.reflect` operation is + :class:`_schema.ForeignKey` object will still resolve to its related + :class:`_schema.Table` after the :meth:`_schema.MetaData.reflect` + operation is complete. Defaults to True. .. versionadded:: 1.3.0 .. seealso:: - :paramref:`.Table.resolve_fks` + :paramref:`_schema.Table.resolve_fks` :param \**dialect_kwargs: Additional keyword arguments not mentioned above are dialect specific, and passed in the form @@ -4073,7 +4199,7 @@ class MetaData(SchemaItem): .. versionadded:: 0.9.2 - Added :paramref:`.MetaData.reflect.**dialect_kwargs` to support - dialect-level reflection options for all :class:`.Table` + dialect-level reflection options for all :class:`_schema.Table` objects reflected. """ @@ -4273,7 +4399,7 @@ class Computed(FetchedValue, SchemaItem): """Defines a generated column, i.e. "GENERATED ALWAYS AS" syntax. The :class:`.Computed` construct is an inline construct added to the - argument list of a :class:`.Column` object:: + argument list of a :class:`_schema.Column` object:: from sqlalchemy import Computed @@ -4299,13 +4425,14 @@ class Computed(FetchedValue, SchemaItem): ) def __init__(self, sqltext, persisted=None): """Construct a GENERATED ALWAYS AS DDL construct to accompany a - :class:`.Column`. + :class:`_schema.Column`. :param sqltext: A string containing the column generation expression, which will be - used verbatim, or a SQL expression construct, such as a :func:`.text` + used verbatim, or a SQL expression construct, such as a + :func:`_expression.text` object. If given as a string, the object is converted to a - :func:`.text` object. + :func:`_expression.text` object. :param persisted: Optional, controls how this column should be persisted by the diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py index 08a237636e..bfe5d80ad1 100644 --- a/lib/sqlalchemy/sql/selectable.py +++ b/lib/sqlalchemy/sql/selectable.py @@ -5,7 +5,8 @@ # This module is part of SQLAlchemy and is released under # the MIT License: http://www.opensource.org/licenses/mit-license.php -"""The :class:`.FromClause` class of SQL expression elements, representing +"""The :class:`_expression.FromClause` class of SQL expression elements, +representing SQL tables and derived rowsets. """ @@ -70,12 +71,12 @@ class _OffsetLimitParam(BindParameter): ) def subquery(alias, *args, **kwargs): r"""Return an :class:`.Subquery` object derived - from a :class:`.Select`. + from a :class:`_expression.Select`. :param name: the alias name for the subquery :param \*args, \**kwargs: all other arguments are passed through to the - :func:`~.sql.expression.select` function. + :func:`_expression.select` function. """ return Select(*args, **kwargs).subquery(alias) @@ -107,26 +108,29 @@ class ReturnsRows(roles.ReturnsRowsRole, ClauseElement): def _exported_columns_iterator(self): """An iterator of column objects that represents the "exported" - columns of this :class:`.ReturnsRows`. + columns of this :class:`_expression.ReturnsRows`. This is the same set of columns as are returned by - :meth:`.ReturnsRows.exported_columns` except they are returned + :meth:`_expression.ReturnsRows.exported_columns` + except they are returned as a simple iterator or sequence, rather than as a - :class:`.ColumnCollection` namespace. + :class:`_expression.ColumnCollection` namespace. Subclasses should re-implement this method to bypass the interim - creation of the :class:`.ColumnCollection` if appropriate. + creation of the :class:`_expression.ColumnCollection` if appropriate. """ return iter(self.exported_columns) @property def exported_columns(self): - """A :class:`.ColumnCollection` that represents the "exported" - columns of this :class:`.ReturnsRows`. + """A :class:`_expression.ColumnCollection` + that represents the "exported" + columns of this :class:`_expression.ReturnsRows`. The "exported" columns represent the collection of - :class:`.ColumnElement` expressions that are rendered by this SQL + :class:`_expression.ColumnElement` + expressions that are rendered by this SQL construct. There are primary varieties which are the "FROM clause columns" of a FROM clause, such as a table, join, or subquery, the "SELECTed columns", which are the columns in @@ -137,9 +141,9 @@ class ReturnsRows(roles.ReturnsRowsRole, ClauseElement): .. seealso: - :attr:`.FromClause.exported_columns` + :attr:`_expression.FromClause.exported_columns` - :attr:`.SelectBase.exported_columns` + :attr:`_expression.SelectBase.exported_columns` """ raise NotImplementedError() @@ -162,10 +166,10 @@ class Selectable(ReturnsRows): raise NotImplementedError() def lateral(self, name=None): - """Return a LATERAL alias of this :class:`.Selectable`. + """Return a LATERAL alias of this :class:`expression.Selectable`. - The return value is the :class:`.Lateral` construct also - provided by the top-level :func:`~.expression.lateral` function. + The return value is the :class:`_expression.Lateral` construct also + provided by the top-level :func:`_expression.lateral` function. .. versionadded:: 1.1 @@ -185,34 +189,40 @@ class Selectable(ReturnsRows): @util.preload_module("sqlalchemy.sql.util") def replace_selectable(self, old, alias): """replace all occurrences of FromClause 'old' with the given Alias - object, returning a copy of this :class:`.FromClause`. + object, returning a copy of this :class:`_expression.FromClause`. """ return util.preloaded.sql_util.ClauseAdapter(alias).traverse(self) def corresponding_column(self, column, require_embedded=False): - """Given a :class:`.ColumnElement`, return the exported - :class:`.ColumnElement` object from the - :attr:`.Selectable.exported_columns` - collection of this :class:`.Selectable` which corresponds to that - original :class:`.ColumnElement` via a common ancestor + """Given a :class:`_expression.ColumnElement`, return the exported + :class:`_expression.ColumnElement` object from the + :attr:`expression.Selectable.exported_columns` + collection of this :class:`expression.Selectable` + which corresponds to that + original :class:`_expression.ColumnElement` via a common ancestor column. - :param column: the target :class:`.ColumnElement` to be matched + :param column: the target :class:`_expression.ColumnElement` + to be matched :param require_embedded: only return corresponding columns for - the given :class:`.ColumnElement`, if the given - :class:`.ColumnElement` is actually present within a sub-element - of this :class:`.Selectable`. Normally the column will match if + the given :class:`_expression.ColumnElement`, if the given + :class:`_expression.ColumnElement` + is actually present within a sub-element + of this :class:`expression.Selectable`. + Normally the column will match if it merely shares a common ancestor with one of the exported - columns of this :class:`.Selectable`. + columns of this :class:`expression.Selectable`. .. seealso:: - :attr:`.Selectable.exported_columns` - the - :class:`.ColumnCollection` that is used for the operation + :attr:`expression.Selectable.exported_columns` - the + :class:`_expression.ColumnCollection` + that is used for the operation - :meth:`.ColumnCollection.corresponding_column` - implementation + :meth:`_expression.ColumnCollection.corresponding_column` + - implementation method. """ @@ -232,7 +242,7 @@ class HasPrefixes(object): @_generative @_document_text_coercion( "expr", - ":meth:`.HasPrefixes.prefix_with`", + ":meth:`_expression.HasPrefixes.prefix_with`", ":paramref:`.HasPrefixes.prefix_with.*expr`", ) def prefix_with(self, *expr, **kw): @@ -251,9 +261,10 @@ class HasPrefixes(object): "/*+ BKA(t1) */", dialect="mysql") Multiple prefixes can be specified by multiple calls - to :meth:`.prefix_with`. + to :meth:`_expression.HasPrefixes.prefix_with`. - :param \*expr: textual or :class:`.ClauseElement` construct which + :param \*expr: textual or :class:`_expression.ClauseElement` + construct which will be rendered following the INSERT, UPDATE, or DELETE keyword. :param \**kw: A single keyword 'dialect' is accepted. This is an @@ -287,7 +298,7 @@ class HasSuffixes(object): @_generative @_document_text_coercion( "expr", - ":meth:`.HasSuffixes.suffix_with`", + ":meth:`_expression.HasSuffixes.suffix_with`", ":paramref:`.HasSuffixes.suffix_with.*expr`", ) def suffix_with(self, *expr, **kw): @@ -302,9 +313,10 @@ class HasSuffixes(object): "cycle empno set y_cycle to 1 default 0", dialect="oracle") Multiple suffixes can be specified by multiple calls - to :meth:`.suffix_with`. + to :meth:`_expression.HasSuffixes.suffix_with`. - :param \*expr: textual or :class:`.ClauseElement` construct which + :param \*expr: textual or :class:`_expression.ClauseElement` + construct which will be rendered following the target clause. :param \**kw: A single keyword 'dialect' is accepted. This is an optional string dialect name which will @@ -331,17 +343,19 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): """Represent an element that can be used within the ``FROM`` clause of a ``SELECT`` statement. - The most common forms of :class:`.FromClause` are the - :class:`.Table` and the :func:`~.sql.expression.select` constructs. Key - features common to all :class:`.FromClause` objects include: + The most common forms of :class:`_expression.FromClause` are the + :class:`_schema.Table` and the :func:`_expression.select` constructs. Key + features common to all :class:`_expression.FromClause` objects include: * a :attr:`.c` collection, which provides per-name access to a collection - of :class:`.ColumnElement` objects. + of :class:`_expression.ColumnElement` objects. * a :attr:`.primary_key` attribute, which is a collection of all those - :class:`.ColumnElement` objects that indicate the ``primary_key`` flag. + :class:`_expression.ColumnElement` + objects that indicate the ``primary_key`` flag. * Methods to generate various derivations of a "from" clause, including - :meth:`.FromClause.alias`, :meth:`.FromClause.join`, - :meth:`.FromClause.select`. + :meth:`_expression.FromClause.alias`, + :meth:`_expression.FromClause.join`, + :meth:`_expression.FromClause.select`. """ @@ -351,11 +365,11 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): _hide_froms = [] schema = None - """Define the 'schema' attribute for this :class:`.FromClause`. + """Define the 'schema' attribute for this :class:`_expression.FromClause`. This is typically ``None`` for most objects except that of - :class:`.Table`, where it is taken as the value of the - :paramref:`.Table.schema` argument. + :class:`_schema.Table`, where it is taken as the value of the + :paramref:`_schema.Table.schema` argument. """ @@ -366,11 +380,11 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): _use_schema_map = False def select(self, whereclause=None, **params): - """return a SELECT of this :class:`.FromClause`. + """return a SELECT of this :class:`_expression.FromClause`. .. seealso:: - :func:`~.sql.expression.select` - general purpose + :func:`_expression.select` - general purpose method which allows for arbitrary column lists. """ @@ -378,7 +392,8 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): return Select([self], whereclause, **params) def join(self, right, onclause=None, isouter=False, full=False): - """Return a :class:`.Join` from this :class:`.FromClause` + """Return a :class:`_expression.Join` from this + :class:`_expression.FromClause` to another :class:`FromClause`. E.g.:: @@ -395,12 +410,14 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): JOIN address ON user.id = address.user_id :param right: the right side of the join; this is any - :class:`.FromClause` object such as a :class:`.Table` object, and + :class:`_expression.FromClause` object such as a + :class:`_schema.Table` object, and may also be a selectable-compatible object such as an ORM-mapped class. :param onclause: a SQL expression representing the ON clause of the - join. If left at ``None``, :meth:`.FromClause.join` will attempt to + join. If left at ``None``, :meth:`_expression.FromClause.join` + will attempt to join the two tables based on a foreign key relationship. :param isouter: if True, render a LEFT OUTER JOIN, instead of JOIN. @@ -412,16 +429,17 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): .. seealso:: - :func:`.join` - standalone function + :func:`_expression.join` - standalone function - :class:`.Join` - the type of object produced + :class:`_expression.Join` - the type of object produced """ return Join(self, right, onclause, isouter, full) def outerjoin(self, right, onclause=None, full=False): - """Return a :class:`.Join` from this :class:`.FromClause` + """Return a :class:`_expression.Join` from this + :class:`_expression.FromClause` to another :class:`FromClause`, with the "isouter" flag set to True. @@ -440,12 +458,14 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): isouter=True) :param right: the right side of the join; this is any - :class:`.FromClause` object such as a :class:`.Table` object, and + :class:`_expression.FromClause` object such as a + :class:`_schema.Table` object, and may also be a selectable-compatible object such as an ORM-mapped class. :param onclause: a SQL expression representing the ON clause of the - join. If left at ``None``, :meth:`.FromClause.join` will attempt to + join. If left at ``None``, :meth:`_expression.FromClause.join` + will attempt to join the two tables based on a foreign key relationship. :param full: if True, render a FULL OUTER JOIN, instead of @@ -455,45 +475,47 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): .. seealso:: - :meth:`.FromClause.join` + :meth:`_expression.FromClause.join` - :class:`.Join` + :class:`_expression.Join` """ return Join(self, right, onclause, True, full) def alias(self, name=None, flat=False): - """return an alias of this :class:`.FromClause`. + """return an alias of this :class:`_expression.FromClause`. E.g.:: a2 = some_table.alias('a2') - The above code creates an :class:`.Alias` object which can be used + The above code creates an :class:`_expression.Alias` + object which can be used as a FROM clause in any SELECT statement. .. seealso:: :ref:`core_tutorial_aliases` - :func:`~.expression.alias` + :func:`_expression.alias` """ return Alias._construct(self, name) def tablesample(self, sampling, name=None, seed=None): - """Return a TABLESAMPLE alias of this :class:`.FromClause`. + """Return a TABLESAMPLE alias of this :class:`_expression.FromClause`. - The return value is the :class:`.TableSample` construct also - provided by the top-level :func:`~.expression.tablesample` function. + The return value is the :class:`_expression.TableSample` + construct also + provided by the top-level :func:`_expression.tablesample` function. .. versionadded:: 1.1 .. seealso:: - :func:`~.expression.tablesample` - usage guidelines and parameters + :func:`_expression.tablesample` - usage guidelines and parameters """ return TableSample._construct(self, sampling, name, seed) @@ -536,19 +558,21 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): @property def exported_columns(self): - """A :class:`.ColumnCollection` that represents the "exported" - columns of this :class:`.Selectable`. + """A :class:`_expression.ColumnCollection` + that represents the "exported" + columns of this :class:`expression.Selectable`. - The "exported" columns for a :class:`.FromClause` object are synonymous - with the :attr:`.FromClause.columns` collection. + The "exported" columns for a :class:`_expression.FromClause` + object are synonymous + with the :attr:`_expression.FromClause.columns` collection. .. versionadded:: 1.4 .. seealso: - :attr:`.Selectable.exported_columns` + :attr:`expression.Selectable.exported_columns` - :attr:`.SelectBase.exported_columns` + :attr:`_expression.SelectBase.exported_columns` """ @@ -556,8 +580,9 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): @util.memoized_property def columns(self): - """A named-based collection of :class:`.ColumnElement` objects - maintained by this :class:`.FromClause`. + """A named-based collection of :class:`_expression.ColumnElement` + objects + maintained by this :class:`_expression.FromClause`. The :attr:`.columns`, or :attr:`.c` collection, is the gateway to the construction of SQL expressions using table-bound or @@ -663,18 +688,22 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): class Join(FromClause): - """represent a ``JOIN`` construct between two :class:`.FromClause` + """represent a ``JOIN`` construct between two + :class:`_expression.FromClause` elements. - The public constructor function for :class:`.Join` is the module-level - :func:`.join()` function, as well as the :meth:`.FromClause.join` method - of any :class:`.FromClause` (e.g. such as :class:`.Table`). + The public constructor function for :class:`_expression.Join` + is the module-level + :func:`_expression.join()` function, as well as the + :meth:`_expression.FromClause.join` method + of any :class:`_expression.FromClause` (e.g. such as + :class:`_schema.Table`). .. seealso:: - :func:`.join` + :func:`_expression.join` - :meth:`.FromClause.join` + :meth:`_expression.FromClause.join` """ @@ -691,11 +720,11 @@ class Join(FromClause): _is_join = True def __init__(self, left, right, onclause=None, isouter=False, full=False): - """Construct a new :class:`.Join`. + """Construct a new :class:`_expression.Join`. - The usual entrypoint here is the :func:`~.expression.join` - function or the :meth:`.FromClause.join` method of any - :class:`.FromClause` object. + The usual entrypoint here is the :func:`_expression.join` + function or the :meth:`_expression.FromClause.join` method of any + :class:`_expression.FromClause` object. """ self.left = coercions.expect(roles.FromClauseRole, left) @@ -713,11 +742,11 @@ class Join(FromClause): def _create_outerjoin(cls, left, right, onclause=None, full=False): """Return an ``OUTER JOIN`` clause element. - The returned object is an instance of :class:`.Join`. + The returned object is an instance of :class:`_expression.Join`. Similar functionality is also available via the - :meth:`~.FromClause.outerjoin()` method on any - :class:`.FromClause`. + :meth:`_expression.FromClause.outerjoin()` method on any + :class:`_expression.FromClause`. :param left: The left side of the join. @@ -727,9 +756,10 @@ class Join(FromClause): derived from foreign key relationships established between left and right otherwise. - To chain joins together, use the :meth:`.FromClause.join` or - :meth:`.FromClause.outerjoin` methods on the resulting - :class:`.Join` object. + To chain joins together, use the :meth:`_expression.FromClause.join` + or + :meth:`_expression.FromClause.outerjoin` methods on the resulting + :class:`_expression.Join` object. """ return cls(left, right, onclause, isouter=True, full=full) @@ -738,7 +768,8 @@ class Join(FromClause): def _create_join( cls, left, right, onclause=None, isouter=False, full=False ): - """Produce a :class:`.Join` object, given two :class:`.FromClause` + """Produce a :class:`_expression.Join` object, given two + :class:`_expression.FromClause` expressions. E.g.:: @@ -753,18 +784,21 @@ class Join(FromClause): JOIN address ON user.id = address.user_id Similar functionality is available given any - :class:`.FromClause` object (e.g. such as a :class:`.Table`) using - the :meth:`.FromClause.join` method. + :class:`_expression.FromClause` object (e.g. such as a + :class:`_schema.Table`) using + the :meth:`_expression.FromClause.join` method. :param left: The left side of the join. :param right: the right side of the join; this is any - :class:`.FromClause` object such as a :class:`.Table` object, and + :class:`_expression.FromClause` object such as a + :class:`_schema.Table` object, and may also be a selectable-compatible object such as an ORM-mapped class. :param onclause: a SQL expression representing the ON clause of the - join. If left at ``None``, :meth:`.FromClause.join` will attempt to + join. If left at ``None``, :meth:`_expression.FromClause.join` + will attempt to join the two tables based on a foreign key relationship. :param isouter: if True, render a LEFT OUTER JOIN, instead of JOIN. @@ -775,9 +809,10 @@ class Join(FromClause): .. seealso:: - :meth:`.FromClause.join` - method form, based on a given left side + :meth:`_expression.FromClause.join` - method form, + based on a given left side - :class:`.Join` - the type of object produced + :class:`_expression.Join` - the type of object produced """ @@ -989,9 +1024,11 @@ class Join(FromClause): ) def select(self, whereclause=None, **kwargs): - r"""Create a :class:`.Select` from this :class:`.Join`. + r"""Create a :class:`_expression.Select` from this + :class:`_expression.Join`. - The equivalent long-hand form, given a :class:`.Join` object + The equivalent long-hand form, given a :class:`_expression.Join` + object ``j``, is:: from sqlalchemy import select @@ -1020,11 +1057,11 @@ class Join(FromClause): @util.preload_module("sqlalchemy.sql.util") def alias(self, name=None, flat=False): - r"""return an alias of this :class:`.Join`. + r"""return an alias of this :class:`_expression.Join`. The default behavior here is to first produce a SELECT - construct from this :class:`.Join`, then to produce an - :class:`.Alias` from that. So given a join of the form:: + construct from this :class:`_expression.Join`, then to produce an + :class:`_expression.Alias` from that. So given a join of the form:: j = table_a.join(table_b, table_a.c.id == table_b.c.a_id) @@ -1040,7 +1077,8 @@ class Join(FromClause): FROM table_a JOIN table_b ON table_a.id = table_b.a_id) AS anon_1 - The equivalent long-hand form, given a :class:`.Join` object + The equivalent long-hand form, given a :class:`_expression.Join` + object ``j``, is:: from sqlalchemy import select, alias @@ -1052,20 +1090,22 @@ class Join(FromClause): name=name ) - The selectable produced by :meth:`.Join.alias` features the same + The selectable produced by :meth:`_expression.Join.alias` + features the same columns as that of the two individual selectables presented under a single name - the individual columns are "auto-labeled", meaning - the ``.c.`` collection of the resulting :class:`.Alias` represents + the ``.c.`` collection of the resulting :class:`_expression.Alias` + represents the names of the individual columns using a ``_`` scheme:: j.c.table_a_id j.c.table_b_a_id - :meth:`.Join.alias` also features an alternate + :meth:`_expression.Join.alias` also features an alternate option for aliasing joins which produces no enclosing SELECT and does not normally apply labels to the column names. The - ``flat=True`` option will call :meth:`.FromClause.alias` + ``flat=True`` option will call :meth:`_expression.FromClause.alias` against the left and right sides individually. Using this option, no new ``SELECT`` is produced; we instead, from a construct as below:: @@ -1094,15 +1134,16 @@ class Join(FromClause): ON table_b_1.id = table_c_1.b_id ) ON table_a_1.id = table_b_1.a_id - The standalone :func:`~.expression.alias` function as well as the - base :meth:`.FromClause.alias` method also support the ``flat=True`` + The standalone :func:`_expression.alias` function as well as the + base :meth:`_expression.FromClause.alias` + method also support the ``flat=True`` argument as a no-op, so that the argument can be passed to the ``alias()`` method of any selectable. :param name: name given to the alias. :param flat: if True, produce an alias of the left and right - sides of this :class:`.Join` and return the join of those + sides of this :class:`_expression.Join` and return the join of those two selectables. This produces join expression that does not include an enclosing SELECT. @@ -1110,7 +1151,7 @@ class Join(FromClause): :ref:`core_tutorial_aliases` - :func:`~.expression.alias` + :func:`_expression.alias` """ sqlutil = util.preloaded.sql_util @@ -1260,13 +1301,14 @@ class Alias(AliasedReturnsRows): sub-select within a SQL statement using the ``AS`` keyword (or without the keyword on certain databases such as Oracle). - This object is constructed from the :func:`~.expression.alias` module - level function as well as the :meth:`.FromClause.alias` method available - on all :class:`.FromClause` subclasses. + This object is constructed from the :func:`_expression.alias` module + level function as well as the :meth:`_expression.FromClause.alias` + method available + on all :class:`_expression.FromClause` subclasses. .. seealso:: - :meth:`.FromClause.alias` + :meth:`_expression.FromClause.alias` """ @@ -1274,24 +1316,28 @@ class Alias(AliasedReturnsRows): @classmethod def _factory(cls, selectable, name=None, flat=False): - """Return an :class:`.Alias` object. + """Return an :class:`_expression.Alias` object. - An :class:`.Alias` represents any :class:`.FromClause` + An :class:`_expression.Alias` represents any + :class:`_expression.FromClause` with an alternate name assigned within SQL, typically using the ``AS`` clause when generated, e.g. ``SELECT * FROM table AS aliasname``. - Similar functionality is available via the :meth:`~.FromClause.alias` - method available on all :class:`.FromClause` subclasses. In terms of - a SELECT object as generated from the :func:`~.sql.expression.select` - function, the :meth:`.SelectBase.alias` method returns an - :class:`.Alias` or similar object which represents a named, + Similar functionality is available via the + :meth:`_expression.FromClause.alias` + method available on all :class:`_expression.FromClause` subclasses. + In terms of + a SELECT object as generated from the :func:`_expression.select` + function, the :meth:`_expression.SelectBase.alias` method returns an + :class:`_expression.Alias` or similar object which represents a named, parenthesized subquery. - When an :class:`.Alias` is created from a :class:`.Table` object, + When an :class:`_expression.Alias` is created from a + :class:`_schema.Table` object, this has the effect of the table being rendered as ``tablename AS aliasname`` in a SELECT statement. - For :func:`~.sql.expression.select` objects, the effect is that of + For :func:`_expression.select` objects, the effect is that of creating a named subquery, i.e. ``(select ...) AS aliasname``. The ``name`` parameter is optional, and provides the name @@ -1302,7 +1348,7 @@ class Alias(AliasedReturnsRows): same name for each successive compilation of the same statement object. - :param selectable: any :class:`.FromClause` subclass, + :param selectable: any :class:`_expression.FromClause` subclass, such as a table, select statement, etc. :param name: string name to be assigned as the alias. @@ -1310,7 +1356,8 @@ class Alias(AliasedReturnsRows): at compile time. :param flat: Will be passed through to if the given selectable - is an instance of :class:`.Join` - see :meth:`.Join.alias` + is an instance of :class:`_expression.Join` - see + :meth:`_expression.Join.alias` for details. """ @@ -1322,9 +1369,10 @@ class Alias(AliasedReturnsRows): class Lateral(AliasedReturnsRows): """Represent a LATERAL subquery. - This object is constructed from the :func:`~.expression.lateral` module - level function as well as the :meth:`.FromClause.lateral` method available - on all :class:`.FromClause` subclasses. + This object is constructed from the :func:`_expression.lateral` module + level function as well as the :meth:`_expression.FromClause.lateral` + method available + on all :class:`_expression.FromClause` subclasses. While LATERAL is part of the SQL standard, currently only more recent PostgreSQL versions provide support for this keyword. @@ -1342,9 +1390,10 @@ class Lateral(AliasedReturnsRows): @classmethod def _factory(cls, selectable, name=None): - """Return a :class:`.Lateral` object. + """Return a :class:`_expression.Lateral` object. - :class:`.Lateral` is an :class:`.Alias` subclass that represents + :class:`_expression.Lateral` is an :class:`_expression.Alias` + subclass that represents a subquery with the LATERAL keyword applied to it. The special behavior of a LATERAL subquery is that it appears in the @@ -1368,15 +1417,16 @@ class Lateral(AliasedReturnsRows): class TableSample(AliasedReturnsRows): """Represent a TABLESAMPLE clause. - This object is constructed from the :func:`~.expression.tablesample` module - level function as well as the :meth:`.FromClause.tablesample` method - available on all :class:`.FromClause` subclasses. + This object is constructed from the :func:`_expression.tablesample` module + level function as well as the :meth:`_expression.FromClause.tablesample` + method + available on all :class:`_expression.FromClause` subclasses. .. versionadded:: 1.1 .. seealso:: - :func:`~.expression.tablesample` + :func:`_expression.tablesample` """ @@ -1389,13 +1439,15 @@ class TableSample(AliasedReturnsRows): @classmethod def _factory(cls, selectable, sampling, name=None, seed=None): - """Return a :class:`.TableSample` object. + """Return a :class:`_expression.TableSample` object. - :class:`.TableSample` is an :class:`.Alias` subclass that represents + :class:`_expression.TableSample` is an :class:`_expression.Alias` + subclass that represents a table with the TABLESAMPLE clause applied to it. - :func:`~.expression.tablesample` - is also available from the :class:`.FromClause` class via the - :meth:`.FromClause.tablesample` method. + :func:`_expression.tablesample` + is also available from the :class:`_expression.FromClause` + class via the + :meth:`_expression.FromClause.tablesample` method. The TABLESAMPLE clause allows selecting a randomly selected approximate percentage of rows from a table. It supports multiple sampling methods, @@ -1421,7 +1473,7 @@ class TableSample(AliasedReturnsRows): .. versionadded:: 1.1 :param sampling: a ``float`` percentage between 0 and 100 or - :class:`.functions.Function`. + :class:`_functions.Function`. :param name: optional alias name @@ -1450,8 +1502,8 @@ class TableSample(AliasedReturnsRows): class CTE(Generative, HasPrefixes, HasSuffixes, AliasedReturnsRows): """Represent a Common Table Expression. - The :class:`.CTE` object is obtained using the - :meth:`.SelectBase.cte` method from any selectable. + The :class:`_expression.CTE` object is obtained using the + :meth:`_expression.SelectBase.cte` method from any selectable. See that method for complete examples. """ @@ -1471,9 +1523,10 @@ class CTE(Generative, HasPrefixes, HasSuffixes, AliasedReturnsRows): @classmethod def _factory(cls, selectable, name=None, recursive=False): - r"""Return a new :class:`.CTE`, or Common Table Expression instance. + r"""Return a new :class:`_expression.CTE`, + or Common Table Expression instance. - Please see :meth:`.HasCte.cte` for detail on CTE usage. + Please see :meth:`_expression.HasCTE.cte` for detail on CTE usage. """ return coercions.expect(roles.HasCTERole, selectable).cte( @@ -1500,16 +1553,17 @@ class CTE(Generative, HasPrefixes, HasSuffixes, AliasedReturnsRows): super(CTE, self)._init(selectable, name=name) def alias(self, name=None, flat=False): - """Return an :class:`.Alias` of this :class:`.CTE`. + """Return an :class:`_expression.Alias` of this + :class:`_expression.CTE`. This method is a CTE-specific specialization of the - :class:`.FromClause.alias` method. + :class:`_expression.FromClause.alias` method. .. seealso:: :ref:`core_tutorial_aliases` - :func:`~.expression.alias` + :func:`_expression.alias` """ return CTE._construct( @@ -1550,7 +1604,8 @@ class HasCTE(roles.HasCTERole): """ def cte(self, name=None, recursive=False): - r"""Return a new :class:`.CTE`, or Common Table Expression instance. + r"""Return a new :class:`_expression.CTE`, + or Common Table Expression instance. Common table expressions are a SQL standard whereby SELECT statements can draw upon secondary statements specified along @@ -1567,13 +1622,14 @@ class HasCTE(roles.HasCTERole): .. versionchanged:: 1.1 Added support for UPDATE/INSERT/DELETE as CTE, CTEs added to UPDATE/INSERT/DELETE. - SQLAlchemy detects :class:`.CTE` objects, which are treated - similarly to :class:`.Alias` objects, as special elements + SQLAlchemy detects :class:`_expression.CTE` objects, which are treated + similarly to :class:`_expression.Alias` objects, as special elements to be delivered to the FROM clause of the statement as well as to a WITH clause at the top of the statement. For special prefixes such as PostgreSQL "MATERIALIZED" and - "NOT MATERIALIZED", the :meth:`.CTE.prefix_with` method may be + "NOT MATERIALIZED", the :meth:`_expression.CTE.prefix_with` + method may be used to establish these. .. versionchanged:: 1.3.13 Added support for prefixes. @@ -1711,7 +1767,7 @@ class HasCTE(roles.HasCTERole): .. seealso:: :meth:`.orm.query.Query.cte` - ORM version of - :meth:`.HasCTE.cte`. + :meth:`_expression.HasCTE.cte`. """ return CTE._construct(self, name=name, recursive=recursive) @@ -1721,18 +1777,24 @@ class Subquery(AliasedReturnsRows): """Represent a subquery of a SELECT. A :class:`.Subquery` is created by invoking the - :meth:`.SelectBase.subquery` method, or for convenience the - :class:`.SelectBase.alias` method, on any :class:`.SelectBase` subclass - which includes :class:`.Select`, :class:`.CompoundSelect`, and - :class:`.TextualSelect`. As rendered in a FROM clause, it represents the + :meth:`_expression.SelectBase.subquery` method, or for convenience the + :class:`_expression.SelectBase.alias` method, on any + :class:`_expression.SelectBase` subclass + which includes :class:`_expression.Select`, + :class:`_expression.CompoundSelect`, and + :class:`_expression.TextualSelect`. As rendered in a FROM clause, + it represents the body of the SELECT statement inside of parenthesis, followed by the usual "AS " that defines all "alias" objects. - The :class:`.Subquery` object is very similar to the :class:`.Alias` + The :class:`.Subquery` object is very similar to the + :class:`_expression.Alias` object and can be used in an equivalent way. The difference between - :class:`.Alias` and :class:`.Subquery` is that :class:`.Alias` always - contains a :class:`.FromClause` object whereas :class:`.Subquery` - always contains a :class:`.SelectBase` object. + :class:`_expression.Alias` and :class:`.Subquery` is that + :class:`_expression.Alias` always + contains a :class:`_expression.FromClause` object whereas + :class:`.Subquery` + always contains a :class:`_expression.SelectBase` object. .. versionadded:: 1.4 The :class:`.Subquery` class was added which now serves the purpose of providing an aliased version of a SELECT @@ -1758,10 +1820,10 @@ class Subquery(AliasedReturnsRows): "The :meth:`.Subquery.as_scalar` method, which was previously " "``Alias.as_scalar()`` prior to version 1.4, is deprecated and " "will be removed in a future release; Please use the " - ":meth:`.Select.scalar_subquery` method of the " - ":func:`~.sql.expression.select` " + ":meth:`_expression.Select.scalar_subquery` method of the " + ":func:`_expression.select` " "construct before constructing a subquery object, or with the ORM " - "use the :meth:`.Query.scalar_subquery` method.", + "use the :meth:`_query.Query.scalar_subquery` method.", ) def as_scalar(self): return self.element._set_label_style( @@ -1818,7 +1880,7 @@ class TableClause(Immutable, FromClause): This is a lightweight table object that has only a name and a collection of columns, which are typically produced - by the :func:`.expression.column` function:: + by the :func:`_expression.column` function:: from sqlalchemy import table, column @@ -1828,16 +1890,17 @@ class TableClause(Immutable, FromClause): column("description"), ) - The :class:`.TableClause` construct serves as the base for - the more commonly used :class:`~.schema.Table` object, providing - the usual set of :class:`~.expression.FromClause` services including + The :class:`_expression.TableClause` construct serves as the base for + the more commonly used :class:`_schema.Table` object, providing + the usual set of :class:`_expression.FromClause` services including the ``.c.`` collection and statement generation methods. It does **not** provide all the additional schema-level services - of :class:`~.schema.Table`, including constraints, references to other - tables, or support for :class:`.MetaData`-level services. It's useful + of :class:`_schema.Table`, including constraints, references to other + tables, or support for :class:`_schema.MetaData`-level services. + It's useful on its own as an ad-hoc construct used to generate quick SQL - statements when a more fully fledged :class:`~.schema.Table` + statements when a more fully fledged :class:`_schema.Table` is not on hand. """ @@ -1855,27 +1918,29 @@ class TableClause(Immutable, FromClause): named_with_column = True implicit_returning = False - """:class:`.TableClause` doesn't support having a primary key or column + """:class:`_expression.TableClause` + doesn't support having a primary key or column -level defaults, so implicit returning doesn't apply.""" _autoincrement_column = None """No PK or default support so no autoincrement column.""" def __init__(self, name, *columns): - """Produce a new :class:`.TableClause`. + """Produce a new :class:`_expression.TableClause`. - The object returned is an instance of :class:`.TableClause`, which + The object returned is an instance of :class:`_expression.TableClause` + , which represents the "syntactical" portion of the schema-level - :class:`~.schema.Table` object. + :class:`_schema.Table` object. It may be used to construct lightweight table constructs. - .. versionchanged:: 1.0.0 :func:`.expression.table` can now + .. versionchanged:: 1.0.0 :func:`_expression.table` can now be imported from the plain ``sqlalchemy`` namespace like any other SQL element. :param name: Name of the table. - :param columns: A collection of :func:`.expression.column` constructs. + :param columns: A collection of :func:`_expression.column` constructs. """ @@ -1906,14 +1971,14 @@ class TableClause(Immutable, FromClause): @util.preload_module("sqlalchemy.sql.dml") def insert(self, values=None, inline=False, **kwargs): - """Generate an :func:`~.sql.expression.insert` construct against this - :class:`.TableClause`. + """Generate an :func:`_expression.insert` construct against this + :class:`_expression.TableClause`. E.g.:: table.insert().values(name='foo') - See :func:`~.sql.expression.insert` for argument and usage information. + See :func:`_expression.insert` for argument and usage information. """ return util.preloaded.sql_dml.Insert( @@ -1922,14 +1987,14 @@ class TableClause(Immutable, FromClause): @util.preload_module("sqlalchemy.sql.dml") def update(self, whereclause=None, values=None, inline=False, **kwargs): - """Generate an :func:`.update` construct against this - :class:`.TableClause`. + """Generate an :func:`_expression.update` construct against this + :class:`_expression.TableClause`. E.g.:: table.update().where(table.c.id==7).values(name='foo') - See :func:`.update` for argument and usage information. + See :func:`_expression.update` for argument and usage information. """ return util.preloaded.sql_dml.Update( @@ -1942,14 +2007,14 @@ class TableClause(Immutable, FromClause): @util.preload_module("sqlalchemy.sql.dml") def delete(self, whereclause=None, **kwargs): - """Generate a :func:`.delete` construct against this - :class:`.TableClause`. + """Generate a :func:`_expression.delete` construct against this + :class:`_expression.TableClause`. E.g.:: table.delete().where(table.c.id==7) - See :func:`.delete` for argument and usage information. + See :func:`_expression.delete` for argument and usage information. """ return util.preloaded.sql_dml.Delete(self, whereclause, **kwargs) @@ -1991,7 +2056,8 @@ class ForUpdateArg(ClauseElement): skip_locked=False, key_share=False, ): - """Represents arguments specified to :meth:`.Select.for_update`. + """Represents arguments specified to + :meth:`_expression.Select.for_update`. """ @@ -2012,8 +2078,8 @@ class Values(Generative, FromClause): """represent a ``VALUES`` construct that can be used as a FROM element in a statement. - The :class:`.Values` object is created from the - :func:`~.sql.expression.values` function. + The :class:`_expression.Values` object is created from the + :func:`_expression.values` function. .. versionadded:: 1.4 @@ -2032,13 +2098,15 @@ class Values(Generative, FromClause): ] def __init__(self, *columns, **kw): - r"""Construct a :class:`.Values` construct. + r"""Construct a :class:`_expression.Values` construct. The column expressions and the actual data for - :class:`.Values` are given in two separate steps. The + :class:`_expression.Values` are given in two separate steps. The constructor receives the column expressions typically as - :func:`.column` constructs, and the data is then passed via the - :meth:`.Values.data` method as a list, which can be called multiple + :func:`_expression.column` constructs, + and the data is then passed via the + :meth:`_expression.Values.data` method as a list, + which can be called multiple times to add more data, e.g.:: from sqlalchemy import column @@ -2053,7 +2121,7 @@ class Values(Generative, FromClause): ) :param \*columns: column expressions, typically composed using - :func:`.column` objects. + :func:`_expression.column` objects. :param name: the name for this VALUES construct. If omitted, the VALUES construct will be unnamed in a SQL expression. Different @@ -2073,17 +2141,18 @@ class Values(Generative, FromClause): @_generative def alias(self, name, **kw): - """Return a new :class:`.Values` construct that is a copy of this + """Return a new :class:`_expression.Values` + construct that is a copy of this one with the given name. This method is a VALUES-specific specialization of the - :class:`.FromClause.alias` method. + :class:`_expression.FromClause.alias` method. .. seealso:: :ref:`core_tutorial_aliases` - :func:`~.expression.alias` + :func:`_expression.alias` """ self.name = name @@ -2091,12 +2160,13 @@ class Values(Generative, FromClause): @_generative def lateral(self, name=None): - """Return a new :class:`.Values` with the lateral flag set, so that + """Return a new :class:`_expression.Values` with the lateral flag set, + so that it renders as LATERAL. .. seealso:: - :func:`~.expression.lateral` + :func:`_expression.lateral` """ self._is_lateral = True @@ -2105,7 +2175,8 @@ class Values(Generative, FromClause): @_generative def data(self, values): - """Return a new :class:`.Values` construct, adding the given data + """Return a new :class:`_expression.Values` construct, + adding the given data to the data list. E.g.:: @@ -2113,7 +2184,8 @@ class Values(Generative, FromClause): my_values = my_values.data([(1, 'value 1'), (2, 'value2')]) :param values: a sequence (i.e. list) of tuples that map to the - column expressions given in the :class:`.Values` constructor. + column expressions given in the :class:`_expression.Values` + constructor. """ @@ -2142,8 +2214,9 @@ class SelectBase( """Base class for SELECT statements. - This includes :class:`.Select`, :class:`.CompoundSelect` and - :class:`.TextualSelect`. + This includes :class:`_expression.Select`, + :class:`_expression.CompoundSelect` and + :class:`_expression.TextualSelect`. """ @@ -2159,11 +2232,14 @@ class SelectBase( @property def selected_columns(self): - """A :class:`.ColumnCollection` representing the columns that + """A :class:`_expression.ColumnCollection` + representing the columns that this SELECT statement or similar construct returns in its result set. - This collection differs from the :attr:`.FromClause.columns` collection - of a :class:`.FromClause` in that the columns within this collection + This collection differs from the + :attr:`_expression.FromClause.columns` collection + of a :class:`_expression.FromClause` + in that the columns within this collection cannot be directly nested inside another SELECT statement; a subquery must be applied first which provides for the necessary parenthesization required by SQL. @@ -2175,19 +2251,21 @@ class SelectBase( @property def exported_columns(self): - """A :class:`.ColumnCollection` that represents the "exported" - columns of this :class:`.Selectable`. + """A :class:`_expression.ColumnCollection` + that represents the "exported" + columns of this :class:`expression.Selectable`. - The "exported" columns for a :class:`.SelectBase` object are synonymous - with the :attr:`.SelectBase.selected_columns` collection. + The "exported" columns for a :class:`_expression.SelectBase` + object are synonymous + with the :attr:`_expression.SelectBase.selected_columns` collection. .. versionadded:: 1.4 .. seealso: - :attr:`.Selectable.exported_columns` + :attr:`expression.Selectable.exported_columns` - :attr:`.FromClause.exported_columns` + :attr:`_expression.FromClause.exported_columns` """ @@ -2196,13 +2274,16 @@ class SelectBase( @property @util.deprecated( "1.4", - "The :attr:`.SelectBase.c` and :attr:`.SelectBase.columns` attributes " + "The :attr:`_expression.SelectBase.c` and " + ":attr:`_expression.SelectBase.columns` attributes " "are deprecated and will be removed in a future release; these " "attributes implicitly create a subquery that should be explicit. " - "Please call :meth:`.SelectBase.subquery` first in order to create " + "Please call :meth:`_expression.SelectBase.subquery` " + "first in order to create " "a subquery, which then contains this attribute. To access the " "columns that this SELECT object SELECTs " - "from, use the :attr:`.SelectBase.selected_columns` attribute.", + "from, use the :attr:`_expression.SelectBase.selected_columns` " + "attribute.", ) def c(self): return self._implicit_subquery.columns @@ -2213,10 +2294,11 @@ class SelectBase( @util.deprecated( "1.4", - "The :meth:`.SelectBase.select` method is deprecated " + "The :meth:`_expression.SelectBase.select` method is deprecated " "and will be removed in a future release; this method implicitly " "creates a subquery that should be explicit. " - "Please call :meth:`.SelectBase.subquery` first in order to create " + "Please call :meth:`_expression.SelectBase.subquery` " + "first in order to create " "a subquery, which then can be seleted.", ) def select(self, *arg, **kw): @@ -2224,10 +2306,11 @@ class SelectBase( @util.deprecated( "1.4", - "The :meth:`.SelectBase.join` method is deprecated " + "The :meth:`_expression.SelectBase.join` method is deprecated " "and will be removed in a future release; this method implicitly " "creates a subquery that should be explicit. " - "Please call :meth:`.SelectBase.subquery` first in order to create " + "Please call :meth:`_expression.SelectBase.subquery` " + "first in order to create " "a subquery, which then can be selected.", ) def join(self, *arg, **kw): @@ -2235,10 +2318,11 @@ class SelectBase( @util.deprecated( "1.4", - "The :meth:`.SelectBase.outerjoin` method is deprecated " + "The :meth:`_expression.SelectBase.outerjoin` method is deprecated " "and will be removed in a future release; this method implicitly " "creates a subquery that should be explicit. " - "Please call :meth:`.SelectBase.subquery` first in order to create " + "Please call :meth:`_expression.SelectBase.subquery` " + "first in order to create " "a subquery, which then can be selected.", ) def outerjoin(self, *arg, **kw): @@ -2250,9 +2334,10 @@ class SelectBase( @util.deprecated( "1.4", - "The :meth:`.SelectBase.as_scalar` method is deprecated and will be " + "The :meth:`_expression.SelectBase.as_scalar` " + "method is deprecated and will be " "removed in a future release. Please refer to " - ":meth:`.SelectBase.scalar_subquery`.", + ":meth:`_expression.SelectBase.scalar_subquery`.", ) def as_scalar(self): return self.scalar_subquery() @@ -2267,11 +2352,12 @@ class SelectBase( an enclosing SELECT. Note that the scalar subquery differentiates from the FROM-level - subquery that can be produced using the :meth:`.SelectBase.subquery` + subquery that can be produced using the + :meth:`_expression.SelectBase.subquery` method. .. versionchanged: 1.4 - the ``.as_scalar()`` method was renamed to - :meth:`.SelectBase.scalar_subquery`. + :meth:`_expression.SelectBase.scalar_subquery`. """ if self._label_style is not LABEL_STYLE_NONE: @@ -2285,16 +2371,16 @@ class SelectBase( .. seealso:: - :meth:`~.SelectBase.as_scalar`. + :meth:`_expression.SelectBase.as_scalar`. """ return self.scalar_subquery().label(name) def lateral(self, name=None): - """Return a LATERAL alias of this :class:`.Selectable`. + """Return a LATERAL alias of this :class:`expression.Selectable`. - The return value is the :class:`.Lateral` construct also - provided by the top-level :func:`~.expression.lateral` function. + The return value is the :class:`_expression.Lateral` construct also + provided by the top-level :func:`_expression.lateral` function. .. versionadded:: 1.1 @@ -2310,7 +2396,7 @@ class SelectBase( return [self] def subquery(self, name=None): - """Return a subquery of this :class:`.SelectBase`. + """Return a subquery of this :class:`_expression.SelectBase`. A subquery is from a SQL perspective a parentheized, named construct that can be placed in the FROM clause of another SELECT statement. @@ -2335,10 +2421,14 @@ class SelectBase( SELECT anon_1.id, anon_1.name FROM (SELECT table.id, table.name FROM table) AS anon_1 - Historically, :meth:`.SelectBase.subquery` is equivalent to calling - the :meth:`.FromClause.alias` method on a FROM object; however, - as a :class:`.SelectBase` object is not directly FROM object, - the :meth:`.SelectBase.subquery` method provides clearer semantics. + Historically, :meth:`_expression.SelectBase.subquery` + is equivalent to calling + the :meth:`_expression.FromClause.alias` + method on a FROM object; however, + as a :class:`_expression.SelectBase` + object is not directly FROM object, + the :meth:`_expression.SelectBase.subquery` + method provides clearer semantics. .. versionadded:: 1.4 @@ -2355,22 +2445,25 @@ class SelectBase( raise NotImplementedError() def alias(self, name=None, flat=False): - """Return a named subquery against this :class:`.SelectBase`. + """Return a named subquery against this + :class:`_expression.SelectBase`. - For a :class:`.SelectBase` (as opposed to a :class:`.FromClause`), + For a :class:`_expression.SelectBase` (as opposed to a + :class:`_expression.FromClause`), this returns a :class:`.Subquery` object which behaves mostly the - same as the :class:`.Alias` object that is used with a - :class:`.FromClause`. + same as the :class:`_expression.Alias` object that is used with a + :class:`_expression.FromClause`. - .. versionchanged:: 1.4 The :meth:`.SelectBase.alias` method is now - a synonym for the :meth:`.SelectBase.subquery` method. + .. versionchanged:: 1.4 The :meth:`_expression.SelectBase.alias` + method is now + a synonym for the :meth:`_expression.SelectBase.subquery` method. """ return self.subquery(name=name) class SelectStatementGrouping(GroupedElement, SelectBase): - """Represent a grouping of a :class:`.SelectBase`. + """Represent a grouping of a :class:`_expression.SelectBase`. This differs from :class:`.Subquery` in that we are still an "inner" SELECT statement, this is strictly for grouping inside of @@ -2417,7 +2510,8 @@ class SelectStatementGrouping(GroupedElement, SelectBase): @property def selected_columns(self): - """A :class:`.ColumnCollection` representing the columns that + """A :class:`_expression.ColumnCollection` + representing the columns that the embedded SELECT statement returns in its result set. .. versionadded:: 1.4 @@ -2437,9 +2531,10 @@ class SelectStatementGrouping(GroupedElement, SelectBase): class DeprecatedSelectBaseGenerations(object): @util.deprecated( "1.4", - "The :meth:`.GenerativeSelect.append_order_by` method is deprecated " + "The :meth:`_expression.GenerativeSelect.append_order_by` " + "method is deprecated " "and will be removed in a future release. Use the generative method " - ":meth:`.GenerativeSelect.order_by`.", + ":meth:`_expression.GenerativeSelect.order_by`.", ) def append_order_by(self, *clauses): """Append the given ORDER BY criterion applied to this selectable. @@ -2447,21 +2542,23 @@ class DeprecatedSelectBaseGenerations(object): The criterion will be appended to any pre-existing ORDER BY criterion. This is an **in-place** mutation method; the - :meth:`~.GenerativeSelect.order_by` method is preferred, as it + :meth:`_expression.GenerativeSelect.order_by` method is preferred, + as it provides standard :term:`method chaining`. .. seealso:: - :meth:`.GenerativeSelect.order_by` + :meth:`_expression.GenerativeSelect.order_by` """ self.order_by.non_generative(self, *clauses) @util.deprecated( "1.4", - "The :meth:`.GenerativeSelect.append_group_by` method is deprecated " + "The :meth:`_expression.GenerativeSelect.append_group_by` " + "method is deprecated " "and will be removed in a future release. Use the generative method " - ":meth:`.GenerativeSelect.group_by`.", + ":meth:`_expression.GenerativeSelect.group_by`.", ) def append_group_by(self, *clauses): """Append the given GROUP BY criterion applied to this selectable. @@ -2469,12 +2566,13 @@ class DeprecatedSelectBaseGenerations(object): The criterion will be appended to any pre-existing GROUP BY criterion. This is an **in-place** mutation method; the - :meth:`~.GenerativeSelect.group_by` method is preferred, as it + :meth:`_expression.GenerativeSelect.group_by` method is preferred, + as it provides standard :term:`method chaining`. .. seealso:: - :meth:`.GenerativeSelect.group_by` + :meth:`_expression.GenerativeSelect.group_by` """ self.group_by.non_generative(self, *clauses) @@ -2489,10 +2587,13 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase): """Base class for SELECT statements where additional elements can be added. - This serves as the base for :class:`.Select` and :class:`.CompoundSelect` + This serves as the base for :class:`_expression.Select` and + :class:`_expression.CompoundSelect` where elements such as ORDER BY, GROUP BY can be added and column - rendering can be controlled. Compare to :class:`.TextualSelect`, which, - while it subclasses :class:`.SelectBase` and is also a SELECT construct, + rendering can be controlled. Compare to + :class:`_expression.TextualSelect`, which, + while it subclasses :class:`_expression.SelectBase` + and is also a SELECT construct, represents a fixed textual string which cannot be altered at this level, only wrapped as a subquery. @@ -2540,7 +2641,8 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase): skip_locked=False, key_share=False, ): - """Specify a ``FOR UPDATE`` clause for this :class:`.GenerativeSelect`. + """Specify a ``FOR UPDATE`` clause for this + :class:`_expression.GenerativeSelect`. E.g.:: @@ -2569,7 +2671,8 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase): ``nowait``, will render ``FOR SHARE NOWAIT``. :param of: SQL expression or list of SQL expression elements - (typically :class:`.Column` objects or a compatible expression) which + (typically :class:`_schema.Column` + objects or a compatible expression) which will render into a ``FOR UPDATE OF`` clause; supported by PostgreSQL and Oracle. May render as a table or as a column depending on backend. @@ -2708,7 +2811,7 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase): support ``LIMIT`` will attempt to provide similar functionality. - .. versionchanged:: 1.0.0 - :meth:`.Select.limit` can now + .. versionchanged:: 1.0.0 - :meth:`_expression.Select.limit` can now accept arbitrary SQL expressions as well as integer values. :param limit: an integer LIMIT parameter, or a SQL expression @@ -2730,7 +2833,7 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase): functionality. - .. versionchanged:: 1.0.0 - :meth:`.Select.offset` can now + .. versionchanged:: 1.0.0 - :meth:`_expression.Select.offset` can now accept arbitrary SQL expressions as well as integer values. :param offset: an integer OFFSET parameter, or a SQL expression @@ -2749,7 +2852,8 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase): stmt = select([table]).order_by(table.c.id, table.c.name) - :param \*order_by: a series of :class:`.ColumnElement` constructs + :param \*order_by: a series of :class:`_expression.ColumnElement` + constructs which will be used to generate an ORDER BY clause. .. seealso:: @@ -2776,7 +2880,8 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase): stmt = select([table.c.name, func.max(table.c.stat)]).\ group_by(table.c.name) - :param \*group_by: a series of :class:`.ColumnElement` constructs + :param \*group_by: a series of :class:`_expression.ColumnElement` + constructs which will be used to generate an GROUP BY clause. .. seealso:: @@ -2810,17 +2915,17 @@ class CompoundSelect(HasCompileState, GenerativeSelect): .. seealso:: - :func:`.union` + :func:`_expression.union` - :func:`.union_all` + :func:`_expression.union_all` - :func:`.intersect` + :func:`_expression.intersect` - :func:`.intersect_all` + :func:`_expression.intersect_all` - :func:`.except` + :func:`_expression.except` - :func:`.except_all` + :func:`_expression.except_all` """ @@ -2863,13 +2968,13 @@ class CompoundSelect(HasCompileState, GenerativeSelect): r"""Return a ``UNION`` of multiple selectables. The returned object is an instance of - :class:`.CompoundSelect`. + :class:`_expression.CompoundSelect`. A similar :func:`union()` method is available on all - :class:`.FromClause` subclasses. + :class:`_expression.FromClause` subclasses. \*selects - a list of :class:`.Select` instances. + a list of :class:`_expression.Select` instances. \**kwargs available keyword arguments are the same as those of @@ -2883,13 +2988,13 @@ class CompoundSelect(HasCompileState, GenerativeSelect): r"""Return a ``UNION ALL`` of multiple selectables. The returned object is an instance of - :class:`.CompoundSelect`. + :class:`_expression.CompoundSelect`. A similar :func:`union_all()` method is available on all - :class:`.FromClause` subclasses. + :class:`_expression.FromClause` subclasses. \*selects - a list of :class:`.Select` instances. + a list of :class:`_expression.Select` instances. \**kwargs available keyword arguments are the same as those of @@ -2903,10 +3008,10 @@ class CompoundSelect(HasCompileState, GenerativeSelect): r"""Return an ``EXCEPT`` of multiple selectables. The returned object is an instance of - :class:`.CompoundSelect`. + :class:`_expression.CompoundSelect`. \*selects - a list of :class:`.Select` instances. + a list of :class:`_expression.Select` instances. \**kwargs available keyword arguments are the same as those of @@ -2920,10 +3025,10 @@ class CompoundSelect(HasCompileState, GenerativeSelect): r"""Return an ``EXCEPT ALL`` of multiple selectables. The returned object is an instance of - :class:`.CompoundSelect`. + :class:`_expression.CompoundSelect`. \*selects - a list of :class:`.Select` instances. + a list of :class:`_expression.Select` instances. \**kwargs available keyword arguments are the same as those of @@ -2937,10 +3042,10 @@ class CompoundSelect(HasCompileState, GenerativeSelect): r"""Return an ``INTERSECT`` of multiple selectables. The returned object is an instance of - :class:`.CompoundSelect`. + :class:`_expression.CompoundSelect`. \*selects - a list of :class:`.Select` instances. + a list of :class:`_expression.Select` instances. \**kwargs available keyword arguments are the same as those of @@ -2954,10 +3059,10 @@ class CompoundSelect(HasCompileState, GenerativeSelect): r"""Return an ``INTERSECT ALL`` of multiple selectables. The returned object is an instance of - :class:`.CompoundSelect`. + :class:`_expression.CompoundSelect`. \*selects - a list of :class:`.Select` instances. + a list of :class:`_expression.Select` instances. \**kwargs available keyword arguments are the same as those of @@ -3035,11 +3140,13 @@ class CompoundSelect(HasCompileState, GenerativeSelect): @property def selected_columns(self): - """A :class:`.ColumnCollection` representing the columns that + """A :class:`_expression.ColumnCollection` + representing the columns that this SELECT statement or similar construct returns in its result set. - For a :class:`.CompoundSelect`, the - :attr:`.CompoundSelect.selected_columns` attribute returns the selected + For a :class:`_expression.CompoundSelect`, the + :attr:`_expression.CompoundSelect.selected_columns` + attribute returns the selected columns of the first SELECT statement contained within the series of statements within the set operation. @@ -3067,16 +3174,18 @@ class CompoundSelect(HasCompileState, GenerativeSelect): class DeprecatedSelectGenerations(object): @util.deprecated( "1.4", - "The :meth:`.Select.append_correlation` method is deprecated " + "The :meth:`_expression.Select.append_correlation` " + "method is deprecated " "and will be removed in a future release. Use the generative " - "method :meth:`.Select.correlate`.", + "method :meth:`_expression.Select.correlate`.", ) def append_correlation(self, fromclause): """append the given correlation expression to this select() construct. This is an **in-place** mutation method; the - :meth:`~.Select.correlate` method is preferred, as it provides + :meth:`_expression.Select.correlate` method is preferred, + as it provides standard :term:`method chaining`. """ @@ -3085,9 +3194,9 @@ class DeprecatedSelectGenerations(object): @util.deprecated( "1.4", - "The :meth:`.Select.append_column` method is deprecated " + "The :meth:`_expression.Select.append_column` method is deprecated " "and will be removed in a future release. Use the generative " - "method :meth:`.Select.column`.", + "method :meth:`_expression.Select.column`.", ) def append_column(self, column): """append the given column expression to the columns clause of this @@ -3098,28 +3207,30 @@ class DeprecatedSelectGenerations(object): my_select.append_column(some_table.c.new_column) This is an **in-place** mutation method; the - :meth:`~.Select.column` method is preferred, as it provides standard + :meth:`_expression.Select.column` method is preferred, + as it provides standard :term:`method chaining`. - See the documentation for :meth:`.Select.with_only_columns` + See the documentation for :meth:`_expression.Select.with_only_columns` for guidelines on adding /replacing the columns of a - :class:`.Select` object. + :class:`_expression.Select` object. """ self.add_columns.non_generative(self, column) @util.deprecated( "1.4", - "The :meth:`.Select.append_prefix` method is deprecated " + "The :meth:`_expression.Select.append_prefix` method is deprecated " "and will be removed in a future release. Use the generative " - "method :meth:`.Select.prefix_with`.", + "method :meth:`_expression.Select.prefix_with`.", ) def append_prefix(self, clause): """append the given columns clause prefix expression to this select() construct. This is an **in-place** mutation method; the - :meth:`~.Select.prefix_with` method is preferred, as it provides + :meth:`_expression.Select.prefix_with` method is preferred, + as it provides standard :term:`method chaining`. """ @@ -3127,9 +3238,10 @@ class DeprecatedSelectGenerations(object): @util.deprecated( "1.4", - "The :meth:`.Select.append_whereclause` method is deprecated " + "The :meth:`_expression.Select.append_whereclause` " + "method is deprecated " "and will be removed in a future release. Use the generative " - "method :meth:`.Select.where`.", + "method :meth:`_expression.Select.where`.", ) def append_whereclause(self, whereclause): """append the given expression to this select() construct's WHERE @@ -3138,7 +3250,8 @@ class DeprecatedSelectGenerations(object): The expression will be joined to existing WHERE criterion via AND. This is an **in-place** mutation method; the - :meth:`~.Select.where` method is preferred, as it provides standard + :meth:`_expression.Select.where` method is preferred, + as it provides standard :term:`method chaining`. """ @@ -3146,9 +3259,9 @@ class DeprecatedSelectGenerations(object): @util.deprecated( "1.4", - "The :meth:`.Select.append_having` method is deprecated " + "The :meth:`_expression.Select.append_having` method is deprecated " "and will be removed in a future release. Use the generative " - "method :meth:`.Select.having`.", + "method :meth:`_expression.Select.having`.", ) def append_having(self, having): """append the given expression to this select() construct's HAVING @@ -3157,7 +3270,8 @@ class DeprecatedSelectGenerations(object): The expression will be joined to existing HAVING criterion via AND. This is an **in-place** mutation method; the - :meth:`~.Select.having` method is preferred, as it provides standard + :meth:`_expression.Select.having` method is preferred, + as it provides standard :term:`method chaining`. """ @@ -3166,16 +3280,17 @@ class DeprecatedSelectGenerations(object): @util.deprecated( "1.4", - "The :meth:`.Select.append_from` method is deprecated " + "The :meth:`_expression.Select.append_from` method is deprecated " "and will be removed in a future release. Use the generative " - "method :meth:`.Select.select_from`.", + "method :meth:`_expression.Select.select_from`.", ) def append_from(self, fromclause): """append the given FromClause expression to this select() construct's FROM clause. This is an **in-place** mutation method; the - :meth:`~.Select.select_from` method is preferred, as it provides + :meth:`_expression.Select.select_from` method is preferred, + as it provides standard :term:`method chaining`. """ @@ -3353,32 +3468,38 @@ class Select( @classmethod def _create_select(cls, *entities): - r"""Construct a new :class:`.Select` using the 2.x style API. + r"""Construct a new :class:`_expression.Select` using the 2. + x style API. .. versionadded:: 2.0 - the :func:`.future.select` construct is the same construct as the one returned by - :func:`.sql.expression.select`, except that the function only + :func:`_expression.select`, except that the function only accepts the "columns clause" entities up front; the rest of the state of the SELECT should be built up using generative methods. Similar functionality is also available via the - :meth:`.FromClause.select` method on any :class:`.FromClause`. + :meth:`_expression.FromClause.select` method on any + :class:`_expression.FromClause`. .. seealso:: :ref:`coretutorial_selecting` - Core Tutorial description of - :func:`~.sql.expression.select`. + :func:`_expression.select`. :param \*entities: Entities to SELECT from. For Core usage, this is typically a series - of :class:`.ColumnElement` and / or :class:`.FromClause` + of :class:`_expression.ColumnElement` and / or + :class:`_expression.FromClause` objects which will form the columns clause of the resulting statement. For those objects that are instances of - :class:`.FromClause` (typically :class:`.Table` or :class:`.Alias` - objects), the :attr:`.FromClause.c` collection is extracted - to form a collection of :class:`.ColumnElement` objects. - - This parameter will also accept :class:`.Text` constructs as + :class:`_expression.FromClause` (typically :class:`_schema.Table` + or :class:`_expression.Alias` + objects), the :attr:`_expression.FromClause.c` + collection is extracted + to form a collection of :class:`_expression.ColumnElement` objects. + + This parameter will also accept :class:`_expression.TextClause` + constructs as given, as well as ORM-mapped classes. """ @@ -3417,82 +3538,102 @@ class Select( suffixes=None, **kwargs ): - """Construct a new :class:`.Select` using the 1.x style API. + """Construct a new :class:`_expression.Select` using the 1.x style API + . Similar functionality is also available via the - :meth:`.FromClause.select` method on any :class:`.FromClause`. + :meth:`_expression.FromClause.select` method on any + :class:`_expression.FromClause`. - All arguments which accept :class:`.ClauseElement` arguments also + All arguments which accept :class:`_expression.ClauseElement` + arguments also accept string arguments, which will be converted as appropriate into - either :func:`.text()` or :func:`.literal_column()` constructs. + either :func:`_expression.text()` or + :func:`_expression.literal_column()` constructs. .. seealso:: :ref:`coretutorial_selecting` - Core Tutorial description of - :func:`~.sql.expression.select`. + :func:`_expression.select`. :param columns: - A list of :class:`.ColumnElement` or :class:`.FromClause` + A list of :class:`_expression.ColumnElement` or + :class:`_expression.FromClause` objects which will form the columns clause of the resulting statement. For those objects that are instances of - :class:`.FromClause` (typically :class:`.Table` or :class:`.Alias` - objects), the :attr:`.FromClause.c` collection is extracted - to form a collection of :class:`.ColumnElement` objects. - - This parameter will also accept :class:`.Text` constructs as + :class:`_expression.FromClause` (typically :class:`_schema.Table` + or :class:`_expression.Alias` + objects), the :attr:`_expression.FromClause.c` + collection is extracted + to form a collection of :class:`_expression.ColumnElement` objects. + + This parameter will also accept :class:`_expression.TextClause` + constructs as given, as well as ORM-mapped classes. .. note:: - The :paramref:`.select.columns` parameter is not available - in the method form of :func:`~.sql.expression.select`, e.g. - :meth:`.FromClause.select`. + The :paramref:`_expression.select.columns` + parameter is not available + in the method form of :func:`_expression.select`, e.g. + :meth:`_expression.FromClause.select`. .. seealso:: - :meth:`.Select.column` + :meth:`_expression.Select.column` - :meth:`.Select.with_only_columns` + :meth:`_expression.Select.with_only_columns` :param whereclause: - A :class:`.ClauseElement` expression which will be used to form the + A :class:`_expression.ClauseElement` + expression which will be used to form the ``WHERE`` clause. It is typically preferable to add WHERE - criterion to an existing :class:`.Select` using method chaining - with :meth:`.Select.where`. + criterion to an existing :class:`_expression.Select` + using method chaining + with :meth:`_expression.Select.where`. .. seealso:: - :meth:`.Select.where` + :meth:`_expression.Select.where` :param from_obj: - A list of :class:`.ClauseElement` objects which will be added to the + A list of :class:`_expression.ClauseElement` + objects which will be added to the ``FROM`` clause of the resulting statement. This is equivalent - to calling :meth:`.Select.select_from` using method chaining on - an existing :class:`.Select` object. + to calling :meth:`_expression.Select.select_from` + using method chaining on + an existing :class:`_expression.Select` object. .. seealso:: - :meth:`.Select.select_from` - full description of explicit + :meth:`_expression.Select.select_from` + - full description of explicit FROM clause specification. :param bind=None: - an :class:`~.Engine` or :class:`~.Connection` instance + an :class:`_engine.Engine` or :class:`_engine.Connection` instance to which the - resulting :class:`.Select` object will be bound. The - :class:`.Select` object will otherwise automatically bind to + resulting :class:`_expression.Select` object will be bound. The + :class:`_expression.Select` + object will otherwise automatically bind to whatever :class:`~.base.Connectable` instances can be located within - its contained :class:`.ClauseElement` members. + its contained :class:`_expression.ClauseElement` members. :param correlate=True: - indicates that this :class:`.Select` object should have its - contained :class:`.FromClause` elements "correlated" to an enclosing - :class:`.Select` object. It is typically preferable to specify - correlations on an existing :class:`.Select` construct using - :meth:`.Select.correlate`. + indicates that this :class:`_expression.Select` + object should have its + contained :class:`_expression.FromClause` + elements "correlated" to an enclosing + :class:`_expression.Select` object. + It is typically preferable to specify + correlations on an existing :class:`_expression.Select` + construct using + :meth:`_expression.Select.correlate`. .. seealso:: - :meth:`.Select.correlate` - full description of correlation. + :meth:`_expression.Select.correlate` + - full description of correlation. :param distinct=False: when ``True``, applies a ``DISTINCT`` qualifier to the columns @@ -3503,66 +3644,74 @@ class Select( is understood by the PostgreSQL dialect to render the ``DISTINCT ON ()`` syntax. - ``distinct`` is also available on an existing :class:`.Select` - object via the :meth:`~.Select.distinct` method. + ``distinct`` is also available on an existing + :class:`_expression.Select` + object via the :meth:`_expression.Select.distinct` method. .. seealso:: - :meth:`.Select.distinct` + :meth:`_expression.Select.distinct` :param group_by: - a list of :class:`.ClauseElement` objects which will comprise the + a list of :class:`_expression.ClauseElement` + objects which will comprise the ``GROUP BY`` clause of the resulting select. This parameter is typically specified more naturally using the - :meth:`.Select.group_by` method on an existing :class:`.Select`. + :meth:`_expression.Select.group_by` method on an existing + :class:`_expression.Select`. .. seealso:: - :meth:`.Select.group_by` + :meth:`_expression.Select.group_by` :param having: - a :class:`.ClauseElement` that will comprise the ``HAVING`` clause + a :class:`_expression.ClauseElement` + that will comprise the ``HAVING`` clause of the resulting select when ``GROUP BY`` is used. This parameter is typically specified more naturally using the - :meth:`.Select.having` method on an existing :class:`.Select`. + :meth:`_expression.Select.having` method on an existing + :class:`_expression.Select`. .. seealso:: - :meth:`.Select.having` + :meth:`_expression.Select.having` :param limit=None: a numerical value which usually renders as a ``LIMIT`` expression in the resulting select. Backends that don't support ``LIMIT`` will attempt to provide similar functionality. This parameter is typically specified more - naturally using the :meth:`.Select.limit` method on an existing - :class:`.Select`. + naturally using the :meth:`_expression.Select.limit` + method on an existing + :class:`_expression.Select`. .. seealso:: - :meth:`.Select.limit` + :meth:`_expression.Select.limit` :param offset=None: a numeric value which usually renders as an ``OFFSET`` expression in the resulting select. Backends that don't support ``OFFSET`` will attempt to provide similar functionality. This parameter is typically specified more naturally - using the :meth:`.Select.offset` method on an existing - :class:`.Select`. + using the :meth:`_expression.Select.offset` method on an existing + :class:`_expression.Select`. .. seealso:: - :meth:`.Select.offset` + :meth:`_expression.Select.offset` :param order_by: - a scalar or list of :class:`.ClauseElement` objects which will + a scalar or list of :class:`_expression.ClauseElement` + objects which will comprise the ``ORDER BY`` clause of the resulting select. This parameter is typically specified more naturally using the - :meth:`.Select.order_by` method on an existing :class:`.Select`. + :meth:`_expression.Select.order_by` method on an existing + :class:`_expression.Select`. .. seealso:: - :meth:`.Select.order_by` + :meth:`_expression.Select.order_by` :param use_labels=False: when ``True``, the statement will be generated using labels @@ -3570,16 +3719,18 @@ class Select( column with its parent table's (or aliases) name so that name conflicts between columns in different tables don't occur. The format of the label is _. The "c" - collection of the resulting :class:`.Select` object will use these + collection of the resulting :class:`_expression.Select` + object will use these names as well for targeting column members. This parameter can also be specified on an existing - :class:`.Select` object using the :meth:`.Select.apply_labels` + :class:`_expression.Select` object using the + :meth:`_expression.Select.apply_labels` method. .. seealso:: - :meth:`.Select.apply_labels` + :meth:`_expression.Select.apply_labels` """ util.warn_deprecated_20( @@ -3656,9 +3807,10 @@ class Select( return self._compile_state_factory(self, None)._get_display_froms() def with_statement_hint(self, text, dialect_name="*"): - """add a statement hint to this :class:`.Select`. + """add a statement hint to this :class:`_expression.Select`. - This method is similar to :meth:`.Select.with_hint` except that + This method is similar to :meth:`_expression.Select.with_hint` + except that it does not require an individual table, and instead applies to the statement as a whole. @@ -3670,7 +3822,7 @@ class Select( .. seealso:: - :meth:`.Select.with_hint` + :meth:`_expression.Select.with_hint` :meth:.`.Select.prefix_with` - generic SELECT prefixing which also can suit some database-specific HINT syntaxes such as MySQL @@ -3682,11 +3834,12 @@ class Select( @_generative def with_hint(self, selectable, text, dialect_name="*"): r"""Add an indexing or other executional context hint for the given - selectable to this :class:`.Select`. + selectable to this :class:`_expression.Select`. The text of the hint is rendered in the appropriate location for the database backend in use, relative - to the given :class:`.Table` or :class:`.Alias` passed as the + to the given :class:`_schema.Table` or :class:`_expression.Alias` + passed as the ``selectable`` argument. The dialect implementation typically uses Python string substitution syntax with the token ``%(name)s`` to render the name of @@ -3710,7 +3863,7 @@ class Select( .. seealso:: - :meth:`.Select.with_statement_hint` + :meth:`_expression.Select.with_statement_hint` """ if selectable is None: @@ -3724,7 +3877,7 @@ class Select( be rendered into the columns clause of the resulting SELECT statement. This method is legacy as of 1.4 and is superseded by the - :attr:`.Select.exported_columns` collection. + :attr:`_expression.Select.exported_columns` collection. """ @@ -3795,9 +3948,10 @@ class Select( my_select = my_select.add_columns(table.c.new_column) - See the documentation for :meth:`.Select.with_only_columns` + See the documentation for + :meth:`_expression.Select.with_only_columns` for guidelines on adding /replacing the columns of a - :class:`.Select` object. + :class:`_expression.Select` object. """ # memoizations should be cleared here as of @@ -3812,9 +3966,9 @@ class Select( @util.deprecated( "1.4", - "The :meth:`.Select.column` method is deprecated and will " + "The :meth:`_expression.Select.column` method is deprecated and will " "be removed in a future release. Please use " - ":meth:`.Select.add_columns`", + ":meth:`_expression.Select.add_columns`", ) def column(self, column): """return a new select() construct with the given column expression @@ -3824,9 +3978,10 @@ class Select( my_select = my_select.column(table.c.new_column) - See the documentation for :meth:`.Select.with_only_columns` + See the documentation for + :meth:`_expression.Select.with_only_columns` for guidelines on adding /replacing the columns of a - :class:`.Select` object. + :class:`_expression.Select` object. """ return self.add_columns(column) @@ -3841,7 +3996,8 @@ class Select( comparison in the WHERE clause of the statement. The primary purpose of this method is to automatically construct a select statement with all uniquely-named columns, without the need to use - table-qualified labels as :meth:`.apply_labels` does. + table-qualified labels as :meth:`_expression.Select.apply_labels` does + . When columns are omitted based on foreign key, the referred-to column is the one that's kept. When columns are omitted based on @@ -3863,11 +4019,11 @@ class Select( @_generative def with_only_columns(self, columns): - r"""Return a new :func:`~.sql.expression.select` construct with its columns + r"""Return a new :func:`_expression.select` construct with its columns clause replaced with the given columns. This method is exactly equivalent to as if the original - :func:`~.sql.expression.select` had been called with the given columns + :func:`_expression.select` had been called with the given columns clause. I.e. a statement:: s = select([table1.c.a, table1.c.b]) @@ -3893,7 +4049,7 @@ class Select( The preferred way to maintain a specific FROM clause in the construct, assuming it won't be represented anywhere else (i.e. not in the WHERE clause, etc.) is to set it using - :meth:`.Select.select_from`:: + :meth:`_expression.Select.select_from`:: >>> s1 = select([table1.c.a, table2.c.b]).\ ... select_from(table1.join(table2, @@ -3903,13 +4059,15 @@ class Select( SELECT t2.b FROM t1 JOIN t2 ON t1.a=t2.a Care should also be taken to use the correct set of column objects - passed to :meth:`.Select.with_only_columns`. Since the method is - essentially equivalent to calling the :func:`~.sql.expression.select` + passed to :meth:`_expression.Select.with_only_columns`. + Since the method is + essentially equivalent to calling the :func:`_expression.select` construct in the first place with the given columns, the columns passed - to :meth:`.Select.with_only_columns` should usually be a subset of - those which were passed to the :func:`~.sql.expression.select` + to :meth:`_expression.Select.with_only_columns` + should usually be a subset of + those which were passed to the :func:`_expression.select` construct, not those which are available from the ``.c`` collection of - that :func:`~.sql.expression.select`. That is:: + that :func:`_expression.select`. That is:: s = select([table1.c.a, table1.c.b]).select_from(table1) s = s.with_only_columns([table1.c.b]) @@ -3925,7 +4083,7 @@ class Select( FROM (SELECT t1.a AS a, t1.b AS b FROM t1), t1 - Since the :func:`~.sql.expression.select` construct is essentially + Since the :func:`_expression.select` construct is essentially being asked to select both from ``table1`` as well as itself. """ @@ -3945,7 +4103,8 @@ class Select( @property def _whereclause(self): - """Legacy, return the WHERE clause as a :class:`.BooleanClauseList`""" + """Legacy, return the WHERE clause as a """ + """:class:`_expression.BooleanClauseList`""" return and_(*self._where_criteria) @@ -3990,7 +4149,7 @@ class Select( @_generative def select_from(self, *froms): - r"""return a new :func:`~.sql.expression.select` construct with the + r"""return a new :func:`_expression.select` construct with the given FROM expression(s) merged into its list of FROM objects. @@ -4004,14 +4163,17 @@ class Select( ) The "from" list is a unique set on the identity of each element, - so adding an already present :class:`.Table` or other selectable - will have no effect. Passing a :class:`.Join` that refers - to an already present :class:`.Table` or other selectable will have + so adding an already present :class:`_schema.Table` + or other selectable + will have no effect. Passing a :class:`_expression.Join` that refers + to an already present :class:`_schema.Table` + or other selectable will have the effect of concealing the presence of that selectable as an individual element in the rendered FROM list, instead rendering it into a JOIN clause. - While the typical purpose of :meth:`.Select.select_from` is to + While the typical purpose of :meth:`_expression.Select.select_from` + is to replace the default, derived FROM clause with a join, it can also be called with individual table elements, multiple times if desired, in the case that the FROM clause cannot be fully @@ -4028,41 +4190,52 @@ class Select( @_generative def correlate(self, *fromclauses): - r"""return a new :class:`.Select` which will correlate the given FROM - clauses to that of an enclosing :class:`.Select`. + r"""return a new :class:`_expression.Select` + which will correlate the given FROM + clauses to that of an enclosing :class:`_expression.Select`. - Calling this method turns off the :class:`.Select` object's + Calling this method turns off the :class:`_expression.Select` object's default behavior of "auto-correlation". Normally, FROM elements - which appear in a :class:`.Select` that encloses this one via + which appear in a :class:`_expression.Select` + that encloses this one via its :term:`WHERE clause`, ORDER BY, HAVING or - :term:`columns clause` will be omitted from this :class:`.Select` + :term:`columns clause` will be omitted from this + :class:`_expression.Select` object's :term:`FROM clause`. Setting an explicit correlation collection using the - :meth:`.Select.correlate` method provides a fixed list of FROM objects + :meth:`_expression.Select.correlate` + method provides a fixed list of FROM objects that can potentially take place in this process. - When :meth:`.Select.correlate` is used to apply specific FROM clauses + When :meth:`_expression.Select.correlate` + is used to apply specific FROM clauses for correlation, the FROM elements become candidates for - correlation regardless of how deeply nested this :class:`.Select` - object is, relative to an enclosing :class:`.Select` which refers to + correlation regardless of how deeply nested this + :class:`_expression.Select` + object is, relative to an enclosing :class:`_expression.Select` + which refers to the same FROM object. This is in contrast to the behavior of "auto-correlation" which only correlates to an immediate enclosing - :class:`.Select`. Multi-level correlation ensures that the link - between enclosed and enclosing :class:`.Select` is always via + :class:`_expression.Select`. + Multi-level correlation ensures that the link + between enclosed and enclosing :class:`_expression.Select` + is always via at least one WHERE/ORDER BY/HAVING/columns clause in order for correlation to take place. - If ``None`` is passed, the :class:`.Select` object will correlate + If ``None`` is passed, the :class:`_expression.Select` + object will correlate none of its FROM entries, and all will render unconditionally in the local FROM clause. - :param \*fromclauses: a list of one or more :class:`.FromClause` + :param \*fromclauses: a list of one or more + :class:`_expression.FromClause` constructs, or other compatible constructs (i.e. ORM-mapped classes) to become part of the correlate collection. .. seealso:: - :meth:`.Select.correlate_except` + :meth:`_expression.Select.correlate_except` :ref:`correlated_subqueries` @@ -4078,26 +4251,29 @@ class Select( @_generative def correlate_except(self, *fromclauses): - r"""return a new :class:`.Select` which will omit the given FROM + r"""return a new :class:`_expression.Select` + which will omit the given FROM clauses from the auto-correlation process. - Calling :meth:`.Select.correlate_except` turns off the - :class:`.Select` object's default behavior of + Calling :meth:`_expression.Select.correlate_except` turns off the + :class:`_expression.Select` object's default behavior of "auto-correlation" for the given FROM elements. An element specified here will unconditionally appear in the FROM list, while all other FROM elements remain subject to normal auto-correlation behaviors. - If ``None`` is passed, the :class:`.Select` object will correlate + If ``None`` is passed, the :class:`_expression.Select` + object will correlate all of its FROM entries. - :param \*fromclauses: a list of one or more :class:`.FromClause` + :param \*fromclauses: a list of one or more + :class:`_expression.FromClause` constructs, or other compatible constructs (i.e. ORM-mapped classes) to become part of the correlate-exception collection. .. seealso:: - :meth:`.Select.correlate` + :meth:`_expression.Select.correlate` :ref:`correlated_subqueries` @@ -4113,18 +4289,22 @@ class Select( @HasMemoized.memoized_attribute def selected_columns(self): - """A :class:`.ColumnCollection` representing the columns that + """A :class:`_expression.ColumnCollection` + representing the columns that this SELECT statement or similar construct returns in its result set. - This collection differs from the :attr:`.FromClause.columns` collection - of a :class:`.FromClause` in that the columns within this collection + This collection differs from the + :attr:`_expression.FromClause.columns` collection + of a :class:`_expression.FromClause` + in that the columns within this collection cannot be directly nested inside another SELECT statement; a subquery must be applied first which provides for the necessary parenthesization required by SQL. - For a :func:`~.sql.expression.select` construct, the collection here is + For a :func:`_expression.select` construct, the collection here is exactly what would be rendered inside the "SELECT" statement, and the - :class:`.ColumnElement` objects are directly present as they were + :class:`_expression.ColumnElement` + objects are directly present as they were given, e.g.:: col1 = column('q', Integer) @@ -4133,9 +4313,11 @@ class Select( Above, ``stmt.selected_columns`` would be a collection that contains the ``col1`` and ``col2`` objects directly. For a statement that is - against a :class:`.Table` or other :class:`.FromClause`, the collection - will use the :class:`.ColumnElement` objects that are in the - :attr:`.FromClause.c` collection of the from element. + against a :class:`_schema.Table` or other + :class:`_expression.FromClause`, the collection + will use the :class:`_expression.ColumnElement` + objects that are in the + :attr:`_expression.FromClause.c` collection of the from element. .. versionadded:: 1.4 @@ -4425,7 +4607,7 @@ class ScalarSelect(roles.InElementRole, Generative, Grouping): @_generative def where(self, crit): """Apply a WHERE clause to the SELECT statement referred to - by this :class:`.ScalarSelect`. + by this :class:`_expression.ScalarSelect`. """ self.element = self.element.where(crit) @@ -4442,8 +4624,8 @@ class Exists(UnaryExpression): _from_objects = [] def __init__(self, *args, **kwargs): - """Construct a new :class:`.Exists` against an existing - :class:`.Select` object. + """Construct a new :class:`_expression.Exists` against an existing + :class:`_expression.Select` object. Calling styles are of the following forms:: @@ -4499,8 +4681,10 @@ class Exists(UnaryExpression): return e def select_from(self, clause): - """return a new :class:`.Exists` construct, applying the given - expression to the :meth:`.Select.select_from` method of the select + """return a new :class:`_expression.Exists` construct, + applying the given + expression to the :meth:`_expression.Select.select_from` + method of the select statement contained. """ @@ -4519,25 +4703,30 @@ class Exists(UnaryExpression): class TextualSelect(SelectBase): - """Wrap a :class:`.TextClause` construct within a :class:`.SelectBase` + """Wrap a :class:`_expression.TextClause` construct within a + :class:`_expression.SelectBase` interface. - This allows the :class:`.TextClause` object to gain a ``.c`` collection - and other FROM-like capabilities such as :meth:`.FromClause.alias`, - :meth:`.SelectBase.cte`, etc. + This allows the :class:`_expression.TextClause` object to gain a ``. + c`` collection + and other FROM-like capabilities such as + :meth:`_expression.FromClause.alias`, + :meth:`_expression.SelectBase.cte`, etc. - The :class:`.TextualSelect` construct is produced via the - :meth:`.TextClause.columns` method - see that method for details. + The :class:`_expression.TextualSelect` construct is produced via the + :meth:`_expression.TextClause.columns` + method - see that method for details. - .. versionchanged:: 1.4 the :class:`.TextualSelect` class was renamed + .. versionchanged:: 1.4 the :class:`_expression.TextualSelect` + class was renamed from ``TextAsFrom``, to more correctly suit its role as a SELECT-oriented object and not a FROM clause. .. seealso:: - :func:`.text` + :func:`_expression.text` - :meth:`.TextClause.columns` - primary creation interface. + :meth:`_expression.TextClause.columns` - primary creation interface. """ @@ -4562,18 +4751,23 @@ class TextualSelect(SelectBase): @HasMemoized.memoized_attribute def selected_columns(self): - """A :class:`.ColumnCollection` representing the columns that + """A :class:`_expression.ColumnCollection` + representing the columns that this SELECT statement or similar construct returns in its result set. - This collection differs from the :attr:`.FromClause.columns` collection - of a :class:`.FromClause` in that the columns within this collection + This collection differs from the + :attr:`_expression.FromClause.columns` collection + of a :class:`_expression.FromClause` + in that the columns within this collection cannot be directly nested inside another SELECT statement; a subquery must be applied first which provides for the necessary parenthesization required by SQL. - For a :class:`.TextualSelect` construct, the collection contains the - :class:`.ColumnElement` objects that were passed to the constructor, - typically via the :meth:`.TextClause.columns` method. + For a :class:`_expression.TextualSelect` construct, + the collection contains the + :class:`_expression.ColumnElement` + objects that were passed to the constructor, + typically via the :meth:`_expression.TextClause.columns` method. .. versionadded:: 1.4 diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py index 245b809aef..ba8a258211 100644 --- a/lib/sqlalchemy/sql/sqltypes.py +++ b/lib/sqlalchemy/sql/sqltypes.py @@ -210,7 +210,8 @@ class String(Concatenable, TypeEngine): In the vast majority of cases, the :class:`.Unicode` or :class:`.UnicodeText` datatypes should be used for a - :class:`.Column` that expects to store non-ascii data. These + :class:`_schema.Column` that expects to store non-ascii data. + These datatypes will ensure that the correct types are used on the database side as well as set up the correct Unicode behaviors under Python 2. @@ -218,7 +219,7 @@ class String(Concatenable, TypeEngine): .. seealso:: :paramref:`.create_engine.convert_unicode` - - :class:`.Engine`-wide parameter + :class:`_engine.Engine`-wide parameter :param unicode_error: Optional, a method to use to handle Unicode conversion errors. Behaves like the ``errors`` keyword argument to @@ -440,7 +441,7 @@ class UnicodeText(Text): """ Create a Unicode-converting Text type. - Parameters are the same as that of :class:`.Text`, + Parameters are the same as that of :class:`_expression.TextClause`, with the exception that ``convert_unicode`` defaults to ``True``. @@ -774,7 +775,7 @@ class DateTime(_LookupExpressionAdapter, TypeEngine): backends include additional options, such as timezone support and fractional seconds support. For fractional seconds, use the dialect-specific datatype, such as :class:`.mysql.TIME`. For - timezone support, use at least the :class:`~.types.TIMESTAMP` datatype, + timezone support, use at least the :class:`_types.TIMESTAMP` datatype, if not the dialect-specific datatype object. """ @@ -787,7 +788,7 @@ class DateTime(_LookupExpressionAdapter, TypeEngine): :param timezone: boolean. Indicates that the datetime type should enable timezone support, if available on the **base date/time-holding type only**. It is recommended - to make use of the :class:`~.types.TIMESTAMP` datatype directly when + to make use of the :class:`_types.TIMESTAMP` datatype directly when using this flag, as some databases include separate generic date/time-holding types distinct from the timezone-capable TIMESTAMP datatype, such as Oracle. @@ -980,7 +981,7 @@ class SchemaType(SchemaEventTarget): :meth:`.DDLEvents.before_parent_attach` and :meth:`.DDLEvents.after_parent_attach` events, where the events fire off surrounding the association of the type object with a parent - :class:`.Column`. + :class:`_schema.Column`. .. seealso:: @@ -1231,7 +1232,7 @@ class Enum(Emulated, String, SchemaType): .. seealso:: - :class:`.postgresql.ENUM` - PostgreSQL-specific type, + :class:`_postgresql.ENUM` - PostgreSQL-specific type, which has additional functionality. :class:`.mysql.ENUM` - MySQL-specific type @@ -1312,16 +1313,17 @@ class Enum(Emulated, String, SchemaType): The ``schema`` of the :class:`.Enum` type does not by default make use of the ``schema`` established on the - owning :class:`.Table`. If this behavior is desired, + owning :class:`_schema.Table`. If this behavior is desired, set the ``inherit_schema`` flag to ``True``. :param quote: Set explicit quoting preferences for the type's name. :param inherit_schema: When ``True``, the "schema" from the owning - :class:`.Table` will be copied to the "schema" attribute of this + :class:`_schema.Table` + will be copied to the "schema" attribute of this :class:`.Enum`, replacing whatever value was passed for the ``schema`` attribute. This also takes effect when using the - :meth:`.Table.tometadata` operation. + :meth:`_schema.Table.tometadata` operation. :param validate_strings: when True, string values that are being passed to the database in a SQL statement will be checked @@ -1935,7 +1937,8 @@ class Interval(Emulated, _AbstractInterval, TypeDecorator): class JSON(Indexable, TypeEngine): """Represent a SQL JSON type. - .. note:: :class:`.types.JSON` is provided as a facade for vendor-specific + .. note:: :class:`_types.JSON` + is provided as a facade for vendor-specific JSON types. Since it supports JSON SQL operations, it only works on backends that have an actual JSON type, currently: @@ -1945,10 +1948,10 @@ class JSON(Indexable, TypeEngine): * SQLite as of version 3.9 - :class:`.types.JSON` is part of the Core in support of the growing + :class:`_types.JSON` is part of the Core in support of the growing popularity of native JSON datatypes. - The :class:`.types.JSON` type stores arbitrary JSON format data, e.g.:: + The :class:`_types.JSON` type stores arbitrary JSON format data, e.g.:: data_table = Table('data_table', metadata, Column('id', Integer, primary_key=True), @@ -1963,7 +1966,8 @@ class JSON(Indexable, TypeEngine): **JSON-Specific Expression Operators** - The :class:`.types.JSON` datatype provides these additional SQL operations: + The :class:`_types.JSON` + datatype provides these additional SQL operations: * Keyed index operations:: @@ -1985,15 +1989,16 @@ class JSON(Indexable, TypeEngine): .. versionadded:: 1.3.11 Additional operations may be available from the dialect-specific versions - of :class:`.types.JSON`, such as :class:`.postgresql.JSON` and - :class:`.postgresql.JSONB` which both offer additional PostgreSQL-specific + of :class:`_types.JSON`, such as :class:`_postgresql.JSON` and + :class:`_postgresql.JSONB` which both offer additional PostgreSQL-specific operations. **Casting JSON Elements to Other Types** Index operations, i.e. those invoked by calling upon the expression using the Python bracket operator as in ``some_column['some key']``, return an - expression object whose type defaults to :class:`.JSON` by default, so that + expression object whose type defaults to :class:`_types.JSON` by default, + so that further JSON-oriented instructions may be called upon the result type. However, it is likely more common that an index operation is expected to return a specific scalar element, such as a string or integer. In @@ -2042,7 +2047,7 @@ class JSON(Indexable, TypeEngine): **Detecting Changes in JSON columns when using the ORM** - The :class:`.JSON` type, when used with the SQLAlchemy ORM, does not + The :class:`_types.JSON` type, when used with the SQLAlchemy ORM, does not detect in-place mutations to the structure. In order to detect these, the :mod:`sqlalchemy.ext.mutable` extension must be used. This extension will allow "in-place" changes to the datastructure to produce events which @@ -2051,7 +2056,8 @@ class JSON(Indexable, TypeEngine): **Support for JSON null vs. SQL NULL** - When working with NULL values, the :class:`.JSON` type recommends the + When working with NULL values, the :class:`_types.JSON` + type recommends the use of two specific constants in order to differentiate between a column that evaluates to SQL NULL, e.g. no value, vs. the JSON-encoded string of ``"null"``. To insert or select against a value that is SQL NULL, @@ -2061,23 +2067,24 @@ class JSON(Indexable, TypeEngine): conn.execute(table.insert(), json_value=null()) To insert or select against a value that is JSON ``"null"``, use the - constant :attr:`.JSON.NULL`:: + constant :attr:`_types.JSON.NULL`:: conn.execute(table.insert(), json_value=JSON.NULL) - The :class:`.JSON` type supports a flag - :paramref:`.JSON.none_as_null` which when set to True will result + The :class:`_types.JSON` type supports a flag + :paramref:`_types.JSON.none_as_null` which when set to True will result in the Python constant ``None`` evaluating to the value of SQL NULL, and when set to False results in the Python constant ``None`` evaluating to the value of JSON ``"null"``. The Python value ``None`` may be used in conjunction with either - :attr:`.JSON.NULL` and :func:`.null` in order to indicate NULL + :attr:`_types.JSON.NULL` and :func:`.null` in order to indicate NULL values, but care must be taken as to the value of the - :paramref:`.JSON.none_as_null` in these cases. + :paramref:`_types.JSON.none_as_null` in these cases. **Customizing the JSON Serializer** - The JSON serializer and deserializer used by :class:`.JSON` defaults to + The JSON serializer and deserializer used by :class:`_types.JSON` + defaults to Python's ``json.dumps`` and ``json.loads`` functions; in the case of the psycopg2 dialect, psycopg2 may be using its own custom loader function. @@ -2099,13 +2106,13 @@ class JSON(Indexable, TypeEngine): .. seealso:: - :class:`.postgresql.JSON` + :class:`_postgresql.JSON` - :class:`.postgresql.JSONB` + :class:`_postgresql.JSONB` :class:`.mysql.JSON` - :class:`.sqlite.JSON` + :class:`_sqlite.JSON` .. versionadded:: 1.1 @@ -2121,9 +2128,11 @@ class JSON(Indexable, TypeEngine): This value is used to force the JSON value of ``"null"`` to be used as the value. A value of Python ``None`` will be recognized either as SQL NULL or JSON ``"null"``, based on the setting - of the :paramref:`.JSON.none_as_null` flag; the :attr:`.JSON.NULL` + of the :paramref:`_types.JSON.none_as_null` flag; the + :attr:`_types.JSON.NULL` constant can be used to always resolve to JSON ``"null"`` regardless - of this setting. This is in contrast to the :func:`.sql.null` construct, + of this setting. This is in contrast to the :func:`_expression.null` + construct, which always resolves to SQL NULL. E.g.:: from sqlalchemy import null @@ -2139,15 +2148,16 @@ class JSON(Indexable, TypeEngine): session.commit() In order to set JSON NULL as a default value for a column, the most - transparent method is to use :func:`.text`:: + transparent method is to use :func:`_expression.text`:: Table( 'my_table', metadata, Column('json_data', JSON, default=text("'null'")) ) - While it is possible to use :attr:`.JSON.NULL` in this context, the - :attr:`.JSON.NULL` value will be returned as the value of the column, + While it is possible to use :attr:`_types.JSON.NULL` in this context, the + :attr:`_types.JSON.NULL` value will be returned as the value of the column + , which in the context of the ORM or other repurposing of the default value, may not be desirable. Using a SQL expression means the value will be re-fetched from the database within the context of retrieving @@ -2157,7 +2167,7 @@ class JSON(Indexable, TypeEngine): """ def __init__(self, none_as_null=False): - """Construct a :class:`.types.JSON` type. + """Construct a :class:`_types.JSON` type. :param none_as_null=False: if True, persist the value ``None`` as a SQL NULL value, not the JSON encoding of ``null``. Note that @@ -2169,9 +2179,9 @@ class JSON(Indexable, TypeEngine): .. note:: - :paramref:`.JSON.none_as_null` does **not** apply to the - values passed to :paramref:`.Column.default` and - :paramref:`.Column.server_default`; a value of ``None`` + :paramref:`_types.JSON.none_as_null` does **not** apply to the + values passed to :paramref:`_schema.Column.default` and + :paramref:`_schema.Column.server_default`; a value of ``None`` passed for these parameters means "no default present". .. seealso:: @@ -2236,7 +2246,7 @@ class JSON(Indexable, TypeEngine): """ class Comparator(Indexable.Comparator, Concatenable.Comparator): - """Define comparison operations for :class:`.types.JSON`.""" + """Define comparison operations for :class:`_types.JSON`.""" def _setup_getitem(self, index): if not isinstance(index, util.string_types) and isinstance( @@ -2366,7 +2376,7 @@ class JSON(Indexable, TypeEngine): @property def should_evaluate_none(self): - """Alias of :attr:`.JSON.none_as_null`""" + """Alias of :attr:`_types.JSON.none_as_null`""" return not self.none_as_null @should_evaluate_none.setter @@ -2417,17 +2427,18 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine): .. note:: This type serves as the basis for all ARRAY operations. However, currently **only the PostgreSQL backend has support for SQL arrays in SQLAlchemy**. It is recommended to use the - :class:`.postgresql.ARRAY` type directly when using ARRAY types + :class:`_postgresql.ARRAY` type directly when using ARRAY types with PostgreSQL, as it provides additional operators specific to that backend. - :class:`.types.ARRAY` is part of the Core in support of various SQL - standard functions such as :class:`.array_agg` which explicitly involve + :class:`_types.ARRAY` is part of the Core in support of various SQL + standard functions such as :class:`_functions.array_agg` + which explicitly involve arrays; however, with the exception of the PostgreSQL backend and possibly some third-party dialects, no other SQLAlchemy built-in dialect has support for this type. - An :class:`.types.ARRAY` type is constructed given the "type" + An :class:`_types.ARRAY` type is constructed given the "type" of element:: mytable = Table("mytable", metadata, @@ -2444,7 +2455,7 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine): data=[1,2,3] ) - The :class:`.types.ARRAY` type can be constructed given a fixed number + The :class:`_types.ARRAY` type can be constructed given a fixed number of dimensions:: mytable = Table("mytable", metadata, @@ -2470,10 +2481,10 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine): >>> expr = table.c.column[5] # returns ARRAY(Integer, dimensions=1) >>> expr = expr[6] # returns Integer - For 1-dimensional arrays, an :class:`.types.ARRAY` instance with no + For 1-dimensional arrays, an :class:`_types.ARRAY` instance with no dimension parameter will generally assume single-dimensional behaviors. - SQL expressions of type :class:`.types.ARRAY` have support for "index" and + SQL expressions of type :class:`_types.ARRAY` have support for "index" and "slice" behavior. The Python ``[]`` operator works normally here, given integer indexes or slices. Arrays default to 1-based indexing. The operator produces binary expression @@ -2482,7 +2493,8 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine): select([mytable.c.data[5], mytable.c.data[2:7]]) - as well as UPDATE statements when the :meth:`.Update.values` method + as well as UPDATE statements when the :meth:`_expression.Update.values` + method is used:: mytable.update().values({ @@ -2490,16 +2502,16 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine): mytable.c.data[2:7]: [1, 2, 3] }) - The :class:`.types.ARRAY` type also provides for the operators + The :class:`_types.ARRAY` type also provides for the operators :meth:`.types.ARRAY.Comparator.any` and :meth:`.types.ARRAY.Comparator.all`. The PostgreSQL-specific version of - :class:`.types.ARRAY` also provides additional operators. + :class:`_types.ARRAY` also provides additional operators. .. versionadded:: 1.1.0 .. seealso:: - :class:`.postgresql.ARRAY` + :class:`_postgresql.ARRAY` """ @@ -2511,7 +2523,7 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine): class Comparator(Indexable.Comparator, Concatenable.Comparator): - """Define comparison operations for :class:`.types.ARRAY`. + """Define comparison operations for :class:`_types.ARRAY`. More operators are available on the dialect-specific form of this type. See :class:`.postgresql.ARRAY.Comparator`. @@ -2586,7 +2598,7 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine): .. seealso:: - :func:`.sql.expression.any_` + :func:`_expression.any_` :meth:`.types.ARRAY.Comparator.all` @@ -2622,7 +2634,7 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine): .. seealso:: - :func:`.sql.expression.all_` + :func:`_expression.all_` :meth:`.types.ARRAY.Comparator.any` @@ -2639,7 +2651,7 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine): def __init__( self, item_type, as_tuple=False, dimensions=None, zero_indexes=False ): - """Construct an :class:`.types.ARRAY`. + """Construct an :class:`_types.ARRAY`. E.g.:: @@ -2662,7 +2674,7 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine): on the database, how it goes about interpreting Python and result values, as well as how expression behavior in conjunction with the "getitem" operator works. See the description at - :class:`.types.ARRAY` for additional detail. + :class:`_types.ARRAY` for additional detail. :param zero_indexes=False: when True, index values will be converted between Python zero-based and SQL one-based indexes, e.g. @@ -2764,7 +2776,7 @@ class TIMESTAMP(DateTime): """The SQL TIMESTAMP type. - :class:`~.types.TIMESTAMP` datatypes have support for timezone + :class:`_types.TIMESTAMP` datatypes have support for timezone storage on some backends, such as PostgreSQL and Oracle. Use the :paramref:`~types.TIMESTAMP.timezone` argument in order to enable "TIMESTAMP WITH TIMEZONE" for these backends. @@ -2774,7 +2786,7 @@ class TIMESTAMP(DateTime): __visit_name__ = "TIMESTAMP" def __init__(self, timezone=False): - """Construct a new :class:`.TIMESTAMP`. + """Construct a new :class:`_types.TIMESTAMP`. :param timezone: boolean. Indicates that the TIMESTAMP type should enable timezone support, if available on the target database. @@ -2895,7 +2907,8 @@ class NullType(TypeEngine): by the :class:`.Dialect` * When constructing SQL expressions using plain Python objects of unknown types (e.g. ``somecolumn == my_special_object``) - * When a new :class:`.Column` is created, and the given type is passed + * When a new :class:`_schema.Column` is created, + and the given type is passed as ``None`` or is not passed at all. The :class:`.NullType` can be used within SQL expression invocation @@ -2904,7 +2917,8 @@ class NullType(TypeEngine): :class:`.NullType` will result in a :exc:`.CompileError` if the compiler is asked to render the type itself, such as if it is used in a :func:`.cast` operation or within a schema creation operation such as that - invoked by :meth:`.MetaData.create_all` or the :class:`.CreateTable` + invoked by :meth:`_schema.MetaData.create_all` or the + :class:`.CreateTable` construct. """ diff --git a/lib/sqlalchemy/sql/traversals.py b/lib/sqlalchemy/sql/traversals.py index 032488826d..4a135538e9 100644 --- a/lib/sqlalchemy/sql/traversals.py +++ b/lib/sqlalchemy/sql/traversals.py @@ -165,7 +165,7 @@ class HasCacheKey(HasMemoized): each one; these bound parameters must be consulted in order to execute the statement with the correct parameters. - a :class:`.ClauseElement` structure that does not implement + a :class:`_expression.ClauseElement` structure that does not implement a :meth:`._gen_cache_key` method and does not implement a :attr:`.traverse_internals` attribute will not be cacheable; when such an element is embedded into a larger structure, this method diff --git a/lib/sqlalchemy/sql/type_api.py b/lib/sqlalchemy/sql/type_api.py index e9632c5023..ccda21e112 100644 --- a/lib/sqlalchemy/sql/type_api.py +++ b/lib/sqlalchemy/sql/type_api.py @@ -82,7 +82,8 @@ class TypeEngine(Traversible): This method determines the type of a resulting binary expression given two source types and an operator. For example, two - :class:`.Column` objects, both of the type :class:`.Integer`, will + :class:`_schema.Column` objects, both of the type + :class:`.Integer`, will produce a :class:`.BinaryExpression` that also has the type :class:`.Integer` when compared via the addition (``+``) operator. However, using the addition operator with an :class:`.Integer` @@ -116,7 +117,8 @@ class TypeEngine(Traversible): comparator_factory = Comparator """A :class:`.TypeEngine.Comparator` class which will apply - to operations performed by owning :class:`.ColumnElement` objects. + to operations performed by owning :class:`_expression.ColumnElement` + objects. The :attr:`.comparator_factory` attribute is a hook consulted by the core expression system when column and SQL expression operations @@ -195,14 +197,15 @@ class TypeEngine(Traversible): In all cases, the actual NULL SQL value can be always be persisted in any column by using - the :obj:`~.expression.null` SQL construct in an INSERT statement + the :obj:`_expression.null` SQL construct in an INSERT statement or associated with an ORM-mapped attribute. .. note:: The "evaluates none" flag does **not** apply to a value - of ``None`` passed to :paramref:`.Column.default` or - :paramref:`.Column.server_default`; in these cases, ``None`` + of ``None`` passed to :paramref:`_schema.Column.default` or + :paramref:`_schema.Column.server_default`; in these cases, + ``None`` still means "no default". .. versionadded:: 1.1 @@ -676,7 +679,7 @@ class UserDefinedType(util.with_metaclass(VisitableCheckKWArg, TypeEngine)): The ``get_col_spec()`` method will in most cases receive a keyword argument ``type_expression`` which refers to the owning expression - of the type as being compiled, such as a :class:`.Column` or + of the type as being compiled, such as a :class:`_schema.Column` or :func:`.cast` construct. This keyword is only sent if the method accepts keyword arguments (e.g. ``**kw``) in its argument signature; introspection is used to check for this in order to support legacy @@ -859,7 +862,7 @@ class TypeDecorator(SchemaEventTarget, TypeEngine): If the :class:`.TypeDecorator` is augmenting a type that requires special logic for certain types of operators, this method **must** be overridden. A key example is when decorating - the :class:`.postgresql.JSON` and :class:`.postgresql.JSONB` types; + the :class:`_postgresql.JSON` and :class:`_postgresql.JSONB` types; the default rules of :meth:`.TypeEngine.coerce_compared_value` should be used in order to deal with operators like index operations:: diff --git a/lib/sqlalchemy/sql/visitors.py b/lib/sqlalchemy/sql/visitors.py index 29ed013091..8f6bb2333d 100644 --- a/lib/sqlalchemy/sql/visitors.py +++ b/lib/sqlalchemy/sql/visitors.py @@ -228,35 +228,37 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)): """Visit a :class:`.HasCacheKey` object.""" dp_clauseelement = symbol("CE") - """Visit a :class:`.ClauseElement` object.""" + """Visit a :class:`_expression.ClauseElement` object.""" dp_fromclause_canonical_column_collection = symbol("FC") - """Visit a :class:`.FromClause` object in the context of the + """Visit a :class:`_expression.FromClause` object in the context of the ``columns`` attribute. The column collection is "canonical", meaning it is the originally defined location of the :class:`.ColumnClause` objects. Right now - this means that the object being visited is a :class:`.TableClause` - or :class:`.Table` object only. + this means that the object being visited is a + :class:`_expression.TableClause` + or :class:`_schema.Table` object only. """ dp_clauseelement_tuples = symbol("CT") - """Visit a list of tuples which contain :class:`.ClauseElement` + """Visit a list of tuples which contain :class:`_expression.ClauseElement` objects. """ dp_clauseelement_list = symbol("CL") - """Visit a list of :class:`.ClauseElement` objects. + """Visit a list of :class:`_expression.ClauseElement` objects. """ dp_clauseelement_unordered_set = symbol("CU") - """Visit an unordered set of :class:`.ClauseElement` objects. """ + """Visit an unordered set of :class:`_expression.ClauseElement` + objects. """ dp_fromclause_ordered_set = symbol("CO") - """Visit an ordered set of :class:`.FromClause` objects. """ + """Visit an ordered set of :class:`_expression.FromClause` objects. """ dp_string = symbol("S") """Visit a plain string value. @@ -320,7 +322,7 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)): """visit a dialect options structure.""" dp_string_clauseelement_dict = symbol("CD") - """Visit a dictionary of string keys to :class:`.ClauseElement` + """Visit a dictionary of string keys to :class:`_expression.ClauseElement` objects. """ @@ -361,18 +363,20 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)): """ dp_prefix_sequence = symbol("PS") - """Visit the sequence represented by :class:`.HasPrefixes` - or :class:`.HasSuffixes`. + """Visit the sequence represented by :class:`_expression.HasPrefixes` + or :class:`_expression.HasSuffixes`. """ dp_table_hint_list = symbol("TH") - """Visit the ``_hints`` collection of a :class:`.Select` object. + """Visit the ``_hints`` collection of a :class:`_expression.Select` object + . """ dp_statement_hint_list = symbol("SH") - """Visit the ``_statement_hints`` collection of a :class:`.Select` + """Visit the ``_statement_hints`` collection of a + :class:`_expression.Select` object. """ @@ -383,7 +387,8 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)): """ dp_dml_ordered_values = symbol("DML_OV") - """visit the values() ordered tuple list of an :class:`.Update` object.""" + """visit the values() ordered tuple list of an + :class:`_expression.Update` object.""" dp_dml_values = symbol("DML_V") """visit the values() dictionary of a :class:`.ValuesBase` @@ -393,7 +398,7 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)): dp_dml_multi_values = symbol("DML_MV") """visit the values() multi-valued list of dictionaries of an - :class:`~.sql.expression.Insert` object. + :class:`_expression.Insert` object. """ @@ -401,7 +406,7 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)): class ExtendedInternalTraversal(InternalTraversal): """defines additional symbols that are useful in caching applications. - Traversals for :class:`.ClauseElement` objects only need to use + Traversals for :class:`_expression.ClauseElement` objects only need to use those symbols present in :class:`.InternalTraversal`. However, for additional caching use cases within the ORM, symbols dealing with the :class:`.HasCacheKey` class are added here. @@ -570,14 +575,18 @@ def iterate(obj, opts): The central API feature used by the :func:`.visitors.iterate` and :func:`.visitors.iterate_depthfirst` functions is the - :meth:`.ClauseElement.get_children` method of :class:`.ClauseElement` - objects. This method should return all the :class:`.ClauseElement` objects - which are associated with a particular :class:`.ClauseElement` object. + :meth:`_expression.ClauseElement.get_children` method of + :class:`_expression.ClauseElement` + objects. This method should return all the + :class:`_expression.ClauseElement` objects + which are associated with a particular :class:`_expression.ClauseElement` + object. For example, a :class:`.Case` structure will refer to a series of - :class:`.ColumnElement` objects within its "whens" and "else\_" member + :class:`_expression.ColumnElement` + objects within its "whens" and "else\_" member variables. - :param obj: :class:`.ClauseElement` structure to be traversed + :param obj: :class:`_expression.ClauseElement` structure to be traversed :param opts: dictionary of iteration options. This dictionary is usually empty in modern usage. @@ -603,7 +612,7 @@ def iterate_depthfirst(obj, opts): traversal is configured to be depth-first. - :param obj: :class:`.ClauseElement` structure to be traversed + :param obj: :class:`_expression.ClauseElement` structure to be traversed :param opts: dictionary of iteration options. This dictionary is usually empty in modern usage. @@ -637,11 +646,13 @@ def traverse_using(iterator, obj, visitors): functions. :param iterator: an iterable or sequence which will yield - :class:`.ClauseElement` structures; the iterator is assumed to be the + :class:`_expression.ClauseElement` + structures; the iterator is assumed to be the product of the :func:`.visitors.iterate` or :func:`.visitors.iterate_depthfirst` functions. - :param obj: the :class:`.ClauseElement` that was used as the target of the + :param obj: the :class:`_expression.ClauseElement` + that was used as the target of the :func:`.iterate` or :func:`.iterate_depthfirst` function. :param visitors: dictionary of visit functions. See :func:`.traverse` @@ -679,7 +690,7 @@ def traverse(obj, opts, visitors): The iteration of objects uses the :func:`.visitors.iterate` function, which does a breadth-first traversal using a stack. - :param obj: :class:`.ClauseElement` structure to be traversed + :param obj: :class:`_expression.ClauseElement` structure to be traversed :param opts: dictionary of iteration options. This dictionary is usually empty in modern usage. @@ -718,9 +729,12 @@ def cloned_traverse(obj, opts, visitors): The central API feature used by the :func:`.visitors.cloned_traverse` and :func:`.visitors.replacement_traverse` functions, in addition to the - :meth:`.ClauseElement.get_children` function that is used to achieve - the iteration, is the :meth:`.ClauseElement._copy_internals` method. - For a :class:`.ClauseElement` structure to support cloning and replacement + :meth:`_expression.ClauseElement.get_children` + function that is used to achieve + the iteration, is the :meth:`_expression.ClauseElement._copy_internals` + method. + For a :class:`_expression.ClauseElement` + structure to support cloning and replacement traversals correctly, it needs to be able to pass a cloning function into its internal members in order to make copies of them.