py3 module helper

Py3 is a special helper object that gets injected into py3status modules, providing extra functionality. A module can access it via the self.py3 instance attribute of its py3status class.



Special constant that when returned for cache_until will cause the module to not update unless externally triggered.


Show as Error


Show as Informational


Show as Warning


exception Py3Exception

Base Py3 exception class. All custom Py3 exceptions derive from this class.

exception RequestException

A Py3.request() base exception. This will catch any of the more specific exceptions.

exception RequestTimeout

A timeout has occured during a request made via Py3.request().

exception RequestURLError

A URL related error has occured during a request made via Py3.request().


build_composite(format_string, param_dict=None, composites=None, attr_getter=None)


deprecated in 3.3 use safe_format().

Build a composite output using a format string.

Takes a format_string and treats it the same way as safe_format() but also takes a composites dict where each key/value is the name of the placeholder and either an output eg {'full_text': 'something'} or a list of outputs.


Checks to see if commands in list are available using which.

returns the first available command.

If a string is passed then that command will be checked for.

command_output(command, shell=False)

Run a command and return its output as unicode. The command can either be supplied as a sequence or string.

An Exception is raised if an error occurs


Runs a command and returns the exit code. The command can either be supplied as a sequence or string.

An Exception is raised if an error occurs


Create and return a Composite.

The item may be a string, dict, list of dicts or a Composite.

composite_join(separator, items)

Join a list of items with a separator. This is used in joining strings, responses and Composites.

A Composite object will be returned.

composite_update(item, update_dict, soft=False)

Takes a Composite (item) if item is a type that can be converted into a Composite then this is done automatically. Updates all entries it the Composite with values from update_dict. Updates can be soft in which case existing values are not overwritten.

A Composite object will be returned.

error(msg, timeout=None)

Raise an error for the module.

param msg:message to be displayed explaining the error
param timeout:how long before we should retry. For permanent errors py3.CACHE_FOREVER should be returned. If not supplied then the modules cache_timeout will be used.
format_contains(format_string, name)

Determines if format_string contains placeholder name

name is tested against placeholders using fnmatch so the following patterns can be used:

*       matches everything
?       matches any single character
[seq]       matches any character in seq
[!seq]      matches any character not in seq

This is useful because a simple test like '{placeholder}' in format_string will fail if the format string contains placeholder formatting eg '{placeholder:.2f}'

format_units(value, unit='B', optimal=5, auto=True, si=False)

Takes a value and formats it for user output, we can choose the unit to use eg B, MiB, kbits/second. This is mainly for use with bytes/bits it converts the value into a human readable form. It has various additional options but they are really only for special cases.

The function returns a tuple containing the new value (this is a number so that the user can still format it if required) and a unit that is the units that we have been converted to.

By supplying unit to the function we can force those units to be used eg unit=KiB would force the output to be in Kibibytes. By default we use non-si units but if the unit is si eg kB then we will switch to si units. Units can also be things like Mbit/sec.

If the auto parameter is False then we use the unit provided. This only makes sense when the unit is singular eg ‘Bytes’ and we want the result in bytes and not say converted to MBytes.

optimal is used to control the size of the output value. We try to provide an output value of that number of characters (including decimal point), it may also be less due to rounding. If a fixed unit is used the output may be more than this number of characters.


Return the output of the named module. This will be a list.

get_placeholders_list(format_string, match=None)

Returns a list of placeholders in format_string.

If match is provided then it is used to filter the result using fnmatch so the following patterns can be used:

*       matches everything
?       matches any single character
[seq]       matches any character in seq
[!seq]      matches any character not in seq

This is useful because we just get simple placeholder without any formatting that may be applied to them eg '{placeholder:.2f}' will give ['{placeholder}']


returns the i3s_config dict.


Tests to see if a color is defined. Because colors can be set to None in the config and we want this to be respected in an expression like.

color = self.py3.COLOR_MUTED or self.py3.COLOR_BAD

The color is treated as True but sometimes we want to know if the color has a value set in which case the color should count as False. This function is a helper for this second case.


Check if item is a Composite and return True if it is.


Checks if an event triggered belongs to the module recieving it. This is mainly for containers who will also recieve events from any children they have.

Returns True if the event name and instance match that of the module checking.


True if the version of python being used is 2.x Can be helpful for fixing python 2 compatability issues

log(message, level=LOG_INFO)

Log the message. The level must be one of LOG_ERROR, LOG_INFO or LOG_WARNING

notify_user(msg, level=LOG_INFO, rate_limit=5)

Send a notification to the user. level must be ‘info’, ‘error’ or ‘warning’. rate_limit is the time period in seconds during which this message should not be repeated.


Plays sound_file if possible.


Calling this function during the on_click() method of a module will request that the module is not refreshed after the event. By default the module is updated after the on_click event has been processed.

register_function(function_name, function)

Register a function for the module.

The following functions can be registered


Called to discover what modules a container is displaying. This is used to determine when updates need passing on to the container and also when modules can be put to sleep.

the function must return a set of module names that are being displayed.


This function should only be used by containers.


This function will be called when one of the contents of a container has changed from a non-urgent to an urgent state. It is used by the group module to switch to displaying the urgent module.

module_names is a list of modules that have become urgent


This function should only be used by containers.

request(url, params=None, data=None, headers=None, timeout=None, auth=None)

Make a request to a url and retrieve the results.

param url:url to request eg
param params:extra query string parameters as a dict
param data:POST data as a dict. If this is not supplied the GET method will be used
param headers:http headers to be added to the request as a dict
param timeout:timeout for the request in seconds
param auth:authentication info as tuple (username, password)
safe_format(format_string, param_dict=None, force_composite=False, attr_getter=None)

Parser for advanced formatting.

Unknown placeholders will be shown in the output eg {foo}.

Square brackets [] can be used. The content of them will be removed from the output if there is no valid placeholder contained within. They can also be nested.

A pipe (vertical bar) | can be used to divide sections the first valid section only will be shown in the output.

A backslash \ can be used to escape a character eg \[ will show [ in the output.

\? is special and is used to provide extra commands to the format string, example \?color=#FF00FF. Multiple commands can be given using an ampersand & as a separator, example \?color=#FF00FF&show.

{<placeholder>} will be converted, or removed if it is None or empty. Formating can also be applied to the placeholder eg {number:03.2f}.

example format_string:

"[[{artist} - ]{title}]|{file}" This will show artist - title if artist is present, title if title but no artist, and file if file is present but not artist or title.

param_dict is a dictionary of palceholders that will be substituted. If a placeholder is not in the dictionary then if the py3status module has an attribute with the same name then it will be used.


Added in version 3.3

Composites can be included in the param_dict.

The result returned from this function can either be a string in the case of simple parsing or a Composite if more complex.

If force_composite parameter is True a composite will always be returned.

attr_getter is a function that will when called with an attribute name as a parameter will return a value.


Stops any currently playing sounds for this module.

threshold_get_color(value, name=None)

Obtain color for a value using thresholds.

The value will be checked against any defined thresholds. These should have been set in the i3status configuration. If more than one threshold is needed for a module then the name can also be supplied. If the user has not supplied a named threshold but has defined a general one that will be used.

time_in(seconds=None, sync_to=None, offset=0)

Returns the time a given number of seconds into the future. Helpful for creating the cached_until value for the module output.


from version 3.1 modules no longer need to explicitly set a cached_until in their response unless they wish to directly control it.

seconds specifies the number of seconds that should occure before the update is required.

sync_to causes the update to be syncronised to a time period. 1 would cause the update on the second, 60 to the nearest minute. By defalt we syncronise to the nearest second. 0 will disable this feature.

offset is used to alter the base time used. A timer that started at a certain time could set that as the offset and any syncronisation would then be relative to that time.

trigger_event(module_name, event)

Trigger an event on a named module.


Update a module. If module_name is supplied the module of that name is updated. Otherwise the module calling is updated.