literalenum 0.1.1__py3-none-any.whl

literalenum/__init__.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from .literal_enum import LiteralEnum, LiteralEnumMeta
+from .stubgen import main as lestub
+
+import typing_literalenum as core
+
+__all__ = [
+    "LiteralEnum", "LiteralEnumMeta",
+    "plugin",
+    "compatibility_extensions",
+    "lestub",
+    "core"
+]
+
+
+def __getattr__(name: str):
+    if name == "plugin":
+        from .mypy_plugin import plugin
+        return plugin
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

literalenum/compatibility_extensions/__init__.py

@@ -0,0 +1,15 @@
+from .annotated import annotated
+from .base_model import base_model
+from .enum import enum
+from .graphene_enum import graphene_enum
+from .int_enum import int_enum
+from .json_schema import json_schema
+from .literal import literal
+from .regex import regex_str, regex_pattern
+from .sqlalchemy_enum import sqlalchemy_enum
+from .str_enum import str_enum
+from .strawberry_enum import strawberry_enum
+from .bare_class import bare_class
+from .click_choice import click_choice
+from .django_choices import django_choices
+from .random_choice import random_choice

literalenum/compatibility_extensions/annotated.py

@@ -0,0 +1,6 @@
+from typing import Any
+
+
+def annotated(cls, *metadata: Any):
+    from typing import Annotated
+    return Annotated[cls.runtime_literal, *metadata]

literalenum/compatibility_extensions/bare_class.py

@@ -0,0 +1,2 @@
+def bare_class(cls):
+    return type(cls.__name__, (), dict(cls._members_))

literalenum/compatibility_extensions/base_model.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Literal
+
+
+def base_model(
+    enum_cls: type,
+    *,
+    model_name: str | None = None,
+    field_name: str = "value",
+    description: str | None = None,
+) -> type["BaseModel"]:
+    """
+    Create a pydantic BaseModel with a single field that validates against enum_cls.literal.
+    """
+    from pydantic import BaseModel, create_model, Field
+    ann = Literal[*enum_cls.values()]  # <-- Literal["GET","POST",...]
+    default = Field(..., description=description) if description else ...
+
+    return create_model(
+        model_name or f"{enum_cls.__name__}Model",
+        **{field_name: (ann, default)},
+    )

literalenum/compatibility_extensions/click_choice.py

@@ -0,0 +1,3 @@
+def click_choice(cls):
+    import click
+    return click.Choice(list(cls))

literalenum/compatibility_extensions/django_choices.py

@@ -0,0 +1,2 @@
+def django_choices(cls):
+    return [(v, name) for name, v in cls.items()] 

literalenum/compatibility_extensions/enum.py

@@ -0,0 +1,7 @@
+from enum import Enum
+
+import typing_literalenum as core
+
+
+def enum(cls: core.LiteralEnumMeta) -> Enum:
+    return Enum(cls.__name__, dict(cls._members_))

literalenum/compatibility_extensions/graphene_enum.py

@@ -0,0 +1,18 @@
+def graphene_enum(cls) -> type:
+    """Convert this LiteralEnum to a Graphene GraphQL enum type.
+
+    Requires ``graphene`` to be installed.  Uses canonical members
+    only (aliases are excluded)::
+
+        class Color(LiteralEnum):
+            RED = "red"
+            GREEN = "green"
+
+        # use in a Graphene schema
+        ColorEnum = Color.graphene_enum
+    """
+    import enum as _enum
+    import graphene
+
+    PyEnum = _enum.Enum(cls.__name__, dict(cls.unique_mapping))
+    return graphene.Enum.from_enum(PyEnum)

literalenum/compatibility_extensions/int_enum.py

@@ -0,0 +1,9 @@
+from enum import IntEnum
+
+import typing_literalenum as core
+
+
+def int_enum(cls: core.LiteralEnumMeta) -> IntEnum:
+    if not all(isinstance(v, int) for v in cls._ordered_values_ if v is not None):
+        raise TypeError("int_enum only works on a int-valued LiteralEnum")
+    return IntEnum(cls.__name__, dict(cls._members_))

literalenum/compatibility_extensions/json_schema.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+JsonSchema = Dict[str, Any]
+
+
+
+def json_schema(
+    enum_cls: type,
+    *,
+    title: str | None = None,
+    description: str | None = None,
+    nullable: bool | None = None,
+    openapi: bool = False,
+) -> JsonSchema:
+    """
+    Build a JSON Schema (and OpenAPI-friendly) schema for a LiteralEnumMeta class.
+
+    Expects `enum_cls` to have:
+      - _ordered_values_: list/tuple of literal values in order
+      - _members_: dict[str, value]
+
+    Supports literals: str, int, bool, None, bytes.
+    For mixed types, emits a union schema (oneOf / anyOf).
+
+    Params:
+      - nullable:
+          * None (default): inferred from presence of None in values
+          * True/False: force nullable behavior
+      - openapi:
+          * If True: emits OpenAPI 3.0-friendly shape (uses nullable: true)
+          * If False: emits JSON Schema 2020-12-friendly shape (uses type: "null" or oneOf)
+    """
+    values: List[Any] = list(getattr(enum_cls, "_ordered_values_", ()))
+    if not values:
+        raise ValueError(f"{enum_cls!r} has no _ordered_values_")
+
+    # JSON Schema can't represent bytes directly; common convention is base64 string.
+    def _json_type(v: Any) -> str:
+        if v is None:
+            return "null"
+        if isinstance(v, bool):
+            return "boolean"
+        if isinstance(v, int) and not isinstance(v, bool):
+            return "integer"
+        if isinstance(v, str):
+            return "string"
+        if isinstance(v, (bytes, bytearray, memoryview)):
+            return "string"
+        # float literal support not listed in your metaclass, but easy to add if you want:
+        if isinstance(v, float):
+            return "number"
+        raise TypeError(f"Unsupported LiteralEnum value {v!r} (type {type(v).__name__})")
+
+    # Normalize bytes -> base64-ish string representation? (You can swap this.)
+    def _normalize(v: Any) -> Any:
+        if isinstance(v, (bytes, bytearray, memoryview)):
+            # JSON can't carry bytes. Convention: base64 string.
+            # If you prefer "binary" format in OpenAPI, keep as string and add format.
+            return bytes(v).decode("base64", errors="strict")
+        return v
+
+    normalized_values = [_normalize(v) for v in values]
+    types = [_json_type(v) for v in values]
+    unique_types = sorted(set(types))
+
+    has_null = "null" in unique_types
+    inferred_nullable = has_null
+    if nullable is None:
+        nullable = inferred_nullable
+
+    # Remove nulls from enum list if we represent null via nullable/type: null separately.
+    enum_no_null = [v for v, t in zip(normalized_values, types) if t != "null"]
+
+    schema: JsonSchema = {}
+    schema["title"] = title or getattr(enum_cls, "__name__", "LiteralEnum")
+    if description:
+        schema["description"] = description
+
+    # If only one non-null type, simplest representation.
+    non_null_types = [t for t in unique_types if t != "null"]
+
+    def _apply_nullable_oas(s: JsonSchema) -> JsonSchema:
+        if nullable:
+            s["nullable"] = True
+        return s
+
+    # Helper: JSON Schema style nullability (2020-12-ish)
+    def _apply_nullable_jsonschema(s: JsonSchema) -> JsonSchema:
+        if not nullable:
+            return s
+        # If already unioned, add {"type": "null"} via oneOf
+        if "oneOf" in s:
+            s["oneOf"].append({"type": "null"})
+            return s
+        # If type is a single string, allow null via type array
+        t = s.get("type")
+        if isinstance(t, str):
+            s["type"] = [t, "null"]
+        elif isinstance(t, list) and "null" not in t:
+            t.append("null")
+        else:
+            # Fallback: union with null
+            s = {"oneOf": [s, {"type": "null"}], **{k: v for k, v in s.items() if k not in ("type", "enum")}}
+        return s
+
+    # Build
+    if len(non_null_types) == 1:
+        t = non_null_types[0]
+        schema["type"] = t
+        if enum_no_null:
+            schema["enum"] = enum_no_null
+
+        # bytes convention: if any bytes present, add format hint
+        if any(isinstance(v, (bytes, bytearray, memoryview)) for v in values):
+            schema.setdefault("format", "byte")  # OpenAPI convention for base64
+
+        if openapi:
+            schema = _apply_nullable_oas(schema)
+        else:
+            schema = _apply_nullable_jsonschema(schema)
+
+        return schema
+
+    # Mixed types: use union
+    # In OpenAPI 3.0, "oneOf" is supported; "anyOf" also works but oneOf is clearer.
+    alts: List[JsonSchema] = []
+    for t in sorted(set(non_null_types)):
+        vals_for_t = [v for v, tt in zip(normalized_values, types) if tt == t]
+        alt: JsonSchema = {"type": t, "enum": vals_for_t}
+        if t == "string" and any(isinstance(v, (bytes, bytearray, memoryview)) for v in values):
+            # Only add if those strings are actually from bytes;
+            # leaving this hint in case you mix bytes + str.
+            alt.setdefault("format", "byte")
+        alts.append(alt)
+
+    schema["oneOf"] = alts
+
+    if openapi:
+        schema = _apply_nullable_oas(schema)
+    else:
+        schema = _apply_nullable_jsonschema(schema)
+
+    return schema

literalenum/compatibility_extensions/literal.py

@@ -0,0 +1,9 @@
+from typing import Literal, TypeVar, Any
+
+import typing_literalenum as core
+
+def literal(cls: core.LiteralEnumMeta) -> TypeVar:
+    try:
+        return Literal[*cls._ordered_values_]
+    except TypeError:
+        return Any

literalenum/compatibility_extensions/random_choice.py

@@ -0,0 +1,3 @@
+def random_choice(cls):
+    import random
+    return random.choice(cls._ordered_values_)

literalenum/compatibility_extensions/regex.py

@@ -0,0 +1,10 @@
+def regex_str(cls) -> str:
+    if not all(isinstance(v, str) for v in cls._ordered_values_ if v is not None):
+        raise TypeError("regex is only valid for string-valued LiteralEnum")
+    import re
+    vals = [v for v in cls._ordered_values_ if isinstance(v, str)]
+    return "^(?:" + "|".join(re.escape(v) for v in vals) + ")$"
+
+def regex_pattern(cls, flags=0) -> "re.Pattern":
+    import re
+    return re.compile(cls.regex_str(), flags)

literalenum/compatibility_extensions/sqlalchemy_enum.py

@@ -0,0 +1,6 @@
+def sqlalchemy_enum(cls):
+    try:
+        from sqlalchemy import Enum
+    except ImportError as e:
+        raise RuntimeError("Install sqlalchemy to use .sqlalchemy_enum") from e
+    return Enum(*cls._ordered_values_, name=cls.__name__)

literalenum/compatibility_extensions/str_enum.py

@@ -0,0 +1,9 @@
+from enum import StrEnum
+
+import typing_literalenum as core
+
+
+def str_enum(cls: core.LiteralEnumMeta) -> StrEnum:
+    if not all(isinstance(v, str) for v in cls._ordered_values_ if v is not None):
+        raise TypeError("str_enum only works on a string-valued LiteralEnum")
+    return StrEnum(cls.__name__, dict(cls._members_))

literalenum/compatibility_extensions/strawberry_enum.py

@@ -0,0 +1,18 @@
+def strawberry_enum(cls) -> type:
+    """Convert this LiteralEnum to a Strawberry GraphQL enum type.
+
+    Requires ``strawberry`` to be installed.  Uses canonical members
+    only (aliases are excluded)::
+
+        class Color(LiteralEnum):
+            RED = "red"
+            GREEN = "green"
+
+        # use in a Strawberry schema
+        ColorEnum = Color.strawberry_enum
+    """
+    import enum as _enum
+    import strawberry
+
+    PyEnum = _enum.Enum(cls.__name__, dict(cls.unique_mapping))
+    return strawberry.enum(PyEnum)

literalenum/literal_enum.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+from typing import Never, NoReturn
+
+import typing_literalenum as core
+from literalenum import compatibility_extensions as compat
+
+
+class LiteralEnumMeta(core.LiteralEnumMeta):
+    def literal(cls):
+        return compat.literal(cls)
+
+    def enum(cls):
+        return compat.enum(cls)
+
+    def str_enum(cls):
+        return compat.str_enum(cls)
+
+    def int_enum(cls):
+        return compat.int_enum(cls)
+
+    def json_schema(cls):
+        return compat.json_schema(cls)
+
+    def base_model(cls):
+        return compat.base_model(cls)
+
+    def sqlalchemy_enum(cls):
+        return compat.sqlalchemy_enum(cls)
+
+    def strawberry_enum(cls):
+        return compat.strawberry_enum(cls)
+
+    def graphene_enum(cls):
+        return compat.graphene_enum(cls)
+
+    def regex_str(cls):
+        return compat.regex_str(cls)
+
+    def regex_pattern(cls, flags=0):
+        return compat.regex_pattern(cls, flags)
+
+    def annotated(cls):
+        return compat.annotated(cls)
+
+    def django_choices(cls):
+        return compat.django_choices(cls)
+
+    def click_choice(cls):
+        return compat.click_choice(cls)
+
+    def random_choice(cls):
+        return compat.random_choice(cls)
+
+    def bare_class(cls):
+        return compat.bare_class(cls)
+
+    def set(cls):
+        return set(cls)
+
+    def list(cls):
+        return list(cls)
+
+    def frozenset(cls):
+        return frozenset(cls)
+
+    def dict(cls):
+        return dict(cls.mapping)
+
+    def tuple(cls):
+        return tuple(cls)
+
+    def str(cls):
+        return "|".join(f'"{v}"' if isinstance(v, str) else repr(v) for v in cls)
+
+    def stub(cls):
+        from literalenum.stubgen import stub_for
+        return stub_for(cls)
+
+    @property
+    def T_(cls):
+        return cls.literal()
+
+class LiteralEnum(metaclass=LiteralEnumMeta):
+    """Base class for defining a set of named literal values.
+
+        Subclass ``LiteralEnum`` and assign literal values as class attributes::
+
+            class Color(LiteralEnum):
+                RED = "red"
+                GREEN = "green"
+                BLUE = "blue"
+
+        At runtime:
+
+        * ``Color.RED`` evaluates to ``"red"`` (a plain ``str``).
+        * ``list(Color)`` returns ``["red", "green", "blue"]``.
+        * ``"red" in Color`` returns ``True``.
+        * ``Color.validate(x)`` returns *x* if valid or raises ``ValueError``.
+
+        At type-check time, ``Color`` is intended to be equivalent to
+        ``Literal["red", "green", "blue"]``.
+
+        ``LiteralEnum`` is **not instantiable** — its values are plain scalars,
+        not wrapper objects.  Use ``validate()`` or ``is_valid()`` instead.
+
+        Duplicate values are permitted; the first declared name is canonical
+        and later names are aliases::
+
+            class Method(LiteralEnum):
+                GET = "GET"
+                get = "GET"       # alias for GET
+
+            Method.names("GET")           # ("GET", "get")
+            Method.canonical_name("GET")  # "GET"
+            list(Method)                  # ["GET"]  (aliases not yielded)
+
+        To extend an existing LiteralEnum, pass ``extend=True``::
+
+            class ExtendedColor(Color, extend=True):
+                YELLOW = "yellow"
+        """
+
+    def __new__(cls, value: Never) -> NoReturn | core.LE:
+        """Signal to type checkers that LiteralEnum is not instantiable.
+
+        At runtime, the metaclass ``__call__`` intercepts before this is
+        reached — either validating (``call_to_validate=True``) or raising
+        ``TypeError``.  This method exists solely so that type checkers
+        flag ``HttpMethod("GET")`` as an error by default.
+        """
+        if cls._call_to_validate_:
+            return core.validate_is_member(cls, value)
+        raise TypeError(
+            f"{cls.__name__} is not instantiable; "
+            f"use {cls.__name__}.validate(x) or x in {cls.__name__}"
+        )