mediathekwatch 0.1.0__tar.gz

mediathekwatch-0.1.0/.forgejo/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: codeberg-small
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install system tools
+        env:
+          DEBIAN_FRONTEND: noninteractive
+        run: |
+          apt-get update
+          apt-get install -y make curl
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | env UV_UNMANAGED_INSTALL="/usr/local/bin" sh
+          uv --version
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-extras --dev
+
+      - name: Validate and test
+        run: |
+          uv run make all
+
+      - name: Build package
+        run: |
+          uv build
+
+      - name: Check package artifacts
+        run: |
+          uv tool run twine check dist/*

mediathekwatch-0.1.0/.forgejo/workflows/publish.yml

@@ -0,0 +1,60 @@
+name: Publish Python package
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: codeberg-small
+    environment: release
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install system tools
+        env:
+          DEBIAN_FRONTEND: noninteractive
+        run: |
+          apt-get update
+          apt-get install -y make curl
+
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | env UV_UNMANAGED_INSTALL="/usr/local/bin" sh
+          uv --version
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-extras --dev
+
+      - name: Validate and test
+        run: |
+          uv run make all
+
+      - name: Build package
+        run: |
+          uv build
+
+      - name: Check package artifacts
+        run: |
+          uv tool run twine check dist/*
+
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: |
+          uv publish
+
+      # Optional: publish a mirror to Codeberg's Forgejo package registry.
+      # Enable this only after adding CODEBERG_USERNAME and CODEBERG_TOKEN secrets.
+      #
+      # - name: Publish to Codeberg package registry
+      #   env:
+      #     TWINE_USERNAME: ${{ secrets.CODEBERG_USERNAME }}
+      #     TWINE_PASSWORD: ${{ secrets.CODEBERG_TOKEN }}
+      #   run: |
+      #     uv tool run twine upload \
+      #       --repository-url https://codeberg.org/api/packages/smeinecke/pypi \
+      #       dist/*

mediathekwatch-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.ruff_cache
+.coverage
+coverage.xml
+.pytest_cache
+*.pyc
+.vscode
+.crush
+
+# Virtual environments
+.venv

mediathekwatch-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+default_stages: [pre-push]
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.2
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.397
+    hooks:
+    - id: pyright

mediathekwatch-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

mediathekwatch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Stefan Meinecke
+
+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.

mediathekwatch-0.1.0/Makefile

@@ -0,0 +1,83 @@
+# Makefile for disposable email domain generator
+
+.PHONY: all format check validate test test-unit test-integration test-all help reformat-ruff fix-ruff fix vulture complexity xenon bandit pyright
+
+# Default target: runs format and check
+all: validate test-unit
+
+# Format the code using ruff
+format:
+	ruff format --check --diff .
+
+reformat-ruff:
+	ruff format .
+
+# Check the code using ruff
+check:
+	ruff check .
+
+fix-ruff:
+	ruff check . --fix
+
+fix: reformat-ruff fix-ruff
+	@echo "Updated code."
+
+vulture:
+	vulture src --exclude .venv,__pycache__ --min-confidence 80
+
+complexity:
+	radon cc src -a -nc
+
+xenon:
+	-xenon -b C -m C -a C src || true
+
+bandit:
+	bandit -c pyproject.toml -r src
+
+pyright:
+	pyright
+
+test:
+	pytest -m "not integration"
+
+test-unit:
+	pytest tests/unit/ --cov-fail-under=85
+
+test-integration:
+	pytest -m integration
+
+test-all:
+	pytest --tb=short
+
+# Validate the code (format + check)
+validate: format check bandit pyright vulture complexity xenon
+	@echo "Validation passed. Your code is ready to push."
+
+build:
+	uv build
+
+package-check:
+	uv tool run twine check dist/*
+
+ci: all build package-check
+
+# Help target
+help:
+	@echo "Available targets:"
+	@echo "  all           - Run validation and unit tests (default)"
+	@echo "  format        - Check code formatting with ruff"
+	@echo "  reformat-ruff - Format code with ruff"
+	@echo "  check         - Run ruff linting"
+	@echo "  fix-ruff      - Auto-fix ruff issues"
+	@echo "  fix           - Run reformat-ruff and fix-ruff"
+	@echo "  vulture       - Run dead code detection"
+	@echo "  complexity    - Run complexity analysis"
+	@echo "  xenon         - Run xenon complexity check"
+	@echo "  bandit        - Run security analysis"
+	@echo "  pyright       - Run type checking"
+	@echo "  test          - Run all tests"
+	@echo "  test-unit     - Run unit tests only"
+	@echo "  test-integration - Run integration tests only"
+	@echo "  test-all      - Run all tests with short traceback"
+	@echo "  validate      - Run all validation checks"
+	@echo "  help          - Show this help message"

mediathekwatch-0.1.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: mediathekwatch
+Version: 0.1.0
+Summary: Monitor ARD Mediathek series for new episodes and download them via yt-dlp
+Author: Stefan Meinecke
+License: MIT
+License-File: LICENSE
+Requires-Python: <4.0,>=3.10
+Requires-Dist: duckdb>=1.0
+Requires-Dist: requests>=2.32
+Description-Content-Type: text/markdown
+
+# MediathekWatch
+
+A Python CLI tool to monitor ARD Mediathek, ARTE.tv, and ZDF Mediathek series for new episodes and automatically download them using yt-dlp. State is tracked in a local DuckDB database.
+
+## Requirements
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/)
+- [yt-dlp](https://github.com/yt-dlp/yt-dlp) installed and available in `$PATH`
+
+## Installation
+
+```bash
+# Clone or navigate to the project
+cd /path/to/mediathekwatch
+
+# Install with uv
+uv sync
+
+# Or install as editable
+uv pip install -e .
+```
+
+## Usage
+
+The tool is installed as `mediathekwatch` command:
+
+### Add a series to monitor
+
+```bash
+mediathekwatch add "https://www.ardmediathek.de/serie/feuer-und-flamme/staffel-11/Y3JpZDovL3dkci5kZS9mZXVlcnVuZGZsYW1tZQ/11" --name "Feuer und Flamme"
+```
+
+ZDF Mediathek URLs are also supported:
+
+```bash
+mediathekwatch add "https://www.zdf.de/serien/die-anstalt" --name "Die Anstalt"
+```
+
+Assign to a group (see [Groups](#groups)):
+
+```bash
+mediathekwatch add "https://www.ardmediathek.de/serie/..." --name "My Show" --group "TVShows"
+```
+
+### List monitored series
+
+```bash
+mediathekwatch list
+```
+
+### Check for new episodes (intended for cron)
+
+```bash
+mediathekwatch check --target /mnt/media/TVShows
+
+# Silent mode (suppress all output)
+mediathekwatch check --target /mnt/media/TVShows --silent
+```
+
+When groups are configured, each group downloads to its own target folder and `--target` is not allowed:
+
+```bash
+mediathekwatch check --silent
+```
+
+### Force redownload of a specific episode
+
+```bash
+# By series ID
+mediathekwatch redownload 1 11 5 --target /mnt/media/TVShows
+
+# By series name
+mediathekwatch redownload "Feuer und Flamme" 11 5 --target /mnt/media/TVShows
+```
+
+If `--target` is omitted, the episode downloads to the series' group folder.
+
+### Download all episodes from a series URL
+
+```bash
+mediathekwatch download "https://www.ardmediathek.de/serie/feuer-und-flamme/staffel-11/Y3JpZDovL3dkci5kZS9mZXVlcnVuZGZsYW1tZQ/11" --target /mnt/media/TVShows
+```
+
+Works with ZDF Mediathek too:
+
+```bash
+mediathekwatch download "https://www.zdf.de/serien/die-anstalt" --target /mnt/media/TVShows
+```
+
+### Remove a series
+
+```bash
+# By ID
+mediathekwatch remove 1
+
+# By name
+mediathekwatch remove "Feuer und Flamme"
+```
+
+## Groups
+
+Groups let you organize series into separate download destinations. Each group has its own target folder. When any non-default group exists, `check` uses group folders instead of `--target`.
+
+### Create a group
+
+```bash
+mediathekwatch group create "TVShows" --target /mnt/media/TVShows
+```
+
+### List groups
+
+```bash
+mediathekwatch group list
+```
+
+### Update a group
+
+```bash
+mediathekwatch group update "TVShows" --name "TV Shows" --target /mnt/media/TV
+```
+
+### Delete a group
+
+```bash
+mediathekwatch group delete "TVShows"
+```
+
+### Move a series to a group
+
+```bash
+mediathekwatch set-group "Feuer und Flamme" "TVShows"
+```
+
+## Global Options
+
+- `--db PATH` — Path to DuckDB database (default: `~/.config/mediathekwatch/mediathekwatch.db`)
+- `--target PATH` — Target folder for downloads (default: current directory)
+
+## Cron Setup
+
+Add to your crontab (e.g., every 6 hours):
+
+```cron
+0 */6 * * * /path/to/uv run mediathekwatch check --target /mnt/media/TVShows
+```
+
+Or if installed globally:
+
+```cron
+0 */6 * * * /home/user/.local/bin/mediathekwatch check --target /mnt/media/TVShows
+```
+
+## Filename Format
+
+Downloaded episodes are organized as:
+
+```
+<Target Folder>/<Series Name>/S<Season>/<Series> - S<season>E<episode> - <episode name>.mkv
+```
+
+Example:
+
+```
+/mnt/media/TVShows/Feuer und Flamme/S11/Feuer und Flamme - S11E05 - Der neue Fall.mkv
+```
+
+## Database Schema
+
+Three tables are maintained in DuckDB:
+
+- `groups` — download groups with target folders
+- `monitored_series` — series being tracked
+- `downloaded_episodes` — episodes already downloaded
+
+## Project Structure
+
+```
+src/mediathekwatch/
+├── __init__.py    # Package init
+├── main.py        # CLI entry point
+├── cli.py         # Command handlers
+├── models.py      # Episode/Series dataclasses
+├── database.py    # DuckDB interface
+├── api/           # API clients (ARD, ARTE, ZDF)
+└── download.py    # yt-dlp wrapper & filename utils
+```
+
+## Notes
+
+- The tool queries ARD Mediathek, ARTE.tv EMAC, and ZDF GraphQL APIs to discover episodes.
+- yt-dlp is invoked with flags for embedding thumbnails, subtitles, metadata, chapters, and info-json.
+- Episodes are skipped if they already exist in the `downloaded_episodes` table; use `redownload` to override.
+
+## Acknowledgments
+
+- Thanks to the [MediathekView](https://mediathekview.de/) project for providing valuable insights into the structure of German public media APIs.
+
+## Development
+
+```bash
+# Run tests
+uv run pytest
+
+# Type check
+uv run pyright
+```

mediathekwatch-0.1.0/README.md

@@ -0,0 +1,207 @@
+# MediathekWatch
+
+A Python CLI tool to monitor ARD Mediathek, ARTE.tv, and ZDF Mediathek series for new episodes and automatically download them using yt-dlp. State is tracked in a local DuckDB database.
+
+## Requirements
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/)
+- [yt-dlp](https://github.com/yt-dlp/yt-dlp) installed and available in `$PATH`
+
+## Installation
+
+```bash
+# Clone or navigate to the project
+cd /path/to/mediathekwatch
+
+# Install with uv
+uv sync
+
+# Or install as editable
+uv pip install -e .
+```
+
+## Usage
+
+The tool is installed as `mediathekwatch` command:
+
+### Add a series to monitor
+
+```bash
+mediathekwatch add "https://www.ardmediathek.de/serie/feuer-und-flamme/staffel-11/Y3JpZDovL3dkci5kZS9mZXVlcnVuZGZsYW1tZQ/11" --name "Feuer und Flamme"
+```
+
+ZDF Mediathek URLs are also supported:
+
+```bash
+mediathekwatch add "https://www.zdf.de/serien/die-anstalt" --name "Die Anstalt"
+```
+
+Assign to a group (see [Groups](#groups)):
+
+```bash
+mediathekwatch add "https://www.ardmediathek.de/serie/..." --name "My Show" --group "TVShows"
+```
+
+### List monitored series
+
+```bash
+mediathekwatch list
+```
+
+### Check for new episodes (intended for cron)
+
+```bash
+mediathekwatch check --target /mnt/media/TVShows
+
+# Silent mode (suppress all output)
+mediathekwatch check --target /mnt/media/TVShows --silent
+```
+
+When groups are configured, each group downloads to its own target folder and `--target` is not allowed:
+
+```bash
+mediathekwatch check --silent
+```
+
+### Force redownload of a specific episode
+
+```bash
+# By series ID
+mediathekwatch redownload 1 11 5 --target /mnt/media/TVShows
+
+# By series name
+mediathekwatch redownload "Feuer und Flamme" 11 5 --target /mnt/media/TVShows
+```
+
+If `--target` is omitted, the episode downloads to the series' group folder.
+
+### Download all episodes from a series URL
+
+```bash
+mediathekwatch download "https://www.ardmediathek.de/serie/feuer-und-flamme/staffel-11/Y3JpZDovL3dkci5kZS9mZXVlcnVuZGZsYW1tZQ/11" --target /mnt/media/TVShows
+```
+
+Works with ZDF Mediathek too:
+
+```bash
+mediathekwatch download "https://www.zdf.de/serien/die-anstalt" --target /mnt/media/TVShows
+```
+
+### Remove a series
+
+```bash
+# By ID
+mediathekwatch remove 1
+
+# By name
+mediathekwatch remove "Feuer und Flamme"
+```
+
+## Groups
+
+Groups let you organize series into separate download destinations. Each group has its own target folder. When any non-default group exists, `check` uses group folders instead of `--target`.
+
+### Create a group
+
+```bash
+mediathekwatch group create "TVShows" --target /mnt/media/TVShows
+```
+
+### List groups
+
+```bash
+mediathekwatch group list
+```
+
+### Update a group
+
+```bash
+mediathekwatch group update "TVShows" --name "TV Shows" --target /mnt/media/TV
+```
+
+### Delete a group
+
+```bash
+mediathekwatch group delete "TVShows"
+```
+
+### Move a series to a group
+
+```bash
+mediathekwatch set-group "Feuer und Flamme" "TVShows"
+```
+
+## Global Options
+
+- `--db PATH` — Path to DuckDB database (default: `~/.config/mediathekwatch/mediathekwatch.db`)
+- `--target PATH` — Target folder for downloads (default: current directory)
+
+## Cron Setup
+
+Add to your crontab (e.g., every 6 hours):
+
+```cron
+0 */6 * * * /path/to/uv run mediathekwatch check --target /mnt/media/TVShows
+```
+
+Or if installed globally:
+
+```cron
+0 */6 * * * /home/user/.local/bin/mediathekwatch check --target /mnt/media/TVShows
+```
+
+## Filename Format
+
+Downloaded episodes are organized as:
+
+```
+<Target Folder>/<Series Name>/S<Season>/<Series> - S<season>E<episode> - <episode name>.mkv
+```
+
+Example:
+
+```
+/mnt/media/TVShows/Feuer und Flamme/S11/Feuer und Flamme - S11E05 - Der neue Fall.mkv
+```
+
+## Database Schema
+
+Three tables are maintained in DuckDB:
+
+- `groups` — download groups with target folders
+- `monitored_series` — series being tracked
+- `downloaded_episodes` — episodes already downloaded
+
+## Project Structure
+
+```
+src/mediathekwatch/
+├── __init__.py    # Package init
+├── main.py        # CLI entry point
+├── cli.py         # Command handlers
+├── models.py      # Episode/Series dataclasses
+├── database.py    # DuckDB interface
+├── api/           # API clients (ARD, ARTE, ZDF)
+└── download.py    # yt-dlp wrapper & filename utils
+```
+
+## Notes
+
+- The tool queries ARD Mediathek, ARTE.tv EMAC, and ZDF GraphQL APIs to discover episodes.
+- yt-dlp is invoked with flags for embedding thumbnails, subtitles, metadata, chapters, and info-json.
+- Episodes are skipped if they already exist in the `downloaded_episodes` table; use `redownload` to override.
+
+## Acknowledgments
+
+- Thanks to the [MediathekView](https://mediathekview.de/) project for providing valuable insights into the structure of German public media APIs.
+
+## Development
+
+```bash
+# Run tests
+uv run pytest
+
+# Type check
+uv run pyright
+```