Skip to content

BastiTee/pype-cli

Repository files navigation

pype-cli

A command-line tool for command-line tools

pype-cli Logo

GitHub Workflow Status PyPU - Version PyPI - Python Version

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.

pype-cli GIF

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 mypypealias mm="pype myplugin mypype"
  • Register an alias with options: pype --alias-register mm myplugin mypype --option opt1 --togglealias 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.