w6w 0.2.1__py3-none-any.whl

w6w/__init__.py

@@ -0,0 +1,131 @@
+"""w6w — the official Python client for the w6w workflow API.
+
+Typed, dependency-free, and stdlib-only: transport is `urllib.request`, tests
+run under `unittest`. Nothing here imports a third-party module, and nothing
+here ever will — see README "Zero runtime dependencies".
+
+    import w6w
+    print(w6w.__version__)
+
+THE BARREL RULE
+---------------
+**Every public symbol of this package must be re-exported from this module and
+listed in `__all__`.** `w6w.ApiError`, `w6w.W6wClient`, `w6w.Doc`, … are the
+only import paths users are promised; anything reachable only as
+`w6w._http.something` is private and may move without a major bump.
+Modules whose names start with an underscore (`_version`, `_config`, `_vars`,
+…) are implementation detail — the underscore is the signal, and `_vars` in
+particular is spelled that way because the public attribute it backs is
+`client.vars`, which would otherwise read like the `vars` builtin at module
+scope.
+
+The API surface itself (which operations exist, what each is called in each
+language) is pinned by the wrappers' shared `endpoints.json` contract, not
+decided here: three wrappers implement one surface, and they release together
+at one version.
+"""
+
+from __future__ import annotations
+
+from ._config import BASE_PATH, ResolvedConfig, join_base_url
+from ._http import HttpResponse, Transport, path
+from ._vars import VarsApi, VarsRequest
+from ._version import __version__
+from .client import W6wClient
+from .connections import ConnectionsApi, ConnectionsRequest
+from .documents import DocumentsApi, DocumentsHost
+from .errors import ApiError, ConfigError
+from .me import MeRequest, fetch_me
+from .run import RunRequest, run_urn
+from .types import (
+    UNSET,
+    ConnectionState,
+    ConnectionSummary,
+    Doc,
+    DocFormat,
+    Me,
+    PatchableStr,
+    RunEnvelope,
+    RunResult,
+    RunStatus,
+    StepError,
+    Unset,
+    Var,
+    VarType,
+    WorkflowRunResult,
+    WorkflowStatus,
+    WorkflowSummary,
+    is_action_run,
+    is_function_run,
+    is_terminal_run_status,
+    is_workflow_run,
+)
+from .workflows import WorkflowsApi, WorkflowsHost
+
+__all__ = [
+    "ApiError",
+    "BASE_PATH",
+    "ConfigError",
+    # Identity and discovery (T2.3.4). `connections.list` and `workflows.list`
+    # are how a caller finds a URN to hand to `run` (D4); `me` is what makes a
+    # bug report actionable.
+    "ConnectionState",
+    "ConnectionSummary",
+    "ConnectionsApi",
+    "ConnectionsRequest",
+    # Asset operations (T2.3.3). The namespace classes are exported alongside
+    # their wire types and host protocols because a host that types a helper
+    # around `client.documents` needs to name them; they are reached through a
+    # client, never constructed directly.
+    "Doc",
+    "DocFormat",
+    "DocumentsApi",
+    "DocumentsHost",
+    "HttpResponse",
+    "Me",
+    "MeRequest",
+    "PatchableStr",
+    "ResolvedConfig",
+    # Execution (T2.3.5). `run` dispatches on a URN and hands back the
+    # kind-tagged envelope as it arrived — a plain dict, so a `kind` this
+    # release has never heard of keeps every sibling field. The predicates are
+    # how a caller discriminates the three known arms.
+    "RunEnvelope",
+    "RunRequest",
+    "RunResult",
+    "RunStatus",
+    "StepError",
+    "Transport",
+    # The omit-vs-null sentinel and its type. Public because a caller assembling
+    # a patch programmatically has to be able to say "not this field" — `None`
+    # already means "set this field to null", and the two must stay distinct.
+    "UNSET",
+    "Unset",
+    "Var",
+    "VarType",
+    "VarsApi",
+    "VarsRequest",
+    "W6wClient",
+    "WorkflowRunResult",
+    "WorkflowStatus",
+    "WorkflowSummary",
+    "WorkflowsApi",
+    "WorkflowsHost",
+    "__version__",
+    # `client.me()` and `client.run()` are methods rather than namespaces, so
+    # the functions they delegate to are the exported symbols — same layering
+    # as the namespaces.
+    "fetch_me",
+    "is_action_run",
+    "is_function_run",
+    "is_terminal_run_status",
+    "is_workflow_run",
+    "join_base_url",
+    # Exported because `W6wClient.request` is public: a host reaching an
+    # endpoint this version does not model yet must have the same
+    # encoding-at-interpolation primitive the operation modules use, or it will
+    # concatenate a caller value into a path by hand — the one bug the encoding
+    # pin exists to prevent.
+    "path",
+    "run_urn",
+]

w6w/_config.py

@@ -0,0 +1,236 @@
+"""Configuration resolution: what server, what credential, what project.
+
+This module turns whatever the caller supplied — plus the environment, read
+through the single seam in `_env.py` — into one plain :class:`ResolvedConfig`
+value. It is resolved **once, at client construction**, and handed to the
+transport; nothing downstream re-reads the environment.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Mapping, Optional
+from urllib.parse import urlsplit
+
+from ._env import ENV_BASE_URL, ENV_TOKEN, read_env
+from .errors import ConfigError
+
+#: The API's base path, from the shared contract's `basePath`
+#: (`packages/wrappers/endpoints.json`).
+#:
+#: **Empty since v0.2.0.** The server serves its routes at the ROOT of its own
+#: host (``https://api.w6w.io/vars``, not ``.../api/vars`` — the host already
+#: says "api"), so there is no prefix to append and :func:`join_base_url`
+#: appends nothing. Kept exported, and kept mirroring the contract, so the
+#: constant still answers "what does this client prepend?" — now "nothing".
+BASE_PATH: str = ""
+
+#: The schemes a w6w base URL may use. Anything else is a configuration
+#: mistake — most often a bare `host:port` that `urlsplit` reads as a scheme.
+ALLOWED_SCHEMES = ("http", "https")
+
+#: Characters that may never appear in an HTTP header value. CR and LF are
+#: header injection; NUL and the rest are rejected with them rather than left to
+#: fail somewhere deeper. HTAB is technically legal in a field-value and is
+#: rejected too — it cannot appear in a bearer token for any good reason.
+_CONTROL_CHARS_RE = re.compile(r"[\x00-\x1f\x7f]")
+
+
+@dataclass(frozen=True)
+class ResolvedConfig:
+    """Configuration after resolution — the value the transport runs on.
+
+    Held as **instance** state on the client, never in a module-level variable:
+    two clients in one process must be able to hold different credentials and
+    point at different servers with no interference
+    (`docs/implementation.md` §2). Frozen, so nothing downstream can mutate a
+    client's identity in place.
+    """
+
+    #: The normalized base, e.g. `https://api.example.com`. Never
+    #: trailing-slashed, never relative.
+    base_url: str
+    #: The bearer token, or `None` when none was configured.
+    token: Optional[str] = None
+    #: Default project id for the project-scoped operations, or `None`.
+    project: Optional[str] = None
+
+
+def join_base_url(origin: str) -> str:
+    """Validate a configured origin and join it with the API base path.
+
+    **This is the one and only base-URL code path.** `resolve_config` calls this
+    function and does no normalising of its own, so a caller who imports the
+    helper gets exactly the answer their client will use — including the same
+    errors. A helper that were merely *similar* to the client's path (skipping
+    the whitespace trim, say) would answer differently for the same input, which
+    is worse than having no helper at all.
+
+    The join rule is pinned by `docs/implementation.md` §2 and mirrors the house
+    helper the operator console already uses against this same API, so every
+    client agrees on what `W6W_BASE_URL` means:
+
+    1. strip surrounding whitespace, then **all** trailing slashes;
+    2. reject anything that is not an absolute `http`/`https` URL;
+    3. append nothing — the API is served at the root of its own host.
+
+    ::
+
+        https://api.example.com      -> https://api.example.com
+        https://api.example.com/     -> https://api.example.com
+        https://api.example.com///   -> https://api.example.com
+
+    Any path in the configured value is preserved verbatim, so a deployment
+    that genuinely sits behind a gateway prefix can still be addressed by
+    configuring that prefix. This is also why a stale
+    ``https://api.example.com/api`` is NOT silently rewritten: it is
+    indistinguishable from such a prefix, and quietly stripping it would break
+    the deployments that mean it. It will 404 — the announced break for the
+    v0.1.x base path.
+
+    Step 2 exists because a **relative** base URL must fail *here*, as
+    configuration, with a message about configuration. Without an absoluteness
+    check, ``W6W_BASE_URL=/foo`` would walk straight past blank-is-absent
+    (`_env.read_env`) and then fail on the first request as "the server may be
+    down" — the same hole, reopened by another route, and misdiagnosed.
+
+    :param origin: The configured origin. Surrounding whitespace and trailing
+        slashes are tolerated.
+    :returns: The normalized base URL.
+    :raises ConfigError: When the origin is blank, relative, or not http(s).
+    """
+    trimmed = origin.strip().rstrip("/")
+    if not trimmed:
+        raise ConfigError(
+            "No w6w base URL is configured. Pass one to the client "
+            '(W6wClient(base_url="https://api.example.com")) or set the '
+            "{env} environment variable. It holds the server's origin, e.g. "
+            '"https://api.example.com" — the API is served at its root, so no '
+            "path is appended.".format(env=ENV_BASE_URL),
+        )
+
+    split = urlsplit(trimmed)
+    if split.scheme not in ALLOWED_SCHEMES or not split.netloc:
+        raise ConfigError(
+            "The w6w base URL {value!r} is not an absolute http(s) URL. "
+            "{env} holds an ORIGIN, e.g. \"https://api.example.com\" — scheme "
+            "and host. A relative or host-only value cannot be requested and "
+            "would fail later as a connection problem rather than as the "
+            "configuration mistake it is.".format(value=trimmed, env=ENV_BASE_URL),
+        )
+
+    return trimmed
+
+
+def resolve_config(
+    base_url: Optional[str] = None,
+    token: Optional[str] = None,
+    project: Optional[str] = None,
+    environ: Optional[Mapping[str, str]] = None,
+) -> ResolvedConfig:
+    """Resolve explicit arguments and the environment into one config value.
+
+    Precedence is **explicit argument > environment variable**, always; there is
+    no default base URL. The two sides of that chain treat emptiness
+    *asymmetrically*, on purpose (`docs/implementation.md` §2, Precedence):
+
+    - An explicitly passed empty string is an **explicit value**, not "unset".
+      It does not fall through to the environment — a caller who wrote
+      ``base_url=""`` gets the configuration error, not a value the wrapper went
+      looking for behind their back. (It is still not a usable base URL, so the
+      error is the same one either way.)
+    - An **empty or whitespace-only environment variable is ABSENT** and falls
+      through (see `_env.read_env`), so ``W6W_BASE_URL=``, ``W6W_BASE_URL="  "``
+      and an unset ``W6W_BASE_URL`` all end here, in the same configuration
+      error — never in a relative base.
+
+    The difference is the difference between a value a *caller* chose and a
+    value a *shell* produced.
+
+    :param base_url: Explicit origin; `None` consults `W6W_BASE_URL`.
+    :param token: Explicit bearer token; `None` consults `W6W_TOKEN`.
+    :param project: Default project id for the `documents.*` operations. There
+        is no environment variable for it, and no `vars.*` operation takes one —
+        vars are not project-scoped (`docs/implementation.md` §7).
+    :param environ: Environment mapping override, for tests.
+    :returns: The resolved configuration.
+    :raises ConfigError: When no usable base URL was supplied, naming
+        `W6W_BASE_URL`.
+    """
+    raw_base_url = base_url if base_url is not None else read_env(ENV_BASE_URL, environ)
+    return ResolvedConfig(
+        # Every normalisation, emptiness test and validation lives in
+        # `join_base_url` — one code path, so the exported helper and the client
+        # can never answer differently for the same input.
+        base_url=join_base_url(raw_base_url or ""),
+        token=token if token is not None else read_env(ENV_TOKEN, environ),
+        project=project,
+    )
+
+
+def require_token(config: ResolvedConfig) -> str:
+    """Return the configured token, or raise a :class:`ConfigError` naming `W6W_TOKEN`.
+
+    A client may be *constructed* without a token so that a CLI's `--help` and
+    `--version` work offline; the error surfaces on the first request instead.
+    There are no anonymous operations in this surface
+    (`docs/implementation.md` §2).
+
+    A blank token counts as no token, for the same reason a blank base URL does:
+    ``W6W_TOKEN=`` is how a shell or a Dockerfile spells "I meant to set this and
+    did not", and ``Authorization: Bearer `` would turn that into an opaque 401
+    instead of the one message that explains it.
+
+    **The token is also validated as a header value, here, by this package.**
+    A token carrying CR or LF is HTTP header injection — everything after the
+    newline becomes an attacker-chosen header or request line — and it arrives
+    the way secrets usually do: `$(cat token.txt)` with a trailing newline, a
+    copy-paste out of a UI, a CI variable spanning two lines. This check is not
+    delegated to the runtime on purpose. `http.client` does reject CR/LF, but
+    only when the request is actually *sent*, and it raises a bare `ValueError`
+    from outside this package's error model — so an injected token would sail
+    through every unit test in this suite (which never sends), and in production
+    would surface as an exception a caller has no reason to be catching. NUL and
+    the other control characters are rejected alongside them.
+
+    The offending character is reported by codepoint and position; **the token
+    itself is never echoed**, because this message lands in logs.
+
+    :param config: The resolved configuration.
+    :returns: The configured token, verbatim.
+    :raises ConfigError: When no non-blank token is configured, or when the
+        token cannot be sent as a header value.
+    """
+    if config.token is None or not config.token.strip():
+        raise ConfigError(
+            "No w6w API token is configured. Pass one to the client "
+            '(W6wClient(token="...")) or set the {env} environment variable. '
+            "Every w6w API operation is authenticated.".format(env=ENV_TOKEN),
+        )
+
+    control = _CONTROL_CHARS_RE.search(config.token)
+    if control is not None:
+        raise ConfigError(
+            "The configured w6w API token contains a control character "
+            "(U+{code:04X}) at position {index}, so it cannot be sent as an "
+            "Authorization header — a carriage return or newline in a header "
+            "value is header injection. Check {env} for a stray newline (a "
+            "token read from a file usually has one).".format(
+                code=ord(control.group()),
+                index=control.start(),
+                env=ENV_TOKEN,
+            ),
+        )
+    try:
+        # http.client encodes header values as latin-1; anything else would
+        # raise a UnicodeEncodeError from deep inside the send path.
+        config.token.encode("latin-1")
+    except UnicodeEncodeError as err:
+        raise ConfigError(
+            "The configured w6w API token contains a non-latin-1 character at "
+            "position {index}, so it cannot be sent as an Authorization header. "
+            "Check {env}.".format(index=err.start, env=ENV_TOKEN),
+        ) from None
+
+    return config.token

w6w/_env.py

@@ -0,0 +1,84 @@
+"""The **only** module in this package that reads the environment.
+
+`docs/implementation.md` §2 (MECHANISM PIN — instance state, never globals) pins
+exactly one environment-reading module per wrapper; everything else receives
+resolved configuration as a plain value. That is not a style preference. It is
+what keeps `os.environ` out of the operation modules, so no operation can
+silently acquire a dependency on ambient process state, and so every env-var
+behaviour has exactly **one** seam to exercise in tests (§9).
+
+The spec names that module `w6w/_config.py`; this package splits the *reading*
+(here) from the *resolving* (`_config.py`, which imports this file and is its
+only caller). The invariant the pin is about — one place touches the
+environment — is unchanged, and it is enforced mechanically: the repo gate greps
+the whole `src/w6w` tree for `os.environ|os.getenv` and requires exactly one
+matching file. The `node` wrapper made the same split for the same reason
+(`src/env.ts` beside `src/config.ts`).
+
+The mapping is **injectable** (`environ=`) so the whole precedence chain can be
+tested without mutating the process environment: a module-patched global cannot
+be exercised two different ways in one process, which is the same argument that
+makes the credential and the transport constructor-injected.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Mapping, Optional
+
+#: Environment variable holding the server **origin** (see `_config.py`).
+ENV_BASE_URL: str = "W6W_BASE_URL"
+
+#: Environment variable holding the bearer token.
+ENV_TOKEN: str = "W6W_TOKEN"
+
+
+def process_environ() -> Mapping[str, str]:
+    """Return the live process environment.
+
+    Factored out as a function so `read_env`'s default source is a named,
+    assertable thing rather than a value captured at import time — and so this
+    file stays the single grep-able point where `os.environ` appears.
+
+    :returns: `os.environ` itself (not a copy — reads must see later changes).
+    """
+    return os.environ
+
+
+def read_env(name: str, environ: Optional[Mapping[str, str]] = None) -> Optional[str]:
+    """Read one environment variable, or `None` when it carries no usable value.
+
+    **A variable that is set but empty — or whitespace-only — reads as ABSENT.**
+    `W6W_BASE_URL=`, `W6W_BASE_URL="   "`, `W6W_BASE_URL=$'\\n'` and an unset
+    `W6W_BASE_URL` are all the same thing here, and the precedence chain falls
+    through all four to the next source (and ultimately to a `ConfigError`).
+
+    The guard is therefore a **truthiness/strip** check and deliberately *not*
+    an `is None` test. `os.environ.get` returns `""` for a set-but-empty
+    variable, never `None`, so `is None` is the Python spelling of the same
+    nullish-coalescing mistake that `docs/implementation.md` §2 forbids in the
+    TypeScript wrappers: an empty `W6W_BASE_URL` would survive as a value and
+    short-circuit the precedence chain, leaving the client on an empty base and
+    issuing every request against a relative URL — exactly the browser
+    same-origin default a library must not have. Do not "tidy" this into
+    `if value is None`.
+
+    An empty environment variable is not a hypothetical. `export W6W_BASE_URL=`,
+    a Dockerfile `ENV W6W_BASE_URL=` with no build arg, and a CI variable whose
+    template did not interpolate all produce exactly this, and it *looks* absent
+    in every log line while behaving as present in every null check.
+
+    The value is returned **verbatim**, not stripped: trimming applies to the
+    emptiness *test*, not to the stored value. Normalising the shape of a base
+    URL is the join rule's job (`_config.join_base_url`).
+
+    :param name: The variable to read, e.g. :data:`ENV_BASE_URL`.
+    :param environ: Mapping to read from. Defaults to the process environment;
+        pass one to test the precedence chain without touching `os.environ`.
+    :returns: The value, or `None` if unset, empty or whitespace-only.
+    """
+    source = process_environ() if environ is None else environ
+    value = source.get(name)
+    if value is None or not value.strip():
+        return None
+    return value