jellyplex-sync 0.3.4__tar.gz → 0.4.0__tar.gz

{jellyplex_sync-0.3.4 → jellyplex_sync-0.4.0}/PKG-INFO

@@ -1,25 +1,33 @@
 Metadata-Version: 2.4
 Name: jellyplex-sync
-Version: 0.3.4
+Version: 0.4.0
 Summary: Convert your media library between Jellyfin and Plex formats by creating a hard-linked mirror
+Keywords: plex,jellyfin,media-library,movies,sync,hardlink,mirror
 Author: Stefan Schönberger
 Author-email: Stefan Schönberger <stefan@sniner.dev>
 License-Expression: BSD-3-Clause
 License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Video
 Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/sniner/jellyplex-sync
+Project-URL: Repository, https://github.com/sniner/jellyplex-sync
+Project-URL: Issues, https://github.com/sniner/jellyplex-sync/issues
+Project-URL: Changelog, https://github.com/sniner/jellyplex-sync/blob/main/CHANGELOG.md
 Description-Content-Type: text/markdown
 
 # Bidirectional Movie Library Sync for Plex and Jellyfin
 
 Can't decide between Jellyfin and Plex? This tool might help. It synchronizes your **movie library** between Jellyfin and Plex formats in **both directions** — without duplicating any files. Instead, it uses **hardlinks** to mirror your collection efficiently, saving storage while keeping both libraries in sync.
 
-> ⚠️ **0.3.0 is another major rewrite.** The internals are reorganised into a clean `discover → plan → realize` pipeline with an immutable Plan as a first-class concept. User-visible: a new **`plan` subcommand** that shows what a sync would do (text or `--json`) without touching anything, and **video-level clashes now auto-resolve with a hash suffix** instead of aborting the movie. The `sync` and `diff` CLI is unchanged. If you depend on the old shape, **try the new version with `--dry-run` first**. Cautious users can pin to a `0.2.x` (or even `0.1.x`) release until they're comfortable. See the [CHANGELOG](./CHANGELOG.md) for the full migration notes.
-
 ## Overview
 
 The script scans the source library, parses each movie folder for metadata (title, year, optional provider ID), and reproduces the same directory structure in the target location. Rather than copying video files, it creates hard links to avoid extra storage usage. Asset folders (e.g., `extras`, `subtitles`) are also mirrored. Loose top-level files (posters, NFOs, subtitles) are synced 1:1 by default since 0.2.0. With `--delete`, any files or folders in the target that are no longer present in the source will be removed.
@@ -98,6 +106,15 @@ The first positional is the source library, the second is the target. By default
 
 Use `--copy` when source and target are on different filesystems (NAS to local disk, cross-pool moves, etc.). The size+mtime check makes re-runs cheap.
 
+#### Exit codes
+
+- `0` — sync completed (including "nothing to do").
+- `1` — setup error (missing directories, undecipherable format, hardlinks across
+  filesystem boundaries).
+- `2` — folder-level clash: the run was aborted, nothing was synced.
+- `3` — sync completed, but some items marked for removal could not be removed
+  (permissions, busy files); they remain in the target.
+
 #### Examples
 
 Mirror a Jellyfin library into a new Plex structure:
@@ -230,15 +247,15 @@ The schema (still evolving — pin a version when consuming):
 - `source` / `target`: `{path, format}` for each endpoint.
 - `dry_run` (sync only): whether the run was a preview.
 - `summary`: counters; the set of fields depends on the operation.
-  - sync: `movies_total`, `movies_processed`, `files_updated`, `files_removed`, `items_ignored`, `strays_in_target`, `clashes`.
+  - sync: `movies_total`, `movies_processed`, `files_updated`, `files_removed`, `remove_errors`, `items_ignored`, `strays_in_target`, `clashes`.
   - plan: `movies`, `folder_clashes`, `movie_clashes`, `translation_losses`, `ignored`.
 - `ignored`: list of source-side entries the scanner skipped, each `{path, name, reason}`.
 - `strays_in_target` (sync only): list of names found in target that aren't in source.
 - `translation_losses`: distinct `{kind, key, value, reason}` tuples for labels/attributes the target format can't express. Deduplicated — one entry per distinct loss, not per affected file.
-- `events` (sync only): flat array of per-file actions, each `{action, target, source?, context?}`. Actions are `link`, `replace`, `skip`, `remove`. For `remove`, `context` is `library_stray` / `movie_stray` / `asset_stray`. Action names are the same in `--dry-run` and real runs; the top-level `dry_run` flag tells you which mode you were in.
+- `events` (sync only): flat array of per-file actions, each `{action, target, source?, context?}`. Actions are `link`, `replace`, `skip`, `remove` — `link` covers every creation, including copies in `--copy` mode. For `remove`, `context` is `library_stray` / `movie_stray` / `asset_stray`. Action names are the same in `--dry-run` and real runs; the top-level `dry_run` flag tells you which mode you were in.
 - `clashes` (sync only): movie-level video clashes the disambiguator couldn't resolve at all. Normally empty since the hash-fallback resolves the practical cases.
 - `diff`-specific fields: `movies_only_in_source`, `movies_only_in_target`, `differing_movies`, `in_sync`.
-- `plan`-specific fields: `movies` (each with `videos`, `loose_files`, `assets`), `folder_clashes`, `movie_clashes`. Videos that needed disambiguation carry a `disambiguation` sub-object (`{strategy, detail}`) — `strategy="hash_suffix"` for the auto-resolution case.
+- `plan`-specific fields: `movies` (each with `videos`, `loose_files`, `assets`), `folder_clashes`, `movie_clashes`. Videos that needed disambiguation carry a `disambiguation` sub-object (`{strategy, detail}`) — `strategy="hash_suffix"` for the auto-resolution case. Videos and movies that lose labels or attributes in translation carry their own `drops` / `folder_drops` lists (same `{kind, key, value, reason}` shape as `translation_losses`, but per file — so you can see which file loses what).
 
 #### `jq` examples
 
@@ -307,7 +324,7 @@ This helper can also be used on other NAS systems or Linux servers — schedule
 - **Stray items** — With `--delete`, any file or folder in the target that has no counterpart in the source is removed. Without `--delete`, strays are still reported in the summary and the `--json` output, plus a warning at the end of the run points at `--delete`.
 - **Ignored items** — Entries the scanner couldn't classify (stray files at the library root, folders whose names don't parse) are reported in the summary and the `--json` `ignored` array. They are *not* carried over to the target — useful to verify before deleting the source.
 - **Video-level clashes auto-resolve** — When two source files would translate to the same target name (a common P→J outcome: `[1080p].mkv` and `[1080p] [remux].mkv` both collapse to `- BD.mkv`), a short hash of the source filename gets appended (e.g. `Movie - BD [a3f7c819].mkv`). Both files get synced; spot the hash in the `plan` output or in `--json` via the per-file `disambiguation` field. Pre-0.3 the whole movie was skipped on clash.
-- **Folder-level clashes still abort** — Two source folders mapping to the same target folder name (e.g. via dropped `[bracket]` labels) is a structural error in the source library, not something to silently merge. The run is stopped, the clashing folders are listed, and you're asked to rename one side.
+- **Folder-level clashes still abort** — Two source folders mapping to the same target folder name (e.g. via dropped `[bracket]` labels) is a structural error in the source library, not something to silently merge. The run is stopped with exit code 2, the clashing folders are listed, and you're asked to rename one side.
 
 ## Library layouts
 
@@ -333,7 +350,7 @@ Each movie must reside in its own folder, with optional subfolders for extras. D
 
 #### Special filename handling
 
-Jellyfin doesn't distinguish between editions (e.g., Director's Cut) and versions (e.g., 1080p vs. 4K). To work around this, I appended labels like "DVD", "BD", or "4K" to filenames in my personal library, ensuring the highest quality appears first and is selected by default in Jellyfin. Plex, on the other hand, supports editions natively and handles different versions via naming patterns and its internal version management. These specific labels are converted into Plex versions on the way over; other suffixes are treated as editions. The detailed mapping rules (and why DVD/BD/4k beats DVD/SDR/FHD/UHD despite the naming inconsistency) live in [SPECS.md](./SPECS.md).
+Jellyfin doesn't distinguish between editions (e.g., Director's Cut) and versions (e.g., 1080p vs. 4K). To work around this, I appended labels like "DVD", "BD", or "4K" to filenames in my personal library, ensuring the highest quality appears first and is selected by default in Jellyfin. Plex, on the other hand, supports editions natively and handles different versions via naming patterns and its internal version management. These specific labels are converted into Plex versions on the way over; other suffixes are treated as editions. The detailed mapping rules (and why DVD/BD/4k beats DVD/SDR/FHD/UHD despite the naming inconsistency) live in [docs/SPECS.md](./docs/SPECS.md).
 
 ### Plex
 
@@ -361,6 +378,12 @@ Movies
         └── Making of.mkv
 ```
 
+## Development
+
+The pipeline architecture and internal vocabulary are documented in
+[docs/DEV.md](./docs/DEV.md); the Plex/Jellyfin format details and translation
+rules live in [docs/SPECS.md](./docs/SPECS.md).
+
 ## License
 
 This project is licensed under the [BSD 3-Clause License](./LICENSE).

{jellyplex_sync-0.3.4 → jellyplex_sync-0.4.0}/README.md

@@ -2,8 +2,6 @@
 
 Can't decide between Jellyfin and Plex? This tool might help. It synchronizes your **movie library** between Jellyfin and Plex formats in **both directions** — without duplicating any files. Instead, it uses **hardlinks** to mirror your collection efficiently, saving storage while keeping both libraries in sync.
 
-> ⚠️ **0.3.0 is another major rewrite.** The internals are reorganised into a clean `discover → plan → realize` pipeline with an immutable Plan as a first-class concept. User-visible: a new **`plan` subcommand** that shows what a sync would do (text or `--json`) without touching anything, and **video-level clashes now auto-resolve with a hash suffix** instead of aborting the movie. The `sync` and `diff` CLI is unchanged. If you depend on the old shape, **try the new version with `--dry-run` first**. Cautious users can pin to a `0.2.x` (or even `0.1.x`) release until they're comfortable. See the [CHANGELOG](./CHANGELOG.md) for the full migration notes.
-
 ## Overview
 
 The script scans the source library, parses each movie folder for metadata (title, year, optional provider ID), and reproduces the same directory structure in the target location. Rather than copying video files, it creates hard links to avoid extra storage usage. Asset folders (e.g., `extras`, `subtitles`) are also mirrored. Loose top-level files (posters, NFOs, subtitles) are synced 1:1 by default since 0.2.0. With `--delete`, any files or folders in the target that are no longer present in the source will be removed.
@@ -82,6 +80,15 @@ The first positional is the source library, the second is the target. By default
 
 Use `--copy` when source and target are on different filesystems (NAS to local disk, cross-pool moves, etc.). The size+mtime check makes re-runs cheap.
 
+#### Exit codes
+
+- `0` — sync completed (including "nothing to do").
+- `1` — setup error (missing directories, undecipherable format, hardlinks across
+  filesystem boundaries).
+- `2` — folder-level clash: the run was aborted, nothing was synced.
+- `3` — sync completed, but some items marked for removal could not be removed
+  (permissions, busy files); they remain in the target.
+
 #### Examples
 
 Mirror a Jellyfin library into a new Plex structure:
@@ -214,15 +221,15 @@ The schema (still evolving — pin a version when consuming):
 - `source` / `target`: `{path, format}` for each endpoint.
 - `dry_run` (sync only): whether the run was a preview.
 - `summary`: counters; the set of fields depends on the operation.
-  - sync: `movies_total`, `movies_processed`, `files_updated`, `files_removed`, `items_ignored`, `strays_in_target`, `clashes`.
+  - sync: `movies_total`, `movies_processed`, `files_updated`, `files_removed`, `remove_errors`, `items_ignored`, `strays_in_target`, `clashes`.
   - plan: `movies`, `folder_clashes`, `movie_clashes`, `translation_losses`, `ignored`.
 - `ignored`: list of source-side entries the scanner skipped, each `{path, name, reason}`.
 - `strays_in_target` (sync only): list of names found in target that aren't in source.
 - `translation_losses`: distinct `{kind, key, value, reason}` tuples for labels/attributes the target format can't express. Deduplicated — one entry per distinct loss, not per affected file.
-- `events` (sync only): flat array of per-file actions, each `{action, target, source?, context?}`. Actions are `link`, `replace`, `skip`, `remove`. For `remove`, `context` is `library_stray` / `movie_stray` / `asset_stray`. Action names are the same in `--dry-run` and real runs; the top-level `dry_run` flag tells you which mode you were in.
+- `events` (sync only): flat array of per-file actions, each `{action, target, source?, context?}`. Actions are `link`, `replace`, `skip`, `remove` — `link` covers every creation, including copies in `--copy` mode. For `remove`, `context` is `library_stray` / `movie_stray` / `asset_stray`. Action names are the same in `--dry-run` and real runs; the top-level `dry_run` flag tells you which mode you were in.
 - `clashes` (sync only): movie-level video clashes the disambiguator couldn't resolve at all. Normally empty since the hash-fallback resolves the practical cases.
 - `diff`-specific fields: `movies_only_in_source`, `movies_only_in_target`, `differing_movies`, `in_sync`.
-- `plan`-specific fields: `movies` (each with `videos`, `loose_files`, `assets`), `folder_clashes`, `movie_clashes`. Videos that needed disambiguation carry a `disambiguation` sub-object (`{strategy, detail}`) — `strategy="hash_suffix"` for the auto-resolution case.
+- `plan`-specific fields: `movies` (each with `videos`, `loose_files`, `assets`), `folder_clashes`, `movie_clashes`. Videos that needed disambiguation carry a `disambiguation` sub-object (`{strategy, detail}`) — `strategy="hash_suffix"` for the auto-resolution case. Videos and movies that lose labels or attributes in translation carry their own `drops` / `folder_drops` lists (same `{kind, key, value, reason}` shape as `translation_losses`, but per file — so you can see which file loses what).
 
 #### `jq` examples
 
@@ -291,7 +298,7 @@ This helper can also be used on other NAS systems or Linux servers — schedule
 - **Stray items** — With `--delete`, any file or folder in the target that has no counterpart in the source is removed. Without `--delete`, strays are still reported in the summary and the `--json` output, plus a warning at the end of the run points at `--delete`.
 - **Ignored items** — Entries the scanner couldn't classify (stray files at the library root, folders whose names don't parse) are reported in the summary and the `--json` `ignored` array. They are *not* carried over to the target — useful to verify before deleting the source.
 - **Video-level clashes auto-resolve** — When two source files would translate to the same target name (a common P→J outcome: `[1080p].mkv` and `[1080p] [remux].mkv` both collapse to `- BD.mkv`), a short hash of the source filename gets appended (e.g. `Movie - BD [a3f7c819].mkv`). Both files get synced; spot the hash in the `plan` output or in `--json` via the per-file `disambiguation` field. Pre-0.3 the whole movie was skipped on clash.
-- **Folder-level clashes still abort** — Two source folders mapping to the same target folder name (e.g. via dropped `[bracket]` labels) is a structural error in the source library, not something to silently merge. The run is stopped, the clashing folders are listed, and you're asked to rename one side.
+- **Folder-level clashes still abort** — Two source folders mapping to the same target folder name (e.g. via dropped `[bracket]` labels) is a structural error in the source library, not something to silently merge. The run is stopped with exit code 2, the clashing folders are listed, and you're asked to rename one side.
 
 ## Library layouts
 
@@ -317,7 +324,7 @@ Each movie must reside in its own folder, with optional subfolders for extras. D
 
 #### Special filename handling
 
-Jellyfin doesn't distinguish between editions (e.g., Director's Cut) and versions (e.g., 1080p vs. 4K). To work around this, I appended labels like "DVD", "BD", or "4K" to filenames in my personal library, ensuring the highest quality appears first and is selected by default in Jellyfin. Plex, on the other hand, supports editions natively and handles different versions via naming patterns and its internal version management. These specific labels are converted into Plex versions on the way over; other suffixes are treated as editions. The detailed mapping rules (and why DVD/BD/4k beats DVD/SDR/FHD/UHD despite the naming inconsistency) live in [SPECS.md](./SPECS.md).
+Jellyfin doesn't distinguish between editions (e.g., Director's Cut) and versions (e.g., 1080p vs. 4K). To work around this, I appended labels like "DVD", "BD", or "4K" to filenames in my personal library, ensuring the highest quality appears first and is selected by default in Jellyfin. Plex, on the other hand, supports editions natively and handles different versions via naming patterns and its internal version management. These specific labels are converted into Plex versions on the way over; other suffixes are treated as editions. The detailed mapping rules (and why DVD/BD/4k beats DVD/SDR/FHD/UHD despite the naming inconsistency) live in [docs/SPECS.md](./docs/SPECS.md).
 
 ### Plex
 
@@ -345,6 +352,12 @@ Movies
         └── Making of.mkv
 ```
 
+## Development
+
+The pipeline architecture and internal vocabulary are documented in
+[docs/DEV.md](./docs/DEV.md); the Plex/Jellyfin format details and translation
+rules live in [docs/SPECS.md](./docs/SPECS.md).
+
 ## License
 
 This project is licensed under the [BSD 3-Clause License](./LICENSE).

jellyplex_sync-0.4.0/pyproject.toml

@@ -0,0 +1,97 @@
+[project]
+name = "jellyplex-sync"
+version = "0.4.0"
+description = "Convert your media library between Jellyfin and Plex formats by creating a hard-linked mirror"
+requires-python = ">=3.11"
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+keywords = [
+    "plex",
+    "jellyfin",
+    "media-library",
+    "movies",
+    "sync",
+    "hardlink",
+    "mirror",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Video",
+]
+dependencies = []
+
+[[project.authors]]
+name = "Stefan Schönberger"
+email = "stefan@sniner.dev"
+
+[project.urls]
+Homepage = "https://github.com/sniner/jellyplex-sync"
+Repository = "https://github.com/sniner/jellyplex-sync"
+Issues = "https://github.com/sniner/jellyplex-sync/issues"
+Changelog = "https://github.com/sniner/jellyplex-sync/blob/main/CHANGELOG.md"
+
+[project.scripts]
+jellyplex = "jellyplex_sync.cli.main:main"
+jellyplex-sync = "jellyplex_sync.cli.sync:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.5,<9",
+    "jellyplex-gen>=0.1.0",
+    "ruff>=0.15.5,<0.16",
+    "basedpyright>=1.38.2,<2",
+]
+
+[tool.uv]
+default-groups = "all"
+
+[tool.pytest.ini_options]
+addopts = "-ra -q"
+testpaths = ["tests"]
+
+[tool.pyright]
+typeCheckingMode = "strict"
+useLibraryCodeForTypes = true
+venvPath = "."
+venv = ".venv"
+
+[[tool.pyright.executionEnvironments]]
+root = "tests"
+reportUnknownParameterType = false
+reportMissingParameterType = false
+reportUnknownArgumentType = false
+reportUnknownMemberType = false
+reportUnknownVariableType = false
+reportUnknownLambdaType = false
+reportMissingTypeArgument = false
+reportPrivateUsage = false
+reportUnusedCallResult = false
+reportMissingTypeStubs = false
+
+[tool.ruff]
+line-length = 96
+
+[tool.ruff.lint]
+ignore = ["E402"]
+extend-select = [
+    "I",
+    "UP",
+    "SIM",
+    "B",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+
+[build-system]
+requires = ["uv_build>=0.12,<0.13"]
+build-backend = "uv_build"

jellyplex_sync-0.3.4/pyproject.toml → jellyplex_sync-0.4.0/pyproject.toml.orig

@@ -1,21 +1,33 @@
 [project]
 name = "jellyplex-sync"
-version = "0.3.4"
+version = "0.4.0"
 description = "Convert your media library between Jellyfin and Plex formats by creating a hard-linked mirror"
 authors = [{ name = "Stefan Schönberger", email = "stefan@sniner.dev" }]
 requires-python = ">=3.11"
 readme = "README.md"
 license = "BSD-3-Clause"
 license-files = ["LICENSE"]
+keywords = ["plex", "jellyfin", "media-library", "movies", "sync", "hardlink", "mirror"]
 classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Topic :: Multimedia :: Video",
 ]
 dependencies = []
 
+[project.urls]
+Homepage = "https://github.com/sniner/jellyplex-sync"
+Repository = "https://github.com/sniner/jellyplex-sync"
+Issues = "https://github.com/sniner/jellyplex-sync/issues"
+Changelog = "https://github.com/sniner/jellyplex-sync/blob/main/CHANGELOG.md"
+
 [project.scripts]
 jellyplex = "jellyplex_sync.cli.main:main"
 jellyplex-sync = "jellyplex_sync.cli.sync:main"
@@ -24,13 +36,15 @@ jellyplex-sync = "jellyplex_sync.cli.sync:main"
 dev = [
     "pytest>=8.3.5,<9",
     "jellyplex-gen>=0.1.0",
+    "ruff>=0.15.5,<0.16",
+    "basedpyright>=1.38.2,<2",
 ]
 
 [tool.uv]
 default-groups = "all"
 
 [build-system]
-requires = ["uv_build>=0.10.4,<0.11.0"]
+requires = ["uv_build>=0.12,<0.13"]
 build-backend = "uv_build"
 
 [tool.pytest.ini_options]
@@ -38,11 +52,27 @@ addopts = "-ra -q"
 testpaths = ["tests"]
 
 [tool.pyright]
-typeCheckingMode = "standard"
+typeCheckingMode = "strict"
 useLibraryCodeForTypes = true
 venvPath = "."
 venv = ".venv"
 
+# Tests stay at standard-level strictness: annotating every pytest
+# fixture parameter adds noise, not safety. The library itself is
+# checked strict.
+[[tool.pyright.executionEnvironments]]
+root = "tests"
+reportUnknownParameterType = false
+reportMissingParameterType = false
+reportUnknownArgumentType = false
+reportUnknownMemberType = false
+reportUnknownVariableType = false
+reportUnknownLambdaType = false
+reportMissingTypeArgument = false
+reportPrivateUsage = false
+reportUnusedCallResult = false
+reportMissingTypeStubs = false
+
 [tool.ruff]
 line-length = 96
 

{jellyplex_sync-0.3.4 → jellyplex_sync-0.4.0}/src/jellyplex_sync/__init__.py

@@ -1,3 +1,7 @@
+from .compare import (
+    DiffEntry,
+    DiffResult,
+)
 from .jellyfin import (
     JellyfinLibraryReader,
     JellyfinLibraryWriter,
@@ -14,6 +18,7 @@ from .library import (
     LibraryWriter,
     LoggingReporter,
     MovieClash,
+    NullReporter,
     Reporter,
     StrictReporter,
     dedupe_drops,
@@ -41,8 +46,8 @@ from .plex import (
     PlexLibraryWriter,
 )
 from .sync import (
-    DiffEntry,
-    DiffResult,
+    LibraryStats,
+    SyncResult,
     diff,
     import_media,
     plan,
@@ -63,15 +68,17 @@ __all__ = [
     "FolderClash",
     "ForceCopyMaterializer",
     "HardlinkMaterializer",
-    "MoveMaterializer",
     "IgnoredEntry",
     "JellyfinLibraryReader",
     "JellyfinLibraryWriter",
     "LibraryReader",
+    "LibraryStats",
     "LibraryWriter",
     "LoggingReporter",
+    "MoveMaterializer",
     "MovieClash",
     "MovieInfo",
+    "NullReporter",
     "Plan",
     "PlannedAsset",
     "PlannedFile",
@@ -80,6 +87,7 @@ __all__ = [
     "PlexLibraryWriter",
     "Reporter",
     "StrictReporter",
+    "SyncResult",
     "VideoInfo",
     "dedupe_drops",
     "diff",

{jellyplex_sync-0.3.4 → jellyplex_sync-0.4.0}/src/jellyplex_sync/cli/main.py

@@ -1,11 +1,14 @@
-#!/usr/bin/python3
 from __future__ import annotations
 
 import argparse
 import logging
+import pathlib
 import sys
 
 import jellyplex_sync as jp
+from jellyplex_sync.json_output import write_sync_json
+
+log = logging.getLogger(__name__)
 
 
 def _build_parser() -> argparse.ArgumentParser:
@@ -14,8 +17,10 @@ def _build_parser() -> argparse.ArgumentParser:
         description="Convert a media library between Plex and Jellyfin layouts.",
     )
 
-    # Flags shared by every subcommand. Use a parent parser so they can be
-    # given either before or after the subcommand name.
+    # Flags shared by every subcommand. Parent parsers so they can be
+    # given either before or after the subcommand name. --json lives in
+    # its own parent because `import` has no JSON output yet — offering
+    # the flag there would silently produce nothing.
     common = argparse.ArgumentParser(add_help=False)
     common.add_argument(
         "-v",
@@ -28,7 +33,9 @@ def _build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Show debug messages.",
     )
-    common.add_argument(
+
+    json_opt = argparse.ArgumentParser(add_help=False)
+    json_opt.add_argument(
         "--json",
         action="store_true",
         help="Emit a machine-readable JSON document on stdout. Logs continue to go to stderr.",
@@ -38,7 +45,7 @@ def _build_parser() -> argparse.ArgumentParser:
 
     sync_p = sub.add_parser(
         "sync",
-        parents=[common],
+        parents=[common, json_opt],
         help="Mirror a source library into the target layout.",
     )
     _add_io_args(sync_p)
@@ -83,14 +90,14 @@ def _build_parser() -> argparse.ArgumentParser:
 
     diff_p = sub.add_parser(
         "diff",
-        parents=[common],
+        parents=[common, json_opt],
         help="Compare source and target libraries without writing anything.",
     )
     _add_io_args(diff_p)
 
     plan_p = sub.add_parser(
         "plan",
-        parents=[common],
+        parents=[common, json_opt],
         help="Show the Plan a sync would execute, without touching the target.",
     )
     _add_io_args(plan_p)
@@ -116,7 +123,9 @@ def _build_parser() -> argparse.ArgumentParser:
         const="copy",
         help="Copy files; source is kept. On re-runs skip files whose size and mtime match.",
     )
-    import_p.set_defaults(mode="move")
+    # No --json for import (no JSON output yet); the default keeps the
+    # shared `args.json` logging logic in main() working.
+    import_p.set_defaults(mode="move", json=False)
     import_p.add_argument(
         "--dry-run",
         action="store_true",
@@ -190,60 +199,41 @@ def main() -> None:
 
 
 def _do_sync(args: argparse.Namespace) -> int:
-    import pathlib
-
-    from jellyplex_sync.library import CollectingReporter
-    from jellyplex_sync.sync import LibraryStats
-
     materializer = _make_materializer(args.mode)
-    stats = LibraryStats() if args.json else None
-    reporter = CollectingReporter() if args.json else None
     try:
-        rc = jp.sync(
+        result = jp.sync(
             args.source,
             args.target,
             dry_run=args.dry_run,
             delete=args.delete,
             create=args.create,
             verbose=args.verbose,
-            debug=args.debug,
             source_format=args.source_format,
             target_format=args.target_format,
             materializer=materializer,
-            reporter=reporter,
-            stats=stats,
         )
     except KeyboardInterrupt:
-        logging.info("INTERRUPTED")
+        log.info("INTERRUPTED")
         return 10
     except Exception as exc:
-        logging.error("Exception: %s", exc)
+        # Boundary catch: turn anything unexpected into an exit code.
+        # --debug adds the traceback, which the message alone loses.
+        log.error("Exception: %s", exc, exc_info=args.debug)
         return 99
 
     if args.json:
-        assert stats is not None and reporter is not None
-        from jellyplex_sync.json_output import write_sync_json
-        from jellyplex_sync.sync import _resolve_formats
-
-        resolved = _resolve_formats(
-            pathlib.Path(args.source),
-            args.source_format,
-            args.target_format,
-        )
-        source_short, target_short = resolved if resolved else ("?", "?")
-
         write_sync_json(
             sys.stdout,
             source_path=pathlib.Path(args.source),
-            source_format=source_short,
+            source_format=result.source_format or "?",
             target_path=pathlib.Path(args.target),
-            target_format=target_short,
+            target_format=result.target_format or "?",
             dry_run=args.dry_run,
-            exit_code=rc,
-            stats=stats,
-            drops=reporter.drops,
+            exit_code=result.exit_code,
+            stats=result.stats,
+            drops=result.drops,
         )
-    return rc
+    return result.exit_code
 
 
 def _make_materializer(mode: str) -> jp.FileMaterializer:
@@ -257,68 +247,66 @@ def _make_materializer(mode: str) -> jp.FileMaterializer:
 
 
 def _do_diff(args: argparse.Namespace) -> int:
-    from jellyplex_sync.sync import diff
-
     try:
-        return diff(
+        return jp.diff(
             args.source,
             args.target,
-            debug=args.debug,
             source_format=args.source_format,
             target_format=args.target_format,
             as_json=args.json,
         )
     except KeyboardInterrupt:
-        logging.info("INTERRUPTED")
+        log.info("INTERRUPTED")
         return 10
     except Exception as exc:
-        logging.error("Exception: %s", exc)
+        # Boundary catch: turn anything unexpected into an exit code.
+        # --debug adds the traceback, which the message alone loses.
+        log.error("Exception: %s", exc, exc_info=args.debug)
         return 99
 
 
 def _do_plan(args: argparse.Namespace) -> int:
-    from jellyplex_sync.sync import plan as plan_fn
-
     try:
-        return plan_fn(
+        return jp.plan(
             args.source,
             args.target,
-            debug=args.debug,
             source_format=args.source_format,
             target_format=args.target_format,
             as_json=args.json,
         )
     except KeyboardInterrupt:
-        logging.info("INTERRUPTED")
+        log.info("INTERRUPTED")
         return 10
     except Exception as exc:
-        logging.error("Exception: %s", exc)
+        # Boundary catch: turn anything unexpected into an exit code.
+        # --debug adds the traceback, which the message alone loses.
+        log.error("Exception: %s", exc, exc_info=args.debug)
         return 99
 
 
 def _do_import(args: argparse.Namespace) -> int:
-    from jellyplex_sync.sync import import_media
-
     materializer = jp.MoveMaterializer() if args.mode == "move" else jp.CopyMaterializer()
 
     try:
-        return import_media(
+        result = jp.import_media(
             args.source,
             args.target,
             dry_run=args.dry_run,
             create=args.create,
             verbose=args.verbose,
-            debug=args.debug,
             source_format=args.source_format,
             target_format=args.target_format,
             materializer=materializer,
         )
     except KeyboardInterrupt:
-        logging.info("INTERRUPTED")
+        log.info("INTERRUPTED")
         return 10
     except Exception as exc:
-        logging.error("Exception: %s", exc)
+        # Boundary catch: turn anything unexpected into an exit code.
+        # --debug adds the traceback, which the message alone loses.
+        log.error("Exception: %s", exc, exc_info=args.debug)
         return 99
+    return result.exit_code
 
 
 if __name__ == "__main__":

jellyplex_sync-0.4.0/src/jellyplex_sync/cli/sync.py

@@ -0,0 +1,22 @@
+"""Backward-compatible ``jellyplex-sync`` entry point.
+
+A thin alias for ``jellyplex sync``: the ``sync`` subcommand is
+inserted into the argument list and the main CLI takes over. Same
+options, same behaviour, one parser to maintain instead of two
+copies that would have to be kept in step by hand.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from jellyplex_sync.cli import main as cli_main
+
+
+def main() -> None:
+    sys.argv = [sys.argv[0], "sync", *sys.argv[1:]]
+    cli_main.main()
+
+
+if __name__ == "__main__":
+    main()