Creating modules
================

Creating new modules ("things that display something") to contribute
to i3pystatus is reasonably easy. If the module you want to write
updates it's info periodically, like checking for a network link or
displaying the status of some service, then we have prepared common
tools for this which make this even easier:

- Common base classes: :py:class:`i3pystatus.core.modules.Module` for
  everything and :py:class:`i3pystatus.core.modules.IntervalModule`
  specifically for the aforementioned usecase of updating stuff
  periodically.
- Settings (already built into above classes) allow you to easily
  specify user-modifiable attributes of your class for configuration.

  See :py:class:`i3pystatus.core.settings.SettingsBase` for details.
- For modules that require credentials, it is recommended to add a
  keyring_backend setting to allow users to specify their own backends
  for retrieving sensitive credentials. 

  Required settings and default values are also handled.

Check out i3pystatus' source code for plenty of (`simple
<https://github.com/enkore/i3pystatus/blob/master/i3pystatus/mem.py>`_)
examples on how to build modules.

The settings system is built to ease documentation. If you specify
two-tuples like ``("setting", "description")`` then Sphinx will
automatically generate a nice table listing each option, it's default
value and description.

The docstring of your module class is automatically used as the
reStructuredText description for your module in the README file.

.. seealso::

    :py:class:`i3pystatus.core.settings.SettingsBase` for a detailed description of the settings system

Handling Dependencies
---------------------

To make it as easy as possible to use i3pystatus we explicitly
document all dependencies in the docstring of a module.

The wording usually used goes like this:

.. code:: rst

   Requires the PyPI package `colour`

To allow automatic generation of the docs without having all
requirements of every module installed mocks are used. To make this
work simply add all modules you import to the ``MOCK_MODULES`` list in
``docs/conf.py``. This needs to be the actual name of the imported
module, so for example if you have ``from somepkg.mod import AClass``,
you need to add ``somepkg.mod`` to the list.