From 68f6951019dce746a0d093ee597e89d68f4d8fc0 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Sun, 25 Dec 2011 17:34:24 -0500 Subject: [PATCH] fix a whole bunch of note:: / warning:: that were inline, no longer compatible with docutils 0.8 --- doc/build/core/connections.rst | 4 ++- doc/build/core/engines.rst | 27 +++++++++------- doc/build/core/tutorial.rst | 8 +++-- doc/build/intro.rst | 8 +++-- doc/build/orm/collections.rst | 4 ++- doc/build/orm/inheritance.rst | 4 ++- doc/build/orm/mapper_config.rst | 24 +++++++------- doc/build/orm/relationships.rst | 4 ++- doc/build/orm/session.rst | 4 ++- lib/sqlalchemy/dialects/mysql/base.py | 4 ++- lib/sqlalchemy/dialects/postgresql/base.py | 4 ++- lib/sqlalchemy/dialects/sqlite/pysqlite.py | 10 +++--- lib/sqlalchemy/ext/declarative.py | 8 +++-- lib/sqlalchemy/ext/mutable.py | 12 +++++-- lib/sqlalchemy/ext/orderinglist.py | 4 ++- lib/sqlalchemy/ext/sqlsoup.py | 10 ++++-- lib/sqlalchemy/interfaces.py | 8 +++-- lib/sqlalchemy/orm/__init__.py | 36 ++++++++++++++------- lib/sqlalchemy/orm/deprecated_interfaces.py | 12 +++++-- lib/sqlalchemy/orm/query.py | 4 ++- lib/sqlalchemy/orm/session.py | 4 ++- lib/sqlalchemy/sql/expression.py | 12 ++++--- lib/sqlalchemy/types.py | 32 ++++++++++++------ lib/sqlalchemy/util/langhelpers.py | 4 ++- 24 files changed, 169 insertions(+), 82 deletions(-) diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst index 15b87cbae0..9f9a8f07d2 100644 --- a/doc/build/core/connections.rst +++ b/doc/build/core/connections.rst @@ -105,7 +105,9 @@ in :ref:`sqlexpression_toplevel`. Using Transactions ================== -.. note:: This section describes how to use transactions when working directly +.. note:: + + This section describes how to use transactions when working directly with :class:`.Engine` and :class:`.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` diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst index bfcf92bad6..7e315c1a74 100644 --- a/doc/build/core/engines.rst +++ b/doc/build/core/engines.rst @@ -228,8 +228,10 @@ connection pool, it follows that you should keep a single :class:`.Engine` per database established within an application, rather than creating a new one for each connection. -.. note:: :class:`.QueuePool` is not used by default for SQLite engines. See - :ref:`sqlite_toplevel` for details on SQLite connection pool usage. +.. note:: + + :class:`.QueuePool` is not used by default for SQLite engines. See + :ref:`sqlite_toplevel` for details on SQLite connection pool usage. .. autoclass:: sqlalchemy.engine.url.URL :members: @@ -323,13 +325,14 @@ string. To set this to a specific name, use the "logging_name" and "pool_logging_name" keyword arguments with :func:`sqlalchemy.create_engine`. .. note:: - The SQLAlchemy :class:`.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:`~.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` - is procured (in the case of :class:`~.orm.session.Session`, this is - after the current transaction ends and a new one begins). + + The SQLAlchemy :class:`.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:`~.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` + 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/tutorial.rst b/doc/build/core/tutorial.rst index c2dc927574..49029e67ff 100644 --- a/doc/build/core/tutorial.rst +++ b/doc/build/core/tutorial.rst @@ -150,7 +150,9 @@ each table first before creating, so it's safe to call multiple times: () COMMIT -.. note:: Users familiar with the syntax of CREATE TABLE may notice that the +.. note:: + + Users familiar with the syntax of CREATE TABLE may notice that the VARCHAR columns were generated without a length; on SQLite and Postgresql, this is a valid datatype, but on others, it's not allowed. So if running this tutorial on one of those databases, and you wish to use SQLAlchemy to @@ -1511,7 +1513,9 @@ table, or the same table: Multiple Table Updates ---------------------- -.. note:: This feature is new as of version 0.7.4. +.. note:: + + This feature is new as of version 0.7.4. The Postgresql, Microsoft SQL Server, and MySQL backends all support UPDATE statements that refer to multiple tables. For PG and MSSQL, this is the "UPDATE FROM" syntax, diff --git a/doc/build/intro.rst b/doc/build/intro.rst index 52180a91bb..b5020b6ee3 100644 --- a/doc/build/intro.rst +++ b/doc/build/intro.rst @@ -99,7 +99,9 @@ SQLAlchemy supports installation using standard Python "distutils" or rides on top of ``setuptools`` or ``distribute``, replacing the usage of ``easy_install``. It is often preferred for its simpler mode of usage. -.. note:: It is strongly recommended that either ``setuptools`` or ``distribute`` be installed. +.. note:: + + It is strongly recommended that either ``setuptools`` or ``distribute`` be installed. Python's built-in ``distutils`` lacks many widely used installation features. Install via easy_install or pip @@ -141,7 +143,9 @@ pass the flag ``--without-cextensions`` to the ``setup.py`` script:: python setup.py --without-cextensions install -.. note:: The ``--without-cextensions`` flag is available **only** if ``setuptools`` +.. note:: + + The ``--without-cextensions`` flag is available **only** if ``setuptools`` or ``distribute`` is installed. It is not available on a plain Python ``distutils`` installation. The library will still install without the C extensions if they cannot be built, however. diff --git a/doc/build/orm/collections.rst b/doc/build/orm/collections.rst index 6491332f6b..4e0d660917 100644 --- a/doc/build/orm/collections.rst +++ b/doc/build/orm/collections.rst @@ -79,7 +79,9 @@ function in conjunction with ``lazy='dynamic'``:: Note that eager/lazy loading options cannot be used in conjunction dynamic relationships at this time. -.. note:: The :func:`~.orm.dynamic_loader` function is essentially the same +.. note:: + + The :func:`~.orm.dynamic_loader` function is essentially the same as :func:`~.orm.relationship` with the ``lazy='dynamic'`` argument specified. diff --git a/doc/build/orm/inheritance.rst b/doc/build/orm/inheritance.rst index 8d73ceecab..4713f32890 100644 --- a/doc/build/orm/inheritance.rst +++ b/doc/build/orm/inheritance.rst @@ -15,7 +15,9 @@ When mappers are configured in an inheritance relationship, SQLAlchemy has the ability to load elements "polymorphically", meaning that a single query can return objects of multiple types. -.. note:: This section currently uses classical mappings to illustrate inheritance +.. note:: + + This section currently uses classical mappings to illustrate inheritance configurations, and will soon be updated to standardize on Declarative. Until then, please refer to :ref:`declarative_inheritance` for information on how common inheritance mappings are constructed declaratively. diff --git a/doc/build/orm/mapper_config.rst b/doc/build/orm/mapper_config.rst index 118b52f046..407930ad0d 100644 --- a/doc/build/orm/mapper_config.rst +++ b/doc/build/orm/mapper_config.rst @@ -241,17 +241,19 @@ should be included or excluded:: 'primary_key' : [user_table.c.id] } -.. 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. +.. 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. .. _deferred: diff --git a/doc/build/orm/relationships.rst b/doc/build/orm/relationships.rst index f4c43fbc51..6bfd01edd8 100644 --- a/doc/build/orm/relationships.rst +++ b/doc/build/orm/relationships.rst @@ -248,7 +248,9 @@ extension allows the configuration of attributes which will access two "hops" with a single access, one "hop" to the associated object, and a second to a target attribute. -.. note:: When using the association object pattern, it is +.. note:: + + When using the association object pattern, it is advisable that the association-mapped table not be used as the ``secondary`` argument on a :func:`.relationship` elsewhere, unless that :func:`.relationship` contains diff --git a/doc/build/orm/session.rst b/doc/build/orm/session.rst index a41d514f2b..1c1189507b 100644 --- a/doc/build/orm/session.rst +++ b/doc/build/orm/session.rst @@ -705,7 +705,9 @@ is that a "transaction" is always present; this behavior can be disabled by setting ``autocommit=True``. In autocommit mode, a transaction can be initiated by calling the :func:`~sqlalchemy.orm.session.Session.begin` method. -.. note:: The term "transaction" here refers to a transactional +.. note:: + + The term "transaction" here refers to a transactional construct within the :class:`.Session` itself which may be maintaining zero or more actual database (DBAPI) transactions. An individual DBAPI connection begins participation in the "transaction" as it is first diff --git a/lib/sqlalchemy/dialects/mysql/base.py b/lib/sqlalchemy/dialects/mysql/base.py index 2261802473..b7683581cf 100644 --- a/lib/sqlalchemy/dialects/mysql/base.py +++ b/lib/sqlalchemy/dialects/mysql/base.py @@ -1252,7 +1252,9 @@ class MySQLCompiler(compiler.SQLCompiler): def get_select_precolumns(self, select): """Add special MySQL keywords in place of DISTINCT. - .. note:: this usage is deprecated. :meth:`.Select.prefix_with` + .. note:: + + this usage is deprecated. :meth:`.Select.prefix_with` should be used for special keywords at the start of a SELECT. diff --git a/lib/sqlalchemy/dialects/postgresql/base.py b/lib/sqlalchemy/dialects/postgresql/base.py index 673b86add2..ba6f61b40a 100644 --- a/lib/sqlalchemy/dialects/postgresql/base.py +++ b/lib/sqlalchemy/dialects/postgresql/base.py @@ -342,7 +342,9 @@ class ARRAY(sqltypes.MutableType, sqltypes.Concatenable, sqltypes.TypeEngine): performance implications (default changed from ``True`` in 0.7.0). - .. note:: This functionality is now superseded by the + .. note:: + + This functionality is now superseded by the ``sqlalchemy.ext.mutable`` extension described in :ref:`mutable_toplevel`. diff --git a/lib/sqlalchemy/dialects/sqlite/pysqlite.py b/lib/sqlalchemy/dialects/sqlite/pysqlite.py index 63832b8f37..7247168317 100644 --- a/lib/sqlalchemy/dialects/sqlite/pysqlite.py +++ b/lib/sqlalchemy/dialects/sqlite/pysqlite.py @@ -118,10 +118,12 @@ SQLAlchemy sets up pooling to work with Pysqlite's default behavior: prevents a connection from being used again in a different thread and works best with SQLite's coarse-grained file locking. - .. note:: The default selection of :class:`.NullPool` for SQLite file-based databases - is new in SQLAlchemy 0.7. Previous versions - select :class:`.SingletonThreadPool` by - default for all SQLite databases. + .. note:: + + The default selection of :class:`.NullPool` for SQLite file-based databases + is new in SQLAlchemy 0.7. Previous versions + select :class:`.SingletonThreadPool` by + default for all SQLite databases. Modern versions of SQLite no longer have the threading restrictions, and assuming the sqlite3/pysqlite library was built with SQLite's default threading mode diff --git a/lib/sqlalchemy/ext/declarative.py b/lib/sqlalchemy/ext/declarative.py index ffbdfaae99..91d770197c 100755 --- a/lib/sqlalchemy/ext/declarative.py +++ b/lib/sqlalchemy/ext/declarative.py @@ -1424,9 +1424,11 @@ class declared_attr(property): """Mark a class-level method as representing the definition of a mapped property or special declarative member name. - .. note:: @declared_attr is available as - ``sqlalchemy.util.classproperty`` for SQLAlchemy versions - 0.6.2, 0.6.3, 0.6.4. + .. note:: + + @declared_attr is available as + ``sqlalchemy.util.classproperty`` for SQLAlchemy versions + 0.6.2, 0.6.3, 0.6.4. @declared_attr turns the attribute into a scalar-like property that can be invoked from the uninstantiated class. diff --git a/lib/sqlalchemy/ext/mutable.py b/lib/sqlalchemy/ext/mutable.py index ece7e3ad48..8f14f51974 100644 --- a/lib/sqlalchemy/ext/mutable.py +++ b/lib/sqlalchemy/ext/mutable.py @@ -448,7 +448,9 @@ class Mutable(MutableBase): This is a convenience method that calls ``associate_with_attribute`` automatically. - .. warning:: The listeners established by this method are *global* + .. warning:: + + The listeners established by this method are *global* to all mappers, and are *not* garbage collected. Only use :meth:`.associate_with` for types that are permanent to an application, not with ad-hoc types else this will cause unbounded growth @@ -488,7 +490,9 @@ class Mutable(MutableBase): of the particular :meth:`.Mutable` subclass to establish a global association. - .. warning:: The listeners established by this method are *global* + .. warning:: + + The listeners established by this method are *global* to all mappers, and are *not* garbage collected. Only use :meth:`.as_mutable` for types that are permanent to an application, not with ad-hoc types else this will cause unbounded growth @@ -519,7 +523,9 @@ class MutableComposite(MutableBase): See the example in :ref:`mutable_composites` for usage information. - .. warning:: The listeners established by the :class:`.MutableComposite` + .. warning:: + + The listeners established by the :class:`.MutableComposite` class are *global* to all mappers, and are *not* garbage collected. Only use :class:`.MutableComposite` for types that are permanent to an application, not with ad-hoc types else this will cause unbounded growth diff --git a/lib/sqlalchemy/ext/orderinglist.py b/lib/sqlalchemy/ext/orderinglist.py index ce63b88eae..ba505eb7b7 100644 --- a/lib/sqlalchemy/ext/orderinglist.py +++ b/lib/sqlalchemy/ext/orderinglist.py @@ -73,7 +73,9 @@ Use the ``ordering_list`` function to set up the ``collection_class`` on relatio (as in the mapper example above). This implementation depends on the list starting in the proper order, so be SURE to put an order_by on your relationship. -.. warning:: ``ordering_list`` only provides limited functionality when a primary +.. warning:: + + ``ordering_list`` only provides limited functionality when a primary key column or unique column is the target of the sort. Since changing the order of entries often means that two rows must trade values, this is not possible when the value is constrained by a primary key or unique constraint, since one of the rows diff --git a/lib/sqlalchemy/ext/sqlsoup.py b/lib/sqlalchemy/ext/sqlsoup.py index fe2f741373..189aa1af1e 100644 --- a/lib/sqlalchemy/ext/sqlsoup.py +++ b/lib/sqlalchemy/ext/sqlsoup.py @@ -6,7 +6,9 @@ """ -.. note:: SQLSoup will no longer be included with SQLAlchemy as of 0.8. +.. note:: + + SQLSoup will no longer be included with SQLAlchemy as of 0.8. Look for a third party project replicating its functionality soon. @@ -250,8 +252,10 @@ Advanced Use Sessions, Transations and Application Integration ------------------------------------------------- -**Note:** please read and understand this section thoroughly -before using SqlSoup in any web application. +.. note:: + + Please read and understand this section thoroughly + before using SqlSoup in any web application. SqlSoup uses a ScopedSession to provide thread-local sessions. You can get a reference to the current one like this:: diff --git a/lib/sqlalchemy/interfaces.py b/lib/sqlalchemy/interfaces.py index d1e3fa6b2a..650a888999 100644 --- a/lib/sqlalchemy/interfaces.py +++ b/lib/sqlalchemy/interfaces.py @@ -17,7 +17,9 @@ from sqlalchemy import event, util class PoolListener(object): """Hooks into the lifecycle of connections in a :class:`.Pool`. - .. note:: :class:`.PoolListener` is deprecated. Please + .. note:: + + :class:`.PoolListener` is deprecated. Please refer to :class:`.PoolEvents`. Usage:: @@ -149,7 +151,9 @@ class PoolListener(object): class ConnectionProxy(object): """Allows interception of statement execution by Connections. - .. note:: :class:`.ConnectionProxy` is deprecated. Please + .. note:: + + :class:`.ConnectionProxy` is deprecated. Please refer to :class:`.ConnectionEvents`. Either or both of the ``execute()`` and ``cursor_execute()`` diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py index 28d41dab23..39f321aa6d 100644 --- a/lib/sqlalchemy/orm/__init__.py +++ b/lib/sqlalchemy/orm/__init__.py @@ -180,7 +180,9 @@ def create_session(bind=None, **kwargs): def relationship(argument, secondary=None, **kwargs): """Provide a relationship of a primary Mapper to a secondary Mapper. - .. note:: :func:`relationship` is historically known as + .. note:: + + :func:`relationship` is historically known as :func:`relation` prior to version 0.6. This corresponds to a parent-child or associative table relationship. The @@ -1117,7 +1119,9 @@ def synonym(name, map_column=False, descriptor=None, comparator_factory=None, doc=None): """Denote an attribute name as a synonym to a mapped property. - .. note:: :func:`.synonym` is superseded as of 0.7 by + .. note:: + + :func:`.synonym` is superseded as of 0.7 by the :mod:`~sqlalchemy.ext.hybrid` extension. See the documentation for hybrids at :ref:`hybrids_toplevel`. @@ -1159,7 +1163,9 @@ def comparable_property(comparator_factory, descriptor=None): """Provides a method of applying a :class:`.PropComparator` to any Python descriptor attribute. - .. note:: :func:`.comparable_property` is superseded as of 0.7 by + .. note:: + + :func:`.comparable_property` is superseded as of 0.7 by the :mod:`~sqlalchemy.ext.hybrid` extension. See the example at :ref:`hybrid_custom_comparators`. @@ -1261,10 +1267,12 @@ def joinedload(*keys, **kw): """Return a ``MapperOption`` that will convert the property of the given name or series of mapped attributes into an joined eager load. - .. note:: This function is known as :func:`eagerload` in all versions - of SQLAlchemy prior to version 0.6beta3, including the 0.5 and 0.4 - series. :func:`eagerload` will remain available for the foreseeable - future in order to enable cross-compatibility. + .. note:: + + This function is known as :func:`eagerload` in all versions + of SQLAlchemy prior to version 0.6beta3, including the 0.5 and 0.4 + series. :func:`eagerload` will remain available for the foreseeable + future in order to enable cross-compatibility. Used with :meth:`~sqlalchemy.orm.query.Query.options`. @@ -1286,7 +1294,9 @@ def joinedload(*keys, **kw): query(Order).options(joinedload(Order.user, innerjoin=True)) - .. note:: The join created by :func:`joinedload` is anonymously aliased such that + .. note:: + + 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 tables - so-called "user space" joins are constructed using @@ -1314,10 +1324,12 @@ def joinedload_all(*keys, **kw): given dot-separated path or series of mapped attributes into an joined eager load. - .. note:: This function is known as :func:`eagerload_all` in all versions - of SQLAlchemy prior to version 0.6beta3, including the 0.5 and 0.4 - series. :func:`eagerload_all` will remain available for the - foreseeable future in order to enable cross-compatibility. + .. note:: + + This function is known as :func:`eagerload_all` in all versions + of SQLAlchemy prior to version 0.6beta3, including the 0.5 and 0.4 + series. :func:`eagerload_all` will remain available for the + foreseeable future in order to enable cross-compatibility. Used with :meth:`~sqlalchemy.orm.query.Query.options`. diff --git a/lib/sqlalchemy/orm/deprecated_interfaces.py b/lib/sqlalchemy/orm/deprecated_interfaces.py index d5a9ab9c69..3d78ce7571 100644 --- a/lib/sqlalchemy/orm/deprecated_interfaces.py +++ b/lib/sqlalchemy/orm/deprecated_interfaces.py @@ -11,7 +11,9 @@ from interfaces import EXT_CONTINUE class MapperExtension(object): """Base implementation for :class:`.Mapper` event hooks. - .. note:: :class:`.MapperExtension` is deprecated. Please + .. note:: + + :class:`.MapperExtension` is deprecated. Please refer to :func:`.event.listen` as well as :class:`.MapperEvents`. @@ -375,7 +377,9 @@ class SessionExtension(object): """Base implementation for :class:`.Session` event hooks. - .. note:: :class:`.SessionExtension` is deprecated. Please + .. note:: + + :class:`.SessionExtension` is deprecated. Please refer to :func:`.event.listen` as well as :class:`.SessionEvents`. @@ -493,7 +497,9 @@ class AttributeExtension(object): """Base implementation for :class:`.AttributeImpl` event hooks, events that fire upon attribute mutations in user code. - .. note:: :class:`.AttributeExtension` is deprecated. Please + .. note:: + + :class:`.AttributeExtension` is deprecated. Please refer to :func:`.event.listen` as well as :class:`.AttributeEvents`. diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py index 156c40b60d..8395540b17 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -1360,7 +1360,9 @@ class Query(object): q = session.query(User).join(Address, User.id==Address.user_id) - .. note:: In SQLAlchemy 0.6 and earlier, the two argument form of + .. note:: + + In SQLAlchemy 0.6 and earlier, the two argument form of :meth:`~.Query.join` requires the usage of a tuple:: query(User).join((Address, User.id==Address.user_id)) diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index 06dc8dcb42..8f366b43d4 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -1653,7 +1653,9 @@ class Session(object): return session.is_modified(someobject, passive=True) - .. note:: In SQLAlchemy 0.7 and earlier, the ``passive`` + .. note:: + + In SQLAlchemy 0.7 and earlier, the ``passive`` flag should **always** be explicitly set to ``True``. The current default value of :data:`.attributes.PASSIVE_OFF` for this flag is incorrect, in that it loads unloaded diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py index c333bb6396..268448bc3d 100644 --- a/lib/sqlalchemy/sql/expression.py +++ b/lib/sqlalchemy/sql/expression.py @@ -236,9 +236,11 @@ def select(columns=None, whereclause=None, from_obj=[], **kwargs): ``distinct`` is also available via the :meth:`~.Select.distinct` generative method. - .. note:: The ``distinct`` keyword's acceptance of a string - argument for usage with MySQL is deprecated. Use - the ``prefixes`` argument or :meth:`~.Select.prefix_with`. + .. note:: + + The ``distinct`` keyword's acceptance of a string + argument for usage with MySQL is deprecated. Use + the ``prefixes`` argument or :meth:`~.Select.prefix_with`. :param for_update=False: when ``True``, applies ``FOR UPDATE`` to the end of the @@ -4697,7 +4699,9 @@ class Select(_SelectBase): """Return a new :func:`.select` construct with its columns clause replaced with the given columns. - .. note:: Due to a bug fix, this method has a slight + .. note:: + + Due to a bug fix, this method has a slight behavioral change as of version 0.7.3. Prior to version 0.7.3, the FROM clause of a :func:`.select` was calculated upfront and as new columns diff --git a/lib/sqlalchemy/types.py b/lib/sqlalchemy/types.py index 1ad1280f53..bad181f97b 100644 --- a/lib/sqlalchemy/types.py +++ b/lib/sqlalchemy/types.py @@ -92,9 +92,11 @@ class TypeEngine(AbstractType): are serialized into strings are examples of "mutable" column structures. - .. note:: This functionality is now superseded by the - ``sqlalchemy.ext.mutable`` extension described in - :ref:`mutable_toplevel`. + .. note:: + + This functionality is now superseded by the + ``sqlalchemy.ext.mutable`` extension described in + :ref:`mutable_toplevel`. When this method is overridden, :meth:`copy_value` should also be supplied. The :class:`.MutableType` mixin @@ -712,9 +714,11 @@ class TypeDecorator(TypeEngine): are serialized into strings are examples of "mutable" column structures. - .. note:: This functionality is now superseded by the - ``sqlalchemy.ext.mutable`` extension described in - :ref:`mutable_toplevel`. + .. note:: + + This functionality is now superseded by the + ``sqlalchemy.ext.mutable`` extension described in + :ref:`mutable_toplevel`. """ return self.impl.is_mutable() @@ -782,7 +786,9 @@ class MutableType(object): a mutable Python object type. This functionality is used only by the ORM. - .. note:: :class:`.MutableType` is superseded as of SQLAlchemy 0.7 + .. note:: + + :class:`.MutableType` is superseded as of SQLAlchemy 0.7 by the ``sqlalchemy.ext.mutable`` extension described in :ref:`mutable_toplevel`. This extension provides an event driven approach to in-place mutation detection that does not @@ -810,7 +816,9 @@ class MutableType(object): type - implementing subclasses should override these appropriately. - .. warning:: The usage of mutable types has significant performance + .. warning:: + + The usage of mutable types has significant performance implications when using the ORM. In order to detect changes, the ORM must create a copy of the value when it is first accessed, so that changes to the current value can be compared @@ -1280,7 +1288,9 @@ class Numeric(_DateAffinity, TypeEngine): ``decimal.Decimal`` objects by default, applying conversion as needed. - .. note:: The `cdecimal `_ library + .. note:: + + The `cdecimal `_ library is a high performing alternative to Python's built-in ``decimal.Decimal`` type, which performs very poorly in high volume situations. SQLAlchemy 0.7 is tested against ``cdecimal`` and supports @@ -1936,7 +1946,9 @@ class PickleType(MutableType, TypeDecorator): behavior. (default changed from ``True`` in 0.7.0). - .. note:: This functionality is now superseded by the + .. note:: + + This functionality is now superseded by the ``sqlalchemy.ext.mutable`` extension described in :ref:`mutable_toplevel`. diff --git a/lib/sqlalchemy/util/langhelpers.py b/lib/sqlalchemy/util/langhelpers.py index f10ab3fb59..a755470171 100644 --- a/lib/sqlalchemy/util/langhelpers.py +++ b/lib/sqlalchemy/util/langhelpers.py @@ -860,7 +860,9 @@ def warn(msg, stacklevel=3): If msg is a string, :class:`.exc.SAWarning` is used as the category. - .. note:: This function is swapped out when the test suite + .. note:: + + This function is swapped out when the test suite runs, with a compatible version that uses warnings.warn_explicit, so that the warnings registry can be controlled. -- 2.47.2