partial-backup 0.0.2__tar.gz → 0.1.1__tar.gz

{partial_backup-0.0.2 → partial_backup-0.1.1}/.github/workflows/python-app.yml

@@ -5,7 +5,8 @@ on:
     branches: [ "master" ]
     paths:
       - '.github/workflows/python-app.yml'
-      - 'pymobiledevice3/**'
+      - 'partial_backup/**'
+      - 'tests/**'
       - 'requirements.txt'
       - 'pyproject.toml'
   release:
@@ -43,3 +44,5 @@ jobs:
           python -m pip install -U '.[test]'
       - name: Test show usage
         run: partial-backup --help
+      - name: Run tests
+        run: python -m pytest tests

partial_backup-0.1.1/.github/workflows/python-publish.yml

@@ -0,0 +1,29 @@
+# This workflow builds and uploads the Python package to PyPI when a release is created
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [ created ]
+
+jobs:
+  deploy:
+    permissions:
+      id-token: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # setuptools_scm needs full history + tags to derive the release version
+          # from the tag; a shallow clone yields a PyPI-rejected local version
+          # like 0.1.dev1+g<hash>.
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Build distributions
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+          verbose: true

partial_backup-0.1.1/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: partial-backup
+Version: 0.1.1
+Summary: Metadata-Aware Partial Backup Creator
+Project-URL: Homepage, https://github.com/doronz88/partial-backup
+Project-URL: Bug Reports, https://github.com/doronz88/partial-backup/issues
+Keywords: ios,backup,partial-backup
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: rich
+Requires-Dist: typer
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+
+# 🗂️ partial-backup: Metadata-Aware Partial Backup Creator
+
+This utility scans a given directory in a structured *"unbacked"* format and generates a `Backup` object that can be
+written back as a valid backup. It preserves directory and file metadata such as ownership (`user_`), group (`group_`),
+and file mode (`mode_`), and skips common junk files.
+
+---
+
+## 📦 Features
+
+- Recursively scans a directory organized by *domain* (e.g., `HomeDomain`)
+- Supports embedded metadata in directory names (`user_501_group_0_mode_755`)
+- Preserves and serializes:
+  - File contents
+  - Directory structure
+  - Ownership and permissions
+- Skips system-specific noise like `.DS_Store` and `Thumbs.db`
+- Outputs a fully reconstructable `Backup` object
+- Simple CLI using [Typer](https://typer.tiangolo.com/)
+
+---
+
+## 🛠️ Installation
+
+```bash
+pip install partial-backup
+```
+
+## 🧪 Example Usage
+
+Assume your source directory is structured like this:
+
+```none
+unback/HomeDomain/
+└── Library
+    └── Preferences/
+        └── com.example.settings.plist
+```
+
+To generate the backup:
+
+```shell
+partial-backup unback/ output/
+```
+
+It will:
+
+- Detect `HomeDomain`
+- Extract user/group/mode/protection class from directories like `user_501_group_0_mode_755`
+- List every parent directory, including the domain root, so the device can create them
+- Write an iOS 10+ backup (`Manifest.db`) into `output/partial-backup/`
+
+### Matching the device exactly
+
+The device applies the owner, mode and data protection class listed in the backup, including to directories that
+already exist. The built-in defaults follow a real iOS 27.2 backup, but for exact values take a small backup of the
+same area from the target device and pass it as a reference:
+
+```shell
+pymobiledevice3 backup2 backup bk/ --full --only sms
+partial-backup unback/ output/ --reference bk/<UDID>
+```
+
+Entries present in the reference keep its attributes (explicit metadata hints still win), and the device's own
+`Info.plist`/`Manifest.plist` metadata and keybag are reused.
+
+## ♻️ Restore the Backup
+
+The generated backup is compatible with [pymobiledevice3](https://github.com/doronz88/pymobiledevice3), and can be
+restored to an iOS device without a full erase. Installed apps stay installed:
+
+```shell
+pymobiledevice3 backup2 restore output/ --source partial-backup --no-copy --system --no-remove --skip-apps
+```
+
+> [!WARNING]
+> A restore is not additive, even with `--no-remove`. On every restore the device replaces these paths with the
+> backup's contents, deleting anything there the backup doesn't contain:
+>
+> - `HomeDomain`: `Library/Preferences`, `Library/AddressBook`, `Library/Calendar`, `Library/Notes`,
+>   `Library/SMS/sms.db`, `Library/Voicemail`, `Library/Cookies`, `Library/Safari/Bookmarks.db`,
+>   `Library/WebKit/Databases`, `Library/Caches/com.apple.WebAppCache`
+> - `CameraRollDomain`: `Media/PhotoData` (the Photos library database)
+> - every restored app container (`AppDomain-*`, `AppDomainGroup-*`, `AppDomainPlugin-*`), as a whole
+>
+> To change one of these on a device whose data matters, take a fresh backup of that device first and include its
+> full current contents for each path, with your changes applied.
+
+- `--system` is required unless `--reference` was used: `HomeDomain`, `MediaDomain` and the other domains in the
+  device's `MobileBackup.framework/Domains.plist` are "system domains", and the device skips them unless the host asks
+  for system files or the backup's `Lockdown.DeviceClass` matches the device.
+- The device restores only what its `Domains.plist` allows. Paths outside a domain's rules (e.g. anything in
+  `MediaDomain` other than its `RelativePathsToBackupAndRestore`, such as `Media/Recordings` or
+  `Library/SMS/Attachments`) and some whole domains (e.g.
+  `SysSharedContainerDomain-systemgroup.com.apple.configurationprofiles`) are skipped silently: the restore still
+  reports success.
+- App containers (`AppDomain-<bundle id>`, `AppDomainGroup-<group id>`, `AppDomainPlugin-<bundle id>`) of installed
+  apps are restored too; their identifiers are listed in `Manifest.plist`'s `Applications` automatically, since the
+  device skips app domains that aren't listed there. A container of an app that isn't installed is set aside in
+  `/var/mobile/Library/SafeHarbor` instead.
+- The device reboots when done and shows the post-restore Setup Assistant screens; backups are refused
+  (`MBErrorDomain/212`) until they are completed. `--no-reboot` doesn't avoid this, it only postpones it.
+  Developer Mode is turned off; re-enable it with `pymobiledevice3 amfi enable-developer-mode`.
+
+For iOS 9 and older, `--legacy` writes the old `Manifest.mbdb` format directly into `output/`.
+
+## 📁 Metadata Syntax
+
+This tool supports optional metadata hints in folder names:
+
+| Syntax                               | Meaning                               |
+|--------------------------------------|---------------------------------------|
+| `user_501`                           | File owned by user `501`              |
+| `group_20`                           | File belongs to group `20`            |
+| `mode_755`                           | File or directory mode                |
+| `class_4`                            | Data protection class                 |
+| `user_501_group_20_mode_644_class_3` | All of the above                      |
+
+These metadata markers are automatically removed from paths and applied to the entries below them. Without hints,
+files are `0644`, directories `0755`, files use protection class `3`, and the owner is `mobile` (`501`) for domains
+under `/var/mobile` (`HomeDomain`, `AppDomain-*`, ...) and `root` otherwise.
+
+## ⛔ Ignored Files
+
+The following files and folders are skipped automatically:
+
+- `.DS_Store`
+- `Thumbs.db`
+- `desktop.ini`
+- `.Spotlight-V100`
+- `.Trashes`
+
+## API Overview
+
+```python
+from pathlib import Path
+from partial_backup.backup import Backup
+
+backup = Backup.create_backup_from_directory(Path('/path/to/unback'))
+backup.write_to_directory(Path('/path/to/output'))  # -> /path/to/output/partial-backup
+```
+
+## 🙏 Acknowledgments
+
+Huge thanks to [@JJTech0130](https://github.com/JJTech0130) for his insights and foundational work on the backup DB
+implementation.

partial_backup-0.1.1/README.md

@@ -0,0 +1,146 @@
+# 🗂️ partial-backup: Metadata-Aware Partial Backup Creator
+
+This utility scans a given directory in a structured *"unbacked"* format and generates a `Backup` object that can be
+written back as a valid backup. It preserves directory and file metadata such as ownership (`user_`), group (`group_`),
+and file mode (`mode_`), and skips common junk files.
+
+---
+
+## 📦 Features
+
+- Recursively scans a directory organized by *domain* (e.g., `HomeDomain`)
+- Supports embedded metadata in directory names (`user_501_group_0_mode_755`)
+- Preserves and serializes:
+  - File contents
+  - Directory structure
+  - Ownership and permissions
+- Skips system-specific noise like `.DS_Store` and `Thumbs.db`
+- Outputs a fully reconstructable `Backup` object
+- Simple CLI using [Typer](https://typer.tiangolo.com/)
+
+---
+
+## 🛠️ Installation
+
+```bash
+pip install partial-backup
+```
+
+## 🧪 Example Usage
+
+Assume your source directory is structured like this:
+
+```none
+unback/HomeDomain/
+└── Library
+    └── Preferences/
+        └── com.example.settings.plist
+```
+
+To generate the backup:
+
+```shell
+partial-backup unback/ output/
+```
+
+It will:
+
+- Detect `HomeDomain`
+- Extract user/group/mode/protection class from directories like `user_501_group_0_mode_755`
+- List every parent directory, including the domain root, so the device can create them
+- Write an iOS 10+ backup (`Manifest.db`) into `output/partial-backup/`
+
+### Matching the device exactly
+
+The device applies the owner, mode and data protection class listed in the backup, including to directories that
+already exist. The built-in defaults follow a real iOS 27.2 backup, but for exact values take a small backup of the
+same area from the target device and pass it as a reference:
+
+```shell
+pymobiledevice3 backup2 backup bk/ --full --only sms
+partial-backup unback/ output/ --reference bk/<UDID>
+```
+
+Entries present in the reference keep its attributes (explicit metadata hints still win), and the device's own
+`Info.plist`/`Manifest.plist` metadata and keybag are reused.
+
+## ♻️ Restore the Backup
+
+The generated backup is compatible with [pymobiledevice3](https://github.com/doronz88/pymobiledevice3), and can be
+restored to an iOS device without a full erase. Installed apps stay installed:
+
+```shell
+pymobiledevice3 backup2 restore output/ --source partial-backup --no-copy --system --no-remove --skip-apps
+```
+
+> [!WARNING]
+> A restore is not additive, even with `--no-remove`. On every restore the device replaces these paths with the
+> backup's contents, deleting anything there the backup doesn't contain:
+>
+> - `HomeDomain`: `Library/Preferences`, `Library/AddressBook`, `Library/Calendar`, `Library/Notes`,
+>   `Library/SMS/sms.db`, `Library/Voicemail`, `Library/Cookies`, `Library/Safari/Bookmarks.db`,
+>   `Library/WebKit/Databases`, `Library/Caches/com.apple.WebAppCache`
+> - `CameraRollDomain`: `Media/PhotoData` (the Photos library database)
+> - every restored app container (`AppDomain-*`, `AppDomainGroup-*`, `AppDomainPlugin-*`), as a whole
+>
+> To change one of these on a device whose data matters, take a fresh backup of that device first and include its
+> full current contents for each path, with your changes applied.
+
+- `--system` is required unless `--reference` was used: `HomeDomain`, `MediaDomain` and the other domains in the
+  device's `MobileBackup.framework/Domains.plist` are "system domains", and the device skips them unless the host asks
+  for system files or the backup's `Lockdown.DeviceClass` matches the device.
+- The device restores only what its `Domains.plist` allows. Paths outside a domain's rules (e.g. anything in
+  `MediaDomain` other than its `RelativePathsToBackupAndRestore`, such as `Media/Recordings` or
+  `Library/SMS/Attachments`) and some whole domains (e.g.
+  `SysSharedContainerDomain-systemgroup.com.apple.configurationprofiles`) are skipped silently: the restore still
+  reports success.
+- App containers (`AppDomain-<bundle id>`, `AppDomainGroup-<group id>`, `AppDomainPlugin-<bundle id>`) of installed
+  apps are restored too; their identifiers are listed in `Manifest.plist`'s `Applications` automatically, since the
+  device skips app domains that aren't listed there. A container of an app that isn't installed is set aside in
+  `/var/mobile/Library/SafeHarbor` instead.
+- The device reboots when done and shows the post-restore Setup Assistant screens; backups are refused
+  (`MBErrorDomain/212`) until they are completed. `--no-reboot` doesn't avoid this, it only postpones it.
+  Developer Mode is turned off; re-enable it with `pymobiledevice3 amfi enable-developer-mode`.
+
+For iOS 9 and older, `--legacy` writes the old `Manifest.mbdb` format directly into `output/`.
+
+## 📁 Metadata Syntax
+
+This tool supports optional metadata hints in folder names:
+
+| Syntax                               | Meaning                               |
+|--------------------------------------|---------------------------------------|
+| `user_501`                           | File owned by user `501`              |
+| `group_20`                           | File belongs to group `20`            |
+| `mode_755`                           | File or directory mode                |
+| `class_4`                            | Data protection class                 |
+| `user_501_group_20_mode_644_class_3` | All of the above                      |
+
+These metadata markers are automatically removed from paths and applied to the entries below them. Without hints,
+files are `0644`, directories `0755`, files use protection class `3`, and the owner is `mobile` (`501`) for domains
+under `/var/mobile` (`HomeDomain`, `AppDomain-*`, ...) and `root` otherwise.
+
+## ⛔ Ignored Files
+
+The following files and folders are skipped automatically:
+
+- `.DS_Store`
+- `Thumbs.db`
+- `desktop.ini`
+- `.Spotlight-V100`
+- `.Trashes`
+
+## API Overview
+
+```python
+from pathlib import Path
+from partial_backup.backup import Backup
+
+backup = Backup.create_backup_from_directory(Path('/path/to/unback'))
+backup.write_to_directory(Path('/path/to/output'))  # -> /path/to/output/partial-backup
+```
+
+## 🙏 Acknowledgments
+
+Huge thanks to [@JJTech0130](https://github.com/JJTech0130) for his insights and foundational work on the backup DB
+implementation.

partial_backup-0.1.1/partial_backup/__main__.py

@@ -0,0 +1,48 @@
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from rich import print
+
+from partial_backup.backup import DEFAULT_IDENTIFIER, Backup, ReferenceBackup
+
+
+def create_backup_directory(
+    source: Path,
+    output: Path,
+    identifier: Annotated[str, typer.Option(
+        help="Name of the backup directory created under OUTPUT; pass it to `backup2 restore --source`.")
+    ] = DEFAULT_IDENTIFIER,
+    reference: Annotated[Optional[Path], typer.Option(
+        help="A real backup's <UDID> directory taken from the target device (e.g. "
+             "`pymobiledevice3 backup2 backup --only sms`). Its device metadata and the exact attributes of matching "
+             "entries are reused.")
+    ] = None,
+    legacy: Annotated[bool, typer.Option(
+        help="Write the legacy iOS <= 9 format (Manifest.mbdb) directly into OUTPUT.")
+    ] = False,
+) -> None:
+    """
+    Construct a backup directory from a given source directory given in an `unback` format
+    """
+    backup = Backup.create_backup_from_directory(source, ReferenceBackup.load(reference) if reference else None)
+    print(f"Constructing the following backup structure into: {output}")
+    print(backup.files)
+    if legacy:
+        backup.write_legacy_to_directory(output)
+        restore_source = "."
+    else:
+        backup.write_to_directory(output, identifier)
+        restore_source = identifier
+    print("[bold][green]Done![/green][/bold]")
+    print("[bold]Consider restoring this backup using:[/bold]")
+    print(f"[magenta]pymobiledevice3 backup2 restore {output} --source {restore_source} --no-copy --system "
+          f"--no-remove --skip-apps[/magenta]")
+
+
+def cli() -> None:
+    typer.run(create_backup_directory)
+
+
+if __name__ == "__main__":
+    cli()

partial_backup-0.1.1/partial_backup/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.1'
+__version_tuple__ = version_tuple = (0, 1, 1)
+
+__commit_id__ = commit_id = 'gfa08fb7c2'