apollo-config-client 0.1.0__py3-none-any.whl

apollo_config/__init__.py

@@ -0,0 +1,44 @@
+"""apollo-config-client：一个轻量、同步、贴近 Apollo 官方 HTTP API 的 Python 配置客户端。
+
+特性：
+  - 长轮询（long polling）热更新，秒级生效，带 key 级 diff 回调。
+  - 本地磁盘缓存，Apollo 不可用时应用仍可用上一次配置启动（容灾）。
+  - 访问密钥（Access Key）HMAC-SHA1 签名，兼容 Apollo 1.6+。
+  - 极简依赖：核心仅依赖 `requests`；pydantic 模型与 Oracle 助手为可选 extra。
+
+典型用法::
+
+    from apollo_config import create_config_manager_from_env
+
+    cm = create_config_manager_from_env()
+    cm.get_configs("application")            # 读取普通 namespace
+    cm.get_value("feature_flag", "off")      # 读取单个 key
+
+    @cm.on_namespace_change("database")
+    def _on_db_change(ns, changes):
+        ...  # 配置变更时惰性重建连接池等可变资源
+
+公开 API：
+  - :class:`ApolloClient`：底层 HTTP 客户端（长轮询 / 缓存 / 签名）。
+  - :class:`ConfigManager`：按 namespace 订阅变更的二次封装 + 通用读取。
+  - :func:`create_config_manager`：显式参数创建。
+  - :func:`create_config_manager_from_env`：读环境变量创建（可选 dotenv）。
+"""
+from __future__ import annotations
+
+from apollo_config.client import ApolloClient
+from apollo_config.manager import ConfigManager
+from apollo_config._factory import (
+    create_config_manager,
+    create_config_manager_from_env,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ApolloClient",
+    "ConfigManager",
+    "create_config_manager",
+    "create_config_manager_from_env",
+    "__version__",
+]

apollo_config/_factory.py

@@ -0,0 +1,90 @@
+"""工厂函数：构建 ConfigManager。
+
+库只提供工厂，不提供全局单例（避免与应用框架的生命周期冲突）。
+应用侧（如 Flask / FastAPI 的 settings 模块）可自行决定是否缓存为单例。
+"""
+from __future__ import annotations
+
+import os
+from typing import List, Optional
+
+from apollo_config.manager import ConfigManager
+
+
+def _env_namespaces() -> List[str]:
+    """运行时读取 APOLLO_NAMESPACES，避免模块导入时缓存导致后续设置不生效。"""
+    return [
+        n.strip()
+        for n in os.getenv("APOLLO_NAMESPACES", "application").split(",")
+        if n.strip()
+    ]
+
+
+def create_config_manager(
+    app_id: str,
+    config_url: str,
+    cluster: str = "default",
+    namespaces: Optional[List[str]] = None,
+    env: Optional[str] = None,
+    access_key_secret: Optional[str] = None,
+    cache_dir: str = ".apollo_cache",
+    auto_start: bool = True,
+    poll_timeout: int = 70,
+    request_timeout: int = 5,
+    poll_interval: float = 2.0,
+    max_retry_backoff: float = 30.0,
+) -> ConfigManager:
+    """以显式参数创建 ConfigManager。
+
+    ``auto_start=True``（默认）时立即拉取一次全量配置并启动后台长轮询线程。
+    """
+    mgr = ConfigManager(
+        app_id=app_id,
+        config_url=config_url,
+        cluster=cluster,
+        namespaces=namespaces,
+        env=env,
+        access_key_secret=access_key_secret,
+        cache_dir=cache_dir,
+        poll_timeout=poll_timeout,
+        request_timeout=request_timeout,
+        poll_interval=poll_interval,
+        max_retry_backoff=max_retry_backoff,
+    )
+    if auto_start:
+        mgr.start()
+    return mgr
+
+
+def create_config_manager_from_env(auto_start: bool = True) -> ConfigManager:
+    """从环境变量构建 ConfigManager。
+
+    读取以下环境变量::
+
+        APOLLO_APP_ID           应用 AppId（默认 "apollo-app"）
+        APOLLO_CONFIG_URL       Config Service 地址（默认 http://localhost:8080）
+        APOLLO_CLUSTER          集群（默认 "default"）
+        APOLLO_NAMESPACES       逗号分隔的 namespace 列表（默认 "application"）
+        APOLLO_ENV              环境名（默认 None）
+        APOLLO_ACCESS_KEY_SECRET 访问密钥（默认 None，留空走匿名）
+        APOLLO_CACHE_DIR        本地缓存目录（默认 ".apollo_cache"）
+
+    若已安装 ``python-dotenv``，则自动调用 ``load_dotenv()``（未安装则跳过，不报错）。
+    """
+    try:
+        from dotenv import load_dotenv
+
+        load_dotenv()
+    except ImportError:
+        pass
+
+    return create_config_manager(
+        app_id=os.getenv("APOLLO_APP_ID", "apollo-app"),
+        config_url=os.getenv("APOLLO_CONFIG_URL", "http://localhost:8080"),
+        cluster=os.getenv("APOLLO_CLUSTER", "default"),
+        namespaces=_env_namespaces(),
+        env=os.getenv("APOLLO_ENV"),
+        access_key_secret=os.getenv("APOLLO_ACCESS_KEY_SECRET"),
+        cache_dir=os.getenv("APOLLO_CACHE_DIR", ".apollo_cache"),
+        auto_start=auto_start,
+    )

apollo_config/client.py

@@ -0,0 +1,248 @@
+"""Apollo 配置中心 HTTP 客户端（兼容 Apollo 2.x，含长轮询热更新与本地容灾缓存）。
+
+直接基于 Apollo 开放的 HTTP 接口实现，不依赖任何第三方 Apollo 专用客户端：
+  - 配置拉取: GET  {config_url}/configs/{appId}/{cluster}/{namespace}
+  - 变更通知: GET  {config_url}/notifications/v2  (HTTP 长轮询)
+官方 Java / .NET 客户端底层使用的也是同一套接口，因此本实现可稳定对接 Apollo 2.4.1。
+
+特性：
+  1. 长轮询（long polling）监听配置变更，秒级生效（热更新）。
+  2. 变更回调：拿到 namespace 的 key 级 diff，方便业务层做热重建。
+  3. 本地缓存：每次成功拉取都会落盘，Apollo 不可用时应用仍能用上次配置启动。
+  4. 线程安全的运行时配置快照，供业务直接读取。
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import logging
+import threading
+import time
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+import requests
+from requests import Request
+
+logger = logging.getLogger("apollo")
+
+# 变更回调签名: (namespace: str, changes: Dict[key, {"old":..., "new":...}])
+ChangeCallback = Callable[[str, Dict[str, Any]], None]
+
+
+class ApolloClient:
+    def __init__(
+        self,
+        app_id: str,
+        config_url: str,
+        cluster: str = "default",
+        namespaces: Optional[List[str]] = None,
+        env: Optional[str] = None,
+        client_ip: Optional[str] = None,
+        access_key_secret: Optional[str] = None,
+        cache_dir: str = ".apollo_cache",
+        poll_timeout: int = 70,
+        request_timeout: int = 5,
+        poll_interval: float = 2.0,
+        max_retry_backoff: float = 30.0,
+    ) -> None:
+        self.app_id = app_id
+        self.config_url = config_url.rstrip("/")
+        self.cluster = cluster
+        self.env = env
+        self.namespaces = namespaces or ["application"]
+        self.client_ip = client_ip
+        # 访问密钥（可选）：配了则对所有请求做 HMAC-SHA1 签名，否则走匿名访问。
+        self.access_key_secret = access_key_secret
+        self.cache_dir = Path(cache_dir)
+        self.poll_timeout = poll_timeout          # 略大于 Apollo 服务端长轮询超时(默认 60s)
+        self.request_timeout = request_timeout
+        self.poll_interval = poll_interval
+        self.max_retry_backoff = max_retry_backoff
+
+        # 运行时状态（加锁保证线程安全）
+        self._lock = threading.RLock()
+        self._configs: Dict[str, Dict[str, str]] = {}
+        self._release_keys: Dict[str, str] = {}
+        self._notification_ids: Dict[str, int] = {ns: -1 for ns in self.namespaces}
+
+        self._callbacks: List[ChangeCallback] = []
+        self._running = False
+        self._thread: Optional[threading.Thread] = None
+
+        # 启动前先装载本地缓存，保证 Apollo 不可用时应用仍可启动
+        for ns in self.namespaces:
+            cached = self._load_cache(ns)
+            if cached:
+                with self._lock:
+                    self._configs[ns] = cached.get("configurations", {})
+                    self._release_keys[ns] = cached.get("releaseKey", "")
+                logger.info("从本地缓存恢复 namespace=%s 的配置", ns)
+
+    # ------------------------- 对外 API -------------------------
+    def register_callback(self, cb: ChangeCallback) -> None:
+        """注册全局配置变更回调。"""
+        self._callbacks.append(cb)
+
+    def get_configs(self, namespace: str = "application") -> Dict[str, str]:
+        with self._lock:
+            return dict(self._configs.get(namespace, {}))
+
+    def get_value(self, key: str, default: Optional[str] = None, namespace: str = "application") -> Optional[str]:
+        return self.get_configs(namespace).get(key, default)
+
+    def start(self) -> None:
+        """拉取一次全量配置并启动后台长轮询线程。"""
+        if self._running:
+            return
+        for ns in self.namespaces:
+            try:
+                self._fetch_namespace(ns)
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("启动时拉取 namespace=%s 失败(将使用本地缓存): %s", ns, exc)
+        self._running = True
+        self._thread = threading.Thread(target=self._long_poll, name="apollo-long-poll", daemon=True)
+        self._thread.start()
+        logger.info("Apollo 长轮询已启动, appId=%s namespaces=%s", self.app_id, self.namespaces)
+
+    def stop(self) -> None:
+        self._running = False
+        if self._thread:
+            self._thread.join(timeout=5)
+
+    # ------------------------- 内部实现 -------------------------
+    def _auth_headers(self, path_with_query: str) -> Dict[str, str]:
+        """Apollo 1.6+ 客户端访问密钥签名。
+
+        明文 = 毫秒时间戳 + "\\n" + pathWithQuery；HMAC-SHA1 + Base64。
+        通过 Timestamp / Authorization 两个头传递（无独立 Signature 头）。
+        未配置 access_key_secret 时返回空 dict（匿名访问）。
+        """
+        if not self.access_key_secret:
+            return {}
+        timestamp = str(int(time.time() * 1000))
+        plain = f"{timestamp}\n{path_with_query}"
+        digest = hmac.new(
+            self.access_key_secret.encode("utf-8"), plain.encode("utf-8"), hashlib.sha1
+        ).digest()
+        signature = base64.b64encode(digest).decode("utf-8")
+        return {
+            "Timestamp": timestamp,
+            "Authorization": f"Apollo {self.app_id}:{signature}",
+        }
+
+    def _signed_get(self, url: str, params: Dict[str, Any], timeout: int) -> "requests.Response":
+        """构造带签名的 GET 请求。
+
+        用 Request.prepare() 得到最终 pathWithQuery，确保签名用的 path 与
+        实际发出的 URL 完全一致（含查询串的编码）。
+        """
+        prepared = Request("GET", url, params=params).prepare()
+        headers = self._auth_headers(prepared.path_url)
+        return requests.get(prepared.url, headers=headers, timeout=timeout)
+
+    def _fetch_namespace(self, namespace: str) -> Dict[str, Any]:
+        url = f"{self.config_url}/configs/{self.app_id}/{self.cluster}/{namespace}"
+        params: Dict[str, Any] = {}
+        release_key = self._release_keys.get(namespace)
+        if release_key:
+            params["releaseKey"] = release_key
+        if self.client_ip:
+            params["ip"] = self.client_ip
+
+        resp = self._signed_get(url, params, self.request_timeout)
+        resp.raise_for_status()
+        data = resp.json()
+        new_configs = data.get("configurations", {})
+        new_release = data.get("releaseKey", "")
+
+        with self._lock:
+            old_configs = self._configs.get(namespace, {})
+            changes = self._diff(old_configs, new_configs)
+            self._configs[namespace] = new_configs
+            self._release_keys[namespace] = new_release
+
+        self._save_cache(namespace, new_release, new_configs)
+
+        if changes:
+            logger.info("namespace=%s 配置变更: %s", namespace, list(changes.keys()))
+            for cb in self._callbacks:
+                try:
+                    cb(namespace, changes)
+                except Exception as exc:  # noqa: BLE001
+                    logger.exception("配置变更回调执行失败: %s", exc)
+        return changes
+
+    @staticmethod
+    def _diff(old: Dict[str, str], new: Dict[str, str]) -> Dict[str, Dict[str, Any]]:
+        changes: Dict[str, Dict[str, Any]] = {}
+        for k in set(old) | set(new):
+            ov, nv = old.get(k), new.get(k)
+            if ov != nv:
+                changes[k] = {"old": ov, "new": nv}
+        return changes
+
+    def _long_poll(self) -> None:
+        backoff = self.poll_interval
+        while self._running:
+            try:
+                notifications = [
+                    {"namespaceName": ns, "notificationId": self._notification_ids.get(ns, -1)}
+                    for ns in self.namespaces
+                ]
+                url = f"{self.config_url}/notifications/v2"
+                params = {
+                    "appId": self.app_id,
+                    "cluster": self.cluster,
+                    "notifications": json.dumps(notifications),
+                }
+                resp = self._signed_get(url, params, self.poll_timeout)
+                if resp.status_code == 304:
+                    continue
+                resp.raise_for_status()
+                items = resp.json() or []
+                if not items:
+                    backoff = self.poll_interval
+                    continue
+                for item in items:
+                    ns = item["namespaceName"]
+                    nid = item["notificationId"]
+                    if nid > self._notification_ids.get(ns, -1):
+                        self._notification_ids[ns] = nid
+                        try:
+                            self._fetch_namespace(ns)
+                        except Exception as exc:  # noqa: BLE001
+                            logger.warning("长轮询触发后拉取 namespace=%s 失败: %s", ns, exc)
+                backoff = self.poll_interval
+            except requests.exceptions.Timeout:
+                # 长轮询超时(服务端 60s 无变更)是正常现象，立即继续下一轮
+                continue
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("Apollo 长轮询异常, %ss 后重试: %s", backoff, exc)
+                time.sleep(backoff)
+                backoff = min(backoff * 2, self.max_retry_backoff)
+
+    # ------------------------- 本地缓存 -------------------------
+    def _cache_path(self, namespace: str) -> Path:
+        d = self.cache_dir / self.app_id / (self.env or "default")
+        d.mkdir(parents=True, exist_ok=True)
+        safe = namespace.replace("/", "_")
+        return d / f"{safe}.json"
+
+    def _save_cache(self, namespace: str, release_key: str, configs: Dict[str, str]) -> None:
+        try:
+            payload = {"releaseKey": release_key, "configurations": configs}
+            self._cache_path(namespace).write_text(json.dumps(payload, ensure_ascii=False), encoding="utf-8")
+        except OSError as exc:  # noqa: BLE001
+            logger.warning("写入本地缓存失败 namespace=%s: %s", namespace, exc)
+
+    def _load_cache(self, namespace: str) -> Optional[Dict[str, Any]]:
+        try:
+            p = self._cache_path(namespace)
+            if p.exists():
+                return json.loads(p.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:  # noqa: BLE001
+            logger.warning("读取本地缓存失败 namespace=%s: %s", namespace, exc)
+        return None

apollo_config/contrib.py

@@ -0,0 +1,145 @@
+"""可选领域辅助（需要对应的 extra 依赖）。
+
+安装方式::
+
+    pip install apollo-config-client[models]   # DatabaseConfig / LdapConfig（依赖 pydantic）
+    pip install apollo-config-client[oracle]   # init_oracle_thick_mode（依赖 oracledb）
+    pip install apollo-config-client[all]      # 以上全部
+
+核心库（``apollo_config``）刻意不依赖这些领域模型；这里仅作为「拿来即用」的参考实现，
+你完全可以用自己的项目模型调用 ``ConfigManager.get_typed(namespace, YourModel)``。
+"""
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Dict
+
+try:
+    from pydantic import BaseModel, ConfigDict
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "apollo_config.contrib 的模型需要 pydantic，请执行 "
+        "pip install apollo-config-client[models]"
+    ) from exc
+
+logger = logging.getLogger("apollo.contrib")
+
+
+class DatabaseConfig(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    # 数据库类型 / 驱动：默认 Oracle 11g + python-oracledb
+    dialect: str = "oracle"        # oracle / postgresql / mysql
+    driver: str = "oracledb"       # Oracle: oracledb(推荐) / cx_oracle
+    host: str
+    port: int = 1521               # Oracle 默认监听端口 1521
+    username: str
+    password: str
+    # Oracle 连接标识：service_name 与 sid 二选一（11g 常用 service_name）
+    service_name: str | None = None
+    sid: str | None = None
+    pool_size: int = 10
+    echo: bool = False
+
+    @classmethod
+    def from_namespace(cls, configs: Dict[str, Any]) -> "DatabaseConfig":
+        # Apollo 所有值均为字符串，pydantic 在 lax 模式下自动做类型转换
+        return cls.model_validate(dict(configs))
+
+    def connection_url(self, redact: bool = False) -> str:
+        """生成 SQLAlchemy 连接串；redact=True 时隐藏密码（用于日志输出）。"""
+        pwd = "***" if redact else self.password
+        if self.dialect == "oracle":
+            base = f"oracle+{self.driver}://{self.username}:{pwd}@{self.host}:{self.port}"
+            if self.service_name:
+                return f"{base}/?service_name={self.service_name}"
+            if self.sid:
+                return f"{base}/{self.sid}"
+            return base
+        if self.dialect == "postgresql":
+            db = self.service_name or self.sid or ""
+            return f"postgresql+psycopg2://{self.username}:{pwd}@{self.host}:{self.port}/{db}"
+        if self.dialect == "mysql":
+            db = self.service_name or ""
+            return f"mysql+pymysql://{self.username}:{pwd}@{self.host}:{self.port}/{db}"
+        raise ValueError(f"unsupported dialect: {self.dialect}")
+
+    def public_dict(self) -> Dict[str, Any]:
+        """对外暴露配置时脱敏（不返回密码）。"""
+        return {
+            "dialect": self.dialect,
+            "driver": self.driver,
+            "host": self.host,
+            "port": self.port,
+            "username": self.username,
+            "service_name": self.service_name,
+            "sid": self.sid,
+            "pool_size": self.pool_size,
+            "echo": self.echo,
+        }
+
+
+class LdapConfig(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    server: str
+    port: int = 389
+    use_ssl: bool = False
+    bind_dn: str
+    bind_password: str
+    base_dn: str
+    user_search_base: str
+    user_search_filter: str = "(uid={user})"
+    timeout: int = 5
+
+    @classmethod
+    def from_namespace(cls, configs: Dict[str, Any]) -> "LdapConfig":
+        return cls.model_validate(dict(configs))
+
+    def public_dict(self) -> Dict[str, Any]:
+        return {
+            "server": self.server,
+            "port": self.port,
+            "use_ssl": self.use_ssl,
+            "bind_dn": self.bind_dn,
+            "base_dn": self.base_dn,
+            "user_search_base": self.user_search_base,
+            "user_search_filter": self.user_search_filter,
+            "timeout": self.timeout,
+        }
+
+
+def init_oracle_thick_mode(lib_dir: str | None = None) -> None:
+    """启用 Oracle thick 模式；重复调用安全（第二次直接跳过）。
+
+    重要：Oracle 11g 无法使用 python-oracledb 的 thin 模式（thin 要求 Oracle DB ≥ 12.1），
+    必须在创建任何连接前用 Instant Client 启用 thick 模式。
+
+    Instant Client 路径通过环境变量 ``ORACLE_INSTANT_CLIENT`` 指定，例如::
+
+        /opt/lib/instantclient-basiclite-arm-23.26.1.0.0
+    """
+    _INITIALIZED = getattr(init_oracle_thick_mode, "_initialized", False)
+    if _INITIALIZED:
+        return
+
+    try:
+        import oracledb
+    except ImportError:
+        logger.warning("未安装 oracledb，跳过 Oracle 驱动初始化（连接 11g 将失败）")
+        init_oracle_thick_mode._initialized = True
+        return
+
+    lib_dir = lib_dir or os.getenv("ORACLE_INSTANT_CLIENT")
+    if not lib_dir:
+        logger.info("未配置 ORACLE_INSTANT_CLIENT，使用 oracledb thin 模式（仅支持 Oracle >= 12.1，11g 无法连接）")
+        init_oracle_thick_mode._initialized = True
+        return
+
+    try:
+        oracledb.init_oracle_client(lib_dir=lib_dir)
+        logger.info("Oracle thick 模式已启用, lib_dir=%s", lib_dir)
+    except Exception as exc:  # 已初始化会抛 DPI-1049，忽略即可
+        logger.info("Oracle 驱动初始化跳过(可能已初始化): %s", exc)
+    init_oracle_thick_mode._initialized = True

apollo_config/manager.py

@@ -0,0 +1,94 @@
+"""ConfigManager：在 ApolloClient 之上做二次封装。
+
+职责：
+  - 聚合多个 namespace 的 ApolloClient；
+  - 提供「按 namespace 订阅变更」的回调（装饰器风格）；
+  - 提供通用的配置读取；领域模型（如 DatabaseConfig）通过 get_typed() 接入，
+    库本身不耦合任何业务模型，保持核心仅依赖 requests。
+"""
+from __future__ import annotations
+
+import logging
+from collections import defaultdict
+from typing import Any, Callable, Dict, List, Type, TypeVar
+
+from apollo_config.client import ApolloClient
+
+logger = logging.getLogger("apollo.config")
+
+# 回调签名: (namespace: str, changes: Dict[key, {"old":..., "new":...}])
+NamespaceCallback = Callable[[str, Dict], None]
+T = TypeVar("T")
+
+
+class ConfigManager:
+    def __init__(
+        self,
+        app_id: str,
+        config_url: str,
+        cluster: str = "default",
+        namespaces: List[str] | None = None,
+        env: str | None = None,
+        access_key_secret: str | None = None,
+        cache_dir: str = ".apollo_cache",
+        poll_timeout: int = 70,
+        request_timeout: int = 5,
+        poll_interval: float = 2.0,
+        max_retry_backoff: float = 30.0,
+    ) -> None:
+        self._client = ApolloClient(
+            app_id=app_id,
+            config_url=config_url,
+            cluster=cluster,
+            namespaces=namespaces,
+            env=env,
+            access_key_secret=access_key_secret,
+            cache_dir=cache_dir,
+            poll_timeout=poll_timeout,
+            request_timeout=request_timeout,
+            poll_interval=poll_interval,
+            max_retry_backoff=max_retry_backoff,
+        )
+        self._ns_callbacks: Dict[str, List[NamespaceCallback]] = defaultdict(list)
+        self._client.register_callback(self._dispatch)
+
+    # ------------------------- 生命周期 -------------------------
+    def start(self) -> None:
+        self._client.start()
+
+    def stop(self) -> None:
+        self._client.stop()
+
+    # ------------------------- 变更订阅 -------------------------
+    def _dispatch(self, namespace: str, changes: dict) -> None:
+        for cb in self._ns_callbacks.get(namespace, []):
+            try:
+                cb(namespace, changes)
+            except Exception as exc:  # noqa: BLE001
+                logger.exception("namespace=%s 变更回调失败: %s", namespace, exc)
+
+    def on_namespace_change(self, namespace: str):
+        """装饰器 / 注册器：订阅某个 namespace 的变更。回调签名 (namespace, changes)。"""
+        def decorator(cb: NamespaceCallback) -> NamespaceCallback:
+            self._ns_callbacks[namespace].append(cb)
+            return cb
+        return decorator
+
+    # ------------------------- 通用读取 -------------------------
+    def get_value(self, key: str, default: str | None = None, namespace: str = "application") -> str | None:
+        return self._client.get_value(key, default, namespace)
+
+    def get_configs(self, namespace: str = "application") -> Dict[str, str]:
+        return self._client.get_configs(namespace)
+
+    def get_typed(self, namespace: str, model_cls: Type[T]) -> T:
+        """用任意模型类（如 pydantic.BaseModel 子类）解析某个 namespace 的配置。
+
+        例::
+
+            cfg = cm.get_typed("database", DatabaseConfig)
+
+        库不绑定任何模型库：只要 ``model_cls`` 提供 ``model_validate(dict)`` 类方法即可
+        （pydantic v2 天然满足）。
+        """
+        return model_cls.model_validate(dict(self.get_configs(namespace)))

apollo_config_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: apollo-config-client
+Version: 0.1.0
+Summary: A lightweight, synchronous Apollo config-center client: long-polling hot reload, local cache failover, and access-key HMAC signing. Only depends on requests.
+Project-URL: Homepage, https://github.com/Jiafan/apollo-config-client
+Project-URL: Repository, https://github.com/Jiafan/apollo-config-client
+Project-URL: Documentation, https://github.com/Jiafan/apollo-config-client#readme
+Author: Jiafan
+License: MIT
+License-File: LICENSE
+Keywords: apollo,config,configuration,hot-reload,long-polling
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.31.0
+Provides-Extra: all
+Requires-Dist: oracledb>=2.0.0; extra == 'all'
+Requires-Dist: pydantic>=2.5.0; extra == 'all'
+Requires-Dist: python-dotenv>=1.0.0; extra == 'all'
+Provides-Extra: dotenv
+Requires-Dist: python-dotenv>=1.0.0; extra == 'dotenv'
+Provides-Extra: models
+Requires-Dist: pydantic>=2.5.0; extra == 'models'
+Provides-Extra: oracle
+Requires-Dist: oracledb>=2.0.0; extra == 'oracle'
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Requires-Dist: requests-mock>=1.11.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# apollo-config-client
+
+一个**轻量、同步、贴近 Apollo 官方 HTTP API** 的 Python 配置中心客户端。
+
+> 直接基于 Apollo 开放的 HTTP 接口实现，不依赖任何第三方 Apollo 专用客户端，版本兼容性最好，且对热更新逻辑完全可控。官方 Java / .NET 客户端底层使用的也是同一套接口，可稳定对接 Apollo 1.6 – 2.4.1。
+
+## 特性
+
+| 能力 | 说明 |
+|------|------|
+| 长轮询热更新 | 后台守护线程长轮询 `notifications/v2`，配置发布后**秒级生效**，并给出 key 级 diff |
+| 本地容灾缓存 | 每次成功拉取都落盘；Apollo 全部不可用时，应用仍可用上一次的配置启动 |
+| 访问密钥签名 | 兼容 Apollo 1.6+ 的 `Access Key` HMAC-SHA1 签名（匿名访问同样支持） |
+| 类型化读取 | `get_typed(namespace, Model)` 用任意模型类（如 pydantic）解析配置 |
+| 极简依赖 | **核心仅依赖 `requests`**；pydantic 模型与 Oracle 助手都是可选 extra |
+
+## 安装
+
+```bash
+pip install apollo-config-client            # 核心（仅 requests）
+pip install apollo-config-client[models]    # + pydantic 领域模型 DatabaseConfig / LdapConfig
+pip install apollo-config-client[oracle]    # + init_oracle_thick_mode 助手
+pip install apollo-config-client[all]       # 以上全部
+```
+
+> 发布前请先在 https://pypi.org 确认包名 `apollo-config-client` 可用；若被占用，备选 `apolloc` / `apollo-config`。
+
+## 快速开始
+
+```python
+from apollo_config import create_config_manager_from_env
+
+# 读环境变量 APOLLO_APP_ID / APOLLO_CONFIG_URL / APOLLO_NAMESPACES ...
+cm = create_config_manager_from_env()
+
+# 普通读取
+cm.get_configs("application")
+cm.get_value("feature_flag", "off")
+
+# 订阅 namespace 变更，配置一发布即刻拿到 key 级 diff
+@cm.on_namespace_change("database")
+def _on_db_change(namespace, changes):
+    # 这里只做「置空 / 标记失效」等轻量操作，
+    # 真正的资源重建放到请求路径上惰性执行（避免回调里做重 IO）
+    rebuild_connection_pool_lazily()
+```
+
+显式参数创建（不走环境变量）：
+
+```python
+from apollo_config import create_config_manager
+
+cm = create_config_manager(
+    app_id="my-app",
+    config_url="http://apollo-config-service:8080",
+    namespaces=["application", "database"],
+    access_key_secret="38fdae497a324263a5ad81aa387deee3",  # 可选
+)
+```
+
+### 用 pydantic 模型读取（可选 extra `[models]`）
+
+```python
+from apollo_config.contrib import DatabaseConfig
+
+cfg = cm.get_typed("database", DatabaseConfig)
+engine = create_engine(cfg.connection_url(), pool_size=cfg.pool_size)
+```
+
+## 设计要点
+
+1. **直接调用 Apollo 开放 HTTP API**（官方客户端同款接口）：
+   - 配置拉取：`GET {config_url}/configs/{appId}/{cluster}/{namespace}`
+   - 变更通知：`GET {config_url}/notifications/v2`（HTTP 长轮询，秒级生效）
+2. **热更新机制**：后台守护线程长轮询 `notifications/v2`，一旦 Apollo 发布新配置，
+   客户端拉取最新值并计算 key 级 diff，触发业务注册的回调。
+3. **本地容灾缓存**：每次成功拉取都会落盘到缓存目录；即使 Apollo 全部不可用，
+   应用也能用上一次的配置正常启动。
+4. **访问密钥签名**：配置 `access_key_secret` 后，对 `configs` 与 `notifications/v2`
+   两类请求统一做 HMAC-SHA1 加签；留空则走匿名访问，行为完全一致。
+
+## 环境变量（用于 `create_config_manager_from_env`）
+
+| 变量 | 说明 | 默认 |
+|------|------|------|
+| `APOLLO_APP_ID` | 应用 AppId | `apollo-app` |
+| `APOLLO_CONFIG_URL` | Config Service 地址（非 Portal 的 8070） | `http://localhost:8080` |
+| `APOLLO_CLUSTER` | 集群 | `default` |
+| `APOLLO_NAMESPACES` | 逗号分隔的 namespace | `application` |
+| `APOLLO_ENV` | 环境名 | 空 |
+| `APOLLO_ACCESS_KEY_SECRET` | 访问密钥（可选） | 空 |
+| `APOLLO_CACHE_DIR` | 本地缓存目录 | `.apollo_cache` |
+| `ORACLE_INSTANT_CLIENT` | Oracle Instant Client 路径（仅 11g 需要） | 空 |
+
+## 示例应用
+
+`examples/` 下提供 Flask / FastAPI 两个完整示例（DB 连接池热重建）：
+
+```bash
+cd examples
+pip install -r requirements.txt        # 会以 editable 方式安装本库
+cp ../.env.example .env                # 按需修改 Apollo 地址 / AppId
+python flask_app.py                    # http://localhost:5000/config/database
+# 或 python fastapi_app.py
+```
+
+## 与 flask_apollo_lab 的关系
+
+本项目（库）原是从 `flask_apollo_lab` 中抽离出的通用部分（`apollo/` + `config/`）。
+`flask_apollo_lab` 作为**消费方 / dogfooding 示例**保留，可改为 `pip install apollo-config-client`
+并 `from apollo_config import ...`，从而把"拷贝两个包"变成一行导入。
+
+## 生产建议
+
+- **脱敏**：`password` / `bind_password` 等建议标记为 Apollo「私密配置」，对外接口务必脱敏（见 `public_dict()`）。
+- **优雅关闭**：进程退出前调用 `config_manager.stop()` 停止长轮询线程（示例在 `settings.py` 用 `atexit` 注册）。
+- **回调要快**：变更回调里只做「置空 / 标记失效」这类轻量操作，真正的重建放到请求路径上惰性执行。
+- **本地缓存目录** `.apollo_cache/` 应加入 `.gitignore`，不要提交到代码库。
+
+## Roadmap
+
+- [ ] 多 Config Service 端点 / HA 故障转移（当前为单 `config_url`）
+- [ ] 可选的 async wrapper（基于 `httpx` 或线程池），不进核心
+- [ ] 配置变更事件的同步原语（如 `watch()` 返回最新值的上下文管理器）
+
+## License
+
+[MIT](LICENSE)

apollo_config_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+apollo_config/__init__.py,sha256=bccTtk1XLPanjdTnuVtilQVNlzPNheRmaOeqeZfIiM8,1611
+apollo_config/_factory.py,sha256=3pJxqwPtmrdU58CMcsook0wCbr6R2ZWwWMh3BSAkRi8,3052
+apollo_config/client.py,sha256=d1XJ2TwpIfvhkppj-lfTaoeNgL1JFLw6Vj6uojvirXc,10751
+apollo_config/contrib.py,sha256=95KBzv2dnSI2WRpF8iLSE30nXiXXPgp54SM0_VSXVCE,5472
+apollo_config/manager.py,sha256=GXQoXnDI6AzNlTQJSFBCGsFYal81oiFOKVlmX4U40ck,3561
+apollo_config_client-0.1.0.dist-info/METADATA,sha256=7lMbqexWRKcFMozOGCkzij1VDi982JEnJcZd5FQS6WQ,7246
+apollo_config_client-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+apollo_config_client-0.1.0.dist-info/licenses/LICENSE,sha256=vZ7MRjFRVZPFAsEkrkxm7eG9ykCpHrWjHBggw1ubgeM,1063
+apollo_config_client-0.1.0.dist-info/RECORD,,

apollo_config_client-0.1.0.dist-info/WHEEL

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

apollo_config_client-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jiafan
+
+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.