pype-cli 0.3.4

A command-line tool for command-line tools

pype

A command-line tool for command-line tools

DISCLAIMER: This project is in alpha stage and interfaces can still change a lot.

In a nutshell

pype-cli is a CLI-configurable 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 on your system
  • To use an alternative name install via PYPE_CUSTOM_SHELL_COMMAND=my_cmd_name pip3 install --user pype-cli
• 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-config.json. To configure a custom configuration file use the environment variable PYPE_CONFIGURATION_FILE, e.g. in your ~/.bashrc file set export PYPE_CONFIGURATION_FILE=/path/to/myconfig.json.

Basic operations

• List all available pypes: pype -l
• Open pype-cli's configuration file: pype -o
• Refer to pype ... -h for further information on the command-line

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 (unfortunatly there is no corresponding solution for zshell):

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

Un-/register plugins

• Register an existing plugin: pype pype.config plugin-register -n myplugin -p ~/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 -c -n myplugin -p ~/pype_plugins
• Unregister (but not delete) a plugin: pype pype.config plugin-unregister -n 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 -c mypype
• Create a new pype from a template with less boilerplate: pype myplugin --minimal -c mypype or pype myplugin -mc mypype
• Create a new pype from minimal template and open immediately: pype myplugin --minimal --edit -c mypype or pype myplugin -mec mypype
• Open a pype in your default editor: pype myplugin -o mypype
• Delete a pype: pype myplugin -d 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 -r mm myplugin mypype → alias mm="pype myplugin mypype"
• Register an alias with options: pype -r mm myplugin mypype -o opt1 -v → alias mm="pype myplugin mypype -o opt1 -v"
• Unregister an alias: pype -u mm

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.

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)

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.