ohapi 0.1.0__tar.gz

ohapi-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,106 @@
+# 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/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-0.1.0/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)
+        )