flatback 1.0__py3-none-any.whl

flatback/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0"

flatback/__main__.py

@@ -0,0 +1,48 @@
+import argparse
+import sys
+from .core import Backup, Restore
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        prog="flatback",
+        description="Backup and restore Flatpak applications for offline transfer",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    backup = sub.add_parser("backup", help="Backup a Flatpak application")
+    backup.add_argument("app_id", help="Flatpak application ID (e.g. org.yuzu_emu.yuzu)")
+    backup.add_argument("-o", "--output", help="Output path (default: <app_id>.tar.gz)")
+    backup.add_argument("--no-tar", action="store_true", help="Save as directory instead of tar.gz")
+    backup.add_argument("--data", action="store_true", help="Include user data (~/.var/app/<app_id>) in backup")
+    backup.add_argument("--system", action="store_true", help="Use system installation instead of user")
+
+    restore = sub.add_parser("restore", help="Restore a Flatpak application from backup")
+    restore.add_argument("source", help="Path to backup tar.gz or directory")
+    restore.add_argument("--data", action="store_true", default=None, help="Restore user data without prompting")
+    restore.add_argument("--no-data", action="store_true", help="Skip user data restore without prompting")
+    restore.add_argument("--system", action="store_true", help="Install to system instead of user")
+
+    return parser.parse_args()
+
+
+def main():
+    args = parse_args()
+    installation = "system" if args.system else "user"
+
+    if args.command == "backup":
+        bk = Backup(args.app_id, installation)
+        bk.create(output_path=args.output, as_tar=not args.no_tar, include_data=args.data)
+
+    elif args.command == "restore":
+        restore_data = None
+        if args.data:
+            restore_data = True
+        elif args.no_data:
+            restore_data = False
+        rs = Restore(installation, restore_data=restore_data)
+        rs.load(args.source)
+
+
+if __name__ == "__main__":
+    main()

flatback/core.py

@@ -0,0 +1,264 @@
+import subprocess
+import yaml
+import shutil
+import tarfile
+import tempfile
+from pathlib import Path
+
+from . import __version__
+
+
+class FlatpakRef:
+    def __init__(self, app_id, arch="x86_64", branch="stable", origin="flathub", installation="user"):
+        self.app_id = app_id
+        self.arch = arch
+        self.branch = branch
+        self.origin = origin
+        self.installation = installation
+
+    @property
+    def ref(self):
+        return f"{self.app_id}/{self.arch}/{self.branch}"
+
+    def as_dict(self):
+        return {
+            "app_id": self.app_id,
+            "arch": self.arch,
+            "branch": self.branch,
+            "origin": self.origin,
+            "installation": self.installation,
+        }
+
+    @classmethod
+    def from_dict(cls, d):
+        return cls(**d)
+
+
+class FlatpakQuery:
+    def __init__(self, installation="user"):
+        self._install_flag = f"--{installation}"
+
+    def _run(self, args):
+        result = subprocess.run(
+            ["flatpak"] + args,
+            capture_output=True, text=True, check=True,
+        )
+        return result.stdout.strip()
+
+    def app_info(self, app_id):
+        raw = self._run(["info", self._install_flag, app_id])
+        info = {}
+        for line in raw.splitlines():
+            if ":" in line:
+                key, _, val = line.partition(":")
+                info[key.strip()] = val.strip()
+        return info
+
+    def app_ref(self, app_id):
+        info = self.app_info(app_id)
+        ref_str = info.get("Ref", "")
+        parts = ref_str.split("/")
+        return FlatpakRef(
+            app_id=parts[1] if len(parts) > 1 else app_id,
+            arch=parts[2] if len(parts) > 2 else "x86_64",
+            branch=parts[3] if len(parts) > 3 else "stable",
+            origin=info.get("Origin", "flathub"),
+            installation="user" if self._install_flag == "--user" else "system",
+        )
+
+    def runtime_ref(self, app_id):
+        raw = self._run(["info", self._install_flag, "--show-runtime", app_id])
+        parts = raw.split("/")
+        return FlatpakRef(
+            app_id=parts[0],
+            arch=parts[1] if len(parts) > 1 else "x86_64",
+            branch=parts[2] if len(parts) > 2 else "stable",
+            origin="flathub",
+            installation="user" if self._install_flag == "--user" else "system",
+        )
+
+    def repo_path(self, installation="user"):
+        if installation == "user":
+            return Path.home() / ".local/share/flatpak/repo"
+        return Path("/var/lib/flatpak/repo")
+
+
+class BundleBuilder:
+    def __init__(self, query: FlatpakQuery):
+        self.query = query
+
+    def build_bundle(self, ref: FlatpakRef, output_path: Path, is_runtime=False):
+        repo = self.query.repo_path(ref.installation)
+        args = [
+            "flatpak", "build-bundle",
+            str(repo), str(output_path),
+            ref.app_id, ref.branch,
+            f"--arch={ref.arch}",
+        ]
+        if is_runtime:
+            args.append("--runtime")
+        subprocess.run(args, check=True)
+
+
+class Backup:
+    MANIFEST = "flatback.yml"
+    DATA_DIR = "data"
+
+    def __init__(self, app_id, installation="user"):
+        self.app_id = app_id
+        self.installation = installation
+        self.query = FlatpakQuery(installation)
+        self.builder = BundleBuilder(self.query)
+
+    def _bundle_name(self, ref: FlatpakRef, is_runtime=False):
+        prefix = "runtime" if is_runtime else "app"
+        return f"{prefix}_{ref.app_id}_{ref.arch}_{ref.branch}.flatpak"
+
+    def _user_data_path(self):
+        return Path.home() / ".var" / "app" / self.app_id
+
+    def create(self, output_path=None, as_tar=True, include_data=False):
+        app_ref = self.query.app_ref(self.app_id)
+        runtime_ref = self.query.runtime_ref(self.app_id)
+        app_info = self.query.app_info(self.app_id)
+
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_dir = Path(tmp)
+
+            app_bundle = self._bundle_name(app_ref)
+            runtime_bundle = self._bundle_name(runtime_ref, is_runtime=True)
+
+            print(f"Bundling app: {app_ref.ref}")
+            self.builder.build_bundle(app_ref, tmp_dir / app_bundle)
+
+            print(f"Bundling runtime: {runtime_ref.ref}")
+            self.builder.build_bundle(runtime_ref, tmp_dir / runtime_bundle, is_runtime=True)
+
+            has_data = False
+            if include_data:
+                has_data = self._copy_user_data(tmp_dir)
+
+            manifest = {
+                "app": app_ref.as_dict(),
+                "runtime": runtime_ref.as_dict(),
+                "app_bundle": app_bundle,
+                "runtime_bundle": runtime_bundle,
+                "version": app_info.get("Version", "unknown"),
+                "flatback_version": __version__,
+                "has_data": has_data,
+            }
+
+            with open(tmp_dir / self.MANIFEST, "w") as f:
+                yaml.dump(manifest, f, default_flow_style=False)
+
+            default_name = self.app_id
+            if as_tar:
+                out = Path(output_path or f"{default_name}.tar.gz")
+                self._pack_tar(tmp_dir, out)
+            else:
+                out = Path(output_path or default_name)
+                if out.exists():
+                    shutil.rmtree(out)
+                shutil.copytree(tmp_dir, out)
+
+            print(f"Backup saved to: {out}")
+            return out
+
+    def _copy_user_data(self, tmp_dir):
+        src = self._user_data_path()
+        if not src.exists():
+            print(f"No user data found at: {src}")
+            return False
+        dst = tmp_dir / self.DATA_DIR
+        print(f"Copying user data: {src}")
+        shutil.copytree(src, dst, symlinks=True)
+        return True
+
+    def _pack_tar(self, source_dir, tar_path):
+        with tarfile.open(tar_path, "w:gz") as tar:
+            for item in source_dir.iterdir():
+                tar.add(item, arcname=item.name)
+
+
+class Restore:
+    MANIFEST = "flatback.yml"
+    DATA_DIR = "data"
+
+    def __init__(self, installation="user", restore_data=None):
+        self.installation = installation
+        self._install_flag = f"--{installation}"
+        self._restore_data = restore_data
+
+    def load(self, source_path):
+        source = Path(source_path)
+        if source.is_file() and (source.suffix == ".gz" or source.name.endswith(".tar.gz")):
+            self._load_from_tar(source)
+        elif source.is_dir():
+            self._load_from_dir(source)
+        else:
+            raise ValueError(f"Unsupported source: {source}")
+
+    def _load_from_tar(self, tar_path):
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_dir = Path(tmp)
+            with tarfile.open(tar_path, "r:gz") as tar:
+                tar.extractall(tmp_dir, filter="data")
+            self._load_from_dir(tmp_dir)
+
+    def _load_from_dir(self, directory):
+        manifest_path = directory / self.MANIFEST
+        if not manifest_path.exists():
+            raise FileNotFoundError(f"Manifest not found: {manifest_path}")
+
+        with open(manifest_path) as f:
+            manifest = yaml.safe_load(f)
+
+        runtime_bundle = directory / manifest["runtime_bundle"]
+        app_bundle = directory / manifest["app_bundle"]
+
+        runtime_ref = FlatpakRef.from_dict(manifest["runtime"])
+        app_ref = FlatpakRef.from_dict(manifest["app"])
+
+        print(f"Installing runtime: {runtime_ref.ref}")
+        self._install_bundle(runtime_bundle)
+
+        print(f"Installing app: {app_ref.ref}")
+        self._install_bundle(app_bundle)
+
+        if manifest.get("has_data"):
+            self._handle_user_data(directory, app_ref.app_id)
+
+        print(f"Restore complete: {app_ref.app_id}")
+
+    def _handle_user_data(self, directory, app_id):
+        data_dir = directory / self.DATA_DIR
+        if not data_dir.exists():
+            return
+
+        should_restore = self._restore_data
+        if should_restore is None:
+            answer = input("Backup contains user data. Restore it? [y/N] ").strip().lower()
+            should_restore = answer in ("y", "yes")
+
+        if not should_restore:
+            print("Skipping user data restore")
+            return
+
+        dst = Path.home() / ".var" / "app" / app_id
+        if dst.exists():
+            print(f"Replacing existing user data: {dst}")
+            shutil.rmtree(dst)
+        print(f"Restoring user data to: {dst}")
+        shutil.copytree(data_dir, dst, symlinks=True)
+
+    def _install_bundle(self, bundle_path):
+        result = subprocess.run(
+            ["flatpak", "install", self._install_flag, "--bundle", "-y", str(bundle_path)],
+            capture_output=True, text=True,
+        )
+        if result.returncode != 0:
+            if "already installed" in result.stderr:
+                print(f"Already installed, skipping: {bundle_path.name}")
+            else:
+                print(result.stderr)
+                raise subprocess.CalledProcessError(result.returncode, result.args)

flatback-1.0.dist-info/METADATA

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: flatback
+Version: 1.0
+Summary: Backup and restore Flatpak applications for offline transfer
+Home-page: https://github.com/jfhack/flatback
+Project-URL: Homepage, https://github.com/jfhack/flatback
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml
+Dynamic: home-page
+
+# Flatback
+
+This is a simple script utility to back up and restore Flatpak applications for offline transfer.
+
+Packages a Flatpak app together with its runtime into a single `.tar.gz` archive (or directory), including a YAML manifest. Ideal for moving apps to offline computers or preserving deprecated packages.
+
+## Install
+
+```sh
+pip install flatback
+```
+
+Requires `flatpak` to be installed on the system.
+
+## Usage
+
+### Backup
+
+```sh
+flatback backup org.popular.emulator
+flatback backup org.popular.emulator -o emulator-backup.tar.gz
+flatback backup com.slack.Slack --no-tar
+flatback backup com.google.Chrome --system
+flatback backup org.popular.emulator --data
+```
+
+### Restore
+
+```sh
+flatback restore org.popular.emulator.tar.gz
+flatback restore emulator-backup.tar.gz
+flatback restore com.slack.Slack/
+flatback restore com.google.Chrome.tar.gz --system
+flatback restore org.popular.emulator.tar.gz --data
+flatback restore org.popular.emulator.tar.gz --no-data
+```
+
+## How It Works
+
+**Backup** bundles the app and its runtime into `.flatpak` files using `flatpak build-bundle`, then packages everything with a `flatback.yml` manifest into a `.tar.gz`.
+
+**Restore** extracts the archive, reads the manifest, and installs the runtime and app bundles using `flatpak install --bundle`.
+
+### Manifest Example (`flatback.yml`)
+
+```yaml
+app:
+  app_id: org.popular.emulator
+  arch: x86_64
+  branch: stable
+  installation: user
+  origin: flathub
+app_bundle: app_org.popular.emulator_x86_64_stable.flatpak
+flatback_version: '1.0'
+has_data: true
+runtime:
+  app_id: org.kde.Platform
+  arch: x86_64
+  branch: 5.15-23.08
+  installation: user
+  origin: flathub
+runtime_bundle: runtime_org.kde.Platform_x86_64_5.15-23.08.flatpak
+version: mainline-0-1734
+```
+
+## Arguments
+
+### `flatback backup`
+
+| Argument | Description |
+|-|-|
+| `app_id` | Flatpak application ID (e.g. `org.popular.emulator`) |
+| `-o`, `--output` | Output path (default: `<app_id>.tar.gz`) |
+| `--no-tar` | Save as directory instead of tar.gz |
+| `--data` | Include user data (`~/.var/app/<app_id>`) in backup |
+| `--system` | Use system installation instead of user |
+
+### `flatback restore`
+
+| Argument | Description |
+|-|-|
+| `source` | Path to backup `.tar.gz` or directory |
+| `--data` | Restore user data without prompting |
+| `--no-data` | Skip user data restore without prompting |
+| `--system` | Install to system instead of user |

flatback-1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+flatback/__init__.py,sha256=kM55qqhSrc4b-StNTuN03Srg0kwfg1G4BckCKhUytaE,20
+flatback/__main__.py,sha256=f2t0CJ_zli1qxPPc5XKJc-RS-4O8TNgoedaG41qBtSw,1969
+flatback/core.py,sha256=hR1kwG-YiSS8XXGO3lucy0bISrhkbULyh1MBd5wLoSc,8938
+flatback-1.0.dist-info/METADATA,sha256=KNgcaOVGx0GV6DcJQ22q2oKtUYNsUGAJKzfs3N-qo60,2728
+flatback-1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+flatback-1.0.dist-info/entry_points.txt,sha256=q-sGWJ9YozIuZLp0eF6u5b8Trys_eUmlx92_pkHxe4Y,52
+flatback-1.0.dist-info/top_level.txt,sha256=2EfndshBwfueTm9DcMXk5MzsmJsJv2PBSISyAiZLUh4,9
+flatback-1.0.dist-info/RECORD,,

flatback-1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

flatback-1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+flatback = flatback.__main__:main

flatback-1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+flatback