StrEnum

0.4.15 · active · verified Sun Mar 29

StrEnum is a Python library that provides an `Enum` class that inherits from `str`, allowing enumeration members to behave directly like strings. This is particularly useful for scenarios involving APIs, JSON serialization, and generally replacing 'magic strings' with type-safe, readable constants. The library is actively maintained, with version 0.4.15 being the current release, and follows a frequent, minor-version release cadence.

Warnings

breaking Support for Python 3.6 was dropped in version 0.4.9. Users on older Python versions will need to pin `strenum<0.4.9` or upgrade their Python environment.
Fix: Upgrade Python to 3.7+ or pin `strenum` to a version less than 0.4.9 (`pip install "strenum<0.4.9"`).
gotcha Python 3.11 introduced `enum.StrEnum` in the standard library. The `strenum` library is *not* a drop-in replacement for the standard library's `StrEnum`, especially regarding the default behavior of `auto()`. The `strenum.StrEnum` preserves the member name as its value when `auto()` is used (e.g., `MY_VALUE` becomes `'MY_VALUE'`), while the standard library's `enum.StrEnum` defaults to lowercasing (`MY_VALUE` becomes `'my_value'`).
Fix: Be explicit when using `auto()`: use `strenum.StrEnum` for literal name values, or `strenum.LowercaseStrEnum`, `strenum.CamelCaseStrEnum`, etc., for specific casing. If migrating to `enum.StrEnum` (stdlib), be aware of its default lowercasing behavior for `auto()` or define a custom `_generate_next_value_`.
gotcha When using the case-converting `StrEnum` subclasses (e.g., `CamelCaseStrEnum`, `KebabCaseStrEnum`), the automatic name conversion to value only applies when `auto()` is used. Manually assigned values will be used exactly as provided, without any case transformation.
Fix: Always use `auto()` if you expect the name conversion to apply to the member's value, or explicitly assign the desired string value if it should not be converted.
gotcha While `strenum` members compare equal to their underlying string values (e.g., `MyEnum.FOO == "FOO"` returns `True`), relying on this for critical logic can sometimes lead to subtle bugs or typos. It's generally safer and more type-explicit to compare enum members directly (e.g., `MyEnum.FOO is MyEnum.FOO` or `MyEnum.FOO == another_enum_member`).
Fix: Prefer comparing enum members to other enum members. If comparing to a string is necessary, consider its implications for type safety and potential errors.
gotcha In some parts of the Python standard library, checks for `type(unknown) == str` are performed instead of `isinstance(unknown, str)`. In these specific cases, a `strenum` member might not be recognized as a plain string. To ensure compatibility, you might need to explicitly cast the enum member to `str` (e.g., `str(MyStrEnum.MY_MEMBER)`).
Fix: If encountering unexpected type mismatches in string-sensitive standard library functions, explicitly cast the `strenum` member to `str`.

Install

pip install strenum Install latest version

Imports

StrEnum
```
from strenum import StrEnum
```
LowercaseStrEnum
```
from strenum import LowercaseStrEnum
```
CamelCaseStrEnum
```
from strenum import CamelCaseStrEnum
```
auto
```
from enum import auto
```
The 'auto' function is part of Python's standard 'enum' module, not 'strenum'.

Quickstart

This quickstart demonstrates defining a basic `StrEnum` where `auto()` uses the member name directly, and a `LowercaseStrEnum` which converts `auto()` values to lowercase. It also shows manual string assignment and how `StrEnum` members behave like strings, including comparison.

from enum import auto
from strenum import StrEnum, LowercaseStrEnum

class HttpMethod(StrEnum):
    GET = auto() # Value will be 'GET'
    POST = 'post_value' # Explicitly assigned string value
    PUT = auto()

class FileExtension(LowercaseStrEnum):
    TXT = auto() # Value will be 'txt'
    PDF = auto()

assert HttpMethod.GET == 'GET'
assert HttpMethod.POST == 'post_value'
assert HttpMethod.PUT == 'PUT'

assert FileExtension.TXT == 'txt'
assert FileExtension.PDF == 'pdf'

print(f"HTTP Method: {HttpMethod.GET}")
print(f"File Type: {FileExtension.PDF}")

# Enums compare equal to their string value
assert HttpMethod.GET == "GET"

# However, it's generally recommended to compare enum to enum for type safety
if HttpMethod.GET is HttpMethod.GET:
    print("GET method detected.")

view raw JSON →