xqc-pymagicpush 0.0.1__tar.gz

xqc_pymagicpush-0.0.1/LICENSE

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

xqc_pymagicpush-0.0.1/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.3
+Name: xqc-pymagicpush
+Version: 0.0.1
+Summary: 🎉 微信公众号：XiaoqiangClub 自用模块。
+Keywords: magicpush,push,notification,feishu,dingtalk,telegram,bark,wecom
+Author: Xiaoqiang
+Author-email: xiaoqiangclub@hotmail.com
+Requires-Python: >=3.10
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications
+Requires-Dist: python-dotenv (>=1.0.0)
+Requires-Dist: requests (>=2.28.0)
+Project-URL: Homepage, https://xiaoqiangclub.github.io/
+Project-URL: Repository, https://github.com/xiaoqiangclub/pymagicpush

xqc_pymagicpush-0.0.1/pyproject.toml

@@ -0,0 +1,32 @@
+[tool.poetry]
+name = "xqc-pymagicpush"
+version = "0.0.1"
+description = "🎉 微信公众号：XiaoqiangClub 自用模块。"
+authors = ["Xiaoqiang <xiaoqiangclub@hotmail.com>"]
+homepage = "https://xiaoqiangclub.github.io/"
+repository = "https://github.com/xiaoqiangclub/pymagicpush"
+keywords = ["magicpush", "push", "notification", "feishu", "dingtalk", "telegram", "bark", "wecom"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Communications",
+]
+packages = [{ include = "pymagicpush", from = "src" }]
+include = [{ path = "src/pymagicpush/skill/SKILL.md", format = ["sdist", "wheel"] }]
+
+[tool.poetry.dependencies]
+python = ">=3.10"
+requests = ">=2.28.0"
+python-dotenv = ">=1.0.0"
+
+[tool.poetry.scripts]
+pymagicpush = "pymagicpush.cli:main"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"

xqc_pymagicpush-0.0.1/src/pymagicpush/__init__.py

@@ -0,0 +1,27 @@
+"""pymagicpush —— MagicPush 消息推送服务的 Python 客户端。
+
+快速示例::
+
+    from pymagicpush import MagicPushClient
+    client = MagicPushClient()  # 自动读取 .env / 环境变量
+    client.send(content="Hello from pymagicpush!", title="测试")
+"""
+from .config import Config
+from .client import MagicPushClient
+from .exceptions import (
+    MagicPushError,
+    MagicPushAuthError,
+    MagicPushAPIError,
+    MagicPushConfigError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "MagicPushClient",
+    "Config",
+    "MagicPushError",
+    "MagicPushAuthError",
+    "MagicPushAPIError",
+    "MagicPushConfigError",
+    "__version__",
+]

xqc_pymagicpush-0.0.1/src/pymagicpush/cli.py

@@ -0,0 +1,452 @@
+"""pymagicpush 命令行工具。
+
+提供消息推送、渠道/接口管理、推送记录、管理员、配置查看、AI Skill 安装等子命令。
+运行 `pymagicpush --help` 查看完整帮助；`pymagicpush <子命令> --help` 查看子命令详情。
+"""
+import argparse
+import json
+import os
+import shutil
+import sys
+from typing import Any, Optional
+
+from . import __version__
+from .client import MagicPushClient
+from .config import Config
+from .exceptions import MagicPushError
+
+# .env 模板（内联，确保 wheel 安装也能在 skill 目录生成配置模板）
+_ENV_EXAMPLE_TEMPLATE = """# ============================================================
+# pymagicpush 配置示例
+#
+# ⚠️ 前置：本模块只是客户端，使用前必须先部署 MagicPush 服务端。
+#    部署教程：https://xiaoqiangclub.blog.csdn.net/article/details/160310725
+#    部署完成后，把下方服务地址、推送令牌、登录账号填入即可。
+#
+# 使用方式：
+#   1. 复制本文件为 .env：cp .env.example .env
+#   2. 取消下方对应行的注释（删去行首 #）
+#   3. 把示例值替换为你的真实值
+#   .env 已被 .gitignore 忽略，不会提交。
+#   所有配置项均可通过同名环境变量覆盖（环境变量优先级高于 .env）。
+# ============================================================
+
+# -------------------- 服务地址 --------------------
+# MagicPush 服务地址（部署后的后端地址，含端口，不要带 /api 后缀）
+# 优先作为「本地地址」使用，客户端初始化时会先尝试连通本地地址。
+# MAGICPUSH_BASE_URL=http://localhost:3000
+
+# 远程访问地址（可选，域名或公网 IP）
+# 配置后客户端会在本地不可达时自动切换到远程地址，保证外网场景仍可推送。
+# 留空或保持注释则仅使用上面的 MAGICPUSH_BASE_URL。
+# MAGICPUSH_BASE_URL_REMOTE=https://your-domain.com
+
+# -------------------- 推送令牌 --------------------
+# 默认推送令牌（接口令牌，用于 /api/push 推送，无需登录）
+# 推送时未显式指定令牌即使用此值。
+# MAGICPUSH_TOKEN=your_push_token
+
+# 带描述的推送令牌列表（可选，多接口场景按描述选用）
+# 一个 MagicPush 服务可创建多个接口，每个接口对应独立令牌；
+# 格式为「令牌:描述」，多对用逗号分隔——AI 会读取描述理解每个令牌的用途。
+# 调用 push(token_desc="关键字") 时按描述模糊匹配取令牌。
+# 两种写法任选其一：
+#   简易格式：令牌1:描述1,令牌2:描述2
+#   JSON 格式：[{"token":"令牌1","desc":"描述1"},{"token":"令牌2","desc":"描述2"}]
+# 示例（按用途/渠道描述，便于 AI 选用）：
+#   MAGICPUSH_TOKENS=abc123:飞书频道推送,def456:告警通知专用,ghi789:每日报告
+# MAGICPUSH_TOKENS=
+
+# -------------------- 登录账号 --------------------
+# 登录账号（用于调用需要 JWT 认证的管理类接口，如渠道/接口管理）
+# MAGICPUSH_EMAIL=your_email@example.com
+# MAGICPUSH_PASSWORD=your_password
+
+# 已有的 JWT 令牌（可选，提供后将跳过登录；access 过期会自动用 refresh 续期）
+# MAGICPUSH_ACCESS_TOKEN=
+# MAGICPUSH_REFRESH_TOKEN=
+
+# -------------------- 请求行为 --------------------
+# 请求超时时间（秒）
+# MAGICPUSH_TIMEOUT=30
+
+# 网络失败重试次数（不含首次请求，默认 2 次）
+# 仅对网络层错误（连接超时、SSL 抖动等）生效；业务错误（如 401/4xx）不重试。
+# 设为 0 表示不重试，仅尝试一次。
+# MAGICPUSH_MAX_RETRIES=2
+"""
+
+
+def _print(obj: Any) -> None:
+    """以缩进 JSON 输出结果，非 JSON 则原样打印。"""
+    if isinstance(obj, (dict, list)):
+        print(json.dumps(obj, ensure_ascii=False, indent=2, default=str))
+    else:
+        print(obj)
+
+
+def _build_client(args: argparse.Namespace) -> MagicPushClient:
+    """根据命令行参数构造客户端。"""
+    return MagicPushClient(
+        base_url=getattr(args, "base_url", None),
+        token=getattr(args, "token", None),
+        email=getattr(args, "email", None),
+        password=getattr(args, "password", None),
+        env_path=getattr(args, "env", None),
+    )
+
+
+def _add_conn_args(p: argparse.ArgumentParser) -> None:
+    """为子命令添加连接相关公共参数。"""
+    p.add_argument("--base-url", help="MagicPush 服务地址（不含 /api），覆盖 .env/环境变量")
+    p.add_argument("--token", help="推送令牌，覆盖 .env/环境变量")
+    p.add_argument("--token-desc", help="令牌描述关键字，从 MAGICPUSH_TOKENS 中按描述模糊匹配取令牌推送（与 --token 互斥）")
+    p.add_argument("--email", help="登录邮箱，覆盖 .env/环境变量")
+    p.add_argument("--password", help="登录密码，覆盖 .env/环境变量")
+    p.add_argument("--env", help=".env 文件路径")
+
+
+# ----------------------------------------------------------------------
+# 子命令实现
+# ----------------------------------------------------------------------
+def cmd_health(args: argparse.Namespace) -> int:
+    """健康检查。"""
+    _print(_build_client(args).health())
+    return 0
+
+
+def cmd_version(args: argparse.Namespace) -> int:
+    """获取服务版本。"""
+    _print(_build_client(args).version())
+    return 0
+
+
+def _parse_extra_data(raw: Optional[str]) -> Optional[dict]:
+    """解析 --extra-data 参数（JSON 字符串），为空返回 None。"""
+    if not raw:
+        return None
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise SystemExit(f"[错误] --extra-data 不是合法 JSON：{e}")
+
+
+def cmd_push(args: argparse.Namespace) -> int:
+    """推送消息。"""
+    client = _build_client(args)
+    extra_data = _parse_extra_data(args.extra_data)
+    # 按渠道名定向推送（需登录），优先于 --channel-id
+    if args.channel_name:
+        _print(client.push_by_channel_name(
+            name=args.channel_name, title=args.title, content=args.content,
+            type=args.type, url=args.url, extra_data=extra_data,
+        ))
+        return 0
+    result = client.push(
+        token=args.token, token_desc=args.token_desc,
+        title=args.title, content=args.content, type=args.type, url=args.url, method=args.method,
+        extra_data=extra_data, channel_id=args.channel_id,
+    )
+    _print(result)
+    return 0
+
+
+def cmd_send(args: argparse.Namespace) -> int:
+    """快捷推送（使用配置中的 token）。"""
+    client = _build_client(args)
+    extra_data = _parse_extra_data(args.extra_data)
+    # 按渠道名定向推送（需登录），优先于 --channel-id
+    if args.channel_name:
+        _print(client.push_by_channel_name(
+            name=args.channel_name, title=args.title, content=args.content,
+            type=args.type, url=args.url, extra_data=extra_data,
+        ))
+        return 0
+    _print(client.send(
+        content=args.content, title=args.title, type=args.type, url=args.url,
+        extra_data=extra_data, channel_id=args.channel_id, token_desc=args.token_desc,
+    ))
+    return 0
+
+
+def cmd_channels(args: argparse.Namespace) -> int:
+    """渠道管理。"""
+    client = _build_client(args)
+    action = args.action
+    if action == "list":
+        _print(client.list_channels())
+    elif action == "types":
+        _print(client.get_channel_types())
+    elif action == "get":
+        _print(client.get_channel(args.id))
+    elif action == "create":
+        cfg = json.loads(args.config) if args.config else {}
+        _print(client.create_channel(args.type, args.name, cfg, args.description))
+    elif action == "delete":
+        _print(client.delete_channel(args.id))
+    elif action == "test":
+        _print(client.test_channel(args.id))
+    return 0
+
+
+def cmd_endpoints(args: argparse.Namespace) -> int:
+    """接口管理。"""
+    client = _build_client(args)
+    action = args.action
+    if action == "list":
+        _print(client.list_endpoints(args.page, args.pageSize))
+    elif action == "get":
+        _print(client.get_endpoint(args.id))
+    elif action == "create":
+        data = json.loads(args.data) if args.data else {}
+        _print(client.create_endpoint(data))
+    elif action == "delete":
+        _print(client.delete_endpoint(args.id))
+    elif action == "regenerate-token":
+        _print(client.regenerate_endpoint_token(args.id))
+    elif action == "channels":
+        _print(client.get_endpoint_channels(args.id))
+    elif action == "bind":
+        ids = json.loads(args.channel_ids)
+        _print(client.update_endpoint_channels(args.id, ids))
+    return 0
+
+
+def cmd_logs(args: argparse.Namespace) -> int:
+    """推送记录。"""
+    client = _build_client(args)
+    action = args.action
+    if action == "list":
+        _print(client.list_logs(args.page, args.pageSize, args.channelType, args.status, args.keyword, args.startDate, args.endDate))
+    elif action == "stats":
+        _print(client.get_log_stats())
+    elif action == "get":
+        _print(client.get_log(args.id))
+    elif action == "clear":
+        _print(client.clear_logs())
+    return 0
+
+
+def cmd_auth(args: argparse.Namespace) -> int:
+    """认证。"""
+    client = _build_client(args)
+    if args.action == "login":
+        _print(client.login())
+    elif args.action == "refresh":
+        _print(client.refresh_access_token())
+    elif args.action == "me":
+        _print(client.get_me())
+    return 0
+
+
+def cmd_admin(args: argparse.Namespace) -> int:
+    """管理员接口。"""
+    client = _build_client(args)
+    if args.action == "users":
+        _print(client.admin_list_users(args.page, args.pageSize, args.keyword))
+    elif args.action == "settings":
+        _print(client.admin_get_settings())
+    elif args.action == "rate-limits":
+        _print(client.admin_get_rate_limits())
+    return 0
+
+
+def cmd_config(args: argparse.Namespace) -> int:
+    """查看当前配置（脱敏）。"""
+    cfg = Config.from_env(args.env)
+    if args.action == "show":
+        _print(cfg.to_dict())
+    elif args.action == "init":
+        example = os.path.join(os.path.dirname(__file__), "..", "..", ".env.example")
+        example = os.path.abspath(example)
+        target = args.target or ".env"
+        if not os.path.exists(example):
+            print(f"未找到 .env.example 模板：{example}", file=sys.stderr)
+            return 1
+        shutil.copyfile(example, target)
+        print(f"已生成 {target}，请填写真实配置后使用。")
+    return 0
+
+
+def cmd_install_skill(args: argparse.Namespace) -> int:
+    """安装 AI 调用 Skill 到本地技能目录（固定目录名 magicpush-skill）。
+
+    默认安装到当前工作目录下的 ./magicpush-skill；通过 --target 指定时安装到 <target>/magicpush-skill。
+    """
+    src = os.path.join(os.path.dirname(__file__), "skill", "SKILL.md")
+    if not os.path.exists(src):
+        print(f"未找到内置 SKILL.md：{src}", file=sys.stderr)
+        return 1
+
+    # 固定目录名 magicpush-skill；默认安装到当前项目根目录下，--target 指定父目录
+    base_dir = args.target if args.target else os.getcwd()
+    target_dir = os.path.join(base_dir, "magicpush-skill")
+
+    os.makedirs(target_dir, exist_ok=True)
+    dst = os.path.join(target_dir, "SKILL.md")
+    shutil.copyfile(src, dst)
+    print(f"AI Skill 安装成功：{dst}")
+    # 在该目录放置 .env 模板，便于全局 skill 安装时配置凭证
+    env_dst = os.path.join(target_dir, ".env.example")
+    with open(env_dst, "w", encoding="utf-8") as f:
+        f.write(_ENV_EXAMPLE_TEMPLATE)
+    # 若目录下尚无 .env，提示用户填写
+    if not os.path.exists(os.path.join(target_dir, ".env")):
+        print(f"请复制 {env_dst} 为 .env 并填写服务地址、推送令牌、登录账号后使用。")
+    print("重启 TRAE 会话或在技能面板刷新后即可使用名为 `magicpush` 的技能。")
+    return 0
+
+
+def cmd_selfcheck(args: argparse.Namespace) -> int:
+    """本地自检（不发真实请求）。"""
+    from .client import demo
+    demo()
+    return 0
+
+
+# ----------------------------------------------------------------------
+# 解析器构建
+# ----------------------------------------------------------------------
+def build_parser() -> argparse.ArgumentParser:
+    """构建 CLI 解析器。"""
+    parser = argparse.ArgumentParser(
+        prog="pymagicpush",
+        description="MagicPush 消息推送服务 Python 客户端命令行工具。",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "示例:\n"
+            "  pymagicpush push --content '你好' --title '测试'\n"
+            "  pymagicpush channels types\n"
+            "  pymagicpush endpoints list\n"
+            "  pymagicpush logs stats\n"
+            "  pymagicpush install-skill\n"
+        ),
+    )
+    parser.add_argument("-V", "--version", action="version", version=f"pymagicpush {__version__}")
+    sub = parser.add_subparsers(dest="command", metavar="<子命令>")
+
+    # health
+    p = sub.add_parser("health", help="健康检查")
+    _add_conn_args(p)
+    p.set_defaults(func=cmd_health)
+
+    # version
+    p = sub.add_parser("version", help="获取服务版本")
+    _add_conn_args(p)
+    p.set_defaults(func=cmd_version)
+
+    # push
+    p = sub.add_parser("push", help="通过推送令牌发送消息")
+    _add_conn_args(p)
+    p.add_argument("--content", help="消息正文（发送特有类型 --extra-data 时可省略）")
+    p.add_argument("--title", help="消息标题")
+    p.add_argument("--type", default="text", choices=["text", "markdown", "html"], help="消息类型（默认 text）")
+    p.add_argument("--url", help="跳转链接")
+    p.add_argument("--method", default="header", choices=["header", "url", "get"], help="推送方式（默认 header 最安全）")
+    p.add_argument("--extra-data", help="渠道特有消息类型参数（JSON 字符串），如飞书富文本、企业微信模板卡片、Telegram 图片")
+    p.add_argument("--channel-id", help="定向推送的渠道 ID（用于特有类型定向推送）")
+    p.add_argument("--channel-name", help="按渠道名称/类型关键字定向推送（需登录，如「小爱音响」「飞书」），优先于 --channel-id")
+    p.set_defaults(func=cmd_push)
+
+    # send（快捷）
+    p = sub.add_parser("send", help="快捷推送（使用配置中的 token）")
+    _add_conn_args(p)
+    p.add_argument("--content", help="消息正文（发送特有类型 --extra-data 时可省略）")
+    p.add_argument("--title", help="消息标题")
+    p.add_argument("--type", default="text", choices=["text", "markdown", "html"], help="消息类型")
+    p.add_argument("--url", help="跳转链接")
+    p.add_argument("--extra-data", help="渠道特有消息类型参数（JSON 字符串）")
+    p.add_argument("--channel-id", help="定向推送的渠道 ID（用于特有类型定向推送）")
+    p.add_argument("--channel-name", help="按渠道名称/类型关键字定向推送（需登录，如「小爱音响」「飞书」），优先于 --channel-id")
+    p.set_defaults(func=cmd_send)
+
+    # channels
+    p = sub.add_parser("channels", help="渠道管理")
+    _add_conn_args(p)
+    p.add_argument("action", choices=["list", "types", "get", "create", "delete", "test"], help="操作")
+    p.add_argument("--id", help="渠道 ID（get/delete/test）")
+    p.add_argument("--type", help="渠道类型标识（create）")
+    p.add_argument("--name", help="渠道名称（create）")
+    p.add_argument("--config", help="渠道配置 JSON 字符串（create）")
+    p.add_argument("--description", help="渠道描述（create）")
+    p.set_defaults(func=cmd_channels)
+
+    # endpoints
+    p = sub.add_parser("endpoints", help="接口管理")
+    _add_conn_args(p)
+    p.add_argument("action", choices=["list", "get", "create", "delete", "regenerate-token", "channels", "bind"], help="操作")
+    p.add_argument("--id", help="接口 ID")
+    p.add_argument("--page", type=int, help="页码")
+    p.add_argument("--pageSize", type=int, help="每页数量")
+    p.add_argument("--data", help="接口数据 JSON 字符串（create）")
+    p.add_argument("--channel-ids", help="渠道 ID 列表 JSON 字符串（bind）")
+    p.set_defaults(func=cmd_endpoints)
+
+    # logs
+    p = sub.add_parser("logs", help="推送记录")
+    _add_conn_args(p)
+    p.add_argument("action", choices=["list", "stats", "get", "clear"], help="操作")
+    p.add_argument("--id", help="记录 ID（get）")
+    p.add_argument("--page", type=int, help="页码")
+    p.add_argument("--pageSize", type=int, help="每页数量")
+    p.add_argument("--channelType", help="按渠道类型筛选")
+    p.add_argument("--status", help="按状态筛选（success/failed/skipped_dnd）")
+    p.add_argument("--keyword", help="关键词搜索")
+    p.add_argument("--startDate", help="开始日期（YYYY-MM-DD）")
+    p.add_argument("--endDate", help="结束日期（YYYY-MM-DD）")
+    p.set_defaults(func=cmd_logs)
+
+    # auth
+    p = sub.add_parser("auth", help="认证与当前用户")
+    _add_conn_args(p)
+    p.add_argument("action", choices=["login", "refresh", "me"], help="操作")
+    p.set_defaults(func=cmd_auth)
+
+    # admin
+    p = sub.add_parser("admin", help="管理员接口（需 Admin 角色）")
+    _add_conn_args(p)
+    p.add_argument("action", choices=["users", "settings", "rate-limits"], help="操作")
+    p.add_argument("--page", type=int, help="页码")
+    p.add_argument("--pageSize", type=int, help="每页数量")
+    p.add_argument("--keyword", help="搜索关键词")
+    p.set_defaults(func=cmd_admin)
+
+    # config
+    p = sub.add_parser("config", help="查看当前配置（脱敏）/ 生成 .env")
+    p.add_argument("action", choices=["show", "init"], help="操作")
+    p.add_argument("--env", help=".env 文件路径（show）")
+    p.add_argument("--target", help="生成目标路径（init，默认 .env）")
+    p.set_defaults(func=cmd_config)
+
+    # install-skill
+    p = sub.add_parser("install-skill", help="安装 AI 调用 Skill 到本地技能目录")
+    p.add_argument("--target", help="目标父目录（默认当前工作目录，skill 安装到 <target>/magicpush-skill）")
+    p.set_defaults(func=cmd_install_skill)
+
+    # selfcheck
+    p = sub.add_parser("selfcheck", help="本地自检（不发真实请求）")
+    p.set_defaults(func=cmd_selfcheck)
+
+    return parser
+
+
+def main(argv: Optional[list] = None) -> int:
+    """CLI 入口。无子命令时直接显示帮助信息。"""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    # 无子命令：直接打印帮助并退出（exit 0）
+    if not getattr(args, "command", None):
+        parser.print_help()
+        return 0
+    try:
+        return args.func(args)
+    except MagicPushError as e:
+        print(f"[错误] {e}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("\n已中断", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())