pearlarr 1.0.0__tar.gz

pearlarr-1.0.0/.gitignore

@@ -0,0 +1,239 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# macOS
+.DS_Store
+
+# Editor settings
+.vscode/
+
+# uv lockfile
+# uv.lock
+
+# Pearlarr runtime / user files (root-anchored: .github/ISSUE_TEMPLATE/config.yml
+# is a tracked GitHub file, not a runtime config)
+/config.yml
+cache.json
+cache.json.migrated
+cache.db
+cache.db-wal
+cache.db-shm
+cache.backup.db
+cache.db.corrupt-*
+mappings.db
+mappings.db-wal
+mappings.db-shm
+mappings.db.corrupt-*
+.pearlarr.lock
+logs/
+
+# Downloaded mapping data
+anime_ids.json
+anime-list-master.xml
+anibridge_mappings.json
+anibridge_mappings_v3.json

pearlarr-1.0.0/CHANGELOG.md

@@ -0,0 +1,185 @@
+# Changelog
+
+All notable, user-observable changes to Pearlarr are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Pearlarr is a fork of [bbtufty/seadexarr](https://github.com/bbtufty/seadexarr); everything up to and including 0.9.0 is inherited upstream history.
+
+## [1.0.0] - 2026-07-12
+
+The first release of the fork.
+
+### Upgrade notes
+
+Coming from upstream 0.9.x:
+
+- **The project is renamed** from SeaDexArr to Pearlarr: the package, the `pearlarr` command, the data directory, and the `PEARLARR_*` environment variables all follow (the `seadexarr` PyPI name stays with upstream).
+- **The config format changed wholesale**, from flat keys to nested groups with strict validation.
+  Rewrite your `config.yml` against the new layout (`pearlarr config init` writes a commented starter, and [docs/configuration.md](docs/configuration.md) documents every key): `sonarr_url` is now `sonarr.url`, `qbit_info` is `qbittorrent.*`, `torrent_tags` is `qbittorrent.tags`, `seadex.public_only` is replaced by `seadex.private_releases`.
+  Unknown or misspelled keys now fail at load instead of being ignored.
+- **The data location moved** off the install directory to one OS-standard data directory (`~/.local/share/pearlarr` on Linux, `~/Library/Application Support/pearlarr` on macOS).
+  `pearlarr config init` writes the new config there; set `PEARLARR_DATA_DIR` to relocate everything.
+  Logs follow the data directory instead of the working directory; `pearlarr paths` prints every resolved location.
+- **The cache is not carried over**: the SQLite `cache.db` replaces `cache.json`, and the old file is not read.
+  The first run re-evaluates the library from scratch - cheap in the default matching mode, which checks what the arrs already have on disk; see [docs/deployment.md](docs/deployment.md#migrating-from-upstream-seadexarr) before enabling hash matching.
+- **Python 3.13 or newer is required** (3.12 support dropped); the Docker image runs 3.14.
+- **`SCHEDULE_TIME` is deprecated** in favor of `schedule.interval_hours` (on bare metal a still-set `SCHEDULE_TIME` wins, with a deprecation warning; the Docker image never reads it - set `PEARLARR_CRON`).
+
+### Added
+
+- Wait-for-completion and Sonarr manual import (`imports.wait_mode`: `off`/`deferred`/`blocking`/`hybrid`): Pearlarr waits for qBittorrent to finish grabbed torrents, lets Sonarr import them, and steps in with a series-pinned manual import when Sonarr can't.
+  Downloads that outlast a run are carried as pending imports and picked up by a later run.
+- `notifications.wait_webhook_url`: a generic outbound webhook (ntfy, gotify, Home Assistant, ...) for the wait-pass summary, alongside the Discord webhook, with `notifications.wait_notify` controlling the push.
+- `imports.post_import_category`: move a torrent to a different qBittorrent category (created if missing) once its import is verified complete, e.g. to give finished torrents different seeding rules.
+- Arr-side activity detection (`advanced.detect_arr_activity`, on by default): each run polls the arr's history and re-checks titles whose files were imported or deleted arr-side since the last run, so a quality upgrade or manual grab is re-evaluated without waiting for SeaDex to update.
+  The first scan covers the last 30 days; a coverage gap re-checks everything once.
+- AniBridge mappings as the primary ID/episode mapping source, mopping up titles the other sources miss.
+- `seadex.ignore_anilist_ids` (skip specific AniList IDs), `seadex.ignore_tags` (filter releases by SeaDex tag), and `qbittorrent.tags` (tag every added torrent).
+- Discord notifications are rich embeds with colors, links, and a version footer.
+- The console shows a live cockpit during startup and the import-wait pass (spinners, ticking timers, files-imported progress).
+- `advanced.log_format` picks the console surface (`auto`/`rich`/`plain`/`json`); `json` writes one JSON object per event to stdout - a versioned machine interface with a generated event catalog ([docs/output.md](docs/output.md)).
+- Rotated logs are dated per-run backups, kept for `advanced.log_retention_days` days, replacing the fixed ten-file cascade.
+- New CLI surface:
+  - `run single --dry-run` (simulate without grabbing, caching, or notifying), `--movie-id`/`--series-id` (single-title runs by TMDB/TVDB ID), and `--import-wait-mode`/`--log-level` per-run overrides.
+  - `config validate` and `config show` (effective config with secrets redacted, safe to paste into a bug report).
+  - `cache stats` and `cache check`.
+  - `pearlarr --version`, `-h` everywhere; a bare group command prints its help.
+  - `replay FILE` (or `-` for stdin) re-renders a captured `log_format: json` / `--json` stream back into the readable text log grammar, for reading a docker-captured log after the fact.
+- `--json` on every subcommand (`paths`, `config init`/`validate`/`migrate`/`show`, `cache backup`/`restore`/`remove`/`stats`/`check`) emitting the same `schema_version` 1 envelope as run logs.
+- Every config key can be set by environment variable as `PEARLARR_<GROUP>__<KEY>` (for example `PEARLARR_SONARR__URL`); values are parsed as YAML and an environment override beats the file.
+- The scheduled-run cadence is a config field, `schedule.interval_hours` (default 6), re-read each cycle so an edit takes effect without a restart.
+- Config schema versioning: `config_version` stamps the file, and a file from an older Pearlarr is migrated automatically in memory at every load (a nested-format file still saying `seadex.public_only` or `private_releases: allow` keeps loading, with a warning naming the fold).
+  `pearlarr config migrate` rewrites the file itself at the current schema, keeping the previous file as `config.yml.bak`.
+
+### Changed
+
+- **Private releases are never grabbed** (SeaDex carries no download link for them, and no private-tracker auth is supported).
+  `seadex.private_releases` decides what happens when a title's preferred release is private-only: `warn` (default) warns and leaves the title uncached so it is re-checked every run; `fallback` grabs the entry's best public alternative, warning only when none exists.
+  Titles satisfied by a fallback are remembered; switching back to `warn` re-checks them and resurfaces the warning.
+- Where multiple preferred release groups cover exactly the same files, only one is downloaded (preferring a public release) instead of all of them.
+- `advanced.max_torrents_to_add` defaults to `10` instead of unlimited, so a first run against a large library doesn't flood qBittorrent - later runs pick up where the cap stopped.
+  Preview runs ignore the cap and always report the whole library; set the key to `0` to remove the cap.
+- Only configured arrs run: a Sonarr-only (or Radarr-only) config skips the other arr with a ledger note instead of failing every cycle; explicitly selecting an unconfigured arr fails with a one-line error naming the missing keys; a half-configured arr (URL without API key, or the reverse) is warned about by name.
+- `run single` with no selection flags runs every configured arr, mirroring scheduled mode (previously it printed a usage hint and failed).
+- Failed CLI commands exit non-zero (previously always 0); a malformed config, missing backup, unreachable arr, or rejected API key is reported as a clean one-line error naming the config keys to check, instead of a traceback.
+- `cache backup` writes via a temp file so a failed backup can never destroy the previous good one; `cache restore` copies instead of consuming the backup, so a restore is repeatable.
+- `config init` refuses to overwrite an existing `config.yml` unless `--force` is passed.
+- The Python import surface is internal as of 1.0.0: the supported interfaces are the CLI, the config schema, the JSON event stream, and the notification payloads.
+- Runtime dependencies bumped to current majors (typer 0.26, rich 15, qbittorrent-api 2026.6).
+
+### Deprecated
+
+- `SCHEDULE_TIME` (Docker-era env var): set `schedule.interval_hours` (bare metal) or `PEARLARR_CRON` (Docker, which ignores `SCHEDULE_TIME`) instead; an invalid value now falls back to the configured cadence with a report instead of crashing the scheduler.
+
+### Removed
+
+- `seadex.public_only` (replaced by `seadex.private_releases`, see Upgrade notes).
+- Python 3.12 support.
+
+### Fixed
+
+- `advanced.log_level` is honored everywhere: `ERROR` is a real level (the logger previously treated it as `INFO`), and CLI runs no longer force `INFO` regardless of config.
+- In `fallback` mode, a public substitute never replaces a copy of the preferred private release you already own: when your private copy is stale-sized, Pearlarr warns and holds the title (the summary names both ways out) instead of overwriting it with the fallback.
+
+## Inherited from upstream
+
+The releases below are [bbtufty/seadexarr](https://github.com/bbtufty/seadexarr) history, reproduced as shipped.
+
+## [0.9.0] - 2025-09-13
+
+- Include PlexAniBridge-Mappings to mop up some missed titles
+- Update cache if version/config changes
+- Add option to ignore SeaDex update time
+- Don't recreate cache on config change
+- Add a number of useful CLI commands
+- Include option to just check torrents by hash
+- Update cache if no suitable releases found
+- Check file sizes, for different versions of releases etc.
+
+## [0.8.1] - 2025-09-05
+
+- Fix cache not updating with versions
+
+## [0.8.0] - 2025-09-05
+
+- If we're ignoring Radarr movies in Sonarr, also check the cache
+- Do a more proper check for episodes in Sonarr
+- Ensure docker-compose run also uses cache
+- Fix crash if AniList ID isn't already in cache
+- Include AniList name in cache
+- Sort cache by AniList ID
+- Revert removing trackers
+
+## [0.7.0] - 2025-08-24
+
+- Create a cache to avoid checked entries that haven't updated
+- Fix grabbing multiple releases when there's a mismatch in episode parsing
+- Removed trackers that aren't used by SeaDex
+- Add support for RuTracker
+
+## [0.6.0] - 2025-08-13
+
+- Take Ja-only releases if `prefer_dual_audio` is False
+- Catch crash if SeaDex is unreachable
+- Cleanup dictionaries
+- Search specifically in qBittorrent by torrent hash, to speed up hash checks
+- Skip adding downloads to torrent client if download flag not set
+- Fix bug where maximum number of torrents added was not respected
+
+## [0.5.0] - 2025-08-08
+
+- Fix UTF-8 encoding warning in log
+- Move to episode-based filtering of torrents for Sonarr
+- Include SeaDex tags in log and Discord messages
+- Add options to ignore unmonitored series/movies
+- Save logs to file
+- Ensure SCHEDULE_TIME is brought in as a float
+- Fix Discord messages not getting pushed if no torrent client selected
+- Fix adding too many torrents in one go
+
+## [0.4.1] - 2025-07-31
+
+- Add PyYAML to pyproject.toml
+- Added support for AnimeTosho
+
+## [0.4.0] - 2025-07-31
+
+- Added ignore_movies_in_radarr for SeaDexSonarr, which will skip movies flagged as Specials in Sonarr that already exist in Radarr
+- More robust config when parameters added
+- Build Docker for every main update
+- Fix crash when AniDB mapping contains no text
+- Use IMDb for finding AniList mappings as well
+- Initial support for other trackers
+- Better handle Discord notifications and log messages when torrent already in client
+- Map potentially weird episodes SeaDexSonarr if in Season 0 (Specials)
+
+## [0.3.0] - 2025-07-30
+
+- Added scheduling in Docker mode
+
+## [0.2.0] - 2025-07-30
+
+- Add Docker support
+- Move to config files, to make the call simpler
+- Fix crash if torrent in list but not already downloaded
+
+## [0.1.0] - 2025-07-22
+
+- Add support for Radarr
+
+## [0.0.3] - 2025-07-22
+
+- Rename from seadex_sonarr to seadexarr, in preparation for Radarr support
+- Add interactive mode, for selecting when multiple "best" options are found
+- Add support for adding torrents to qBittorrent
+
+## [0.0.2] - 2025-07-13
+
+- Improved Discord messaging
+- Catch the case where we don't find any suitable SeaDex releases
+- Include potentially weird offset mappings via AniDB lists
+- Add a rest time to not hit AniList rate limiting
+
+## [0.0.1] - 2025-07-12
+
+- Initial release