spdx-headers 1.5.0

A command-line tool for managing SPDX headers in Python source files

SPDX Headers

spdx-headers is a command-line tool for auditing and maintaining SPDX license headers in Python projects. It can add, verify, and update SPDX headers, extract license texts, and integrates seamlessly with pre-commit.

Table of Contents

1. Features
2. Installation
3. Quick Start
4. Core Commands
5. Using As a Pre-Commit Hook
6. Documentation
7. Contributing
8. License

Features

• Automated SPDX management – add, change, remove, or verify headers across your Python sources.
• Auto-fix missing headers – infer the repository’s SPDX identifier and repair files automatically.
• SPDX license data updates – fetches the latest license list directly from SPDX.
• Pre-commit integration – ships with a hook that can block commits or auto-fix issues.
• License extraction – generate LICENSE files by SPDX identifier.
• Dry-run support – inspect changes before applying them.
• Typed codebase – includes py.typed for first-class type checking.
• Flexible license viewing – preview SPDX license summaries and optionally keep the generated files for reference.
• Configurable exclusions – opt specific files out of header checks via a .spdx-headers.ini file.

Recent Enhancements

• Individual file targeting – Use --file to target specific files instead of entire directories
• Enhanced directory targeting – Improved --path option with better path resolution
• Better copyright detection – Automatically detects copyright information from repository root
• Template-ready version script – The bump_version.py script now works across different projects with dynamic license detection

Installation

pip install spdx-headers

Working from Source (with uv)

The development workflow relies on uv for dependency management. Install it first:

curl -LsSf https://astral.sh/uv/install.sh | sh
# or: pipx install uv

Then clone the repository and install dependencies:

git clone https://github.com/uglyegg/spdx-tools.git
cd spdx-tools
uv sync --dev
uv run pre-commit install

Quick Start

# Add AGPL-3.0-or-later headers to all Python files
spdx-headers --add AGPL-3.0-or-later

# Verify all files have valid SPDX headers
spdx-headers --verify

# Check (CI friendly) and auto-fix missing headers when possible
spdx-headers --check --fix

# List SPDX identifiers containing “Apache”
spdx-headers --list Apache

# Extract the MIT license into LICENSE-MIT
spdx-headers --extract --add MIT --dry-run

# Target a specific file
spdx-headers --file src/my_module.py --add MIT

# Target a specific directory
spdx-headers --path src/utils --add Apache-2.0

Core Commands

Command	Description
spdx-headers --add LICENSE	Add the specified SPDX header to all Python files.
spdx-headers --change LICENSE	Replace existing headers with the specified SPDX identifier.
spdx-headers --remove	Remove SPDX headers from all Python files.
spdx-headers --verify	Print a report of files missing headers (no exit code).
spdx-headers --check [--fix]	Return exit code 0/1 depending on compliance; --fix attempts auto-repair and the command reports detected SPDX identifiers (listing files if multiple licenses are found).
spdx-headers --list [KEYWORD]	List available SPDX identifiers, optionally filtering by keyword.
spdx-headers --show LICENSE [--keep-temp]	Display a license summary using the system’s default viewer (optionally keep the temp file).
spdx-headers --extract [KEYWORD] [--add LICENSE]	Extract license text for identifiers matching KEYWORD; combine with --add/--change to write headers and license text together.
spdx-headers --update	Download the latest SPDX license data.
spdx-headers --file FILENAME	Target an individual Python file instead of a directory. Overrides --path.
spdx-headers --path DIRECTORY	Specify the directory path to operate on. Defaults to auto-detected source directory.
.spdx-headers.ini	Optional configuration file used to exclude generated/vendor files from checks.

See docs/usage.md for a comprehensive walkthrough.

Using As a Pre-Commit Hook

spdx-headers ships with a pre-commit hook that checks for (and can auto-fix) missing headers. Add the following to your .pre-commit-config.yaml:

- repo: https://github.com/uglyegg/spdx-tools
  rev: v1.0.0
  hooks:
    - id: spdx-header-check

The bundled configuration automatically runs spdx-headers --check --fix, so files missing a header are rewritten when the repository has a consistent SPDX identifier. See docs/pre-commit.md for advanced configuration.

Documentation

• docs/usage.md – extended CLI usage guide, tips, and examples.
• docs/pre-commit.md – integrating the tool with pre-commit.
• docs/configuration.md – managing .spdx-headers.ini exclusions.
• docs/github-actions.md – integrating the tool with GitHub Workflows.
• docs/dev-workflow – workflow when working on development for this application.

Contributing

Contributions are welcome! Please open an issue or pull request. When submitting changes:

1. Run make check to execute formatting, lint, mypy, and test suites.
2. Update or add documentation in docs/ if behaviour changes.
3. Add tests covering new functionality.

License

This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See the LICENSE file for details. Additional license texts can be generated via spdx-headers --extract.