envread 0.2.0__py3-none-any.whl

envread/__init__.py

@@ -0,0 +1,32 @@
+"""Typed, zero-dependency reader for environment variables with mypy-inferred types."""
+
+from __future__ import annotations
+
+from ._dotenv import load_dotenv, parse_dotenv, read_dotenv
+from ._env import Env, env
+from ._errors import (
+    DotenvError,
+    EnvError,
+    EnvValidationError,
+    InvalidEnvError,
+    MissingEnvError,
+)
+from ._secret import Secret
+from ._settings import load, var
+from ._version import __version__ as __version__
+
+__all__ = [
+    "DotenvError",
+    "Env",
+    "EnvError",
+    "EnvValidationError",
+    "InvalidEnvError",
+    "MissingEnvError",
+    "Secret",
+    "env",
+    "load",
+    "load_dotenv",
+    "parse_dotenv",
+    "read_dotenv",
+    "var",
+]

envread/__main__.py

@@ -0,0 +1,7 @@
+"""Allow ``python -m envread`` as an alias for the ``envread`` command."""
+
+import sys
+
+from ._cli import main
+
+sys.exit(main())

envread/_check.py

@@ -0,0 +1,68 @@
+"""Evaluate a list of variable specs against a reader, collecting every outcome."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from typing import Any
+
+from ._errors import InvalidEnvError, MissingEnvError
+from ._reader import MISSING, Reader, parse_value
+
+
+@dataclass(frozen=True)
+class VarSpec:
+    """One variable to read: its name, parser and what to do when it is unset."""
+
+    name: str
+    type_name: str
+    parser: Callable[[str, str], Any]
+    required: bool = True
+    default: Any = MISSING
+    default_factory: Callable[[], Any] | None = None
+    secret: bool = False
+    attr: str = ""
+
+    def fallback(self) -> Any:
+        """The value used when the variable is unset and not required."""
+        if self.default_factory is not None:
+            return self.default_factory()
+        return None if self.default is MISSING else self.default
+
+
+@dataclass(frozen=True)
+class Outcome:
+    """The result of reading one spec.
+
+    ``status`` is ``"ok"`` (set and valid), ``"unset"`` (unset but optional, so
+    ``value`` is the fallback), ``"missing"`` or ``"invalid"`` (``error`` is set).
+    """
+
+    spec: VarSpec
+    full_name: str
+    status: str
+    value: Any = None
+    error: MissingEnvError | InvalidEnvError | None = None
+
+    @property
+    def failed(self) -> bool:
+        return self.error is not None
+
+
+def evaluate_one(spec: VarSpec, reader: Reader) -> Outcome:
+    full = reader.full_name(spec.name)
+    raw = reader.raw(spec.name)
+    if raw is None:
+        if spec.required:
+            return Outcome(spec, full, "missing", error=MissingEnvError(full))
+        return Outcome(spec, full, "unset", spec.fallback())
+    try:
+        value = parse_value(spec.parser, full, raw, spec.secret)
+    except InvalidEnvError as exc:
+        return Outcome(spec, full, "invalid", error=exc)
+    return Outcome(spec, full, "ok", value)
+
+
+def evaluate(specs: Iterable[VarSpec], reader: Reader) -> list[Outcome]:
+    """Read every spec, never stopping at the first failure."""
+    return [evaluate_one(spec, reader) for spec in specs]

envread/_cli.py

@@ -0,0 +1,152 @@
+"""The ``envread`` command: validate a spec against the environment, or read one value."""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import os
+import sys
+from collections import ChainMap
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any, NoReturn
+
+from ._check import VarSpec, evaluate, evaluate_one
+from ._dotenv import read_layer
+from ._env import Env
+from ._errors import EnvError
+from ._reader import parse_value
+from ._report import canonical, render_json, render_text, summary
+from ._settings import specs_for
+from ._specfile import TYPE_HELP, SpecError, parse_type, read_spec
+from ._version import __version__
+
+EPILOG = """\
+examples:
+  envread check env.spec                     validate every variable in a spec file
+  envread check myapp.settings:Settings      validate the fields of a dataclass
+  envread check env.spec --env-file .env     layer a .env file under the environment
+  envread check env.spec --format json       machine-readable report
+  envread get PORT --type int --default 8080 print one parsed value
+  envread get DEBUG --type bool              prints true or false
+
+spec file format (one variable per line, # starts a comment):
+  DATABASE_URL  secret
+  PORT          int       optional
+  DEBUG         bool      optional
+  LOG_LEVEL     choice:debug,info,warning
+  HOSTS         list:;
+
+check exits 0 when every variable is valid and 1 otherwise; values are only printed
+with --show-values, and secrets never are. Errors go to stderr with exit code 1.
+module:Class is imported with the current directory added to the import path.
+"""
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str) -> NoReturn:
+        self.print_usage(sys.stderr)
+        self.exit(1, f"{self.prog}: error: {message}\n")
+
+
+def _common(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--prefix", default="", help="prepend PREFIX to every name")
+    parser.add_argument("--env-file", metavar="FILE", help="read FILE under the environment")
+    parser.add_argument(
+        "--empty-is-unset", action="store_true", help="treat variables set to '' as unset"
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = _Parser(
+        prog="envread",
+        description="Validate and read typed environment variables.",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"envread {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True, parser_class=_Parser)
+    check = commands.add_parser(
+        "check",
+        help="validate a spec or dataclass",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    check.add_argument("target", help="a spec file path, or module:Class for a dataclass")
+    _common(check)
+    check.add_argument("--format", choices=("text", "json"), default="text")
+    check.add_argument("--show-values", action="store_true", help="print values (not secrets)")
+    check.add_argument("--quiet", "-q", action="store_true", help="print nothing, exit code only")
+    get = commands.add_parser(
+        "get",
+        help="print one parsed value",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    get.add_argument("name", help="the variable name (without --prefix)")
+    get.add_argument("--type", default="str", help=f"one of {TYPE_HELP} (default str)")
+    get.add_argument("--default", help="value to use when the variable is unset")
+    get.add_argument("--secret", action="store_true", help="never show the value in errors")
+    _common(get)
+    return parser
+
+
+def _reader(args: argparse.Namespace) -> Env:
+    source: Mapping[str, str] = os.environ
+    if args.env_file:
+        source = ChainMap(os.environ, read_layer(args.env_file))
+    return Env(source, prefix=args.prefix, empty_is_unset=args.empty_is_unset)
+
+
+def _specs(target: str) -> list[VarSpec]:
+    if Path(target).is_file():
+        return read_spec(target)
+    module_name, colon, attr = target.partition(":")
+    if not colon or not module_name or not attr:
+        raise SpecError(f"{target!r} is neither a spec file nor module:Class")
+    if os.getcwd() not in sys.path:
+        sys.path.insert(0, os.getcwd())
+    obj: Any = importlib.import_module(module_name)
+    for part in attr.split("."):
+        obj = getattr(obj, part)
+    return specs_for(obj)
+
+
+def _check(args: argparse.Namespace) -> int:
+    outcomes = evaluate(_specs(args.target), _reader(args))
+    failed = any(outcome.failed for outcome in outcomes)
+    if not args.quiet:
+        render = render_json if args.format == "json" else render_text
+        report = render(outcomes, args.show_values)
+        if report:
+            print(report)
+        if args.format == "text":
+            print(f"envread: {summary(outcomes)}", file=sys.stderr if failed else sys.stdout)
+    return 1 if failed else 0
+
+
+def _get(args: argparse.Namespace) -> int:
+    parser, type_name = parse_type(args.type)
+    spec = VarSpec(args.name, type_name, parser, required=args.default is None, secret=args.secret)
+    outcome = evaluate_one(spec, _reader(args))
+    if outcome.error is not None:
+        raise outcome.error
+    value = outcome.value
+    if outcome.status == "unset":
+        value = parse_value(parser, f"--default for {outcome.full_name}", args.default, args.secret)
+    print("\n".join(value) if isinstance(value, list) else canonical(value))
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command line interface and return the process exit code."""
+    args = build_parser().parse_args(argv)
+    try:
+        return _check(args) if args.command == "check" else _get(args)
+    except (EnvError, SpecError, TypeError, ImportError, AttributeError, OSError) as exc:
+        print(f"envread: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

envread/_dotenv.py

@@ -0,0 +1,105 @@
+r"""Read ``.env`` files: a documented subset of python-dotenv 1.x syntax.
+
+Supported, matching ``dotenv_values`` / ``load_dotenv``: blank lines, ``#`` comment
+lines, an optional ``export`` keyword, ``KEY=value`` with spaces allowed around ``=``;
+unquoted values (trimmed, an inline comment needs whitespace before ``#``); single
+quotes (literal, only ``\'`` and ``\\`` are escapes, and ``${`` is refused because
+the two references disagree on it); double quotes (escapes
+``\\ \' \" \a \b \f \n \r \t \v``); and ``${NAME}`` / ``${NAME:-default}``
+expansion in unquoted and double-quoted values. A bare ``KEY`` with no ``=`` is
+skipped. Anything else, such as multi-line quoted values or other ``${...}`` forms,
+raises :class:`DotenvError` naming the line, instead of being guessed at.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+
+from ._dotenv_value import Expand, parse_value
+from ._errors import DotenvError
+
+_LINE = re.compile(r"\s*(?:export\s+)?(?P<key>[^=#\s'\"]+)\s*(?:=(?P<rest>.*))?")
+_WINDOWS_MAX = 32767
+
+
+def _entries(text: str, path: str | None) -> list[tuple[int, str, str, bool]]:
+    """Return ``(line, key, value, expandable)`` for every assignment line."""
+    entries = []
+    for number, line in enumerate(text.splitlines(), start=1):
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        match = _LINE.fullmatch(line)
+        if match is None:
+            raise DotenvError("expected KEY=value", number, path)
+        rest = match.group("rest")
+        if rest is None:
+            continue
+        try:
+            value, expandable = parse_value(rest)
+        except ValueError as exc:
+            raise DotenvError(str(exc), number, path) from None
+        entries.append((number, match.group("key"), value, expandable))
+    return entries
+
+
+def _resolve(
+    text: str, path: str | None, environ: Mapping[str, str], file_first: bool
+) -> dict[str, str]:
+    values: dict[str, str] = {}
+    for number, key, raw, expandable in _entries(text, path):
+        lookup = Expand(values, environ, file_first)
+        try:
+            values[key] = lookup.expand(raw) if expandable else raw
+        except ValueError as exc:
+            raise DotenvError(str(exc), number, path) from None
+    return values
+
+
+def parse_dotenv(text: str, environ: Mapping[str, str] | None = None) -> dict[str, str]:
+    """Parse ``.env`` text into a dict, like python-dotenv's ``dotenv_values``.
+
+    ``${NAME}`` resolves against earlier keys in the text first, then ``environ``
+    (``os.environ`` by default); an unknown name expands to ``""``.
+    """
+    return _resolve(text, None, os.environ if environ is None else environ, True)
+
+
+def read_dotenv(
+    path: str | os.PathLike[str], environ: Mapping[str, str] | None = None
+) -> dict[str, str]:
+    """Read and parse a UTF-8 ``.env`` file without touching the environment."""
+    text = Path(path).read_text(encoding="utf-8-sig")
+    return _resolve(text, os.fspath(path), os.environ if environ is None else environ, True)
+
+
+def load_dotenv(path: str | os.PathLike[str], *, override: bool = False) -> dict[str, str]:
+    """Copy the variables of a ``.env`` file into ``os.environ``; return what was set.
+
+    Like python-dotenv, variables that are already set win unless ``override=True``,
+    and the same precedence applies to ``${NAME}`` expansion. On Windows an entry
+    whose ``NAME=value`` exceeds 32,767 characters cannot be stored in the process
+    environment, so it raises :class:`DotenvError` before anything is written.
+    """
+    name = os.fspath(path)
+    text = Path(path).read_text(encoding="utf-8-sig")
+    values = _resolve(text, name, os.environ, override)
+    chosen = {k: v for k, v in values.items() if override or k not in os.environ}
+    if sys.platform == "win32":
+        lines = {key: number for number, key, *_ in _entries(text, name)}
+        for key, value in chosen.items():
+            if len(key) + 1 + len(value) > _WINDOWS_MAX:
+                reason = f"{key} is longer than the 32767 characters Windows allows"
+                raise DotenvError(reason, lines[key], name)
+    os.environ.update(chosen)
+    return chosen
+
+
+def read_layer(path: str | os.PathLike[str]) -> dict[str, str]:
+    """Parse a file the way :func:`load_dotenv` would see it, without writing anything."""
+    text = Path(path).read_text(encoding="utf-8-sig")
+    return _resolve(text, os.fspath(path), os.environ, False)

envread/_dotenv_value.py

@@ -0,0 +1,73 @@
+"""Decode the value part of one ``.env`` line and expand ``${NAME}`` references."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+
+_SINGLE = re.compile(r"'((?:\\'|[^'])*)'")
+_DOUBLE = re.compile(r'"((?:\\"|[^"])*)"')
+_TAIL = re.compile(r"\s*(?:#.*)?")
+_SINGLE_ESCAPES = re.compile(r"\\([\\'])")
+_DOUBLE_ESCAPES = re.compile(r"\\([\\'\"abfnrtv])")
+_CONTROL = {"a": "\a", "b": "\b", "f": "\f", "n": "\n", "r": "\r", "t": "\t", "v": "\v"}
+_REFERENCE = re.compile(r"\$\{([^}]*)\}")
+_PLAIN = re.compile(r"([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?")
+# python-dotenv 1.x expands ${...} inside single quotes while docker compose keeps it
+# literal, so the subset refuses the construct rather than pick one silently.
+_AMBIGUOUS = "${ inside single quotes is read differently by python-dotenv and docker compose"
+
+
+def parse_value(rest: str) -> tuple[str, bool]:
+    """Return ``(value, expandable)`` for the text after ``=``.
+
+    Raises ValueError with a reason that never quotes the value.
+    """
+    text = rest.lstrip()
+    if text.startswith(("'", '"')):
+        quote = text[0]
+        match = (_SINGLE if quote == "'" else _DOUBLE).match(text)
+        if match is None:
+            raise ValueError("unterminated quoted value (multi-line values are not supported)")
+        if _TAIL.fullmatch(text, match.end()) is None:
+            raise ValueError("unexpected text after the closing quote")
+        body = match.group(1)
+        if quote == "'":
+            if "${" in body:
+                raise ValueError(_AMBIGUOUS)
+            return _SINGLE_ESCAPES.sub(r"\1", body), False
+        return _DOUBLE_ESCAPES.sub(lambda m: _CONTROL.get(m.group(1), m.group(1)), body), True
+    return re.sub(r"\s+#.*", "", text).rstrip(), True
+
+
+class Expand:
+    """Resolve ``${NAME}`` and ``${NAME:-default}`` against the file and an environment.
+
+    ``file_first`` decides who wins when a name exists in both: the earlier file
+    entries (``dotenv_values`` behaviour) or the environment (``load_dotenv`` without
+    ``override``). An unknown name with no default expands to ``""``; the default is
+    used only when the name is unset, never when it is set to ``""``.
+    """
+
+    def __init__(self, values: Mapping[str, str], environ: Mapping[str, str], file_first: bool):
+        self._first, self._second = (values, environ) if file_first else (environ, values)
+
+    def lookup(self, name: str) -> str | None:
+        value = self._first.get(name)
+        return value if value is not None else self._second.get(name)
+
+    def expand(self, raw: str) -> str:
+        if "${" not in raw:
+            return raw
+        if raw.count("${") != len(_REFERENCE.findall(raw)):
+            raise ValueError("unterminated ${ reference")
+        return _REFERENCE.sub(self._replace, raw)
+
+    def _replace(self, match: re.Match[str]) -> str:
+        inner = _PLAIN.fullmatch(match.group(1))
+        if inner is None:
+            raise ValueError("only ${NAME} and ${NAME:-default} references are supported")
+        value = self.lookup(inner.group(1))
+        if value is not None:
+            return value
+        return inner.group(2) or ""

envread/_duration.py

@@ -0,0 +1,57 @@
+"""Parse human durations such as ``90``, ``250ms``, ``1h30m`` or ``1.5h``."""
+
+from __future__ import annotations
+
+import re
+from datetime import timedelta
+
+from ._errors import InvalidEnvError
+
+_UNITS = {
+    "ms": 0.001,
+    "s": 1.0,
+    "m": 60.0,
+    "h": 3600.0,
+    "d": 86400.0,
+    "w": 604800.0,
+}
+_PART = re.compile(r"(\d+(?:\.\d+)?|\.\d+)(ms|s|m|h|d|w)")
+_REASON = "expected seconds (90) or amounts with units ms, s, m, h, d, w (1h30m, 250ms)"
+
+
+def parse_duration(name: str, raw: str) -> timedelta:
+    """Return a non-negative timedelta.
+
+    A bare number is seconds. Otherwise the value is one or more ``<number><unit>``
+    parts with no spaces between them, each unit used at most once and from the
+    largest to the smallest, so ``1h30m`` is valid and ``30m1h`` is not.
+    """
+    text = raw.strip().lower()
+    try:
+        return timedelta(seconds=float(text)) if _is_number(text) else _parse_parts(text)
+    except (ValueError, OverflowError):
+        raise InvalidEnvError(name, raw, "duration", _REASON) from None
+
+
+def _is_number(text: str) -> bool:
+    return re.fullmatch(r"\d+(?:\.\d+)?|\.\d+", text) is not None
+
+
+def _parse_parts(text: str) -> timedelta:
+    if not text:
+        raise ValueError("empty")
+    order = list(_UNITS)[::-1]
+    position = 0
+    last_rank = -1
+    seconds = 0.0
+    while position < len(text):
+        match = _PART.match(text, position)
+        if match is None:
+            raise ValueError("bad part")
+        rank = order.index(match.group(2))
+        if rank <= last_rank:
+            raise ValueError("units out of order")
+        last_rank = rank
+        seconds += float(match.group(1)) * _UNITS[match.group(2)]
+        position = match.end()
+    return timedelta(seconds=seconds)

envread/_env.py

@@ -0,0 +1,136 @@
+"""The Env reader: typed getters whose return type mypy infers from the call."""
+
+from __future__ import annotations
+
+from builtins import bool as _bool
+from builtins import float as _float
+from builtins import int as _int
+from builtins import list as _list
+from builtins import str as _str
+from typing import Any, Literal, overload
+
+from ._parsers import parse_bool, parse_float, parse_int, parse_json, parse_list, parse_str
+from ._reader import MISSING
+from ._rich import RichGetters
+
+# The getters are named after the builtin types (env.int, env.str, ...), which shadows
+# those names inside the class body, so annotations use these module-level aliases.
+
+
+class Env(RichGetters):
+    """Read environment variables as typed values.
+
+    Each getter is overloaded so the static type follows the call: with no default
+    and no ``required=`` the result is non-optional and a missing variable raises;
+    passing ``None`` or ``required=False`` widens the result to include ``None``.
+    ``secret=True`` keeps the value out of any error message.
+    """
+
+    @overload
+    def str(self, name: _str, *, secret: _bool = ...) -> _str: ...
+    @overload
+    def str(self, name: _str, default: _str, *, secret: _bool = ...) -> _str: ...
+    @overload
+    def str(self, name: _str, default: None, *, secret: _bool = ...) -> _str | None: ...
+    @overload
+    def str(self, name: _str, *, required: Literal[True], secret: _bool = ...) -> _str: ...
+    @overload
+    def str(self, name: _str, *, required: Literal[False], secret: _bool = ...) -> _str | None: ...
+    def str(
+        self, name: _str, default: Any = MISSING, *, required: Any = MISSING, secret: _bool = False
+    ) -> _str | None:
+        """Return the raw value; an empty value is returned as ``""``."""
+        return self._get(name, parse_str, default, required, secret)
+
+    @overload
+    def int(self, name: _str, *, secret: _bool = ...) -> _int: ...
+    @overload
+    def int(self, name: _str, default: _int, *, secret: _bool = ...) -> _int: ...
+    @overload
+    def int(self, name: _str, default: None, *, secret: _bool = ...) -> _int | None: ...
+    @overload
+    def int(self, name: _str, *, required: Literal[True], secret: _bool = ...) -> _int: ...
+    @overload
+    def int(self, name: _str, *, required: Literal[False], secret: _bool = ...) -> _int | None: ...
+    def int(
+        self, name: _str, default: Any = MISSING, *, required: Any = MISSING, secret: _bool = False
+    ) -> _int | None:
+        """Parse what ``int()`` accepts in base 10 (``1_000`` too), ignoring whitespace."""
+        return self._get(name, parse_int, default, required, secret)
+
+    @overload
+    def float(self, name: _str, *, secret: _bool = ...) -> _float: ...
+    @overload
+    def float(self, name: _str, default: _float, *, secret: _bool = ...) -> _float: ...
+    @overload
+    def float(self, name: _str, default: None, *, secret: _bool = ...) -> _float | None: ...
+    @overload
+    def float(self, name: _str, *, required: Literal[True], secret: _bool = ...) -> _float: ...
+    @overload
+    def float(
+        self, name: _str, *, required: Literal[False], secret: _bool = ...
+    ) -> _float | None: ...
+    def float(
+        self, name: _str, default: Any = MISSING, *, required: Any = MISSING, secret: _bool = False
+    ) -> _float | None:
+        """Parse anything Python's ``float()`` accepts, ignoring surrounding whitespace."""
+        return self._get(name, parse_float, default, required, secret)
+
+    @overload
+    def bool(self, name: _str, *, secret: _bool = ...) -> _bool: ...
+    @overload
+    def bool(self, name: _str, default: _bool, *, secret: _bool = ...) -> _bool: ...
+    @overload
+    def bool(self, name: _str, default: None, *, secret: _bool = ...) -> _bool | None: ...
+    @overload
+    def bool(self, name: _str, *, required: Literal[True], secret: _bool = ...) -> _bool: ...
+    @overload
+    def bool(
+        self, name: _str, *, required: Literal[False], secret: _bool = ...
+    ) -> _bool | None: ...
+    def bool(
+        self, name: _str, default: Any = MISSING, *, required: Any = MISSING, secret: _bool = False
+    ) -> _bool | None:
+        """Accept true/false, yes/no, on/off, 1/0, y/n, t/f, enable(d)/disable(d), any case."""
+        return self._get(name, parse_bool, default, required, secret)
+
+    @overload
+    def list(self, name: _str, *, separator: _str = ",", secret: _bool = ...) -> _list[_str]: ...
+    @overload
+    def list(
+        self, name: _str, default: _list[_str], *, separator: _str = ",", secret: _bool = ...
+    ) -> _list[_str]: ...
+    @overload
+    def list(
+        self, name: _str, default: None, *, separator: _str = ",", secret: _bool = ...
+    ) -> _list[_str] | None: ...
+    @overload
+    def list(
+        self, name: _str, *, required: Literal[True], separator: _str = ",", secret: _bool = ...
+    ) -> _list[_str]: ...
+    @overload
+    def list(
+        self, name: _str, *, required: Literal[False], separator: _str = ",", secret: _bool = ...
+    ) -> _list[_str] | None: ...
+    def list(
+        self,
+        name: _str,
+        default: Any = MISSING,
+        *,
+        required: Any = MISSING,
+        separator: _str = ",",
+        secret: _bool = False,
+    ) -> _list[_str] | None:
+        """Split on ``separator`` and trim each item; an empty value is ``[]``."""
+        return self._get(
+            name, lambda n, raw: parse_list(n, raw, separator), default, required, secret
+        )
+
+    def json(
+        self, name: _str, default: Any = MISSING, *, required: Any = MISSING, secret: _bool = False
+    ) -> Any:
+        """Parse the value as JSON. Return type is Any, so annotate the call site."""
+        return self._get(name, parse_json, default, required, secret)
+
+
+env = Env()