powerrules 0.5.0b3

About

Define rules to control your computer's power state based on configurable conditions.

Rules are evaluated from top to bottom. The first matching rule executes its configured action.

Getting Started

1. Install via pip (Python 3.11+) or download a standalone binary:

pip install powerrules

2. Create a policy file:

# yaml-language-server: $schema=https://raw.githubusercontent.com/LeoTN/PowerRules/main/assets/schema/powerrules_policy.schema.json

rules:
  # Shut down when no backup process is running and the current time is between 23:00 and 01:30
  - name: "Shutdown after nightly backup"
    enabled: true
    conditions:
      and:
        - process:
            name: "backup.exe"
            exists: false
        - datetime:
            between:
              start: "23"
              end: "1:30"
    action:
      type: shutdown

3. Validate and evaluate the policy once. Use --dry-run to see what would happen:

pwru policy validate --policy my-policy.yaml
pwru policy run --once --policy my-policy.yaml --dry-run

Features

Process & Window Matching

Match rules based on processes and window titles.

# Match if process "firefox.exe" is running
- process:
    name: "firefox.exe"
    exists: true

# Match if window with exact title "Firefox" exists
- window:
    title: "Firefox"
    exists: true

Regex Matching

Match process names and window titles using regular expressions with full-string matching.

# Match if process name contains "fire"
- process:
    name: '.*fire.*'
    exists: true
    match:
      type: regex
      case_sensitive: true # This is the default behavior

# Match if window title starts with "firefox" (case insensitive)
- window:
    title: "Firefox.*"
    exists: true
    match:
      type: regex
      case_sensitive: false

Time-based Conditions

Match specific dates, time ranges, weekdays and months. If several of between, weekday and month are configured, all of them must match. The end of a range is always exclusive.

# Match every day from 23:00 until 1:30 the next morning
- datetime:
    between:
      start: "23"
      end: "1:30"

# Match on Mondays and Fridays
- datetime:
    weekday:
      - "Monday"
      - "Friday"

# Match in June, July and August
- datetime:
    month:
      - "June"
      - "July"
      - "August"

# Match on the whole days 2026-08-21 and 2026-08-22 (the end date 2026-08-23 is not included)
- datetime:
    between:
      start: "2026-08-21"
      end: "2026-08-23"

# Match from 2026-08-21 18:00 until 2026-08-23 6:00
- datetime:
    between:
      start: "2026-08-21 18:00"
      end: "2026-08-23 6:00"

# Match on Saturdays and Sundays from 2026-08-21 until the end of 2026
- datetime:
    between:
      start: "2026-08-21"
      end: "2027-01-01"
    weekday:
      - "Saturday"
      - "Sunday"

# Match on Saturday and Sunday nights in December from 22:00 until 6:00 the next morning
- datetime:
    between:
      start: "22"
      end: "6"
    weekday:
      - "Saturday"
      - "Sunday"
    month:
      - "December"

start and end must be of the same kind: both times, both dates or both dates with a time. All values use the local time of the computer, timezones are not supported.

If a time range crosses midnight, weekday and month refer to the day on which the range starts. For dates, they refer to the current day.

Logical Conditions

Combine multiple conditions using and, or, and not.

# Match if (condition_1 OR condition_2) AND NOT condition_3
- and:
    - or:
        - condition_1: ...
        - condition_2: ...
    - not:
        condition_3: ...

Power Actions

Shutdown, sleep, hibernate, or reboot your computer.

# Shutdown on match
- action:
    type: shutdown

# Reboot on match
- action:
    type: reboot

Continuous Evaluation

Evaluate rules every 10 seconds. A matching rule is triggered only when it becomes the active match, avoiding repeated execution while the same rule remains matched.

pwru policy run

--stop-on-match can be used to stop the evaluation after the first match. The policy is loaded once at startup, so changes to the file require a restart.

Supported Platforms

Platform independent via pip:

pip install powerrules

Credits & License

• Inkscape → program used to design the logo
• Nuitka → standalone binaries
• psutil → process information
• Pydantic → configuration validation
• PyYAML → YAML policy parsing
• rich → console output formatting
• Typer → command-line interface

This repository is licensed under the MIT License.