mnamer 2.6.1.dev18__tar.gz → 2.7.1__tar.gz

mnamer-2.7.1/.dockerignore

@@ -0,0 +1,8 @@
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.venv
+build
+dist
+*.egg-info
+__pycache__

{mnamer-2.6.1.dev18 → mnamer-2.7.1}/.github/actions/init/action.yml

@@ -7,7 +7,7 @@ runs:
     - uses: actions/setup-python@v5
       with:
         python-version: '3.12'
-        
+
     - name: Install uv
       uses: astral-sh/setup-uv@v4
       with:
@@ -16,4 +16,4 @@ runs:
 
     - name: Install dependencies
       shell: sh
-      run: uv sync --dev
+      run: uv sync --locked --dev

{mnamer-2.6.1.dev18 → mnamer-2.7.1}/.github/dependabot.yml

@@ -5,7 +5,7 @@
 
 version: 2
 updates:
-  - package-ecosystem: "pip"
+  - package-ecosystem: "uv"
     directory: "/"
     schedule:
       interval: "weekly"

mnamer-2.7.1/.github/workflows/publish-docker.yml

@@ -0,0 +1,251 @@
+name: publish docker
+
+on:
+  workflow_call:
+    inputs:
+      target:
+        required: true
+        type: string
+      release_tag:
+        required: false
+        type: string
+        default: ""
+      is_prerelease:
+        required: false
+        type: boolean
+        default: false
+    secrets:
+      DOCKERHUB_USERNAME:
+        required: true
+      DOCKERHUB_TOKEN:
+        required: true
+
+  workflow_dispatch:
+    inputs:
+      target:
+        description: What Docker image set to publish
+        required: true
+        type: choice
+        options:
+          - latest sha
+          - latest release
+
+env:
+  DOCKERHUB_IMAGE: jkwill87/mnamer
+  GHCR_IMAGE: ghcr.io/jkwill87/mnamer/mnamer
+
+jobs:
+  publish-docker:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Resolving Source
+        id: resolve
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RAW_TARGET: ${{ inputs.target || github.event.inputs.target }}
+          RELEASE_TAG: ${{ inputs.release_tag }}
+          IS_PRERELEASE: ${{ inputs.is_prerelease }}
+        run: |
+          set -euo pipefail
+
+          target="$(printf '%s' "$RAW_TARGET" | tr ' ' '-')"
+          main_sha="$(git ls-remote "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY.git" refs/heads/main | awk '{print $1}')"
+
+          case "$target" in
+            latest-sha)
+              checkout_ref="$main_sha"
+              release_tag=""
+              is_prerelease="false"
+              ;;
+            latest-release)
+              release_json="$(gh release view --repo "$GITHUB_REPOSITORY" --json tagName,isPrerelease)"
+              release_tag="$(jq -r '.tagName' <<<"$release_json")"
+              is_prerelease="$(jq -r '.isPrerelease' <<<"$release_json")"
+              checkout_ref="$release_tag"
+              ;;
+            event-release)
+              release_tag="$RELEASE_TAG"
+              is_prerelease="$IS_PRERELEASE"
+              checkout_ref="$release_tag"
+              ;;
+            *)
+              echo "Unsupported Docker publish target: $RAW_TARGET" >&2
+              exit 1
+              ;;
+          esac
+
+          if [ -z "$checkout_ref" ]; then
+            echo "Could not resolve a checkout ref for target: $RAW_TARGET" >&2
+            exit 1
+          fi
+
+          {
+            echo "target=$target"
+            echo "checkout_ref=$checkout_ref"
+            echo "main_sha=$main_sha"
+            echo "release_tag=$release_tag"
+            echo "is_prerelease=$is_prerelease"
+          } >> "$GITHUB_OUTPUT"
+
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ steps.resolve.outputs.checkout_ref }}
+          fetch-depth: 0
+
+      - name: Finalizing Tags
+        id: tags
+        env:
+          TARGET: ${{ steps.resolve.outputs.target }}
+          MAIN_SHA: ${{ steps.resolve.outputs.main_sha }}
+          RELEASE_TAG: ${{ steps.resolve.outputs.release_tag }}
+          IS_PRERELEASE: ${{ steps.resolve.outputs.is_prerelease }}
+        run: |
+          set -euo pipefail
+
+          source_sha="$(git rev-parse HEAD)"
+          aliases=()
+
+          if [ "$TARGET" = "latest-sha" ]; then
+            python -m pip install --quiet setuptools-scm[toml]
+            version="$(python -m setuptools_scm)"
+            aliases+=("dev")
+          else
+            version="${RELEASE_TAG#v}"
+            aliases+=("$version")
+
+            if [ "$IS_PRERELEASE" != "true" ]; then
+              aliases+=("latest")
+            fi
+
+            if [ "$TARGET" = "latest-release" ] && [ "$source_sha" = "$MAIN_SHA" ]; then
+              aliases+=("dev")
+            fi
+          fi
+
+          {
+            echo "source_sha=$source_sha"
+            echo "version=$version"
+            echo "aliases<<EOF"
+            printf '%s\n' "${aliases[@]}"
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Logging In To GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Logging In To Docker Hub
+        uses: docker/login-action@v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+          scope: jkwill87/mnamer@push
+
+      - name: Setting Up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Setting Up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Planning Docker Push
+        id: plan
+        env:
+          SOURCE_SHA: ${{ steps.tags.outputs.source_sha }}
+          ALIASES: ${{ steps.tags.outputs.aliases }}
+        run: |
+          set -euo pipefail
+
+          tag_is_current() {
+            local ref="$1"
+            local output
+            local error_file
+            error_file="$(mktemp)"
+
+            if ! output="$(docker buildx imagetools inspect "$ref" --raw 2>"$error_file")"; then
+              if grep -Eiq 'not found|manifest unknown|name unknown' "$error_file"; then
+                rm -f "$error_file"
+                return 1
+              fi
+
+              cat "$error_file" >&2
+              rm -f "$error_file"
+              return 2
+            fi
+
+            rm -f "$error_file"
+            revision="$(
+              jq -r '
+                .annotations["org.opencontainers.image.revision"]
+                // (.manifests[]?.annotations["org.opencontainers.image.revision"] // empty)
+              ' <<<"$output" | head -n 1
+            )"
+            [ "$revision" = "$SOURCE_SHA" ]
+          }
+
+          tags=()
+          while IFS= read -r alias; do
+            [ -n "$alias" ] || continue
+
+            tags+=("$GHCR_IMAGE:$alias")
+            tags+=("$DOCKERHUB_IMAGE:$alias")
+          done <<<"$ALIASES"
+
+          publish_tags=()
+          for tag in "${tags[@]}"; do
+            if tag_is_current "$tag"; then
+              echo "$tag is already current"
+            else
+              echo "$tag needs publishing"
+              publish_tags+=("$tag")
+            fi
+          done
+
+          if [ "${#publish_tags[@]}" -eq 0 ]; then
+            echo "All requested Docker tags are already current."
+            echo "should_push=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "should_push=true" >> "$GITHUB_OUTPUT"
+            {
+              echo "tags<<EOF"
+              printf '%s\n' "${publish_tags[@]}"
+              echo "EOF"
+            } >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Extracting Docker Metadata
+        if: steps.plan.outputs.should_push == 'true'
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: |
+            ${{ env.GHCR_IMAGE }}
+            ${{ env.DOCKERHUB_IMAGE }}
+          labels: |
+            org.opencontainers.image.title=mnamer
+            org.opencontainers.image.description=A command-line utility for organizing media files.
+            org.opencontainers.image.revision=${{ steps.tags.outputs.source_sha }}
+            org.opencontainers.image.version=${{ steps.tags.outputs.version }}
+
+      - name: Building And Publishing Docker Image
+        if: steps.plan.outputs.should_push == 'true'
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.plan.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          annotations: |
+            org.opencontainers.image.revision=${{ steps.tags.outputs.source_sha }}
+            org.opencontainers.image.version=${{ steps.tags.outputs.version }}
+            org.opencontainers.image.source=https://github.com/${{ github.repository }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

{mnamer-2.6.1.dev18 → mnamer-2.7.1}/.github/workflows/push.yml

@@ -49,3 +49,42 @@ jobs:
       inherit
 
     uses: ./.github/workflows/publish.yml
+
+  publish-docker-main:
+    if: >-
+      success()
+      && github.event_name == 'push'
+      && github.ref == 'refs/heads/main'
+
+    needs:
+      - lint
+      - test
+
+    secrets:
+      inherit
+
+    uses: ./.github/workflows/publish-docker.yml
+    with:
+      target: latest-sha
+
+  publish-docker-release:
+    if: >-
+      success()
+      && github.event_name == 'release'
+      && (
+        github.event.action == 'published'
+        || github.event.action == 'prereleased'
+      )
+
+    needs:
+      - lint
+      - test
+
+    secrets:
+      inherit
+
+    uses: ./.github/workflows/publish-docker.yml
+    with:
+      target: event-release
+      release_tag: ${{ github.event.release.tag_name }}
+      is_prerelease: ${{ github.event.release.prerelease }}

mnamer-2.7.1/AGENTS.md

@@ -0,0 +1,123 @@
+# AGENTS.md
+
+This file provides guidance to LLMs when working with code in this repository.
+
+## Project Overview
+
+mnamer (media renamer) is a command-line utility for organizing media files. It parses filenames for metadata using guessit, queries metadata providers (TMDb, OMDb, TVDb, TvMaze), and intelligently renames/moves files based on configurable templates.
+
+## Development Setup
+
+This project requires Python 3.12+ and uses `uv` as the package manager:
+
+```bash
+# Install dependencies
+uv sync --dev
+
+# Run mnamer locally
+uv run mnamer [args]
+```
+
+## Common Commands
+
+### Testing
+
+The test suite is organized by pytest markers. Keep local tests free of network
+access; network and e2e tests can be flaky because they exercise providers and
+the CLI workflow.
+
+```bash
+# Run local unit tests (no network)
+uv run pytest -m local
+
+# Run network tests (requires internet, may be flaky)
+uv run pytest -m network --reruns 3
+
+# Run end-to-end tests
+uv run pytest -m e2e --reruns 3
+
+# Run all tests with coverage
+uv run pytest --cov=./ --cov-report=term-missing
+
+# Run a specific test file
+uv run pytest tests/local/test_metadata.py
+
+# Run a specific test function
+uv run pytest tests/local/test_metadata.py::test_function_name
+```
+
+Registered markers are declared in `pytest.ini`: `local`, `network`, `e2e`,
+plus provider markers `omdb`, `tmdb`, `tvdb`, and `tvmaze`.
+
+### Linting and Formatting
+
+```bash
+# Check code with ruff
+uv run ruff check mnamer tests
+
+# Format code with ruff
+uv run ruff format mnamer tests
+
+# Type check with mypy
+uv run mypy mnamer tests
+```
+
+## Architecture
+
+### Core Data Flow
+
+1. **Entry Point** (`__main__.py:main`): Loads settings and initializes the CLI frontend
+2. **Frontend** (`frontends.py:Cli`): Orchestrates the file processing workflow
+3. **Target** (`target.py:Target`): Represents a media file, manages its metadata and relocation
+4. **Metadata** (`metadata.py`): Dataclasses for storing parsed and enriched metadata
+   - `MetadataMovie`: Movie-specific fields (name, year, id_imdb, id_tmdb)
+   - `MetadataEpisode`: TV episode fields (series, season, episode, id_tvdb, id_tvmaze)
+5. **Providers** (`providers.py`): High-level interface for querying metadata APIs
+   - `Tmdb`, `Omdb`: Movie providers
+   - `Tvdb`, `Tvmaze`: TV episode providers
+6. **Endpoints** (`endpoints.py`): Low-level API request functions and response TypedDicts
+
+### Key Architectural Patterns
+
+- **Metadata Parsing**: Uses `guessit` library to extract metadata from filenames. The `Target._parse()` method converts guessit output into `Metadata` objects.
+
+- **Target Discovery**: `Target.populate_paths()` crawls positional targets, applies `--recurse`, `--ignore`, `--mask`, de-duplicates paths, and filters by `--media` when supplied.
+
+- **Provider System**: Providers are registered per-provider in a class variable cache (`Target._providers`). `Provider.provider_factory()` instantiates providers based on the `ProviderType` enum and settings.
+
+- **Settings Management**: `SettingStore` loads configuration from both CLI arguments (`argument.py:ArgLoader`) and JSON config files (`.mnamer-v2.json`). CLI args take precedence over config files. Config-only fields include API keys and replacement maps.
+
+- **Template Formatting**: `MetadataMovie.__format__()` and `MetadataEpisode.__format__()` use `_MetaFormatter` to substitute template variables like `{name}`, `{season:02}`, and `{extension}`. Templates are configured per media type via settings.
+
+- **File Relocation**: `Target.destination` combines the optional `movie_directory` or `episode_directory` setting with the matching format template, then applies replacement, scene/lowercase settings, and filename sanitization. `Target.relocate()` creates destination directories and moves the file.
+
+### Important Implementation Details
+
+- **Subtitle Handling**: Subtitle files (`.srt`, `.idx`, `.sub`) are detected via `is_subtitle()`. They use the same format pattern as their media type and, when subtitle language is known, prefix the extension with the 2-letter language code (e.g., `.en.srt`).
+
+- **Language Support**: The `Language` class (in `language.py`) wraps babelfish for language code conversion. Providers return metadata in the language specified by `--language` setting.
+
+- **Request Caching**: API requests go through `utils.get_session()`, a `requests-cache` `CachedSession` stored under the user cache directory for six days. Cache can be cleared with the `--clear-cache` directive or bypassed per run with `--no-cache`.
+
+- **Error Handling**: Custom exceptions in `exceptions.py` distinguish between network errors (`MnamerNetworkException`), missing results (`MnamerNotFoundException`), and user actions (`MnamerSkipException`, `MnamerAbortException`).
+
+- **Test Organization**:
+  - `tests/local/`: Pure unit tests, no network or filesystem side effects
+  - `tests/network/`: Integration tests hitting real APIs (may be flaky)
+  - `tests/e2e/`: End-to-end tests with actual file operations
+
+## Configuration
+
+- **Config File**: `.mnamer-v2.json` in the current or parent directories, or the explicit path from `--config-path`
+- **Settings Precedence**: CLI arguments > config file > defaults
+- **Directives vs Parameters**: Directives (like `--test`, `--id-tmdb`) are one-time overrides not stored in config files
+- **Config-only Fields**: `api_key_omdb`, `api_key_tmdb`, `api_key_tvdb`, `api_key_tvmaze`, `replace_before`, and `replace_after` are only loaded from config/defaults, not CLI flags
+
+## API Keys
+
+Providers load API keys through `Provider.from_settings()` using config-only
+fields named `api_key_<provider>`. If unset, provider classes fall back to
+environment variables (`API_KEY_OMDB`, `API_KEY_TMDB`, `API_KEY_TVDB`,
+`API_KEY_TVMAZE`) and then bundled defaults where present.
+
+Check provider classes in `providers.py` for API key handling via `from_settings()` class method.

mnamer-2.7.1/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

mnamer-2.7.1/Dockerfile

@@ -0,0 +1,20 @@
+# syntax=docker/dockerfile:1
+
+FROM python:alpine AS builder
+
+RUN apk add --no-cache git
+WORKDIR /src
+COPY . .
+RUN pip wheel --no-cache-dir --wheel-dir /wheels .
+
+FROM python:alpine
+ARG UID=1000
+ARG GID=1000
+RUN addgroup mnamer -g "$GID"
+RUN adduser mnamer -u "$UID" -G mnamer --disabled-password
+COPY --from=builder /wheels/*.whl /tmp/
+RUN pip3 install --no-cache-dir --upgrade pip /tmp/*.whl \
+    && rm -f /tmp/*.whl
+USER mnamer
+ENTRYPOINT ["python", "-m", "mnamer"]
+CMD ["--batch", "/mnt"]

{mnamer-2.6.1.dev18 → mnamer-2.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mnamer
-Version: 2.6.1.dev18
+Version: 2.7.1
 Summary: A command-line utility for organizing media files.
 Author-email: Jessy Williams <jessy@jessywilliams.com>
 Maintainer-email: Jessy Williams <jessy@jessywilliams.com>
@@ -33,7 +33,7 @@ License-File: LICENSE.txt
 Requires-Dist: appdirs~=1.4.4
 Requires-Dist: babelfish~=0.6.1
 Requires-Dist: guessit~=3.8.0
-Requires-Dist: requests~=2.33.1
+Requires-Dist: requests<2.35.0,>=2.33.1
 Requires-Dist: requests-cache~=1.3.1
 Requires-Dist: setuptools-scm>=10.0.0
 Requires-Dist: teletype~=1.3.4
@@ -134,3 +134,11 @@ Parameters can either by entered as command line arguments or from a config file
 Community contributions are a welcome addition to the project. In order to be merged upstream any additions will need to be formatted with [ruff](https://docs.astral.sh/ruff/) for consistency with the rest of the project and pass the continuous integration tests run against each PR. Before introducing any major features or changes to the configuration api please consider opening [an issue](https://github.com/jkwill87/mnamer/issues) to outline your proposal.
 
 Bug reports are also welcome on the [issue page](https://github.com/jkwill87/mnamer/issues). Please include any generated crash reports if applicable. Feature requests are welcome but consider checking out [if it is in the works](https://github.com/jkwill87/mnamer/issues?q=label%3Arequest) first to avoid duplication.
+
+## Star History
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=jkwill87/mnamer&type=date&theme=dark&legend=top-left" />
+  <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=jkwill87/mnamer&type=date&legend=top-left" />
+  <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=jkwill87/mnamer&type=date&legend=top-left" />
+</picture>

{mnamer-2.6.1.dev18 → mnamer-2.7.1}/README.md

@@ -93,3 +93,11 @@ Parameters can either by entered as command line arguments or from a config file
 Community contributions are a welcome addition to the project. In order to be merged upstream any additions will need to be formatted with [ruff](https://docs.astral.sh/ruff/) for consistency with the rest of the project and pass the continuous integration tests run against each PR. Before introducing any major features or changes to the configuration api please consider opening [an issue](https://github.com/jkwill87/mnamer/issues) to outline your proposal.
 
 Bug reports are also welcome on the [issue page](https://github.com/jkwill87/mnamer/issues). Please include any generated crash reports if applicable. Feature requests are welcome but consider checking out [if it is in the works](https://github.com/jkwill87/mnamer/issues?q=label%3Arequest) first to avoid duplication.
+
+## Star History
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=jkwill87/mnamer&type=date&theme=dark&legend=top-left" />
+  <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=jkwill87/mnamer&type=date&legend=top-left" />
+  <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=jkwill87/mnamer&type=date&legend=top-left" />
+</picture>

{mnamer-2.6.1.dev18 → mnamer-2.7.1}/mnamer/__version__.py

@@ -1,4 +1,4 @@
 # file generated by setuptools_scm
 # don't change, don't track in version control
 
-__version__ = "2.6.1.dev18"
+__version__ = "2.7.1"

{mnamer-2.6.1.dev18 → mnamer-2.7.1}/mnamer.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mnamer
-Version: 2.6.1.dev18
+Version: 2.7.1
 Summary: A command-line utility for organizing media files.
 Author-email: Jessy Williams <jessy@jessywilliams.com>
 Maintainer-email: Jessy Williams <jessy@jessywilliams.com>
@@ -33,7 +33,7 @@ License-File: LICENSE.txt
 Requires-Dist: appdirs~=1.4.4
 Requires-Dist: babelfish~=0.6.1
 Requires-Dist: guessit~=3.8.0
-Requires-Dist: requests~=2.33.1
+Requires-Dist: requests<2.35.0,>=2.33.1
 Requires-Dist: requests-cache~=1.3.1
 Requires-Dist: setuptools-scm>=10.0.0
 Requires-Dist: teletype~=1.3.4
@@ -134,3 +134,11 @@ Parameters can either by entered as command line arguments or from a config file
 Community contributions are a welcome addition to the project. In order to be merged upstream any additions will need to be formatted with [ruff](https://docs.astral.sh/ruff/) for consistency with the rest of the project and pass the continuous integration tests run against each PR. Before introducing any major features or changes to the configuration api please consider opening [an issue](https://github.com/jkwill87/mnamer/issues) to outline your proposal.
 
 Bug reports are also welcome on the [issue page](https://github.com/jkwill87/mnamer/issues). Please include any generated crash reports if applicable. Feature requests are welcome but consider checking out [if it is in the works](https://github.com/jkwill87/mnamer/issues?q=label%3Arequest) first to avoid duplication.
+
+## Star History
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=jkwill87/mnamer&type=date&theme=dark&legend=top-left" />
+  <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=jkwill87/mnamer&type=date&legend=top-left" />
+  <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=jkwill87/mnamer&type=date&legend=top-left" />
+</picture>

{mnamer-2.6.1.dev18 → mnamer-2.7.1}/mnamer.egg-info/SOURCES.txt

@@ -1,5 +1,8 @@
+.dockerignore
 .gitignore
 .python-version
+AGENTS.md
+CLAUDE.md
 Dockerfile
 LICENSE.txt
 MANIFEST.in
@@ -12,6 +15,7 @@ uv.lock
 .github/actions/init/action.yml
 .github/actions/lint/action.yml
 .github/actions/test/action.yml
+.github/workflows/publish-docker.yml
 .github/workflows/publish.yml
 .github/workflows/pull_request.yml
 .github/workflows/push.yml

{mnamer-2.6.1.dev18 → mnamer-2.7.1}/mnamer.egg-info/requires.txt

@@ -1,7 +1,7 @@
 appdirs~=1.4.4
 babelfish~=0.6.1
 guessit~=3.8.0
-requests~=2.33.1
+requests<2.35.0,>=2.33.1
 requests-cache~=1.3.1
 setuptools-scm>=10.0.0
 teletype~=1.3.4

{mnamer-2.6.1.dev18 → mnamer-2.7.1}/pyproject.toml

@@ -13,7 +13,7 @@ dependencies = [
     "appdirs~=1.4.4",
     "babelfish~=0.6.1",
     "guessit~=3.8.0",
-    "requests~=2.33.1",
+    "requests>=2.33.1,<2.35.0",
     "requests-cache~=1.3.1",
     "setuptools-scm>=10.0.0",
     "teletype~=1.3.4",