From: Mike Bayer Date: Tue, 15 Jan 2019 21:12:39 +0000 (-0500) Subject: Convert most "See also" phrases into .. seealso:: X-Git-Tag: rel_1_2_17~12 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3ad2966da2fdf6cb5f86a6328f9c81631d62ed60;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git Convert most "See also" phrases into .. seealso:: Change-Id: Ie32598b895c1c5f5bce7c8e1573abbcfe9d434a8 (cherry picked from commit e81d3815abb36c52b0019dee6e4f67990e3d1c7d) --- diff --git a/doc/build/orm/mapping_columns.rst b/doc/build/orm/mapping_columns.rst index 4b31b92102..e076923885 100644 --- a/doc/build/orm/mapping_columns.rst +++ b/doc/build/orm/mapping_columns.rst @@ -207,16 +207,18 @@ should be included or excluded:: .. note:: - insert and update defaults configured on individual - :class:`.Column` objects, i.e. those described at :ref:`metadata_defaults` - including those configured by the ``default``, ``update``, - ``server_default`` and ``server_onupdate`` arguments, will continue to - function normally even if those :class:`.Column` objects are not mapped. - This is because in the case of ``default`` and ``update``, the - :class:`.Column` object is still present on the underlying - :class:`.Table`, thus allowing the default functions to take place when - the ORM emits an INSERT or UPDATE, and in the case of ``server_default`` - and ``server_onupdate``, the relational database itself maintains these - functions. + insert and update defaults configured on individual :class:`.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 + take place when the ORM emits an INSERT or UPDATE, and in the case of + :paramref:`.Column.server_default` and :paramref:`.Column.server_onupdate`, + the relational database itself emits these defaults as a server side + behavior. diff --git a/doc/build/orm/session_basics.rst b/doc/build/orm/session_basics.rst index 6f3500abbb..4547e12436 100644 --- a/doc/build/orm/session_basics.rst +++ b/doc/build/orm/session_basics.rst @@ -664,7 +664,9 @@ it will be deleted on flush:: some_user.preference = None session.flush() # will delete the Preference object -See also :ref:`unitofwork_cascades` for detail on cascades. +.. seealso:: + + :ref:`unitofwork_cascades` for detail on cascades. Deleting based on Filter Criterion diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index 2b7c3f86e4..91accd9ec8 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -609,14 +609,14 @@ class Connection(Connectable): :class:`.Transaction` objects will roll back the transaction. - See also: + .. seealso:: - :meth:`.Connection.begin_nested` - use a SAVEPOINT + :meth:`.Connection.begin_nested` - use a SAVEPOINT - :meth:`.Connection.begin_twophase` - use a two phase /XID transaction + :meth:`.Connection.begin_twophase` - use a two phase /XID transaction - :meth:`.Engine.begin` - context manager available from - :class:`.Engine`. + :meth:`.Engine.begin` - context manager available from + :class:`.Engine` """ if self.__branch_from: @@ -639,8 +639,12 @@ class Connection(Connectable): still controls the overall ``commit`` or ``rollback`` of the transaction of a whole. - See also :meth:`.Connection.begin`, - :meth:`.Connection.begin_twophase`. + .. seealso:: + + :meth:`.Connection.begin` + + :meth:`.Connection.begin_twophase` + """ if self.__branch_from: return self.__branch_from.begin_nested() @@ -663,8 +667,11 @@ class Connection(Connectable): :param xid: the two phase transaction id. If not supplied, a random id will be generated. - See also :meth:`.Connection.begin`, - :meth:`.Connection.begin_twophase`. + .. seealso:: + + :meth:`.Connection.begin` + + :meth:`.Connection.begin_twophase` """ @@ -1553,7 +1560,7 @@ class Connection(Connectable): with engine.begin() as conn: conn.execute("some statement", {'x':5, 'y':10}) - See also: + .. seealso:: :meth:`.Engine.begin` - engine-level transactional context @@ -1643,8 +1650,13 @@ class Transaction(object): The Transaction object is **not** threadsafe. - See also: :meth:`.Connection.begin`, :meth:`.Connection.begin_twophase`, - :meth:`.Connection.begin_nested`. + .. seealso:: + + :meth:`.Connection.begin` + + :meth:`.Connection.begin_twophase` + + :meth:`.Connection.begin_nested` .. index:: single: thread safety; Transaction @@ -1797,11 +1809,11 @@ class Engine(Connectable, log.Identified): An :class:`.Engine` object is instantiated publicly using the :func:`~sqlalchemy.create_engine` function. - See also: + .. seealso:: - :doc:`/core/engines` + :doc:`/core/engines` - :ref:`connections_toplevel` + :ref:`connections_toplevel` """ @@ -2082,7 +2094,7 @@ class Engine(Connectable, log.Identified): with engine.begin() as conn: conn.execute("some statement", {'x':5, 'y':10}) - See also: + .. seealso:: :meth:`.Engine.begin` - engine-level transactional context diff --git a/lib/sqlalchemy/events.py b/lib/sqlalchemy/events.py index c1b6f3740b..5eb84a1564 100644 --- a/lib/sqlalchemy/events.py +++ b/lib/sqlalchemy/events.py @@ -80,8 +80,7 @@ class DDLEvents(event.Events): The above :class:`.DDL` object will also be associated with the :class:`.Table` object represented by ``new_table``. - - See also: + .. seealso:: :ref:`event_toplevel` @@ -669,9 +668,9 @@ class ConnectionEvents(event.Events): :param multiparams: Multiple parameter sets, a list of dictionaries. :param params: Single parameter set, a single dictionary. - See also: + .. seealso:: - :meth:`.before_cursor_execute` + :meth:`.before_cursor_execute` """ @@ -722,11 +721,11 @@ class ConnectionEvents(event.Events): :param executemany: boolean, if ``True``, this is an ``executemany()`` call, if ``False``, this is an ``execute()`` call. - See also: + .. seealso:: - :meth:`.before_execute` + :meth:`.before_execute` - :meth:`.after_cursor_execute` + :meth:`.after_cursor_execute` """ diff --git a/lib/sqlalchemy/orm/descriptor_props.py b/lib/sqlalchemy/orm/descriptor_props.py index f9d955f85e..edb61b4273 100644 --- a/lib/sqlalchemy/orm/descriptor_props.py +++ b/lib/sqlalchemy/orm/descriptor_props.py @@ -393,15 +393,15 @@ class CompositeProperty(DescriptorProperty): See the example in :ref:`composite_operations` for an overview of usage , as well as the documentation for :class:`.PropComparator`. - See also: + .. seealso:: - :class:`.PropComparator` + :class:`.PropComparator` - :class:`.ColumnOperators` + :class:`.ColumnOperators` - :ref:`types_operators` + :ref:`types_operators` - :attr:`.TypeEngine.comparator_factory` + :attr:`.TypeEngine.comparator_factory` """ diff --git a/lib/sqlalchemy/orm/interfaces.py b/lib/sqlalchemy/orm/interfaces.py index aac14669c1..a93c0d1605 100644 --- a/lib/sqlalchemy/orm/interfaces.py +++ b/lib/sqlalchemy/orm/interfaces.py @@ -338,19 +338,19 @@ class PropComparator(operators.ColumnOperators): :attr:`.TypeEngine.comparator_factory` attribute. See :ref:`types_operators` for more detail. - See also: + .. seealso:: - :class:`.ColumnProperty.Comparator` + :class:`.ColumnProperty.Comparator` - :class:`.RelationshipProperty.Comparator` + :class:`.RelationshipProperty.Comparator` - :class:`.CompositeProperty.Comparator` + :class:`.CompositeProperty.Comparator` - :class:`.ColumnOperators` + :class:`.ColumnOperators` - :ref:`types_operators` + :ref:`types_operators` - :attr:`.TypeEngine.comparator_factory` + :attr:`.TypeEngine.comparator_factory` """ diff --git a/lib/sqlalchemy/orm/properties.py b/lib/sqlalchemy/orm/properties.py index c06b43918d..d0305509e2 100644 --- a/lib/sqlalchemy/orm/properties.py +++ b/lib/sqlalchemy/orm/properties.py @@ -260,15 +260,15 @@ class ColumnProperty(StrategizedProperty): See the documentation for :class:`.PropComparator` for a brief overview. - See also: + .. seealso:: - :class:`.PropComparator` + :class:`.PropComparator` - :class:`.ColumnOperators` + :class:`.ColumnOperators` - :ref:`types_operators` + :ref:`types_operators` - :attr:`.TypeEngine.comparator_factory` + :attr:`.TypeEngine.comparator_factory` """ diff --git a/lib/sqlalchemy/orm/relationships.py b/lib/sqlalchemy/orm/relationships.py index 046e7d4ee9..ff8b679e48 100644 --- a/lib/sqlalchemy/orm/relationships.py +++ b/lib/sqlalchemy/orm/relationships.py @@ -94,9 +94,9 @@ class RelationshipProperty(StrategizedProperty): Public constructor is the :func:`.orm.relationship` function. - See also: + .. seealso:: - :ref:`relationship_config_toplevel` + :ref:`relationship_config_toplevel` """ @@ -894,17 +894,17 @@ class RelationshipProperty(StrategizedProperty): See the documentation for :class:`.PropComparator` for a brief overview of ORM level operator definition. - See also: + .. seealso:: - :class:`.PropComparator` + :class:`.PropComparator` - :class:`.ColumnProperty.Comparator` + :class:`.ColumnProperty.Comparator` - :class:`.ColumnOperators` + :class:`.ColumnOperators` - :ref:`types_operators` + :ref:`types_operators` - :attr:`.TypeEngine.comparator_factory` + :attr:`.TypeEngine.comparator_factory` """ diff --git a/lib/sqlalchemy/pool.py b/lib/sqlalchemy/pool.py index f8d46b21f1..df714f0162 100644 --- a/lib/sqlalchemy/pool.py +++ b/lib/sqlalchemy/pool.py @@ -405,7 +405,9 @@ class Pool(log.Identified): remaining open, as it only affects connections that are idle in the pool. - See also the :meth:`Pool.recreate` method. + .. seealso:: + + :meth:`Pool.recreate` """ diff --git a/lib/sqlalchemy/sql/operators.py b/lib/sqlalchemy/sql/operators.py index f202cf3532..f36fb6d340 100644 --- a/lib/sqlalchemy/sql/operators.py +++ b/lib/sqlalchemy/sql/operators.py @@ -320,15 +320,15 @@ class ColumnOperators(Operators): so that the ``==`` operation above is replaced by a clause construct. - See also: + .. seealso:: - :ref:`types_operators` + :ref:`types_operators` - :attr:`.TypeEngine.comparator_factory` + :attr:`.TypeEngine.comparator_factory` - :class:`.ColumnOperators` + :class:`.ColumnOperators` - :class:`.PropComparator` + :class:`.PropComparator` """ diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py index 4428bb8f9c..eb9d2c2f43 100644 --- a/lib/sqlalchemy/sql/sqltypes.py +++ b/lib/sqlalchemy/sql/sqltypes.py @@ -376,7 +376,7 @@ class Unicode(String): unicode. The recipe at :ref:`coerce_to_unicode` illustrates how this is done. - See also: + .. seealso:: :class:`.UnicodeText` - unlengthed textual counterpart to :class:`.Unicode`. diff --git a/lib/sqlalchemy/sql/type_api.py b/lib/sqlalchemy/sql/type_api.py index baa41e6f1b..4a4d20f364 100644 --- a/lib/sqlalchemy/sql/type_api.py +++ b/lib/sqlalchemy/sql/type_api.py @@ -295,9 +295,9 @@ class TypeEngine(Visitable): The method is evaluated at statement compile time, as opposed to statement construction time. - See also: + .. seealso:: - :ref:`types_sql_value_processing` + :ref:`types_sql_value_processing` """ @@ -336,9 +336,9 @@ class TypeEngine(Visitable): may be used in an executemany() call against an arbitrary number of bound parameter sets. - See also: + .. seealso:: - :ref:`types_sql_value_processing` + :ref:`types_sql_value_processing` """ return None