atom.api module

Module exporting the public interface to atom.

class atom.api.Atom

Bases: CAtom

The base class for defining atom objects.

Atom objects are special Python objects which never allocate an instance dictionary unless one is explicitly requested. The storage for an atom is instead computed from the Member objects declared on the class. Memory is reserved for these members with no over allocation.

This restriction make atom objects a bit less flexible than normal Python objects, but they are between 3x-10x more memory efficient than normal objects depending on the number of attributes.

classmethod members() → Mapping[str, Member]

Get the members dictionary for the type.

Returns:

result – The dictionary of members defined on the class. User code should not modify the contents of the dict.

Return type:

Mapping[str, Member]

suppress_notifications() → Iterator[None]

Disable member notifications within in a context.

Returns:

result – A context manager which disables atom notifications for the duration of the context. When the context exits, the state is restored to its previous value.

Return type:

contextmanager

class atom.api.AtomMeta(name: str, bases: Tuple[type, ...], dct: Dict[str, Any], enable_weakrefs: bool = False, use_annotations: bool = True, type_containers: int = 1)

Bases: type

The metaclass for classes derived from Atom.

This metaclass computes the memory layout of the members in a given class so that the CAtom class can allocate exactly enough space for the object data slots when it instantiates an object.

All classes deriving from Atom will be automatically slotted, which will prevent the creation of an instance dictionary and also the ability of an Atom to be weakly referenceable. If that behavior is required, then a subclasss should declare the appropriate slots.

class atom.api.Bool(default=False, *, factory=None)

Bases: Value

A value of type bool.

class atom.api.Bytes(default=b'', *, factory=None, strict=True)

Bases: Value

A value of type bytes.

By default, strings will NOT be promoted to bytes. Pass strict=False to the constructor to enable loose byte checking.

class atom.api.CAtom

Bases: object

freeze()

Freeze the atom to prevent further modifications to its attributes.

get_member()

Get the named member for the atom.

has_observer()

Get whether the atom has the given observer for a given topic.

has_observers()

Get whether the atom has observers for a given topic.

notifications_enabled()

Get whether notification is enabled for the atom.

notify()

Call the registered observers for a given topic with positional and keyword arguments.

observe()

Register an observer callback to observe changes on the given topic(s).

set_notifications_enabled()

Enable or disable notifications for the atom.

unobserve()

Unregister an observer callback for the given topic(s).

class atom.api.Callable(default=None, *, factory=None)

Bases: Value

A value which is callable.

class atom.api.ChangeDict

Bases: dict

count: int

index: int

item: Any

key: Any

name: str

newitem: Any

object: Atom

olditem: Any

oldvalue: Any

operation: Literal['reverse'] | Literal['__delitem__'] | Literal['__iadd__'] | Literal['__imul__'] | Literal['__setitem__'] | Literal['append'] | Literal['extend'] | Literal['insert'] | Literal['pop'] | Literal['remove'] | Literal['sort']

reverse: bool

type: Literal['create'] | Literal['update'] | Literal['delete'] | Literal['event'] | Literal['property'] | Literal['container']

value: Any

class atom.api.ChangeType(value)

Bases: IntFlag

An enumeration.

ANY = 255

CONTAINER = 32

CREATE = 1

DELETE = 4

EVENT = 8

PROPERTY = 16

UPDATE = 2

class atom.api.Coerced(kind, args=None, kwargs=None, *, factory=None, coercer=None)

Bases: Member

A member which will coerce a value to a given instance type.

Unlike Typed or Instance, a Coerced value is not intended to be set to None.

class atom.api.Constant(default=None, *, factory=None, kind=None)

Bases: Value

A value which cannot be changed from its default.

class atom.api.ContainerList(item=None, default=None)

Bases: List

A List member which supports container notifications.

class atom.api.DefaultDict(key=None, value=None, default=None, *, missing=None)

Bases: Member

A value of type dict implementing __missing__

clone()

Create a clone of the member.

This will clone the internal dict key and value members if they exist.

set_index(index)

Assign the index to this member.

This method is called by the Atom metaclass when a class is created. This makes sure the index of the internal members are also updated.

set_name(name)

Assign the name to this member.

This method is called by the Atom metaclass when a class is created. This makes sure the name of the internal members are also updated.

class atom.api.DefaultValue(value)

Bases: IntEnum

An enumeration.

CallObject = 8

CallObject_Object = 9

CallObject_ObjectName = 10

DefaultDict = 5

Delegate = 7

Dict = 4

List = 2

MemberMethod_Object = 13

NoOp = 0

NonOptional = 6

ObjectMethod = 11

ObjectMethod_Name = 12

Set = 3

Static = 1

class atom.api.Delegator(delegate)

Bases: Member

A member subclass which delegates all work to a wrapped member.

The only behaviors not delegated are GetAttr and SetAttr. Subclasses should override behavior as needed to suit their needs. In order to change a particular mode, the relevant change method must be called via super(Delegator, …).

add_static_observer(observer)

Add a static observer to the member.

This method also adds the static observer to the delegate.

clone()

Create a clone of the declarative property.

This method also creates a clone of the internal delegate for mode handlers which use the original delegate as the context.

delegate

remove_static_observer(observer)

Remove a static observer from the member.

This method also removes the static observer from the delegate.

set_default_value_mode(mode, context)

Set the default value mode for the member.

This method proxies the change to the delegate member.

set_index(index)

Assign the index to this member.

This method keeps the index of the delegate member in sync.

set_name(name)

Assign the name to this member.

This method keeps the name of the delegate member in sync.

set_post_getattr_mode(mode, context)

Set the post getattr mode for the member.

This method proxies the change to the delegate member.

set_post_setattr_mode(mode, context)

Set the post getattr mode for the member.

This method proxies the change to the delegate member.

set_post_validate_mode(mode, context)

Set the default value mode for the member.

This method proxies the change to the delegate member.

set_validate_mode(mode, context)

Set the default value mode for the member.

This method proxies the change to the delegate member.

class atom.api.Dict(key=None, value=None, default=None)

Bases: Member

A value of type dict.

clone()

Create a clone of the member.

This will clone the internal dict key and value members if they exist.

set_index(index)

Assign the index to this member.

This method is called by the Atom metaclass when a class is created. This makes sure the index of the internal members are also updated.

set_name(name)

Assign the name to this member.

This method is called by the Atom metaclass when a class is created. This makes sure the name of the internal members are also updated.

class atom.api.Enum(*items)

Bases: Member

A member where the value can be one in a sequence of items.

added(*items)

Create a clone of the Enum with added items.

Parameters:

*items – Additional items to include in the Enum.

Returns:

result – A new enum object which contains all of the original items plus the new items.

Return type:

Enum

property items

A readonly property which returns the items in the enum.

removed(*items)

Create a clone of the Enum with some items removed.

Parameters:

*items – The items to remove remove from the new enum.

Returns:

result – A new enum object which contains all of the original items but with the given items removed.

Return type:

Enum

class atom.api.Event(kind=None)

Bases: Member

A member which acts like a stateless event.

set_index(index)

A reimplemented parent class method.

This method ensures that the delegate index is also set, if a delegate validator is being used.

set_name(name)

A reimplemented parent class method.

This method ensures that the delegate name is also set, if a delegate validator is being used.

class atom.api.Float(default=0.0, *, factory=None, strict=False)

Bases: Value

A value of type float.

By default, ints and longs will be promoted to floats. Pass strict=True to the constructor to enable strict float checking.

class atom.api.FloatRange(low=None, high=None, value=None, *, strict=False)

Bases: Value

A float value clipped to a range.

By default, ints and longs will be promoted to floats. Pass strict=True to the constructor to enable strict float checking.

class atom.api.ForwardInstance(resolve, args=None, kwargs=None, *, factory=None, optional=None)

Bases: Instance

An Instance which delays resolving the type definition.

The first time the value is accessed or modified, the type will be resolved and the forward instance will behave identically to a normal instance.

args

clone()

Create a clone of the ForwardInstance object.

default(owner)

Called to retrieve the default value.

This is called the first time the default value is retrieved for the member. It resolves the type and updates the internal default handler to behave like a normal Instance member.

kwargs

optional

resolve

validate(owner, old, new)

Called to validate the value.

This is called the first time a value is validated for the member. It resolves the type and updates the internal validate handler to behave like a normal Instance member.

class atom.api.ForwardSubclass(resolve)

Bases: Subclass

A Subclass which delays resolving the type definition.

The first time the value is accessed or modified, the type will be resolved and the forward subclass will behave identically to a normal subclass.

clone()

Create a clone of the ForwardSubclass object.

default(owner)

Called to retrieve the default value.

This is called the first time the default value is retrieved for the member. It resolves the type and updates the internal default handler to behave like a normal Subclass member.

resolve

validate(owner, old, new)

Called to validate the value.

This is called the first time a value is validated for the member. It resolves the type and updates the internal validate handler to behave like a normal Subclass member.

class atom.api.ForwardTyped(resolve, args=None, kwargs=None, *, factory=None, optional=None)

Bases: Typed

A Typed which delays resolving the type definition.

The first time the value is accessed or modified, the type will be resolved and the forward typed will behave identically to a normal typed.

args

clone()

Create a clone of the ForwardTyped instance.

default(owner)

Called to retrieve the default value.

This is called the first time the default value is retrieved for the member. It resolves the type and updates the internal default handler to behave like a normal Typed member.

kwargs

optional

resolve

validate(owner, old, new)

Called to validate the value.

This is called the first time a value is validated for the member. It resolves the type and updates the internal validate handler to behave like a normal Typed member.

class atom.api.GetAttr(value)

Bases: IntEnum

An enumeration.

CachedProperty = 6

CallObject_Object = 7

CallObject_ObjectName = 8

Delegate = 4

Event = 2

MemberMethod_Object = 11

NoOp = 0

ObjectMethod = 9

ObjectMethod_Name = 10

Property = 5

Signal = 3

Slot = 1

class atom.api.GetState(value)

Bases: IntEnum

An enumeration.

Exclude = 1

Include = 0

IncludeNonDefault = 2

MemberMethod_Object = 5

ObjectMethod_Name = 4

Property = 3

class atom.api.Instance(kind, args=None, kwargs=None, *, factory=None, optional=None)

Bases: Member

A value which allows objects of a given type or types.

Values will be tested using the PyObject_IsInstance C API call. This call is equivalent to isinstance(value, kind) and all the same rules apply.

If optional is True, the value of an Instance may be set to None, otherwise None is not considered as a valid value. By default, optional will be considered False if a default value is provided and True otherwise.

class atom.api.Int(default=0, *, factory=None, strict=True)

Bases: Value

A value of type int.

By default, ints are strictly typed. Pass strict=False to the constructor to enable int casting for longs and floats.

class atom.api.List(item=None, default=None)

Bases: Member

A member which allows list values.

Assigning to a list creates a copy. The orginal list will remain unmodified. This is similar to the semantics of the assignment operator on the C++ STL container classes.

clone()

Create a clone of the list.

This will clone the internal list item if one is in use.

item

set_index(index)

Assign the index to this member.

This method ensures that the item member index is also updated.

set_name(name)

Set the name of the member.

This method ensures that the item member name is also updated.

class atom.api.Member

Bases: object

add_static_observer()

Add the name of a method to call on all atoms when the member changes.

clone()

Create a clone of this member.

copy_static_observers()

Copy the static observers from one member into this member.

default_value_mode

Get the default value mode for the member.

del_slot()

Delete the atom’s slot value directly.

delattr_mode

Get the delattr mode for the member.

do_default_value()

Run the default value handler for member.

do_delattr()

Run the delattr handler for the member.

do_full_validate()

Run the validation and post validation handlers for the member.

do_getattr()

Run the getattr handler for the member.

do_post_getattr()

Run the post getattr handler for the member.

do_post_setattr()

Run the post setattr handler for the member.

do_post_validate()

Run the post validation handler for the member.

do_setattr()

Run the setattr handler for the member.

do_should_getstate()

Run the validation and post validation handlers for the member.

do_validate()

Run the validation handler for the member.

get_slot()

Get the atom’s slot value directly.

getattr_mode

Get the getattr mode for the member.

getstate_mode

Get the getstate mode for the member

has_observer()

Get whether or not the member already has the given observer.

has_observers()

Get whether or not this member has observers.

index

Get the index to which the member is bound

metadata

Get and set the metadata for the member.

name

Get the name to which the member is bound.

notify()

Notify the static observers for the given member and atom.

post_getattr_mode

Get the post getattr mode for the member.

post_setattr_mode

Get the post setattr mode for the member.

post_validate_mode

Get the post validate mode for the member.

remove_static_observer()

Remove the name of a method to call on all atoms when the member changes.

set_default_value_mode()

Set the default value mode for the member.

set_delattr_mode()

Set the delattr mode for the member.

set_getattr_mode()

Set the getattr mode for the member.

set_getstate_mode()

Set the getstate mode for the member.

set_index()

Set the index to which the member is bound. Use with extreme caution!

set_name()

Set the name to which the member is bound. Use with extreme caution!

set_post_getattr_mode()

Set the post getattr mode for the member.

set_post_setattr_mode()

Set the post setattr mode for the member.

set_post_validate_mode()

Set the post validate mode for the member.

set_setattr_mode()

Set the setattr mode for the member.

set_slot()

Set the atom’s slot value directly.

set_validate_mode()

Set the validate mode for the member.

setattr_mode

Get the setattr mode for the member.

static_observers()

Get a tuple of the static observers defined for this member

tag()

Tag the member with metatdata.

validate_mode

Get the validate mode for the member.

exception atom.api.MissingMemberWarning

Bases: UserWarning

Signal an expected member is not present.

class atom.api.PostGetAttr(value)

Bases: IntEnum

An enumeration.

Delegate = 1

MemberMethod_ObjectValue = 4

NoOp = 0

ObjectMethod_NameValue = 3

ObjectMethod_Value = 2

class atom.api.PostSetAttr(value)

Bases: IntEnum

An enumeration.

Delegate = 1

MemberMethod_ObjectOldNew = 4

NoOp = 0

ObjectMethod_NameOldNew = 3

ObjectMethod_OldNew = 2

class atom.api.PostValidate(value)

Bases: IntEnum

An enumeration.

Delegate = 1

MemberMethod_ObjectOldNew = 4

NoOp = 0

ObjectMethod_NameOldNew = 3

ObjectMethod_OldNew = 2

class atom.api.Property(fget=None, fset=None, fdel=None, cached=False)

Bases: Member

A Member which behaves similar to a Python property.

property cached

Test whether or not this is a cached property.

deleter(func)

Use the given function as the property deleter.

This method is intended to be used as a decorator. The original function will still be callable.

property fdel

Get the deleter function for the property.

This will not find a specially named _del_* function.

property fget

Get the getter function for the property.

This will not find a specially named _get_* function.

property fset

Get the setter function for the property.

This will not find a specially named _set_* function.

getter(func)

Use the given function as the property getter.

This method is intended to be used as a decorator. The original function will still be callable.

reset(owner)

Reset the value of the property.

The old property value will be cleared and the notifiers will be run if the new value is different from the old value. If the property is not cached, notifiers will be unconditionally run using None as the old value.

setter(func)

Use the given function as the property setter.

This method is intended to be used as a decorator. The original function will still be callable.

class atom.api.Range(low=None, high=None, value=None)

Bases: Value

An integer value clipped to a range.

class atom.api.ReadOnly(kind=None, *, default=None, factory=None)

Bases: Value

A value which can be assigned once and is then read-only.

class atom.api.Set(item=None, default=None)

Bases: Member

A member which allows set values.

Assigning to a set creates a copy. The original set will remain unmodified. This is similar to the semantics of the assignment operator on the C++ STL container classes.

clone()

Create a clone of the member.

This will clone the internal set item members if they exist.

item

set_index(index)

Assign the index to this member.

This method is called by the Atom metaclass when a class is created. This makes sure the index of the internal members are also updated.

set_name(name)

Assign the name to this member.

This method is called by the Atom metaclass when a class is created. This makes sure the name of the internal members are also updated.

class atom.api.SetAttr(value)

Bases: IntEnum

An enumeration.

CallObject_ObjectNameValue = 9

CallObject_ObjectValue = 8

Constant = 2

Delegate = 6

Event = 4

MemberMethod_ObjectValue = 12

NoOp = 0

ObjectMethod_NameValue = 11

ObjectMethod_Value = 10

Property = 7

ReadOnly = 3

Signal = 5

Slot = 1

class atom.api.Signal

Bases: Member

A member which acts similar to a Qt signal.

class atom.api.Str(default='', *, factory=None, strict=True)

Bases: Value

A value of type str.

By default, bytes will NOT be promoted to strings. Pass strict=False to the constructor to enable loose string checking.

class atom.api.Subclass(kind, default=None)

Bases: Member

A value which allows objects subtypes of a given type.

Values will be tested using the PyObject_IsSubclass C API call. This call is equivalent to issubclass(value, kind) and all the same rules apply.

A Subclass member cannot be set to None.

class atom.api.Tuple(item=None, default=())

Bases: Member

A member which allows tuple values.

If item validation is used, then assignment will create a copy of the original tuple before validating the items, since validation may change the item values.

clone()

Create a clone of the tuple.

This will clone the internal tuple item if one is in use.

item

set_index(index)

Assign the index to this member.

This method ensures that the item member index is also updated.

set_name(name)

Set the name of the member.

This method ensures that the item member name is also updated.

class atom.api.Typed(kind, args=None, kwargs=None, *, factory=None, optional=None)

Bases: Member

A value which allows objects of a given type or types.

Values will be tested using the PyObject_TypeCheck C API call. This call is equivalent to type(obj) in cls.mro(). It is less flexible but can be faster than Instance. Use Instance when allowing you need a tuple of types or (abstract) types relying on custom __isinstancecheck__ and Typed when the value type is explicit.

If optional is True, the value of a Typed may be set to None, otherwise None is not considered as a valid value.

class atom.api.Validate(value)

Bases: IntEnum

An enumeration.

Bool = 1

Bytes = 6

BytesPromote = 7

Callable = 22

Coerced = 26

ContainerList = 12

DefaultDict = 15

Delegate = 27

Dict = 14

Enum = 21

Float = 4

FloatPromote = 5

FloatRange = 23

FloatRangePromote = 24

Instance = 17

Int = 2

IntPromote = 3

List = 11

MemberMethod_ObjectOldNew = 30

NoOp = 0

ObjectMethod_NameOldNew = 29

ObjectMethod_OldNew = 28

OptionalInstance = 16

OptionalTyped = 18

Range = 25

Set = 13

Str = 8

StrPromote = 9

Subclass = 20

Tuple = 10

Typed = 19

class atom.api.Value(default=None, *, factory=None)

Bases: Member

A member class which supports value initialization.

A plain Value provides support for default values and factories, but does not perform any type checking or validation. It serves as a useful base class for scalar members and can be used for cases where type checking is not needed (like private attributes).

atom.api.add_member(cls: AtomMeta, name: str, member: Member) → None

Add or override a member after the class creation.

class atom.api.atomclist(iterable=(), /)

Bases: atomlist

append()

L.append(object) – append object to end

extend()

L.extend(iterable) – extend list by appending elements from the iterable

insert()

L.insert(index, object) – insert object before index

pop([index]) → item -- remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove()

L.remove(value) – remove first occurrence of value. Raises ValueError if the value is not present.

reverse()

L.reverse() – reverse IN PLACE

sort()

L.sort(cmp=None, key=None, reverse=False) – stable sort IN PLACE; cmp(x, y) -> -1, 0, 1

class atom.api.atomdict

Bases: dict

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

update([E, ]**F) → None. Update D from dict/iterable E and F

class atom.api.atomlist(iterable=(), /)

Bases: list

append()

L.append(object) – append object to end

extend()

L.extend(iterable) – extend list by appending elements from the iterable

insert()

L.insert(index, object) – insert object before index

class atom.api.atomref

Bases: object

class atom.api.atomset

Bases: set

add()

Add an element to a set.

difference_update()

Update a set with the difference of itself and another.

intersection_update()

Update a set with the intersection of itself and another.

symmetric_difference_update()

Update a set with the symmetric difference of itself and another.

update()

Update a set with the union of itself and another.

atom.api.cached_property(fget)

A decorator which converts a function into a cached Property.

Parameters:

fget (callable) – The callable invoked to get the property value. It must accept a single argument which is the owner object.

atom.api.clone_if_needed(cls: AtomMeta, member: M) → M

Clone a member if is not owned by a class.

This function is meant to be used in __init__subclass__ to safely customize members static behaviors.

class atom.api.defaultatomdict

Bases: atomdict

atom.api.observe(*names: str, change_types: ChangeType = ChangeType.ANY) → ObserveHandler

A decorator which can be used to observe members on a class.

Parameters:

• *names – The str names of the attributes to observe on the object. These must be of the form ‘foo’ or ‘foo.bar’.

• change_types – The flag specifying the type of changes to observe.

class atom.api.set_default(value: Any)

Bases: object

An object used to set the default value of a base class member.

clone() → set_default

Create a clone of the sentinel.

name: str | None

Name of the member for which a new default value should be set. Used by the metaclass.

value: Any

New default value to be set.