From: Mike Bayer Date: Tue, 15 Jan 2019 21:12:39 +0000 (-0500) Subject: Convert most "See also" phrases into .. seealso:: X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=aebf88802f0cb1f8c527561101d583788374ca71;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 95b69ed3ea..ba73cb105c 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -586,14 +586,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: @@ -616,8 +616,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() @@ -640,8 +644,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` """ @@ -1497,7 +1504,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 @@ -1578,8 +1585,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 @@ -1730,11 +1742,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` """ @@ -2009,7 +2021,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 cd7db41107..446681cbe8 100644 --- a/lib/sqlalchemy/events.py +++ b/lib/sqlalchemy/events.py @@ -77,8 +77,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` @@ -652,9 +651,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` """ @@ -704,11 +703,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 77e4a4366a..fa56b50d3b 100644 --- a/lib/sqlalchemy/orm/descriptor_props.py +++ b/lib/sqlalchemy/orm/descriptor_props.py @@ -388,15 +388,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 7123660351..2dd9d3650e 100644 --- a/lib/sqlalchemy/orm/interfaces.py +++ b/lib/sqlalchemy/orm/interfaces.py @@ -316,19 +316,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 8820f6a8e8..3cde8484f2 100644 --- a/lib/sqlalchemy/orm/properties.py +++ b/lib/sqlalchemy/orm/properties.py @@ -226,15 +226,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 144cbc0eb0..efe326dc5f 100644 --- a/lib/sqlalchemy/orm/relationships.py +++ b/lib/sqlalchemy/orm/relationships.py @@ -78,9 +78,9 @@ class RelationshipProperty(StrategizedProperty): Public constructor is the :func:`.orm.relationship` function. - See also: + .. seealso:: - :ref:`relationship_config_toplevel` + :ref:`relationship_config_toplevel` """ @@ -867,17 +867,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 af7db9b317..05d03bfd89 100644 --- a/lib/sqlalchemy/pool.py +++ b/lib/sqlalchemy/pool.py @@ -377,7 +377,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 6e63eb285b..b5512ead10 100644 --- a/lib/sqlalchemy/sql/operators.py +++ b/lib/sqlalchemy/sql/operators.py @@ -257,15 +257,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 b2b97d690a..24796b4740 100644 --- a/lib/sqlalchemy/sql/sqltypes.py +++ b/lib/sqlalchemy/sql/sqltypes.py @@ -343,7 +343,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 e6fba2b152..5404c8de6e 100644 --- a/lib/sqlalchemy/sql/type_api.py +++ b/lib/sqlalchemy/sql/type_api.py @@ -292,9 +292,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` """ @@ -331,9 +331,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