Skip to content

The py3 module helper

The Py3 module 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.

Constants

CACHE_FOREVER

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

LOG_ERROR

Show as Error

LOG_INFO

Show as Informational

LOG_WARNING

Show as Warning

Exceptions

CommandError

An error occurred running the given command.

This exception provides some additional attributes

error_code: The error code returned from the call

output: Any output returned by the call

error: Any error output returned by the call

Py3Exception

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

RequestException

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

RequestInvalidJSON

The request has not returned valid JSON

RequestTimeout

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

RequestURLError

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

Methods

check_commands(cmd_list)

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

returns the first available command.

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

command_output(command, shell=False, capture_stderr=False, localized=False)

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

:param command: command to run can be a str or list :param shell: if True then command is run through the shell :param capture_stderr: if True then STDERR is piped to STDOUT :param localized: if False then command is forced to use its default (English) locale

A CommandError is raised if an error occurs

command_run(command)

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

composite_create(item)

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.

flatten_dict(d, delimiter='-', intermediates=False, parent_key=None)

Flatten a dictionary.

Values that are dictionaries are flattened using delimiter in between (eg. parent-child)

Values that are lists are flattened using delimiter followed by the index (eg. parent-0)

example:

{
    'fish_facts': {
        'sharks': 'Most will drown if they stop moving',
        'skates': 'More than 200 species',
    },
    'fruits': ['apple', 'peach', 'watermelon'],
    'number': 52
}

# becomes

{
    'fish_facts-sharks': 'Most will drown if they stop moving',
    'fish_facts-skates': 'More than 200 species',
    'fruits-0': 'apple',
    'fruits-1': 'peach',
    'fruits-2': 'watermelon',
    'number': 52
}

# if intermediates is True then we also get unflattened elements
# as well as the flattened ones.

{
    'fish_facts': {
        'sharks': 'Most will drown if they stop moving',
        'skates': 'More than 200 species',
    },
    'fish_facts-sharks': 'Most will drown if they stop moving',
    'fish_facts-skates': 'More than 200 species',
    'fruits': ['apple', 'peach', 'watermelon'],
    'fruits-0': 'apple',
    'fruits-1': 'peach',
    'fruits-2': 'watermelon',
    'number': 52
}

format_contains(format_string, names)

Determines if format_string contains a placeholder string names or a list of placeholders names.

names 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.

get_color_names_list(format_string, matches=None)

Returns a list of color names in format_string.

  • format_string: Accepts a format string.
  • matches: Filter results with a string or a list of strings.

If matches 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

get_composite_string(format_string)

Return a string from a Composite.

get_output(module_name)

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

get_placeholder_formats_list(format_string)

Parses the format_string and returns a list of tuples [(placeholder, format), ...].

eg '{placeholder:.2f}' will give [('placeholder', ':.2f')]

get_placeholders_list(format_string, matches=None)

Returns a list of placeholders in format_string.

If matches 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}']

get_wm_msg()

Return the control program of the current window manager.

On i3, will return "i3-msg" On sway, will return "swaymsg"

i3s_config()

returns the i3s_config dict.

is_color(color)

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.

is_composite(item)

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

is_my_event(event)

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

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

log(message, level='info')

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

notify_user(msg, level='info', rate_limit=5, title=None, icon=None)

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. icon must be an icon path or icon name.

play_sound(sound_file)

Plays sound_file if possible.

prevent_refresh()

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:

content_function()

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.

Note

This function should only be used by containers.

urgent_function(module_names)

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

Note

This function should only be used by containers.

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

Make a request to a url and retrieve the results.

If the headers parameter does not provide an 'User-Agent' key, one will be added automatically following the convention:

py3status/<version> <per session random uuid>
  • url: url to request eg http://example.com
  • params: extra query string parameters as a dict
  • data: POST data as a dict. If this is not supplied the GET method will be used
  • headers: http headers to be added to the request as a dict
  • timeout: timeout for the request in seconds
  • auth: authentication info as tuple (username, password)
  • cookiejar: an object of a CookieJar subclass
  • retry_times: how many times to retry the request
  • retry_wait: how long to wait between retries in seconds

returns: HttpResponse

safe_format(format_string, param_dict=None, force_composite=False, attr_getter=None, max_width=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.

\?if=<placeholder> can be used to check if a placeholder exists. An exclamation mark ! after the equals sign = can be used to negate the condition.

\?if=<placeholder>=<value> can be used to determine if {} would be replaced with . [] in don't need to be escaped.

{<placeholder>} will be converted, or removed if it is None or empty. Formatting 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 placeholders 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.

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.

max_width lets you to control the total max width of 'full_text' the module is allowed to output on the bar.

stop_sound()

Stops any currently playing sounds for this module.

storage_del(key=None)

Remove the value stored with the key from storage. If key is not supplied then all values for the module are removed.

storage_get(key)

Retrieve a value for the module.

storage_items()

Return key, value pairs of the stored data for the module.

Keys will contain the following metadata entries: - '_ctime': storage creation timestamp - '_mtime': storage last modification timestamp

storage_keys()

Return a list of the keys for values stored for the module.

Keys will contain the following metadata entries: - '_ctime': storage creation timestamp - '_mtime': storage last modification timestamp

storage_set(key, value)

Store a value for the 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.

If the gradients config parameter is True then rather than sharp thresholds we will use a gradient between the color values.

  • value: numerical value to be graded
  • name: accepts a string, otherwise 'threshold' accepts 3-tuples to allow name with different values eg ('name', 'key', 'thresholds')

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.

Note

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 occur before the update is required. Passing a value of CACHE_FOREVER returns CACHE_FOREVER which can be useful for some modules.

  • sync_to: causes the update to be synchronized to a time period. 1 would cause the update on the second, 60 to the nearest minute. By default we synchronize 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 synchronization would then be relative to that time.

trigger_event(module_name, event)

Trigger an event on a named module.

update(module_name=None)

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

update_placeholder_formats(format_string, formats)

Update a format string adding formats if they are not already present. This is useful when for example a placeholder has a floating point value but by default we only want to show it to a certain precision.