PimpMyRice
Configuration

Module

A module lets you apply your theme to a specific program or part of your system (like a bar, terminal, browser...). Modules use the theme_dict to generate config files, run shell commands, or execute Python hooks. You can create your own modules or use starter modules from the community.

On this page:

What is a module?

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

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

Module YAML structure

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 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 will generate a file from the template and save it to the target path, 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

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

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

These actions run before run.

python

Use this to modify 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 module run slideshow start

Previous

theme_dict

Next

CLI Commands

On this page

What is a module?Module YAML structurerunfileshellpythonenabledosinitlinkpre_runpythoncommandspythonRelated