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:
[Plugins]
enableplugins = true
pluginpath = None
# this needs to be an absolute path. Plugins are loaded from this directory
[Cli]
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.
[Plugin]
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 chepy_some_plugin.py. 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
https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
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¶
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):
@chepy.core.ChepyDecorators.call_stack
def myplugin_method(self):
"""another method
Returns:
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):
@chepy.core.ChepyDecorators.call_stack
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.
Docstrings¶
"""another method
Returns:
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
Returns¶
self.state = self.state * 20
return self
Important
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()
print(c)
Tip
If you do create a plugin that is helpful, feel free to share it, or make a pull request!