Metadata-Version: 2.1
Name: pib-cli
Version: 1.2.0
Summary: Python Development CLI
Home-page: https://github.com/niall-byrne/pib_cli
License: MPL-2.0
Keywords: development cli,development docker,development environment,development testing,development tooling,development utility,pib,python-in-a-box
Author: Niall Byrne
Author-email: niall@niallbyrne.ca
Requires-Python: >=3.7.0,<3.11.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Utilities
Provides-Extra: docs
Provides-Extra: docstrings
Provides-Extra: pib_docs
Provides-Extra: types
Requires-Dist: GitPython (>=3.1.26,<4.0.0)
Requires-Dist: PyYAML (>=5.4.1,<7.0.0)
Requires-Dist: bandit (>=1.7.0,<2.0.0)
Requires-Dist: click (>=8.0.1,<9.0.0)
Requires-Dist: commitizen (>=2.20.0,<3.0.0)
Requires-Dist: darglint (>=1.8.1,<2.0.0); extra == "docs"
Requires-Dist: isort (>=5.10.0,<6.0.0)
Requires-Dist: jinja2 (>=2.11.3,<4.0.0)
Requires-Dist: jsonschema (>=4.4.0,<5.0.0)
Requires-Dist: mypy; extra == "types"
Requires-Dist: pre-commit (>=2.17.0,<3.0.0)
Requires-Dist: pydocstyle (>=6.1.1,<7.0.0); extra == "docstrings"
Requires-Dist: pylint (>=2.8.3,<3.0.0)
Requires-Dist: pytest (>=7.0.1,<8.0.0)
Requires-Dist: pytest-cov (>=3.0.0,<4.0.0)
Requires-Dist: pytest-pylint (>=0.18.0,<0.19.0)
Requires-Dist: safety (>=1.10.3,<2.0.0)
Requires-Dist: sphinx (>=4.4.0,<5.0.0); extra == "docs" or extra == "pib_docs"
Requires-Dist: sphinx-autopackagesummary (>=1.3,<2.0); extra == "docs" or extra == "pib_docs"
Requires-Dist: sphinx-click (>=3.1.0,<4.0.0); extra == "pib_docs"
Requires-Dist: sphinx-intl (>=2.0.1,<3.0.0); extra == "pib_docs"
Requires-Dist: sphinx-jsonschema (>=1.17.2,<2.0.0); extra == "pib_docs"
Requires-Dist: sphinx_rtd_theme (>=1.0.0,<2.0.0); extra == "docs" or extra == "pib_docs"
Requires-Dist: wheel (>=0.37.1,<0.38.0)
Requires-Dist: yamllint (>=1.26.3,<2.0.0)
Requires-Dist: yapf (>=0.32.0,<0.33.0)
Project-URL: Documentation, https://github.com/niall-byrne/pib_cli/blob/develop/README.md
Project-URL: Repository, https://github.com/niall-byrne/pib_cli
Description-Content-Type: text/markdown

# PIB CLI

A batteries included [make](https://www.gnu.org/software/make/) style CLI for [python](https://python.org) projects in [git](https://git-scm.com/) repositories.

[Project Documentation](https://pib_cli.readthedocs.io/en/latest/)

## Master Branch

[![pib_cli-automation](https://github.com/niall-byrne/pib_cli/workflows/pib_cli%20Automation/badge.svg?branch=master)](https://github.com/niall-byrne/pib_cli/actions)

## Production Branch

[![pib_cli-automation](https://github.com/niall-byrne/pib_cli/workflows/pib_cli%20Automation/badge.svg?branch=production)](https://github.com/niall-byrne/pib_cli/actions)

## Documentation Builds

[![Documentation Status](https://readthedocs.org/projects/pib-cli/badge/?version=latest)](https://pib-cli.readthedocs.io/en/latest/?badge=latest)

## Supported Python Versions

Tested to work with the following Python versions:

  - Python 3.7
  - Python 3.8
  - Python 3.9
  - Python 3.10

## Installation

To install, simply use: 

  - `pip install pib_cli`
  - `pip install pib_cli[docs]` (Adds [Sphinx](https://www.sphinx-doc.org/en/master/) support.)
  - `pip install pib_cli[docstrings]` (Adds [pydocstyle](http://www.pydocstyle.org/en/stable/) support.)
  - `pip install pib_cli[types]` (Adds [mypy](http://mypy-lang.org/) support.)

## Usage

- The CLI itself is launched with the `dev` command.
- Try `dev --help` for details.

## With Cookiecutter

`pib_cli` is also baked into this [Cookie Cutter](https://github.com/cookiecutter/cookiecutter) template:

  - [Python In A Box](https://github.com/niall-byrne/python-in-a-box)

## License

[MPL-2](https://github.com/niall-byrne/pib_cli/blob/master/LICENSE)

## Included Packages

As it's batteries included, `pib_cli` ships with a slightly opinionated list of popular development packages.  You can customize the exact mix by specifying one or more [extras](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/?highlight=extras#installing-extras) when installing the package. 

### Core installed packages
| package       | Description                       |
| ------------- | --------------------------------- |
| bandit        | Finds common security issues      |
| commitizen    | Standardizes commit messages      |
| isort         | Sorts imports                     |
| pre-commit    | Pre-commit hook manager           |
| pylint        | Static code analysis              |
| pytest        | Testing with Python               |
| pytest-cov    | Coverage support for pytest       |
| pytest-pylint | Pylint support for pytest         |
| safety        | Dependency vulnerability scanning |
| wheel         | Package distribution tools        |
| yamllint      | Lint YAML configuration files     |
| yapf          | Customizable code formatting      |

### Installed and required by pib_cli
| package       | Description                        |
| ------------- | ---------------------------------- |
| click         | Command line interface toolkit     |
| jsonschema    | JSON Schema validation for Python  |
| GitPython     | Interact with Git repositories     |
| PyYAML        | YAML parser and emitter for Python |

  - `pip install pib_cli` to install only these dependencies.
  - These become indirect **development** dependencies of **YOUR** project, so it's good to keep that in mind.

### 'docs' extras
| package                   | Description                                                |
| ------------------------- | ---------------------------------------------------------- |
| darglint                  | Sphinx style guide enforcement                             |
| sphinx                    | Python documentation generator                             |
| sphinx-autopackagesummary | Template nested module content                             |
| sphinx_rtd_theme          | The [Read the Docs](https://readthedocs.org/) Sphinx theme | 

  - `pip install pib_cli[docs]` to add these dependencies to the core installation.

### 'docstrings' extras
| package    | Description                       |
| ---------- | --------------------------------- |
| pydocstyle | PEP 257 enforcement               |

  - `pip install[docstrings]` to add these dependencies to the core installation.

### 'types' extras
| package    | Description                       |
| ---------- | --------------------------------- |
| mypy       | Static type checker               |

  - `pip install pib_cli[types]` to add these dependencies to the core installation.

### 'pib_docs' extras
| package                   | Description                                                |
| ------------------------- | ---------------------------------------------------------- |
| sphinx                    | Python documentation generator                             |
| sphinx-autopackagesummary | Templates nested module content                            |
| sphinx-click              | Generates CLI documentation                                |
| sphinx-intl               | Generates documentation translations                       |
| sphinx-jsonschema         | Generates JSON schema documentation                        |
| sphinx_rtd_theme          | The [Read the Docs](https://readthedocs.org/) Sphinx theme | 

  - `pip install pib_cli[pib_docs]` to add these dependencies to the core installation.
  - These extras exist only to support building `pib_cli` documentation- they aren't meant to be consumed by user projects.

### Installing multiple extras

This is straightforward to do:

  - `pip install pib_cli[docs,docstrings,types]`

## Customizing the Command Line Interface

The most powerful feature of `pib_cli` is its ability to customize how it interacts with the packages it brings to your project.  In this way it's very similar to the standard Linux [make](https://www.gnu.org/software/make/) command- with the notable difference being that `pib_cli` is packaged with a suite of Python libraries.

**The CLI configuration file is in YAML format, and conforms to [this](https://github.com/niall-byrne/pib_cli/blob/master/pib_cli/config/schemas) set of JSON schemas.**

  - pib_cli v1.0.0 introduces a [new JSON schema version](https://github.com/niall-byrne/pib_cli/blob/master/pib_cli/config/schemas/cli_base_schema_v2.0.0.json).
  - pib_cli v1.2.0 introduces [further refinements to the JSON schema](https://github.com/niall-byrne/pib_cli/blob/master/pib_cli/config/schemas/cli_base_schema_v2.1.0.json) but is fully backwards compatible with v1.0.0, and **ALL** legacy configuration files.

### Creating a '.pib.yml' file

The `.pib.yml` file is where you can take control, and customize `pib_cli` behaviour to suit your particular needs.  This file should adhere to the specification detailed above- read on for further detail.

The top level of your `.pib.yml` file should include metadata information.  This metadata is used to tell `pib_cli` where to find your project's codebase and any documentation (Sphinx) definitions.

```yaml
metadata:
  project_name: "Tell pib_cli the folder your codebase is in."
  documentation_root: "Tell pib_cli where to find your documentation definitions."
cli_definition:
  - [A YAML array of cli command definitions, which are detailed in the next section].
```

  - The `cli_definition` section is mandatory, and `pib_cli` will throw an error if it's missing.
  - The metadata itself though is actually optional, and can also be declared using environment variables.

**Understanding pib_cli metadata**

Metadata tells `pib_cli` where to find your project's files, so it's important to set these values appropriately:

  - `project_name` is your project's name from a Python perspective.  It's the top level folder (inside your git repository) that houses your codebase, such that `from <project_name> import *` would be accessing your codebase.
  - `documentation_root` is a relative path from your repository's root to a folder containing a Sphinx Makefile.  This is purely a convenience definition for any documentation related commands.

**Environment variables and pib_cli**

You may also define your project's metadata by setting environment variables.  This would allow you to reuse the same CLI configuration for multiple projects:

  - `project_name` can also be defined by `PIB_PROJECT_NAME` environment variable
  - `documentation_root` can also be defined by the `PIB_DOCUMENTATION_ROOT` environment variable

When configuration AND environment variables exist, `pib_cli` will **prefer to use environment variable values**.

**Environment variables and pib_cli commands**

Regardless of whether you have used configuration or environment variables, when your CLI commands are executed, the environment variables will be available in the shell:

  - `PIB_PROJECT_NAME` will always be defined and accessible from inside the shell
  - `PIB_DOCUMENTATION_ROOT` will always be defined and accessible from inside the shell


### Adding a CLI definition to a '.pib.yml' file

The `cli_definition` YAML key, should contain a list of definitions for CLI commands you wish to use.

Each command should adhere to this format (and you can have many commands for whatever tasks you need to perform):

```yaml
    - name: "command-name"
      description: "A description of the command."
      container_only: false # Optional restriction of the command to a PIB container
      path: "repo_root"
      commands:
        - "one or more"
        - "shell commands"
        - "each run in a discrete environment"
        - "The ${PIB_DOCUMENTATION_ROOT} environment variable is also available if you need to navigate to that folder."
        - "The ${PIB_PROJECT_NAME} environment variable is available if you need to navigate to that folder."
        - "Any extra arguments passed are stored in the ${PIB_OVERLOAD_ARGUMENTS} environment variable."
      success: "Success Message"
      failure: "Failure Message"
```

Notes on this configuration format: 

  - `container_only` restricts the command to working only inside a [Python-in-a-Box](https://github.com/niall-byrne/python-in-a-box) container environment.  (Completely optional key to include, defaults to `false`.)
  - `path` must be one of:
    - `repo_root` (The root folder of your code repository.)
    - `documentation_root` (Defaults to the folder `documentation`, can be customized with metadata or environment variables.)
    - `project_root` (The `project_name` folder as defined with metadata or environment variables.)

### Validating a '.pib.yml' file

Use `pib_cli` to validate new configuration files before activating them:

  - `dev @pib config -c <path to your file> validate`

### Activating a '.pib.yml' file

To `activate` your configuration, use one of the following methods:

   1. You can set the environment variable `PIB_CONFIG_FILE_LOCATION` to the absolute path where the file is located.
   2. Or just move your new `.pib.yml` file to the top level folder (the repository root) of your project.

Use the command `dev @pib config where` to confirm it's been activated.

If a `.pib.yml` file cannot be found with either of these methods, then the [default config](https://github.com/niall-byrne/pib_cli/blob/master/pib_cli/config/default_cli_config.yml) will be used.

## Development Guide for `pib_cli`

Please see the documentation [here](https://github.com/niall-byrne/pib_cli/blob/master/CONTRIBUTING.md).

## Environment Variable Summary

This table summarizes the environment variables that can be used with `pib_cli`:

| Name                      | Purpose                                                                   |
| ------------------------- | ------------------------------------------------------------------------- |
| PIB_CONFIG_FILE_LOCATION  | The absolute path to the configuration file that should be used.          | 
| PIB_DOCUMENTATION_ROOT    | A relative path from the repository root where a Sphinx Makefile lives.   |
| PIB_OVERLOAD_ARGUMENTS    | Reserved to pass arguments to customized CLI commands.                    |
| PIB_PROJECT_NAME          | The top level folder in the repository where the codebase is found.       |

