Metadata-Version: 2.4
Name: powerrules
Version: 0.3.0b1
Summary: A rule-based computer power state management tool
License-Expression: MIT
License-File: LICENSE
Keywords: cli,hibernate,linux,macos,management,manager,policy,power,reboot,rules,shutdown,sleep,windows
Author: LeoTN
Author-email: LeoTN.GitHub@gmx.net
Requires-Python: >=3.11,<4.0
Classifier: Topic :: Utilities
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Requires-Dist: psutil (>=7.0,<8.0)
Requires-Dist: pydantic (>=2.11,<3.0)
Requires-Dist: pywinctl (>=0.4.1,<0.5.0)
Requires-Dist: pyyaml (>=6.0,<7.0)
Requires-Dist: typer (>=0.27.1,<0.28.0)
Project-URL: Bug Tracker, https://github.com/LeoTN/PowerRules/issues
Project-URL: Homepage, https://github.com/LeoTN/PowerRules#readme
Project-URL: Repository, https://github.com/LeoTN/PowerRules
Description-Content-Type: text/markdown

<div align="center">

[![PowerRules](https://raw.githubusercontent.com/LeoTN/PowerRules/main/assets/logo/readme_logo.svg)](https://github.com/LeoTN/PowerRules)

[![latest-version](https://img.shields.io/github/v/release/LeoTN/PowerRules?&filter=*.*.*&display_name=release&style=for-the-badge&logo=Rocket&logoColor=green&label=LATEST&color=green)](https://github.com/LeoTN/PowerRules/releases/latest)
[![latest-beta-version](https://img.shields.io/github/v/release/LeoTN/PowerRules?&include_prereleases&filter=*.*.*b*&display_name=release&style=for-the-badge&logo=Textpattern&logoColor=orange&label=LATEST%20BETA&color=orange)](https://github.com/LeoTN/PowerRules/releases)
[![license](https://img.shields.io/github/license/LeoTN/PowerRules?&style=for-the-badge&logo=Google%20Docs&logoColor=blue&label=License&color=blue)](https://github.com/LeoTN/PowerRules/blob/main/LICENSE)

<details>
  <summary><b>Table of Contents</b></summary>
  <a href="#about">About</a><br>
  <a href="#getting-started">Getting Started</a><br>
  <a href="#features">Features</a><br>
  <a href="#supported-platforms">Supported Platforms</a><br>
  <a href="#credits--license">Credits & License</a>
</details>

</div>

## 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:**

```bash
pip install powerrules
```

**Create a policy file:**

```yaml
# 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:**

```bash
pwru policy validate
```

**Show configured rules:**

```bash
pwru policy show
```

**Evaluate the policy once:**

```bash
pwru policy run --once
```

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

```bash
pwru policy run --policy my-policy.yaml
```

## Features

### Process & Window Matching

Match rules based on processes and window titles.

```yaml
# 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.

```yaml
# 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 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.

```yaml
# 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`.

```yaml
# 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.

```yaml
# Shutdown on match
- action:
    type: shutdown

# Reboot on match
- action:
    type: reboot
```

### Continuous Evaluation

Evaluate rules at a set interval.

```bash
pwru policy run
```

## Supported Platforms

| Platform | Status |
|----------|:------:|
| Windows 10/11 | ✅ |
| Linux | ✅ |
| macOS* | ✅ |

\* Hibernation is not supported on macOS.

## Credits & License

* [Pydantic](https://github.com/pydantic/pydantic) → configuration validation
* [PyYAML](https://github.com/yaml/pyyaml) → YAML policy parsing
* [Typer](https://github.com/fastapi/typer) → command-line interface
* [psutil](https://github.com/giampaolo/psutil) → process information
* [PyWinCtl](https://github.com/Kalmat/PyWinCtl) → window information
* [Inkscape](https://inkscape.org) → program used to design the logo

*This repository is licensed under the [MIT License](https://github.com/LeoTN/PowerRules/blob/main/LICENSE).*

