open-enum 0.1.0__tar.gz

open_enum-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.3
+Name: open-enum
+Version: 0.1.0
+Summary: Add your description here
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# OpenEnum
+
+Enum implementation that accepts unknown values.
+
+## Rationale
+
+When parsing external data into Python data types, sometimes we deal with enumerated data types which have several documented possible values, but should be parsed with assumption that more possible values will be added over time.
+
+Code that reads such values should be written with **forward compatibility** in mind: handle all known values, but also include a fallback for any other values that can appear in the future. Options for doing this in Python include parsing as `str`, as `EnumType | str` or as `EnumType` with a `_missing_` method defined.
+
+This library attempts to provide a pattern for handling such values in a **type-safe manner that plays well with existing linters**.
+
+## Usage
+
+### Parsing possibly-unknown values
+
+Define an `OpenEnum` subclass with one member value of `None` that will be used as fallback:
+
+```python
+from open_enum import OpenEnum
+
+
+class Status(OpenEnum):
+    NEW = "new"
+    IN_PROGRESS = "in_progress"
+    DONE = "done"
+
+    UNKNOWN = None
+```
+
+Normal values work intuitively:
+
+```python
+new = Status.NEW
+done = Status.DONE
+assert Status("new") == new
+assert Status("new") != done
+```
+
+But unlike normal enum, you can also instantiate the type with unknown values:
+
+```python
+blocked = Status("blocked")
+cancelled = Status("cancelled")
+assert isinstance(blocked, Status)
+```
+
+These compare as different to each other:
+
+```python
+assert blocked != new
+assert blocked != cancelled
+```
+
+but still compare as equal if the underlying value matches:
+
+```python
+assert blocked == Status("blocked")
+```
+
+### Checking for unknown values using the `UNKNOWN` marker
+
+The `UNKNOWN` value defined on the enum type is a special **marker object**, not an actual enum member:
+
+```python
+assert not isinstance(Status.UNKNOWN, Status)
+```
+
+> [!NOTE]  
+> You'll never get `Status.UNKNOWN` from parsing; it's meant to be used explicitly.
+
+The unknown marker compares as equal to unknown values, but not to known values:
+
+```python
+assert Status.UNKNOWN == Status("blocked")
+assert Status.UNKNOWN == Status("cancelled")
+
+assert Status.UNKNOWN != Status("new")
+assert Status.UNKNOWN != Status("in_progress")
+```
+
+### Pattern matching
+
+All this allows you to do **exhaustive pattern matching** that your linter will validate for you:
+
+```python
+
+class Response:
+    status: Status
+    ...
+
+
+match response.status:
+    case Status.NEW:
+        print("new!")
+    case Status.IN_PROGRESS:
+        print("in progress...")
+    case Status.DONE:
+        print("nothing more to do")
+    case Status.UNKNOWN:
+        print("oh, encountered a status we don't know!")
+    case _:
+        assert_never(response.status)
+```
+
+Now if you go back to `class Status` and add enum members for `"blocked"` or `"cancelled"`, your type checker will ask you to add corresponding `case` arms in this `match` statement.
+
+> [!TIP]
+> The main advantage of this pattern over just using `case _` as fallback is that is that it **communicates the intention that every known value should have a `case` branch**. Thanks to `assert_never`, a type checker can actually check and enforce this!
+
+Importantly, as long as you include `assert_never`, the type checker should nudge you to include a case for `Status.UNKNOWN`:
+
+```python
+match response.status:
+    case Status.NEW:
+        print("new!")
+    case Status.IN_PROGRESS:
+        print("in progress...")
+    case Status.DONE:
+        print("nothing more to do")
+    case _:
+        assert_never(response.status)  # error: Type "Literal[Status.UNKNOWN]" is not assignable to type "Never"
+```
+
+This way as long as you remember about `assert_never()`, you'll have a helpful reminder to add handling of additional unknown values that can be added in the future, even if you already handled all values that are _currently_ documented.

open_enum-0.1.0/README.md

@@ -0,0 +1,125 @@
+# OpenEnum
+
+Enum implementation that accepts unknown values.
+
+## Rationale
+
+When parsing external data into Python data types, sometimes we deal with enumerated data types which have several documented possible values, but should be parsed with assumption that more possible values will be added over time.
+
+Code that reads such values should be written with **forward compatibility** in mind: handle all known values, but also include a fallback for any other values that can appear in the future. Options for doing this in Python include parsing as `str`, as `EnumType | str` or as `EnumType` with a `_missing_` method defined.
+
+This library attempts to provide a pattern for handling such values in a **type-safe manner that plays well with existing linters**.
+
+## Usage
+
+### Parsing possibly-unknown values
+
+Define an `OpenEnum` subclass with one member value of `None` that will be used as fallback:
+
+```python
+from open_enum import OpenEnum
+
+
+class Status(OpenEnum):
+    NEW = "new"
+    IN_PROGRESS = "in_progress"
+    DONE = "done"
+
+    UNKNOWN = None
+```
+
+Normal values work intuitively:
+
+```python
+new = Status.NEW
+done = Status.DONE
+assert Status("new") == new
+assert Status("new") != done
+```
+
+But unlike normal enum, you can also instantiate the type with unknown values:
+
+```python
+blocked = Status("blocked")
+cancelled = Status("cancelled")
+assert isinstance(blocked, Status)
+```
+
+These compare as different to each other:
+
+```python
+assert blocked != new
+assert blocked != cancelled
+```
+
+but still compare as equal if the underlying value matches:
+
+```python
+assert blocked == Status("blocked")
+```
+
+### Checking for unknown values using the `UNKNOWN` marker
+
+The `UNKNOWN` value defined on the enum type is a special **marker object**, not an actual enum member:
+
+```python
+assert not isinstance(Status.UNKNOWN, Status)
+```
+
+> [!NOTE]  
+> You'll never get `Status.UNKNOWN` from parsing; it's meant to be used explicitly.
+
+The unknown marker compares as equal to unknown values, but not to known values:
+
+```python
+assert Status.UNKNOWN == Status("blocked")
+assert Status.UNKNOWN == Status("cancelled")
+
+assert Status.UNKNOWN != Status("new")
+assert Status.UNKNOWN != Status("in_progress")
+```
+
+### Pattern matching
+
+All this allows you to do **exhaustive pattern matching** that your linter will validate for you:
+
+```python
+
+class Response:
+    status: Status
+    ...
+
+
+match response.status:
+    case Status.NEW:
+        print("new!")
+    case Status.IN_PROGRESS:
+        print("in progress...")
+    case Status.DONE:
+        print("nothing more to do")
+    case Status.UNKNOWN:
+        print("oh, encountered a status we don't know!")
+    case _:
+        assert_never(response.status)
+```
+
+Now if you go back to `class Status` and add enum members for `"blocked"` or `"cancelled"`, your type checker will ask you to add corresponding `case` arms in this `match` statement.
+
+> [!TIP]
+> The main advantage of this pattern over just using `case _` as fallback is that is that it **communicates the intention that every known value should have a `case` branch**. Thanks to `assert_never`, a type checker can actually check and enforce this!
+
+Importantly, as long as you include `assert_never`, the type checker should nudge you to include a case for `Status.UNKNOWN`:
+
+```python
+match response.status:
+    case Status.NEW:
+        print("new!")
+    case Status.IN_PROGRESS:
+        print("in progress...")
+    case Status.DONE:
+        print("nothing more to do")
+    case _:
+        assert_never(response.status)  # error: Type "Literal[Status.UNKNOWN]" is not assignable to type "Never"
+```
+
+This way as long as you remember about `assert_never()`, you'll have a helpful reminder to add handling of additional unknown values that can be added in the future, even if you already handled all values that are _currently_ documented.

open_enum-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "open-enum"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.12"
+lincense = "MIT"
+dependencies = []
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+]

open_enum-0.1.0/src/open_enum/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tomasz Wesołowski
+
+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.

open_enum-0.1.0/src/open_enum/__init__.py

@@ -0,0 +1 @@
+from .open_enum import OpenEnum as OpenEnum

open_enum-0.1.0/src/open_enum/open_enum.py

@@ -0,0 +1,55 @@
+from enum import Enum, EnumMeta
+from typing import Type, cast
+
+
+class OpenEnumMeta(EnumMeta):
+    def __new__(cls, name, bases, classdict):
+        # Only use the custom behavior for subclasses
+        if name == "OpenEnum" and bases == (Enum,):
+            return super().__new__(cls, name, bases, classdict)
+
+        # Find the None member in classdict
+        none_items = {k: v for k, v in classdict.items() if v is None}
+        if len(none_items) > 1:
+            raise ValueError("Only one None member is allowed in OpenEnum")
+        if len(none_items) == 0:
+            raise ValueError("An OpenEnum must have a None member")
+        (unknown_key,) = none_items.keys()
+
+        # Create a marker class for this specific enum
+        class UnknownMarker:
+            own_type: Type[Enum]
+            own_members: set[Enum]
+
+            def __eq__(self, other):
+                return (
+                    isinstance(other, self.own_type) and other not in self.own_members
+                )
+
+        # make it not a memmber
+        classdict.pop(unknown_key)
+        classdict._member_names.pop(unknown_key)
+
+        # substitute the marker instad
+        classdict._ignore.append(unknown_key)
+        marker = UnknownMarker()
+        classdict[unknown_key] = marker
+        newcls = cast(Type[OpenEnum], super().__new__(cls, name, bases, classdict))
+
+        # configure the marker
+        marker.own_type = newcls
+        marker.own_members = set(newcls)
+
+        return newcls
+
+
+class OpenEnum(Enum, metaclass=OpenEnumMeta):
+    @classmethod
+    def _missing_(cls, value):
+        instance = object.__new__(cls)
+        instance._name_ = "UNKNOWN"
+        instance._value_ = value
+        instance = cls._value2member_map_.setdefault(value, instance)
+        return instance
+
+    __match_args__ = ("value",)

open_enum-0.1.0/src/open_enum/open_enum_test.py

@@ -0,0 +1,132 @@
+from typing import assert_never
+import pytest
+from open_enum import OpenEnum
+
+
+class Status(OpenEnum):
+    NEW = "new"
+    IN_PROGRESS = "in_progress"
+    DONE = "done"
+
+    UNKNOWN = None
+
+
+# Known values
+new = Status.NEW
+done = Status.DONE
+
+# Unknown values
+blocked = Status("blocked")
+cancelled = Status("cancelled")
+
+
+def test_member_list():
+    assert list(Status) == [Status.NEW, Status.IN_PROGRESS, Status.DONE]
+
+
+def test_basic_equality():
+    assert Status("new") == new
+    assert Status("new") != done
+
+
+def test_subtyping():
+    assert isinstance(blocked, Status)
+
+
+def test_value_equality():
+    assert blocked == Status("blocked")
+    assert blocked != new
+    assert blocked != cancelled
+
+
+def test_unknown_subtyping():
+    assert not isinstance(Status.UNKNOWN, Status)
+
+
+def test_unknown_equality():
+    assert Status.UNKNOWN == Status("blocked")
+    assert Status.UNKNOWN == Status("cancelled")
+    assert Status.UNKNOWN != Status("new")
+    assert Status.UNKNOWN != Status("in_progress")
+
+
+@pytest.mark.parametrize(
+    "input,output",
+    [
+        ("new", "new"),
+        ("in_progress", "in progress"),
+        ("done", "done and done"),
+        ("cancelled", "unknown: cancelled"),
+        ("closed", "unknown: closed"),
+    ],
+)
+def test_pattern_matching_simple(input, output):
+    status = Status(input)
+
+    match status:
+        case Status.NEW:
+            result = "new"
+        case Status.IN_PROGRESS:
+            result = "in progress"
+        case Status.DONE:
+            result = "done and done"
+        case Status.UNKNOWN:
+            result = f"unknown: {status._value_}"
+        case _:
+            assert_never(status)
+
+    assert result == output
+
+
+@pytest.mark.parametrize(
+    "input,output",
+    [
+        ("new", "known value"),
+        ("in_progress", "known value"),
+        ("done", "known value"),
+        ("cancelled", "custom value"),
+        ("blocked", "custom value"),
+        ("cursed", "unknown value"),
+    ],
+)
+def test_pattern_matching_multiple(input, output):
+    status = Status(input)
+
+    match status:
+        case Status.NEW | Status("in_progress") | Status.DONE:
+            result = "known value"
+        case Status("blocked") | Status("cancelled"):
+            result = "custom value"
+        case Status.UNKNOWN:
+            result = "unknown value"
+        case _:
+            assert_never(status)
+
+    assert result == output
+
+
+def test_unknown_only_matches_own_type():
+    class Color(OpenEnum):
+        RED = "red"
+        GREEN = "green"
+
+        UNKNOWN = None
+
+    mauve = Color("mauve")
+    assert mauve == Color.UNKNOWN
+    assert mauve != Status.UNKNOWN
+
+    assert blocked == Status.UNKNOWN
+    assert blocked != Color.UNKNOWN
+
+    assert Color.UNKNOWN != Status.UNKNOWN
+
+
+def test_custom_name_for_undefined():
+    class Color(OpenEnum):
+        RED = "red"
+        NOT_RED = None
+
+    mauve = Color("mauve")
+    assert mauve != Color.RED
+    assert mauve == Color.NOT_RED