Metadata-Version: 2.1
Name: jfaleiro.setup-headers
Version: 0.0.2
Summary: Sets a standard header in all source files
Home-page: https://gitlab.com/jfaleiro.open/setup_headers
Author: Jorge M. Faleiro Jr.
Author-email: j@falei.ro
License: Affero GPL, see LICENSE for details
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: cerberus
Requires-Dist: pyyaml
Requires-Dist: glom

# 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

```bash
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:

```python
...
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`:

```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`:

```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](https://stackoverflow.com/questions/49047402/python-3-6-glob-include-hidden-files-and-folders).

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:

```text
     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:

```bash
$ 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:

```yaml
# 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
```


