dictation 1.0.0__py3-none-any.whl

dictation/__init__.py

@@ -0,0 +1,528 @@
+from __future__ import annotations
+
+import logging
+import copy
+
+
+logger = logging.getLogger(__name__)
+
+
+class AnnotationError(AttributeError):
+    """Error for alerting the absence of or inability to set the requested annotation"""
+
+    pass
+
+
+class dictation(dict):
+    """Annotated dictionary type supports one or more annotation stored alongside the
+    standard dictionary key-value pairs, as well as automatic hierarchical links between
+    root and child dictionary nodes allowing for annotations to be defined and gathered
+    hierarchically from a given child dictionary node upwards to the root node."""
+
+    _reserved: list[str] = ["recursive"]
+
+    class _annotation(object):
+        """The _annotation class holds an annotation value and its recursive state"""
+
+        def __init__(self, value: object, recursive: bool = True):
+            self._value = value
+
+            if not isinstance(recursive, bool):
+                raise TypeError("The 'recursive' argument must have a boolean value!")
+
+            self._recursive = recursive
+
+        @property
+        def value(self) -> object | None:
+            """Return the annotation class' stored value"""
+
+            return self._value
+
+        @value.setter
+        def value(self, value: object):
+            """The annotation value can only be set during class construction"""
+
+            raise NotImplementedError
+
+        @property
+        def recursive(self) -> bool:
+            """Return the annotation class' stored recursive state"""
+
+            return self._recursive
+
+        @recursive.setter
+        def recursive(self, recursive: bool):
+            """The recursive value can only be set during class construction"""
+
+            raise NotImplementedError
+
+        @property
+        def data(self) -> dict[str, object]:
+            """Provide access to the annotation in the form of a dictionary"""
+
+            return dict(value=self.value, recursive=self.recursive)
+
+    def __init__(self, *args, parent: dictation = None, **kwargs):
+        """Initialize a `dictation` instance, which as a subclass of `dict` supports the
+        same instantiation patterns as a standard `dict` class for compatibility"""
+
+        super().__init__()
+
+        self._special: list[str] = sorted(
+            self.__class__._reserved
+            + [attr for attr in dir(self) if not attr.startswith("_")]
+        )
+
+        self._annotations: dict[str, annotation] = {}
+
+        self._parent: dictation = None
+
+        if parent is None:
+            pass
+        elif isinstance(parent, dictation):
+            self._parent = parent
+        else:
+            raise TypeError(
+                "The 'parent' argument, if set, must have a `dictation` instance value!"
+            )
+
+        # Iterate through any args
+        for arg in args:
+            if isinstance(arg, (dict, dictation)):
+                for key, value in arg.items():
+                    self[key] = value
+
+                if isinstance(arg, dictation):
+                    if isinstance(annotations := arg._annotations, dict):
+                        for name, annotation in annotations.items():
+                            self._annotations[name] = self._annotation(
+                                value=annotation.value,
+                                recursive=annotation.recursive,
+                            )
+
+                    if isinstance(parent := arg.parent, dictation):
+                        self._parent = parent
+
+        for key, value in kwargs.items():
+            self[key] = value
+
+        def transform(source: object, parent: dictation = None) -> object:
+            """Transform the current dictionary ensuring all subdictionaries are of the
+            expected class type and that their parent relationships are set as needed"""
+
+            if isinstance(source, dict):
+                if isinstance(source, dictation):
+                    if source.parent is None:
+                        source._parent = parent
+                else:
+                    source = dictation(source, parent=parent)
+
+                for key, value in source.items():
+                    source[key] = transform(value, parent=source)
+            elif isinstance(source, (list, tuple, set)):
+                for index, value in enumerate(source):
+                    source[index] = transform(value, parent=parent)
+
+            return source
+
+        transform(source=self, parent=parent)
+
+    def __str__(self) -> str:
+        return "<dictation(%s)>" % (super().__str__())
+
+    def __copy__(self):
+        """Supports the creation of shallow copies of dictation class instances"""
+
+        data = dict()
+
+        for key, value in self.items():
+            data[key] = copy.copy(value)
+
+        annotations = dict()
+
+        for key, annotation in self._annotations.items():
+            annotations[key] = copy.copy(annotation)
+
+        return dictation(data).annotate(**annotations)
+
+    def __deepcopy__(self, memo):
+        """Supports the creation of deep copies of dictation class instances"""
+
+        data = dict()
+
+        for key, value in self.items():
+            data[key] = copy.deepcopy(value, memo)
+
+        annotations = dict()
+
+        for key, annotation in self._annotations.items():
+            annotations[key] = copy.deepcopy(annotation, memo)
+
+        return dictation(data).annotate(**annotations)
+
+    def __setattr__(self, name: str, value: object):
+        """Supports setting class attributes or annotations via attributes; annotation
+        attributes cannot have names starting with underscores as these are reserved for
+        class attributes and methods, nor can annotations use the same name as inherent
+        class attributes or public methods; using such names will raise an exception."""
+
+        if not isinstance(name, str):
+            raise TypeError("The 'name' argument must have a string value!")
+
+        if name.startswith("_"):
+            super().__setattr__(name, value)
+        elif name in self._special:
+            if isinstance(attr := getattr(self.__class__, name, None), property):
+                super().__setattr__(name, value)
+            else:
+                raise AnnotationError(
+                    "Annotations cannot use any of the following reserved word names: %s!"
+                    % (", ".join(self._special))
+                )
+        else:
+            self.annotate(**{name: value}, recursive=False)
+
+        return self
+
+    def __getattr__(self, name: str, recursive: bool = False) -> object | None:
+        """Supports obtaining class attributes or annotations; annotation attributes
+        cannot have names starting with underscores as these are reserved for class
+        attributes and methods. Annotations are searched hierarchically; if a matching
+        annotation is present on the current node it will be returned, alternatively all
+        parent nodes up to the root node will be searched for a match; if a match cannot
+        be found then an AttributeError exception will be raised to note its absence."""
+
+        if not isinstance(name, str):
+            raise TypeError("The 'name' argument must have a string value!")
+
+        if not isinstance(recursive, bool):
+            raise TypeError("The 'recursive' argument must have a boolean value!")
+
+        if name.startswith("_") or name in self._special:
+            return super().__getattribute__(name)
+        elif isinstance(annotation := self._annotations.get(name), self._annotation):
+            if recursive is False or annotation.recursive is True:
+                return annotation.value
+        elif isinstance(parent := self._parent, dictation):
+            return parent.__getattr__(name=name, recursive=True)
+        else:
+            raise AttributeError(f"The attribute '{name}' does not exist!")
+
+    def __delattr__(self, name: str):
+        """Supports deleting previously assigned annotations"""
+
+        if name.startswith("_") or name in self._special:
+            super().__delattr__(name)
+        else:
+            self.unannotate(name=name)
+
+    def __setitem__(self, key: object, value: object):
+        """Supports setting a dictionary item via the usual subscript d[k]=v notation"""
+
+        if isinstance(value, dict) and not isinstance(value, dictation):
+            value = dictation(value, parent=self)
+
+        super().__setitem__(key, value)
+
+    def __getitem__(self, key: object) -> object:
+        """Supports getting a dictionary item via the usual subscript v=d[k] notation"""
+
+        value = super().__getitem__(key)
+
+        if isinstance(value, dict) and not isinstance(value, dictation):
+            value = dictation(value, parent=self)
+
+        return value
+
+    def __getstate__(self) -> dict:
+        """Supports pickling the `dictation` dictionary instance"""
+
+        return self.__dict__.copy()
+
+    def __setstate__(self, state: dict):
+        """Supports un-pickling the `dictation` dictionary instance"""
+
+        self.__dict__.update(state)
+
+    @property
+    def parent(self) -> dictation | None:
+        """Return the instance's parent relationship, if one has been assigned"""
+
+        return self._parent
+
+    @parent.setter
+    def parent(self, parent: dictation):
+        """A dictation instance's parent relationship can only be assigned internally by
+        the library to ensure integrity of the hierarchical references and the correct
+        determination of any recursively available annotations for child nodes."""
+
+        raise NotImplementedError("The 'parent' property cannot be set externally!")
+
+    def get(self, key: object, default: object = None) -> object | None:
+        """Overrides the `dict` class' `get` method to support specifying the default
+        value positionally as well as via its keyword argument to improve documentation
+        of the code at the call site, e.g. x.get("y", 0) vs x.get("y", default=0)."""
+
+        return super().get(key, default)
+
+    def set(self, key: object, value: object) -> dictation:
+        """Provides a `set` method to compliment the built-in `dict` class' `get` method
+        which takes the usual key and value as keyword arguments, and assigns the value
+        to the current dictionary instance at the provided key. As this method returns
+        `self`, calls to `set()` can be chained with calls to other class methods, such
+        as the `annotate()` method."""
+
+        self[key] = value
+
+        return self
+
+    @property
+    def annotations(self) -> dict[str, object]:
+        """Obtain the current annotations associated with the current `dictation` node
+        as well as any annotations assigned to ancestors that are marked as recursive"""
+
+        def gather(source: object, annotations: dict, recursive: bool = False):
+            """Recursively gather any annotations assigned to the current node as well
+            as any assigned to any ancestor nodes, returning them as a dictionary"""
+
+            if isinstance(source, dictation):
+                for key, annotation in source._annotations.items():
+                    # If an annotation with the same name has already been encountered
+                    # do not overwrite it; this ensures that annotations assigned higher
+                    # in the hierarchy (starting at the root node), do not overwrite any
+                    # annotations assigned at deeper levels, such as on a child node:
+                    if not key in annotations:
+                        if recursive is False or annotation.recursive is True:
+                            annotations[key] = annotation.value
+
+                if isinstance(parent := source.parent, dictation):
+                    gather(source=parent, annotations=annotations, recursive=True)
+
+            return annotations
+
+        return gather(source=self, annotations=dict())
+
+    @annotations.setter
+    def annotations(self, annotations: dict):
+        """The `annotations` property setter supports assigning one or more annotations
+        to the current `dictation` instance by assigning a dictionary value of key-value
+        pairs. The key-value pairs will be applied to the current `dictation` instance
+        as additional annotations. If any of the annotation keys overlap with existing
+        annotation keys, the new value will replace the old; annotation keys which do
+        not match any existing annotation keys for the current instance will be applied
+        as new annotations alongside the old. This behaviour is equivalent to the `dict`
+        class' `update()` method, which overwrites existing keys and adds any new keys.
+
+        It is important to note that annotations applied to the current `dictation`
+        instance via the `annotations` property will not be available recursively to
+        any of the current instance's nested children. Furthermore, if a pre-existing
+        recursive annotation was stored on the current instance under a key that matches
+        a key provided in the annotations assigned via the property, not only will the
+        new value replace the old, but it will no longer be available recursively.
+
+        In order to control which annotations are applied recursively, one may use the
+        `annotate()` method instead which provides this additional level of control."""
+
+        if not isinstance(annotations, dict):
+            raise TypeError("The annotations property must be assigned as a dictionary")
+        else:
+            for name, value in annotations.items():
+                if not isinstance(name, str):
+                    raise AnnotationError("Annotations must have string names!")
+                elif name.startswith("_"):
+                    raise AnnotationError(
+                        "Annotations cannot have names starting with underscores!"
+                    )
+                elif name in self._special:
+                    raise AnnotationError(
+                        "Annotations cannot use any of the following reserved word names: %s!"
+                        % (", ".join(self._special))
+                    )
+
+        self.annotate(**annotations)
+
+    def annotate(self, recursive: bool = False, **annotations) -> dictation:
+        """Supports assigning one or more annotations to the current dictation instance,
+        specified as key-value pairs. The 'recursive' keyword is reserved for specifying
+        if the annotations will be marked as being recursively available for the current
+        node and any children; otherwise they are only available to the current node."""
+
+        if not isinstance(recursive, bool):
+            raise TypeError("The 'recursive' argument must have a boolean value!")
+
+        for name, value in annotations.items():
+            if not isinstance(name, str):
+                raise AnnotationError("Annotations must have string names!")
+            elif name.startswith("_"):
+                raise AnnotationError(
+                    "Annotations cannot have names starting with underscores!"
+                )
+            elif name in self._special:
+                raise AnnotationError(
+                    "Annotations cannot use any of the following reserved word names: %s!"
+                    % (", ".join(self._special))
+                )
+
+            self._annotations[name] = self._annotation(
+                value=value,
+                recursive=recursive,
+            )
+
+        return self
+
+    def annotation(
+        self,
+        name: str,
+        default: object = None,
+        recursive: bool = True,
+    ) -> object | None:
+        """Supports recursively obtaining and returning a named annotation value. If the
+        named annotation cannot be found, and if a default value has been specified, it
+        will be returned, otherwise the method will return the `None` value instead. If
+        the named annotation should only be retrieved from the current node and not via
+        a recursive lookup, the 'recursive' argument may be set to `False`."""
+
+        if not isinstance(name, str):
+            raise TypeError("The 'name' argument must have a string value!")
+
+        if not isinstance(recursive, bool):
+            raise TypeError("The 'recursive' argument must have a boolean value!")
+
+        if isinstance(annotation := self._annotations.get(name), self._annotation):
+            return annotation.value
+        elif recursive is True and isinstance(parent := self._parent, dictation):
+            return parent.annotation(name=name, recursive=recursive, default=default)
+        elif not default is None:
+            return default
+
+    def unannotate(self, name: str) -> dictation:
+        """Supports removing an annotation assigned directly to the current `dictation`
+        node. The `dictation` class does not support removing annotations recursively,
+        as annotations are not stored recursively, rather they are stored directly on
+        the node to which they are assigned, but each annotation can be marked as being
+        available recursively – or not – to any nested children. As such, to remove any
+        recursively available annotation that is no longer needed, it must either be
+        removed from the node that it was directly assigned to, or it can be reassigned
+        to the same node without recursive availability via the `annotate()` method."""
+
+        if not isinstance(name, str):
+            raise TypeError("The 'name' argument must have a string value!")
+
+        if name in self._annotations:
+            del self._annotations[name]
+
+        return self
+
+    def data(self, metadata: bool = False, annotations: bool = False):
+        """Supports generating a dictionary representation of a `dictation` instance's
+        data, optionally including associated metadata such as any parent references,
+        any assigned annotation values, and typing information for each value. This is
+        primarily useful for debugging purposes."""
+
+        if not isinstance(metadata, bool):
+            raise TypeError("The 'metadata' argument must have a boolean value!")
+
+        if not isinstance(annotations, bool):
+            raise TypeError("The 'annotations' argument must have a boolean value!")
+
+        def dump(source: object, metadata: bool = False, annotations: bool = False):
+            data = {}
+
+            if metadata is True:
+                data["@type"] = str(type(source))
+
+            if isinstance(source, dict):
+                if isinstance(source, dictation):
+                    if metadata is True:
+                        data["@parent"] = str(source.parent) if source.parent else None
+
+                        if annotations is True:
+                            data["@annotations"] = {
+                                key: value for key, value in source.annotations.items()
+                            }
+
+                if metadata is True:
+                    data["@value"] = {}
+
+                    for key, value in source.items():
+                        data["@value"][key] = dump(
+                            source=value,
+                            metadata=metadata,
+                            annotations=annotations,
+                        )
+                else:
+                    for key, value in source.items():
+                        data[key] = dump(
+                            source=value,
+                            metadata=metadata,
+                            annotations=annotations,
+                        )
+            elif isinstance(source, (list, tuple)):
+                if metadata is True:
+                    data["@value"] = []
+
+                    for index, value in enumerate(source):
+                        data["@value"].append(
+                            dump(
+                                source=value,
+                                metadata=metadata,
+                                annotations=annotations,
+                            )
+                        )
+                else:
+                    data = []
+
+                    for index, value in enumerate(source):
+                        data.append(
+                            dump(
+                                source=value,
+                                metadata=metadata,
+                                annotations=annotations,
+                            )
+                        )
+            else:
+                if metadata is True:
+                    data["@value"] = source
+                else:
+                    data = source
+
+            return data
+
+        return dump(source=self, metadata=metadata, annotations=annotations)
+
+    def print(self, indent: int = 0):
+        """Supports generating a print-out of the `dictation` instance's data as well as
+        any annotations which can be useful for debugging or visualisation purposes."""
+
+        if not isinstance(indent, int):
+            raise TypeError("The 'indent' argument must have an integer value!")
+
+        def printer(source: object, indent: int = 0):
+            print(("  " * indent) + " => %s" % (type(source)))
+
+            if isinstance(source, dictation):
+                print(("  " * indent) + " => parent      -> %s" % (source.parent))
+                print(("  " * indent) + " => annotations -> %s" % (source.annotations))
+
+            if isinstance(source, dict):
+                for key, value in source.items():
+                    print(("  " * indent) + " => %s" % (key))
+
+                    if isinstance(value, (dict, list, tuple)):
+                        printer(value, indent=(indent + 1))
+                    else:
+                        print(("  " * (indent + 1)) + " => %s" % (value))
+            elif isinstance(source, (list, tuple)):
+                print((" " * indent) + " => parent      -> %s" % (source.parent))
+
+                for key, index in enumerate(source):
+                    print((" " * indent) + " => %s" % (index))
+
+                    if isinstance(value, (dict, list, tuple)):
+                        printer(value, indent=(indent + 1))
+                    else:
+                        print(("  " * (indent + 1)) + " => %s" % (value))
+            else:
+                print(("  " * indent) + " => %s (%s)" % (source, type(source)))
+
+        printer(source=self, indent=indent)

dictation/version.txt

@@ -0,0 +1 @@
+1.0.0

dictation-1.0.0.dist-info/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2024–2025 Daniel Sissman.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dictation-1.0.0.dist-info/METADATA

@@ -0,0 +1,363 @@
+Metadata-Version: 2.2
+Name: dictation
+Version: 1.0.0
+Summary: Annotated dictionaries for Python
+Author: Daniel Sissman
+License: MIT License
+        
+        Copyright © 2024–2025 Daniel Sissman.
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Documentation, https://github.com/bluebinary/dictation/blob/main/README.md
+Project-URL: Changelog, https://github.com/bluebinary/dictation/blob/main/CHANGELOG.md
+Project-URL: Repository, https://github.com/bluebinary/dictation
+Project-URL: Issues, https://github.com/bluebinary/dictation/issues
+Keywords: dictionary,dict,annotated dictionary
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+
+# Dictation: Annotated Python Dictionaries
+
+The Dictation library compliments Python's built-in `dict` data type by offering a fully
+compatible subclass, `dictation`, which adds support for annotations – a way to carry
+additional metadata within – yet separate from – the data held in the dictionary itself.
+
+The `dictation` dictionary type also automatically assigns parent relationships to all
+child dictionaries, which is useful to have access to in some data processing scenarios,
+whether or not these are used in addition to the library's annotation capabilities.
+
+The ability to assign annotations, or keep track of parent relationships for child nodes
+of a nested dictionary structure can be useful where one can not modify the structure or
+data held in a dictionary, because doing so could render it incompatible for some uses.
+
+As the `dictation` data type is compatible with the built-in `dict` data type, it should
+be usable anywhere an ordinary `dict` instance can be used.
+
+The `dictation` library name is a portmanteau of `dic-tionary` and `anno-tation`.
+
+### Requirements
+
+The Dictation library has been tested with Python 3.9, 3.10, 3.11, 3.12 and 3.13 but may
+work with some earlier versions such as 3.8 but has not been tested against this version
+or any earlier. The library is not compatible with Python 2.* or earlier.
+
+### Installation
+
+The Dictation library is available from PyPI so may be added to a project's dependencies
+via its `requirements.txt` file or similar by referencing the Dictation library's name,
+`dictation`, or the library may be installed directly into the local runtime environment
+using `pip install` by entering the following command, and following any prompts:
+
+	$ pip install dictation
+
+### Class Methods & Properties
+
+The Dictation library's `dictation` class is a subclass of the built-in `dict` class, so
+all of the built-in functionality of `dict` is available, as well as several additional
+class methods and properties as documented below:
+
+* `annotate(recursive: bool = False, **kwargs)` – The `annotate()` method can be used to
+assign one or more annotations to the current `dictation` instance provided as key-value
+pairs; these are held separately from and do not interfere with the actual data held in
+the dictionary. The `recursive` keyword is reserved for specifying if the annotations
+provided will be marked as being recursively available for the current node as well as
+for any nested child nodes, when `recursive` is set to `True` – when `recursive` is set
+to `False` (or simply when the `recursive` argument is not specified), the annotations
+will only available for the current node. Additionally, the `annotate()` method returns
+`self` upon completion so calls to `annotate()` can be chained with calls to other class
+methods, such as the `get()` method.
+
+* `unannotate(name: str) -> dictation` – The `unannotate()` method provides support for
+removing a named annotation from the current node; it cannot remove any annotations that
+have been inherited from ancestors in the hierarchy; to remove a recursive annotation,
+it must be removed directly from the `dictation` ancestor node it was assigned to.
+
+* `annotation(name: str, default: object = None, recursive: bool = True) -> object` –
+The `annotation()` method supports recursively obtaining a named annotation value. If
+the named annotation cannot be found, the `default` value will be returned if one has
+been provided, and if not, the `None` value will be returned.
+
+* `annotations (getter) -> dict[str, object]` – The `annotations` getter returns the
+annotations, if any, assigned to the current `dictation` node, or inherited from any
+ancestors, where those annotations were assigned and set as being recursively available.
+
+* `annotations (setter) <- dict[str, object]` – The `annotations` setter supports
+assigning one or more annotations, specified as a dictionary of key-value pairs, to the
+current `dictation` node. Annotations applied via the `annotations` setter only apply to
+the current `dictation` node as they are not assigned as being recursively available to
+any child nodes. If an annotation needs to be made available to the current node as well
+as recursively to any child nodes, it must be set via the `annotate()` method instead,
+which provides control over the recursive availability of the annotation being assigned.
+
+* `parent (getter) -> dictation | None` – The `parent` property returns a reference to
+the current `dictation` instance's parent, if available, otherwise `None` is returned.
+
+* `set(key: object, value: object) -> dictation` – The `set()` method is a compliment to
+the built-in `dict` class' `get` method. The `set()` method accepts the usual key and
+value as method keyword arguments, and assigns the value to the current `dictation`
+instance at the provided key. Additionally, the `set()` method returns `self` upon
+completion, so calls to `set()` can be chained with calls to other class methods, such
+as the `annotate()` method.
+
+* `data(metadata: bool = False, annotations: bool = False) -> dict` – The `data()`
+method supports generating a dictionary representation of the dictation's data, as well
+as optionally including associated metadata such as the parent reference, any assigned
+annotation values, and typing information for each value.
+
+* `print(indent: int = 0)` – The `print()` method supports generating a print-out of the
+`dictation` instance's data as well as any annotations which can be useful for debugging
+and data visualisation purposes.
+
+
+### Usage Demonstration
+
+To use the Dictation library, simply import it and use the library's `dictation` class
+as a replacement of, or compliment to, the built-in `dict` class:
+
+```python
+from dictation import dictation
+
+# Create a new `dictation` class instance with example data and add a few annotations:
+sample = dictation(a=1, b=2, c=3).annotate(x=4, y=5)
+
+# Check that the data held by the `dictation` instance is as expected; note that as
+# the `dictation` class is a subclass of the `dict` class, that the two assertions below
+# comparing against another `dictation` instance as well as a `dict` instance are valid:
+assert sample == dictation(a=1, b=2, c=3)
+assert sample == dict(a=1, b=2, c=3)
+
+# Check that the annotation data held by the `dictation` instance is as expected; note
+# that the annotations are held completely separately from the dictionary's data:
+assert sample.annotations == dictation(x=4, y=5)
+assert sample.annotations == dict(x=4, y=5)
+
+# Modify the example annotation, "y", and add an annotation, "z", making both recursive:
+sample.annotate(y=0, z=6.789, recursive=True)
+
+# Check that the updates to the annotations are as expected:
+assert sample.annotations == dictation(x=4, y=0, z=6.789)
+
+# Attempt to obtain a named annotation; this works like the `dict` class' `get` method
+# whereby if the annotation is found, it's value will be returned, otherwise the default
+# value, if specified, will be returned, otherwise `None` will be returned instead:
+assert sample.annotation("z") == 6.789
+
+# An annotation named "v" does not exist, so the provided default is returned:
+assert sample.annotation("v", default=8) == 8
+
+# An annotation named "v" does not exist, nor is there a default, so `None` is returned:
+assert sample.annotation("v") is None
+
+# Add a new child dictionary to the current `dictation` instance, note that the child
+# dictionary will be converted to a new `dictation` instance as will any of its nested
+# child dictionaries:
+sample["d"] = dict(e=5, f=6)
+
+assert isinstance(sample["d"], dict)
+assert isinstance(sample["d"], dictation)
+
+# Check that the `sample` dictionary has the expected structure and data:
+assert sample == dict(a=1, b=2, c=3, d=dict(e=5, f=6))
+
+# Check that the nested dictionary, "d", has the expected annotations; as no annotations
+# have currently been assigned directly to the nested dictionary "d", it will only have
+# inherited recursive annotations assigned to its parent and their parents. As per this
+# example code, it currently means that the inherited annotations consist of "y" and "z"
+# which were assigned to the parent dictionary, `sample`, and as they were both marked
+# as recursive annotations, they are available to any nested children, including to "d":
+assert sample["d"].annotations == dict(y=0, z=6.789)
+
+# The `dictation` library also supports assigning annotations as attributes; annotations
+# added as attributes cannot use the same name as any of the class' inherent attributes,
+# properties or methods however; attempting to assign an attribute using the name of an
+# inherent class` attribute will raise an exception. So long as the annotation names are
+# distinct, annotations can easily be assigned and retrieved using attribute accessors:
+sample.greeting = "hello"
+
+# Check that the annotation, "greeting", has the expected value
+assert sample.greeting == "hello"
+
+# Annotations assigned via attributes are stored identically as annotations assigned to
+# a `dictation` instance in any other way, so they can all be accessed interchangeably:
+assert sample.annotation("greeting") == "hello"
+
+# Annotations assigned via the `annotate()` method can also be accessed as attributes:
+assert sample.x == 4
+assert sample.y == 0
+assert sample.z == 6.789
+
+# All annotations assigned to a node can be accessed as a dictionary representation via
+# the `annotations` property, which returns a `dict` instance holding the annotations:
+assert sample.annotations == dict(x=4, y=0, z=6.789, greeting="hello")
+
+# Regardless of how annotations are assigned to the `dictation` instance, they can be
+# accessed, modified or removed by any of the other methods; for example, annotations
+# can be removed using the `unannotate()` method, which returns `self` on completion
+# so can be chained:
+assert sample.unannotate("y").annotations == dict(x=4, z=6.789, greeting="hello")
+
+# The `del` language keyword can also be used to remove previously assigned annotations:
+del sample.z
+
+assert sample.annotations == dict(x=4, greeting="hello")
+```
+
+Please Note: Like any subclass of the built-in `dict` type, instances of the `dictation`
+class can not be created directly via Python's dictionary-literal `{...}` syntax, rather
+they must be instantiated using the `dictation` class constructor. One can however wrap
+any `{}` dictionary literal, as well as variables holding a `dict`, with a `dictation`
+class constructor to convert any regular `dict` to a `dictation` class instance:
+
+```python
+from dictation import dictation
+
+# The Python dictionary-literal syntax can only create `dict` instances:
+sample = {"a": 1, "b": 2, "c": 3}
+assert isinstance(sample, dictation) is False
+assert isinstance(sample, dict) is True
+assert sample == {"a": 1, "b": 2, "c": 3}
+
+# So the `dictation` class constructor must be used to create all `dictation` instances,
+# however, the `dictation` constructor can take a dictionary literal as input:
+sample = dictation({"a": 1, "b": 2, "c": 3})
+assert isinstance(sample, dictation) is True
+assert isinstance(sample, dict) is True
+assert sample == {"a": 1, "b": 2, "c": 3}
+
+# Furthermore, variables holding regular `dict` values, whether created via the literal
+# syntax or via the `dict` class constructor syntax...
+sample = {"x": 7, "y": 8, "z": 9}
+assert isinstance(sample, dictation) is False
+assert isinstance(sample, dict) is True
+assert sample == {"x": 7, "y": 8, "z": 9}
+
+sample = dict(sample)
+assert isinstance(sample, dictation) is False
+assert isinstance(sample, dict) is True
+assert sample == {"x": 7, "y": 8, "z": 9}
+
+# ...can be passed to the `dictation` class constructor to cast to a `dictation` class:
+sample = dictation(sample)
+assert isinstance(sample, dictation) is True
+assert isinstance(sample, dict) is True
+assert sample == {"x": 7, "y": 8, "z": 9}
+```
+
+One may also pass additional key-value pairs to the `dictation` class constructor during
+casting. These additional key-value pairs will overwrite any matching existing keys with
+the newly assigned values, as well as adding new key-value pairs to the dictionary for
+keys that have not yet been defined:
+
+```python
+from dictation import dictation
+
+base = dict(a=1, b=2, c=3)
+assert base == dict(a=1, b=2, c=3)
+
+sample = dictation(base, c=4, x=7, y=8, z=9)  # "c" is being redefined with a value of 4
+
+assert sample == dictation(a=1, b=2, c=4, x=7, y=8, z=9)
+assert sample == dict(a=1, b=2, c=4, x=7, y=8, z=9)
+```
+
+### Contributing & Local Development
+
+To carry out development of the Dictation library, create a fork of the repository from
+the GitHub account, then clone a copy of the fork to the local machine for development
+and testing:
+
+```
+$ cd path/to/local/development/directory
+$ git clone git@github.com:<username>/dictation.git
+```
+
+Then create a new feature/development branch, using a descriptive name for the branch:
+
+```
+$ cd path/to/local/development/directory/dictation
+$ git checkout -b new_feature_branch
+```
+
+#### Code Linting
+
+The Dictation library adheres to the code formatting specifications detailed in PEP-8,
+which are verified and applied by the _Black_ code formatting tool. When code changes
+are made to the library, one needs to ensure that the code conforms to these code
+formatting specifications. To simplify this, the provided `Dockerfile` creates an image
+that supports running _Black_ against the latest version of the code, and will report if
+any issues are found. To run the code formatting checks, perform the following commands,
+which will build the Docker image and then run the formatting checks:
+
+```
+$ docker compose build
+$ docker compose run black
+```
+
+If any code formatting issues are found, they will be reported by _Black_. It is also
+possible to run _Black_ so that it will automatically reformat the affected files; this
+can be achieved as follows, by passing the `--verbose` flag, which allows _Black_ to
+report which files:
+
+```
+$ docker compose run black --verbose
+```
+
+The above will reformat any library source and unit test files that contain formatting
+issues, and will report which changes are made.
+
+#### Unit Tests
+
+The Dictation library includes a suite of comprehensive unit tests which ensure that the
+library functionality operates as expected. The unit tests were developed with and are
+run via `pytest`.
+
+To ensure that the unit tests are run within a predictable runtime environment where all
+of the necessary dependencies are available, a [Docker](https://www.docker.com) image is
+created within which the tests are run. To run the unit tests, ensure Docker and Docker
+Compose are [installed](https://docs.docker.com/engine/install/), and run the commands
+listed below, which will build the Docker image via `docker compose build` and then run
+the tests via `docker compose run tests` – the output of the tests will be displayed:
+
+```
+$ docker compose build
+$ docker compose run tests
+```
+
+To run the unit tests with optional command line arguments being passed to `pytest`,
+append the relevant arguments to the `docker compose run tests` command, as follows, for
+example passing `-v` to enable verbose output or `-s` to print standard output:
+
+```
+$ docker compose run tests -v -s
+```
+
+See the documentation for [PyTest](https://docs.pytest.org/en/latest/) regarding the
+available optional command line arguments.
+
+### Copyright & License Information
+
+Copyright © 2024–2025 Daniel Sissman; licensed under the MIT License.

dictation-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+dictation/__init__.py,sha256=edbANTtc7HvxOu9QifboI3H6pCF5Vc2Sfqyo2qfZh_k,22269
+dictation/version.txt,sha256=klIfw8vZZL3J9YSpkbif3apXVO0cyW1tQkRTOGacEwU,5
+dictation-1.0.0.dist-info/LICENSE.md,sha256=j1XidOCGUhPx7CyXA31uC0XGKDRnvUcZpMp161qHI6g,1077
+dictation-1.0.0.dist-info/METADATA,sha256=ORuUcuQw31fwaHjdO55tTVmLjGv9nxn2YFt0LppBmqE,17591
+dictation-1.0.0.dist-info/WHEEL,sha256=52BFRY2Up02UkjOa29eZOS2VxUrpPORXg1pkohGGUS8,91
+dictation-1.0.0.dist-info/top_level.txt,sha256=4ChkzqzYWFJx61tY8Tdu8M_ZZGz42k8F7tkp-jP3qTI,10
+dictation-1.0.0.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+dictation-1.0.0.dist-info/RECORD,,

dictation-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (76.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dictation-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dictation

dictation-1.0.0.dist-info/zip-safe

@@ -0,0 +1 @@
+