envread 0.2.0__py3-none-any.whl

envread/_errors.py

@@ -0,0 +1,98 @@
+"""Exceptions raised when an environment variable is missing or malformed."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+MASK = "***"
+"""What a secret value is replaced with in every message and attribute."""
+
+_SHOWN = 80
+
+
+def _shown(value: str) -> str:
+    """Quote a value for a message, trimming very long ones to stay readable."""
+    if len(value) <= _SHOWN:
+        return repr(value)
+    return f"{value[:_SHOWN]!r}... ({len(value)} characters)"
+
+
+class EnvError(Exception):
+    """Base class for every error raised by this package."""
+
+
+class MissingEnvError(EnvError, KeyError):
+    """A required variable is not set and no default was given.
+
+    Subclasses KeyError so existing ``except KeyError`` handlers keep working.
+    """
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        # KeyError.__str__ quotes its argument, so build the message on Exception.
+        Exception.__init__(self, f"required environment variable {name!r} is not set")
+
+    def __str__(self) -> str:
+        return str(self.args[0])
+
+
+class InvalidEnvError(EnvError, ValueError):
+    """A variable is set but its value cannot be parsed as the requested type.
+
+    With ``secret=True`` the value never reaches the message or the ``value``
+    attribute: both carry ``"***"`` instead, and ``reason`` must not quote it either.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        value: str,
+        type_name: str,
+        reason: str = "",
+        *,
+        secret: bool = False,
+    ) -> None:
+        self.name = name
+        self.value = MASK if secret else value
+        self.type_name = type_name
+        self.reason = reason
+        self.secret = secret
+        shown = MASK if secret else _shown(value)
+        suffix = f": {reason}" if reason else ""
+        # The message without the variable name, for reports that already show it.
+        self.detail = f"not a valid {type_name}: {shown}{suffix}"
+        super().__init__(f"environment variable {name!r} is {self.detail}")
+
+    def masked(self) -> InvalidEnvError:
+        """Return a copy of this error that hides the value."""
+        return InvalidEnvError(self.name, MASK, self.type_name, self.reason, secret=True)
+
+
+class EnvValidationError(EnvError, ValueError):
+    """Several variables failed at once; ``errors`` holds every one of them.
+
+    Raised by :func:`envread.load` after it has read every field, so a single run
+    reports all missing and invalid variables instead of stopping at the first.
+    """
+
+    def __init__(self, errors: Iterable[MissingEnvError | InvalidEnvError]) -> None:
+        self.errors: tuple[MissingEnvError | InvalidEnvError, ...] = tuple(errors)
+        count = len(self.errors)
+        noun = "variable" if count == 1 else "variables"
+        lines = [f"{count} environment {noun} failed validation:"]
+        lines.extend(f"  - {error}" for error in self.errors)
+        super().__init__("\n".join(lines))
+
+
+class DotenvError(EnvError, ValueError):
+    """A ``.env`` file uses syntax outside the supported subset.
+
+    The message names the file and line but never quotes the offending value.
+    """
+
+    def __init__(self, reason: str, line: int, path: str | None = None) -> None:
+        self.reason = reason
+        self.line = line
+        self.path = path
+        where = f"{path}:{line}" if path else f"line {line}"
+        super().__init__(f"{where}: {reason}")

envread/_parsers.py

@@ -0,0 +1,114 @@
+"""Pure string-to-value parsers, each raising InvalidEnvError on bad input.
+
+Every parser takes ``(name, raw)`` and keeps its error ``reason`` free of the raw
+value, so the caller can mask a secret without the value leaking through the reason.
+"""
+
+from __future__ import annotations
+
+import json as _json
+from decimal import Decimal, InvalidOperation
+from enum import Enum
+from pathlib import Path
+from typing import Any, TypeVar
+
+from ._errors import InvalidEnvError
+
+# Same words as the DEFAULT vocabulary of the sibling library boolish, matched after
+# trimming and lower-casing.
+TRUE_WORDS = frozenset({"1", "true", "yes", "on", "y", "t", "enable", "enabled"})
+FALSE_WORDS = frozenset({"0", "false", "no", "off", "n", "f", "disable", "disabled"})
+
+E = TypeVar("E", bound=Enum)
+
+
+def parse_str(name: str, raw: str) -> str:
+    return raw
+
+
+def parse_int(name: str, raw: str) -> int:
+    try:
+        return int(raw.strip())
+    except ValueError:
+        raise InvalidEnvError(name, raw, "integer") from None
+
+
+def parse_float(name: str, raw: str) -> float:
+    try:
+        return float(raw.strip())
+    except ValueError:
+        raise InvalidEnvError(name, raw, "float") from None
+
+
+def parse_bool(name: str, raw: str) -> bool:
+    value = raw.strip().lower()
+    if value in TRUE_WORDS:
+        return True
+    if value in FALSE_WORDS:
+        return False
+    raise InvalidEnvError(
+        name,
+        raw,
+        "boolean",
+        "expected one of true/false, yes/no, on/off, 1/0, enabled/disabled",
+    )
+
+
+def parse_decimal(name: str, raw: str) -> Decimal:
+    try:
+        value = Decimal(raw.strip())
+    except InvalidOperation:
+        raise InvalidEnvError(name, raw, "decimal") from None
+    if not value.is_finite():
+        raise InvalidEnvError(name, raw, "decimal", "must be a finite number")
+    return value
+
+
+def parse_path(name: str, raw: str) -> Path:
+    if not raw.strip():
+        raise InvalidEnvError(name, raw, "path", "must not be empty")
+    return Path(raw)
+
+
+def split_list(raw: str, separator: str) -> list[str]:
+    stripped = raw.strip()
+    if not stripped:
+        return []
+    return [item.strip() for item in stripped.split(separator)]
+
+
+def parse_list(name: str, raw: str, separator: str) -> list[str]:
+    return split_list(raw, separator)
+
+
+def parse_json(name: str, raw: str) -> Any:
+    try:
+        return _json.loads(raw)
+    except _json.JSONDecodeError as exc:
+        reason = f"{exc.msg} at line {exc.lineno} column {exc.colno}"
+        raise InvalidEnvError(name, raw, "JSON", reason) from None
+    except (ValueError, RecursionError):
+        # Integers past the digit limit and pathologically deep nesting land here.
+        raise InvalidEnvError(name, raw, "JSON", "too large or too deeply nested") from None
+
+
+def parse_enum(name: str, raw: str, enum_type: type[E]) -> E:
+    """Match a member by name (case-insensitive) first, then by its value as text."""
+    value = raw.strip()
+    folded = value.casefold()
+    for member in enum_type:
+        if member.name.casefold() == folded:
+            return member
+    for member in enum_type:
+        if str(member.value) == value:
+            return member
+    choices = ", ".join(member.name for member in enum_type)
+    raise InvalidEnvError(name, raw, enum_type.__name__, f"expected one of {choices}")
+
+
+def parse_choice(name: str, raw: str, choices: tuple[str, ...]) -> str:
+    """Accept one of a fixed set of strings, compared exactly after trimming."""
+    value = raw.strip()
+    if value in choices:
+        return value
+    raise InvalidEnvError(name, raw, "choice", f"expected one of {', '.join(choices)}")

envread/_reader.py

@@ -0,0 +1,114 @@
+"""The lookup core shared by every getter: prefix, empty handling, secret masking."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable, Mapping
+from typing import Any, TypeVar, cast
+
+from ._errors import InvalidEnvError, MissingEnvError
+
+T = TypeVar("T")
+R = TypeVar("R", bound="Reader")
+
+
+class _Missing:
+    """Sentinel telling "no argument given" apart from an explicit None default."""
+
+    def __repr__(self) -> str:
+        return "<missing>"
+
+
+MISSING: Any = _Missing()
+
+
+class Reader:
+    """Look names up in a mapping (``os.environ`` by default) and parse the values.
+
+    ``prefix`` is prepended to every name, so ``Env(prefix="APP_").int("PORT")`` reads
+    ``APP_PORT`` and errors name ``APP_PORT``. With ``empty_is_unset=True`` a variable
+    set to the empty string counts as unset, which matches how many deployment tools
+    write "no value" (``KEY=``).
+
+    Name matching is whatever the mapping does: ``os.environ`` is case-insensitive on
+    Windows and case-sensitive on POSIX, while a plain ``dict`` is always exact.
+    """
+
+    def __init__(
+        self,
+        source: Mapping[str, str] | None = None,
+        *,
+        prefix: str = "",
+        empty_is_unset: bool = False,
+    ) -> None:
+        self._source: Mapping[str, str] = source if source is not None else os.environ
+        self.prefix = prefix
+        self.empty_is_unset = empty_is_unset
+
+    @property
+    def source(self) -> Mapping[str, str]:
+        """The mapping values are read from."""
+        return self._source
+
+    def prefixed(self: R, prefix: str) -> R:
+        """Return a reader over the same source with ``prefix`` appended to the prefix."""
+        return type(self)(
+            self._source, prefix=self.prefix + prefix, empty_is_unset=self.empty_is_unset
+        )
+
+    def full_name(self, name: str) -> str:
+        """The real variable name read for ``name``, prefix included."""
+        return self.prefix + name
+
+    def raw(self, name: str) -> str | None:
+        """Return the unparsed value of ``name``, or None when it is unset."""
+        value = self._source.get(self.full_name(name))
+        if value is not None and value == "" and self.empty_is_unset:
+            return None
+        return value
+
+    def is_set(self, name: str) -> bool:
+        """Whether ``name`` is set (an empty value counts unless ``empty_is_unset``)."""
+        return self.raw(name) is not None
+
+    def __contains__(self, name: object) -> bool:
+        return isinstance(name, str) and self.is_set(name)
+
+    def __repr__(self) -> str:
+        where = "os.environ" if self._source is os.environ else type(self._source).__name__
+        return (
+            f"{type(self).__name__}(source={where}, prefix={self.prefix!r}, "
+            f"empty_is_unset={self.empty_is_unset!r})"
+        )
+
+    def _get(
+        self,
+        name: str,
+        parser: Callable[[str, str], T],
+        default: Any,
+        required: Any,
+        secret: bool = False,
+    ) -> T | None:
+        full = self.full_name(name)
+        raw = self.raw(name)
+        if raw is not None:
+            return parse_value(parser, full, raw, secret)
+        if required is True:
+            raise MissingEnvError(full)
+        if default is not MISSING:
+            return cast("T | None", default)
+        if required is False:
+            return None
+        raise MissingEnvError(full)
+
+
+def parse_value(parser: Callable[[str, str], T], name: str, raw: str, secret: bool) -> T:
+    """Run ``parser``; for a secret, re-raise outside the handler so no context leaks."""
+    if not secret:
+        return parser(name, raw)
+    failure: InvalidEnvError | None = None
+    try:
+        return parser(name, raw)
+    except InvalidEnvError as exc:
+        failure = exc.masked()
+    raise failure

envread/_report.py

@@ -0,0 +1,88 @@
+"""Render check outcomes as an aligned text table or as JSON, never leaking secrets."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from datetime import timedelta
+from decimal import Decimal
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from ._check import Outcome
+from ._errors import MASK, InvalidEnvError
+from ._secret import Secret
+
+
+def canonical(value: Any) -> str:
+    """Format a parsed value the way the command line prints it."""
+    if isinstance(value, Secret):
+        return MASK
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, timedelta):
+        seconds = value.total_seconds()
+        return str(int(seconds)) if seconds.is_integer() else str(seconds)
+    if isinstance(value, Enum):
+        return value.name
+    if isinstance(value, (Decimal, Path, int, float, str)):
+        return str(value)
+    if value is None:
+        return ""
+    return json.dumps(value, default=canonical, ensure_ascii=False)
+
+
+def _shown(outcome: Outcome) -> str:
+    if outcome.spec.secret:
+        return MASK
+    return canonical(outcome.value) if outcome.status in ("ok", "unset") else ""
+
+
+def _detail(outcome: Outcome, show_values: bool) -> str:
+    kind = outcome.spec.type_name + ("" if outcome.spec.required else ", optional")
+    if outcome.spec.secret and outcome.spec.type_name != "secret":
+        kind += ", secret"
+    if isinstance(outcome.error, InvalidEnvError):
+        return f"{kind}: {outcome.error.detail}"
+    if outcome.status == "missing":
+        return f"{kind}: not set"
+    if show_values and (outcome.status == "ok" or outcome.value is not None):
+        return f"{kind} = {_shown(outcome)}"
+    return kind
+
+
+def render_text(outcomes: Sequence[Outcome], show_values: bool) -> str:
+    width = max((len(outcome.full_name) for outcome in outcomes), default=0)
+    lines = [
+        f"{outcome.status:<8} {outcome.full_name:<{width}}  {_detail(outcome, show_values)}"
+        for outcome in outcomes
+    ]
+    return "\n".join(lines)
+
+
+def render_json(outcomes: Sequence[Outcome], show_values: bool) -> str:
+    rows = []
+    for outcome in outcomes:
+        row: dict[str, Any] = {
+            "name": outcome.full_name,
+            "type": outcome.spec.type_name,
+            "status": outcome.status,
+            "required": outcome.spec.required,
+            "secret": outcome.spec.secret,
+            "error": None if outcome.error is None else str(outcome.error),
+        }
+        if show_values and outcome.status in ("ok", "unset"):
+            row["value"] = _shown(outcome)
+        rows.append(row)
+    ok = not any(outcome.failed for outcome in outcomes)
+    return json.dumps({"ok": ok, "variables": rows}, indent=2, ensure_ascii=False)
+
+
+def summary(outcomes: Sequence[Outcome]) -> str:
+    failed = sum(1 for outcome in outcomes if outcome.failed)
+    total = len(outcomes)
+    noun = "variable" if total == 1 else "variables"
+    if failed:
+        return f"{failed} of {total} {noun} failed"
+    return f"all {total} {noun} ok"

envread/_rich.py

@@ -0,0 +1,119 @@
+"""Getters for richer types: Decimal, Path, timedelta, Enum members and secrets."""
+
+from __future__ import annotations
+
+from datetime import timedelta
+from decimal import Decimal
+from enum import Enum
+from pathlib import Path
+from typing import Any, Literal, TypeVar, overload
+
+from ._duration import parse_duration
+from ._parsers import parse_decimal, parse_enum, parse_path, parse_str
+from ._reader import MISSING, Reader
+from ._secret import Secret
+
+E = TypeVar("E", bound=Enum)
+
+
+class RichGetters(Reader):
+    """Overloaded getters whose return type follows the default and ``required=``."""
+
+    @overload
+    def decimal(self, name: str, *, secret: bool = ...) -> Decimal: ...
+    @overload
+    def decimal(self, name: str, default: Decimal, *, secret: bool = ...) -> Decimal: ...
+    @overload
+    def decimal(self, name: str, default: None, *, secret: bool = ...) -> Decimal | None: ...
+    @overload
+    def decimal(self, name: str, *, required: Literal[True], secret: bool = ...) -> Decimal: ...
+    @overload
+    def decimal(
+        self, name: str, *, required: Literal[False], secret: bool = ...
+    ) -> Decimal | None: ...
+    def decimal(
+        self, name: str, default: Any = MISSING, *, required: Any = MISSING, secret: bool = False
+    ) -> Decimal | None:
+        """Parse an exact decimal such as ``19.99``; NaN and infinities are rejected."""
+        return self._get(name, parse_decimal, default, required, secret)
+
+    @overload
+    def path(self, name: str, *, secret: bool = ...) -> Path: ...
+    @overload
+    def path(self, name: str, default: Path, *, secret: bool = ...) -> Path: ...
+    @overload
+    def path(self, name: str, default: None, *, secret: bool = ...) -> Path | None: ...
+    @overload
+    def path(self, name: str, *, required: Literal[True], secret: bool = ...) -> Path: ...
+    @overload
+    def path(self, name: str, *, required: Literal[False], secret: bool = ...) -> Path | None: ...
+    def path(
+        self, name: str, default: Any = MISSING, *, required: Any = MISSING, secret: bool = False
+    ) -> Path | None:
+        """Return a ``pathlib.Path``, taken literally (no ``~`` or variable expansion)."""
+        return self._get(name, parse_path, default, required, secret)
+
+    @overload
+    def duration(self, name: str, *, secret: bool = ...) -> timedelta: ...
+    @overload
+    def duration(self, name: str, default: timedelta, *, secret: bool = ...) -> timedelta: ...
+    @overload
+    def duration(self, name: str, default: None, *, secret: bool = ...) -> timedelta | None: ...
+    @overload
+    def duration(self, name: str, *, required: Literal[True], secret: bool = ...) -> timedelta: ...
+    @overload
+    def duration(
+        self, name: str, *, required: Literal[False], secret: bool = ...
+    ) -> timedelta | None: ...
+    def duration(
+        self, name: str, default: Any = MISSING, *, required: Any = MISSING, secret: bool = False
+    ) -> timedelta | None:
+        """Parse ``90`` (seconds), ``250ms``, ``1h30m`` or ``1.5h`` into a timedelta."""
+        return self._get(name, parse_duration, default, required, secret)
+
+    @overload
+    def enum(self, name: str, enum_type: type[E], *, secret: bool = ...) -> E: ...
+    @overload
+    def enum(self, name: str, enum_type: type[E], default: E, *, secret: bool = ...) -> E: ...
+    @overload
+    def enum(
+        self, name: str, enum_type: type[E], default: None, *, secret: bool = ...
+    ) -> E | None: ...
+    @overload
+    def enum(
+        self, name: str, enum_type: type[E], *, required: Literal[True], secret: bool = ...
+    ) -> E: ...
+    @overload
+    def enum(
+        self, name: str, enum_type: type[E], *, required: Literal[False], secret: bool = ...
+    ) -> E | None: ...
+    def enum(
+        self,
+        name: str,
+        enum_type: type[E],
+        default: Any = MISSING,
+        *,
+        required: Any = MISSING,
+        secret: bool = False,
+    ) -> E | None:
+        """Return the member named by the value (any case), or whose value matches it."""
+        return self._get(
+            name, lambda n, raw: parse_enum(n, raw, enum_type), default, required, secret
+        )
+
+    @overload
+    def secret(self, name: str) -> Secret: ...
+    @overload
+    def secret(self, name: str, default: Secret) -> Secret: ...
+    @overload
+    def secret(self, name: str, default: None) -> Secret | None: ...
+    @overload
+    def secret(self, name: str, *, required: Literal[True]) -> Secret: ...
+    @overload
+    def secret(self, name: str, *, required: Literal[False]) -> Secret | None: ...
+    def secret(
+        self, name: str, default: Any = MISSING, *, required: Any = MISSING
+    ) -> Secret | None:
+        """Return the value wrapped in :class:`Secret`, which never shows it in a repr."""
+        value = self._get(name, parse_str, default, required, True)
+        return Secret(value) if isinstance(value, str) else value

envread/_secret.py

@@ -0,0 +1,64 @@
+"""A string wrapper that keeps a sensitive value out of reprs, logs and tracebacks."""
+
+from __future__ import annotations
+
+import hmac
+from typing import Any, NoReturn
+
+from ._errors import MASK
+
+
+class Secret:
+    """Hold a sensitive string and only hand it out through :meth:`reveal`.
+
+    ``str()``, ``repr()``, ``format()`` and f-strings all show ``***``, so a settings
+    object that holds a ``Secret`` can be printed or logged without leaking it.
+    Equality compares the hidden values in constant time. Pickling is refused, so the
+    value cannot slip into a cache or a queue by accident.
+
+    >>> token = Secret("hunter2")
+    >>> token
+    Secret('***')
+    >>> token.reveal()
+    'hunter2'
+    """
+
+    __slots__ = ("_value",)
+
+    def __init__(self, value: str) -> None:
+        if not isinstance(value, str):
+            raise TypeError(f"Secret holds a str, not {type(value).__name__}")
+        self._value = value
+
+    def reveal(self) -> str:
+        """Return the hidden value. Call it only where the value is really needed."""
+        return self._value
+
+    def __repr__(self) -> str:
+        return f"Secret({MASK!r})"
+
+    def __str__(self) -> str:
+        return MASK
+
+    def __format__(self, spec: str) -> str:
+        return format(MASK, spec)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Secret):
+            return NotImplemented
+        return hmac.compare_digest(self._value.encode(), other._value.encode())
+
+    def __hash__(self) -> int:
+        return hash((Secret, self._value))
+
+    def __bool__(self) -> bool:
+        return bool(self._value)
+
+    def __reduce__(self) -> NoReturn:
+        raise TypeError("Secret values cannot be pickled")
+
+    def __copy__(self) -> Secret:
+        return self
+
+    def __deepcopy__(self, memo: dict[int, Any]) -> Secret:
+        return self

envread/_settings.py

@@ -0,0 +1,95 @@
+"""Populate a plain dataclass from the environment, reporting every failure at once."""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Callable
+from typing import Any, TypeVar, get_type_hints
+
+from ._check import VarSpec, evaluate
+from ._env import Env, env
+from ._errors import EnvValidationError
+from ._reader import MISSING
+from ._secret import Secret
+from ._types import resolve, unwrap_optional
+
+T = TypeVar("T")
+_KEY = "envread"
+
+
+@dataclasses.dataclass(frozen=True)
+class _VarOptions:
+    name: str | None
+    separator: str
+    secret: bool
+
+
+def var(
+    name: str | None = None,
+    *,
+    default: Any = MISSING,
+    default_factory: Callable[[], Any] | None = None,
+    separator: str = ",",
+    secret: bool = False,
+) -> Any:
+    """Describe how a dataclass field is read; use it where you would use ``field()``.
+
+    ``name`` overrides the variable name (the field name upper-cased by default; any
+    prefix still applies). ``default`` / ``default_factory`` make the field optional,
+    ``separator`` splits ``list[...]`` and ``tuple[..., ...]`` fields, and ``secret``
+    keeps the value out of error messages.
+    """
+    if default is not MISSING and default_factory is not None:
+        raise ValueError("pass default or default_factory, not both")
+    metadata = {_KEY: _VarOptions(name, separator, secret)}
+    if default_factory is not None:
+        return dataclasses.field(default_factory=default_factory, metadata=metadata)
+    if default is not MISSING:
+        return dataclasses.field(default=default, metadata=metadata)
+    return dataclasses.field(metadata=metadata)
+
+
+def specs_for(cls: type[Any]) -> list[VarSpec]:
+    """Build one spec per init field of the dataclass ``cls``."""
+    if not (isinstance(cls, type) and dataclasses.is_dataclass(cls)):
+        raise TypeError(f"expected a dataclass type, got {cls!r}")
+    try:
+        hints = get_type_hints(cls)
+    except NameError as exc:
+        raise TypeError(f"cannot resolve the annotations of {cls.__qualname__}: {exc}") from None
+    return [_spec(field, hints[field.name]) for field in dataclasses.fields(cls) if field.init]
+
+
+def _spec(field: dataclasses.Field[Any], annotation: Any) -> VarSpec:
+    options = field.metadata.get(_KEY) or _VarOptions(None, ",", False)
+    inner, optional = unwrap_optional(annotation)
+    parser, type_name = resolve(inner, options.separator)
+    has_default = field.default is not dataclasses.MISSING
+    factory = field.default_factory
+    has_factory = factory is not dataclasses.MISSING
+    return VarSpec(
+        name=options.name or field.name.upper(),
+        type_name=type_name,
+        parser=parser,
+        required=not (has_default or has_factory or optional),
+        default=field.default if has_default else MISSING,
+        default_factory=factory if has_factory else None,  # type: ignore[arg-type]
+        secret=options.secret or inner is Secret,
+        attr=field.name,
+    )
+
+
+def load(cls: type[T], source: Env | None = None) -> T:
+    """Read every field of the dataclass ``cls`` from the environment and build it.
+
+    Each field is read from the upper-cased field name (or ``var(name=...)``), with
+    the prefix of ``source`` applied (``Env(prefix="APP_")``). A field with a default,
+    a ``default_factory`` or an ``X | None`` annotation is optional; any other field
+    is required. Every field is read before anything is raised, so one
+    :class:`EnvValidationError` lists all missing and invalid variables together.
+    """
+    outcomes = evaluate(specs_for(cls), source if source is not None else env)
+    errors = [outcome.error for outcome in outcomes if outcome.error is not None]
+    if errors:
+        raise EnvValidationError(errors)
+    return cls(**{outcome.spec.attr: outcome.value for outcome in outcomes})