Licenseheaders

Common errors

• Not a built-in template

  cause 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.')

  cause 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).

  cause 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.

Warnings

• gotcha Template 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'`).
• gotcha The 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.
• gotcha When 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.
• gotcha The `--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.

Install

• pip install licenseheaders Install stable version

Imports

• 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.

Quickstart

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")