vcti-enum
Value-generated string enums and a serialization bridge that keeps your internal enums decoupled from the strings on the wire.
Overview
vcti-enum does two things. First, it provides StrEnum base classes
whose member values are auto-generated from a naming convention —
declare the convention once (lowercase, camelCase, PascalCase, …) and
every value is derived from the member name, so nothing drifts when you
rename or add members.
Second, it separates the enum your program uses from the strings the
outside world sees. An EnumCoder bridges the two directions, and the
Pydantic helpers wire that bridge into a model field: internally the
enum can be an IntEnum, a StrEnum, or anything else, while the JSON,
config files, and API schema speak stable strings. The wire carries
whatever the coder's value_generator emits, so internal changes that
leave its output alone — renumbering, switching base class — never move
the contract. With a name-based generator a rename does change the
string; generate from an explicit mapping if renames must be safe too.
The three pieces build on each other; use only the layer you need:
Value-generated enums
│
▼
EnumCoder ← the serialization bridge; works with any Enum
│
▼
Pydantic integration ← optional
The package has zero required dependencies. Pydantic 2 is optional
and only needed for the FIELD attribute and the @enum_for_pydantic
attachment to take effect.
Contents
- Installation
- Choosing an entry point
- Quick Start
- Enum base classes
- Public API
- Dependencies
- Documentation
Installation
pip install vcti-enum
pip install "vcti-enum[pydantic]" # with the Pydantic integration
In requirements.txt
vcti-enum>=2.1.0
In pyproject.toml dependencies
dependencies = [
"vcti-enum>=2.1.0",
]
Choosing an entry point
The package has three entry points that build on each other. Pick by what you need:
| You want to… | Use | Needs pydantic |
|---|---|---|
| Give an enum string values derived from the member names by a convention | a base class — EnumValueLowerCase and friends |
no |
| Encode/decode any enum to and from custom strings (serialize, parse) | EnumCoder |
no |
| A Pydantic field that holds the enum member but reads/writes strings on the wire | @enum_for_pydantic + MyEnum.FIELD |
yes |
The three-layer idea underneath all of this:
flowchart LR
subgraph prog["Your program — internal"]
member["Theme.DARK<br/>enum member · has .value"]
end
subgraph wire["JSON · config · API — external"]
string["'dark'<br/>stable encoded string"]
end
member -->|"CODER.encode"| string
string -->|"CODER.decode"| member
Your code works with the enum member; everyone else sees the string. The encoded string is derived from the member name, not its value.
Quick Start
Value-generated enums
from vcti.enum import EnumValueLowerCase, auto_enum_value
class FileFormat(EnumValueLowerCase):
JSON = auto_enum_value() # value: "json"
CSV = auto_enum_value() # value: "csv"
PARQUET = auto_enum_value() # value: "parquet"
FileFormat.JSON.value # "json"
FileFormat.JSON == "json" # True (StrEnum members are str)
The value is derived from the member name by the base class's
convention, so renaming JSON to JSON_LINES updates its value to
"json_lines" automatically.
EnumCoder for serialization
EnumCoder maps an enum to and from strings using any
value_generator you supply — independent of the enum's own .value.
It works with any Python Enum, not only the value-generated base
classes in this package:
from enum import Enum
from vcti.enum import EnumCoder
class Color(Enum):
RED = 1
GREEN = 2
coder = EnumCoder(Color, value_generator=lambda e: e.name.lower(), default=Color.RED)
coder.encode(Color.RED) # "red"
coder.decode("green") # Color.GREEN
coder.default # "red"
coder.list # ["red", "green"]
Both directions are precomputed at construction, so encode/decode
are O(1) lookups and two members mapping to the same string is rejected
immediately.
Pydantic integration
@enum_for_pydantic attaches a ready-made, member-bound field
annotation, MyEnum.FIELD. Used in a model it validates against the
encoded strings, decodes them to the enum member on the way in, and
encodes back on the way out — so the model attribute is the real member
while the JSON and schema stay strings.
from pydantic import BaseModel
from vcti.enum import EnumValueLowerCase, auto_enum_value, enum_for_pydantic
@enum_for_pydantic(default="JSON")
class FileFormat(EnumValueLowerCase):
JSON = auto_enum_value()
CSV = auto_enum_value()
class ExportConfig(BaseModel):
format: FileFormat.FIELD # type + default + description bundled
ExportConfig().format # FileFormat.JSON (the member)
ExportConfig(format="csv").format # FileFormat.CSV (decoded from "csv")
ExportConfig(format="csv").model_dump_json() # '{"format":"csv"}'
If no default is given, the field is required — building the
model without it raises ValidationError.
setup_enum_for_pydantic() is the function form of the decorator; use
it when the enum is defined elsewhere — a stdlib IntEnum, a
third-party class — and you cannot decorate it in place.
The decoupling pays off most when the internal enum is not a string.
Here the server stores a theme as an integer while clients speak
"light" / "dark":
from enum import IntEnum
from pydantic import BaseModel
from vcti.enum import setup_enum_for_pydantic
class Theme(IntEnum):
LIGHT = 1
DARK = 2
setup_enum_for_pydantic(
Theme,
value_generator=lambda e: e.name.lower(), # "LIGHT" -> "light"
default_member="LIGHT",
)
class UiSettings(BaseModel):
theme: Theme.FIELD
UiSettings().theme # Theme.LIGHT — an IntEnum member, .value == 1
UiSettings(theme="dark").theme # Theme.DARK — decoded from the wire string
UiSettings(theme="dark").model_dump_json() # '{"theme":"dark"}'
Renumber LIGHT = 100 tomorrow and nothing on the API side notices —
the encoded strings come from the member name, not its value.
Enum base classes
| Class | Convention | FIRST_VALUE becomes |
|---|---|---|
EnumValueSameAsName |
Unchanged | FIRST_VALUE |
EnumValueLowerCase |
lower_case | first_value |
EnumValueCamelCase |
camelCase | firstValue |
EnumValuePascalCase |
PascalCase | FirstValue |
EnumValueCapitalizedPhrase |
Title Case | First Value |
EnumValueSpaceSeparatedLower |
space lower | first value |
All extend StrEnum, so members are string instances. Need another
convention? create_enum_class() builds a base from any
str -> str function — see the Extension Guide.
Public API
| Symbol | Import | Purpose |
|---|---|---|
auto_enum_value() |
vcti.enum |
Triggers automatic value generation |
create_enum_class() |
vcti.enum |
Factory to create custom enum base classes |
EnumValueSameAsName |
vcti.enum |
Base class: value = member name |
EnumValueLowerCase |
vcti.enum |
Base class: value = lowercase |
EnumValueCamelCase |
vcti.enum |
Base class: value = camelCase |
EnumValuePascalCase |
vcti.enum |
Base class: value = PascalCase |
EnumValueCapitalizedPhrase |
vcti.enum |
Base class: value = Title Case |
EnumValueSpaceSeparatedLower |
vcti.enum |
Base class: value = space separated |
EnumCoder |
vcti.enum |
Flexible enum serialization/deserialization |
setup_enum_for_pydantic() |
vcti.enum |
Attach encoder attributes to an enum class |
enum_for_pydantic() |
vcti.enum |
Decorator form of the setup function |
get_enum_field_description() |
vcti.enum |
Build a field description string on its own |
Attributes attached by setup_enum_for_pydantic / @enum_for_pydantic
| Attribute | Type | What it contains |
|---|---|---|
CODER |
EnumCoder |
The encoder instance for this enum |
ENCODED_DEFAULT |
str | None |
Encoded string of the default member; None if the field is required |
ENCODED_LIST |
list[str] |
All encoded strings, as a list |
ENCODED_TUPLE |
tuple[str, ...] |
All encoded strings, as a tuple |
FIELD |
member-bound Annotated[...] |
Model attribute is the enum member; wire is the encoded string. Required when no default |
These are class-level: one enum class carries one encoding policy, and
setting it up again replaces the attributes. To encode the same enum
more than one way, keep separate EnumCoder instances.
Removed in 2.0: the 1.x aliases
DEFAULT_VALUE,LIST,TUPLE, andLITERALare no longer attached. UseENCODED_DEFAULT,ENCODED_LIST,ENCODED_TUPLE, andFIELDrespectively.
Dependencies
None required. Standard library only.
Optional: pydantic>=2 (the pydantic extra), for the FIELD
attribute and the @enum_for_pydantic attachment. An installed
Pydantic 1.x raises ImportError at setup rather than silently
leaving FIELD off.
Documentation
| If you want to… | Read |
|---|---|
| Get started using the package | Quick Start above |
| Understand the three-layer model and design decisions | docs/design.md |
| Navigate and understand the source | docs/source-guide.md |
| Add a new enum base class or custom coder | docs/extending.md |
Metadata
Release files for vcti-enum 2.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vcti_enum-2.1.0.tar.gz | 30.9 kB | With provenance | Details for vcti_enum-2.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vcti_enum-2.1.0-py3-none-any.whl | Python 3 | none | any | Details for vcti_enum-2.1.0-py3-none-any.whl |
Total release size: 47.1 kB
Release files / vcti_enum-2.1.0.tar.gz
| Download URL | vcti_enum-2.1.0.tar.gz |
|---|---|
| Size | 30.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f9b7263f055462f835e85fcad7b60f77a8ed1919308c6e73d29c4d684f87f5d5
|
|
BLAKE2b-256 checksum How to use checksums |
4a73e35942cbb0716db0fc7328b79fbe685f41875d7988e7754915d0ab9b389b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logRelease files / vcti_enum-2.1.0-py3-none-any.whl
| Download URL | vcti_enum-2.1.0-py3-none-any.whl |
|---|---|
| Size | 16.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
81125759733959ac239cb20da37de8c9c0292c8aa44a988f43a6e89b7b50fb5f
|
|
BLAKE2b-256 checksum How to use checksums |
b39d5aea4fc35219b5934af0cc88cf100175cf6495868264a9ce1ff04e0ea4ff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logSecurity for vcti-enum 2.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for vcti_enum-2.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.