atom.api module
Module exporting the public interface to atom.
- class atom.api.Atom[source]
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.
- 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)[source]
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.Bytes(default=b'', *, factory=None, strict=True)[source]
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)[source]
Bases:
Value
A value which is callable.
- class atom.api.ChangeDict[source]
Bases:
dict
- count: int
- index: int
- item: Any
- key: Any
- name: str
- newitem: Any
- 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)[source]
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)[source]
Bases:
Value
A value which cannot be changed from its default.
- class atom.api.ContainerList(item=None, default=None)[source]
Bases:
List
A List member which supports container notifications.
- class atom.api.DefaultDict(key=None, value=None, default=None, *, missing=None)[source]
Bases:
Member
A value of type dict implementing __missing__
- clone()[source]
Create a clone of the member.
This will clone the internal dict key and value members if they exist.
- 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)[source]
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)[source]
Add a static observer to the member.
This method also adds the static observer to the delegate.
- clone()[source]
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)[source]
Remove a static observer from the member.
This method also removes the static observer from the delegate.
- set_default_value_mode(mode, context)[source]
Set the default value mode for the member.
This method proxies the change to the delegate member.
- set_index(index)[source]
Assign the index to this member.
This method keeps the index of the delegate member in sync.
- set_name(name)[source]
Assign the name to this member.
This method keeps the name of the delegate member in sync.
- set_post_getattr_mode(mode, context)[source]
Set the post getattr mode for the member.
This method proxies the change to the delegate member.
- set_post_setattr_mode(mode, context)[source]
Set the post getattr mode for the member.
This method proxies the change to the delegate member.
- class atom.api.Dict(key=None, value=None, default=None)[source]
Bases:
Member
A value of type dict.
- clone()[source]
Create a clone of the member.
This will clone the internal dict key and value members if they exist.
- class atom.api.Enum(*items)[source]
Bases:
Member
A member where the value can be one in a sequence of items.
- added(*items)[source]
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:
- property items
A readonly property which returns the items in the enum.
- class atom.api.Event(kind=None)[source]
Bases:
Member
A member which acts like a stateless event.
- class atom.api.FixedTuple(*items, default=None)[source]
Bases:
Member
A member which allows tuple values with a fixed number of items.
Items are always validated and can be of different types. Assignment will create a copy of the original tuple before validating the items, since validation may change the item values.
- clone()[source]
Create a clone of the tuple.
This will clone the internal tuple item if one is in use.
- class atom.api.Float(default=0.0, *, factory=None, strict=False)[source]
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)[source]
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)[source]
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
- default(owner)[source]
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
- class atom.api.ForwardSubclass(resolve)[source]
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.
- default(owner)[source]
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
- class atom.api.ForwardTyped(resolve, args=None, kwargs=None, *, factory=None, optional=None)[source]
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
- default(owner)[source]
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
- 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)[source]
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)[source]
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)[source]
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()[source]
Create a clone of the list.
This will clone the internal list item if one is in use.
- item
- 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[source]
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)[source]
Bases:
Member
A Member which behaves similar to a Python property.
- property cached
Test whether or not this is a cached property.
- deleter(func)[source]
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)[source]
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.
- class atom.api.Range(low=None, high=None, value=None)[source]
Bases:
Value
An integer value clipped to a range.
- class atom.api.ReadOnly(kind=None, *, default=None, factory=None)[source]
Bases:
Value
A value which can be assigned once and is then read-only.
- class atom.api.Set(item=None, default=None)[source]
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()[source]
Create a clone of the member.
This will clone the internal set item members if they exist.
- item
- 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.Str(default='', *, factory=None, strict=True)[source]
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)[source]
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=())[source]
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()[source]
Create a clone of the tuple.
This will clone the internal tuple item if one is in use.
- item
- class atom.api.Typed(kind, args=None, kwargs=None, *, factory=None, optional=None)[source]
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 = 23
- Coerced = 27
- ContainerList = 13
- DefaultDict = 16
- Delegate = 28
- Dict = 15
- Enum = 22
- FixedTuple = 11
- Float = 4
- FloatPromote = 5
- FloatRange = 24
- FloatRangePromote = 25
- Instance = 18
- Int = 2
- IntPromote = 3
- List = 12
- MemberMethod_ObjectOldNew = 31
- NoOp = 0
- ObjectMethod_NameOldNew = 30
- ObjectMethod_OldNew = 29
- OptionalInstance = 17
- OptionalTyped = 19
- Range = 26
- Set = 14
- Str = 8
- StrPromote = 9
- Subclass = 21
- Tuple = 10
- Typed = 20
- class atom.api.Value(default=None, *, factory=None)[source]
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 [source]
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)[source]
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 [source]
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.
- atom.api.observe(*names: str, change_types: ~atom.catom.ChangeType = <ChangeType.ANY: 255>) ObserveHandler [source]
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)[source]
Bases:
object
An object used to set the default value of a base class member.
- clone() set_default [source]
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.