diff options
24 files changed, 169 insertions, 82 deletions
diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst index 15b87cbae..9f9a8f07d 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 bfcf92bad..7e315c1a7 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 c2dc92757..49029e67f 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 52180a91b..b5020b6ee 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 6491332f6..4e0d66091 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 8d73ceeca..4713f3289 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 118b52f04..407930ad0 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 f4c43fbc5..6bfd01edd 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 a41d514f2..1c1189507 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 226180247..b7683581c 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 673b86add..ba6f61b40 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 63832b8f3..724716831 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 ffbdfaae9..91d770197 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 ece7e3ad4..8f14f5197 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 ce63b88ea..ba505eb7b 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 fe2f74137..189aa1af1 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 d1e3fa6b2..650a88899 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 28d41dab2..39f321aa6 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 d5a9ab9c6..3d78ce757 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 156c40b60..8395540b1 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 06dc8dcb4..8f366b43d 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 c333bb639..268448bc3 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 1ad1280f5..bad181f97 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 <http://pypi.python.org/pypi/cdecimal/>`_ library + .. note:: + + The `cdecimal <http://pypi.python.org/pypi/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 f10ab3fb5..a75547017 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. |