papollo 0.1.0__py3-none-any.whl

papollo/__init__.py

@@ -0,0 +1,5 @@
+from .async_client import AsyncApollo
+from .client import Apollo
+from .exceptions import ApolloError
+
+__all__ = ["Apollo", "ApolloError", "AsyncApollo"]

papollo/_core.py

@@ -0,0 +1,94 @@
+"""Sans-IO protocol logic shared by the sync and async clients."""
+
+import base64
+import hashlib
+import hmac
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from urllib.parse import quote
+
+import httpx
+
+from .exceptions import ApolloError
+
+DEFAULT_NAMESPACE = "application"
+
+_PROPERTIES_SUFFIX = ".properties"
+
+
+@dataclass(frozen=True, slots=True)
+class Snapshot:
+    release_key: str
+    configurations: Mapping[str, str]
+
+
+def normalize_namespace(name: str) -> str:
+    # Apollo treats "foo" and "foo.properties" as the same namespace.
+    if name.lower().endswith(_PROPERTIES_SUFFIX):
+        return name[: -len(_PROPERTIES_SUFFIX)]
+    return name
+
+
+def sign(timestamp: str, path_with_query: str, secret: str) -> str:
+    message = f"{timestamp}\n{path_with_query}".encode()
+    digest = hmac.new(secret.encode(), message, hashlib.sha1).digest()
+    return base64.b64encode(digest).decode()
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    server_url: str
+    app_id: str
+    cluster: str
+    secret: str | None
+    ip: str | None
+    label: str | None
+    timeout: float | None
+
+    def build_config_request(
+        self,
+        http: httpx.Client | httpx.AsyncClient,
+        namespace: str,
+        release_key: str | None,
+    ) -> httpx.Request:
+        path = "/".join(quote(part, safe="") for part in (self.app_id, self.cluster, namespace))
+        params = {
+            key: value
+            for key, value in (("releaseKey", release_key), ("ip", self.ip), ("label", self.label))
+            if value is not None
+        }
+        request = http.build_request(
+            "GET",
+            f"{self.server_url}/configs/{path}",
+            params=params,
+            timeout=self.timeout if self.timeout is not None else httpx.USE_CLIENT_DEFAULT,
+        )
+        if self.secret is not None:
+            # Sign exactly what goes on the wire so the server side check matches.
+            timestamp = str(int(time.time() * 1000))
+            signature = sign(timestamp, request.url.raw_path.decode("ascii"), self.secret)
+            request.headers["Authorization"] = f"Apollo {self.app_id}:{signature}"
+            request.headers["Timestamp"] = timestamp
+        return request
+
+
+def parse_config_response(response: httpx.Response, namespace: str) -> Snapshot | None:
+    """Return the new snapshot, or None when the server answers 304 Not Modified."""
+    if response.status_code == 304:
+        return None
+    if response.status_code != 200:
+        raise ApolloError(
+            f"failed to fetch namespace {namespace!r}: HTTP {response.status_code}",
+            status_code=response.status_code,
+        )
+    try:
+        body = response.json()
+        release_key = body["releaseKey"]
+        configurations = dict(body["configurations"])
+    except (ValueError, KeyError, TypeError) as exc:
+        raise ApolloError(
+            f"invalid response for namespace {namespace!r}", status_code=response.status_code
+        ) from exc
+    return Snapshot(release_key, MappingProxyType(configurations))

papollo/async_client.py

@@ -0,0 +1,115 @@
+import asyncio
+import sys
+from collections.abc import Mapping
+from types import TracebackType
+from typing import TypeVar, overload
+
+import httpx
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+from ._core import (
+    DEFAULT_NAMESPACE,
+    Settings,
+    Snapshot,
+    normalize_namespace,
+    parse_config_response,
+)
+from .exceptions import ApolloError
+
+T = TypeVar("T")
+
+
+class AsyncApollo:
+    """Asyncio Apollo config client, same API as ``Apollo``.
+
+    A client instance is bound to the event loop it is first used in.
+    """
+
+    def __init__(
+        self,
+        server_url: str,
+        app_id: str,
+        *,
+        cluster: str = "default",
+        secret: str | None = None,
+        ip: str | None = None,
+        label: str | None = None,
+        timeout: float | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._settings = Settings(
+            server_url.rstrip("/"), app_id, cluster, secret, ip, label, timeout
+        )
+        self._http = http_client if http_client is not None else httpx.AsyncClient()
+        self._owns_http = http_client is None
+        self._snapshots: dict[str, Snapshot] = {}
+        self._locks: dict[str, asyncio.Lock] = {}
+
+    @overload
+    async def get(self, key: str, *, namespace: str = DEFAULT_NAMESPACE) -> str | None: ...
+    @overload
+    async def get(self, key: str, default: T, *, namespace: str = DEFAULT_NAMESPACE) -> str | T: ...
+    async def get(
+        self, key: str, default: object = None, *, namespace: str = DEFAULT_NAMESPACE
+    ) -> object:
+        return (await self.namespace(namespace)).get(key, default)
+
+    async def namespace(self, name: str = DEFAULT_NAMESPACE) -> Mapping[str, str]:
+        name = normalize_namespace(name)
+        snapshot = self._snapshots.get(name)
+        if snapshot is None:
+            snapshot = await self._load(name, only_if_missing=True)
+        return snapshot.configurations
+
+    async def refresh(self, name: str | None = None) -> None:
+        """Refetch one namespace, or every loaded namespace when ``name`` is None.
+
+        A namespace that has not been loaded yet is loaded, so this can also be
+        used to preload namespaces at startup. On failure the cached config is
+        kept and the error is raised after all namespaces were tried.
+        """
+        names = [normalize_namespace(name)] if name is not None else list(self._snapshots)
+        results = await asyncio.gather(*(self._load(ns) for ns in names), return_exceptions=True)
+        for result in results:
+            if isinstance(result, BaseException):
+                raise result
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def _load(self, name: str, *, only_if_missing: bool = False) -> Snapshot:
+        async with self._locks.setdefault(name, asyncio.Lock()):
+            current = self._snapshots.get(name)
+            if only_if_missing and current is not None:
+                return current
+            release_key = current.release_key if current is not None else None
+            try:
+                request = self._settings.build_config_request(self._http, name, release_key)
+                response = await self._http.send(request)
+            except (httpx.HTTPError, httpx.InvalidURL) as exc:
+                raise ApolloError(f"failed to fetch namespace {name!r}: {exc}") from exc
+            snapshot = parse_config_response(response, name)
+            if snapshot is None:
+                if current is None:
+                    raise ApolloError(
+                        f"unexpected 304 for unloaded namespace {name!r}", status_code=304
+                    )
+                return current
+            self._snapshots[name] = snapshot
+            return snapshot

papollo/client.py

@@ -0,0 +1,120 @@
+import sys
+import threading
+from collections.abc import Mapping
+from types import TracebackType
+from typing import TypeVar, overload
+
+import httpx
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+from ._core import (
+    DEFAULT_NAMESPACE,
+    Settings,
+    Snapshot,
+    normalize_namespace,
+    parse_config_response,
+)
+from .exceptions import ApolloError
+
+T = TypeVar("T")
+
+
+class Apollo:
+    """Blocking Apollo config client.
+
+    Namespaces are fetched on first access and then served from memory.
+    Call ``refresh()`` to pull the latest release.
+    """
+
+    def __init__(
+        self,
+        server_url: str,
+        app_id: str,
+        *,
+        cluster: str = "default",
+        secret: str | None = None,
+        ip: str | None = None,
+        label: str | None = None,
+        timeout: float | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._settings = Settings(
+            server_url.rstrip("/"), app_id, cluster, secret, ip, label, timeout
+        )
+        self._http = http_client if http_client is not None else httpx.Client()
+        self._owns_http = http_client is None
+        self._snapshots: dict[str, Snapshot] = {}
+        self._locks: dict[str, threading.Lock] = {}
+
+    @overload
+    def get(self, key: str, *, namespace: str = DEFAULT_NAMESPACE) -> str | None: ...
+    @overload
+    def get(self, key: str, default: T, *, namespace: str = DEFAULT_NAMESPACE) -> str | T: ...
+    def get(
+        self, key: str, default: object = None, *, namespace: str = DEFAULT_NAMESPACE
+    ) -> object:
+        return self.namespace(namespace).get(key, default)
+
+    def namespace(self, name: str = DEFAULT_NAMESPACE) -> Mapping[str, str]:
+        name = normalize_namespace(name)
+        snapshot = self._snapshots.get(name)
+        if snapshot is None:
+            snapshot = self._load(name, only_if_missing=True)
+        return snapshot.configurations
+
+    def refresh(self, name: str | None = None) -> None:
+        """Refetch one namespace, or every loaded namespace when ``name`` is None.
+
+        A namespace that has not been loaded yet is loaded, so this can also be
+        used to preload namespaces at startup. On failure the cached config is
+        kept and the error is raised after all namespaces were tried.
+        """
+        names = [normalize_namespace(name)] if name is not None else list(self._snapshots)
+        error: Exception | None = None
+        for ns in names:
+            try:
+                self._load(ns)
+            except Exception as exc:  # noqa: BLE001 raised below after all were tried
+                error = error or exc
+        if error is not None:
+            raise error
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def _load(self, name: str, *, only_if_missing: bool = False) -> Snapshot:
+        with self._locks.setdefault(name, threading.Lock()):
+            current = self._snapshots.get(name)
+            if only_if_missing and current is not None:
+                return current
+            release_key = current.release_key if current is not None else None
+            try:
+                request = self._settings.build_config_request(self._http, name, release_key)
+                response = self._http.send(request)
+            except (httpx.HTTPError, httpx.InvalidURL) as exc:
+                raise ApolloError(f"failed to fetch namespace {name!r}: {exc}") from exc
+            snapshot = parse_config_response(response, name)
+            if snapshot is None:
+                if current is None:
+                    raise ApolloError(
+                        f"unexpected 304 for unloaded namespace {name!r}", status_code=304
+                    )
+                return current
+            self._snapshots[name] = snapshot
+            return snapshot

papollo/exceptions.py

@@ -0,0 +1,6 @@
+class ApolloError(Exception):
+    """Raised when config can not be fetched from Apollo."""
+
+    def __init__(self, message: str, *, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code

papollo-0.1.0.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: papollo
+Version: 0.1.0
+Summary: Python client for Apollo config center, with sync and async support
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: httpx>=0.28
+Requires-Dist: typing-extensions>=4.0 ; python_full_version < '3.11'
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# papollo
+
+Python client for [Apollo](https://github.com/apolloconfig/apollo) config center, with sync and async support.
+
+```python
+from papollo import Apollo
+
+client = Apollo("http://apollo-config:8080", "demo-app")
+
+client.get("timeout")                          # "30", or None if missing
+client.get("timeout", "10")                    # with default
+client.get("db.url", namespace="database")
+client.namespace("app.json")["content"]        # non-properties namespace
+client.refresh()                               # pull latest releases
+```
+
+```python
+from papollo import AsyncApollo
+
+client = AsyncApollo("http://apollo-config:8080", "demo-app")
+
+await client.get("timeout")
+await client.refresh()
+```
+
+A client is meant to live as long as the process, usually as a module level object. It holds an
+httpx connection pool, so call `close()` (or `await client.aclose()`) if you create short lived
+clients. Both also work as context managers. An `AsyncApollo` is bound to the event loop it
+is first used in.
+
+Namespaces are fetched on first access and then served from memory. `refresh()` refetches every
+loaded namespace, and `refresh(name)` also loads a namespace that was not loaded yet, which is handy
+for failing fast at startup. Failures raise `ApolloError` and keep the previously cached config.
+
+Other options: `cluster`, `secret` (access key), `ip` and `label` (gray release), `timeout`, and
+`http_client` to bring your own `httpx.Client` / `httpx.AsyncClient`. When `timeout` is not set, the
+httpx client's own timeout is used. `ip` is not detected automatically, so IP based gray release
+only works when it is set.
+
+## Testing
+
+Most tests run against a real Apollo at `http://localhost:8080`, the rest cover pure functions and
+failures a real server can not produce on demand. The easiest server is the
+[quick start](https://github.com/apolloconfig/apollo-quick-start) all in one jar with an in memory
+H2 database:
+
+```sh
+SPRING_PROFILES_ACTIVE=github,database-discovery,auth SPRING_PROFILES_GROUP_GITHUB=h2 \
+LOGGING_FILE_NAME=/tmp/apollo.log java -jar apollo-all-in-one.jar
+
+uv run pytest
+```
+
+Tests that need Apollo are skipped when it is not reachable. Set `PAPOLLO_REQUIRE_APOLLO=1` to make
+them fail instead, which is what CI should do. The portal at `http://localhost:8070` is used to
+create apps and publish releases. Use `APOLLO_CONFIG_URL`, `APOLLO_PORTAL_URL`,
+`APOLLO_PORTAL_USER`, `APOLLO_PORTAL_PASSWORD` and `APOLLO_ENV` to point elsewhere.

papollo-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+papollo/__init__.py,sha256=7jVHK-L7pmmKjAcEX1rm_rrI175RcPHp0-BAvrELxBg,153
+papollo/_core.py,sha256=34wJuOitjSTiBQdssMl7Wq9hn5ufBzrnSNJFrjmn3gY,3104
+papollo/async_client.py,sha256=BRC6tkvr2Xxni4DQ-zfpG5DNWxODgeIdNseK5vELLCI,4116
+papollo/client.py,sha256=j5jAc1Ix_RN4qyNRcQ06CRM1O9MWAdILoOuEnB6Sw5g,4122
+papollo/exceptions.py,sha256=ODLw1ABRW0RefbGHxHLWnutO-EAT51vfUgge1umSnJg,246
+papollo-0.1.0.dist-info/licenses/LICENSE,sha256=5LtonWQJ4JYxkh2u5scD3oN1kfZ1yGrPG6bTZMvwA_s,1074
+papollo-0.1.0.dist-info/WHEEL,sha256=V5-3dKee3Zs8C4JP6swr6zdqriLsOpItBEQxe6_oWpY,81
+papollo-0.1.0.dist-info/METADATA,sha256=YL0DfhvyGkcymZgKF2Rvujg6UqwTivCZUHKevunxyng,2805
+papollo-0.1.0.dist-info/RECORD,,

papollo-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.18
+Root-Is-Purelib: true
+Tag: py3-none-any

papollo-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 AN Long
+
+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.