powerrules 0.2.0

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

Install with pip:

pip install powerrules

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, a matching backup window is open, and the current time is between 23:00 and 01:30
  - name: "Shutdown after nightly backup"
    conditions:
      and:
        - process:
            name: "backup.exe"
            exists: false
        - window:
            title: "Backup Nr. [0-9]+ Completed"
            exists: true
            match:
              type: regex
        - datetime:
            between:
              start: "23"
              end: "1:30"
    action:
      type: shutdown

Validate the policy:

pwru policy validate

Show configured rules:

pwru policy show

Evaluate the policy once:

pwru policy run --once

Use a different policy file with --policy or -p:

pwru policy run --policy my-policy.yaml

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 ends with "firefox"
- process:
    name: ".*firefox.exe"
    match:
      type: regex
      # This is the default behavior
      case_sensitive: true

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

Time-based Conditions
Match specific time ranges and weekdays.

# Match if the current time is between 23:00 and 1:30
- datetime:
    between:
      start: "23"
      end: "1:30"

# Match on Monday or Friday
- datetime:
    weekdays:
      - "Monday"
      - "Friday"

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 at a set interval.

pwru policy run

Supported Platforms

* Hibernation is not supported on macOS.

Credits & License

• Pydantic → configuration validation
• PyYAML → YAML policy parsing
• Typer → command-line interface
• psutil → process information
• PyWinCtl → window information
• Inkscape → program used to design the logo

This repository is licensed under the MIT License.