Hello, world! ============= On the :doc:`homepage `, we showed you the following *"Hello world!"* plugin as an example: .. code-block:: python from errbot import BotPlugin, botcmd class HelloWorld(BotPlugin): """Example 'Hello, world!' plugin for Errbot""" @botcmd def hello(self, msg, args): """Say hello to the world""" return "Hello, world!" In this chapter, you will learn exactly how this plugin works. I will assume you've configured the `BOT_EXTRA_PLUGIN_DIR` as described in the previous chapter. To get started, create a new, empty directory named `HelloWorld` inside this directory. Create a new file called `helloworld.py` inside the `HelloWorld` directory you just created. This file contains all the logic for your plugin, so copy and paste the above example code into it. Anatomy of a BotPlugin ---------------------- Although this plugin is only 9 lines long, there is already a lot of interesting stuff going on here. Lets go through it step by step. .. code-block:: python from errbot import BotPlugin, botcmd This should be pretty self-explanatory. Here we import the :class:`~errbot.botplugin.BotPlugin` class and the :func:`~errbot.decorators.botcmd` decorator. These let us build a class that can be loaded as a plugin and allow us to mark methods of that class as bot commands. .. code-block:: python class HelloWorld(BotPlugin): """Example 'Hello, world!' plugin for Errbot""" Here we define the class that makes up our plugin. The name of your class, `HelloWorld` in this case, is what will make up the name of your plugin. This name will be used in commands such as `!status`, `!plugin load` and `!plugin unload` The class' docstring is used to automatically populate the built-in command documentation. It will be visible when issuing the `!help` command. .. warning:: A plugin should only ever contain a single class inheriting from :class:`~errbot.botplugin.BotPlugin` .. code-block:: python @botcmd def hello(self, msg, args): """Say hello to the world""" return "Hello, world!" This method, `hello`, is turned into a bot command which can be executed because it is decorated with the :func:`~errbot.decorators.botcmd` decorator. Just as with the class docstring above, the docstring here is used to populate the `!help` command. The name of the method, `hello` in this case, will be used as the name of the command. That means this method creates the `!hello` command. .. note:: The method name must comply with the usual Python naming conventions for `identifiers `_ , that is, they may not begin with a digit (like ``911`` but only with a letter or underscore, so ``_911`` would work) and cannot be any of the `reserved keywords `_ such as ``pass`` (instead use ``password``) etc. .. note:: Should multiple plugins define the same command, they will be dynamically renamed (by prefixing them with the plugin name) so that they no longer clash with each other. If we look at the function definition, we see it takes two parameters, `msg` and `args`. The first is a :class:`~errbot.backends.base.Message` object, which represents the full message object received by Errbot. The second is a string (or a list, if using the `split_args_with` parameter of :func:`~errbot.decorators.botcmd`) with the arguments passed to the command. For example, if a user were to say `!hello Mister Errbot`, `args` would be the string `"Mister Errbot"`. Finally, you can see we return with the string `Hello, world!`. This defines the response that Errbot should give. In this case, it makes all executions of the `!hello` command return the message *Hello, world!*. .. note:: If you return `None`, Errbot will not respond with any kind of message when executing the command. Plugin metadata --------------- We have our plugin itself ready, but if you start the bot now, you'll see it still won't load your plugin. What gives? As it turns out, you need to supply a file with some meta-data alongside your actual plugin file. This is a file that ends with the extension `.plug` and it is used by Errbot to identify and load plugins. Lets go ahead and create ours. Place the following in a file called `helloworld.plug`: .. code-block:: ini [Core] Name = HelloWorld Module = helloworld [Python] Version = 3 [Documentation] Description = Example "Hello, world!" plugin .. note:: This INI-style file is parsed using the Python `configparser `_ class. Make sure to use a `valid `_ file structure. Lets look at what this does. We see two sections, `[Core]` , and `[Documentation]`. The `[Core]` section is what tells Errbot where it can actually find the code for this plugin. The key `Module` should point to a module that Python can find and import. Typically, this is the name of the file you placed your code in with the `.py` suffix removed. The key `Name` should be identical to the name you gave to the class in your plugin file, which in our case was `HelloWorld`. While these names can differ, doing so is not recommended. .. note:: If you're wondering why you have to specify it when it should be the same as the class name anyway, this has to do with technical limitations that we won't go into here. The `[Documentation]` section will be explained in more detail further on in this guide, but you should make sure to at least have the `Description` item here with a short description of your plugin. Python Submodules ----------------- In cases where the plugin code base is large and complex, it may be desirable to break the code into submodules to be imported by the plugin. The following directory tree shows a commonly used layout for submodules: .. code-block:: bash plugins ├── LICENSE ├── helloworld.plug ├── helloworld.py ├── README.md ├── requirements.txt ├── lib │   ├── __init__.py │   ├── moduleA.py │   ├── moduleB.py │   ├── moduleC.py The presence of `__init__.py` indicates `lib` is a Python regular package. Assuming `moduleA` has the function `invert_string()`, the `helloworld` plugin can import it and use it with the following syntax: .. code-block:: python from lib.moduleA import invert_string from errbot import BotPlugin, botcmd class HelloWorld(BotPlugin): """Example 'Hello, world!' plugin for Errbot""" @botcmd def hello(self, msg, args): """Say hello to the world""" return invert_string("Hello, world!") Packaging --------- A plugin can be packaged and distributed through pypi.org. The errbot plugin system uses entrypoints in setuptools to find available plugins. The two entrypoint available are * `errbot.plugins` - normal plugin and flows * `errbot.backend_plugins` - backend plugins for collaboration providers To get this setup, add this block of code to `setup.py`. .. code-block:: python entry_points = { "errbot.plugins": [ "helloworld = helloWorld:HelloWorld", ] } Optionally, you may need to include a `MANIFEST.in` to include files of the repo .. code-block:: python include *.py *.plug Wrapping up ----------- If you've followed along so far, you should now have a working *Hello, world!* plugin for Errbot. If you start your bot, it should load your plugin automatically. You can verify this by giving the `!status` command, which should respond with something like the following:: Yes I am alive... With these plugins (A=Activated, D=Deactivated, B=Blacklisted, C=Needs to be configured): [A] ChatRoom [A] HelloWorld [A] VersionChecker [A] Webserver If you don't see your plugin listed or it shows up as unloaded, make sure to start your bot with *DEBUG*-level logging enabled and pay close attention to what it reports. You will most likely see an error being reported somewhere along the way while Errbot starts up. Next steps ---------- You now know enough to create very simple plugins, but we have barely scratched the surface of what Errbot can do. The rest of this guide will be a recipe-style set of topics that cover all the advanced features Errbot has to offer.