jfaleiro.setup-headers 0.0.2

Sets a standard header in all source files

setup_headers

Sets a standard header in all source files. Searches a project directory tree finding all files matching a sequence of glob patterns (e.g. **/*.py,*.cfg,**/config/*.yml), and replaces any comments on the beginning of the file by lines from a header file, preceded by a comment marker (a prefix).

The substitution does not apply to "hashbangs" (anything started by #!). These will be kept where they were originally.

Installation

pip install jfaleiro.setup_headers

It is recommended to add the dependency to a requirements-dev.txt or to a dev extras configuration. Dependencies set on test_requires are no longer recommended.

Configuration

Change your setup.py to reflect something like this:

...
from setup_headers import LicenseHeaderCommand
...
setup(
    ...
    entry_points={
        "distutils.commands": [
            "adjust_license_headers = setup_headers.command:LicenseHeaderCommand"
        ]
    },
    ...
)

If you intend to use a configuration file with a name different than headers.yaml you can add the name on the corresponding section in setup.cfg:

[adjust_license_headers]
config = my_headers.yaml

The section name must match the distutils.commands under entry_points in your setup.py (see above).

The configuration of where license headers will be added is given on the config attribute, what by defualt is named headers.yaml:

header: HEADER
prefixes:
  - prefix: "#"
    globs: [
    "setup_headers/**/*.py",
    "test/**/*.py",
    ".devcontainer/Dockerfile",
    "Makefile"]
  - prefix: "##"
    globs:
    - "*.yml"
    - "*.yaml"
  - prefix: "//"
    globs:
    - ".devcontainer/devcontainer.json"
  - prefix: ";"
    globs: [
        setup.cfg,
        tox.ini
      ]

Each prefix is a recognized comment character(s) on the beginning of each line in the header. Globs are a pathlib.glob() pattern. Only relative patterns are allowed.

The **/* comes from Python's Pathlib and indicates all matches under that directory. The pattern ** will match only sub-directories, what is probably not what you want.

Create a file matching the name on the header with what you want to be inserted on the beginning of all files that match the globs pattern, something like:

     my_awesome_project - Does something awesome

     Copyright (C) 2019 Joe Doe.

     This program is not free. You should pay lots of money to use it.
     Contact me for my paypal account.

     You should have received a copy of My Proprietary License
     along with this program.  If not, see <http://joe.doe/licenses/>.

Use

Setuptools Command

Just issue the command you have previously configured:

$ python setup.py adjust_license_headers --help
Common commands: ...
Global options: ...

Options for 'LicenseHeaderCommand' command:
  --config (-c)   YAML configuration file (default=headers.yaml)
  --dry-run (-d)  dry run (optional)

usage: ...

Command Line

You can also use the CLI for any projects that do not care or rely on setuptools:

$ adjust-license-header --help
usage: adjust-license-header [-h] [--config CONFIG] [--dry-run] [--prefix-mandatory] [files [files ...]]

positional arguments:
  files               process only files in the list (default: None)

optional arguments:
  -h, --help          show this help message and exit
  --config CONFIG     name of the YAML config file (default: headers.yaml)
  --dry-run           don't apply any changes (default: False)
  --prefix-mandatory  failure if file is not associated to a prefix (default: False

Pre-Commit

Finally, you can also make sure licenses are kept up to date at git commit time. Just add a .pre-commit-config.yaml to your project root:

# See https://pre-commit.com for more information on pre-commit
# See https://pre-commit.com/hooks.html for more hooks

repos:
-   repo: https://gitlab.com/jfaleiro.open/setup_headers
    rev: 0.0.2
    hooks:
    - id: adjust-license-header