Module

A module receives a module-specific theme_dict (see style for more info on "module-specific") and applies the theme through:

It is configured using a module.yaml file located in PIMP_CONFIG_DIR/modules/MODULE_NAME/.

Here's an example:

../MODULE_NAME/module.yaml

# yaml-language-server: $schema=../../.json_schemas/module.json
 
os:
  - linux
 
run:
  - action: if_running
    program_name: i3
 
  - action: file
    target: "{{config_dir}}/i3/pimp.conf"
 
  - action: shell
    command: i3-msg reload

Every action in run will be executed sequentially, stopping on error.

`run`

`file`

Use file to generate a file from a Jinja template located in ../MODULE_NAME/templates/example.j2 using the theme_dict.
You can also use values from the theme_dict in the file path.

../MODULE_NAME/module.yaml

run:
  - action: file
    target: "{{config_dir}}/waybar/style.css"
    template: "style.css.j2" # optional, will default to TARGET_FILENAME.j2

This example will generate a file from the template ../MODULE_NAME/templates/style.css.j2 and save it to ~/.config/waybar/style.css (on Linux), overwriting the existing file.

You can also:

../MODULE_NAME/module.yaml

run:
  - action: file
    target: "{{config_dir}}/waybar/style.css"
    template: '{{variant | default("solid")}}.css.j2'
    # select the template file using the theme_dict
 
  - action: file
    target: "{{config_dir}}/waybar/style.css"
    template: 'subdir/style.css.j2' # specify a subdirectory

Here's an example template:

../MODULE_NAME/templates/alacritty.toml.j2

[colors.normal]
black = '{{term.color0}}'
red = '{{term.color1}}'
green = '{{term.color2}}'
yellow = '{{term.color3}}'
blue = '{{term.color4}}'
magenta = '{{term.color5}}'
cyan = '{{term.color6}}'
white = '{{term.color7}}'
 
 
[colors.bright]
black    = '{{term.color8}}'
red      = '{{term.color9}}'
green    = '{{term.color10}}'
yellow   = '{{term.color11}}'
blue     = '{{term.color12}}'
magenta  = '{{term.color13}}'
cyan     = '{{term.color14}}'
white    = '{{term.color15}}'
 
[colors.primary]
background = '{{term.color0}}'
foreground = '{{term.color15}}'
 
[font]
size = {{font.size}}
 
[font.normal]
family = "{{font.mono}}"
 
[[keyboard.bindings]]
action = "SpawnNewInstance"
key = "Return"
mods = "Control|Shift"
 
[window]
opacity = {{opacity.terminal}}
 
[window.padding]
x = {{padding.x}}
y = {{padding.y}}

For advanced usage see the Jinja docs or the starter modules for some examples.

`shell`

Use shell to run shell commands.

../MODULE_NAME/module.yaml

run:
  - action: shell
    command: makoctl reload

You can also:

../MODULE_NAME/module.yaml

run:
  - action: shell
    command: waybar
    detached: true # run in detached, for long running processes
 
  - action: shell
    command: razer-cli -c {{accent.bg.maxsat.nohash}}
    # use values from the theme_dict

`python`

Use python to execute a python function.

../MODULE_NAME/module.yaml

run:
  - action: python
    py_file_path: myfile.py
    function_name: main

../MODULE_NAME/myfile.py

async def main(theme_dict):
    print(theme_dict.wallpaper.path)
    print(theme_dict["wallpaper"].path)
    print(theme_dict)

The function will receive the theme_dict as an argument and must be async.

`enabled`

Use enabled activate or deactivate the module.

../MODULE_NAME/module.yaml

enabled: true

`os`

Defines the operating systems where this module should be executed. If the current OS is not listed, the module is ignored.

../MODULE_NAME/module.yaml

os:
  - linux
  - windows
  - mac

`init`

A list of actions that are executed when the module is installed or reinitialized.

`link`

Use this to link files or directories. The source should be located under ../MODULE_NAME/files/ (eg: ../MODULE_NAME/files/FlatColor)

../MODULE_NAME/module.yaml

init:
  - action: link
    destination: ~/.themes/FlatColor
    origin: FlatColor

`pre_run`

This actions run before run.

`python`

It's specifically designed for modifying the theme_dict before any run actions are executed. This allows you to dynamically adjust theme values based on conditions or computations.

../MODULE_NAME/module.yaml

pre_run:
  - action: python
    function_name: upscale
    py_file_path: upscaler.py

../MODULE_NAME/upscaler.py

async def upscale(theme_dict):
    upscaled = ...
    theme_dict.wallpaper.path = Path(upscaled)
 
    return theme_dict

The Python function must be async, will receive the theme_dict as an argument and must return it.

`commands`

Define custom commands that can be invoked independently via the CLI. Useful for utility commands, debugging, or providing module-specific tools.

`python`

../MODULE_NAME/module.yaml

commands: 
  start:  # will be the name of the command to run from the CLI
    action: python
    py_file_path: slideshow.py
    function_name: start

../MODULE_NAME/slideshow.py

import asyncio
import random
import logging
from pimpmyrice.theme import ThemeManager
 
log = logging.getLogger(__name__)
 
 
async def start(tm: ThemeManager, *args, **kwargs):
    themes = list(tm.themes)[:3]
    random.shuffle(themes)
 
    for theme_name in themes:
        await tm.apply_theme(theme_name)
        if theme_name != themes[-1]:
            await asyncio.sleep(3)
        print()
    log.info(f"{len(themes)} themes showed")

The function receives an instance of ThemeManager and must be async.

You will then be able to run it with:

pimp run module slideshow start

On this page