dwy-notify 0.1.0__py3-none-any.whl

dwy_notify/__init__.py

@@ -0,0 +1,6 @@
+"""独立多目标通知；公开 API 仅包含本包拥有的配置、结果和发送器。"""
+
+from .models import NotificationConfig, NotificationDelivery, NotificationResult
+from .notifier import Notifier
+
+__all__ = ["NotificationConfig", "NotificationDelivery", "NotificationResult", "Notifier"]

dwy_notify/_logging.py

@@ -0,0 +1,21 @@
+"""只过滤当前通知工作线程的原始 HTTP 调试日志，不改变宿主日志级别。"""
+
+import logging
+from contextvars import ContextVar
+
+notification_http_active: ContextVar[bool] = ContextVar("dwy_notify_http_active", default=False)
+
+
+class _NotificationHTTPFilter(logging.Filter):
+    def filter(self, record: logging.LogRecord) -> bool:
+        return not notification_http_active.get()
+
+
+# urllib3 会在 DEBUG 输出包含凭据的请求路径；过滤器只作用于通知的同步 HTTP 区间。
+for _name in (
+    "urllib3.connectionpool",
+    "urllib3.util.retry",
+    "requests.packages.urllib3.connectionpool",
+    "requests.packages.urllib3.util.retry",
+):
+    logging.getLogger(_name).addFilter(_NotificationHTTPFilter())

dwy_notify/_plugins.py

@@ -0,0 +1,127 @@
+"""固定版本 Apprise 的窄适配；保留上游解析、分段和 Discord 消息构造。"""
+
+import importlib
+import logging
+from urllib.parse import urlsplit, urlunsplit
+
+import requests
+from apprise import AppriseAsset, NotifyFormat
+from apprise.plugins import N_MGR
+from apprise.plugins.discord import NotifyDiscord
+from apprise.plugins.wecombot import NotifyWeComBot
+
+from . import _transport
+
+
+class _QuietLogger(logging.Logger):
+    def trace(self, *args, **kwargs):
+        pass
+
+
+# 插件调试日志会包含 URL 和正文；只隔离本包子类，不能修改宿主的 logger。
+_quiet_logger = _QuietLogger("dwy_notify.apprise", level=100)
+_quiet_logger.propagate = False
+_quiet_logger.addHandler(logging.NullHandler())
+
+
+class _Discord(NotifyDiscord):
+    logger = _quiet_logger
+
+    def _send(self, payload, attach=None, params=None, **kwargs):
+        if self.outcome.get("error_code"):
+            return False
+        payload.pop("allow_mentions", None)
+        payload["allowed_mentions"] = {"parse": []}
+        payload["flags"] = payload.get("flags", 0) | 4
+        response = _transport.send(
+            self,
+            f"{self.notify_url}/{self.webhook_id}/{self.webhook_token}",
+            payload,
+            params={**(params or {}), "wait": "true"},
+        )
+        if response is None:
+            return False
+        try:
+            data = response.json()
+        except ValueError:
+            data = None
+        message_id = data.get("id") if isinstance(data, dict) else None
+        if (
+            not isinstance(message_id, str)
+            or not 1 <= len(message_id) <= 128
+            or not message_id.isascii()
+            or not message_id.isdecimal()
+        ):
+            self.outcome = {"error_code": "invalid_response"}
+            return False
+        self.outcome = {"message_id": message_id}
+        return True
+
+
+class _WeComBot(NotifyWeComBot):
+    logger = _quiet_logger
+
+    def send(self, body, title="", **kwargs):
+        response = _transport.send(
+            self,
+            self.api_url,
+            {"msgtype": "text", "text": {"content": f"{title}\r\n{body}" if title else body}},
+        )
+        if response is None:
+            return False
+        try:
+            data = response.json()
+        except ValueError:
+            data = None
+        if not isinstance(data, dict) or type(data.get("errcode")) is not int or data["errcode"] != 0:
+            self.outcome = {"error_code": "provider_error"}
+            return False
+        return True
+
+
+def create_plugin(url: str, timeout: float):
+    parsed = urlsplit(url)
+    if parsed.scheme == "https" and parsed.hostname in {"discord.com", "discordapp.com"}:
+        parts = parsed.path.strip("/").split("/")
+        if len(parts) == 4 and parts[:2] == ["api", "webhooks"] and not parsed.username:
+            url = urlunsplit(("discord", parts[2], "/" + parts[3], parsed.query, ""))
+            parsed = urlsplit(url)
+    if parsed.scheme not in N_MGR:
+        raise ValueError("invalid_target")
+    base = N_MGR[parsed.scheme]
+    if base.__module__.split(".")[2] in {"fluxer", "revolt", "matrix", "sparkpost", "sendpulse"}:
+        # 这些固定版本插件有绕过 retry=0 的内部重试，不能兑现单次发送约定。
+        raise ValueError("unsupported_transport")
+    # 只接受上游基于 requests 的 HTTPS 渠道；SMTP、本地命令等不共享 HTTP 安全约束。
+    if getattr(importlib.import_module(base.__module__), "requests", None) is not requests:
+        raise ValueError("unsupported_transport")
+    protocols = base.secure_protocol
+    if isinstance(protocols, str):
+        protocols = (protocols,)
+    if not protocols or parsed.scheme not in protocols or not base.enabled:
+        raise ValueError("unsupported_transport")
+    plugin_type = {NotifyDiscord: _Discord, NotifyWeComBot: _WeComBot}.get(base)
+    if plugin_type is None:
+        plugin_type = type(f"_Safe{base.__name__}", (base,), {"logger": _quiet_logger})
+    try:
+        options = plugin_type.parse_url(url)
+        if options is None:
+            raise ValueError("invalid_target")
+        options.update(
+            verify=True,
+            redirect=False,
+            retry=0,
+            optional=False,
+            cto=timeout,
+            rto=timeout,
+            secure=True,
+            asset=AppriseAsset(secure_logging=True, http_redirects=False),
+        )
+        plugin = plugin_type(**options)
+    except (TypeError, ValueError, AttributeError):
+        raise ValueError("invalid_target") from None
+    if not plugin.enabled:
+        raise ValueError("invalid_target")
+    if isinstance(plugin, _Discord):
+        plugin.notify_format = NotifyFormat.TEXT
+    return plugin

dwy_notify/_transport.py

@@ -0,0 +1,58 @@
+"""Discord / 企业微信的单次 HTTP 边界，便于宿主测试替换。"""
+
+import math
+from typing import Any
+
+import requests
+
+
+def post(url: str, **kwargs: Any) -> requests.Response:
+    """执行一次 HTTP POST；安全参数由包内适配器显式传入。"""
+    return requests.post(url, **kwargs)
+
+
+def retry_after(response: requests.Response) -> float | None:
+    try:
+        value = response.json().get("retry_after", response.headers.get("Retry-After"))
+    except (ValueError, AttributeError):
+        value = response.headers.get("Retry-After")
+    if isinstance(value, bool):
+        return None
+    try:
+        seconds = float(value)
+    except (TypeError, ValueError):
+        return None
+    return seconds if math.isfinite(seconds) and seconds >= 0 else None
+
+
+def send(plugin: Any, url: str, payload: dict, *, params: dict | None = None) -> requests.Response | None:
+    try:
+        response = post(
+            url,
+            json=payload,
+            params=params,
+            headers={"User-Agent": plugin.app_id},
+            verify=True,
+            timeout=plugin.socket_read_timeout,
+            allow_redirects=False,
+        )
+    except requests.Timeout:
+        plugin.outcome = {"error_code": "timeout"}
+        return None
+    except requests.RequestException:
+        plugin.outcome = {"error_code": "network_error"}
+        return None
+
+    if response.status_code == 429:
+        plugin.outcome = {"error_code": "rate_limited", "retry_after": retry_after(response)}
+        return None
+    if 300 <= response.status_code < 400:
+        plugin.outcome = {"error_code": "redirect_rejected", "permanent": True}
+        return None
+    if not 200 <= response.status_code < 300:
+        plugin.outcome = {
+            "error_code": "http_error",
+            "permanent": 400 <= response.status_code < 500 and response.status_code != 408,
+        }
+        return None
+    return response

dwy_notify/models.py

@@ -0,0 +1,52 @@
+"""通知包拥有的配置与结果契约，不向调用方泄漏 Apprise 类型。"""
+
+from dataclasses import dataclass
+
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, field_validator
+
+
+class NotificationConfig(BaseModel):
+    """显式目标映射；URL 可含凭据，不应解密后写入日志或错误。"""
+
+    model_config = ConfigDict(frozen=True, extra="forbid", hide_input_in_errors=True)
+
+    targets: dict[str, SecretStr] = Field(min_length=1)
+    timeout_seconds: float = Field(default=10, gt=0, le=30, strict=True, allow_inf_nan=False)
+
+    @field_validator("targets")
+    @classmethod
+    def validate_targets(cls, targets: dict[str, SecretStr]) -> dict[str, SecretStr]:
+        if any(not name.strip() or not url.get_secret_value().strip() for name, url in targets.items()):
+            raise ValueError("empty_target")
+        return targets
+
+
+@dataclass(frozen=True)
+class NotificationDelivery:
+    """单个命名目标的结果；错误码固定且不含第三方响应或请求内容。"""
+
+    target: str
+    success: bool
+    message_id: str | None = None
+    error_code: str | None = None
+    retry_after: float | None = None
+    permanent: bool = False
+
+
+@dataclass(frozen=True)
+class NotificationResult:
+    """按请求目标顺序保留结果；failed 可直接作为下次 send 的 targets。"""
+
+    deliveries: tuple[NotificationDelivery, ...]
+
+    @property
+    def success(self) -> bool:
+        return bool(self.deliveries) and all(delivery.success for delivery in self.deliveries)
+
+    @property
+    def succeeded(self) -> tuple[str, ...]:
+        return tuple(delivery.target for delivery in self.deliveries if delivery.success)
+
+    @property
+    def failed(self) -> tuple[str, ...]:
+        return tuple(delivery.target for delivery in self.deliveries if not delivery.success)

dwy_notify/notifier.py

@@ -0,0 +1,83 @@
+"""同步 SDK 在线程中执行，锁只覆盖同一实例内的同一个目标。"""
+
+import asyncio
+import hashlib
+import threading
+from collections.abc import Sequence
+
+import requests
+
+from ._logging import notification_http_active
+from ._plugins import create_plugin
+from .models import NotificationConfig, NotificationDelivery, NotificationResult
+
+
+class Notifier:
+    """显式配置的异步通知器；不读环境变量、不重试、不记录 URL 或正文。
+
+    取消等待会向调用方传播；已开始的同步请求由超时结束，同目标锁直到请求结束才释放。
+    """
+
+    def __init__(self, config: NotificationConfig):
+        """固定目标与安全配置；无效 URL 只抛出固定错误，不回显凭据。"""
+        self._plugins = {
+            name: create_plugin(url.get_secret_value(), config.timeout_seconds)
+            for name, url in config.targets.items()
+        }
+        self._fingerprints = {
+            name: hashlib.sha256(url.get_secret_value().encode()).hexdigest()
+            for name, url in config.targets.items()
+        }
+        self._locks = {name: threading.Lock() for name in self._plugins}
+
+    @property
+    def targets(self) -> tuple[str, ...]:
+        return tuple(self._plugins)
+
+    def target_fingerprint(self, name: str) -> str:
+        """返回目标 URL 的 SHA-256 摘要，用于队列检测接收方配置变更。"""
+        return self._fingerprints[name]
+
+    async def send(
+        self, body: str, *, title: str = "", targets: Sequence[str] | None = None
+    ) -> NotificationResult:
+        """发送到全部或指定目标；结果保留顺序，未知或重复目标在网络调用前报错。"""
+        if not isinstance(body, str) or not body.strip():
+            raise ValueError("invalid_body")
+        if not isinstance(title, str):
+            raise ValueError("invalid_title")
+        if targets is not None and (isinstance(targets, (str, bytes)) or not targets):
+            raise ValueError("invalid_targets")
+        selected = self.targets if targets is None else tuple(targets)
+        if any(not isinstance(name, str) for name in selected):
+            raise ValueError("invalid_targets")
+        if any(name not in self._plugins for name in selected):
+            raise ValueError("unknown_target")
+        if len(selected) != len(set(selected)):
+            raise ValueError("duplicate_target")
+        deliveries = await asyncio.gather(
+            *(asyncio.to_thread(self._send, name, body, title) for name in selected)
+        )
+        return NotificationResult(deliveries=tuple(deliveries))
+
+    def _send(self, target: str, body: str, title: str) -> NotificationDelivery:
+        with self._locks[target]:
+            plugin = self._plugins[target]
+            plugin.outcome = {}
+            token = notification_http_active.set(True)
+            try:
+                success = bool(plugin.notify(body=body, title=title))
+            except requests.Timeout:
+                return NotificationDelivery(target=target, success=False, error_code="timeout")
+            except requests.RequestException:
+                return NotificationDelivery(target=target, success=False, error_code="network_error")
+            except Exception:
+                # 第三方插件可能把响应正文放入异常；在 SDK 边界只返回固定错误码。
+                return NotificationDelivery(target=target, success=False, error_code="provider_error")
+            finally:
+                notification_http_active.reset(token)
+            return NotificationDelivery(
+                target=target,
+                success=success,
+                **(plugin.outcome if plugin.outcome else {} if success else {"error_code": "send_failed"}),
+            )

dwy_notify-0.1.0.dist-info/METADATA

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: dwy-notify
+Version: 0.1.0
+Summary: 基于 Apprise 的独立多目标通知与安全发送边界
+Requires-Python: <3.13,>=3.11
+Requires-Dist: apprise==2.1.0
+Requires-Dist: dwyeapi==0.12.1
+Requires-Dist: requests==2.34.2
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio==1.3.0; extra == 'dev'
+Requires-Dist: pytest==9.0.3; extra == 'dev'
+Requires-Dist: ruff==0.15.12; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# dwy-notify
+
+独立多目标异步通知包，基于 `apprise==2.1.0`，公共配置和结果类型由本包拥有。依赖 `dwyeapi==0.12.1` 基础规范，不要求运行 Webhook 服务。
+
+```bash
+pip install dwy-notify==0.1.0
+```
+
+```python
+import asyncio
+import os
+
+from dwy_notify import NotificationConfig, Notifier
+
+
+async def main() -> None:
+    notifier = Notifier(NotificationConfig(targets={
+        "discord": os.environ["DISCORD_NOTIFY_URL"],
+        "wecom": os.environ["WECOM_NOTIFY_URL"],
+    }))
+    result = await notifier.send("任务完成", title="每日汇总")
+    for delivery in result.deliveries:
+        if not delivery.success:
+            print(delivery.target, delivery.error_code, delivery.retry_after, delivery.permanent)
+
+
+asyncio.run(main())
+```
+
+`DISCORD_NOTIFY_URL` 来自宿主环境，可用 `discord://WEBHOOK_ID/WEBHOOK_TOKEN` 或 `https://discord.com/api/webhooks/WEBHOOK_ID/WEBHOOK_TOKEN`。`WECOM_NOTIFY_URL` 使用 `wecombot://WEBHOOK_KEY`。凭据应来自环境变量或秘密存储，不写入版本库。配置使用 `SecretStr` 隐藏 URL；调用方不要解密后记录。
+
+`NotificationConfig(targets=..., timeout_seconds=10)` 为 frozen Pydantic 模型，目标映射非空，超时必须为有限正数且不超过 30 秒，不接受布尔值。`Notifier` 在构造时固定目标快照，不读取环境变量。`targets` 返回目标名元组，`target_fingerprint(name)` 返回 URL 的 SHA-256 摘要，供调用方检测配置变更；摘要不包含明文 URL。
+
+`await notifier.send(body, title="", targets=None)` 默认发送全部目标，返回 `NotificationResult`。`success` 仅在至少一个目标且全部成功时为真，`succeeded` / `failed` 是目标名元组，详情位于 `deliveries`。每条 `NotificationDelivery` 包含 `target`、`success`、`message_id`、`error_code`、`retry_after`、`permanent`。正文必须为非空白字符串，标题必须为字符串，显式 targets 必须非空且不重复；无效输入或未知目标在发请求前抛出固定 `ValueError`。调用方应遵守 `retry_after` 并排除永久失败，再用失败目标列表重试。
+
+安全边界：
+
+- HTTP 渠道强制 TLS 校验、禁重定向、禁 SDK retry 和 optional 成功；覆盖 URL 中相反选项。普通渠道沿用 Apprise 的 HTTPS 协议和安全参数，不使用全局 monkeypatch。
+- Discord 复用上游解析、消息构造和分段，仅适配单次 HTTP 发送：`allowed_mentions={"parse": []}`、始终设置 flags 的 `4` 位，并用 `wait=true` 确认真实消息 ID；响应 ID 必须为 1 至 128 位 ASCII 数字。需要分段时使用 Apprise 的 `?overflow=split`，分段遇失败停止后续请求。企业微信仅在 JSON `errcode` 为整数 `0` 时成功。
+- Discord / 企业微信返回 HTTP 状态对应的安全错误码，429 的有效秒数放入 `retry_after`，408 与 5xx 可重试。普通渠道以 SDK 返回值判断成功，失败统一 `send_failed`，不暴露原始响应或异常。插件日志通过本包子类隔离；urllib3 原始 HTTP 日志仅在通知工作线程的发送区间被过滤，宿主其它线程、普通 HTTP 调用与应用日志保留。
+- 支持 Apprise 基于 `requests` 的 HTTPS 渠道，例如 Discord、企业微信、钉钉、飞书和 `jsons` 自定义 HTTPS；不支持 SMTP、本地命令等非 HTTP 协议或明文协议，也拒绝固定版本中自带内部重试的 Fluxer、Revolt、Matrix、SparkPost、SendPulse，构造时返回 `unsupported_transport`。可选渠道的额外依赖仍需由宿主安装。
+- 同一目标串行，不同目标可并发。取消等待会传播 `CancelledError`；已开始的同步请求在线程中继续，由连接／读取超时结束，同目标锁直到请求结束才释放。超时是 socket 超时，不是整条通知的硬截止时间；上游分段、多接收人或节流可能增加总耗时。
+- `Notifier` 不提供持久化、调度或自动重试。分段通知中已经成功的部分可能在调用方整体重试时重复；HTTP 接收后丢失响应也无法保证恰好一次。
+
+仅 Discord、企业微信、钉钉和飞书通过模拟 HTTP 验证；未进行真实渠道投递验收，也未逐一验收全部 Apprise 插件。发布必须通过 GitHub Actions OIDC，不使用长期发布 token。

dwy_notify-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+dwy_notify/__init__.py,sha256=GMHZf4uHmMYrc7XJcj4C4E4zVJOPBMm5k8lC3Y7VAxE,301
+dwy_notify/_logging.py,sha256=K-m7T6EYSPSzly0BmByZ9NK3gG08sEvg2-Ebya7x9C4,750
+dwy_notify/_plugins.py,sha256=FUNa-2QdcsGJPLNe0IDzCjOAR9M0yrufCQvREkUhBzg,4729
+dwy_notify/_transport.py,sha256=URaeWwkoEoCg9QTojLv-wpBk9oWR3LkOWgv87I6DbTg,1931
+dwy_notify/models.py,sha256=dqiqUlJEZpTKU1dKSNvwI2hhtKRMYRAz1oFjWiTZ6Eo,1835
+dwy_notify/notifier.py,sha256=uSCn6IcB7Cu-CgyPPbvVLNGVY46XwGKkEwRxB8ILz4U,3775
+dwy_notify-0.1.0.dist-info/METADATA,sha256=ZEOt01fC2For-i7pjT0jqmQFxjEL0q3GhxAhJaKLKA8,4780
+dwy_notify-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dwy_notify-0.1.0.dist-info/RECORD,,

dwy_notify-0.1.0.dist-info/WHEEL

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