Skip to content

Atom

dstz.core.atom

Element

Bases: Item

A concrete class representing a basic element with a specific value.

This class inherits from Item and is used to wrap a single value. The identity of an Element is determined solely by its value attribute.

Attributes:

Name Type Description
value Any

The value of the element.
Source code in dstz/core/atom.py 
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
class Element(Item):
    """A concrete class representing a basic element with a specific value.

    This class inherits from `Item` and is used to wrap a single value. The
    identity of an `Element` is determined solely by its `value` attribute.

    Attributes:
        value (Any): The value of the element.
    """

    def __init__(self, value=None):
        """Initializes an Element instance.

        Args:
            value (Any, optional): The initial value of the Element.
                Defaults to `None`.
        """
        super(Element, self).__init__()
        self.value = value

    @property
    def idattr(self):
        """Specifies the identifier attribute for the Element.

        Returns:
            list: A list containing the name of the identifier attribute, `['value']`.
        """
        return ['value']

    def __str__(self):
        """Returns a human-readable string representation of the Element.

        Returns:
            str: The string representation of the Element's value.
        """
        return str(self.value)

    def __repr__(self):
        """Returns a developer-friendly string representation of the Element.

        Returns:
            str: The string representation of the Element's value, suitable
                 for debugging.
        """
        return self.__str__()

    def __len__(self):
        """Returns the length of the Element's value.

        This method allows the `len()` function to be called on an `Element`
        instance, provided its `value` has a defined length (e.g., a list,
        tuple, or string).

        Returns:
            int: The length of the `value` attribute.
        """
        return len(self.value)

    def __iter__(self):
        """Makes the Element iterable.

        If the Element's `value` is iterable (and not a string), this method
        yields its items one by one. This allows iterating directly over an
        `Element` instance.

        Yields:
            Any: The next item from the `value` attribute.
        """
        if hasattr(self.value, '__iter__') and not isinstance(self.value, str):
            yield from self.value

idattr property

Specifies the identifier attribute for the Element.

Returns:

Name Type Description
list

A list containing the name of the identifier attribute, ['value'].

__init__(value=None)

Initializes an Element instance.

Parameters:

Name Type Description Default
value Any

The initial value of the Element. Defaults to None.

 None
Source code in dstz/core/atom.py 
84
85
86
87
88
89
90
91
92
def __init__(self, value=None):
    """Initializes an Element instance.

    Args:
        value (Any, optional): The initial value of the Element.
            Defaults to `None`.
    """
    super(Element, self).__init__()
    self.value = value

__iter__()

Makes the Element iterable.

If the Element's value is iterable (and not a string), this method yields its items one by one. This allows iterating directly over an Element instance.

Yields:

Name Type Description
Any

The next item from the value attribute.
Source code in dstz/core/atom.py 
132
133
134
135
136
137
138
139
140
141
142
143
def __iter__(self):
    """Makes the Element iterable.

    If the Element's `value` is iterable (and not a string), this method
    yields its items one by one. This allows iterating directly over an
    `Element` instance.

    Yields:
        Any: The next item from the `value` attribute.
    """
    if hasattr(self.value, '__iter__') and not isinstance(self.value, str):
        yield from self.value

__len__()

Returns the length of the Element's value.

This method allows the len() function to be called on an Element instance, provided its value has a defined length (e.g., a list, tuple, or string).

Returns:

Name Type Description
int

The length of the value attribute.
Source code in dstz/core/atom.py 
120
121
122
123
124
125
126
127
128
129
130
def __len__(self):
    """Returns the length of the Element's value.

    This method allows the `len()` function to be called on an `Element`
    instance, provided its `value` has a defined length (e.g., a list,
    tuple, or string).

    Returns:
        int: The length of the `value` attribute.
    """
    return len(self.value)

__repr__()

Returns a developer-friendly string representation of the Element.

Returns:

Name Type Description
str

The string representation of the Element's value, suitable for debugging.
Source code in dstz/core/atom.py 
111
112
113
114
115
116
117
118
def __repr__(self):
    """Returns a developer-friendly string representation of the Element.

    Returns:
        str: The string representation of the Element's value, suitable
             for debugging.
    """
    return self.__str__()

__str__()

Returns a human-readable string representation of the Element.

Returns:

Name Type Description
str

The string representation of the Element's value.
Source code in dstz/core/atom.py 
103
104
105
106
107
108
109
def __str__(self):
    """Returns a human-readable string representation of the Element.

    Returns:
        str: The string representation of the Element's value.
    """
    return str(self.value)

Item

Bases: ABC

Abstract base class for items that can be uniquely identified and hashed.

This class provides a foundation for creating objects that need to be distinguishable based on specific attributes. Subclasses are required to implement the idattr property, which specifies which attributes are used for identification, equality checks, and hashing.

Attributes:

Name Type Description
_value Any

An internal attribute for use by subclasses.
Source code in dstz/core/atom.py 
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
class Item(ABC):
    """Abstract base class for items that can be uniquely identified and hashed.

    This class provides a foundation for creating objects that need to be
    distinguishable based on specific attributes. Subclasses are required to
    implement the `idattr` property, which specifies which attributes are used
    for identification, equality checks, and hashing.

    Attributes:
        _value (Any): An internal attribute for use by subclasses.
    """

    def __init__(self):
        """Initializes the Item instance.

        Sets the internal `_value` attribute to `None`.
        """
        self._value = None

    @property
    @abstractmethod
    def idattr(self):
        """Specifies the unique identifying attributes for an instance.

        This abstract property must be implemented by any subclass. It should
        return a list or tuple of strings, where each string is the name of an

        attribute that uniquely identifies the object.

        Returns:
            A list or tuple of attribute names.
        """
        pass

    def __eq__(self, other):
        """Compares this item with another for equality.

        Two items are considered equal if they are of the same type and the
        values of their identifying attributes (specified by `idattr`) are
        all equal.

        Args:
            other (Any): The object to compare against.

        Returns:
            bool: `True` if the objects are equal, `False` otherwise.
        """
        if not isinstance(other, type(self)):
            return False
        return all(getattr(self, attr) == getattr(other, attr) for attr in self.idattr)

    def __hash__(self):
        """Computes a hash value for the item.

        The hash is based on the values of the identifying attributes
        (specified by `idattr`). If an attribute's value is not hashable
        (e.g., a list or set), it is converted to a `frozenset` before hashing.

        Returns:
            int: The computed hash value.
        """
        attrs = []
        for attr in self.idattr:
            value = getattr(self, attr)
            if not isinstance(value, Hashable):
                value = frozenset(value)
            attrs.append(value)
        return hash(tuple(attrs))

idattr abstractmethod property

Specifies the unique identifying attributes for an instance.

This abstract property must be implemented by any subclass. It should return a list or tuple of strings, where each string is the name of an

attribute that uniquely identifies the object.

Returns:

Type Description

A list or tuple of attribute names.

__eq__(other)

Compares this item with another for equality.

Two items are considered equal if they are of the same type and the values of their identifying attributes (specified by idattr) are all equal.

Parameters:

Name Type Description Default
other Any

The object to compare against.

 required

Returns:

Name Type Description
bool

True if the objects are equal, False otherwise.
Source code in dstz/core/atom.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
def __eq__(self, other):
    """Compares this item with another for equality.

    Two items are considered equal if they are of the same type and the
    values of their identifying attributes (specified by `idattr`) are
    all equal.

    Args:
        other (Any): The object to compare against.

    Returns:
        bool: `True` if the objects are equal, `False` otherwise.
    """
    if not isinstance(other, type(self)):
        return False
    return all(getattr(self, attr) == getattr(other, attr) for attr in self.idattr)

__hash__()

Computes a hash value for the item.

The hash is based on the values of the identifying attributes (specified by idattr). If an attribute's value is not hashable (e.g., a list or set), it is converted to a frozenset before hashing.

Returns:

Name Type Description
int

The computed hash value.
Source code in dstz/core/atom.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
def __hash__(self):
    """Computes a hash value for the item.

    The hash is based on the values of the identifying attributes
    (specified by `idattr`). If an attribute's value is not hashable
    (e.g., a list or set), it is converted to a `frozenset` before hashing.

    Returns:
        int: The computed hash value.
    """
    attrs = []
    for attr in self.idattr:
        value = getattr(self, attr)
        if not isinstance(value, Hashable):
            value = frozenset(value)
        attrs.append(value)
    return hash(tuple(attrs))

__init__()

Initializes the Item instance.

Sets the internal _value attribute to None.

Source code in dstz/core/atom.py 
16
17
18
19
20
21
def __init__(self):
    """Initializes the Item instance.

    Sets the internal `_value` attribute to `None`.
    """
    self._value = None