Chepy Plugins

Chepy allows users to extend Chepy and add plugins to it. This documentation describes how to create or load plugins in Chepy. For current official Chepy plugins, refer to this docs, or this repo. These plugins are disabled by default, but can be enabled using the config file. If an import requirement fails for any of the built in plugins, it will show a message showing which one failed.

To use the existing plugin path directory, use cli_plugin_path from the cli to identify the plugin path, or refer to the chepy.conf file.

chepy.conf file

The chepy.conf file is what controls various aspects of how chepy runs. This file can be located in the users home directory. Plugins can be enabled or disabled with Plugins.enableplugins in the chepy.conf file.

The default Chepy conf file on setup looks like this:

enableplugins = true
pluginpath = None
# this needs to be an absolute path. Plugins are loaded from this directory

historypath = /home/hapsida/.chepy/chepy_history
# controls where the Chepy cli history is saved. This path will be set to
# the users home dir automatically on setup.

Plugins folder location

The location of the plugins folder can be found in the chepy.conf file. To use custom plugins, set the value of pluginpath in this file.

pluginpath = /some/dir/

Chepy will attempt to read the plugins folder (if one is set) to resolve any plugins from it.

Creating plugins

Naming plugins

Because Chepy utilizes name spaces to load its plugins, all plugin files needs to be named as This ensures that there are no namespace conflicts.

Plugin files should be placed in the directory that is specified by the pluginpath in chepy.conf

Plugin module

All Chepy plugins have to follow a specific format for best results.

  • ChepyCore needs to be inherited in the plugin class

  • Methods must have google style docstrings.

  • Methods should preferably be prefixed with something that distinguishes them. For example myplugin_somemethod. This avoids namespace conflicts.

Sample plugin

Plugin Asciinema

This is a bare bones example of how a Chepy plugin works. In this case, myplugin_method will be available in both Chepy cli (with auto completion) and the Chepy library.

The only thing this plugin at the moment will do is take whatever value is in the state, and multiply it with 20. All methods in Chepy plugins should set the value of self.state and should return self. This allows chaining with other methods that are available.

import chepy.core

class MyPlugin(chepy.core.ChepyCore):
    def myplugin_method(self):
        """another method
            ChepyPlugin: The chepy object
        self.state = self.state * 20
        return self

Lets breakdown this sample plugin.

Importing ChepyCore

import chepy.core

class MyPlugin(chepy.core.ChepyCore):

    def myplugin_method(self):

All Chepy plugins needs to inherit the ChepyCore class. This ensures that all the core attributes and methods from ChepyCore are available to the plugin.

The ChepyDecorators class offers stack methods to decorate plugin methods with. In this example, the call_stack decorator is being applied to the myplugin_method method. Although using the decorator is not required, it is recommended. This decorator ensures that that external plugins are also able to use the recipe feature.


"""another method
    Chepy: The chepy object

This is an example of Google style docstrings in python. Chepy cli parses these doc strings to show the help message and command completion dynamically. Although this can be omitted, it is strong recommended to have them to leverage the best capabilities of Chepy. The return type of ChepyPlugin is important for both autocompletion, and also highlighting the method as a plugin method.

Method body

This could be any code that the method is trying to accomplish


self.state = self.state * 20
return self


These two lines are very important. Both Chepy cli and library allows the user to chain various methods with each other.

  • self.state = ... This line ensures that the value being produced by the method can be accessed by other methods in Chepy.

  • return self This line ensures that methods can be changed together. Example,

In the example gif and asciinema, we can see how we first load the hello string to chepy, then call our myplugin_method, and then modify the output with to_hex followed by base64_encode.

Using plugins in script

As all plugins found in the directory is loaded automatically by Chepy at init, using plugins in script is super simple.

This code is equivalent to what is happening in the gif and asciinema.

from chepy import Chepy

c = Chepy("hello").myplugin_method().to_hex().base64_encode()


If you do create a plugin that is helpful, feel free to share it, or make a pull request!