i3pyblocks.core

i3pyblocks core.

This module contains the essence of i3pyblocks. Most of its functionality is implemented in Runner class, a class that manages Blocks and also handles outputing the result, handling i3bar events and handling Unix signals.

Attributes:

logger: Logger instance used by i3pyblocks.

Module Contents

Classes

Runner

Main class of i3pyblocks, managing and running Blocks.

class i3pyblocks.core.Runner

Main class of i3pyblocks, managing and running Blocks.

This is the class in i3pyblocks responsible to managing Blocks and running them, printing its results to stdout and also reading stdin for possible click events comming from i3bar.

register_signal(self, block: i3pyblocks.blocks.Block, signums: Iterable[Union[int, signal.Signals]]) → None

Registers a list of Unix signals for a Block.

This will register a signal_handler() method as a callback for when signums[] is called. Note that since signals are associated with the main thread of i3pyblocks, each signal can only be assigned to a specific Block.

The received signal will be passed to signal_handler() as a parameter, so when receiving multiple signals it is possible to identify each of them separately.

This method capture the errors inside signal_handler(), but it also logs it so you can inspect the issue later on.

Parameters

• block – instance of Block that will receive the signal.

• signmums – Any iterable containing signal numbers. Each signal can be an int or a Signal enum.

register_task(self, awaitable: Awaitable) → None

Register a task that will be run in Runner’s loop.

Parameters

awaitable – Either a coroutine, task or future that will be added to the task list to be schedule inside main loop in i3pyblocks.

async register_block(self, block: i3pyblocks.blocks.Block, signals: Iterable[Union[int, signal.Signals]] = ()) → None

Registers a Block that will be run and managed by Runner.

This will register a new Block in Runner and also make sure that everything is ready to run the Block correctly.

Optionally it will also register any Unix signals that the Block wants to wait for events (see register_signal() method).

Parameters

• block – instance of Block instance that will be registered inside Runner’s main loop.

• signums – Any iterable containing signal numbers, can be either an int or a signal.Signals’ enum. See register_signal() method for more information.

async update_results(self) → None

Get updated results from registed Blocks.

async write_results(self) → None

Writes results to stdout.

This is a endless loop that will wait for an update in any Block, get this update and print all Blocks results using the format described in https://i3wm.org/docs/i3bar-protocol.html#_the_protocol.

async click_event(self, raw: AnyStr) → None

Parses a click event, passing it to a Block’s click_handler().

Receives a click event from stdin in JSON format, parses it, finds the correspondent Block and calls its click_handler() method.

Parameters

raw – A JSON formatted string with the click event, as described in https://i3wm.org/docs/i3bar-protocol.html#_click_events.

async click_events(self) → None

Reads stdin for new click events.

stop(self) → None

Stops the Runner.

async start(self, timeout: Optional[int] = None) → None

Starts the Runner.

This will first print the header as specified in https://i3wm.org/docs/i3bar-protocol.html#_the_protocol, declaring the capabilities of i3pyblocks to i3bar.

Afterwards it will run forever printing to stdout the updates from the registered Blocks in the format expected by i3bar, and will also reads stdin for any click events coming from i3bar.

Parameters

timeout – Time in seconds to stop the Runner. This is mostly used by tests or debug purposes.