subliminal 2.5.0__tar.gz → 2.7.0__tar.gz

{subliminal-2.5.0 → subliminal-2.7.0}/.github/actions/prepare-tests/action.yaml

@@ -10,13 +10,13 @@ runs:
       run: |
         echo "::error title=⛔ error hint::Support Linux, Windows, and macOS Only"
         exit 1
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v7
       with:
         persist-credentials: false
         fetch-depth: 0
     - name: Cache test data
       id: cache-test-data
-      uses: actions/cache@v4
+      uses: actions/cache@v5
       with:
         path: tests/data/
         enableCrossOsArchive: true
@@ -34,7 +34,7 @@ runs:
       with:
         packages: rar
         version: 1.0
-    - uses: actions/setup-python@v5
+    - uses: actions/setup-python@v6
       if: steps.cache-test-data.outputs.cache-hit != 'true'
       with:
         python-version-file: .python-version-default
@@ -52,7 +52,7 @@ runs:
         tox -e prepare-tests
 
     # - name: Upload files for test
-    #   uses: actions/upload-artifact@v4
+    #   uses: actions/upload-artifact@v7
     #   with:
     #     name: tests-data
     #     path: tests/data/

{subliminal-2.5.0 → subliminal-2.7.0}/.github/workflows/CI.yaml

@@ -20,7 +20,7 @@ jobs:
   check-manifest:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
       - run: pipx run check-manifest --ignore "_version.py"
@@ -28,10 +28,10 @@ jobs:
   pre-commit:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version-file: .python-version-default
       - uses: pre-commit/action@v3.0.1
@@ -41,10 +41,10 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version-file: .python-version-default
       - name: Install hatch
@@ -58,10 +58,10 @@ jobs:
     name: Build docs and run doctests
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           # Keep in sync with tox/docs, hatch.toml and .readthedocs.yaml.
           python-version-file: .python-version-default
@@ -76,7 +76,7 @@ jobs:
       - name: Check changelog
         run: hatch run changelog:run
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: docs
           path: docs/_build/
@@ -86,10 +86,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version-file: .python-version-default
           cache: pip
@@ -104,7 +104,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
           fetch-depth: 0
@@ -122,7 +122,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
           fetch-depth: 0
@@ -142,10 +142,10 @@ jobs:
         # Created by the build-and-inspect-python-package action above.
         py: ${{ fromJson(needs.build-package.outputs.supported-python-versions) }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.py }}
           allow-prereleases: true
@@ -181,7 +181,7 @@ jobs:
         shell: bash
 
       - name: Store coverage file
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: coverage-${{ matrix.os }}-${{ matrix.py }}
           path: .coverage*
@@ -196,17 +196,17 @@ jobs:
       pull-requests: write
       contents: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           # py-cov-action/python-coverage-comment-action needs git credentials
           persist-credentials: true
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version-file: .python-version-default
       - uses: hynek/setup-cached-uv@v2
 
       - name: Download coverage data
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           pattern: coverage-*
           merge-multiple: true
@@ -222,7 +222,7 @@ jobs:
           coverage report --skip-covered --skip-empty --show-missing --format=markdown >> $GITHUB_STEP_SUMMARY
 
       - name: Upload HTML report if check failed.
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: html-report
           path: htmlcov
@@ -234,7 +234,7 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Store Pull Request comment to be posted
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         if: steps.coverage_comment.outputs.COMMENT_FILE_WRITTEN == 'true'
         with:
           # If you use a different name, update COMMENT_ARTIFACT_NAME accordingly
@@ -247,10 +247,10 @@ jobs:
     runs-on: ubuntu-latest
     needs: [build-package, prepare-test]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         id: setup
         with:
           python-version-file: .python-version-default
@@ -287,7 +287,7 @@ jobs:
         shell: bash
 
       - name: Store coverage file
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         if: ${{ failure() }}
         with:
           name: core-coverage

{subliminal-2.5.0 → subliminal-2.7.0}/.github/workflows/docker-build.yaml

@@ -35,12 +35,12 @@ jobs:
     steps:
       - name: Checkout repository
         if: github.event_name == 'push' || github.event_name == 'pull_request'
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         with:
           persist-credentials: false
       - name: Checkout repository
         if: github.event_name == 'workflow_call' || github.event_name == 'workflow_dispatch'
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         with:
           ref: ${{ inputs.tag-name }}
           persist-credentials: false
@@ -50,15 +50,15 @@ jobs:
           github.event_name == 'push'
           || github.event_name == 'workflow_call'
           || github.event_name == 'workflow_dispatch'
-        uses: docker/setup-qemu-action@v3
+        uses: docker/setup-qemu-action@v4
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
         with:
           cache-binary: false
 
       - name: Log in to the Container registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
@@ -66,7 +66,7 @@ jobs:
 
       - name: Extract metadata (tags, labels) for Docker
         id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@v6
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |
@@ -76,7 +76,7 @@ jobs:
             type=semver,pattern={{major}},enable=${{ !startsWith(github.ref, 'refs/tags/0.') }}
 
       - name: Test building Docker image
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@v7
         if: github.event_name == 'pull_request'
         with:
           context: .
@@ -86,7 +86,7 @@ jobs:
           cache-to: type=gha,mode=max
 
       - name: Build and push Docker image
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@v7
         if: |
           github.event_name == 'push'
           || github.event_name == 'workflow_call'

{subliminal-2.5.0 → subliminal-2.7.0}/.github/workflows/prepare-release-pr.yaml

@@ -29,14 +29,14 @@ jobs:
       pull-requests: write
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v7
       with:
         fetch-depth: 0
         # persist-credentials is needed in order for us to push the release branch.
         persist-credentials: true
 
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version-file: .python-version-default
         cache: pip

{subliminal-2.5.0 → subliminal-2.7.0}/.github/workflows/publish-release.yaml

@@ -31,12 +31,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         if: github.event_name == 'push'
         with:
           persist-credentials: false
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         if: |
           github.event_name == 'workflow_dispatch'
           || github.event_name == 'workflow_call'
@@ -63,19 +63,19 @@ jobs:
     # Publish a Github release when a tag was pushed, or it's called with a tag.
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         with:
           fetch-tags: true
           ref: ${{ needs.build-package.outputs.tag }}
           persist-credentials: false
 
       - name: Download packages built by build-and-inspect-python-package
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: Packages
           path: dist
       - name: Publish GitHub Release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@v3
         with:
           files: dist/*
           generate_release_notes: true

{subliminal-2.5.0 → subliminal-2.7.0}/.github/workflows/publish.yaml

@@ -20,7 +20,7 @@ jobs:
     name: Build & verify package
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -45,7 +45,7 @@ jobs:
       && github.event.action == 'published'
     steps:
       - name: Download packages built by build-and-inspect-python-package
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: Packages
           path: dist

{subliminal-2.5.0 → subliminal-2.7.0}/.github/workflows/scheduled-tests.yaml

@@ -24,10 +24,10 @@ jobs:
       || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.x"
       - name: Prepare tests

{subliminal-2.5.0 → subliminal-2.7.0}/.github/workflows/tag-release.yaml

@@ -24,7 +24,7 @@ jobs:
     name: Build & verify package
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -72,7 +72,7 @@ jobs:
     env:
       RELEASE_VERSION: ${{ needs.define-tag.outputs.tag }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
           # keep credentials to create a tag

subliminal-2.7.0/.github/zizmor.yml

@@ -0,0 +1,11 @@
+rules:
+  dangerous-triggers:
+    ignore:
+      - coverage.yaml:3:1
+  unpinned-uses:
+    config:
+      policies:
+        "*": ref-pin
+  superfluous-actions:
+    ignore:
+      - publish-release.yaml:78:15

{subliminal-2.5.0 → subliminal-2.7.0}/.pre-commit-config.yaml

@@ -8,19 +8,19 @@ repos:
       - id: end-of-file-fixer
 
   - repo: https://github.com/crate-ci/typos
-    rev: v1.40.0
+    rev: v1.45.0
     hooks:
       - id: typos
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.9
+    rev: v0.15.10
     hooks:
       - id: ruff
         args: [--fix, --unsafe-fixes]
       - id: ruff-format
 
   - repo: https://github.com/abravalheri/validate-pyproject
-    rev: v0.24.1
+    rev: v0.25
     hooks:
       - id: validate-pyproject
         name: validate-pyproject
@@ -33,7 +33,7 @@ repos:
         require_serial: true
 
   - repo: https://github.com/woodruffw/zizmor-pre-commit
-    rev: v1.18.0
+    rev: v1.23.1
     hooks:
     - id: zizmor
 

subliminal-2.7.0/.python-version-default

@@ -0,0 +1 @@
+3.13

{subliminal-2.5.0 → subliminal-2.7.0}/.readthedocs.yaml

@@ -4,10 +4,10 @@
 version: 2
 
 build:
-  os: ubuntu-22.04
+  os: ubuntu-lts-latest
   tools:
     # Keep in sync with CI.yaml/docs, hatch.toml and tox/docs.
-    python: "3.12"
+    python: "3.13"
 
 python:
   install:

{subliminal-2.5.0 → subliminal-2.7.0}/HISTORY.rst

@@ -2,6 +2,63 @@
 
 .. towncrier release notes start
 
+2.7.0 (2026-07-21)
+^^^^^^^^^^^^^^^^^^
+
+Changes
+-------
+
+- Rename language_type to category. Deprecate ``--language-type-suffix`` for ``--category-suffix`` (`#1344 <https://github.com/Diaoul/subliminal/issues/1344>`__)
+- make EmbeddedSubtitle subtitle_id unique (`#1347 <https://github.com/Diaoul/subliminal/issues/1347>`__)
+- Safely call Guessit and format output (`#1351 <https://github.com/Diaoul/subliminal/issues/1351>`__)
+
+
+CLI Changes
+-----------
+
+- add a ``--subtitle-categories`` option to replace ``-hi/-HI`` and ``-fo/-FO`` (`#1357 <https://github.com/Diaoul/subliminal/issues/1357>`__)
+- check for undefined or deprecated entries in the config file (`#1358 <https://github.com/Diaoul/subliminal/issues/1358>`__)
+- Allow ``--name`` to be a sed-like ``s/pattern/replacement/flags`` substitution, applied to the path of each
+  file individually, to parameterize the guessed name per file (`#1362 <https://github.com/Diaoul/subliminal/issues/1362>`__)
+- allow multiple use of sed-like ``--name`` options (`#1364 <https://github.com/Diaoul/subliminal/issues/1364>`__)
+
+
+Documentation
+-------------
+
+- fix docs for config file with the subtitle_categories option (`#1360 <https://github.com/Diaoul/subliminal/issues/1360>`__)
+
+
+Misc
+----
+
+- Drop Python 3.9 (`#1345 <https://github.com/Diaoul/subliminal/issues/1345>`__)
+- fix gestdown tests (`#1354 <https://github.com/Diaoul/subliminal/issues/1354>`__)
+
+
+2.6.0 (2026-02-20)
+^^^^^^^^^^^^^^^^^^
+
+Provider Changes
+----------------
+
+- OpenSubtitlesCom: replace recursive ``_search()`` implementation to prevent a stack overflow in some edge case (`#1336 <https://github.com/Diaoul/subliminal/issues/1336>`__)
+- Add Subtis provider for Spanish subtitles (`#1337 <https://github.com/Diaoul/subliminal/issues/1337>`__)
+
+
+Refiner Changes
+---------------
+
+- hash: cache the result of hash_opensubtitles so it can be reused costlessly (`#1340 <https://github.com/Diaoul/subliminal/issues/1340>`__)
+
+
+Misc
+----
+
+- Fixes for some scheduled tests failures (`#1339 <https://github.com/Diaoul/subliminal/issues/1339>`__)
+- add a gif to show CLI usage (`#1341 <https://github.com/Diaoul/subliminal/issues/1341>`__)
+
+
 2.5.0 (2025-12-14)
 ^^^^^^^^^^^^^^^^^^
 

{subliminal-2.5.0 → subliminal-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: subliminal
-Version: 2.5.0
+Version: 2.7.0
 Summary: Subtitles, faster than your thoughts
 Project-URL: homepage, https://github.com/Diaoul/subliminal
 Project-URL: repository, https://github.com/Diaoul/subliminal
@@ -16,7 +16,6 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 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
@@ -24,7 +23,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Multimedia :: Video
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Requires-Dist: babelfish>=0.6.1
 Requires-Dist: beautifulsoup4>=4.4.0
 Requires-Dist: chardet>=5.0
@@ -56,7 +55,6 @@ Requires-Dist: rarfile>=2.7; extra == 'rar'
 Provides-Extra: tests
 Requires-Dist: colorama; extra == 'tests'
 Requires-Dist: coverage[toml]>=7; extra == 'tests'
-Requires-Dist: importlib-metadata>=4.6; (python_version < '3.10') and extra == 'tests'
 Requires-Dist: pytest-cov; extra == 'tests'
 Requires-Dist: pytest-xdist; extra == 'tests'
 Requires-Dist: pytest>=6.0; extra == 'tests'
@@ -103,6 +101,10 @@ Subtitles, faster than your thoughts.
 
 Usage
 -----
+
+.. image:: https://github.com/Diaoul/subliminal/blob/main/docs/assets/demo.gif
+    :alt: Demo of the app CLI usage
+
 CLI
 ^^^
 Download English subtitles::
@@ -120,7 +122,7 @@ By default it looks for a `subliminal.toml` file in the default configuration fo
 (see the CLI help for the exact platform-specific default path).
 Or use the `-c` option to specify the path to the configuration file.
 
-`Look for this example configuration file <https://github.com/Diaoul/subliminal/blob/main/docs/config.toml>`__
+`Look for this example configuration file <https://github.com/Diaoul/subliminal/blob/main/docs/assets/config.toml>`__
 or use the `generate_default_config` function from the `subliminal.cli` module to generate a
 configuration file with all the options and their default values::
 

{subliminal-2.5.0 → subliminal-2.7.0}/README.rst

@@ -30,6 +30,10 @@ Subtitles, faster than your thoughts.
 
 Usage
 -----
+
+.. image:: https://github.com/Diaoul/subliminal/blob/main/docs/assets/demo.gif
+    :alt: Demo of the app CLI usage
+
 CLI
 ^^^
 Download English subtitles::
@@ -47,7 +51,7 @@ By default it looks for a `subliminal.toml` file in the default configuration fo
 (see the CLI help for the exact platform-specific default path).
 Or use the `-c` option to specify the path to the configuration file.
 
-`Look for this example configuration file <https://github.com/Diaoul/subliminal/blob/main/docs/config.toml>`__
+`Look for this example configuration file <https://github.com/Diaoul/subliminal/blob/main/docs/assets/config.toml>`__
 or use the `generate_default_config` function from the `subliminal.cli` module to generate a
 configuration file with all the options and their default values::
 

{subliminal-2.5.0 → subliminal-2.7.0}/docs/api/providers.rst

@@ -43,6 +43,11 @@ Subtitulamos
 .. automodule:: subliminal.providers.subtitulamos
    :members:
 
+Subtis
+------
+.. automodule:: subliminal.providers.subtis
+   :members:
+
 TVsubtitles
 -----------
 .. automodule:: subliminal.providers.tvsubtitles

{subliminal-2.5.0/docs → subliminal-2.7.0/docs/assets}/config.toml

@@ -22,7 +22,7 @@ provider = ["addic7ed", "opensubtitlescom", "opensubtitles"]
 refiner = ["metadata", "hash", "omdb"]
 ignore_refiner = ["tmdb"]
 language = ["fr", "en", "pt-br"]
-foreign_only = false
+subtitle_categories = "n,hi"
 encoding = "utf-8"
 min_score = 50
 archives = true

{subliminal-2.5.0 → subliminal-2.7.0}/docs/user/configuration_file.rst

@@ -12,7 +12,7 @@ Sections
 
 The configuration file supports different sections or tables:
 
-    - a ``[default]`` table, corresponding to the options of the :ref:`cli-subliminal-download` command.
+    - a ``[default]`` table, corresponding to the options of the :ref:`cli-subliminal` command.
 
     - ``[refiner.<refiner_name>]`` and ``[provider.<provider_name>]`` tables to specify refiner and provider options.
 
@@ -24,9 +24,16 @@ CLI arguments (like ``path``) cannot be specified in the configuration file.
 
 Options that can be used multiple times (like ``--language``) need to be defined as arrays.
 
-``hearing_impaired`` and ``foreign_only`` can take three values: "true", "false" or "[]".
-They mean that hearing impaired (or foreign-only) subtitles will be, respectively,
-ranked first, ranked last or not given any particular rank, for subtitles with identical scores.
+Hyphens in parameter names need to be substituted by underscores in the config file:
+``--cache-dir=/tmp`` → ``cache_dir = "/tmp"``.
+
+.. note::
+    ``hearing_impaired`` and ``foreign_only`` can take three values: "true", "false" or "[]".
+    They mean that hearing impaired (or foreign-only) subtitles will be, respectively,
+    ranked first, ranked last or not given any particular rank, for subtitles with identical scores.
+
+    .. deprecated:: 2.7.04
+        Use ``--subtitle-categories`` instead.
 
 
 Example
@@ -34,7 +41,7 @@ Example
 
 An example of configuration file:
 
-.. literalinclude:: ../config.toml
+.. literalinclude:: ../assets/config.toml
     :language: toml
 
 

{subliminal-2.5.0 → subliminal-2.7.0}/docs/user/how_it_works.rst

@@ -13,6 +13,7 @@ subtitles. Current supported providers are:
 * OpenSubtitles
 * OpenSubtitles.com
 * Podnapisi
+* Subtis
 * Subtitulamos
 * TvSubtitles
 

{subliminal-2.5.0 → subliminal-2.7.0}/docs/user/usage.rst

@@ -52,6 +52,31 @@ See :ref:`cli` for more details on the available commands and options.
         $ python -m subliminal download -h
 
 
+Parameterized name
+^^^^^^^^^^^^^^^^^^^
+
+The ``--name/-n`` option lets you override the file name that is used to guess information about a video.
+In addition to a static alternative name, you can use a
+`sed <https://www.man7.org/linux/man-pages/man1/sed.1.html>`_-like substitution pattern
+``s/pattern/replacement/flags`` to override the names of all the files in a folder.
+The pattern needs to be a valid Python regex. Back-references (``\1``, ``\2``, …) are available in the
+replacement, and the ``g`` (replace all occurrences) and ``i`` (case-insensitive) flags are supported::
+
+    $ subliminal download -l pl \
+        --name 's/.*YP-1R-([0-9]+)x([0-9]+).*/My Little Pony Friendship Is Magic S\1E\2.mkv/' \
+        */YP-1R-*.mkv
+
+Unlike sed, ``&`` is a literal character (not the whole match), so titles containing an ampersand need
+no escaping::
+
+    $ subliminal download -l pl \
+        --name 's/.*_-_([0-9]+)_.*/Panty & Stocking with Garterbelt S01E\1.mkv/' \
+        *Garterbelt_-_*.mkv
+
+The substitution is applied to the path of each file (after the optional conversion to an absolute path
+with ``--use-absolute-path``), so the pattern can also match parent directories. Any file whose path does
+not match is left untouched and scanned as-is.
+
 Nautilus/Nemo integration
 -------------------------
 See the dedicated `project page <https://github.com/Diaoul/nautilus-subliminal>`_ for more information.