push-tools 0.1.0__py3-none-any.whl

push_tools/__init__.py

@@ -0,0 +1,195 @@
+"""push-tools: a small, pluggable message-push toolkit.
+
+Public API
+----------
+Core abstractions:
+
+- :class:`PushChannel` / :class:`PushResult` - channel base class and result.
+- :func:`register_channel` - decorator that registers a channel plugin.
+- :func:`create_channel` - factory: build a channel by its registered name.
+- :class:`PushComposite` - fan one message out to several channels.
+- :data:`registry` / :func:`load_plugins` - plugin registry and entry-point
+  discovery.
+
+Built-in channels:
+
+- :class:`PushPlus`    (registered name ``"pushplus"``)
+- :class:`Qmsg`        (registered name ``"qmsg"``)
+- :class:`ServerChan`  (registered name ``"server"``)
+- :class:`Telegram`    (registered name ``"telegram"``)
+- :class:`WorkWechat`  (registered name ``"workWechat"``)
+- :class:`WorkWechatRobot` (registered name ``"workWechatRobot"``)
+
+Quick example::
+
+    import logging
+    logging.basicConfig(level=logging.INFO)
+
+    from push_tools import create_channel
+
+    pusher = create_channel("pushplus", "your-token")
+    pusher.send("hello world", title="greeting")
+
+Writing a plugin
+----------------
+Subclass :class:`PushChannel`, decorate it, and start using it::
+
+    from push_tools import PushChannel, register_channel, create_channel
+
+    @register_channel("stdout")
+    class StdoutChannel(PushChannel):
+        def send(self, message, **options):
+            print(message)
+            return self._succeed(raw={"echo": message})
+
+    create_channel("stdout").send("hello")
+
+Third-party packages can also ship channels as ``push_tools.channels``
+entry points - see :mod:`push_tools.registry`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+# Core building blocks.
+from .base import PushChannel, PushResult
+from .composite import PushComposite
+from .errors import (
+    AccessFailed,
+    ChannelAlreadyRegistered,
+    PushChannelError,
+    PushToolsError,
+    UnknownChannelError,
+    catch_exception,
+)
+from .factory import create_channel
+from .registry import (
+    ENTRY_POINT_GROUP,
+    ChannelRegistry,
+    load_plugins,
+    register_channel,
+    registry,
+)
+
+# Importing the built-in channel package triggers self-registration.
+from . import channels as _channels  # noqa: F401
+from .channels.pushplus import PushPlus
+from .channels.qmsg import Qmsg
+from .channels.serverchan import ServerChan
+from .channels.telegram import Telegram
+from .channels.wechat import WorkWechat, WorkWechatRobot
+
+__version__ = "0.0.1"
+
+# ---------------------------------------------------------------------- #
+# Backward-compatible aliases (push-tools 0.0.1 API)
+# ---------------------------------------------------------------------- #
+# New code should use the PEP-8 names above; the lowercase aliases exist so
+# existing callers keep working unchanged.
+push = PushChannel
+pushplus = PushPlus
+qmsg = Qmsg
+server = ServerChan
+telegram = Telegram
+workWechat = WorkWechat
+workWechatRobot = WorkWechatRobot
+push_composite = PushComposite
+
+
+class push_creator:
+    """Deprecated factory wrapper from push-tools 0.0.1.
+
+    New code should use :func:`create_channel`, which raises
+    :class:`UnknownChannelError` for unknown names instead of printing.
+
+    Example (legacy style)::
+
+        creator = push_creator("qmsg", "your-key")
+        creator.send("hello world")
+    """
+
+    def __init__(self, type, key):
+        self.type = type
+        # Preserve the original "print and keep going" behaviour for callers
+        # that relied on an unknown type not raising.
+        try:
+            self.push = self.create(type, key)
+        except UnknownChannelError:
+            print(f"Unsupported push type: {type}")
+            self.push = None
+
+    def create(self, type, key):
+        """Build the underlying channel; kept for API compatibility."""
+
+        return create_channel(type, key)
+
+    def send(self, msg, **kwargs):
+        """Forward the message to the wrapped channel, if any."""
+
+        if self.push is None:
+            print("No push instance created.")
+            return None
+        return self.push.send(msg, **kwargs)
+
+
+class _RegistryView(Mapping):
+    """Read-only dynamic ``{name: channel_class}`` view of the registry.
+
+    Backward-compatible replacement for the old static ``push_server`` dict:
+    it stays in sync with third-party entry-point plugins loaded at runtime.
+    """
+
+    def __getitem__(self, name):
+        try:
+            return registry.get(name)
+        except UnknownChannelError as exc:
+            raise KeyError(name) from exc
+
+    def __iter__(self):
+        return iter(registry.names())
+
+    def __len__(self):
+        return len(registry.names())
+
+
+# Legacy name for the global name -> class mapping.
+push_server = _RegistryView()
+
+__all__ = [
+    # core
+    "PushChannel",
+    "PushResult",
+    "PushComposite",
+    "create_channel",
+    "register_channel",
+    "registry",
+    "ChannelRegistry",
+    "load_plugins",
+    "ENTRY_POINT_GROUP",
+    # errors
+    "PushToolsError",
+    "PushChannelError",
+    "AccessFailed",
+    "UnknownChannelError",
+    "ChannelAlreadyRegistered",
+    "catch_exception",
+    # built-in channels
+    "PushPlus",
+    "Qmsg",
+    "ServerChan",
+    "Telegram",
+    "WorkWechat",
+    "WorkWechatRobot",
+    # legacy aliases
+    "push",
+    "pushplus",
+    "qmsg",
+    "server",
+    "telegram",
+    "workWechat",
+    "workWechatRobot",
+    "push_composite",
+    "push_creator",
+    "push_server",
+]

push_tools/base.py

@@ -0,0 +1,189 @@
+"""Abstract base class shared by every push channel.
+
+A *channel* is a small adapter that knows how to deliver a text message to
+one third-party service (PushPlus, Qmsg, ServerChan, WeCom, ...). Third-party
+packages add new services by subclassing :class:`PushChannel` and registering
+the subclass with :func:`push_tools.registry.register_channel`.
+
+Example:
+    Minimal custom channel::
+
+        from push_tools import PushChannel, register_channel
+
+        @register_channel("stdout")
+        class StdoutChannel(PushChannel):
+            def send(self, message, **options):
+                print(message)
+                return self._succeed(raw={"echo": message})
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, ClassVar, Optional
+
+logger = logging.getLogger("push_tools")
+
+
+@dataclass(frozen=True)
+class PushResult:
+    """Immutable result object returned by a successful :meth:`PushChannel.send`.
+
+    Attributes:
+        success: Always ``True`` for a returned result (``None`` is returned
+            on failure by ``@catch_exception``).
+        channel: Registered name of the channel that produced the result.
+        raw: Parsed JSON body (or any other data) returned by the upstream
+            service; useful for debugging and auditing.
+        message: Optional human-readable note.
+
+    Example:
+        ::
+
+            result = pusher.send("hello")
+            result.success   # True
+            result.channel   # 'pushplus'
+    """
+
+    success: bool
+    channel: str
+    raw: Any = None
+    message: str = ""
+
+
+class PushChannel(ABC):
+    """Abstract base class for all push channels.
+
+    Class attributes:
+        name: Registered channel name. Filled in automatically by
+            ``@register_channel("...")``; subclasses do not need to set it.
+        default_timeout: Default HTTP timeout (seconds) used when the caller
+            does not pass ``timeout`` explicitly. Prevents a stalled
+            connection from blocking forever.
+        allowed_options: White-list of keyword names that
+            :meth:`_filter_options` will forward to the upstream API. This
+            keeps a fan-out call safe: unknown options are silently ignored.
+
+    Constructor arguments:
+        token: Credential required by the service. Most channels take a
+            string key/token; the WeCom application channel takes a dict of
+            ``{"corpid": ..., "corpSecret": ...}``.
+        timeout: Per-request HTTP timeout in seconds; falls back to
+            :attr:`default_timeout` when omitted.
+
+    Example:
+        Implement a new channel::
+
+            @register_channel("bark")
+            class Bark(PushChannel):
+                url = "https://api.day.app"
+                allowed_options = frozenset({"title", "sound"})
+
+                @catch_exception
+                def send(self, message, **options):
+                    data = self._filter_options(**options)
+                    data["body"] = message
+                    res = requests.post(f"{self.url}/{self.token}",
+                                        data=data, timeout=self.timeout).json()
+                    if res.get("code") == 200:
+                        return self._succeed(raw=res)
+                    raise AccessFailed(res.get("message"))
+    """
+
+    # Filled in by the registry decorator; empty for unregistered subclasses.
+    name: ClassVar[str] = ""
+
+    # Network timeout shared by the built-in HTTP channels.
+    default_timeout: ClassVar[float] = 10.0
+
+    # Keyword arguments accepted by the upstream API of a concrete channel.
+    allowed_options: ClassVar[frozenset] = frozenset()
+
+    def __init__(self, token: Any = None, *, timeout: "float | None" = None):
+        # ``token`` is the preferred name; ``key`` is kept as an alias so the
+        # original attribute name from push-tools 0.0.1 still works.
+        self.token = token
+        self.key = token
+        self.timeout = self.default_timeout if timeout is None else timeout
+
+    @property
+    def label(self) -> str:
+        """Log/display label: registered name when available, class name otherwise."""
+
+        return self.name or self.__class__.__name__
+
+    @abstractmethod
+    def send(self, message: str, **options: Any) -> "Optional[PushResult]":
+        """Send ``message`` to the remote service.
+
+        Args:
+            message: Text body to deliver. Channels may accept Markdown / HTML
+                depending on their ``msgtype`` / ``template`` options.
+            **options: Channel-specific keyword arguments. Unknown keywords
+                must be ignored so one :class:`PushComposite` fan-out call can
+                carry options for heterogeneous channels.
+
+        Returns:
+            A :class:`PushResult` on success, or ``None`` when the method is
+            decorated with :func:`~push_tools.errors.catch_exception` and an
+            exception was caught.
+
+        Example:
+            >>> pusher.send("hello world", title="greeting")  # doctest: +SKIP
+        """
+
+        raise NotImplementedError
+
+    # ------------------------------------------------------------------ #
+    # Helpers reusable by concrete channels
+    # ------------------------------------------------------------------ #
+
+    def success(self, *args: Any) -> None:
+        """Log an ``INFO`` message prefixed with the channel label.
+
+        Preserved from the original ``push`` base class which printed
+        ``[ClassName] Operate successfully.``.
+
+        Example:
+            >>> self.success()                                  # doctest: +SKIP
+            >>> self.success("media id:", "abc123")             # doctest: +SKIP
+        """
+
+        if args:
+            logger.info("[%s] %s", self.label, " ".join(str(arg) for arg in args))
+        else:
+            logger.info("[%s] Operate successfully.", self.label)
+
+    def _succeed(self, raw: Any = None) -> PushResult:
+        """Log success and build the :class:`PushResult` returned by ``send``.
+
+        Args:
+            raw: Optional raw payload (usually the decoded JSON response).
+
+        Example:
+            >>> return self._succeed(raw=response_json)   # doctest: +SKIP
+        """
+
+        self.success()
+        return PushResult(success=True, channel=self.label, raw=raw)
+
+    def _filter_options(self, **options: Any) -> dict:
+        """Keep only keys listed in :attr:`allowed_options`.
+
+        This makes a single ``composite.send(..., title=..., qq=...)`` call
+        safe: ``title`` reaches PushPlus while ``qq`` reaches Qmsg and every
+        other channel simply ignores the unrelated keys.
+
+        Example:
+            ::
+
+                # with allowed_options = frozenset({"title"})
+                self._filter_options(title="hi", ignored=1)
+                # -> {'title': 'hi'}
+        """
+
+        return {
+            key: value for key, value in options.items() if key in self.allowed_options
+        }

push_tools/channels/__init__.py

@@ -0,0 +1,25 @@
+"""Built-in push channels shipped with push-tools.
+
+Importing this package imports every built-in channel module once, which in
+turn registers the channel classes on the global registry. Third-party
+channels do not live here - they are discovered from installed packages via
+the ``push_tools.channels`` entry-point group (see
+:mod:`push_tools.registry`).
+
+Example:
+    List every available channel name (built-ins + installed plugins)::
+
+        from push_tools import registry
+    print(registry.names())
+    # ['pushplus', 'qmsg', 'server', 'telegram', 'workWechat',
+    #  'workWechatRobot']
+"""
+
+from __future__ import annotations
+
+# Importing the modules triggers their @register_channel decorators.
+from . import pushplus as pushplus  # noqa: F401
+from . import qmsg as qmsg  # noqa: F401
+from . import serverchan as serverchan  # noqa: F401
+from . import telegram as telegram  # noqa: F401
+from . import wechat as wechat  # noqa: F401