93 lines
3.7 KiB
ReStructuredText
93 lines
3.7 KiB
ReStructuredText
|
|
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:`.Module` for everything and
|
|
:py:class:`.IntervalModule` specifically for the aforementioned
|
|
usecase of updating stuff periodically.
|
|
|
|
the :py:class:`.Module` class inherits a `logger` attribute and as such
|
|
all logging should be implemented via `self.logger.<level>` rather then
|
|
initializing a new logger in the module.
|
|
|
|
- Settings (already built into above classes) allow you to easily
|
|
specify user-modifiable attributes of your class for configuration.
|
|
|
|
See :py:class:`.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/current/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:`.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 of dependencies (so no standard library modules
|
|
or modules provided by i3pystatus) 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.
|
|
|
|
Testing changes
|
|
---------------
|
|
|
|
i3pystatus uses continuous integration (CI) techniques, which means in
|
|
our case that every patch and every pull request is tested
|
|
automatically. While Travis is used for automatic building of GitHub
|
|
pull requests, it is not the authoritative CI system (which is `Der Golem
|
|
<http://golem.enkore.de/>`_) for the main repository.
|
|
|
|
The ``ci-build.sh`` script needs to run successfully for a patch to be
|
|
accepted. It can be run on your machine, too, so you don't need to
|
|
wait for the often slow Travis build to complete. It does not require
|
|
any special privileges, except write access to the ``ci-build``
|
|
directory (a different build directory can be specified as the first
|
|
parameter to ``ci-build.sh``).
|
|
|
|
The script tests the following things:
|
|
|
|
1. PEP8 compliance of the entire codebase, *excluding* errors of too
|
|
long lines (error code E501). Line lengths of about 120 characters
|
|
are acceptable.
|
|
2. That ``setup.py`` installs i3pystatus and related binaries (into a
|
|
location below the build directory)
|
|
3. Unit tests pass, they are tested against the installed version from
|
|
2.). A unit test log in JUnit format is generated in the build
|
|
directory (``testlog.xml``).
|
|
4. Sphinx docs build without errors or warnings. The HTML docs are
|
|
generated in the ``docs`` directory in the build directory.
|