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_3_0b2~26 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=26a8e46527b6443839044855a920ec1f298b03c8;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 d5b3916b7d..45600928fa 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 d2eb4f644f..02eed516b2 100644 --- a/lib/sqlalchemy/orm/interfaces.py +++ b/lib/sqlalchemy/orm/interfaces.py @@ -341,19 +341,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 f7e9434485..328c9b1b4e 100644 --- a/lib/sqlalchemy/orm/properties.py +++ b/lib/sqlalchemy/orm/properties.py @@ -268,15 +268,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 c3e98c0c98..af4d9a7825 100644 --- a/lib/sqlalchemy/orm/relationships.py +++ b/lib/sqlalchemy/orm/relationships.py @@ -95,9 +95,9 @@ class RelationshipProperty(StrategizedProperty): Public constructor is the :func:`.orm.relationship` function. - See also: + .. seealso:: - :ref:`relationship_config_toplevel` + :ref:`relationship_config_toplevel` """ @@ -904,17 +904,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/base.py b/lib/sqlalchemy/pool/base.py index 601c5f48a7..15ac495617 100644 --- a/lib/sqlalchemy/pool/base.py +++ b/lib/sqlalchemy/pool/base.py @@ -358,7 +358,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 5a29d2ce8f..7277787e2b 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 2c0a03123b..1d97bf35c5 100644 --- a/lib/sqlalchemy/sql/sqltypes.py +++ b/lib/sqlalchemy/sql/sqltypes.py @@ -377,7 +377,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 a283b60dc1..2c01484ebf 100644 --- a/lib/sqlalchemy/sql/type_api.py +++ b/lib/sqlalchemy/sql/type_api.py @@ -296,9 +296,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` """ @@ -337,9 +337,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