dictation 1.0.0__tar.gz

dictation-1.0.0/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/PKG-INFO

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