enumerific 0.0.0__tar.gz

enumerific-0.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.

enumerific-0.0.0/PKG-INFO

@@ -0,0 +1,4 @@
+Metadata-Version: 2.2
+Name: enumerific
+Version: 0.0.0
+License-File: LICENSE.md

enumerific-0.0.0/README.md

@@ -0,0 +1,126 @@
+# Enumerific Enums
+
+The `enumerific` library provides several useful extensions to the Python built-in `enums` library.
+
+### Requirements
+
+The Enumerific 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 Enumerific library is available from PyPi, so may be added to a project's dependencies via its `requirements.txt` file or similar by referencing the Enumerific library's name, `enumerific`, or the library may be installed directly into your local runtime environment using `pip install` by entering the following command, and following any prompts:
+
+	$ pip install enumerific
+
+### Usage
+
+To use the Enumerific library, simply import the library and use it like you would the built-in `enum` library as a drop-in replacement:
+
+```
+import enumerific
+
+class MyEnum(enumerific.Enum):
+  Option1 = "ABC"
+  Option2 = "DEF"
+
+val = MyEnum.Option1
+```
+
+You can also import the `Enum` class directly from the `enumerific` library and use it directly:
+
+```
+from enumerific import Enum
+
+class MyEnum(Enum):
+  Option1 = "ABC"
+  ...
+```
+
+The Enumerific library's own `Enum` class is a subclass of the built-in `enum.Enum` class, so all of the built-in functionality of `enum.Enum` is available, as well as several additional class methods:
+
+* `reconcile(value: object, default: Enum = None, raises: bool = False) -> Enum` – The `reconcile` method allows for an enumeration's value or an enumeration option's name to be reconciled against a matching enumeration option. If the provided value can be matched against one of the enumeration's available options, that option will be returned, otherwise there are two possible behaviours: if the `raises` keyword argument has been set to or left as `False` (its default), the value assigned to the `default` keyword argument will be returned, which may be `None` if no default value has been specified; if the `raises` argument has been set to `True` an `EnumValueError` exception will be raised as an alert that the provided value could not be matched. One can also provide an enumeration option as the input value to the `reconcile` method, and these will be validated and returned as-is.
+* `validate(value: object) -> bool` – The `validate` method takes the same range of input values as the `reconcile` method, and returns `True` when the provided value can be reconciled against an enumeration option, or `False` otherwise.
+* `options() -> list[Enum]` – The `options` method provides easy access to the list of the enumeration's available options.
+
+The benefits of being able to validate and reconcile various input values against an enumeration, include allowing for a controlled vocabulary of options to be checked against, and the ability to convert enumeration values into their corresponding enumeration option. This can be especially useful when working with input data where you need to convert those values to their corresponding enumeration options, and to be able to do so without maintaining boilerplate code to perform the matching and assignment.
+
+Some examples of use include the following code samples, where each make use of the example `MyEnum` class, defined as follows:
+
+```
+from enumerific import Enum
+
+class MyEnum(Enum):
+  Option1 = "ABC"
+  Option2 = "DEF"
+```
+
+#### Example 1: Reconciling a Value
+
+```
+# Given a string value in this case
+value = "ABC"
+
+# Reconcile it to the associated enumeration option
+value = MyEnum.reconcile(value)
+
+assert value == MyEnum.Option1  # asserts successfully
+assert value is MyEnum.Option1  # asserts successfully as enums are singletons
+```
+
+#### Example 2: Reconciling an Enumeration Option Name
+
+```
+# Given a string value in this case
+value = "Option1"
+
+# Reconcile it to the associated enumeration option
+value = MyEnum.reconcile(value)
+
+assert value == MyEnum.Option1  # asserts successfully
+assert value is MyEnum.Option1  # asserts successfully as enums are singletons
+```
+
+#### Example 3: Validating a Value
+
+```
+# The value can be an enumeration option's name, its value, or the enumeration option
+value = "Option1"
+value = "ABC"
+value = MyEnum.Option1
+
+if MyEnum.validate(value) is True:
+    # do something if the value could be validated
+else:
+    # do something else if the value could not be validated
+```
+
+#### Example 4: Iterating Over Enumeration Options
+
+```
+for option in MyEnum.options():
+    # do something with each option
+    print(option.name, option.value)
+```
+
+### Unit Tests
+
+The Enumerific 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 is [installed](https://docs.docker.com/engine/install/), and perform the following commands, which will build the Docker image via `docker compose build` and then run the tests via `docker compose run` – the output of running 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 `-vv` to enable verbose output:
+
+```
+$ docker compose run tests -vv
+```
+
+See the documentation for [PyTest](https://docs.pytest.org/en/latest/) regarding available optional command line arguments.
+
+### Copyright & License Information
+
+Copyright © 2024–2025 Daniel Sissman; Licensed under the MIT License.

enumerific-0.0.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+addopts = "-ra -q"
+testpaths = [
+    "tests"
+]
+
+[tool.black]
+line-length = 88
+target-version = ['py310']
+include = '\.pyi?$'
+extend-exclude = '''
+/(
+  # The following are specific to Black, you probably don't want those.
+  | blib2to3
+  | tests/data
+  | profiling
+)/
+'''

enumerific-0.0.0/setup.cfg

@@ -0,0 +1,39 @@
+[project]
+name = enumerific
+version = file: source/enumerific/version.txt
+description = Simplifies working with Python enums.
+long_description = file: README.md, CHANGELOG.md
+long_description_content_type = text/markdown
+keywords = enum, enumeration, enumerations
+author = Daniel Sissman
+license = MIT
+classifiers = 
+	License :: OSI Approved :: MIT License
+	Programming Language :: Python :: 3
+	Programming Language :: Python :: 3.9
+	Programming Language :: Python :: 3.10
+	Programming Language :: Python :: 3.11
+	Programming Language :: Python :: 3.12
+requires-python = ">=3.9"
+
+[project.urls]
+Documentation = "https://github.com/bluebinary/enumerific/blob/main/README.md"
+Changelog = "https://github.com/bluebinary/enumerific/blob/main/CHANGELOG.md"
+Repository = "https://github.com/bluebinary/enumerific"
+Issues = "https://github.com/bluebinary/enumerific/issues"
+
+[options]
+zip_safe = True
+include_package_data = True
+package_dir = 
+	=source
+packages = find:
+install_requires = 
+
+[options.packages.find]
+where = source
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

enumerific-0.0.0/setup.py

@@ -0,0 +1,6 @@
+#!/usr/bin/env python
+
+# Used to create editable installs
+import setuptools
+
+setuptools.setup()

enumerific-0.0.0/source/enumerific/__init__.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+from enum import *
+
+import logging
+
+
+class EnumValueError(ValueError):
+    pass
+
+
+logger = logging.getLogger(__name__)
+
+
+class Enum(Enum):
+    """An extended Enum class that provides support for validating an Enum value and
+    accepting either enumeration class properties as enumeration values or their string
+    names or values, and providing straightforward access to the enumeration values an
+    Enum class holds."""
+
+    @classmethod
+    def validate(cls, value: Enum | str | int | object) -> bool:
+        """Determine if an enum value name or enum value is valid or not"""
+
+        try:
+            return cls.reconcile(value=value, default=None) is not None
+        except EnumValueError as exception:
+            return False
+
+    @classmethod
+    def reconcile(
+        cls,
+        value: Enum | str | int | object,
+        default: Enum = None,
+        raises: bool = False,
+    ) -> Enum | None:
+        """Reconcile enum values and enum names to their corresponding enum option, as
+        well as allowing valid enum options to be returned unmodified; if the provided
+        enum option, enum value or enum name cannot be reconciled and if a default value
+        has been provided, the default value will be returned instead and a warning
+        message will be logged, otherwise an EnumValueError exception will be raised."""
+
+        if isinstance(value, str):
+            for prop, enumeration in cls.__members__.items():
+                if enumeration.name.casefold() == value.casefold():
+                    return enumeration
+                elif (
+                    isinstance(enumeration.value, str)
+                    and enumeration.value.casefold() == value.casefold()
+                ):
+                    return enumeration
+        elif isinstance(value, int) and not isinstance(value, bool):
+            for prop, enumeration in cls.__members__.items():
+                if isinstance(enumeration.value, int) and enumeration.value == value:
+                    return enumeration
+        elif isinstance(value, bool):
+            for prop, enumeration in cls.__members__.items():
+                if enumeration.value is value:
+                    return enumeration
+        elif isinstance(value, cls):
+            if value in cls:
+                return value
+        elif not value is None:
+            for prop, enumeration in cls.__members__.items():
+                if enumeration.value == value:
+                    return enumeration
+
+        if value is not None:
+            if raises is True:
+                raise EnumValueError(
+                    "The provided value, %r, is invalid and does not correspond with this enumeration's options!"
+                    % (value)
+                )
+            else:
+                logger.warning(
+                    "The provided value, %r, is invalid, but a default, %r, has been provided, and will be returned instead!",
+                    value,
+                    default,
+                )
+
+        return default
+
+    @classmethod
+    def options(cls) -> list[Enum]:
+        """Provide straightforward access to the list of enumeration options"""
+
+        return cls.__members__.values()

enumerific-0.0.0/source/enumerific.egg-info/PKG-INFO

@@ -0,0 +1,4 @@
+Metadata-Version: 2.2
+Name: enumerific
+Version: 0.0.0
+License-File: LICENSE.md

enumerific-0.0.0/source/enumerific.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE.md
+README.md
+pyproject.toml
+setup.cfg
+setup.py
+source/enumerific/__init__.py
+source/enumerific.egg-info/PKG-INFO
+source/enumerific.egg-info/SOURCES.txt
+source/enumerific.egg-info/dependency_links.txt
+source/enumerific.egg-info/top_level.txt
+source/enumerific.egg-info/zip-safe
+tests/test_enumerific_library.py

enumerific-0.0.0/source/enumerific.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

enumerific-0.0.0/source/enumerific.egg-info/top_level.txt

@@ -0,0 +1 @@
+enumerific

enumerific-0.0.0/source/enumerific.egg-info/zip-safe

@@ -0,0 +1 @@
+

enumerific-0.0.0/tests/test_enumerific_library.py

@@ -0,0 +1,135 @@
+import pytest
+import enum
+import enumerific
+
+
+def test_type(EnumSampleA, EnumSampleB):
+    """Ensure that Enumerific `Enum` classes are valid `enum.Enum` and `enumerific.Enum`
+    classes by checking their inheritance hierarchy conforms to that which is expected
+    """
+
+    assert issubclass(EnumSampleA, enum.Enum)
+    assert issubclass(EnumSampleA, enumerific.Enum)
+    assert issubclass(EnumSampleB, enum.Enum)
+    assert issubclass(EnumSampleB, enumerific.Enum)
+
+
+def test_type_equivalence(EnumSampleA, EnumSampleB):
+    """Ensure that the sample Enumerific `Enum` subclasses conform to their expected equivalence"""
+
+    assert EnumSampleA is EnumSampleA
+    assert EnumSampleA is not EnumSampleB
+    assert EnumSampleB is EnumSampleB
+    assert EnumSampleB is not EnumSampleA
+
+
+def test_reconciliation_success(EnumSampleA):
+    """Ensure that the enumeration values reconcile to their expected enumeration options"""
+
+    assert EnumSampleA.reconcile("Value1") is EnumSampleA.Value1
+    assert EnumSampleA.reconcile("Value2") is EnumSampleA.Value2
+    assert EnumSampleA.reconcile(3) is EnumSampleA.Value3
+    assert EnumSampleA.reconcile(EnumSampleA.Value2) is EnumSampleA.Value2
+
+
+def test_reconciliation_failure(EnumSampleA):
+    """Ensure that the enumeration values reconcile to their expected enumeration options"""
+
+    assert EnumSampleA.reconcile("Value3", default=None) is not EnumSampleA.Value1
+    assert EnumSampleA.reconcile("123", default=None) is not EnumSampleA.Value1
+    assert EnumSampleA.reconcile(123, default=None) is not EnumSampleA.Value1
+    assert EnumSampleA.reconcile(True, default=None) is not EnumSampleA.Value1
+
+
+def test_reconciliation_without_default_fallback_success(EnumSampleA):
+    """Ensure that attempting to reconcile an invalid enumeration value, while providing
+    no default fallback value results in an EnumValueError exception being raised"""
+
+    assert EnumSampleA.reconcile(4, default=EnumSampleA.Value1) is EnumSampleA.Value1
+    assert EnumSampleA.reconcile(4, default=EnumSampleA.Value2) is EnumSampleA.Value2
+    assert EnumSampleA.reconcile(4, default=EnumSampleA.Value3) is EnumSampleA.Value3
+
+
+def test_reconciliation_failure_with_raises_exception_disabled(EnumSampleA):
+    """Ensure that attempting to reconcile an invalid enumeration value, while providing
+    a None default fallback value results in a None value being returned"""
+
+    # Note the default value for the 'raises' keyword argument is False (disabled)
+    assert EnumSampleA.reconcile("Value4", default=None) is None
+
+
+def test_reconciliation_failure_with_raises_exception_enabled(EnumSampleA):
+    """Ensure that attempting to reconcile an invalid enumeration value, while calling
+    the reconcile method with the raises=True argument raises the expected exception"""
+
+    # Set the 'raises' keyword argument to False to prevent raising an exception; this
+    # is the default behaviour for the reconcile function, but is used below for clarity
+    assert EnumSampleA.reconcile("Value4", raises=False) is None
+
+    with pytest.raises(enumerific.EnumValueError) as exception:
+        # Set the 'raises' keyword argument to True to enable raising an exception; this
+        # overrides the default exception behaviour, and must be specified to override
+        assert EnumSampleA.reconcile("Value4", raises=True) is None
+
+        assert (
+            str(exception)
+            == "EnumValueError: The provided value, 'Value4', is invalid and does not correspond with this enumeration's options!"
+        )
+
+
+def test_validation_success(EnumSampleA, EnumSampleB):
+    """Ensure that values which correspond to enumeration options validate as True"""
+
+    assert EnumSampleA.validate("Value1") is True
+    assert EnumSampleA.validate("Value2") is True
+    assert EnumSampleA.validate(3) is True
+    assert EnumSampleA.validate(EnumSampleA.Value1) is True
+    assert EnumSampleA.validate(EnumSampleA.Value2) is True
+    assert EnumSampleA.validate(EnumSampleA.Value3) is True
+    assert EnumSampleA.validate("Value4") is False
+
+    assert EnumSampleB.validate("Value1") is True
+    assert EnumSampleB.validate("Value2") is True
+    assert EnumSampleB.validate("Value3") is True
+    assert EnumSampleB.validate("Value4") is True
+
+
+def test_validation_failure(EnumSampleA, EnumSampleB):
+    """Ensure that values which do not correspond to enumeration options validate as False"""
+
+    assert EnumSampleA.validate("Value4") is False
+    assert EnumSampleA.validate(1234243) is False
+    assert EnumSampleA.validate(EnumSampleB.Value1) is False
+
+
+def test_iteration(EnumSampleA, EnumSampleB):
+    """Ensure that iterating over the enumeration options produces the expected result"""
+
+    options = {}
+
+    for option in EnumSampleA.options():
+        options[option.name] = option.value
+
+    # EnumSampleA defined in conftest.py has three options
+    assert len(options) == 3
+
+    assert options == {
+        "Value1": "value1",
+        "Value2": "value2",
+        "Value3": 3,
+    }
+
+    options = {}
+
+    for option in EnumSampleB.options():
+        options[option.name] = option.value
+
+    # EnumSampleB defined in conftest.py has four options
+    assert len(options) == 4
+
+    assert options == {
+        "Value1": "value1",
+        "Value2": "value2",
+        "Value3": 3,
+        "Value4": 4.5678,
+    }