licenseheaders

library0.8.8pypypi✓ verified 85d ago

licenseheaders is a Python 3 command-line tool designed to add or change license headers for all files of supported types in a given directory tree. It supports various predefined templates and allows for custom templates and variable substitutions. The current version is 0.8.8, and it appears to be actively maintained, with the last PyPI update on April 8, 2021, and GitHub issues still being addressed.

devops

pip install licenseheaders

github ↗package ↗

INSTALL

IMPORT

SIG · LICENSEHEADERS

licenseheaders

devopspythonv0.8.8

Install

2.2s avg

Import

125ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.8.8 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.133s · 20.5MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.2s · import 0.118s · 22MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

main

✓ from licenseheaders import main

Primarily a CLI tool, direct programmatic usage is less common than invoking via `python -m licenseheaders` or the `licenseheaders` command. The `main` function serves as the CLI entry point.

This quickstart demonstrates how to use `licenseheaders` via its command-line interface to add a predefined license template (LGPLv3) to a specific Python file, including a custom copyright owner.

import os # Ensure licenseheaders is installed: pip install licenseheaders # Create a dummy file for demonstration with open("example.py", "w") as f: f.write("def my_func():\n pass\n") # Run licenseheaders from the command line to add an LGPLv3 license # to a dummy Python file in the current directory, with a specific owner. # This simulates running `licenseheaders -t lgpl3 -o "Your Name" -f example.py` print("Adding LGPLv3 license to example.py...") os.system('python -m licenseheaders -t lgpl3 -o "Your Name" -f example.py') print("\nContent of example.py after adding license:") with open("example.py", "r") as f: print(f.read()) # Clean up os.remove("example.py")

licenseheaders --version

Debug

Known issues

gotchaTemplate variables (e.g., ${varname}) are substituted from environment variables prefixed with `LICENSE_HEADERS_` (e.g., `LICENSE_HEADERS_VARNAME`) or from command-line options. Ensure consistent naming or explicit definition to avoid missing substitutions, which can lead to incomplete license headers.

fix

Define variables explicitly using command-line arguments (e.g., `-o 'Your Name'`) or set corresponding environment variables (e.g., `export LICENSE_HEADERS_OWNER='Your Name'`).

affects: All versions

gotchaThe tool relies on recognizing specific comment styles for different languages. If `--additional-extensions` is used, the specified language must have a recognized comment style, otherwise files might not be processed. Additionally, file extensions containing multiple dots (e.g., '.py.j2') are not currently supported.

fix

For unsupported extensions or custom file types, consider using a custom template that includes the correct comment delimiters. Avoid using extensions with multiple dots.

affects: All versions

gotchaWhen integrated into pre-commit hooks or other isolated environments, `licenseheaders` may fail to find its bundled license templates, resulting in a 'Not a built-in template' error.

fix

Provide the full, absolute path to the template file instead of just its name (e.g., `-t /path/to/my_template.tmpl`). Ensure the template file is accessible within the hook's environment.

affects: All versions

gotchaThe `--enc` command-line parameter for specifying file encoding might not correctly handle or apply the encoding when reading templates, potentially leading to issues with non-UTF-8 characters in headers or content.

fix

Ensure all template files are saved in UTF-8 encoding. If issues persist, verify file content manually or consider pre-processing templates to ensure correct encoding before passing them to the tool.

affects: All versions

Errors

Common errors & fixes

Not a built-in template

The `licenseheaders` tool cannot locate its bundled license templates, often occurring in isolated environments like pre-commit hooks where the package's internal file structure is not correctly mapped.

fix

When specifying a template, use the full path to a custom template file (e.g., `licenseheaders -t /path/to/my_license.tmpl ...`) instead of relying on built-in template names.

XML parsing error or corrupted XML files after processing (e.g., 'Error: Content is not allowed in prolog.')

XML files require a specific processing instruction (e.g., `<?xml version="1.0" encoding="UTF-8"?>`) to be the very first line. If `licenseheaders` inserts a comment *before* this instruction, it invalidates the XML structure.

fix

Use the `--exclude` option to prevent `licenseheaders` from processing XML files (e.g., `licenseheaders ... -x '**/*.xml'`). Manually add headers to XML files, ensuring the XML processing instruction remains the first line.

Copyright years in headers are incorrectly extracted or updated, sometimes picking up arbitrary four-digit numbers (e.g., '1950 Main St' becomes part of a year range).

The regular expression used by some license header tools to identify and update copyright years might be too broad, inadvertently matching other four-digit numbers in the file content, leading to incorrect year ranges or garbled headers.

fix

Review the `--years` or `--current-year` arguments carefully. If using custom templates, ensure the year variable (`${YEARS}`) is clearly isolated from other numerical content. If the issue persists, consider manually inspecting and correcting affected files, or contributing a more specific regex to the project.

Upgrade

Version history

0.8.8latest on PyPI · released Apr 8, 2021

Audit

Dependencies

regexrequiredUsed for parsing and manipulating file content, especially when identifying and replacing license blocks.

Agent activity

12 hits · last 30 days

node

Resources

githubhttp://github.com/johann-petrak/licenseheaders ↗

packagehttps://pypi.org/project/licenseheaders/ ↗