SparkleHelper 0.1.0__py3-none-win_amd64.whl

sparklehelper-0.1.0.data/purelib/sparklehelper/__init__.py

@@ -0,0 +1,62 @@
+"""sparklehelper —— Sparkle / WinSparkle 原生更新框架的 Python 运行时接口。
+
+快速上手::
+
+    from sparklehelper import Updater
+
+    updater = Updater()                # 读 .app 的 Info.plist 配置
+    updater.check_for_updates()        # 弹出平台原生更新窗口
+
+详见 :class:`sparklehelper.updater.Updater`。
+"""
+
+from __future__ import annotations
+
+from . import errors, types
+from ._backend._macos import Decision, UpdaterDelegate
+from .errors import (
+    ConfigurationError,
+    NotABundleError,
+    SparkleError,
+    SparkleNotAvailableError,
+    UpdateCheckError,
+    WrongThreadError,
+)
+from .types import (
+    SystemProfileEntry,
+    UpdateCheckKind,
+    UpdateCheckResult,
+    UpdateInfo,
+    UserUpdateChoice,
+    UserUpdateStage,
+    UserUpdateState,
+)
+from .updater import Subscription, Updater, ensure_runnable
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Updater",
+    "UpdaterDelegate",
+    "Decision",
+    "Subscription",
+    "ensure_runnable",
+    "types",
+    "errors",
+    # dataclass 快捷导出
+    "UpdateInfo",
+    "SystemProfileEntry",
+    "UpdateCheckKind",
+    "UpdateCheckResult",
+    "UserUpdateChoice",
+    "UserUpdateStage",
+    "UserUpdateState",
+    # 异常快捷导出
+    "SparkleError",
+    "SparkleNotAvailableError",
+    "NotABundleError",
+    "ConfigurationError",
+    "UpdateCheckError",
+    "WrongThreadError",
+    "__version__",
+]

sparklehelper-0.1.0.data/purelib/sparklehelper/_backend/__init__.py

@@ -0,0 +1,54 @@
+"""平台后端选择器。
+
+按 ``sys.platform`` 选择并返回一个 :class:`~sparklehelper._backend.base.UpdateBackend`
+实现。后端类的 import 放在函数体内（惰性），保证：
+
+- 非 darwin / 非 win32 平台 ``import sparklehelper._backend`` 本身不失败；
+- 目标平台才 import 对应后端模块（macOS 不 import ctypes win32，Windows
+  不 import PyObjC），避免拉起无关的平台依赖。
+
+后端类尚未全部实现时，调用 ``get_backend`` 在对应平台会抛
+:class:`~sparklehelper.errors.SparkleNotAvailableError`，这是预期行为。
+"""
+
+from __future__ import annotations
+
+import sys
+
+from ..errors import SparkleNotAvailableError
+
+from .base import (
+    Callbacks,
+    SparkleExtras,
+    UpdateBackend,
+    UpdateConfig,
+    WinSparkleExtras,
+)
+
+__all__ = [
+    "get_backend",
+    "UpdateBackend",
+    "UpdateConfig",
+    "Callbacks",
+    "SparkleExtras",
+    "WinSparkleExtras",
+]
+
+
+def get_backend() -> UpdateBackend:
+    """返回当前平台的更新后端实例。
+
+    :raises SparkleNotAvailableError: 当前平台不支持，或对应后端模块缺失。
+    """
+    platform = sys.platform
+    if platform == "darwin":
+        from ._macos import MacOSBackend
+
+        return MacOSBackend()
+    if platform == "win32":
+        from ._windows import WindowsBackend
+
+        return WindowsBackend()
+    raise SparkleNotAvailableError(
+        f"sparklehelper 不支持当前平台: {platform}（仅支持 macOS / Windows）"
+    )

sparklehelper-0.1.0.data/purelib/sparklehelper/_backend/_macos/__init__.py

@@ -0,0 +1,45 @@
+"""macOS 后端包：Sparkle.framework 的加载与 ObjC 桥接。
+
+把原 ``_objc`` / ``_bridge`` / ``delegates`` 三个模块的逻辑按功能边界拆分到
+子模块，由 :class:`MacOSBackend` 组合，对外只暴露统一契约：
+
+- :mod:`._loading`：Sparkle.framework 运行时加载（进程级缓存）
+- :mod:`._runtime`：主线程约束 / bundle 解析 / KVO observer（进程级缓存）
+- :mod:`._delegates`：``SPUUpdaterDelegate`` Python 抽象与 ObjC 适配器
+- :mod:`._backend`：:class:`MacOSBackend` 类（组合上述三者）
+
+非 darwin 安全
+--------------
+本包顶层不 import PyObjC / Foundation。所有 ObjC import 延迟到函数体内
+惰性执行，保证非 darwin 平台 ``import sparklehelper._backend._macos``
+不会触发 ObjC 类注册或导入失败。
+"""
+
+from __future__ import annotations
+
+# MacOSBackend + 公共符号（运行时函数重导出，供 Updater / 测试直接用）。
+from ._backend import MacOSBackend
+from ._delegates import Decision, UpdaterDelegate, make_delegate_adapter
+from ._runtime import (
+    Subscription,
+    assert_main_thread,
+    bundle_info_plist,
+    get_kvo_observer_class,
+    host_bundle_path,
+    in_app_bundle,
+    on_main_thread,
+)
+
+__all__ = [
+    "MacOSBackend",
+    "UpdaterDelegate",
+    "Decision",
+    "Subscription",
+    "make_delegate_adapter",
+    "assert_main_thread",
+    "on_main_thread",
+    "host_bundle_path",
+    "in_app_bundle",
+    "bundle_info_plist",
+    "get_kvo_observer_class",
+]

sparklehelper-0.1.0.data/purelib/sparklehelper/_backend/_macos/_backend.py

@@ -0,0 +1,377 @@
+"""macOS 更新后端：组合 Sparkle 加载、运行时基础设施与 delegate 桥接。
+
+:class:`MacOSBackend` 实现
+:class:`~sparklehelper._backend.base.UpdateBackend` 契约 + macOS 独有能力
+（KVO / system_profile / 24+ delegate 方法）。它本身只持有 controller /
+updater 实例状态与 ObjC selector 调用，底层逻辑由同包的
+:mod:`._loading` / :mod:`._runtime` / :mod:`._delegates` 提供。
+
+所有方法**必须在主线程**调用（``Updater`` Facade 统一断言）。
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Callable, Optional
+
+from ...errors import SparkleNotAvailableError
+from ...types import SystemProfileEntry, from_system_profile
+from ..base import Callbacks, UpdateConfig
+from . import _delegates, _loading, _runtime
+
+# Sparkle 2.9 明确声明为 KVO-compliant 的属性。
+_KVO_PROPERTIES: dict[str, tuple[str, Callable[[Any], Any]]] = {
+    "can_check_for_updates": ("canCheckForUpdates", bool),
+    "automatically_checks_for_updates": ("automaticallyChecksForUpdates", bool),
+    "update_check_interval": ("updateCheckInterval", float),
+    "automatically_downloads_updates": ("automaticallyDownloadsUpdates", bool),
+    "allows_automatic_updates": ("allowsAutomaticUpdates", bool),
+    "sends_system_profile": ("sendsSystemProfile", bool),
+}
+
+
+class MacOSBackend:
+    """macOS 更新后端：Sparkle.framework 的加载与 ObjC 桥接。
+
+    实现 :class:`~sparklehelper._backend.base.UpdateBackend` 契约 +
+    macOS 独有能力（KVO / system_profile / 24+ delegate 方法）。
+
+    所有方法**必须在主线程**调用（``Updater`` Facade 统一断言）。
+    """
+
+    # ------------------------------------------------------------------
+    # 进程级缓存管理（类方法，供测试与诊断）
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def is_loaded(cls) -> bool:
+        """Sparkle.framework 是否已成功加载。"""
+        return _loading.is_loaded()
+
+    @classmethod
+    def loaded_path(cls) -> Optional[str]:
+        """已加载 framework 的磁盘路径；未加载时为 None。"""
+        return _loading.loaded_path()
+
+    @classmethod
+    def _reset_for_test(cls) -> None:
+        """仅供测试：清空所有进程级缓存。"""
+        _loading.reset_for_test()
+
+    # 透传给 _loading，便于测试 patch（与原 _objc 模块函数签名一致）。
+    _main_bundle_frameworks_path = staticmethod(_loading.main_bundle_frameworks_path)
+    _resolve_framework_path = staticmethod(_loading.resolve_framework_path)
+    load_sparkle = staticmethod(_loading.load_sparkle)
+    get_sparkle = staticmethod(_loading.get_sparkle)
+
+    # ------------------------------------------------------------------
+    # ObjC 工具
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _look_up(sparkle_module: Any, class_name: str) -> Any:
+        """从已加载的 Sparkle module 取出类，先查 globals 再 lookUpClass 兜底。"""
+        cls = getattr(sparkle_module, class_name, None)
+        if cls is not None:
+            return cls
+        try:
+            import objc
+
+            return objc.lookUpClass(class_name)
+        except Exception as exc:  # noqa: BLE001
+            raise SparkleNotAvailableError(
+                f"Sparkle.framework loaded but cannot get class {class_name}: {exc}"
+            ) from exc
+
+    # ------------------------------------------------------------------
+    # 构造与生命周期（UpdateBackend Protocol）
+    # ------------------------------------------------------------------
+
+    def __init__(self) -> None:
+        self._controller: Any = None
+        self._updater: Any = None
+        self._delegate: Any = None
+        self._delegate_adapter: Any = None
+        self._started: bool = False
+
+    def configure(self, config: UpdateConfig) -> None:
+        """加载 Sparkle、创建 controller（复刻原 Updater.__init__ 创建链）。
+
+        顺序：load_sparkle → make_delegate_adapter → alloc().initWith...
+        selector 名 ``initWithStartingUpdater_updaterDelegate_userDriverDelegate_``
+        来自 framework introspection，不可改名。
+
+        ``delegate`` 通过 :attr:`UpdateConfig.delegate` 传入。
+        """
+        _runtime.assert_main_thread()
+
+        sparkle = self.get_sparkle()
+        SPUStandardUpdaterController = self._look_up(
+            sparkle, "SPUStandardUpdaterController"
+        )
+
+        delegate = config.delegate
+        self._delegate = delegate
+        delegate_adapter = _delegates.make_delegate_adapter(delegate)
+        self._delegate_adapter = delegate_adapter
+
+        self._controller = (
+            SPUStandardUpdaterController.alloc()
+            .initWithStartingUpdater_updaterDelegate_userDriverDelegate_(
+                False, delegate_adapter, None
+            )
+        )
+        if self._controller is None:
+            raise SparkleNotAvailableError(
+                "SPUStandardUpdaterController 初始化失败（返回 nil）。"
+                "请检查 Info.plist 是否包含 SUFeedURL、SUPublicEDKey、"
+                "CFBundleVersion 等必需字段。"
+            )
+        self._updater = self._controller.updater()
+
+    def register_callbacks(self, callbacks: Callbacks) -> None:
+        """注册跨平台回调集合。
+
+        macOS 后端通过 :class:`~._delegates.UpdaterDelegate` 体系接收回调。
+        粗粒度回调（error/found/no_update/cancelled）由 delegate 的对应方法
+        承载；此方法当前为 Protocol 完整性保留。
+        """
+        return
+
+    def start(self) -> None:
+        """启动更新检查调度器：``[controller startUpdater]``。幂等。"""
+        _runtime.assert_main_thread()
+        if self._controller is None:
+            raise SparkleNotAvailableError(
+                "后端尚未配置，请先调用 configure()。"
+            )
+        if self._started:
+            return
+        self._controller.startUpdater()
+        self._started = True
+
+    def cleanup(self) -> None:
+        """释放资源。macOS 下 Sparkle 无显式清理 API，空操作。"""
+        return
+
+    # ------------------------------------------------------------------
+    # 手动检查（UpdateBackend Protocol）
+    # ------------------------------------------------------------------
+
+    def check_for_updates(self) -> None:
+        """弹出标准更新窗口：``[controller checkForUpdates:nil]``。"""
+        _runtime.assert_main_thread()
+        self._controller.checkForUpdates_(None)
+
+    def check_for_updates_in_background(self) -> None:
+        """后台静默检查：``[updater checkForUpdatesInBackground]``。"""
+        _runtime.assert_main_thread()
+        self._updater.checkForUpdatesInBackground()
+
+    # ------------------------------------------------------------------
+    # macOS 独有检查方法
+    # ------------------------------------------------------------------
+
+    def check_for_update_information(self) -> None:
+        """仅拉取 appcast 信息，不触发起安装流程。"""
+        _runtime.assert_main_thread()
+        self._updater.checkForUpdateInformation()
+
+    def reset_update_cycle(self) -> None:
+        """重置自动检查计时，立即开始新一轮调度。"""
+        _runtime.assert_main_thread()
+        self._updater.resetUpdateCycle()
+
+    def reset_update_cycle_after_short_delay(self) -> None:
+        """短暂延迟后重置自动检查计时。"""
+        _runtime.assert_main_thread()
+        self._updater.resetUpdateCycleAfterShortDelay()
+
+    def clear_feed_url_from_user_defaults(self) -> Optional[str]:
+        """清除此前持久化的 feed URL，返回被清除的值。"""
+        _runtime.assert_main_thread()
+        url = self._updater.clearFeedURLFromUserDefaults()
+        if url is None:
+            return None
+        absolute_string = getattr(url, "absoluteString", None)
+        if callable(absolute_string):
+            value = absolute_string()
+            return str(value) if value else None
+        return str(url) or None
+
+    # ------------------------------------------------------------------
+    # 只读状态（UpdateBackend Protocol + SparkleExtras）
+    # ------------------------------------------------------------------
+
+    @property
+    def can_check_for_updates(self) -> bool:
+        _runtime.assert_main_thread()
+        return bool(self._updater.canCheckForUpdates())
+
+    @property
+    def session_in_progress(self) -> bool:
+        _runtime.assert_main_thread()
+        return bool(self._updater.sessionInProgress())
+
+    @property
+    def feed_url(self) -> Optional[str]:
+        _runtime.assert_main_thread()
+        url = self._updater.feedURL()
+        if url is None:
+            return None
+        if hasattr(url, "absoluteString"):
+            abs_str = url.absoluteString()
+            return str(abs_str) if abs_str else None
+        return str(url) or None
+
+    @property
+    def host_bundle_path(self) -> str:
+        _runtime.assert_main_thread()
+        bundle = self._updater.hostBundle()
+        path = bundle.bundlePath() if bundle is not None else None
+        return str(path) if path else ""
+
+    @property
+    def last_update_check_date(self) -> Optional[datetime]:
+        _runtime.assert_main_thread()
+        date = self._updater.lastUpdateCheckDate()
+        if date is None:
+            return None
+        try:
+            ts = float(date.timeIntervalSince1970())
+        except (AttributeError, TypeError, ValueError):
+            return None
+        return datetime.fromtimestamp(ts, tz=timezone.utc)
+
+    @property
+    def system_profile(self) -> list[SystemProfileEntry]:
+        _runtime.assert_main_thread()
+        entries = self._updater.systemProfileArray()
+        return from_system_profile(entries)
+
+    @property
+    def allows_automatic_updates(self) -> bool:
+        _runtime.assert_main_thread()
+        return bool(self._updater.allowsAutomaticUpdates())
+
+    @property
+    def automatically_downloads_updates(self) -> bool:
+        _runtime.assert_main_thread()
+        return bool(self._updater.automaticallyDownloadsUpdates())
+
+    @automatically_downloads_updates.setter
+    def automatically_downloads_updates(self, value: bool) -> None:
+        _runtime.assert_main_thread()
+        self._updater.setAutomaticallyDownloadsUpdates_(bool(value))
+
+    # ------------------------------------------------------------------
+    # 可读写状态（UpdateBackend Protocol + SparkleExtras）
+    # ------------------------------------------------------------------
+
+    @property
+    def automatically_checks_for_updates(self) -> bool:
+        _runtime.assert_main_thread()
+        return bool(self._updater.automaticallyChecksForUpdates())
+
+    @automatically_checks_for_updates.setter
+    def automatically_checks_for_updates(self, value: bool) -> None:
+        _runtime.assert_main_thread()
+        self._updater.setAutomaticallyChecksForUpdates_(bool(value))
+
+    @property
+    def update_check_interval(self) -> float:
+        _runtime.assert_main_thread()
+        return float(self._updater.updateCheckInterval())
+
+    @update_check_interval.setter
+    def update_check_interval(self, seconds: float) -> None:
+        _runtime.assert_main_thread()
+        self._updater.setUpdateCheckInterval_(float(seconds))
+
+    @property
+    def http_headers(self) -> Optional[dict[str, str]]:
+        _runtime.assert_main_thread()
+        headers = self._updater.httpHeaders()
+        if headers is None:
+            return None
+        return {str(k): str(v) for k, v in headers.items()}
+
+    @http_headers.setter
+    def http_headers(self, headers: Optional[dict[str, str]]) -> None:
+        _runtime.assert_main_thread()
+        if headers is None:
+            self._updater.setHttpHeaders_(None)
+            return
+        from Foundation import NSDictionary
+
+        ns_dict = NSDictionary.dictionaryWithDictionary_(
+            {str(k): str(v) for k, v in headers.items()}
+        )
+        self._updater.setHttpHeaders_(ns_dict)
+
+    @property
+    def user_agent_string(self) -> str:
+        _runtime.assert_main_thread()
+        value = self._updater.userAgentString()
+        return str(value) if value else ""
+
+    @user_agent_string.setter
+    def user_agent_string(self, value: str) -> None:
+        _runtime.assert_main_thread()
+        self._updater.setUserAgentString_(str(value))
+
+    @property
+    def sends_system_profile(self) -> bool:
+        _runtime.assert_main_thread()
+        return bool(self._updater.sendsSystemProfile())
+
+    @sends_system_profile.setter
+    def sends_system_profile(self, value: bool) -> None:
+        _runtime.assert_main_thread()
+        self._updater.setSendsSystemProfile_(bool(value))
+
+    # ------------------------------------------------------------------
+    # KVO 订阅
+    # ------------------------------------------------------------------
+
+    def observe(
+        self, property_name: str, callback: Callable[[Any], None]
+    ) -> "_runtime.Subscription":
+        """订阅 Sparkle 公开的 KVO 属性。订阅建立后立即回调一次。"""
+        _runtime.assert_main_thread()
+        try:
+            key_path, converter = _KVO_PROPERTIES[property_name]
+        except KeyError as exc:
+            supported = ", ".join(sorted(_KVO_PROPERTIES))
+            raise ValueError(
+                f"unsupported observable property {property_name!r}; "
+                f"available: {supported}"
+            ) from exc
+
+        target = self._updater
+        observer_cls = _runtime.get_kvo_observer_class()
+
+        def wrapped(new_value: Any) -> None:
+            if new_value is not None:
+                callback(converter(new_value))
+
+        observer = observer_cls.alloc().initWithCallback_target_keyPath_(
+            wrapped, target, key_path
+        )
+        from Foundation import (
+            NSKeyValueObservingOptionInitial,
+            NSKeyValueObservingOptionNew,
+        )
+
+        options = NSKeyValueObservingOptionNew | NSKeyValueObservingOptionInitial
+        target.addObserver_forKeyPath_options_context_(observer, key_path, options, 0)
+        return _runtime.Subscription(observer=observer, target=target, key_path=key_path)
+
+    def observe_can_check_for_updates(
+        self, callback: Callable[[bool], None]
+    ) -> "_runtime.Subscription":
+        """订阅 ``canCheckForUpdates`` 变化（便捷封装）。"""
+        return self.observe("can_check_for_updates", callback)
+
+
+__all__ = ["MacOSBackend"]