traits.observation Package

traits.observation.exception_handling Module

class traits.observation.exception_handling.ObserverExceptionHandler(handler, reraise_exceptions)

Bases: object

State for an exception handler.

Parameters:

• handler (callable(event) or None) – A callable to handle an event, in the context of an exception. If None, the exceptions will be logged.

• reraise_exceptions (boolean) – Whether to reraise the exception.

class traits.observation.exception_handling.ObserverExceptionHandlerStack

Bases: object

A stack of exception handlers.

Parameters:

handlers (list of ObserverExceptionHandler) – The last item is the current handler.

push_exception_handler(handler=None, reraise_exceptions=False)

Push a new exception handler into the stack. Making it the current exception handler.

Parameters:

• handler (callable(event) or None) – A callable to handle an event, in the context of an exception. If None, the exceptions will be logged.

• reraise_exceptions (boolean) – Whether to reraise the exception.

pop_exception_handler()

Pop the current exception handler from the stack.

Raises:

IndexError – If there are no handlers to pop.

handle_exception(event)

Handle a notification exception using the handler last pushed.

Parameters:

event (object) – An event object emitted by the notification.

traits.observation.exception_handling.push_exception_handler(handler=None, reraise_exceptions=False)

Push a new exception handler into the stack. Making it the current exception handler.

Parameters:

• handler (callable(event) or None) – A callable to handle an event, in the context of an exception. If None, the exceptions will be logged.

• reraise_exceptions (boolean) – Whether to reraise the exception.

traits.observation.exception_handling.pop_exception_handler()

Pop the current exception handler from the stack.

Raises:

IndexError – If there are no handlers to pop.

traits.observation.exception_handling.handle_exception(event)

Handle a notification exception using the handler last pushed.

Parameters:

event (object) – An event object emitted by the notification.

traits.observation.exceptions Module

exception traits.observation.exceptions.NotifierNotFound

Bases: Exception

Raised when a notifier cannot be found.

traits.observation.api Module

traits.observation.expression Module

class traits.observation.expression.ObserverExpression

Bases: object

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.

__or__(expression)

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

Return type:

ObserverExpression

then(expression)

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

Return type:

ObserverExpression

match(filter, notify=True)

Create a new expression for observing traits using the given filter.

Events emitted (if any) will be instances of 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

Return type:

ObserverExpression

anytrait(notify=True)

Create a new expression for observing all traits.

Events emitted (if any) will be instances of TraitChangeEvent.

Parameters:

notify (bool, optional) – Whether to notify for changes. Default is to notify.

Returns:

new_expression

Return type:

ObserverExpression

metadata(metadata_name, notify=True)

Return a new expression for observing traits where the given metadata is not None.

Events emitted (if any) will be instances of 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

Return type:

ObserverExpression

dict_items(notify=True, optional=False)

Create a new expression for observing items inside a dict.

Events emitted (if any) will be instances of 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

Return type:

ObserverExpression

list_items(notify=True, optional=False)

Create a new expression for observing items inside a list.

Events emitted (if any) will be instances of 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

Return type:

ObserverExpression

set_items(notify=True, optional=False)

Create a new expression for observing items inside a set.

Events emitted (if any) will be instances of 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

Return type:

ObserverExpression

trait(name, notify=True, optional=False)

Create a new expression for observing a trait with the exact name given.

Events emitted (if any) will be instances of 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

Return type:

ObserverExpression

class traits.observation.expression.SingleObserverExpression(observer)

Bases: ObserverExpression

Container of ObserverExpression for wrapping a single observer.

__eq__(other)

Return self==value.

class traits.observation.expression.SeriesObserverExpression(first, second)

Bases: ObserverExpression

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.

__eq__(other)

Return self==value.

class traits.observation.expression.ParallelObserverExpression(left, right)

Bases: ObserverExpression

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.

__eq__(other)

Return self==value.

traits.observation.expression.join(*expressions)

Convenient function for joining many expressions in series using ObserverExpression.then

Parameters:

*expressions (iterable of ObserverExpression)

Returns:

new_expression – Joined expression.

Return type:

ObserverExpression

traits.observation.expression.dict_items(notify=True, optional=False)

Create a new expression for observing items inside a dict.

Events emitted (if any) will be instances of 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

Return type:

ObserverExpression

traits.observation.expression.list_items(notify=True, optional=False)

Create a new expression for observing items inside a list.

Events emitted (if any) will be instances of 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

Return type:

ObserverExpression

traits.observation.expression.match(filter, notify=True)

Create a new expression for observing traits using the given filter.

Events emitted (if any) will be instances of 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

Return type:

ObserverExpression

traits.observation.expression.anytrait(notify=True)

Create a new expression for observing all traits on an object.

Events emitted (if any) will be instances of TraitChangeEvent.

Parameters:

notify (bool, optional) – Whether to notify for changes.

traits.observation.expression.metadata(metadata_name, notify=True)

Return a new expression for observing traits where the given metadata is not None.

Events emitted (if any) will be instances of 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

Return type:

ObserverExpression

traits.observation.expression.set_items(notify=True, optional=False)

Create a new expression for observing items inside a set.

Events emitted (if any) will be instances of 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

Return type:

ObserverExpression

traits.observation.expression.trait(name, notify=True, optional=False)

Create a new expression for observing a trait with the exact name given.

Events emitted (if any) will be instances of 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

Return type:

ObserverExpression

traits.observation.expression.compile_expr(expr)

Compile an ObserverExpression to a list of ObserverGraphs.

Parameters:

expr (ObserverExpression)

Return type:

list of ObserverGraph

traits.observation.events Module

Event objects received by change handlers added using observe.

class traits.observation.events.DictChangeEvent(*, object, removed, added)

Event object to represent mutations on a dict.

Note that the API is different from the TraitDictEvent emitted via the “name _items” trait. In particular, the attribute changed is not defined here.

The interface of this object is provisional as of version 6.1.

object

The dict being mutated.

Type:

traits.trait_dict_object.TraitDict

removed

Keys and values for removed or updated items. If keys are found in added as well, they refer to updated items and the values are old.

Type:

dict

added

Keys and values for added or updated items. If keys are found in removed as well, they refer to updated items and the values are new.

Type:

dict

class traits.observation.events.ListChangeEvent(*, object, index, removed, added)

Event object to represent mutations to a list.

The interface of this object is provisional as of version 6.1.

object

The list being mutated.

Type:

traits.trait_list_object.TraitList

index

The index used for the mutation.

Type:

int or slice

added

Values added to the list.

Type:

list

removed

Values removed from the list.

Type:

list

class traits.observation.events.SetChangeEvent(*, object, removed, added)

Event object to represent mutations on a set.

The interface of this object is provisional as of version 6.1.

object

The set being mutated.

Type:

traits.trait_set_object.TraitSet

removed

Values removed from the set.

Type:

set

added

Values added to the set.

Type:

set

class traits.observation.events.TraitChangeEvent(*, object, name, old, new)

Emitted when a trait on a HasTraits object is changed.

The interface of this object is provisional as of version 6.1.

object

Object on which a trait is changed.

Type:

HasTraits

name

Name of the trait.

Type:

str

old

The old value.

Type:

any

new

The new value.

Type:

any

traits.observation.parsing Module

traits.observation.parsing.parse(text)

Top-level function for parsing user’s text to an ObserverExpression.

Parameters:

text (str) – Text to be parsed.

Returns:

expression

Return type:

ObserverExpression

Raises:

ValueError – If the text is not a valid observe expression.

traits.observation.parsing.compile_str(text)

Compile a mini-language string to a list of ObserverGraph objects.

Parameters:

text (str) – Text to be parsed.

Return type:

list of ObserverGraph