Dependencies

This project has no runtime dependencies. All packages listed here are used exclusively for development, testing, or documentation. They are declared as optional dependency groups in pyproject.toml.

Installing dependency groups

# Testing and linting
pip install -e ".[dev]"

# Documentation
pip install -e ".[docs]"

# Both at once
pip install -e ".[dev,docs]"

---

Dev dependencies

Declared in pyproject.toml under [project.optional-dependencies] dev.

pytest ≥8.0

Test framework. Discovers, runs, and reports on all tests in the tests/ directory.

Configuration — pyproject.toml lines 28–30:

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "--junit-xml=test-results.xml --tb=short"

• testpaths restricts discovery to tests/ so pytest never accidentally picks up source files.
• --junit-xml=test-results.xml writes a structured XML report after every run. This file is stamped with a version comment by conftest.py:_stamp_outputs() and uploaded as a CI artifact.
• --tb=short keeps failure tracebacks concise in both terminal output and test-output.txt.

Usage in tests/test_rename.py:

Line	Feature	Purpose
5	import pytest	Brings pytest APIs into the test module
26	pytest.exit()	Aborts the entire session immediately if the test file repo cannot be cloned — prevents misleading empty-pass results
31, 38	pytest.skip()	Skips test_tmp_files_up_to_date gracefully when the test directory is not a git repo or the remote is unreachable
64	@pytest.fixture(scope="module")	Declares script_output as a module-scoped fixture so the CLI subprocess runs once and its stdout is shared across all parametrized cases
74	@pytest.mark.parametrize(...)	Expands _CASES (the list of (original, renamed) tuples from _expected_renames()) into individual test cases, one per file
75	record_property	Attaches renamed_from and renamed_to metadata to each test case node in test-results.xml, making the XML report machine-readable by downstream tools

Usage in conftest.py:

Line	Feature	Purpose
7	import pytest	Brings pytest hook and decorator APIs into conftest
79	@pytest.hookimpl(hookwrapper=True)	Wraps pytest_sessionfinish so it can yield control to pytest's own finish logic (which writes test-results.xml) before running post-session steps
12	pytest_sessionstart hook	Fires at session start; opens test-output.txt and patches the terminal reporter's write method to tee all output into the file simultaneously
80	pytest_sessionfinish hook	Fires after all tests and after junitxml has written test-results.xml; closes the tee file, stamps both artifacts with the version string, and (locally only) calls create_archive()
103	pytest_unconfigure hook	Safety net that ensures test-output.txt is closed even if pytest_sessionfinish is skipped or raises

---

ruff ≥0.9

Linter and formatter. Enforces code style and catches errors across all .py files. Runs automatically via editor integration and is applied to files on save.

Configuration — pyproject.toml lines 21–26:

[tool.ruff]
line-length = 88
target-version = "py314"

[tool.ruff.lint]
select = ["E", "F", "I"]

Setting	Value	Effect
line-length	88	Maximum line length before ruff flags or wraps a line
target-version	py314	Tells ruff which Python syntax features are valid; prevents it from flagging Python 3.14-only constructs
E rule set	pycodestyle errors	Flags whitespace, indentation, and formatting violations
F rule set	pyflakes	Flags undefined names, unused imports, and other logical errors
I rule set	isort	Enforces a consistent import ordering and grouping across all files

Ruff replaces what would otherwise require three separate tools: flake8 (E/F rules) and isort (I rules). It is significantly faster than either because it is written in Rust.

---

Docs dependencies

Declared in pyproject.toml under [project.optional-dependencies] docs. Used only to build and deploy the documentation site — not required for development or testing.

mkdocs-material ≥9.0

Documentation theme and site builder. Provides the visual theme, navigation system, search, and site generation on top of MkDocs.

Configuration — mkdocs.yml lines 6–10:

theme:
  name: material
  features:
    - navigation.instant
    - content.code.copy

Feature	Effect
navigation.instant	Turns the docs site into a single-page application — page transitions happen without a full reload, making navigation feel fast
content.code.copy	Adds a copy-to-clipboard button to every code block in the docs

The mkdocs gh-deploy --force command used in .github/workflows/docs.yml is provided by MkDocs core, which mkdocs-material depends on. It builds the static site and force-pushes it to the gh-pages branch on every push to main.

mkdocstrings[python] ≥0.25

Auto-generates API reference pages from Python docstrings. Reads source files in src/ and renders function signatures, parameters, and docstrings as formatted documentation pages.

Configuration — mkdocs.yml lines 13–17:

plugins:
  - mkdocstrings:
      handlers:
        python:
          paths: [src]

paths: [src] tells mkdocstrings where the package source lives so it can resolve filename_ingest without requiring the package to be installed in the docs build environment.

Usage in docs/api.md:

::: filename_ingest.build_pattern
::: filename_ingest.rename_files
::: filename_ingest.archive.create_archive

Each ::: directive resolves to the named Python object and renders its docstring inline in the page. When a function's signature or docstring changes in source, the API reference page updates automatically on the next docs deploy — no manual editing required.