pyludusavi 0.1.0__tar.gz

pyludusavi-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+**/__pycache__/
+*.pyc
+.ruff_cache/
+.pytest_cache/
+.cache/
+.venv/
+.venv
+dist/
+build/
+coverage.xml
+.coverage
+*.parquet
+/tmp/

pyludusavi-0.1.0/LICENSE

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

pyludusavi-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: pyludusavi
+Version: 0.1.0
+Summary: A robust, type-safe Python wrapper for the Ludusavi game backup tool.
+Project-URL: Homepage, https://github.com/beallio/pyludusavi
+Project-URL: Repository, https://github.com/beallio/pyludusavi
+Project-URL: Issues, https://github.com/beallio/pyludusavi/issues
+Author-email: David Beall <6121439+beallio@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Keywords: api,game-backup,gaming,ludusavi,wrapper
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: System :: Archiving :: Backup
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# pyludusavi
+
+A robust, type-safe Python wrapper for the [Ludusavi](https://github.com/mtkennerly/ludusavi) CLI.
+
+## Features
+
+- **Broad CLI Coverage**: Supports the core Ludusavi subcommands and commonly used flags.
+- **Linux-First**: Native support for both local binaries and Flatpak.
+- **Type-Safe**: Comprehensive `TypedDict` models for all JSON outputs (Python 3.12+).
+- **Dual-Mode Execution**: Transparently handles binary vs. Flatpak command prefixing.
+- **TDD-Backed**: High-quality implementation with an extensive regression suite.
+
+## Setup
+
+For local development, use the project wrapper so virtual environments and tool
+caches stay outside Dropbox:
+
+```bash
+source .envrc
+./run.sh uv sync
+```
+
+Run validation through the same wrapper:
+
+```bash
+./run.sh uv run ruff check .
+./run.sh uv run ty check src/
+./run.sh uv run pytest
+```
+
+## Installation
+
+Use `uv` when adding the package to another Python project:
+
+```bash
+uv add pyludusavi
+```
+
+## Quick Start
+
+### Basic Initialization
+The wrapper automatically discovers Ludusavi via `PATH` or Flatpak.
+
+```python
+from pyludusavi import Ludusavi
+
+lud = Ludusavi()
+print(f"Ludusavi version: {lud.version()}")
+```
+
+### Backing Up Games
+Perform a preview scan or a full backup.
+
+```python
+# Preview a backup for a specific game
+result = lud.backup(games=["The Witcher 3"], preview=True)
+
+# Access typed data
+for name, game in result.data["games"].items():
+    print(f"Game: {name}, Status: {game['change']}")
+```
+
+### Searching for Games
+Use Steam IDs or fuzzy matching to find games in the manifest.
+
+```python
+# Find by Steam ID
+result = lud.find(steam_id="292030")
+
+# Use fuzzy matching
+result = lud.find(games=["Witcher"], fuzzy=True)
+```
+
+### Advanced Usage
+
+#### Flatpak Support
+If you have Ludusavi installed via Flatpak, `pyludusavi` detects it automatically. You can also specify a custom binary path or Flatpak ID:
+
+```python
+lud = Ludusavi(explicit_path="/usr/bin/ludusavi")
+lud = Ludusavi(flatpak_id="com.github.mtkennerly.ludusavi")
+```
+
+#### Custom Config Directory
+```python
+lud = Ludusavi(config_dir="/home/user/my-ludusavi-config")
+```
+
+#### Bulk API
+For performance-critical bulk operations, use the native `api` subcommand:
+
+```python
+payload = {
+    "requests": [
+        {"kind": "backup", "games": ["Game 1"]},
+        {"kind": "backup", "games": ["Game 2"]}
+    ]
+}
+lud.bulk_api(payload)
+```
+
+#### Cloud Sync
+Use the upload/download helpers with the same common options exposed by the CLI.
+
+```python
+lud.cloud_upload(games=["The Witcher 3"], local="/backups", cloud="/cloud", preview=True)
+lud.cloud_download(games=["The Witcher 3"], force=True)
+```
+
+#### Wrap Game Launch
+Ludusavi requires either a direct game name or launcher inference when wrapping a command.
+
+```python
+lud.wrap(["./game.exe", "--windowed"], name="The Witcher 3")
+lud.wrap(["steam", "-applaunch", "292030"], infer="steam", force=True)
+```
+
+#### Game Aliases
+`add_game_alias()` updates Ludusavi's `customGames` configuration using only the Python standard library. It writes the updated config as JSON, which Ludusavi can read as YAML, but this does not preserve existing comments or formatting in `config.yaml`.
+
+## Error Handling
+
+- `LudusaviNotFoundError`: Raised if the executable or Flatpak isn't found.
+- `LudusaviExecutionError`: Raised if the process exits with a non-zero code.
+- `LudusaviContractError`: Raised if the CLI output is malformed or non-JSON when expected.
+
+## Dependency Requirements
+
+- Python 3.12+
+- uv
+- Ludusavi v0.31.0+
+- pytest, pytest-cov, ruff, and ty for local development
+
+## License
+
+MIT

pyludusavi-0.1.0/README.md

@@ -0,0 +1,136 @@
+# pyludusavi
+
+A robust, type-safe Python wrapper for the [Ludusavi](https://github.com/mtkennerly/ludusavi) CLI.
+
+## Features
+
+- **Broad CLI Coverage**: Supports the core Ludusavi subcommands and commonly used flags.
+- **Linux-First**: Native support for both local binaries and Flatpak.
+- **Type-Safe**: Comprehensive `TypedDict` models for all JSON outputs (Python 3.12+).
+- **Dual-Mode Execution**: Transparently handles binary vs. Flatpak command prefixing.
+- **TDD-Backed**: High-quality implementation with an extensive regression suite.
+
+## Setup
+
+For local development, use the project wrapper so virtual environments and tool
+caches stay outside Dropbox:
+
+```bash
+source .envrc
+./run.sh uv sync
+```
+
+Run validation through the same wrapper:
+
+```bash
+./run.sh uv run ruff check .
+./run.sh uv run ty check src/
+./run.sh uv run pytest
+```
+
+## Installation
+
+Use `uv` when adding the package to another Python project:
+
+```bash
+uv add pyludusavi
+```
+
+## Quick Start
+
+### Basic Initialization
+The wrapper automatically discovers Ludusavi via `PATH` or Flatpak.
+
+```python
+from pyludusavi import Ludusavi
+
+lud = Ludusavi()
+print(f"Ludusavi version: {lud.version()}")
+```
+
+### Backing Up Games
+Perform a preview scan or a full backup.
+
+```python
+# Preview a backup for a specific game
+result = lud.backup(games=["The Witcher 3"], preview=True)
+
+# Access typed data
+for name, game in result.data["games"].items():
+    print(f"Game: {name}, Status: {game['change']}")
+```
+
+### Searching for Games
+Use Steam IDs or fuzzy matching to find games in the manifest.
+
+```python
+# Find by Steam ID
+result = lud.find(steam_id="292030")
+
+# Use fuzzy matching
+result = lud.find(games=["Witcher"], fuzzy=True)
+```
+
+### Advanced Usage
+
+#### Flatpak Support
+If you have Ludusavi installed via Flatpak, `pyludusavi` detects it automatically. You can also specify a custom binary path or Flatpak ID:
+
+```python
+lud = Ludusavi(explicit_path="/usr/bin/ludusavi")
+lud = Ludusavi(flatpak_id="com.github.mtkennerly.ludusavi")
+```
+
+#### Custom Config Directory
+```python
+lud = Ludusavi(config_dir="/home/user/my-ludusavi-config")
+```
+
+#### Bulk API
+For performance-critical bulk operations, use the native `api` subcommand:
+
+```python
+payload = {
+    "requests": [
+        {"kind": "backup", "games": ["Game 1"]},
+        {"kind": "backup", "games": ["Game 2"]}
+    ]
+}
+lud.bulk_api(payload)
+```
+
+#### Cloud Sync
+Use the upload/download helpers with the same common options exposed by the CLI.
+
+```python
+lud.cloud_upload(games=["The Witcher 3"], local="/backups", cloud="/cloud", preview=True)
+lud.cloud_download(games=["The Witcher 3"], force=True)
+```
+
+#### Wrap Game Launch
+Ludusavi requires either a direct game name or launcher inference when wrapping a command.
+
+```python
+lud.wrap(["./game.exe", "--windowed"], name="The Witcher 3")
+lud.wrap(["steam", "-applaunch", "292030"], infer="steam", force=True)
+```
+
+#### Game Aliases
+`add_game_alias()` updates Ludusavi's `customGames` configuration using only the Python standard library. It writes the updated config as JSON, which Ludusavi can read as YAML, but this does not preserve existing comments or formatting in `config.yaml`.
+
+## Error Handling
+
+- `LudusaviNotFoundError`: Raised if the executable or Flatpak isn't found.
+- `LudusaviExecutionError`: Raised if the process exits with a non-zero code.
+- `LudusaviContractError`: Raised if the CLI output is malformed or non-JSON when expected.
+
+## Dependency Requirements
+
+- Python 3.12+
+- uv
+- Ludusavi v0.31.0+
+- pytest, pytest-cov, ruff, and ty for local development
+
+## License
+
+MIT

pyludusavi-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "pyludusavi"
+dynamic = ["version"]
+description = "A robust, type-safe Python wrapper for the Ludusavi game backup tool."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [
+    { name = "David Beall", email = "6121439+beallio@users.noreply.github.com" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Intended Audience :: Developers",
+    "Topic :: Games/Entertainment",
+    "Topic :: System :: Archiving :: Backup",
+]
+keywords = ["ludusavi", "game-backup", "wrapper", "api", "gaming"]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/beallio/pyludusavi"
+Repository = "https://github.com/beallio/pyludusavi"
+Issues = "https://github.com/beallio/pyludusavi/issues"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pyludusavi"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/pyludusavi",
+    "README.md",
+    "LICENSE",
+]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+cache-dir = "/tmp/pyludusavi/.uv_cache"
+
+[tool.ruff]
+line-length = 100
+cache-dir = "/tmp/pyludusavi/.ruff_cache"
+
+[tool.pytest.ini_options]
+addopts = "--cov=src --cov-report=term"
+cache_dir = "/tmp/pyludusavi/.pytest_cache"
+pythonpath = ["src"]
+
+[tool.coverage.run]
+data_file = "/tmp/pyludusavi/.coverage"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=5.0.0",
+    "ruff>=0.3.0",
+    "ty>=0.0.24",
+]

pyludusavi-0.1.0/src/pyludusavi/__init__.py

@@ -0,0 +1,15 @@
+from .main import Ludusavi
+from .core import LudusaviResponse, LudusaviError, LudusaviExecutionError, LudusaviContractError
+from .discovery import find_ludusavi, LudusaviNotFoundError
+from ._version import __version__
+
+__all__ = [
+    "Ludusavi",
+    "LudusaviResponse",
+    "LudusaviError",
+    "LudusaviExecutionError",
+    "LudusaviContractError",
+    "find_ludusavi",
+    "LudusaviNotFoundError",
+    "__version__",
+]

pyludusavi-0.1.0/src/pyludusavi/_version.py

@@ -0,0 +1,6 @@
+try:
+    from importlib.metadata import version, PackageNotFoundError
+
+    __version__ = version("pyludusavi")
+except PackageNotFoundError:
+    __version__ = "unknown"

pyludusavi-0.1.0/src/pyludusavi/core.py

@@ -0,0 +1,119 @@
+import subprocess
+import json
+import logging
+from typing import Any, Optional, Literal, Dict, TypeVar, Generic
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+class LudusaviError(Exception):
+    """Base exception for pyludusavi."""
+
+    pass
+
+
+class LudusaviExecutionError(LudusaviError):
+    """Raised when the Ludusavi process exits with a non-zero code."""
+
+    def __init__(self, command: list[str], returncode: int, stdout: str, stderr: str):
+        self.command = command
+        self.returncode = returncode
+        self.stdout = stdout
+        self.stderr = stderr
+        super().__init__(f"Ludusavi command {command} failed with exit code {returncode}: {stderr}")
+
+
+class LudusaviContractError(LudusaviError):
+    """Raised when the Ludusavi output does not match the expected contract (e.g. invalid JSON)."""
+
+    pass
+
+
+@dataclass
+class LudusaviResponse(Generic[T]):
+    """Container for Ludusavi command responses."""
+
+    data: T
+    raw: Any
+    warnings: str
+    command: list[str]
+
+
+class LudusaviExecutor:
+    """Engine for executing Ludusavi commands across different modes."""
+
+    def __init__(self, command_prefix: list[str]):
+        self.command_prefix = command_prefix
+
+    def execute(
+        self,
+        args: list[str],
+        mode: Literal["JSON", "TEXT", "SPAWN", "STDIN_JSON"] = "JSON",
+        input_data: Optional[Any] = None,
+        timeout: Optional[float] = 30.0,
+        env: Optional[Dict[str, str]] = None,
+        auto_api: bool = True,
+    ) -> Optional[LudusaviResponse]:
+        """
+        Execute a Ludusavi command.
+
+        Args:
+            args: Subcommand and flags.
+            mode: Execution mode (JSON, TEXT, SPAWN, STDIN_JSON).
+            input_data: Dictionary to be sent via stdin (only for STDIN_JSON).
+            timeout: Maximum time to wait for the process.
+            env: Environment variables for the subprocess.
+            auto_api: If True, automatically appends --api to JSON/STDIN_JSON modes.
+
+        Returns:
+            LudusaviResponse or None (for SPAWN mode).
+        """
+        full_cmd = self.command_prefix + args
+
+        # Append --api if mode involves JSON parsing
+        if auto_api and mode in ["JSON", "STDIN_JSON"] and "--api" not in full_cmd:
+            full_cmd.append("--api")
+
+        logger.debug(f"Executing Ludusavi command: {full_cmd}")
+
+        if mode == "SPAWN":
+            subprocess.Popen(full_cmd, env=env)
+            return None
+
+        stdin_content = None
+        if mode == "STDIN_JSON" and input_data is not None:
+            stdin_content = json.dumps(input_data)
+
+        try:
+            result = subprocess.run(
+                full_cmd,
+                input=stdin_content,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                env=env,
+            )
+        except subprocess.TimeoutExpired as e:
+            raise LudusaviError(f"Ludusavi command timed out after {timeout}s: {full_cmd}") from e
+
+        if result.returncode != 0:
+            raise LudusaviExecutionError(full_cmd, result.returncode, result.stdout, result.stderr)
+
+        if mode in ["JSON", "STDIN_JSON"]:
+            try:
+                data = json.loads(result.stdout)
+                return LudusaviResponse(
+                    data=data, raw=data, warnings=result.stderr, command=full_cmd
+                )
+            except json.JSONDecodeError as e:
+                raise LudusaviContractError(
+                    f"Failed to parse Ludusavi JSON output: {result.stdout}"
+                ) from e
+
+        # mode == "TEXT"
+        return LudusaviResponse(
+            data=result.stdout, raw=result.stdout, warnings=result.stderr, command=full_cmd
+        )

pyludusavi-0.1.0/src/pyludusavi/discovery.py

@@ -0,0 +1,71 @@
+import shutil
+import subprocess
+from typing import Optional
+
+
+class LudusaviNotFoundError(Exception):
+    """Raised when the Ludusavi executable or Flatpak could not be found."""
+
+    pass
+
+
+def find_ludusavi(
+    explicit_path: Optional[str] = None,
+    explicit_flatpak_id: Optional[str] = None,
+    flatpak_id: str = "com.github.mtkennerly.ludusavi",
+) -> list[str]:
+    """
+    Find the Ludusavi executable or Flatpak.
+
+    Precedence:
+    1. Explicit path.
+    2. Explicit Flatpak ID.
+    3. PATH lookup.
+    4. Default Flatpak ID lookup.
+
+    Returns:
+        list[str]: The command prefix to use for calling Ludusavi.
+
+    Raises:
+        LudusaviNotFoundError: If Ludusavi could not be found or verified.
+    """
+    # 1. Explicit path
+    if explicit_path:
+        if _verify([explicit_path]):
+            return [explicit_path]
+        raise LudusaviNotFoundError(
+            f"Explicitly provided Ludusavi path not found or invalid: {explicit_path}"
+        )
+
+    # 2. Explicit Flatpak ID
+    if explicit_flatpak_id:
+        prefix = ["flatpak", "run", explicit_flatpak_id]
+        if shutil.which("flatpak") and _verify(prefix):
+            return prefix
+        raise LudusaviNotFoundError(
+            f"Explicitly provided Ludusavi Flatpak ID not found or invalid: {explicit_flatpak_id}"
+        )
+
+    # 3. PATH lookup
+    path_lookup = shutil.which("ludusavi")
+    if path_lookup:
+        if _verify([path_lookup]):
+            return [path_lookup]
+
+    # 4. Flatpak ID lookup
+    flatpak_lookup = shutil.which("flatpak")
+    if flatpak_lookup:
+        prefix = ["flatpak", "run", flatpak_id]
+        if _verify(prefix):
+            return prefix
+
+    raise LudusaviNotFoundError("Ludusavi could not be found via PATH or Flatpak.")
+
+
+def _verify(prefix: list[str]) -> bool:
+    """Verify that the command prefix correctly calls Ludusavi."""
+    try:
+        result = subprocess.run(prefix + ["--version"], capture_output=True, text=True, check=False)
+        return result.returncode == 0
+    except (FileNotFoundError, PermissionError):
+        return False