pyupdator 0.1.0__py3-none-any.whl

examples/basic_usage.py

@@ -0,0 +1,66 @@
+"""
+examples/basic_usage.py — GUI-free example showing how to use pyupdator.
+
+This is the canonical example for a game launcher or other host project.
+
+    pip install pyupdator
+
+Usage:
+    python examples/basic_usage.py
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+
+# Ensure the local pyupdator package is importable when running from the repo.
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from pyupdator import Updater, UpdaterError, human_bytes
+
+
+def progress_callback(done: int, total: int, message: str = "") -> None:
+    """Host-provided progress callback."""
+    if total:
+        pct = done / total * 100
+        print(f"[{pct:6.2f}%] {message}  ({human_bytes(done)} / {human_bytes(total)})")
+    else:
+        print(f"{message}  ({human_bytes(done)})")
+
+
+def main() -> int:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+
+    # The host launcher decides install_dir and source.
+    install_dir = Path("C:/Oyun")  # <-- change to your game folder
+    source = "oyun.torrent"        # <-- change to your .torrent or HTTP URL
+
+    try:
+        updater = Updater(install_dir=str(install_dir), source=source)
+
+        # 1) Analyze what needs to be downloaded / verified.
+        plan = updater.analyze()
+        print("Analiz tamamlandı. Plan:", plan)
+
+        # 2) Apply the update, reporting progress back to the host.
+        updater.update(progress_callback=progress_callback)
+        print("Güncelleme tamamlandı.")
+
+        # 3) (Optional) verify the installed files against the torrent.
+        result = updater.verify()
+        print("Doğrulama sonucu:", result)
+
+    except UpdaterError as exc:
+        print(f"Hata: {exc}", file=sys.stderr)
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pyupdator/__init__.py

@@ -0,0 +1,410 @@
+"""
+pyupdator — Delta updater for games (Torrent and HTTP Zip support).
+
+Public API:
+
+    from pyupdator import Updater
+
+    updater = Updater(install_dir="C:/Oyun", source="oyun.torrent")
+    plan = updater.analyze()
+    updater.update(progress_callback=my_func)
+
+The ``pyupdator`` package contains NO tkinter / customtkinter / gui imports.
+GUI code lives in the separate ``pyupdator_gui`` package.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional, Union
+
+from .core import (
+    TorrentParser,
+    PieceMap,
+    DeltaPlan,
+    DeltaAnalyzer,
+    DeltaApplier,
+    Verifier,
+    TorrentError,
+    NeedDownloadError,
+    ZipDeltaEngine,
+    ZipEntry,
+    ZipIndex,
+    ZipDeltaError,
+    HttpRangeClient,
+    chunk_file,
+    generate_manifest,
+    manifest_stats,
+    BackendManager,
+    BackendInfo,
+    BackendScanResult,
+    BackendError,
+    PIECE_LEVEL,
+    FILE_LEVEL,
+    CHUNK_LEVEL,
+    AUTO_ORDER,
+    scan_backends,
+    get_backend_class,
+)
+from .utils import (
+    human_bytes,
+    sha1_hex,
+    sha256_file,
+    safe_join,
+    list_files,
+    read_json,
+    write_json,
+    load_config,
+    save_config,
+    UpdaterError,
+    DEFAULT_CONFIG,
+    CONFIG_PATH,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Updater",
+    "UpdaterError",
+    "TorrentError",
+    "NeedDownloadError",
+    "ZipDeltaError",
+    "BackendError",
+    # core classes
+    "TorrentParser",
+    "PieceMap",
+    "DeltaPlan",
+    "DeltaAnalyzer",
+    "DeltaApplier",
+    "Verifier",
+    "ZipDeltaEngine",
+    "ZipEntry",
+    "ZipIndex",
+    "HttpRangeClient",
+    "BackendManager",
+    "BackendInfo",
+    "BackendScanResult",
+    # constants
+    "PIECE_LEVEL",
+    "FILE_LEVEL",
+    "CHUNK_LEVEL",
+    "AUTO_ORDER",
+    # functions
+    "chunk_file",
+    "generate_manifest",
+    "manifest_stats",
+    "scan_backends",
+    "get_backend_class",
+    "human_bytes",
+    "sha1_hex",
+    "sha256_file",
+    "safe_join",
+    "list_files",
+    "read_json",
+    "write_json",
+    "load_config",
+    "save_config",
+    # version
+    "__version__",
+]
+
+# ---------------------------------------------------------------------------
+# Paket düzeyinde logger; host launcher kendi handler'ını ekleyebilir.
+# ---------------------------------------------------------------------------
+
+logger = logging.getLogger("pyupdator")
+_logger_initialized = False
+
+
+def _ensure_logging() -> None:
+    """Varsayılan logging yapılandırmasını tek seferlik kurar."""
+    global _logger_initialized
+    if _logger_initialized:
+        return
+    _logger_initialized = True
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+
+
+def set_log_level(level: Union[int, str]) -> None:
+    """Kütüphane genel log seviyesini ayarlar."""
+    _ensure_logging()
+    logger.setLevel(level)
+
+
+def add_log_handler(handler: logging.Handler) -> None:
+    """Host launcher'ın kendi log handler'ını ekler (ör. GUI konsolu)."""
+    _ensure_logging()
+    logger.addHandler(handler)
+
+
+def remove_log_handler(handler: logging.Handler) -> None:
+    """Önceden eklenen handler'ı çıkarır."""
+    logger.removeHandler(handler)
+
+
+# ---------------------------------------------------------------------------
+# Updater — Ana API sınıfı
+# ---------------------------------------------------------------------------
+
+
+class Updater:
+    """
+    Ana güncelleme motoru.
+
+    Sözleşme:
+
+        from pyupdator import Updater
+        updater = Updater(install_dir="C:/Oyun", source="oyun.torrent")
+        plan = updater.analyze()
+        updater.update(progress_callback=my_func)
+
+    ``source`` hem .torrent dosya yolu hem de http/https URL'i olabilir.
+    """
+
+    def __init__(
+        self,
+        install_dir: Union[str, Path],
+        source: Union[str, Path],
+        torrent_root: Optional[Union[str, Path]] = None,
+        source_dir: Optional[Union[str, Path]] = None,
+        allow_delete: bool = False,
+        do_backup: bool = True,
+        logger_cb: Optional[Callable[[str], None]] = None,
+        config: Optional[Dict[str, Any]] = None,
+    ):
+        self.install_dir = Path(install_dir).resolve()
+        self.source = str(source)
+        self.torrent_root = Path(torrent_root).resolve() if torrent_root else None
+        self.source_dir = Path(source_dir).resolve() if source_dir else None
+        self.allow_delete = allow_delete
+        self.do_backup = do_backup
+        self.logger_cb = logger_cb or (lambda msg: logger.info(msg))
+
+        self.config = config or load_config()
+
+        # Durum
+        self._plan: Optional[DeltaPlan] = None
+        _ensure_logging()
+
+        # Kaynak türünü belirle (http/https ise ZIP delta / CDC, değilse torrent)
+        self._is_http = self.source.startswith(("http://", "https://"))
+
+    # ------------------------------------------------------------------
+    # Günlükleme
+    # ------------------------------------------------------------------
+
+    def _log(self, msg: str) -> None:
+        self.logger_cb(msg)
+        logger.info(msg)
+
+    # ------------------------------------------------------------------
+    # Analyze
+    # ------------------------------------------------------------------
+
+    def analyze(self) -> Dict[str, Any]:
+        """
+        Kurulu klasörü kaynakla karşılaştırır ve güncelleme planı üretir.
+
+        Döner: plan sözlüğü (DeltaPlan.to_dict()).
+        """
+        if self._is_http:
+            return self._analyze_http()
+        return self._analyze_torrent()
+
+    def _analyze_torrent(self) -> Dict[str, Any]:
+        analyzer = DeltaAnalyzer(
+            installed_dir=self.install_dir,
+            torrent_path=self.source,
+            torrent_root=self.torrent_root,
+            logger=self._log,
+        )
+        plan = analyzer.analyze()
+        self._plan = plan
+        return plan.to_dict()
+
+    def _analyze_http(self) -> Dict[str, Any]:
+        """
+        HTTP kaynağı (ZIP) için analiz.
+
+        ZIP delta motoru kullanılarak uzak ZIP'in Central Directory'si
+        okunur ve yerel klasörle karşılaştırılır.
+        """
+        engine = ZipDeltaEngine(
+            url=self.source,
+            local_dir=self.install_dir,
+            logger_cb=self._log,
+        )
+        index = engine.fetch_index()
+        changed = engine.compare(index)
+
+        plan: Dict[str, Any] = {
+            "mode": "ZIP_DELTA",
+            "url": self.source,
+            "install_dir": str(self.install_dir),
+            "total_entries": len(index.entries),
+            "to_download": [e.to_dict() for e in changed],
+            "unchanged": [
+                e.to_dict() for e in index.entries
+                if not e.is_dir and e not in changed
+            ],
+            "stats": {
+                "total_compressed": index.total_compressed,
+                "changed_count": len(changed),
+            },
+        }
+        self._plan = plan  # type: ignore[assignment]
+        self._log(
+            f"HTTP ZIP analiz tamam: {len(changed)} dosya değişecek / "
+            f"{index.total_entries} toplam giriş"
+        )
+        return plan
+
+    # ------------------------------------------------------------------
+    # Update
+    # ------------------------------------------------------------------
+
+    def update(
+        self,
+        progress_callback: Optional[Callable[[int, int, str], None]] = None,
+        allow_delete: Optional[bool] = None,
+        do_backup: Optional[bool] = None,
+        dry_run: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Mevcut planı uygular.
+
+        Eğer ``analyze()`` henüz çağrılmadıysa otomatik olarak çağrılır.
+
+        Döner: uygulama özeti sözlüğü.
+        """
+        if self._plan is None:
+            self.analyze()
+
+        if self._is_http:
+            return self._update_http(progress_callback=progress_callback)
+
+        return self._update_torrent(
+            progress_callback=progress_callback,
+            allow_delete=allow_delete if allow_delete is not None else self.allow_delete,
+            do_backup=do_backup if do_backup is not None else self.do_backup,
+            dry_run=dry_run,
+        )
+
+    def _update_torrent(
+        self,
+        progress_callback: Optional[Callable[[int, int, str], None]] = None,
+        allow_delete: bool = False,
+        do_backup: bool = True,
+        dry_run: bool = False,
+    ) -> Dict[str, Any]:
+        plan = self._plan
+        assert plan is not None
+
+        def _cb(done: int, total: int, msg: str) -> None:
+            if progress_callback:
+                progress_callback(done, total, msg)
+            self._log(f"{msg} ({done}/{total})")
+
+        applier = DeltaApplier(
+            installed_dir=self.install_dir,
+            torrent_path=self.source,
+            source_dir=self.source_dir,
+            logger=self._log,
+        )
+        result = applier.apply_plan(
+            plan=plan,
+            allow_delete=allow_delete,
+            do_backup=do_backup,
+            dry_run=dry_run,
+        )
+        _cb(1, 1, "Güncelleme tamamlandı")
+        return result
+
+    def _update_http(
+        self,
+        progress_callback: Optional[Callable[[int, int, str], None]] = None,
+    ) -> Dict[str, Any]:
+        plan = self._plan
+        assert plan is not None and plan.get("mode") == "ZIP_DELTA"
+
+        engine = ZipDeltaEngine(
+            url=self.source,
+            local_dir=self.install_dir,
+            logger_cb=self._log,
+        )
+        index = engine.fetch_index()
+        changed_entries = [
+            ZipEntry(
+                name=e["name"],
+                compress_size=e.get("compress_size", 0),
+                file_size=e.get("file_size", 0),
+                crc32=int(e.get("crc32", 0), 16) if isinstance(e.get("crc32"), str) else int(e.get("crc32", 0)),
+                compress_type=e.get("compress_type", 0),
+                flag_bits=e.get("flag_bits", 0),
+                local_header_offset=e.get("local_header_offset", 0),
+            )
+            for e in plan.get("to_download", [])
+        ]
+
+        def _cb(done: int, total: int, msg: str) -> None:
+            if progress_callback:
+                progress_callback(done, total, msg)
+            self._log(f"{msg} ({done}/{total})")
+
+        result = engine.apply(
+            zip_index=index,
+            changed_entries=changed_entries,
+            progress_cb=_cb,
+        )
+        _cb(1, 1, "HTTP ZIP güncelleme tamamlandı")
+        return result
+
+    # ------------------------------------------------------------------
+    # Verify
+    # ------------------------------------------------------------------
+
+    def verify(
+        self,
+        against_dir: Optional[Union[str, Path]] = None,
+        backup_manifest: Optional[Dict[str, Any]] = None,
+        root_override: Optional[Union[str, Path]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Kurulu klasörü .torrent ile doğrular.
+
+        Döner: {"ok": bool, "errors": [...], ...}
+        """
+        if self._is_http:
+            raise UpdaterError("Doğrulama sadece .torrent kaynağı için desteklenir.")
+
+        verifier = Verifier(
+            installed_dir=self.install_dir,
+            torrent_path=self.source,
+            logger=self._log,
+        )
+        return verifier.verify(
+            against_dir=against_dir,
+            backup_manifest=backup_manifest,
+            root_override=root_override,
+        )
+
+    # ------------------------------------------------------------------
+    # Plan accessors
+    # ------------------------------------------------------------------
+
+    @property
+    def plan(self) -> Optional[Dict[str, Any]]:
+        """Son analyze() sonucu (dict) veya None."""
+        if self._plan is None:
+            return None
+        if isinstance(self._plan, DeltaPlan):
+            return self._plan.to_dict()
+        return self._plan
+
+    @property
+    def is_http(self) -> bool:
+        return self._is_http

pyupdator/core/__init__.py

@@ -0,0 +1,74 @@
+"""
+pyupdator.core — Güncelleme motoru.
+
+Paket içerisinde:
+    torrent.py        : .torrent parse, recheck, delta planı, in-place uygulama,
+                        doğrulama
+    zip_engine.py     : HTTP ZIP delta + CDC chunker
+    backend_manager.py: indirme backend tespiti ve seçimi
+"""
+
+from .torrent import (
+    TorrentParser,
+    PieceMap,
+    DeltaPlan,
+    DeltaAnalyzer,
+    DeltaApplier,
+    Verifier,
+    TorrentError,
+    NeedDownloadError,
+)
+from .zip_engine import (
+    ZipDeltaEngine,
+    ZipEntry,
+    ZipIndex,
+    ZipDeltaError,
+    HttpRangeClient,
+    chunk_file,
+    generate_manifest,
+    manifest_stats,
+)
+from .backend_manager import (
+    BackendManager,
+    BackendInfo,
+    BackendScanResult,
+    BackendError,
+    PIECE_LEVEL,
+    FILE_LEVEL,
+    CHUNK_LEVEL,
+    AUTO_ORDER,
+    scan_backends,
+    get_backend_class,
+)
+
+__all__ = [
+    # torrent
+    "TorrentParser",
+    "PieceMap",
+    "DeltaPlan",
+    "DeltaAnalyzer",
+    "DeltaApplier",
+    "Verifier",
+    "TorrentError",
+    "NeedDownloadError",
+    # zip_engine
+    "ZipDeltaEngine",
+    "ZipEntry",
+    "ZipIndex",
+    "ZipDeltaError",
+    "HttpRangeClient",
+    "chunk_file",
+    "generate_manifest",
+    "manifest_stats",
+    # backend_manager
+    "BackendManager",
+    "BackendInfo",
+    "BackendScanResult",
+    "BackendError",
+    "PIECE_LEVEL",
+    "FILE_LEVEL",
+    "CHUNK_LEVEL",
+    "AUTO_ORDER",
+    "scan_backends",
+    "get_backend_class",
+]