pype-cli

A command-line tool for command-line tools

In a nutshell

pype-cli is a command-line tool to manage sets of other command-line tools. It simplifies the creation, orchestration and access of Python scripts that you require for your development work, process automation, etc.

Quickstart

• Install pype-cli via pip3 install --user pype-cli. This will install the command pype for the current user
• To use an alternative name you need to install from source via PYPE_CUSTOM_SHELL_COMMAND=my_cmd_name python3 setup.py install --user
• Run pype pype.config shell-install and open a new shell to activate shell completion
• Create a new plugin in your home folder: pype pype.config plugin-register --create --name my-plugin --path ~/
• Create a sample pype for your plugin: pype my-plugin --create-pype my-pype
• Run your pype: pype my-plugin my-pype
• Show and edit the template pype you've just created: pype my-plugin --open-pype my-pype

You'll find more information on the commands in the sections below.

Usage

pype-cli builds upon plugins and pypes. A pype is a single Python script whereas a plugin is essentially a Python module that extens pype-cli with a collection of pypes.

pype-cli ships with one built-in plugin called pype.config that is used to configure pype-cli. All of the required information will be stored to a local JSON-configuration file that defaults to ~/.pype-cli/config.json. To configure a custom configuration folder use the environment variable PYPE_CONFIG_FOLDER. For example to use /path/to/pype-cli/config.json as configuration folder/file put into your ~/.bashrc file: export PYPE_CONFIG_FOLDER=/path/to/pype-cli.

Basic operations

• List all available pypes: pype --list-pypes
• Open pype-cli's configuration file: pype --open-config
• Refer to pype ... --help for further information on the command-line

For all options you will find a short variant such as -h for --help or pype -l instead of pype --list-pypes. They are omitted here for better readability.

Install pype autocompletion and aliases

pype-cli's main benefit is that is is extendable with custom plugins and that it will allow you to immediatelly browse and use newly created and existing plugins/pypes by using the <TAB> key and by configuring short aliases. To enable the functionality it is required to install a source-script to your shell's rc-file that will be executed everytime you open a shell.

• Run pype pype.config shell-install
• Run pype pype.config shell-uninstall to remove if necessary

If you want to use one-tab completion (instead of two tab presses) you can add the following section to your .bashrc file:

bind 'set show-all-if-ambiguous on'
bind 'set completion-ignore-case on'

For .zshrc apply instead:

unsetopt listambiguous

Un-/register plugins

• Register an existing plugin: pype pype.config plugin-register --name myplugin --path ~/pype_plugins (myplugin is a Python module with at least an __init__.py file and ~/pype_plugins a folder where the plugin is stored)
• On-the-fly create and register a new plugin: pype pype.config plugin-register --create --name myplugin --path ~/pype_plugins
• Unregister (but not delete) a plugin: pype pype.config plugin-unregister --name myplugin

Create, open and delete pypes

To create a new pype you need to decide to which plugin you want to add the pype, e.g., myplugin.

• Create a new pype from a template: pype myplugin --create mypype
• Create a new pype from a template with less boilerplate: pype myplugin --minimal --create mypype
• Create a new pype from minimal template and open immediately: pype myplugin --minimal --edit --create mypype
• Open a pype in your default editor: pype myplugin --open-pype mypype
• Delete a pype: pype myplugin --delete-pype mypype

Un-/register aliases

If you have selected a pype from a plugin you can set aliases for it. Afterwards you need to start a new shell session or source your rc-file to activate the aliases. New aliases are stored in the configuration file.

• Register an alias: pype --alias-register mm myplugin mypype → alias mm="pype myplugin mypype"
• Register an alias with options: pype --alias-register mm myplugin mypype --option opt1 --toggle → alias mm="pype myplugin mypype --option opt1 --toggle"
• Unregister an alias: pype --alias-unregister mm
• List all avaliable aliases: pype --aliases

Global logging configuration

pype-cli contains a built-in logger setup. To configure it use the pype pype pype.config logger. In your pypes you can use it right away like in the provided example.

• Enable/disable global logging: pype pype.config logger enable/disable
• Print current configuration: pype pype.config logger print-config
• Set logging folder: pype pype.config logger set-directory /your/login/folder
• Set logging level: pype pype.config logger set-level DEBUG
• Set logging pattern: pype pype.config logger set-pattern "%(asctime)s %(levelname)s %(name)s %(message)s"

Shared code for plugins

If your plugin contains shared code over all pypes you can simply put it into a subpackage of your plugin or into a file prefixed with __, e.g., __commons__.py. pype-cli will only scan / consider top-level Python scripts without underscores as pypes.

Example recipes

You can register a sample plugin called basics that contains some useful recipes to get you started with your own pipes.

• Register the basics plugin: pype pype.config plugin-register --name basics --path <PYPE_REPOSITORY>/example_pypes
• Navigate to pype basics <TAB> to see its content
• Open a recipe in your edior, for example: pype basics --open-pype hello-world-opt

For some basic information you can also refer to the built-in template.py and template_minimal.py that are used on creation of new pypes.

Note that as long as you don't import some of the convenience utilities of pype-cli directly, your pype will remain an independent Python script that can be used regardless of pype_cli.

Best practises

pype-cli has been built around the Click-project ("Command Line Interface Creation Kit") which is a Python package for creating beautiful command line interfaces. To fully utilize the capabilities of pype-cli it is highly recommended to get familiar with the project and use it in your pypes as well. Again you can refer to the basics plugin for guidance.

pype-cli development

• Run make venv to create a new virtual environment
• Run pipenv shell to activate a local shell with the required configurations
• Run pype to operate locale development version (it will react to code changes)
• Run PYPE_BENCHMARK_INIT=1 pype to print loading times for individual plugins or pypes

How to release

• Switch to latest main branch after making sure it is stable
• Get latest changelog via make changelog and update CHANGELOG.md
• Run NEXT_VERSION=0.0.3 make release
• Trigger Github action to release to PyPi

License and attribution

This software is licensed under Apache License 2.0.

Icon made by Freepik from Flaticon is licensed by CC 3.0 BY.