Metadata-Version: 2.4
Name: ordered_str_enum
Version: 0.1.0
Summary: Enums which are ordered, by int value, and can be compared with both integers and strings.
Author-email: storm-g <storm-g-code@proton.me>
License-Expression: MIT
Project-URL: Repository, https://bitbucket.org/storm-g-za/ordered_str_enum
Keywords: enum,str,strenum,ordered
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Dynamic: license-file

A simple extension of [IntEnum](https://docs.python.org/3/library/enum.html#enum.IntEnum) used to create ordered
[StrEnums](https://docs.python.org/3/library/enum.html#enum.StrEnum).

### What is an `OrderedStrEnum`?
Simply, `OrderdStrEnums` are like `StrEnum` but have an integer value and their string "value" is equal to their name.
This means that `OrderedStrEnum` are ordered (by their integer values) and can be compared with both integers and
strings.

For example, if we have an `OrderedStrEnum` `Foo` and we want it to contain the strings `'One'`, `'Two'`, and `'Three'`
in order, we can achieve this as follows:
```python
from ordered_str_enum import OrderedStrEnum

class Foo(OrderedStrEnum):
  One = 1
  Two = 2
  Three = 3
```
This now gives us the power to compare however we wish, even without case sensitivity
```commandline
>>> Foo.One == 1
True
>>> Foo.One < 'three'
True
>>> Foo.One <= 'Two'
True
>>> Foo.One > 2
False
```
It's that simple.

**Installation**
```
pip install ordered-str-enum
```
Then import
```
from ordered_str_enum import OrderedStrEnum
```


Check out the [source code](https://bitbucket.org/storm-g-za/ordered_str_enum).

### Intersecting `OrderedStrEnum`
What happens when two different inheritors of `OrderedStrEnum` intersect (share common entries)?

`OrderedStrEnum` inherits from `IntEnum` so they would be compared by their integer values. Though, considering
this class intends to add string comparisons to the mix it could lead to confusion. For example if `Foo.A` is `1`
but `Bar.A` is `-1` the result may not be inherently obvious when comparing `Foo.A` with `Bar.A`. It
would not be unlikely to expect `Foo.A == Bar.A` to return `True` since they both can be considered equivalent with the
strings `'A'` and `'a'`, but his is not the case as `1 != -1` and so you'd actually get `False`. This is the result when
comparing the Enums as children of `IntEnum`.

To prevent this confusion, comparison between different children of `OrderedStrEnum` is disabled by default. Each
inheriting class has an internal flag marking them as "strict". Comparison between different inheritors will
raise a `TypeError` unless **both** have this flag set to `False`:

```python
class Foo(OrderedStrEnum):
  A = 1

class Bar(OrderedStrEnum):
  A = 1

Foo.strict()
# True
Bar.strict()
# True

Foo.A == Bar.A
# raises TypeError
```
Both need to set strict to `False`
```python
class Foo(OrderedStrEnum, strict=False):
  A = 1

class Bar(OrderedStrEnum, strict=False):
  A = 1

Foo.strict()
# False
Bar.strict()
# False
Foo.A == Bar.A
# True
```


### Why does `OrderedStrEnum` exist?
I decided to make this reusable when creating Enums for the days of a week in another project.
See the days of the week implementation: _coming soon..._

