ohapi 0.1.0__py3-none-any.whl

ohapi/__init__.py

@@ -0,0 +1,31 @@
+"""Typed client for the ohapi secrets API. Zero dependencies, `urllib` only."""
+
+__version__ = "0.1.0"  # keep equal to pyproject.toml `version`; the tests assert it
+
+from ._client import OhapiError  # noqa: E402
+from ._types import (  # noqa: E402
+    ChangeRequest,
+    Collection,
+    Deleted,
+    Environment,
+    EnvironmentRef,
+    EnvironmentSummary,
+    Me,
+    MeApiKey,
+    OrganizationRef,
+    Patched,
+    Pending,
+    Project,
+    ProjectSummary,
+    Scope,
+    SecretMetadata,
+    SecretValue,
+    Written,
+)
+from .client import UNSET, Ohapi  # noqa: E402
+
+__all__ = [
+    "ChangeRequest", "Collection", "Deleted", "Environment", "EnvironmentRef", "EnvironmentSummary",
+    "Me", "MeApiKey", "Ohapi", "OhapiError", "OrganizationRef", "Patched", "Pending", "Project",
+    "ProjectSummary", "Scope", "SecretMetadata", "SecretValue", "UNSET", "Written", "__version__",
+]

ohapi/_client.py

@@ -0,0 +1,259 @@
+"""The one place a request is made: urllib with no redirects, a timeout and an error mapping."""
+
+import http.client
+import json
+import re
+import socket
+import threading
+import urllib.error
+import urllib.request
+from urllib.parse import urlencode, urlsplit
+
+from . import __version__
+
+DEFAULT_API_URL = "https://ohapi.dev"
+DEFAULT_TIMEOUT_S = 30.0
+_LOOPBACK_HOSTS = ("127.0.0.1", "localhost", "::1")
+_DEFAULT_PORTS = {"http": 80, "https": 443}
+
+
+class OhapiError(Exception):
+    """Every failure of this package.
+
+    `code` is one of: invalid, unauthenticated, forbidden, not_found, conflict, unprocessable,
+    rate_limited, server, network, timeout, rejected. `status` is the HTTP status, or 0 when no
+    response was involved. `change_request` is set on `rejected`: the terminal request.
+    """
+
+    def __init__(self, code, message, *, status=0, retry_after_seconds=None, change_request=None):
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.retry_after_seconds = retry_after_seconds
+        self.change_request = change_request
+
+
+def normalize_api_url(raw):
+    """The server: its origin, plus a sub-path if it is hosted under one (no trailing slash).
+
+    Plain `http://` only for loopback, and no userinfo: the same rule as the CLI's `normalizeApiUrl`.
+    """
+    try:
+        parts = urlsplit(raw)
+        host, port = parts.hostname, parts.port
+    except (ValueError, AttributeError):
+        raise OhapiError("invalid", "apiUrl is not a URL") from None
+    scheme = parts.scheme.lower()
+    if not scheme or not host:
+        raise OhapiError("invalid", "apiUrl is not a URL")
+    if scheme != "https" and not (scheme == "http" and host in _LOOPBACK_HOSTS):
+        raise OhapiError("invalid", "apiUrl must be https:// (http:// is allowed only for loopback)")
+    if parts.username is not None or parts.password is not None:
+        raise OhapiError("invalid", "apiUrl must not carry credentials")
+    shown = "[%s]" % host if ":" in host else host
+    if port is not None and port != _DEFAULT_PORTS[scheme]:
+        shown = "%s:%d" % (shown, port)
+    return "%s://%s%s" % (scheme, shown, parts.path.rstrip("/"))
+
+
+def _error_code_for(status):
+    if status == 401:
+        return "unauthenticated"
+    if status == 403:
+        return "forbidden"
+    if status == 404:
+        return "not_found"
+    if status == 409:
+        return "conflict"
+    if status == 422:
+        return "unprocessable"
+    if status == 429:
+        return "rate_limited"
+    if 400 <= status < 500:
+        return "invalid"
+    return "server"
+
+
+def _retry_after(headers):
+    match = re.match(r"\s*([+-]?\d+)", headers.get("retry-after") or "")
+    if match and int(match.group(1)) >= 0:
+        return int(match.group(1))
+    return None
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    # The base `http_error_30x` reads `Location` and builds the new URL before it asks
+    # `redirect_request`, so a malformed `Location` would raise from there. Returning None here
+    # means `Location` is never read: `OpenerDirector.error` falls through to
+    # `HTTPDefaultErrorHandler`, which raises `HTTPError` with the 3xx code.
+    def http_error_301(self, req, fp, code, msg, headers):
+        return None
+
+    http_error_302 = http_error_303 = http_error_307 = http_error_308 = http_error_301
+
+
+class _Deadline:
+    """A total deadline for one request, enforced by shutting its sockets down.
+
+    A socket timeout bounds one read. A server that sends a byte every few seconds never trips it.
+    """
+
+    def __init__(self, seconds):
+        self.expired = False
+        self._sockets = []
+        self._lock = threading.Lock()
+        self._timer = threading.Timer(seconds, self._fire)
+        self._timer.daemon = True
+
+    def start(self):
+        self._timer.start()
+
+    def stop(self):
+        self._timer.cancel()
+
+    def add(self, sock):
+        with self._lock:
+            self._sockets.append(sock)
+            expired = self.expired
+        if expired:
+            self._kill(sock)
+
+    def _fire(self):
+        with self._lock:
+            self.expired = True
+            sockets = list(self._sockets)
+        for sock in sockets:
+            self._kill(sock)
+
+    @staticmethod
+    def _kill(sock):
+        try:
+            sock.shutdown(socket.SHUT_RDWR)
+        except OSError:
+            pass
+
+
+def _connection(base):
+    class Connection(base):
+        def __init__(self, *args, deadline=None, **kwargs):
+            super().__init__(*args, **kwargs)
+            self._deadline = deadline
+
+        def connect(self):
+            super().connect()
+            self._deadline.add(self.sock)
+
+    return Connection
+
+
+_HTTPConnection = _connection(http.client.HTTPConnection)
+_HTTPSConnection = _connection(http.client.HTTPSConnection)
+
+
+class _HTTPHandler(urllib.request.HTTPHandler):
+    def http_open(self, req):
+        return self.do_open(lambda host, **kw: _HTTPConnection(host, deadline=req.ohapi_deadline, **kw), req)
+
+
+class _HTTPSHandler(urllib.request.HTTPSHandler):
+    def https_open(self, req):
+        return self.do_open(
+            lambda host, **kw: _HTTPSConnection(host, deadline=req.ohapi_deadline, **kw), req, context=self._context
+        )
+
+
+class Client:
+    def __init__(self, token, api_url=None, timeout_s=DEFAULT_TIMEOUT_S, user_agent=None):
+        if not isinstance(token, str) or token == "":
+            raise OhapiError("invalid", "token is required")
+        # Never sent: http.client would raise, and its message quotes the header value.
+        if re.search(r"[\r\n\0]", token):
+            raise OhapiError("invalid", "token must not contain control characters")
+        # Name-mangled, and kept out of repr(): a logger that prints the client must not print the bearer.
+        self.__token = token
+        self.api_url = normalize_api_url(DEFAULT_API_URL if api_url is None else api_url)
+        self.timeout_s = timeout_s
+        self.user_agent = user_agent or "ohapi-sdk-python/%s" % __version__
+        self.__opener = urllib.request.build_opener(_NoRedirect, _HTTPHandler, _HTTPSHandler)
+
+    def __repr__(self):
+        return "Client(api_url=%r)" % self.api_url
+
+    __str__ = __repr__
+
+    def request(self, method, path, *, query=None, headers=None, body=None, timeout_s=None):
+        """Returns `(status, parsed JSON or None)`. A 202 is not an error; everything else outside 2xx raises.
+
+        `timeout_s` is a total deadline for the whole exchange, headers and body included.
+        """
+        url = self.api_url + path
+        pairs = [(name, value) for name, value in (query or {}).items() if value is not None]
+        if pairs:
+            url += "?" + urlencode(pairs)
+        data = None
+        if body is not None:
+            try:
+                data = json.dumps(body, separators=(",", ":"), ensure_ascii=False).encode()
+            except UnicodeEncodeError:
+                raise OhapiError("invalid", "body: must be valid Unicode") from None
+        seconds = timeout_s or self.timeout_s
+
+        # The headers are built inside this call and bound to no local: a traceback (or a logger
+        # that prints frame locals) must not find the bearer in this frame. For the same reason a
+        # failure is recorded in the `except` as a code only, and raised after it with no cause:
+        # the original error's frames (urllib's `do_open` holds the headers) must not be reachable.
+        request = urllib.request.Request(
+            url, data=data, method=method,
+            headers={
+                "authorization": "Bearer " + self.__token,
+                "user-agent": self.user_agent,
+                "accept": "application/json",
+                # urllib would say form-encoded: it does so for any request with data.
+                **({"content-type": "application/json"} if data is not None else {}),
+                **(headers or {}),
+            },
+        )
+        request.ohapi_deadline = deadline = _Deadline(seconds)
+        deadline.start()
+
+        failure = None
+        status, raw, response_headers = 0, b"", {}
+        try:
+            with self.__opener.open(request, timeout=seconds) as response:
+                status, raw = response.status, response.read()
+        except urllib.error.HTTPError as error:
+            status = error.code
+            response_headers = {name.lower(): value for name, value in error.headers.items()}
+            try:
+                raw = error.read()
+            except (OSError, http.client.HTTPException):
+                raw = b""
+            finally:
+                error.close()
+        except (OSError, http.client.HTTPException):
+            failure = "network"
+        finally:
+            deadline.stop()
+
+        if deadline.expired:
+            raise OhapiError("timeout", "No response within %s s" % seconds)
+        if failure is not None:
+            raise OhapiError(failure, "Could not reach the ohapi server")
+
+        try:
+            parsed = json.loads(raw) if raw else None
+        except ValueError:
+            parsed = None
+            if 200 <= status < 300:
+                raise OhapiError("server", "HTTP %d" % status, status=status) from None
+
+        if 200 <= status < 300:
+            return status, parsed
+
+        # A 3xx is never followed (the bearer would go with it) and is never a JSON error.
+        text = "HTTP %d" % status
+        if status >= 400 and isinstance(parsed, dict) and isinstance(parsed.get("error"), str):
+            text = parsed["error"]
+        raise OhapiError(
+            _error_code_for(status), text, status=status, retry_after_seconds=_retry_after(response_headers)
+        )

ohapi/_types.py

@@ -0,0 +1,213 @@
+"""Response types, hand-written to mirror `sdk/src/types.ts`.
+
+Each is built from the fields it knows and ignores the rest, so a field the server adds later is
+invisible here (the additive contract of `v1`). A field the server stops sending is a `server`
+error, not a `TypeError` from a constructor.
+"""
+
+import dataclasses
+from dataclasses import dataclass
+from typing import Generic, List, Optional, TypeVar
+
+from ._client import OhapiError
+
+T = TypeVar("T")
+
+
+def _camel(name):
+    head, *rest = name.split("_")
+    return head + "".join(word.capitalize() for word in rest)
+
+
+def make(cls, data, nested=None):
+    """Build `cls` from a camelCase JSON object. `nested` maps a field name to a converter."""
+    if not isinstance(data, dict):
+        raise OhapiError("server", "Response is not a JSON object")
+    values = {}
+    for field in dataclasses.fields(cls):
+        name = _camel(field.name)
+        if name in data:
+            value = data[name]
+            if nested and field.name in nested and value is not None:
+                value = nested[field.name](value)
+            values[field.name] = value
+    try:
+        return cls(**values)
+    except TypeError:
+        raise OhapiError("server", "Response is missing a field of %s" % cls.__name__) from None
+
+
+@dataclass(frozen=True)
+class Scope:
+    project_id: Optional[str]
+    environments: List[str]
+    access: str  # "READ" or "WRITE"
+
+
+@dataclass(frozen=True)
+class MeApiKey:
+    id: str
+    name: str
+    expires_at: Optional[str]
+    oidc_trust_id: Optional[str]
+
+
+@dataclass(frozen=True)
+class Me:
+    id: str
+    email: Optional[str]
+    name: Optional[str]
+    is_service_account: bool
+    api_key: MeApiKey
+    scope: Optional[Scope]
+
+
+@dataclass(frozen=True)
+class OrganizationRef:
+    id: str
+    name: str
+    slug: str
+
+
+@dataclass(frozen=True)
+class EnvironmentRef:
+    id: str
+    name: str
+
+
+@dataclass(frozen=True)
+class ProjectSummary:
+    id: str
+    name: str
+    slug: str
+    organization: OrganizationRef
+    role: str  # "ADMIN", "MEMBER" or "VIEWER"
+    created_at: str
+    environments: List[EnvironmentRef]
+
+
+@dataclass(frozen=True)
+class Project:
+    id: str
+    name: str
+    slug: str
+    organization_id: str
+    role: str
+    environments: List[EnvironmentRef]
+    created_at: str
+    updated_at: str
+
+
+@dataclass(frozen=True)
+class EnvironmentSummary:
+    id: str
+    name: str
+    secret_count: int
+    created_at: str
+
+
+@dataclass(frozen=True)
+class Environment:
+    id: str
+    name: str
+    project_id: str
+    secret_count: int
+    created_at: str
+    updated_at: str
+
+
+@dataclass(frozen=True)
+class SecretMetadata:
+    """Metadata only. There is no value on this type, and reading it writes no audit row."""
+
+    id: str
+    key: str
+    version: int  # bumps once per value change and never for a metadata change: the drift signal
+    value_type: str
+    format_regex: Optional[str]
+    rotation_due_at: Optional[str]
+    expires_at: Optional[str]
+    is_reference: bool
+    updated_at: str
+    updated_by_id: Optional[str]
+    environment: str
+    project_id: str
+
+
+@dataclass(frozen=True)
+class SecretValue:
+    key: str
+    value: str
+    is_reference: bool
+    resolved: bool
+    value_type: str
+    expires_at: Optional[str]
+
+
+@dataclass(frozen=True)
+class ChangeRequest:
+    id: str
+    status: str  # "PENDING", "APPLIED", "REJECTED" or "CANCELLED"
+    action: str  # "CREATE", "UPDATE" or "DELETE"
+    secret_key: str
+    environment_name: str
+    project_id: str
+    required_approvals: int
+    approvals: int
+    created_at: str
+    resolved_at: Optional[str]
+    note: Optional[str]
+
+
+@dataclass(frozen=True)
+class Collection(Generic[T]):
+    data: List[T]
+    page: int
+    page_size: int
+    total: int
+    total_pages: int
+
+
+@dataclass(frozen=True)
+class Pending:
+    """Dual control holds the change: nothing was written yet. Check for this before reading `version`."""
+
+    change_request_id: str
+    key: str
+
+
+@dataclass(frozen=True)
+class Written:
+    key: str
+    version: int
+    created: bool
+    id: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class Patched:
+    key: str
+
+
+@dataclass(frozen=True)
+class Deleted:
+    key: str
+
+
+def _list_of(cls):
+    return lambda rows: [make(cls, row) for row in rows]
+
+
+def _collection(cls):
+    def build(body):
+        collection = make(Collection, body, {"data": _list_of(cls)})
+        return collection
+
+    return build
+
+
+# Converters used by `client.py`.
+ME_NESTED = {"api_key": lambda v: make(MeApiKey, v), "scope": lambda v: make(Scope, v)}
+PROJECT_SUMMARY_NESTED = {"organization": lambda v: make(OrganizationRef, v), "environments": _list_of(EnvironmentRef)}
+PROJECT_NESTED = {"environments": _list_of(EnvironmentRef)}
+collection_of = _collection

ohapi/_validate.py

@@ -0,0 +1,74 @@
+"""Name and value rules, checked before a URL is composed.
+
+The patterns are the Node SDK's (`sdk/src/index.ts`), which are the server's
+(`src/lib/api/paths.ts`). A name that fails raises `invalid` and nothing is sent.
+`fullmatch` is deliberate: `$` in Python matches before a trailing newline.
+"""
+
+import re
+
+from ._client import OhapiError
+
+# cuid is Zod 4's `z.cuid()`; keep it as lax as the server, never stricter.
+_CUID = re.compile(r"[cC][0-9a-z]{6,}")
+_ENVIRONMENT = re.compile(r"[a-z0-9][a-z0-9_-]*")
+_KEY = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+# The server counts UTF-16 code units (`z.string().max(64 * 1024)`), so this does too.
+MAX_VALUE_LENGTH = 64 * 1024
+
+
+def _invalid(field, rule):
+    # Names the field and the rule, never the offending value.
+    raise OhapiError("invalid", "%s: %s" % (field, rule))
+
+
+def project_id(value):
+    if isinstance(value, str) and _CUID.fullmatch(value):
+        return value
+    _invalid("projectId", "must be a project id")
+
+
+def change_request_id(value):
+    if isinstance(value, str) and _CUID.fullmatch(value):
+        return value
+    _invalid("changeRequestId", "must be a change request id")
+
+
+def environment(value):
+    if isinstance(value, str) and len(value) <= 64 and _ENVIRONMENT.fullmatch(value):
+        return value
+    _invalid("environment", "use lowercase letters, numbers, dashes and underscores, at most 64")
+
+
+def key(value):
+    if isinstance(value, str) and len(value) <= 255 and _KEY.fullmatch(value):
+        return value
+    _invalid("key", "must look like an env var, e.g. DATABASE_URL")
+
+
+def text(field, value):
+    """A string that can be sent as UTF-8. A lone surrogate cannot, and would raise deep in the encoder."""
+    try:
+        value.encode("utf-8")
+    except UnicodeEncodeError:
+        _invalid(field, "must be valid Unicode")
+    return value
+
+
+def secret_value(value):
+    if isinstance(value, str) and len(text("value", value).encode("utf-16-le")) // 2 <= MAX_VALUE_LENGTH:
+        return value
+    _invalid("value", "must be a string of at most 64 KB")
+
+
+def user_agent(value):
+    # A header value: printable ASCII only, so it can never carry a line break.
+    if isinstance(value, str) and 0 < len(value) <= 256 and value.isascii() and value.isprintable():
+        return value
+    _invalid("userAgent", "must be 1 to 256 printable ASCII characters")
+
+
+def timeout_s(value):
+    if isinstance(value, (int, float)) and not isinstance(value, bool) and 0 < value < float("inf"):
+        return value
+    _invalid("timeoutS", "must be a number of seconds above 0")

ohapi/client.py

@@ -0,0 +1,287 @@
+"""`Ohapi`: the typed client. Names are the Node SDK's (`sdk/src/index.ts`) in snake_case."""
+
+import datetime
+import threading
+import time
+
+from . import _validate as check
+from ._client import DEFAULT_TIMEOUT_S, Client, OhapiError
+from ._types import (
+    PROJECT_NESTED,
+    PROJECT_SUMMARY_NESTED,
+    ME_NESTED,
+    ChangeRequest,
+    Deleted,
+    Environment,
+    EnvironmentSummary,
+    Me,
+    Patched,
+    Pending,
+    Project,
+    ProjectSummary,
+    SecretMetadata,
+    SecretValue,
+    Written,
+    collection_of,
+    make,
+)
+
+# "Omitted" and "None" are different things on the wire: an omitted field leaves the column alone,
+# an explicit None (JSON null) clears it. A `None` default would collapse the two.
+UNSET = object()
+
+
+def _date(value):
+    if isinstance(value, datetime.datetime):
+        utc = value.astimezone(datetime.timezone.utc)
+        return utc.strftime("%Y-%m-%dT%H:%M:%S.") + "%03dZ" % (utc.microsecond // 1000)
+    if value is None or isinstance(value, str):
+        return value
+    raise OhapiError("invalid", "date: use an ISO 8601 string or a datetime")
+
+
+def _given(**fields):
+    """The fields the caller set, as the JSON names the server uses."""
+    names = {
+        "format_regex": "formatRegex", "rotation_due_at": "rotationDueAt", "expires_at": "expiresAt",
+        "value_type": "valueType", "note": "note",
+    }
+    body = {}
+    for name, value in fields.items():
+        if value is UNSET:
+            continue
+        if isinstance(value, str):
+            check.text(name, value)
+        body[names[name]] = _date(value) if name in ("rotation_due_at", "expires_at") else value
+    return body
+
+
+def _env_path(project_id, environment):
+    return "/api/v1/projects/%s/environments/%s" % (check.project_id(project_id), check.environment(environment))
+
+
+def _secret_path(project_id, environment, key):
+    return "%s/secrets/%s" % (_env_path(project_id, environment), check.key(key))
+
+
+def _target_headers(project_id, environment):
+    return {"x-project-id": check.project_id(project_id), "x-environment": check.environment(environment)}
+
+
+def _confirm(confirm_production):
+    return {"x-confirm-production": "true"} if confirm_production else {}
+
+
+def _written(status, body, key, cls):
+    # By status, not by "the request worked": a 202 succeeds and nothing was written.
+    if status == 202:
+        if not isinstance(body, dict) or not isinstance(body.get("changeRequestId"), str):
+            raise OhapiError("server", "Response has no change request id")
+        return Pending(change_request_id=body["changeRequestId"], key=key)
+    return make(cls, body)
+
+
+def _walk(fetch_page):
+    page = 1
+    while True:
+        result = fetch_page(page)
+        # A missing count would loop forever.
+        if not isinstance(result.total_pages, int):
+            raise OhapiError("server", "Response has no page count")
+        yield from result.data
+        if page >= result.total_pages:
+            return
+        page += 1
+
+
+class _Projects:
+    def __init__(self, client):
+        self._c = client
+
+    def list(self):
+        """`GET /api/v1/projects` (the frozen shape, unwrapped). Names only; no audit row."""
+        _, body = self._c.request("GET", "/api/v1/projects")
+        rows = body.get("projects") if isinstance(body, dict) else None
+        return [make(ProjectSummary, row, PROJECT_SUMMARY_NESTED) for row in rows or []]
+
+    def get(self, project_id):
+        _, body = self._c.request("GET", "/api/v1/projects/" + check.project_id(project_id))
+        return make(Project, body, PROJECT_NESTED)
+
+
+class _Environments:
+    def __init__(self, client):
+        self._c = client
+
+    def list(self, project_id, *, page=None, page_size=None):
+        _, body = self._c.request(
+            "GET", "/api/v1/projects/%s/environments" % check.project_id(project_id),
+            query={"page": page, "pageSize": page_size},
+        )
+        return collection_of(EnvironmentSummary)(body)
+
+    def iterate(self, project_id, *, page_size=None):
+        return _walk(lambda page: self.list(project_id, page=page, page_size=page_size))
+
+    def get(self, project_id, environment):
+        _, body = self._c.request("GET", _env_path(project_id, environment))
+        return make(Environment, body)
+
+
+class _Secrets:
+    def __init__(self, client):
+        self._c = client
+
+    def list(self, project_id, environment, *, page=None, page_size=None):
+        """Metadata only. **Writes no audit row.**"""
+        _, body = self._c.request(
+            "GET", _env_path(project_id, environment) + "/secrets", query={"page": page, "pageSize": page_size}
+        )
+        return collection_of(SecretMetadata)(body)
+
+    def iterate(self, project_id, environment, *, page_size=None):
+        return _walk(lambda page: self.list(project_id, environment, page=page, page_size=page_size))
+
+    def get(self, project_id, environment, key):
+        """One secret's metadata. **Writes no audit row**, and has no value. `version` is the drift signal."""
+        _, body = self._c.request("GET", _secret_path(project_id, environment, key))
+        return make(SecretMetadata, body)
+
+    def value(self, project_id, environment, key):
+        """The plaintext value. **Writes a `READ` audit row naming the key**, every call.
+
+        Prefer `get()` when you only need to know the secret exists or changed.
+        """
+        _, body = self._c.request("GET", _secret_path(project_id, environment, key) + "/value")
+        return make(SecretValue, body)
+
+    def set(self, project_id, environment, key, value, *, format_regex=UNSET, rotation_due_at=UNSET,
+            expires_at=UNSET, value_type=UNSET, note=UNSET, confirm_production=False):
+        """`PUT`: create or update. Returns `Written`, or `Pending` when dual control holds the change."""
+        return self._write("PUT", project_id, environment, key, value, confirm_production, _given(
+            format_regex=format_regex, rotation_due_at=rotation_due_at, expires_at=expires_at,
+            value_type=value_type, note=note,
+        ))
+
+    def create(self, project_id, environment, key, value, *, format_regex=UNSET, rotation_due_at=UNSET,
+               expires_at=UNSET, value_type=UNSET, note=UNSET, confirm_production=False):
+        """`POST`: create only. An existing key raises `OhapiError` with code `conflict`."""
+        return self._write("POST", project_id, environment, key, value, confirm_production, _given(
+            format_regex=format_regex, rotation_due_at=rotation_due_at, expires_at=expires_at,
+            value_type=value_type, note=note,
+        ))
+
+    def _write(self, method, project_id, environment, key, value, confirm_production, extra):
+        check.secret_value(value)
+        status, body = self._c.request(
+            method, "/api/v1/secrets",
+            headers={**_target_headers(project_id, environment), **_confirm(confirm_production)},
+            body={"key": check.key(key), "value": value, **extra},
+        )
+        return _written(status, body, key, Written)
+
+    def patch(self, project_id, environment, key, *, rotation_due_at=UNSET, expires_at=UNSET,
+              format_regex=UNSET, note=UNSET, confirm_production=False):
+        """`PATCH`: dates and `formatRegex` only. Never appends a version.
+
+        An omitted field is left alone. `None` clears it.
+        """
+        status, body = self._c.request(
+            "PATCH", _secret_path(project_id, environment, key), headers=_confirm(confirm_production),
+            body=_given(rotation_due_at=rotation_due_at, expires_at=expires_at, format_regex=format_regex, note=note),
+        )
+        return _written(status, body, key, Patched)
+
+    def delete(self, project_id, environment, key, *, confirm_production=False):
+        status, body = self._c.request(
+            "DELETE", "/api/v1/secrets",
+            headers={**_target_headers(project_id, environment), **_confirm(confirm_production)},
+            body={"key": check.key(key)},
+        )
+        return _written(status, body, key, Deleted)
+
+    def pull(self, project_id, environment):
+        """The whole environment as `{KEY: VALUE}`, expired keys omitted.
+
+        **Writes one `READ` audit row for the environment.** Meant for an app at boot; do not call
+        it to check a key.
+        """
+        _, body = self._c.request("GET", "/api/v1/secrets", headers=_target_headers(project_id, environment))
+        return body if isinstance(body, dict) else {}
+
+
+class _ChangeRequests:
+    def __init__(self, client):
+        self._c = client
+
+    def get(self, change_request_id):
+        _, body = self._c.request("GET", "/api/v1/change-requests/" + check.change_request_id(change_request_id))
+        return make(ChangeRequest, body)
+
+    def wait(self, change_request_id, *, interval_s=5.0, timeout_s=600.0, cancel=None):
+        """Poll until the request is `APPLIED`.
+
+        `REJECTED` and `CANCELLED` raise `OhapiError` with code `rejected` (the terminal request is
+        on `error.change_request`): returning would let a caller believe a rejected production
+        change landed. A 429 waits `Retry-After` and never tightens the loop. Time runs out, or
+        `cancel` (a `threading.Event`) is set: code `timeout`. A request already in flight is not
+        interrupted by `cancel`; it ends at its own timeout.
+        """
+        path = "/api/v1/change-requests/" + check.change_request_id(change_request_id)
+        deadline = time.monotonic() + timeout_s
+        while True:
+            if cancel is not None and cancel.is_set():
+                raise OhapiError("timeout", "wait() was cancelled")
+            pause = interval_s
+            try:
+                remaining = max(deadline - time.monotonic(), 0.001)
+                _, body = self._c.request("GET", path, timeout_s=min(self._c.timeout_s, remaining))
+                request = make(ChangeRequest, body)
+                if request.status == "APPLIED":
+                    return request
+                if request.status in ("REJECTED", "CANCELLED"):
+                    raise OhapiError(
+                        "rejected", "Change request was %s" % request.status.lower(), change_request=request
+                    )
+            except OhapiError as error:
+                if error.code != "rate_limited":
+                    raise
+                pause = max(interval_s, error.retry_after_seconds or 0)
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise OhapiError("timeout", "Change request still pending when wait() gave up")
+            pause = min(pause, remaining, threading.TIMEOUT_MAX)
+            if cancel is not None:
+                if cancel.wait(pause):
+                    raise OhapiError("timeout", "wait() was cancelled")
+            else:
+                time.sleep(pause)
+
+
+class Ohapi:
+    """Typed client for the ohapi machine API.
+
+    No retries, no logging, no globals: a thin client does not decide retry policy.
+    `change_requests.wait()` is the one polling helper, and it is explicit.
+    """
+
+    def __init__(self, token, *, api_url=None, timeout_s=DEFAULT_TIMEOUT_S, user_agent=None):
+        self.__client = Client(token, api_url, check.timeout_s(timeout_s), None if user_agent is None else check.user_agent(user_agent))
+        self.projects = _Projects(self.__client)
+        self.environments = _Environments(self.__client)
+        self.secrets = _Secrets(self.__client)
+        self.change_requests = _ChangeRequests(self.__client)
+
+    @property
+    def api_url(self):
+        return self.__client.api_url
+
+    def me(self):
+        """`GET /api/v1/me`: who this key acts as. No audit row."""
+        _, body = self.__client.request("GET", "/api/v1/me")
+        return make(Me, body, ME_NESTED)
+
+    def __repr__(self):
+        return "Ohapi(api_url=%r)" % self.api_url
+
+    __str__ = __repr__

ohapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: ohapi
+Version: 0.1.0
+Summary: Python client for the ohapi secrets API.
+Author: Obsidian Heron
+License-Expression: MIT
+Project-URL: Homepage, https://ohapi.dev
+Project-URL: Issues, https://github.com/Obsidian-Heron/ohapi/issues
+Project-URL: Source, https://github.com/Obsidian-Heron/ohapi/tree/main/sdk-python
+Keywords: secrets,env,environment-variables,secrets-management,sdk
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ohapi
+
+A typed Python client for the ohapi secrets API. It has no dependencies. It uses only the standard library. It needs Python 3.10 or later.
+
+## Install
+
+```sh
+pip install ohapi
+```
+
+The package is not on PyPI yet.
+
+## Example
+
+```python
+import os
+
+from ohapi import Ohapi, OhapiError, Pending
+
+ohapi = Ohapi(os.environ["OHAPI_TOKEN"])
+
+result = ohapi.secrets.set(project_id, "production", "API_URL", "https://api.example.com", confirm_production=True)
+
+if isinstance(result, Pending):
+    # Dual control holds the change. Nothing is written yet.
+    try:
+        ohapi.change_requests.wait(result.change_request_id)
+    except OhapiError as error:
+        if error.code != "rejected":
+            raise
+        print("A reviewer refused the change:", error.change_request.status)
+else:
+    print("Wrote version", result.version)
+```
+
+## Methods
+
+| Method | Endpoint | Audit row |
+| --- | --- | --- |
+| `me()` | `GET /api/v1/me` | No |
+| `projects.list()`, `projects.get(id)` | `GET /api/v1/projects`, `…/{id}` | No |
+| `environments.list()`, `.iterate()`, `.get()` | `GET …/environments` | No |
+| `secrets.list()`, `.iterate()`, `.get()` | `GET …/secrets` | **No.** Metadata only. |
+| `secrets.value()` | `GET …/secrets/{key}/value` | **Yes.** One `READ` row for each call. |
+| `secrets.pull()` | `GET /api/v1/secrets` | **Yes.** One `READ` row for the environment. Expired keys are omitted. |
+| `secrets.set()`, `.create()`, `.patch()`, `.delete()` | `PUT`, `POST`, `PATCH`, `DELETE` | Yes, when the write lands. A `Pending` result has no row yet. The row is written when an admin approves the change. |
+| `change_requests.get()`, `.wait()` | `GET /api/v1/change-requests/{id}` | No |
+
+`list()` takes `page` and `page_size`. `iterate()` takes `page_size`. The server accepts page numbers up to 10000 and page sizes up to 500.
+
+The client is synchronous. There is no `asyncio` client.
+
+## Pending writes
+
+Dual control can hold a write to `production`. In that case a write returns `Pending` with a `change_request_id`. The value is not written. Check `isinstance(result, Pending)` before you read `version`.
+
+A write returns one of these types:
+
+| Call | Result |
+| --- | --- |
+| `set()`, `create()` | `Written(key, version, created, id)` |
+| `patch()` | `Patched(key)` |
+| `delete()` | `Deleted(key)` |
+| Any of them, when dual control holds the change | `Pending(change_request_id, key)` |
+
+`wait(change_request_id, interval_s=5.0, timeout_s=600.0, cancel=None)` returns only when the request is `APPLIED`. It raises `OhapiError` with code `rejected` when a reviewer rejects or cancels the request. The terminal request is in `error.change_request`. To stop a wait from another thread, pass a `threading.Event` as `cancel` and set it. A request that is already in flight ends at its own deadline, which is never later than the end of `timeout_s`.
+
+## Omitted and `None`
+
+`set()` and `create()` take `format_regex`, `rotation_due_at`, `expires_at`, `value_type` and `note` as optional arguments. `value_type` is `STRING`, `JSON`, `PASSWORD` or `CERTIFICATE`. `patch()` takes the same arguments except `value_type`. An argument you leave out does not change the stored value. An argument you pass as `None` clears the stored value. Dates are ISO 8601 strings or `datetime` objects.
+
+## Errors
+
+Every failure of a request, and every input that the SDK refuses, is an `OhapiError` with a `code`, a `status` (0 when there was no response), and a message. A wrong call, for example a missing argument, is still a normal Python `TypeError`.
+
+| Code | Cause |
+| --- | --- |
+| `invalid` | Bad input. The SDK refused it before any request, or the server answered `400`. |
+| `unauthenticated` | `401`. The key is missing, wrong, or expired. |
+| `forbidden` | `403`. The key has a read-only role, the route is for admins only, or the key scope does not cover the target. |
+| `not_found` | `404`. The thing does not exist, or the key cannot reach it. |
+| `conflict` | `409`. `create()` found the key already there. |
+| `unprocessable` | `422`. The server refused the value. |
+| `rate_limited` | `429`. `retry_after_seconds` holds the wait. |
+| `server` | Any other HTTP failure. A redirect is also `server`, and so is a `2xx` answer that is not JSON. The SDK never follows a redirect and never reads its `Location` header. |
+| `network` | No connection. |
+| `timeout` | The whole request, headers and body included, did not finish within `timeout_s` (30 seconds by default), or `wait()` ended. |
+| `rejected` | `wait()` found a rejected or cancelled change request. |
+
+The SDK does not retry. You decide the retry policy. The SDK does not log.
+
+## The key
+
+The client keeps the key in a name-mangled attribute. `repr()` and `str()` of the client do not print it. A traceback that shows local variables does not contain it either. This protects logs. It does not hide the key from other code in the same process. The SDK refuses a key that contains a carriage return, a line feed or a null character. It also refuses a custom `user_agent` that is not printable ASCII.
+
+## Not included
+
+The SDK does not create, rename, or delete projects and environments. It does not wrap the organization endpoints. Use the dashboard or the HTTP API for those.
+
+## Tests
+
+```sh
+sdk-python/scripts/test.sh
+```
+
+The script runs the unit tests in Docker. The tests need no server.

ohapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+ohapi/__init__.py,sha256=de4nnEjRCaZb8w0yq_WtI2f5SpwUEk1sxPQ13BYeXGY,882
+ohapi/_client.py,sha256=x93iSU9cw2ufN2DIluVOHNJMCoUEIiITxmfrlEror6I,9647
+ohapi/_types.py,sha256=LdRr-drYVswQtQx94YOX4KT3S9XWu5nTfhp_CySDK24,4732
+ohapi/_validate.py,sha256=QZKPMH_gK2oRE3fVS1xjdVlwuSQiAapnaryRebmGuRY,2559
+ohapi/client.py,sha256=sNdbecITr5niKwiDg-TVFKxV30yJD2fMK0L-RVhzNRQ,11856
+ohapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ohapi-0.1.0.dist-info/licenses/LICENSE,sha256=_BE4gs94_TGtLEEtSjI-bj64vFPEM8VmZDseXJubqqU,1071
+ohapi-0.1.0.dist-info/METADATA,sha256=lJaWEnPfxF0MQBdxRzIp8QYJg3NhOa6NTunDupzn09M,6012
+ohapi-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ohapi-0.1.0.dist-info/top_level.txt,sha256=uUMR0w0FfsvUN-uVB69bEDPDXH0wmaCyW-kc3Q-z9tM,6
+ohapi-0.1.0.dist-info/RECORD,,

ohapi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ohapi-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Obsidian Heron
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ohapi-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ohapi