3 dF@sddlZddlmZddlmZddlmZddlmZddl m Z ddl m Z ddl mZdd lmZd ZGd d d ZGd ddeZGdddeZGdddeZddZd(ddZd)ddZd*ddZd+ddZd,dd Zd-d!d"Zd.d#d$Zejed%d&d'ZdS)/N)anytrait_filter)DictItemObserver)FilteredTraitObserver)ListItemObserver)MetadataFilter)NamedTraitObserver) ObserverGraph)SetItemObserverc@szeZdZdZfZddZddZdddZdd d Zdd d Z dddZ dddZ d ddZ d!ddZ ddZddZdS)"ObserverExpressionaS ObserverExpression is an object for describing what traits are being observed for change notifications. It can be passed directly to ``HasTraits.observe`` method or the ``observe`` decorator. An ObserverExpression is typically created using one of the top-level functions provided in this module, e.g. ``trait``. cCs t||S)av Create a new expression that matches this expression OR the given expression. e.g. ``trait("age") | trait("number")`` will match either trait **age** or trait **number** on an object. Parameters ---------- expression : ObserverExpression Returns ------- new_expression : ObserverExpression )ParallelObserverExpression)self expressionr?/tmp/pip-build-7vycvbft/traits/traits/observation/expression.py__or__)szObserverExpression.__or__cCs t||S)a Create a new expression by extending this expression with the given expression. e.g. ``trait("child").then( trait("age") | trait("number") )`` on an object matches ``child.age`` or ``child.number`` on the object. Parameters ---------- expression : ObserverExpression Returns ------- new_expression : ObserverExpression )SeriesObserverExpression)r rrrrthen:szObserverExpression.thenTcCs|jt||dS)a- Create a new expression for observing traits using the given filter. Events emitted (if any) will be instances of :class:`~traits.observation.events.TraitChangeEvent`. Parameters ---------- filter : callable(str, CTrait) -> bool A callable that receives the name of a trait and the corresponding trait definition. The returned bool indicates whether the trait is observed. In order to remove an existing observer with the equivalent filter, the filter callables must compare equally. The callable must also be hashable. notify : bool, optional Whether to notify for changes. Default is to notify. Returns ------- new_expression : ObserverExpression )filternotify)rmatch)r rrrrrrKszObserverExpression.matchcCs|jt|dS)a Create a new expression for observing all traits. Events emitted (if any) will be instances of :class:`~traits.observation.events.TraitChangeEvent`. Parameters ---------- notify : bool, optional Whether to notify for changes. Default is to notify. Returns ------- new_expression : ObserverExpression )rr)rr)r rrrranytraitcszObserverExpression.anytraitcCs|jt|d|dS)af Return a new expression for observing traits where the given metadata is not None. Events emitted (if any) will be instances of :class:`~traits.observation.events.TraitChangeEvent`. e.g. ``metadata("age")`` matches traits whose 'age' attribute has a non-None value. Parameters ---------- metadata_name : str Name of the metadata to filter traits with. notify : bool, optional Whether to notify for changes. Default is to notify. Returns ------- new_expression : ObserverExpression ) metadata_name)rr)rr)r rrrrrmetadatatszObserverExpression.metadataFcCs|jt||dS)a Create a new expression for observing items inside a dict. Events emitted (if any) will be instances of :class:`~traits.observation.events.DictChangeEvent`. If an expression with ``dict_items`` is further extended, the **values** of the dict will be given to the next item in the expression. For example, the following observes a trait named "number" on any object that is one of the values in the dict named "mapping":: trait("mapping").dict_items().trait("number") Parameters ---------- notify : bool, optional Whether to notify for changes. Default is to notify. optional : bool, optional Whether to ignore this if the upstream object is not a dict. Default is false and an error will be raised if the object is not a dict. Returns ------- new_expression : ObserverExpression )roptional)r dict_items)r rrrrrrszObserverExpression.dict_itemscCs|jt||dS)aa Create a new expression for observing items inside a list. Events emitted (if any) will be instances of :class:`~traits.observation.events.ListChangeEvent`. e.g. ``trait("containers").list_items()`` for observing mutations to a list named ``containers``. e.g. ``trait("containers").list_items().trait("value")`` for observing the trait ``value`` on any items in the list ``containers``. Parameters ---------- notify : bool, optional Whether to notify for changes. Default is to notify. optional : bool, optional Whether to ignore this if the upstream object is not a list. Default is false and an error will be raised if the object is not a list. Returns ------- new_expression : ObserverExpression )rr)r list_items)r rrrrrrszObserverExpression.list_itemscCs|jt||dS)aU Create a new expression for observing items inside a set. Events emitted (if any) will be instances of :class:`~traits.observation.events.SetChangeEvent`. Parameters ---------- notify : bool, optional Whether to notify for changes. Default is to notify. optional : bool, optional Whether to ignore this if the upstream object is not a set. Default is false and an error will be raised if the object is not a set. Returns ------- new_expression : ObserverExpression )rr)r set_items)r rrrrrrszObserverExpression.set_itemscCs|jt|||dS)a Create a new expression for observing a trait with the exact name given. Events emitted (if any) will be instances of :class:`~traits.observation.events.TraitChangeEvent`. Parameters ---------- name : str Name of the trait to match. notify : bool, optional Whether to notify for changes. Default is to notify. optional : bool, optional If true, skip this observer if the requested trait is not found. Default is false, and an error will be raised if the requested trait is not found. Returns ------- new_expression : ObserverExpression )namerr)rtrait)r rrrrrrrszObserverExpression.traitcCs |jgdS)a^ Return all the ObserverGraph for the observer framework to attach notifiers. This is considered private to the users and to modules outside of the ``observation`` subpackage, but public to modules within the ``observation`` subpackage. Returns ------- graphs : list of ObserverGraph )branches)_create_graphs)r rrr _as_graphss zObserverExpression._as_graphscCs tddS)a Return a list of ObserverGraph with the given branches. Parameters ---------- branches : list of ObserverGraph Graphs to be used as branches. Returns ------- graphs : list of ObserverGraph z%'_create_graphs' must be implemented.N)NotImplementedError)r r rrrr!s z!ObserverExpression._create_graphsN)T)T)T)TF)TF)TF)TF)__name__ __module__ __qualname____doc__ __slots__rrrrrrrrrr"r!rrrrr s       r c@s4eZdZdZd ZddZddZddZd d Zd S) SingleObserverExpressionzE Container of ObserverExpression for wrapping a single observer. _observercCs ||_dS)N)r*)r observerrrr__init__sz!SingleObserverExpression.__init__cCstt|j|jfS)N)hashtyper$r*)r rrr__hash__sz!SingleObserverExpression.__hash__cCst|t|ko|j|jkS)N)r.r*)r otherrrr__eq__szSingleObserverExpression.__eq__cCst|j|dgS)N)nodechildren)rr*)r r rrrr!!sz'SingleObserverExpression._create_graphsN)r*) r$r%r&r'r(r,r/r1r!rrrrr)s r)c@s4eZdZdZd ZddZddZdd Zd d Zd S)ra Container of ObserverExpression for joining expressions in series. Parameters ---------- first : ObserverExpression Left expression to be joined in series. second : ObserverExpression Right expression to be joined in series. _first_secondcCs||_||_dS)N)r4r5)r firstsecondrrrr,4sz!SeriesObserverExpression.__init__cCstt|j|j|jfS)N)r-r.r$r4r5)r rrrr/8sz!SeriesObserverExpression.__hash__cCs(t|t|ko&|j|jko&|j|jkS)N)r.r4r5)r r0rrrr1;s zSeriesObserverExpression.__eq__cCs|jj|d}|jj|dS)N)r )r5r!r4)r r rrrr!Bsz'SeriesObserverExpression._create_graphsN)r4r5) r$r%r&r'r(r,r/r1r!rrrrr's  rc@s4eZdZdZd ZddZddZdd Zd d Zd S)r a  Container of ObserverExpression for joining expressions in parallel. Parameters ---------- left : ObserverExpression Left expression to be joined in parallel. right : ObserverExpression Right expression to be joined in parallel. _left_rightcCs||_||_dS)N)r8r9)r leftrightrrrr,Tsz#ParallelObserverExpression.__init__cCstt|j|j|jfS)N)r-r.r$r8r9)r rrrr/Xsz#ParallelObserverExpression.__hash__cCs(t|t|ko&|j|jko&|j|jkS)N)r.r8r9)r r0rrrr1[s z!ParallelObserverExpression.__eq__cCs$|jj|d}|jj|d}||S)N)r )r8r!r9)r r Z left_graphsZ right_graphsrrrr!bsz)ParallelObserverExpression._create_graphsN)r8r9) r$r%r&r'r(r,r/r1r!rrrrr Gs  r cGstjdd|S)a Convenient function for joining many expressions in series using ``ObserverExpression.then`` Parameters ---------- *expressions : iterable of ObserverExpression Returns ------- new_expression : ObserverExpression Joined expression. cSs |j|S)N)r)Ze1e2rrruszjoin..) functoolsreduce)Z expressionsrrrjoinhs r@TFcCst||d}t|S)aq Create a new expression for observing items inside a dict. Events emitted (if any) will be instances of :class:`~traits.observation.events.DictChangeEvent`. If an expression with ``dict_items`` is further extended, the **values** of the dict will be given to the next item in the expression. For example, the following observes a trait named "number" on any object that is one of the values in the dict named "mapping":: trait("mapping").dict_items().trait("number") Parameters ---------- notify : bool, optional Whether to notify for changes. Default is to notify. optional : bool, optional Whether to ignore this if the upstream object is not a dict. Default is false and an error will be raised if the object is not a dict. Returns ------- new_expression : ObserverExpression )rr)rr))rrr+rrrrxs rcCst||d}t|S)a Create a new expression for observing items inside a list. Events emitted (if any) will be instances of :class:`~traits.observation.events.ListChangeEvent`. e.g. ``trait("containers").list_items()`` for observing mutations to a list named ``containers``. e.g. ``trait("containers").list_items().trait("value")`` for observing the trait ``value`` on any items in the list ``containers``. Parameters ---------- notify : bool, optional Whether to notify for changes. Default is to notify. optional : bool, optional Whether to ignore this if the upstream object is not a list. Default is false and an error will be raised if the object is not a list. Returns ------- new_expression : ObserverExpression )rr)rr))rrr+rrrrs rcCst||d}t|S)a Create a new expression for observing traits using the given filter. Events emitted (if any) will be instances of :class:`~traits.observation.events.TraitChangeEvent`. Parameters ---------- filter : callable(str, CTrait) -> bool A callable that receives the name of a trait and the corresponding trait definition. The returned bool indicates whether the trait is observed. In order to remove an existing observer with the equivalent filter, the filter callables must compare equally. The callable must also be hashable. notify : bool, optional Whether to notify for changes. Returns ------- new_expression : ObserverExpression )rr)rr))rrr+rrrrs rcCst|td}t|S)a Create a new expression for observing all traits on an object. Events emitted (if any) will be instances of :class:`~traits.observation.events.TraitChangeEvent`. Parameters ---------- notify : bool, optional Whether to notify for changes. )rr)rrr))rr+rrrrs rcCstt|d|dS)a* Return a new expression for observing traits where the given metadata is not None. Events emitted (if any) will be instances of :class:`~traits.observation.events.TraitChangeEvent`. e.g. ``metadata("age")`` matches traits whose 'age' attribute has a non-None value. Parameters ---------- metadata_name : str Name of the metadata to filter traits with. notify : bool, optional Whether to notify for changes. Default is to notify. Returns ------- new_expression : ObserverExpression )r)rr)rr)rrrrrrsrcCst||d}t|S)a Create a new expression for observing items inside a set. Events emitted (if any) will be instances of :class:`~traits.observation.events.SetChangeEvent`. Parameters ---------- notify : bool, optional Whether to notify for changes. Default is to notify. optional : bool, optional Whether to ignore this if the upstream object is not a set. Default is false and an error will be raised if the object is not a set. Returns ------- new_expression : ObserverExpression )rr)r r))rrr+rrrrs rcCst|||d}t|S)at Create a new expression for observing a trait with the exact name given. Events emitted (if any) will be instances of :class:`~traits.observation.events.TraitChangeEvent`. Parameters ---------- name : str Name of the trait to match. notify : bool, optional Whether to notify for changes. Default is to notify. optional : bool, optional If true, skip this observer if the requested trait is not found. Default is false, and an error will be raised if the requested trait is not found. Returns ------- new_expression : ObserverExpression )rrr)rr))rrrr+rrrrs r)maxsizecCs|jS)z Compile an ObserverExpression to a list of ObserverGraphs. Parameters ---------- expr : ObserverExpression Returns ------- list of ObserverGraph )r")exprrrr compile_expr)s rC)TF)TF)T)T)T)TF)TF) r>Z#traits.observation._anytrait_filterrZ&traits.observation._dict_item_observerrZ+traits.observation._filtered_trait_observerrZ&traits.observation._list_item_observerrZ#traits.observation._metadata_filterrZ(traits.observation._named_trait_observerrZ"traits.observation._observer_graphrZ%traits.observation._set_item_observerr Z"_OBSERVER_EXPRESSION_CACHE_MAXSIZEr r)rr r@rrrrrrr lru_cacherCrrrr s.        s !