[Jc
@ s d Z d d k Z d d k Z d d k Z d d k Z d d k Z d d k i Z d d k l
Z
d d k l Z l
Z
d d d d d g Z e
i i Z d
Z d Z d Z d e f d
YZ d Z d Z d e f d YZ d Z d Z d Z d Z d Z e d Z e d Z! e d Z" d Z# d Z$ e
i% o e& e' f Z( n d d k) Z) e& e' e) i* f Z( d Z+ d Z, d Z- d e. f d YZ/ d! e& f d" YZ0 d# e1 f d$ YZ2 h e/ e. 6e0 e& 6e2 e1 6Z3 h h d% d& 6d' d( 6d) d* 6e# d+ 6e. 6h d, d& 6d' d( 6d) d* 6e- d+ 6e& 6h d- d* 6e$ d+ 6e1 6h e 6Z4 d. e1 f d/ YZ5 d S(0 sJ Support for collections of mapped entities.
The collections package supplies the machinery used to inform the ORM of
collection membership changes. An instrumentation via decoration approach is
used, allowing arbitrary types (including built-ins) to be used as entity
collections without requiring inheritance from a base class.
Instrumentation decoration relays membership change events to the
``InstrumentedCollectionAttribute`` that is currently managing the collection.
The decorators observe function call arguments and return values, tracking
entities entering or leaving the collection. Two decorator approaches are
provided. One is a bundle of generic decorators that map function arguments
and return values to events::
from sqlalchemy.orm.collections import collection
class MyClass(object):
# ...
@collection.adds(1)
def store(self, item):
self.data.append(item)
@collection.removes_return()
def pop(self):
return self.data.pop()
The second approach is a bundle of targeted decorators that wrap appropriate
append and remove notifiers around the mutation methods present in the
standard Python ``list``, ``set`` and ``dict`` interfaces. These could be
specified in terms of generic decorator recipes, but are instead hand-tooled
for increased efficiency. The targeted decorators occasionally implement
adapter-like behavior, such as mapping bulk-set methods (``extend``,
``update``, ``__setslice__``, etc.) into the series of atomic mutation events
that the ORM requires.
The targeted decorators are used internally for automatic instrumentation of
entity collection classes. Every collection class goes through a
transformation process roughly like so:
1. If the class is a built-in, substitute a trivial sub-class
2. Is this class already instrumented?
3. Add in generic decorators
4. Sniff out the collection interface through duck-typing
5. Add targeted decoration to any undecorated interface method
This process modifies the class at runtime, decorating methods and adding some
bookkeeping properties. This isn't possible (or desirable) for built-in
classes like ``list``, so trivial sub-classes are substituted to hold
decoration::
class InstrumentedList(list):
pass
Collection classes can be specified in ``relation(collection_class=)`` as
types or a function that returns an instance. Collection classes are
inspected and instrumented during the mapper compilation phase. The
collection_class callable will be executed once to produce a specimen
instance, and the type of that specimen will be instrumented. Functions that
return built-in types like ``lists`` will be adapted to produce instrumented
instances.
When extending a known type like ``list``, additional decorations are not
generally not needed. Odds are, the extension method will delegate to a
method that's already instrumented. For example::
class QueueIsh(list):
def push(self, item):
self.append(item)
def shift(self):
return self.pop(0)
There's no need to decorate these methods. ``append`` and ``pop`` are already
instrumented as part of the ``list`` interface. Decorating them would fire
duplicate events, which should be avoided.
The targeted decoration tries not to rely on other methods in the underlying
collection class, but some are unavoidable. Many depend on 'read' methods
being present to properly instrument a 'write', for example, ``__setitem__``
needs ``__getitem__``. "Bulk" methods like ``update`` and ``extend`` may also
reimplemented in terms of atomic appends and removes, so the ``extend``
decoration will actually perform many ``append`` operations and not call the
underlying method at all.
Tight control over bulk operation and the firing of events is also possible by
implementing the instrumentation internally in your methods. The basic
instrumentation package works under the general assumption that collection
mutation will not raise unusual exceptions. If you want to closely
orchestrate append and remove events with exception management, internal
instrumentation may be the answer. Within your method,
``collection_adapter(self)`` will retrieve an object that you can use for
explicit control over triggering append and remove events.
The owning object and InstrumentedCollectionAttribute are also reachable
through the adapter, allowing for some very sophisticated behavior.
iN( t
expression( t schemat utilt
collectiont collection_adaptert mapped_collectiont column_mapped_collectiont attribute_mapped_collectionc s d d k l d d k l g } t i D] } | t i | q4 ~ t d j o f d n" t f d f d S( s A dictionary-based collection type with column-based keying.
Returns a MappedCollection factory with a keying function generated
from mapping_spec, which may be a Column or a sequence of Columns.
The key value must be immutable for the lifetime of the object. You
can not, for example, map on foreign key values if those key values will
change during the session, i.e. from None to a database-assigned integer
after a session flush.
i( t
_state_mapper( t instance_statei c s, | } | } | i | d S( Ni ( t _get_state_attr_by_column( t valuet statet m( t colsR R ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt keyfunc s c s5 | t f d D S( Nc 3 s% x | ] } i | Vq Wd S( N( R
( t .0t c( R
R ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pys s ( t tuple( R ( t mapping_specR R ( R
R s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s c s
t S( ( t MappedCollection( ( R ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt s (
t sqlalchemy.orm.utilR t sqlalchemy.orm.attributesR R t to_listR t _no_literalst lenR ( R t _[1]t q( ( R R R R R s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR u s 3 c s
f d S( s A dictionary-based collection type with attribute-based keying.
Returns a MappedCollection factory with a keying based on the
'attr_name' attribute of entities in the collection.
The key value must be immutable for the lifetime of the object. You
can not, for example, map on foreign key values if those key values will
change during the session, i.e. from None to a database-assigned integer
after a session flush.
c s t t i S( ( R t operatort
attrgetter( ( t attr_name( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s ( ( R ( ( R s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s c s
f d S( s A dictionary-based collection type with arbitrary keying.
Returns a MappedCollection factory with a keying function generated
from keyfunc, a callable that takes an entity and returns a key value.
The key value must be immutable for the lifetime of the object. You
can not, for example, map on foreign key values if those key values will
change during the session, i.e. from None to a database-assigned integer
after a session flush.
c s
t S( ( R ( ( R ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s ( ( R ( ( R s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s c B s e Z d Z e d Z e d Z e d Z e d Z e d Z e d Z e d Z
e d Z e d Z e d
Z
RS( s Decorators for entity collection classes.
The decorators fall into two groups: annotations and interception recipes.
The annotating decorators (appender, remover, iterator,
internally_instrumented, on_link) indicate the method's purpose and take no
arguments. They are not written with parens::
@collection.appender
def append(self, append): ...
The recipe decorators all require parens, even those that take no
arguments::
@collection.adds('entity'):
def insert(self, position, entity): ...
@collection.removes_return()
def popitem(self): ...
Decorators can be specified in long-hand for Python 2.3, or with
the class-level dict attribute '__instrumentation__'- see the source
for details.
c C s t | d d | S( s Tag the method as the collection appender.
The appender method is called with one positional argument: the value
to append. The method will be automatically decorated with 'adds(1)'
if not already decorated::
@collection.appender
def add(self, append): ...
# or, equivalently
@collection.appender
@collection.adds(1)
def add(self, append): ...
# for mapping type, an 'append' may kick out a previous value
# that occupies that slot. consider d['a'] = 'foo'- any previous
# value in d['a'] is discarded.
@collection.appender
@collection.replaces(1)
def add(self, entity):
key = some_key_func(entity)
previous = None
if key in self:
previous = self[key]
self[key] = entity
return previous
If the value to append is not allowed in the collection, you may
raise an exception. Something to remember is that the appender
will be called for each object mapped by a database query. If the
database contains rows that violate your collection semantics, you
will need to get creative to fix the problem, as access via the
collection will not work.
If the appender method is internally instrumented, you must also
receive the keyword argument '_sa_initiator' and ensure its
promulgation to collection events.
t _sa_instrument_rolet appender( t setattr( t fn( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR! s )c C s t | d d | S( s Tag the method as the collection remover.
The remover method is called with one positional argument: the value
to remove. The method will be automatically decorated with
'removes_return()' if not already decorated::
@collection.remover
def zap(self, entity): ...
# or, equivalently
@collection.remover
@collection.removes_return()
def zap(self, ): ...
If the value to remove is not present in the collection, you may
raise an exception or return None to ignore the error.
If the remove method is internally instrumented, you must also
receive the keyword argument '_sa_initiator' and ensure its
promulgation to collection events.
R t remover( R" ( R# ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR$ s c C s t | d d | S( s Tag the method as the collection remover.
The iterator method is called with no arguments. It is expected to
return an iterator over all collection members::
@collection.iterator
def __iter__(self): ...
R t iterator( R" ( R# ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR% s c C s t | d t | S( s Tag the method as instrumented.
This tag will prevent any decoration from being applied to the method.
Use this if you are orchestrating your own calls to collection_adapter
in one of the basic SQLAlchemy interface methods, or to prevent
an automatic ABC method decoration from wrapping your implementation::
# normally an 'extend' method on a list-like class would be
# automatically intercepted and re-implemented in terms of
# SQLAlchemy events and append(). your implementation will
# never be called, unless:
@collection.internally_instrumented
def extend(self, items): ...
t _sa_instrumented( R" t True( R# ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt internally_instrumented" s c C s t | d d | S( s Tag the method as a the "linked to attribute" event handler.
This optional event handler will be called when the collection class
is linked to or unlinked from the InstrumentedAttribute. It is
invoked immediately after the '_sa_adapter' property is set on
the instance. A single argument is passed: the collection adapter
that has been linked, or None if unlinking.
R t on_link( R" ( R# ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR) 6 s c C s t | d d | S( s Tag the method as the collection converter.
This optional method will be called when a collection is being
replaced entirely, as in::
myobj.acollection = [newvalue1, newvalue2]
The converter method will receive the object being assigned and should
return an iterable of values suitable for use by the ``appender``
method. A converter must not assign values or mutate the collection,
it's sole job is to adapt the value the user provides into an iterable
of values for the ORM's use.
The default converter implementation will use duck-typing to do the
conversion. A dict-like collection will be convert into an iterable
of dictionary values, and other types will simply be iterated.
@collection.converter
def convert(self, other): ...
If the duck-typing of the object does not match the type of this
collection, a TypeError is raised.
Supply an implementation of this method if you want to expand the
range of possible types that can be assigned in bulk or perform
validation on the values about to be assigned.
R t converter( R" ( R# ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR* D s c s f d } | S( s Mark the method as adding an entity to the collection.
Adds "add to collection" handling to the method. The decorator
argument indicates which method argument holds the SQLAlchemy-relevant
value. Arguments can be specified positionally (i.e. integer) or by
name::
@collection.adds(1)
def push(self, item): ...
@collection.adds('entity')
def do_stuff(self, thing, entity=None): ...
c s t | d d f | S( Nt _sa_instrument_beforet fire_append_event( R" ( R# ( t arg( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt decoratoru s ( ( R- R. ( ( R- s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt addse s c s f d } | S( s Mark the method as replacing an entity in the collection.
Adds "add to collection" and "remove from collection" handling to
the method. The decorator argument indicates which method argument
holds the SQLAlchemy-relevant value to be added, and return value, if
any will be considered the value to remove.
Arguments can be specified positionally (i.e. integer) or by name::
@collection.replaces(2)
def __setitem__(self, index, item): ...
c s* t | d d f t | d d | S( NR+ R, t _sa_instrument_aftert fire_remove_event( R" ( R# ( R- ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR. s ( ( R- R. ( ( R- s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt replacesz s c s f d } | S( s Mark the method as removing an entity in the collection.
Adds "remove from collection" handling to the method. The decorator
argument indicates which method argument holds the SQLAlchemy-relevant
value to be removed. Arguments can be specified positionally (i.e.
integer) or by name::
@collection.removes(1)
def zap(self, item): ...
For methods where the value to remove is not known at call-time, use
collection.removes_return.
c s t | d d f | S( NR+ R1 ( R" ( R# ( R- ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR. s ( ( R- R. ( ( R- s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt removes s c C s
d } | S( s Mark the method as removing an entity in the collection.
Adds "remove from collection" handling to the method. The return value
of the method, if any, is considered the value to remove. The method
arguments are not inspected::
@collection.removes_return()
def pop(self): ...
For methods where the value to remove is known at call-time, use
collection.remove.
c S s t | d d | S( NR0 R1 ( R" ( R# ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR. s ( ( R. ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt removes_return s ( t __name__t
__module__t __doc__t staticmethodR! R$ R% R( R) R* R/ R2 R3 R4 ( ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s ,!c C s t | d d S( s- Fetch the CollectionAdapter for a collection.t _sa_adapterN( t getattrt None( R ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s c C sS y t | d t | d SWn, t j
o t d t | i n Xd S( s Iterate over an object supporting the @iterator or __iter__ protocols.
If the collection is an ORM collection, it need not be attached to an
object to be iterable.
t _sa_iteratort __iter__s '%s' object is not iterableN( R: t AttributeErrort TypeErrort typeR5 ( R ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt collection_iter s t CollectionAdapterc B s e Z d Z d Z e d d d Z d Z d Z d Z d d Z
d Z d d
Z d Z
d d Z d
Z d Z d Z d Z d d Z d d Z d d Z d Z d Z RS( sa Bridges between the ORM and arbitrary Python collections.
Proxies base-level collection operations (append, remove, iterate)
to the underlying Python collection, and emits add/remove events for
entities entering or leaving the collection.
The ORM uses an CollectionAdapter exclusively for interaction with
entity collections.
c C s5 | | _ t i | | _ | | _ | i | d S( N( t attrt weakreft reft _datat owner_statet link_to_self( t selfRC RG t data( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt __init__ s c C s
| i S( ( RF ( t s( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s t docs$ The entity collection being adapted.c C s; t | d | t | d o t | d | n d S( s9 Link a collection to this adapter, and fire a link event.R9 t _sa_on_linkN( R" t hasattrR: ( RI RJ ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyRH s c C s; t | d d t | d o t | d d n d S( s< Unlink a collection from any adapter, and fire a link event.R9 RN N( R" R; RO R: ( RI RJ ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt unlink s c C s3 t | i d d } | d j o | | St i | } t i | i } | d j p
| | j of | d j o d p
| i i } | d j o | i i i } n
| i } t d | | f n t | d d d j o t | d S| t j o t | d t | d St | Sd S( s Converts collection-compatible objects to an iterable of values.
Can be passed any type of object, and if the underlying collection
determines that it can be adapted into a stream of values it can
use, returns an iterable of values suitable for append()ing.
This method may raise TypeError or any other suitable exception
if adaptation fails.
If a converter implementation is not supplied on the collection,
a default duck-typing-based implementation is used.
t
_sa_converterR; s/ Incompatible collection type: %s is not %s-likeR9 t
itervaluest valuesN(
R: RF R; R t duck_type_collectiont __class__R5 R? t dictt iter( RI t objR* t setting_typet receiving_typet givent wanted( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt adapt_like_to_iterable s$
c C s# t | i d | d | d S( s8 Add an entity to the collection, firing mutation events.t _sa_appendert
_sa_initiatorN( R: RF ( RI t itemt initiator( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt append_with_event s c C s# t | i d | d t d S( s= Add or restore an entity to the collection, firing no events.R^ R_ N( R: RF t False( RI R` ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt append_without_event s c C s# t | i d | d | d S( s= Remove an entity from the collection, firing mutation events.t _sa_removerR_ N( R: RF ( RI R` Ra ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt remove_with_event s c C s# t | i d | d t d S( s7 Remove an entity from the collection, firing no events.Re R_ N( R: RF Rc ( RI R` ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt remove_without_event$ s c C s+ x$ t | D] } | i | | q
Wd S( s> Empty the collection, firing a mutation event for each entity.N( t listRf ( RI Ra R` ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt clear_with_event( s
c C s( x! t | D] } | i | q
Wd S( s' Empty the collection, firing no events.N( Rh Rg ( RI R` ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt clear_without_event- s
c C s t | i d S( s( Iterate over entities in the collection.R< ( R: RF ( RI ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR= 2 s c C s" t t t | i d S( s! Count entities in the collection.R< ( R Rh R: RF ( RI ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt __len__6 s c C s t S( N( R' ( RI ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt __nonzero__: s c C sE | t j o0 | d j o# | i i | i | i i | | S| Sd S( s Notify that a entity has entered the collection.
Initiator is the InstrumentedAttribute that initiated the membership
mutation, and should be left as None unless you are passing along
an initiator value from a chained operation.
N( Rc R; RC R, RG RV ( RI R` Ra ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR, = s #c C sD | t j o3 | d j o& | i i | i | i i | | n d S( s Notify that a entity has been removed from the collection.
Initiator is the InstrumentedAttribute that initiated the membership
mutation, and should be left as None unless you are passing along
an initiator value from a chained operation.
N( Rc R; RC R1 RG RV ( RI R` Ra ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR1 J s c C s& | i i | i | i i d | d S( s Notify that an entity is about to be removed from the collection.
Only called if the entity cannot be removed after calling
fire_remove_event().
Ra N( RC t fire_pre_remove_eventRG RV ( RI Ra ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyRm U s c C s% h | i i d 6| i d 6| i d 6S( Nt keyRG RJ ( RC Rn RG RJ ( RI ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt __getstate__^ s
c C sM t | d i i | d i | _ | d | _ t i | d | _ d S( NRG Rn RJ ( R: RX RU t implRC RG RD RE RF ( RI t d( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt __setstate__c s &
N( R5 R6 R7 RK t propertyRJ RH RP R] R; Rb Rd Rf Rg Ri Rj R= Rk Rl R, R1 Rm Ro Rr ( ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyRB s*
)
c C s t | t p t | } n t i } | | p d i | p d } | | p d i | } | | p d i | } xQ | p d D]B } | | j o | i | q | | j o | i | q q W| o" x | D] } | i | q Wn d S( s" Load a new collection, firing events based on prior like membership.
Appends instances in ``values`` onto the ``new_adapter``. Events will be
fired for any instance not present in the ``existing_adapter``. Any
instances in ``existing_adapter`` not present in ``values`` will have
remove events fired upon them.
values
An iterable of collection member instances
existing_adapter
A CollectionAdapter of instances to be replaced
new_adapter
An empty CollectionAdapter to load with ``values``
N( ( ( ( ( ( t
isinstanceRh R t IdentitySett intersectiont
differenceRb Rd Rf ( RS t existing_adaptert new_adaptert idsett constantst additionst removalst member( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt bulk_replacei s #
c C s | t j o t | } n t | } | t j o t | } | } n t i oC z1 t | d d t | j o t | n Wd t i Xn | S( so Prepare a callable for future use as a collection class factory.
Given a collection class factory (either a type or no-arg callable),
return another factory that will produce compatible instances when
called.
This function is responsible for converting collection_class=list
into the run-time behavior of collection_class=InstrumentedList.
R& N(
t __canned_instrumentationR@ t __converting_factoryt __instrumentation_mutext acquireR: R; t idt _instrument_classt release( t factoryt cls( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt prepare_instrumentation s
c s= f d } y d i | _ i | _ Wn n X| S( s Convert the type returned by collection factories on the fly.
Given a collection factory that returns a builtin type (e.g. a list),
return a wrapped function that converts that type to one of our
instrumented types.
c sD } t | } | t j o t | | St i d d S( NsD Collection class factories must produce instances of a single class.( R@ R t sa_exct InvalidRequestError( R t type_( t original_factory( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt wrapper s
s %sWrapper( R5 R7 ( R R ( ( R s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s c
C s | i d j o t i d n t i | } | t j o& t | i } | i d h } n h h } } t | d o# | i t i
t | d n | i d h } xt | D] } t | | d } t i | p q n t | d o | i } | | | Type %s must elect an appender method to be a collection classR, R$ s< Type %s must elect a remover method to be a collection classR1 R% s> Type %s must elect an iterator method to be a collection classs _sa_%sN( NN( s fire_append_eventi N( s fire_remove_eventi N( R6 R t
ArgumentErrorR RT t __interfacest copyt popRO t updatet deepcopyR: t dirR; t callableR R+ R0 t itemsR" R5 t _instrument_membership_mutatorR ( R t collection_typet rolest
decoratorsR t namet methodt rolet beforet aftert opt argumentR. R# ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s~
#
" " "
!c s o t t i t i d } t t j o. t | j o | p d n- | j o | i n d ~ n f d } y% t
| _ i | _ i
| _
Wn n X| S( sE Route method args and/or return value through the collection adapter.i c s\ o d j o2 | j o t i d n | } q t | j o | } q | j o | } q t i d n | i d d } | t j o
d } n t | d d d } o! | o t | | | n p | o | | S | | } | d j o t | | | n | Sd S( Ns Missing argument %sR_ i R9 ( R; R R R R Rc R: ( t argst kwR Ra t executort res( t named_argR t pos_argR R R ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR G s0
N( Rh R t flatten_iteratort inspectt
getargspecR@ t intR R; t indexR' R& R5 R7 ( R R R R t fn_argsR ( ( R R R R R R s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR 7 s$ "(
c C sW | t j oF | d j o9 t | d d } | o t | d | | } qS n | S( s: Run set events, may eventually be inlined into decorators.R9 R, N( Rc R; R: ( R R` R_ R ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt __seto s
c C sU | t j oD | d j o7 t | d d } | o t | d | | qQ n d S( s: Run del events, may eventually be inlined into decorators.R9 R1 N( Rc R; R: ( R R` R_ R ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt __delx s c C s4 t | d d } | o t | d | n d S( s5 Special method to run 'commit existing value' methodsR9 Rm N( R: R; ( R R_ R ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt __before_delete s c s d f d } f d } f d } f d } f d } f d } f d } f d } f d
} f d } t i }
|
i d |
S(
s: Tailored instrumentation wrappers for any list-like class.c S s2 t | d t t t t | i d | _ d S( NR& R7 ( R" R' R: Rh R5 R7 ( R# ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt _tidy s c s d f d } | | S( Nc s# t | | | } | | d S( N( R ( RI R` R_ ( R# ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt append s ( R; ( R# R ( R ( R# s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s d f d } | | S( Nc s. t | | | | t | | | d S( N( R R ( RI R R_ ( R# ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt remove s
( R; ( R# R ( R ( R# s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s f d } | | S( Nc s# t | | } | | | d S( N( R ( RI R R ( R# ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt insert s ( ( R# R ( R ( R# s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s f d } | | S( Nc s t | t pK | | } | d j o t | | n t | | } | | | nF| i d j o
d } n1 | i d j o t | | i } n
| i } | i p d } t | i p d | | } | d j oS x | D] } | | i =q W| i } x | D] } | i
| | | d 7} q Wnp t | t | j o& t d t | t | f n x- t | | D] \ } } | i
| | qWd S( Ni i sB attempt to assign sequence of size %s to extended slice of size %s( Rt t sliceR; R R t stopR t stept ranget startR t
ValueErrort zipt __setitem__( RI R R t existingR R t rngt iR` ( R# ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s<
( ( R# R ( R ( R# s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s f d } | | S( Nc sk t | t p( | | } t | | | | n0 x | | D] } t | | qC W | | d S( N( Rt R R ( RI R R` ( R# ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt __delitem__ s
( ( R# R ( R ( R# s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s f d } | | S( Nc
sf x" | | | !D] } t | | q Wg } | D] } | t | | q0 ~ } | | | | d S( N( R R ( RI R t endRS R R ( R# ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt __setslice__ s
*( ( R# R ( R ( R# s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s f d } | | S( Nc s9 x" | | | !D] } t | | q W | | | d S( N( R ( RI R R R ( R# ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt __delslice__ s ( ( R# R ( R ( R# s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s d } | | S( Nc S s" x | D] } | i | q Wd S( N( R ( RI t iterableR ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt extend s ( ( R# R ( R ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s d } | | S( Nc S s" x | D] } | i | q W| S( N( R ( RI R R ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt __iadd__ s ( ( R# R ( R ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s d f d } | | S( Nic s* t | | | } t | | | S( N( R R ( RI R R` ( R# ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
( ( R# R ( R ( R# s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
R ( t localsR R ( R R R R R R R R R R t l( ( R s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt _list_decorators s $
c s d t i d f d } f d } f d } f d } f d } f d } t i d j o f d } n f d } t i } | i d
| i d | S( sB Tailored instrumentation wrappers for any dict-like mapping class.c S s2 t | d t t t t | i d | _ d S( NR& R7 ( R" R' R: RV R5 R7 ( R# ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s t Unspecifiedc s d f d } | | S( Nc sK | | j o t | | | | n t | | | } | | | d S( N( R R ( RI Rn R R_ ( R# ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
( R; ( R# R ( R ( R# s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s d f d } | | S( Nc s6 | | j o t | | | | n | | d S( N( R ( RI Rn R_ ( R# ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
( R; ( R# R ( R ( R# s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s f d } | | S( Nc s0 x | D] } t | | | q W | d S( N( R ( RI Rn ( R# ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt clear& s ( ( R# R ( R ( R# s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR % s
c s# f d } | | S( Nc sQ | | j o t | | | n | j o | | S | | | Sd S( N( R ( RI Rn t default( R R# ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR . s
( ( R# R ( R R ( R# s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR - s
c s f d } | | S( Nc s+ t | | } t | | d | S( Ni ( R R ( RI R` ( R# ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt popitem9 s
( ( R# R ( R ( R# s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR 8 s
c s d d } | | S( Nc S s3 | | j o | i | | | S| i | Sd S( N( R t __getitem__( RI Rn R ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt
setdefaultB s
( R; ( R# R ( R ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR A s
i i c s d } | | S( Nc S sO xH | i D]: } | | j p | | | | j o | | | | /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR M s
"( ( R# R ( R ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR L s
c s f d } | | S( Nc s | j o t | d oO x | i D]: } | | j p | | | | j o | | | | /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR U s
"( ( R# R ( R R ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR T s
R ( i i ( R t symbolt syst version_infoR R R ( R R R R R R R R ( ( R R s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt _dict_decorators s
c C s t | t | i f S( sG Allow only set, frozenset and self.__class__-derived objects in binops.( Rt t _set_binop_basesRU ( RI RX ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt _set_binops_check_strictq s c C s- t | t | i f p t i | t j S( s5 Allow anything set-like to participate in set binops.( Rt R RU R RT t set( RI RX ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt _set_binops_check_looseu s c s+ d t i d } f d } t i d j o f d } n f d } f d } f d } f d
} f d } f d } f d
} f d } f d }
f d } f d } f d }
t i } | i d | i d | S( s9 Tailored instrumentation wrappers for any set-like class.c S s2 t | d t t t t | i d | _ d S( NR& R7 ( R" R' R: R R5 R7 ( R# ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR ~ s R c s d f d } | | S( Nc s4 | | j o t | | | } n | | d S( N( R ( RI R R_ ( R# ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt add s
( R; ( R# R ( R ( R# s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
i i c s d d } | | S( Nc S s% | | j o | i | | n d S( N( R ( RI R R_ ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt discard s
( R; ( R# R ( R ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s d f d } | | S( Nc s2 | | j o t | | | n | | d S( N( R ( RI R R_ ( R# ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
( R; ( R# R ( R ( R# s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s d f d } | | S( Nc s2 | | j o t | | | n | | d S( N( R ( RI R R_ ( R# ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
( R; ( R# R ( R ( R# s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s f d } | | S( Nc s' t | | } t | | | S( N( R R ( RI R` ( R# ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
( ( R# R ( R ( R# s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s d } | | S( Nc S s( x! t | D] } | i | q
Wd S( N( Rh R ( RI R` ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
( ( R# R ( R ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s d } | | S( Nc S s" x | D] } | i | q Wd S( N( R ( RI R R` ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s ( ( R# R ( R ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s d } | | S( Nc S s7 t | | p t Sx | D] } | i | q W| S( N( R t NotImplementedR ( RI R R` ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt __ior__ s ( ( R# R ( R ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s d } | | S( Nc S s" x | D] } | i | q Wd S( N( R ( RI R R` ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt difference_update s ( ( R# R ( R ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s d } | | S( Nc S s7 t | | p t Sx | D] } | i | q W| S( N( R R R ( RI R R` ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt __isub__ s ( ( R# R ( R ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s d } | | S( Nc S sq | i | t | } } | | | | } } x | D] } | i | q8 Wx | D] } | i | qV Wd S( N( Rv R R R ( RI R t wantt haveR R R` ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt intersection_update s ( ( R# R ( R ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s d } | | S( Nc S s t | | p t S| i | t | } } | | | | } } x | D] } | i | qM Wx | D] } | i | qk W| S( N( R R Rv R R R ( RI R R R R R R` ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt __iand__ s ( ( R# R ( R ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s d } | | S( Nc S sq | i | t | } } | | | | } } x | D] } | i | q8 Wx | D] } | i | qV Wd S( N( t symmetric_differenceR R R ( RI R R R R R R` ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt symmetric_difference_update s ( ( R# R ( R ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
c s d } | | S( Nc S s t | | p t S| i | t | } } | | | | } } x | D] } | i | qM Wx | D] } | i | qk W| S( N( R R R R R R ( RI R R R R R R` ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt __ixor__ s ( ( R# R ( R ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
R ( i i ( R R R R R R R ( R R R R R R R R R R R R R R R ( ( R s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt _set_decorators{ s*
t InstrumentedListc B s) e Z d Z h d d 6d d 6d d 6Z RS( s- An instrumented version of the built-in list.R R! R R$ R= R% ( R5 R6 R7 R ( ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
t InstrumentedSetc B s) e Z d Z h d d 6d d 6d d 6Z RS( s, An instrumented version of the built-in set.R R! R R$ R= R% ( R5 R6 R7 R ( ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR s
t InstrumentedDictc B s e Z d Z h d d 6Z RS( s- An instrumented version of the built-in dict.RR R% ( R5 R6 R7 R ( ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR ' s R R! R R$ R= R% R R RR R c B s e Z d Z d Z d d Z e i e Z e i e Z d d Z e i e Z e i
e Z d Z e i e Z RS( s) A basic dictionary-based collection class.
Extends dict with the minimal bag semantics that collection classes require.
``set`` and ``remove`` are implemented in terms of a keying function: any
callable that takes an object and returns an object for use as a dictionary
key.
c C s
| | _ d S( su Create a new collection with keying provided by keyfunc.
keyfunc may be any callable any callable that takes an object and
returns an object for use as a dictionary key.
The keyfunc will be called every time the ORM needs to add a member by
value-only (such as when loading instances from the database) or
remove a member. The usual cautions about dictionary keying apply-
``keyfunc(object)`` should return the same output for the life of the
collection. Keying based on mutable properties can result in
unreachable instances "lost" in the collection.
N( R ( RI R ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyRK M s c C s& | i | } | i | | | d S( s9 Add an item by value, consulting the keyfunc for the key.N( R R ( RI R R_ Rn ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR ] s c C sX | i | } | | | j o$ t i d | | | | f n | i | | d S( s< Remove an item by value, consulting the keyfunc for the key.s Can not remove '%s': collection holds '%s' for key '%s'. Possible cause: is the MappedCollection key function based on mutable properties or properties that only obtain values after flush?N( R R R R ( RI R R_ Rn ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR e s c c sb x[ t i | D]J \ } } | i | } | | j o t d | | | f n | Vq Wd S( s Validate and convert a dict-like object into values for set()ing.
This is called behind the scenes when a MappedCollection is replaced
entirely by another collection, as in::
myobj.mappedcollection = {'a':obj1, 'b': obj2} # ...
Raises a TypeError if the key in any (key, value) pair in the dictlike
object does not match the key that this collection's keyfunc would
have assigned for that value.
sn Found incompatible key %r for value %r; this collection's keying function requires a key of %r for this value.N( R t dictlike_iteritemsR R? ( RI t dictliket incoming_keyR t new_key( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt _convertv s
N(
R5 R6 R7 RK R; R R R( R! R R$ R R* ( ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyR C s (6 R7 R R R R RD t sqlalchemy.exceptionst
exceptionsR t sqlalchemy.sqlR t
sqlalchemyR R t __all__t threadingt LockR R R R t objectR R RA RB R R R R R R; R R R R R t py3kR t frozensetR t setst BaseSetR R R Rh R R RV R R R R ( ( ( s> /usr/lib/python2.6/site-packages/sqlalchemy/orm/collections.pyt a sr % " l 8 `