Skip to main content

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

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, and LITERAL are no longer attached. Use ENCODED_DEFAULT, ENCODED_LIST, ENCODED_TUPLE, and FIELD respectively.


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)

Source distribution for vcti-enum 2.1.0
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)

Table of built distributions (wheels) for vcti-enum 2.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page