i3pyblocks.blocks.inotify

Blocks related to monitoring file changes, based on aionotify.

This module contains FileWatcherBlock, an abstract, highly efficient Block to show the contents of an arbitrary file. It uses aionotify, that itself is implement using Linux’s inotify, so this Block is only updated when the event that we registered in this Block occurs in the target file.

For an example implementation, take BacklightBlock. It watches for changes in /sys/class/backlight/*/brightness file. So only when the brightness is changed, this Block is updated.

Module Contents

Classes

FileWatcherBlock	File watcher Block.
BacklightBlock	Backlight Block.

class i3pyblocks.blocks.inotify.FileWatcherBlock(path: Union[pathlib.Path, str, None], flags: Optional[aionotify.Flags] = None, format_file_not_found: str = 'File not found {path}', **kwargs)

Bases: i3pyblocks.blocks.Block

File watcher Block.

A highly efficient Block to watch for events that happen in a file.

By default, a click or a signal event will refresh the contents of this Block.

You must not instantiate this class directly, instead you should subclass it and implement run() method first.

Parameters

• path – The file path to watch for events.

• flags –

  The modification flags to be watched. A list of flags can be found in aionotify repo. Multiple flags can be passed to, for example:

  from aionotify import Flags
  
  FileWatcherBlock(
      path="/some/path",
      flags=Flags.MODIFY | Flags.CREATE,
  )
  

• format_file_not_found – Format string to shown when the file in passed in path is not found.

• **kwargs – Extra arguments to be passed to Block class.

async click_handler(self, *, x: int, y: int, button: int, relative_x: int, relative_y: int, width: int, height: int, modifiers: List[Optional[str]]) → None

Callback called when a click event happens to this Block.

Each of this method arguments is from click events in i3bar protocol since they’re mapped directly (so a {"x": 1} results in a x=1).

Parameters

• x – X11 root window coordinates where the click occurred.

• y – X11 root window coordinates where the click occurred.

• button – X11 button ID (for example 1 to 3 for left/middle/right mouse button).

• relative_x – Coordinates where the click occurred, with respect to the top left corner of the block.

• relative_y – Coordinates where the click occurred, with respect to the top left corner of the block.

• width – Width (in px) of the block.

• height – Height (in px) of the block.

• modifier – A list of the modifiers active when the click occurred. The order in which modifiers are listed is not guaranteed.

See also

i3pyblocks.types.MouseButton has the mapping of the available mouse button IDs.

i3pyblocks.types.KeyModifier has the mapping of the available modifiers.

async signal_handler(self, *, sig: signal.Signals) → None

Callback called when a signal event happens to this Block.

Parameters

sig – Signal enum with the signal that originated this event. This can be used to differentiate between different signals.

abstract async run(self) → None

async start(self) → None

Starts a Block.

This is an abstract method, so it should be overriden.

This method is where you generally wants to put your main loop to update the state of the Block. This loop can either be triggered by events or can be an infinity loop. It can even be a single call to update(), but in this case your Block will only be updated once.

class i3pyblocks.blocks.inotify.BacklightBlock(format: str = '{percent:.0f}%', format_no_backlight: str = 'No backlight', base_path: Union[pathlib.Path, str] = '/sys/class/backlight/', device_glob: Optional[str] = '*', command_on_click: Mapping[int, Optional[i3pyblocks._internal.models.CommandArgs]] = {types.MouseButton.LEFT_BUTTON: None, types.MouseButton.MIDDLE_BUTTON: None, types.MouseButton.RIGHT_BUTTON: None, types.MouseButton.SCROLL_UP: None, types.MouseButton.SCROLL_DOWN: None}, **kwargs)

Bases: FileWatcherBlock

Backlight Block.

Based on sysfs backlight interface.

Parameters

• format –

  Format string to shown. Supports the following placeholders:

  • {brightness}: Current brightness of display

  • {max_brightness}: Max brightness supported by display

  • {percent}: Percentage between current and max display brightness

• base_path – The path where available backlights will be searched.

• device_glob – File glob that will be used to search the device inside the base_path. By default it tries to find anything, but if for some reason you want a specific device you can just use device_name here instead.

• command_on_click – Mapping with commands to be called when the user interacts with mouse inside this block. Can be useful to adjust the backlight using scroll, for example.

• **kwargs – Extra arguments to be passed to FileWatcherBlock class.

async click_handler(self, button: int, **_kwargs) → None

Callback called when a click event happens to this Block.

Each of this method arguments is from click events in i3bar protocol since they’re mapped directly (so a {"x": 1} results in a x=1).

Parameters

• x – X11 root window coordinates where the click occurred.

• y – X11 root window coordinates where the click occurred.

• button – X11 button ID (for example 1 to 3 for left/middle/right mouse button).

• relative_x – Coordinates where the click occurred, with respect to the top left corner of the block.

• relative_y – Coordinates where the click occurred, with respect to the top left corner of the block.

• width – Width (in px) of the block.

• height – Height (in px) of the block.

• modifier – A list of the modifiers active when the click occurred. The order in which modifiers are listed is not guaranteed.

See also

i3pyblocks.types.MouseButton has the mapping of the available mouse button IDs.

i3pyblocks.types.KeyModifier has the mapping of the available modifiers.

async run(self) → None