Cell plugins

The content of cells is rendered by plugins. A predefined list is detailed below, but you can also Write your own.

List of plugins

Base plugins

color

Produce a square of the same color of the corresponding download chart line. Takes no arguments.

empty

Produce an empty cell. Takes no arguments.

error

Produce a text corresponding to an error (this is used internally). Takes no arguments.

html

Copy raw html code.

  • html (required) The raw html code to render.

Gitlab

gitlabci

Produce a badge for latest gitlabCI build.

  • server (default http://gitlab.com) URL of the gitlab server.

  • user (required) Name of the user owning the package.

  • slug Repository name, if different from the pypi package name.

Those options, combined, should produce the package URL: {server}/{user}/{slug}.

gitlabcicoverage

Produce a test coverage badge for latest gitlabCI build.

  • server (default http://gitlab.com) URL of the gitlab server.

  • user (required) Name of the user owning the package.

  • slug Repository name, if different from the pypi package name.

Those options, combined, should produce the package URL: {server}/{user}/{slug}.

PyPI

homepage

Package home page, retrieved from Pypi metadata.

  • homepage (default to pypi home page value) Project home page, if different from the value retrieved from pypi.

Readthedocs

readthedocs

Readthedocs build badge.

  • slug Repository name, if different from the pypi package name.

  • branch Branch name, if the default branch should not be used.

  • lang Documentation language, if the default lang should not be used.

Shields

pypiddownloads

Badge displaying Pypi daily download statistics.

pypiwdownloads

Badge displaying Pypi weekly download statistics.

pypimdownloads

Badge displaying Pypi monthly download statistics.

pypiversion

Badge displaying Pypi version.

pythonversions

Badge displaying supported Python versions.

Travis

travisci

Travis badge.

  • user (required) Travis username.

  • slug Repository name, if different from the pypi package name.

Write your own

The HTML page is generated using the Jinja2 template system, but you don’t have to use it for your plugins.

A plugin is an object, subclass of Cell. The Cell.render() method must be implemented: it is the method that is called to fill a cell. Since for many usage, your plugin will simply be a template, you can use the Jinja2 class, which makes this a lot easier. Both classes makes it easy to define default and required arguments, and to log errors.

Raw

class pypimonitor.cell.Cell(renderer)[source]

Render some piece of information about a package as HTML code.

keyword = None

Keyword referencing the plugin, used in the YAML configuration files file to enable this plugin. If None, the class is an abstract class that cannot be used directly.

title = ''

Title of the column.

default = {}

Default values for package arguments. See Default and Required arguments for more details.

required = []

List of names of required package arguments. See Default and Required arguments for more details.

render(context, package, cell)[source]

Return the HTML code corresponding to this cell.

Parameters:

  • context – Current Jinja2 context.

  • package (str) – Package name.

  • cell (dict) – Package arguments for this cell.

Return type:

str

Returns:

The HTML code to display in the given cell.

static render_error(context, cell, package, message)[source]

Return the HTML code corresponding to an error.

Parameters:

  • context –

    Current Jinja2 context.

  • cell (str) – Cell name (plugin keyword).

  • package (str) – Package name.

  • message (str) – Human readable error message.

Return type:

str

Returns:

The HTML code to display in the given cell.

Jinja2

class pypimonitor.cell.Jinja2(renderer)[source]

Generic class for cells that are barely more than a template.

When this class is used to render a cell, it renders template self.keyword. When doing so, the template has access to the following variables:

property template

Return template path.

By default, this is cells/KEYWORD.html. One can redefine this class to provide alternative template path.

keyword = None

Keyword referencing the plugin, used in the YAML configuration files file to enable this plugin. If None, the class is an abstract class that cannot be used directly.

Default and Required arguments

A built-in feature eases processing default and required arguments, for simple cases. This is automatically done before calling the Cell.render() method.

If your plugin has absolute default values for some arguments, those can be set in the Cell.default dictionary. Keys are arguments, and values are default values for these arguments.

If your plugin has required arguments (plugin cannot work without those arguments), they can be listed in the Cell.required list. Using a cell without setting one of those arguments will display an error.

For more complex cases (either foo or bar should be set; foo default value is bar if baz is not set, None otherwise; foo is required only if bar is not set; etc.), you have to implement it by hand in the Cell.render() method.

Errors

To display an error (both in the generated HTML page, and in the log), the Cell class has a Cell.render_error() method. This is to be used as:

class Foo(Cell):
    keyword = 'foo'

    def render(self, context, package, cell):
        if not 'bar' in cell:
            return self.render_error(context, self.keyword, package, "Error: argument 'bar' missing.")
        return "<p>" + cell['bar'] + "</p>"