Limnoria-doc/develop/plugin_tutorial.rst

.. _plugin-tutorial:

**********************************
Writing Your First Limnoria Plugin
**********************************

Introduction
============

This page is a top-down guide on how to write new plugins for Limnoria.

Before you start, you should be more-or-less familiar with how to use and
manage a Limnoria instance (loading plugins, configuring options, etc.).
You should also install a copy of Limnoria on the machine you intend to develop
plugins on, as it includes some additional scripts like
:command:`supybot-plugin-create` to generate the plugin skeleton.

We'll go through this tutorial by actually writing a new plugin, named Random
with just a few commands.

Generating the Plugin template
==============================

The recommended way to start writing a plugin is to use the
:command:`supybot-plugin-create` wizard. You can run this from within your bot's
plugins directory, or make a separate directory for all your own plugins and run
it there. (You can add additional plugin directories to your bot config using
``config directories.plugins``). The latter approach is probably easier if you
intend to publish your code afterwards, as it keeps your code separate from any
other plugins you've installed.

Here's an example session::

    $ supybot-plugin-create
    What should the name of the plugin be? Random

    Sometimes you'll want a callback to be threaded.  If its methods
    (command or regexp-based, either one) will take a significant amount
    of time to run, you'll want to thread them so they don't block the
    entire bot.

    Does your plugin need to be threaded? [y/n] n

    What is your name, so I can fill in the copyright and license
    appropriately? John Doe

    Do you wish to use Supybot's license for your plugin? [y/n] y

    Please provide a short description of the plugin: This plugin contains
    commands relating to random numbers, including random sampling from a list
    and a simple dice roller.

README.md
==========

This is the README page people will see when they download your plugin or view
it from a source control website. It's helpful to include a brief summary of
what the plugin does here, as well as list any third-party dependencies.

The :command:`supybot-plugin-create` wizard should have already filled in the
README with the summary you provided.

__init__.py
===========
The next file we'll look at is :file:`__init__.py`. If you're not so familiar
with the Python import mechanism, think of it as sort of the "glue" file that
pulls all the files in the plugin directory together when you load it.
There are also a few administrative items here that can be queried from the bot,
such as the plugin's author and contact info.

At the top of the file you'll see the copyright header, with your name added as
prompted in :command:`supybot-plugin-create`. Feel free to use whatever
license you choose: the default is the bot's 3-clause BSD. For our example,
we'll leave it as is.

Here is a list of attributes you should usually look at:

* ``__version__``: the plugin version. We'll just make ours "0.1"
* ``__author__`` should be an instance of the :class:`supybot.Author` class.
  This optionally includes a full name, a short name (usually IRC nick), and
  an e-mail address::

    __author__ = supybot.Author(name='Daniel DiPaolo', nick='Strike',
                                email='somewhere@someplace.xxx')

* ``__contributors__`` is a dictionary mapping :class:`supybot.Author`
  instances to lists of things they contributed. See e.g. `in the Plugin plugin
  <https://github.com/progval/Limnoria/blob/master/plugins/Plugin/__init__.py#L42-L49>`_.
  For now we have no contributors, so we'll leave it blank.

* ``__url__`` references the download URL for the plugin. Since this is just an
  example, we'll leave this blank.

The rest of :file:`__init__.py` really shouldn't be touched unless you are
using third-party modules in your plugin. If you are, then you need to add
additional import statements and ``reload`` calls to all those modules, so that
they get reloaded with the rest of the plugin::

    from . import config
    from . import plugin
    from importlib import reload
    reload(plugin) # In case we're being reloaded.
    # Add more reloads here if you add third-party modules and want them
    # to be reloaded when this plugin is reloaded.  Don't forget to
    # import them as well!

config.py
=========
:file:`config.py` is, unsurprisingly, where all the configuration stuff
related to your plugin goes. For this tutorial, the Random plugin is simple
enough that it doesn't need any config variables, so this file can be left as
is.

To briefly outline this file's structure: the ``configure`` function is used by
the :command:`supybot-wizard` wizard and allows users to configure the plugin
further if it's present when the bot is first installed. (In practice though,
this is seldomly used by third-party plugins as they're generally installed
*after* configuring the bot.)

The following line registers an entry for the plugin in Limnoria's config
registry, followed by any configuration groups and variable definitions::

    Random = conf.registerPlugin('Random')
    # This is where your configuration variables (if any) should go.  For example:
    # conf.registerGlobalValue(Random, 'someConfigVariableName',
    #     registry.Boolean(False, _("""Help for someConfigVariableName.""")))

Writing plugin configuration is explained in depth
in the :ref:`Advanced Plugin Config Tutorial <configuration-tutorial>`.

plugin.py
=========
Here's the moment you've been waiting for, the overview of plugin.py and how to
make our plugin actually do stuff.

At the top, same as always, is the standard copyright block to be used and
abused at your leisure.

Next, some standard imports. Not all of them are used at the moment, but you
probably will use many (if not most) of them, so just let them be.  Since
we'll be making use of Python's standard 'random' module, you'll need to add
the following line to the list of imports::

  import random

Now, the plugin class itself. What you're given is a skeleton: a simple
subclass of :class:`callbacks.Plugin` for you to start with. The only real content it
has is the boilerplate docstring, which you should modify to reflect what the
boilerplate text says - it should be useful so that when someone uses the
plugin help command to determine how to use this plugin, they'll know what they
need to do. Ours will read something like::

    """This plugin provides a few random number commands and some
    commands for getting random samples.  Use the "seed" command to seed
    the plugin's random number generator if you like, though it is
    unnecessary as it gets seeded upon loading of the plugin.  The
    "random" command is most likely what you're looking for, though
    there are a number of other useful commands in this plugin.  Use
    'list random' to check them out.  """

It's basically a "guide to getting started" for the plugin. Now, to make the
plugin do something. First of all, to get any random numbers we're going to
need a random number generator (RNG). Pretty much everything in our plugin is
going to use it, so we'll define it in the constructor of our plugin, __init__.
Here we'll also seed it with the current time (standard practice for RNGs).
Here's what our __init__ looks like::

    def __init__(self, irc):
        # Make sure to call the superclass' constructor when you define a custom one
        super().__init__(irc)
        self.rng = random.Random()   # create our rng
        self.rng.seed()   # automatically seeds with current time

Make sure you add it with one indentation level more than the ``class`` line
(ie. with four spaces before the ``def``).

Now, the first two lines may look a little daunting, but it's just
administrative stuff required if you want to use a custom ``__init__``. If we
didn't want to do so, we wouldn't have to, but it's not uncommon so I decided
to use an example plugin that did. For the most part you can just copy/paste
those lines into any plugin you override the ``__init__`` for and just change them
to use the plugin name that you are working on instead.

So, now we have a RNG in our plugin, let's write a command to get a random
number. We'll start with a simple command named random that just returns a
random number from our RNG and takes no arguments. Here's what that looks
like::

    def random(self, irc, msg, args):
        """takes no arguments

        Returns the next random number from the random number generator.
        """
        irc.reply(str(self.rng.random()))
    random = wrap(random)

Same as before, you have to past it with one indentation level.
And that's it. Now here are the important points.

First and foremost, all plugin commands must have all-lowercase function
names. If they aren't all lowercase they won't show up in a plugin's list of
commands (nor will they be useable in general). If you look through a plugin
and see a function that's not in all lowercase, it is not a plugin command.
Chances are it is a helper function of some sort, and in fact using capital
letters is a good way of assuring that you don't accidentally expose helper
functions to users as commands.

You'll note the arguments to this class method are ``(self, irc, msg, args)``. This
is what the argument list for all methods that are to be used as commands must
start with. If you wanted additional arguments, you'd append them onto the end,
but since we take no arguments we just stop there. I'll explain this in more
detail with our next command, but it is very important that all plugin commands
are class methods that start with those four arguments exactly as named.

Next, in the docstring there are two major components. First, the very first
line dictates the argument list to be displayed when someone calls the help
command for this command (i.e., help random). Then you leave a blank line and
start the actual help string for the function. Don't worry about the fact that
it's tabbed in or anything like that, as the help command normalizes it to
make it look nice. This part should be fairly brief but sufficient to explain
the function and what (if any) arguments it requires. Remember that this should
fit in one IRC message which is typically around a 450 character limit.

Then we have the actual code body of the plugin, which consists of a single
line: ``irc.reply(str(self.rng.random()))``.
The :py:meth:`irc.reply <supybot.callbacks.NestedCommandsIrcProxy.reply>`
function issues a reply
to wherever the PRIVMSG it received the command from with whatever text is
provided. If you're not sure what I mean when I say "wherever the PRIVMSG it
received the command from", basically it means: if the command is issued in a
channel the response is sent in the channel, and if the command is issued in a
private dialog the response is sent in a private dialog. The text we want to
display is simply the next number from our RNG (self.rng). We get that number
by calling the random function, and then we str it just to make sure it is a
nice printable string.

Lastly, all plugin commands must be 'wrap'ed. What the wrap function does is
handle argument parsing for plugin commands in a very nice and very powerful
way. With no arguments, we simply need to just wrap it. For more in-depth
information on using wrap check out the wrap tutorial (The astute Python
programmer may note that this is very much like a decorator, and that's
precisely what it is. However, we developed this before decorators existed and
haven't changed the syntax due to our earlier requirement to stay compatible
with Python 2.3.  As we now require Python 2.4 or greater, this may eventually
change to support work via decorators.)

Now let's create a command with some arguments and see how we use those in our
plugin commands. Let's allow the user to seed our RNG with their own seed
value. We'll call the command seed and take just the seed value as the argument
(which we'll require be a floating point value of some sort, though technically
it can be any hashable object). Here's what this command looks like::

    def seed(self, irc, msg, args, seed):
        """<seed>

        Sets the internal RNG's seed value to <seed>.  <seed> must be a
        floating point number.
        """
        self.rng.seed(seed)
        irc.replySuccess()
    seed = wrap(seed, ['float'])

You'll notice first that argument list now includes an extra argument, seed. If
you read the wrap tutorial mentioned above, you should understand how this arg
list gets populated with values. Thanks to wrap we don't have to worry about
type-checking or value-checking or anything like that. We just specify that it
must be a float in the wrap portion and we can use it in the body of the
function.

Of course, we modify the docstring to document this function. Note the syntax
on the first line. Arguments go in <> and optional arguments should be
surrounded by ``[]`` (we'll demonstrate this later as well).

The body of the function should be fairly straightforward to figure out, but it
introduces a new function -
:py:meth:`irc.replySuccess <supybot.callbacks.RichReplyMethods.replySuccess>`.
This is just a generic "I
succeeded" command which responds with whatever the bot owner has configured to
be the success response (configured in supybot.replies.success). Note that we
don't do any error-checking in the plugin, and that's because we simply don't
have to. We are guaranteed that seed will be a float and so the call to our
RNG's seed is guaranteed to work.

Lastly, of course, the wrap call. Again, read the wrap tutorial for fuller
coverage of its use, but the basic premise is that the second argument to wrap
is a list of converters that handles argument validation and conversion and it
then assigns values to each argument in the arg list after the first four
(required) arguments. So, our seed argument gets a float, guaranteed.

With this alone you'd be able to make some pretty usable plugin commands, but
we'll go through two more commands to introduce a few more useful ideas. The
next command we'll make is a sample command which gets a random sample of items
from a list provided by the user::

    def sample(self, irc, msg, args, n, items):
        """<number of items> <item1> [<item2> ...]

        Returns a sample of the <number of items> taken from the remaining
        arguments.  Obviously <number of items> must be less than the number
        of arguments given.
        """
        if n > len(items):
            irc.error('<number of items> must be less than the number '
                      'of arguments.')
            return
        sample = self.rng.sample(items, n)
        sample.sort()
        irc.reply(utils.str.commaAndify(sample))
    sample = wrap(sample, ['int', many('anything')])

This plugin command introduces a few new things, but the general structure
should look fairly familiar by now. You may wonder why we only have two extra
arguments when obviously this plugin can accept any number of arguments. Well,
using wrap we collect all of the remaining arguments after the first one into
the items argument. If you haven't caught on yet, wrap is really cool and
extremely useful.

Next of course is the updated docstring. Note the use of ``[]`` to denote the
optional items after the first item.

The body of the plugin should be relatively easy to read. First we check and
make sure that n (the number of items the user wants to sample) is not larger
than the actual number of items they gave. If it does, we call irc.error with
the error message you see.
:py:meth:`irc.error <supybot.callbacks.NestedCommandsIrcProxy.error>`
is kind of like irc.replySuccess only it
gives an error message using the configured error format (in
``supybot.replies.error``). Otherwise, we use the sample function from our RNG to
get a sample, then we sort it, and we reply with the 'utils.str.commaAndify'ed
version. The utils.str.commaAndify function basically takes a list of strings
and turns it into "item1, item2, item3, item4, and item5" for an arbitrary
length. More details on using the utils module can be found in the utils
tutorial.

Now for the last command that we will add to our plugin.py. This last command
will allow the bot users to roll an arbitrary n-sided die, with as many sides
as they so choose. Here's the code for this command::

    def diceroll(self, irc, msg, args, n):
        """[<number of sides>]

        Rolls a die with <number of sides> sides.  The default number of sides
        is 6.
        """
        s = 'rolls a %s' % self.rng.randrange(1, n)
        irc.reply(s, action=True)
    diceroll = wrap(diceroll, [additional(('int', 'number of sides'), 6)])

The only new thing learned here really is that the irc.reply method accepts an
optional argument action, which if set to True makes the reply an action
instead. So instead of just crudely responding with the number, instead you
should see something like * supybot rolls a 5. You'll also note that it uses a
more advanced wrap line than we have used to this point, but to learn more
about wrap, you should refer to the wrap tutorial

And now that we're done adding plugin commands you should see the boilerplate
stuff at the bottom, which just consists of::

    Class = Random

And also some vim modeline stuff. Leave these as is, and we're finally done
with plugin.py!

test.py
=======
Now that we've gotten our plugin written, we want to make sure it works. Sure,
an easy way to do a somewhat quick check is to start up a bot, load the plugin,
and run a few commands on it. If all goes well there, everything's probably
okay. But, we can do better than "probably okay". This is where written plugin
tests come in. We can write tests that not only assure that the plugin loads
and runs the commands fine, but also that it produces the expected output for
given inputs. And not only that, we can use the nifty supybot-test script to
test the plugin without even having to have a network connection to connect to
IRC with and most certainly without running a local IRC server.

The boilerplate code for test.py is a good start. It imports everything you
need and sets up RandomTestCase which will contain all of our tests. Now we
just need to write some test methods. I'll be moving fairly quickly here just
going over very basic concepts and glossing over details, but the full plugin
test authoring tutorial has much more detail to it and is recommended reading
after finishing this tutorial.

Since we have four commands we should have at least four test methods in our
test case class. Typically you name the test methods that simply checks that a
given command works by just appending the command name to test. So, we'll have
testRandom, testSeed, testSample, and testDiceRoll. Any other methods you want
to add are more free-form and should describe what you're testing (don't be
afraid to use long names).

First we'll write the testRandom method::

    def testRandom(self):
        # difficult to test, let's just make sure it works
        self.assertNotError('random')

Since we can't predict what the output of our random number generator is going
to be, it's hard to specify a response we want. So instead, we just make sure
we don't get an error by calling the random command, and that's about all we
can do.

Next, testSeed. In this method we're just going to check that the command
itself functions. In another test method later on we will check and make sure
that the seed produces reproducible random numbers like we would hope it would,
but for now we just test it like we did random in 'testRandom'::

    def testSeed(self):
        # just make sure it works
        self.assertNotError('seed 20')

Now for testSample. Since this one takes more arguments it makes sense that we
test more scenarios in this one. Also this time we have to make sure that we
hit the error that we coded in there given the right conditions::

    def testSample(self):
        self.assertError('sample 20 foo')
        self.assertResponse('sample 1 foo', 'foo')
        self.assertRegexp('sample 2 foo bar', '... and ...')
        self.assertRegexp('sample 3 foo bar baz', '..., ..., and ...')

So first we check and make sure trying to take a 20-element sample of a
1-element list gives us an error. Next we just check and make sure we get the
right number of elements and that they are formatted correctly when we give 1,
2, or 3 element lists.

And for the last of our basic "check to see that it works" functions,
testDiceRoll::

    def testDiceRoll(self):
        self.assertActionRegexp('diceroll', 'rolls a \d')

We know that diceroll should return an action, and that with no arguments it
should roll a single-digit number. And that's about all we can test reliably
here, so that's all we do.

Lastly, we wanted to check and make sure that seeding the RNG with seed
actually took effect like it's supposed to. So, we write another test method::

    def testSeedActuallySeeds(self):
        # now to make sure things work repeatably
        self.assertNotError('seed 20')
        m1 = self.getMsg('random')
        self.assertNotError('seed 20')
        m2 = self.getMsg('random')
        self.failUnlessEqual(m1, m2)
        m3 = self.getMsg('random')
        self.failIfEqual(m2, m3)

So we seed the RNG with 20, store the message, and then seed it at 20 again. We
grab that message, and unless they are the same number when we compare the two,
we fail. And then just to make sure our RNG is producing random numbers, we get
another random number and make sure it is distinct from the prior one.

Conclusion
==========
You are now very well-prepared to write Limnoria plugins. Now for a few words of
wisdom with regards to Limnoria plugin-writing.

* Read other people's plugins, especially the included plugins and ones by
  the core developers. We (the Limnoria dev team) can't possibly document
  all the awesome things that Limnoria plugins can do, but we try.
  Nevertheless there are some really cool things that can be done that
  aren't very well-documented.

* Hack new functionality into existing plugins first if writing a new
  plugin is too daunting.

* Come ask us questions in #limnoria on Libera. Going back to the
  first point above, the developers themselves can help you even more than
  the docs can (though we prefer you read the docs first).

* :ref:`Share your plugins with the world <distributing-plugins>`
  and make Limnoria all that more attractive for other users so they will want
  to write their plugins for Limnoria as well.

* Read, read, read all the documentation.

* And of course, have fun writing your plugins.