diff options
author | Mike Bayer <mike_mp@zzzcomputing.com> | 2012-07-17 20:24:14 -0400 |
---|---|---|
committer | Mike Bayer <mike_mp@zzzcomputing.com> | 2012-07-17 20:24:14 -0400 |
commit | 02ebb4943914ab691276d990c6aa019d7cb90659 (patch) | |
tree | c9e6b5158b1c353962fdad75f3d079516602c426 /lib/sqlalchemy/ext/mutable.py | |
parent | de115ae40695d8e9fa6d85c629222bec2ea01ff6 (diff) | |
download | sqlalchemy-02ebb4943914ab691276d990c6aa019d7cb90659.tar.gz |
- move ext to relative imports
Diffstat (limited to 'lib/sqlalchemy/ext/mutable.py')
-rw-r--r-- | lib/sqlalchemy/ext/mutable.py | 74 |
1 files changed, 37 insertions, 37 deletions
diff --git a/lib/sqlalchemy/ext/mutable.py b/lib/sqlalchemy/ext/mutable.py index 2280e33f3..2f5c68d7b 100644 --- a/lib/sqlalchemy/ext/mutable.py +++ b/lib/sqlalchemy/ext/mutable.py @@ -21,8 +21,8 @@ Establishing Mutability on Scalar Column Values =============================================== A typical example of a "mutable" structure is a Python dictionary. -Following the example introduced in :ref:`types_toplevel`, we -begin with a custom type that marshals Python dictionaries into +Following the example introduced in :ref:`types_toplevel`, we +begin with a custom type that marshals Python dictionaries into JSON strings before being persisted:: from sqlalchemy.types import TypeDecorator, VARCHAR @@ -43,7 +43,7 @@ JSON strings before being persisted:: value = json.loads(value) return value -The usage of ``json`` is only for the purposes of example. The :mod:`sqlalchemy.ext.mutable` +The usage of ``json`` is only for the purposes of example. The :mod:`sqlalchemy.ext.mutable` extension can be used with any type whose target Python type may be mutable, including :class:`.PickleType`, :class:`.postgresql.ARRAY`, etc. @@ -86,7 +86,7 @@ The above dictionary class takes the approach of subclassing the Python built-in ``dict`` to produce a dict subclass which routes all mutation events through ``__setitem__``. There are many variants on this approach, such as subclassing ``UserDict.UserDict``, -the newer ``collections.MutableMapping``, etc. The part that's important to this +the newer ``collections.MutableMapping``, etc. The part that's important to this example is that the :meth:`.Mutable.changed` method is called whenever an in-place change to the datastructure takes place. @@ -95,7 +95,7 @@ convert any values that are not instances of ``MutationDict``, such as the plain dictionaries returned by the ``json`` module, into the appropriate type. Defining this method is optional; we could just as well created our ``JSONEncodedDict`` such that it always returns an instance of ``MutationDict``, -and additionally ensured that all calling code uses ``MutationDict`` +and additionally ensured that all calling code uses ``MutationDict`` explicitly. When :meth:`.Mutable.coerce` is not overridden, any values applied to a parent object which are not instances of the mutable type will raise a ``ValueError``. @@ -108,14 +108,14 @@ of this type, applying event listening instrumentation to the mapped attribute. Such as, with classical table metadata:: from sqlalchemy import Table, Column, Integer - + my_data = Table('my_data', metadata, Column('id', Integer, primary_key=True), Column('data', MutationDict.as_mutable(JSONEncodedDict)) ) Above, :meth:`~.Mutable.as_mutable` returns an instance of ``JSONEncodedDict`` -(if the type object was not an instance already), which will intercept any +(if the type object was not an instance already), which will intercept any attributes which are mapped against this type. Below we establish a simple mapping against the ``my_data`` table:: @@ -157,7 +157,7 @@ will flag the attribute as "dirty" on the parent object:: The ``MutationDict`` can be associated with all future instances of ``JSONEncodedDict`` in one step, using :meth:`~.Mutable.associate_with`. This -is similar to :meth:`~.Mutable.as_mutable` except it will intercept +is similar to :meth:`~.Mutable.as_mutable` except it will intercept all occurrences of ``MutationDict`` in all mappings unconditionally, without the need to declare it individually:: @@ -167,8 +167,8 @@ the need to declare it individually:: __tablename__ = 'my_data' id = Column(Integer, primary_key=True) data = Column(JSONEncodedDict) - - + + Supporting Pickling -------------------- @@ -314,10 +314,10 @@ the minimal form of our ``Point`` class:: class Point(MutableComposite): # ... - + def __getstate__(self): return self.x, self.y - + def __setstate__(self, state): self.x, self.y = state @@ -326,10 +326,10 @@ pickling process of the parent's object-relational state so that the :meth:`.MutableBase._parents` collection is restored to all ``Point`` objects. """ -from sqlalchemy.orm.attributes import flag_modified -from sqlalchemy import event, types -from sqlalchemy.orm import mapper, object_mapper -from sqlalchemy.util import memoized_property +from ..orm.attributes import flag_modified +from .. import event, types +from ..orm import mapper, object_mapper +from ..util import memoized_property import weakref class MutableBase(object): @@ -338,11 +338,11 @@ class MutableBase(object): @memoized_property def _parents(self): """Dictionary of parent object->attribute name on the parent. - + This attribute is a so-called "memoized" property. It initializes itself with a new ``weakref.WeakKeyDictionary`` the first time it is accessed, returning the same object upon subsequent access. - + """ return weakref.WeakKeyDictionary() @@ -359,7 +359,7 @@ class MutableBase(object): @classmethod def _listen_on_attribute(cls, attribute, coerce, parent_cls): - """Establish this type as a mutation listener for the given + """Establish this type as a mutation listener for the given mapped descriptor. """ @@ -373,7 +373,7 @@ class MutableBase(object): def load(state, *args): """Listen for objects loaded or refreshed. - Wrap the target data member's value with + Wrap the target data member's value with ``Mutable``. """ @@ -389,7 +389,7 @@ class MutableBase(object): data member. Establish a weak reference to the parent object - on the incoming value, remove it for the one + on the incoming value, remove it for the one outgoing. """ @@ -436,7 +436,7 @@ class Mutable(MutableBase): @classmethod def associate_with_attribute(cls, attribute): - """Establish this type as a mutation listener for the given + """Establish this type as a mutation listener for the given mapped descriptor. """ @@ -444,15 +444,15 @@ class Mutable(MutableBase): @classmethod def associate_with(cls, sqltype): - """Associate this wrapper with all future mapped columns + """Associate this wrapper with all future mapped columns of the given type. This is a convenience method that calls ``associate_with_attribute`` automatically. - .. warning:: - + .. warning:: + The listeners established by this method are *global* - to all mappers, and are *not* garbage collected. Only use + 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 in memory usage. @@ -474,7 +474,7 @@ class Mutable(MutableBase): This establishes listeners that will detect ORM mappings against the given type, adding mutation event trackers to those mappings. - The type is returned, unconditionally as an instance, so that + The type is returned, unconditionally as an instance, so that :meth:`.as_mutable` can be used inline:: Table('mytable', metadata, @@ -486,15 +486,15 @@ class Mutable(MutableBase): is given, and that only columns which are declared specifically with that type instance receive additional instrumentation. - To associate a particular mutable type with all occurrences of a + To associate a particular mutable type with all occurrences of a particular type, use the :meth:`.Mutable.associate_with` classmethod of the particular :meth:`.Mutable` subclass to establish a global association. - .. warning:: - + .. warning:: + The listeners established by this method are *global* - to all mappers, and are *not* garbage collected. Only use + 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 in memory usage. @@ -521,13 +521,13 @@ class MutableComposite(MutableBase): """Mixin that defines transparent propagation of change events on a SQLAlchemy "composite" object to its owning parent or parents. - + See the example in :ref:`mutable_composites` for usage information. - - .. warning:: - + + .. warning:: + The listeners established by the :class:`.MutableComposite` - class are *global* to all mappers, and are *not* garbage collected. Only use + 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 in memory usage. @@ -542,7 +542,7 @@ class MutableComposite(MutableBase): prop = object_mapper(parent).get_property(key) for value, attr_name in zip( - self.__composite_values__(), + self.__composite_values__(), prop._attribute_keys): setattr(parent, attr_name, value) |