PIB CLI

A batteries included make style CLI for python projects in git repositories.

Project Documentation

Master Branch

Production Branch

Documentation Builds

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 support.)
• pip install pib_cli[docstrings] (Adds pydocstyle support.)
• pip install pib_cli[types] (Adds mypy 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 template:

• Python In A Box

License

MPL-2

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 when installing the package.

Core installed packages

Installed and required by pib_cli

• 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

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

'docstrings' extras

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

'types' extras

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

'pib_docs' extras

• 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 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 set of JSON schemas.

• pib_cli v1.0.0 introduces a new JSON schema version.
• pib_cli v1.2.0 introduces further refinements to the JSON schema 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.

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

    - 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 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 will be used.

Development Guide for pib_cli

Please see the documentation here.

Environment Variable Summary

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