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)

Handles a traits 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)

Handles a traits notification exception using the handler last pushed.

Parameters

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

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.

__eq__(other)

Return true if the other value is an ObserverExpression with equivalent content.

Returns

Return type

bool

__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

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: traits.observation.expression.ObserverExpression

Container of ObserverExpression for wrapping a single observer.

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

Bases: traits.observation.expression.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.

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

Bases: traits.observation.expression.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.

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.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.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