powerrules 0.1.0__tar.gz

powerrules-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 LeoTN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

powerrules-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: powerrules
+Version: 0.1.0
+Summary: A rule-based computer power state management tool
+License-Expression: MIT
+License-File: LICENSE
+Keywords: shutdown,reboot,hibernate,sleep,cli,windows,linux,macos,rules,policy,manager,power,management
+Author: LeoTN
+Author-email: LeoTN.GitHub@gmx.net
+Requires-Python: >=3.10,<4.0
+Classifier: Topic :: Utilities
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Dist: psutil (>=7.0,<8.0)
+Requires-Dist: pydantic (>=2.0,<3.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)
+
+</div>
+
+#
+
+* [About](#about)
+* [Getting Started](#getting-started)
+* [Features](#features)
+* [Supported Platforms](#supported-platforms)
+* [Credits & License](#credits--license)
+
+## About
+
+PowerRules allows you to define rules that automatically control the power state of your computer 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:
+  - name: "Shutdown after nightly weekend backup"
+    conditions:
+      and:
+        - process:
+            name: "backup.exe"
+            running: false
+        - datetime:
+            between:
+              start: "23"
+              end: "1:30"
+        - datetime:
+            weekday: ["Saturday", "Sunday"]
+    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
+```
+
+**Run continuously:**
+
+```bash
+pwru policy run
+```
+
+Use a different policy file with `--policy` or `-p`:
+
+```bash
+pwru policy run --policy my-policy.yaml
+```
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Rule-based power management** | Define ordered rules with conditions and power actions |
+| **Process conditions** | Match rules based on whether a process is running |
+| **Time conditions** | Match time ranges and weekdays |
+| **Logical conditions** | Combine conditions using `and`, `or`, and `not` |
+| **Power actions** | Shutdown, sleep, hibernate, and reboot |
+| **Continuous evaluation** | Evaluate policies repeatedly |
+| **First-match execution** | Only the first matching rule executes once per match |
+
+## Supported Platforms
+
+| Platform | Status |
+|----------|:------:|
+| Windows 10/11 | ✅ |
+| Linux | Planned |
+| macOS | Planned |
+
+## 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
+* [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).*
+

powerrules-0.1.0/README.md

@@ -0,0 +1,113 @@
+<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)
+
+</div>
+
+#
+
+* [About](#about)
+* [Getting Started](#getting-started)
+* [Features](#features)
+* [Supported Platforms](#supported-platforms)
+* [Credits & License](#credits--license)
+
+## About
+
+PowerRules allows you to define rules that automatically control the power state of your computer 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:
+  - name: "Shutdown after nightly weekend backup"
+    conditions:
+      and:
+        - process:
+            name: "backup.exe"
+            running: false
+        - datetime:
+            between:
+              start: "23"
+              end: "1:30"
+        - datetime:
+            weekday: ["Saturday", "Sunday"]
+    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
+```
+
+**Run continuously:**
+
+```bash
+pwru policy run
+```
+
+Use a different policy file with `--policy` or `-p`:
+
+```bash
+pwru policy run --policy my-policy.yaml
+```
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Rule-based power management** | Define ordered rules with conditions and power actions |
+| **Process conditions** | Match rules based on whether a process is running |
+| **Time conditions** | Match time ranges and weekdays |
+| **Logical conditions** | Combine conditions using `and`, `or`, and `not` |
+| **Power actions** | Shutdown, sleep, hibernate, and reboot |
+| **Continuous evaluation** | Evaluate policies repeatedly |
+| **First-match execution** | Only the first matching rule executes once per match |
+
+## Supported Platforms
+
+| Platform | Status |
+|----------|:------:|
+| Windows 10/11 | ✅ |
+| Linux | Planned |
+| macOS | Planned |
+
+## 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
+* [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).*

powerrules-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["poetry-core>=2.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[project]
+name = "powerrules"
+version = "0.1.0"
+description = "A rule-based computer power state management tool"
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">=3.10,<4.0"
+authors = [
+    { name = "LeoTN", email = "LeoTN.GitHub@gmx.net" }
+]
+keywords = [
+    "shutdown",
+    "reboot",
+    "hibernate",
+    "sleep",
+    "cli",
+    "windows",
+    "linux",
+    "macos",
+    "rules",
+    "policy",
+    "manager",
+    "power",
+    "management"
+]
+classifiers = [
+    "Topic :: Utilities",
+    "Environment :: Console",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: Microsoft :: Windows"
+]
+dependencies = [
+    "pyyaml>=6.0,<7.0",
+    "pydantic>=2.0,<3.0",
+    "typer>=0.27.1,<0.28.0",
+    "psutil>=7.0,<8.0"
+]
+packages = [
+    { include = "powerrules", from = "src" }
+]
+
+[project.urls]
+homepage = "https://github.com/LeoTN/PowerRules#readme"
+repository = "https://github.com/LeoTN/PowerRules"
+"Bug Tracker" = "https://github.com/LeoTN/PowerRules/issues"
+
+[project.scripts]
+powerrules = "powerrules.cli.app:app"
+pwru = "powerrules.cli.app:app"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0,<9.0"
+]

powerrules-0.1.0/src/powerrules/__main__.py

@@ -0,0 +1,4 @@
+from powerrules.cli.app import app
+
+if __name__ == "__main__":
+    app()

powerrules-0.1.0/src/powerrules/actions/base.py

@@ -0,0 +1,11 @@
+from typing import Protocol
+
+
+class Action(Protocol):
+    def execute(self) -> None:
+        """Execute the action.
+
+        Raises:
+            ActionExecutionError: If the action cannot be executed.
+        """
+        ...

powerrules-0.1.0/src/powerrules/actions/power.py

@@ -0,0 +1,70 @@
+from powerrules.engine.exceptions import ActionExecutionError
+from powerrules.providers.power import PowerProvider
+
+
+class ShutdownAction:
+    def __init__(self, power_provider: PowerProvider):
+        self.power_provider = power_provider
+
+    def execute(self) -> None:
+        """Shut down the computer.
+
+        Raises:
+            ActionExecutionError: If the computer cannot be shut down.
+        """
+        try:
+            self.power_provider.shutdown()
+        except Exception as e:
+            raise ActionExecutionError("Failed to shut down the computer") from e
+
+
+class SleepAction:
+    def __init__(self, power_provider: PowerProvider):
+        self.power_provider = power_provider
+
+    def execute(self) -> None:
+        """Put the computer into sleep mode.
+
+        Raises:
+            ActionExecutionError: If the computer cannot be put into sleep mode.
+        """
+        try:
+            self.power_provider.sleep()
+        except Exception as e:
+            raise ActionExecutionError(
+                "Failed to put the computer into sleep mode"
+            ) from e
+
+
+class HibernateAction:
+    def __init__(self, power_provider: PowerProvider):
+        self.power_provider = power_provider
+
+    def execute(self) -> None:
+        """Put the computer into hibernation.
+
+        Raises:
+            ActionExecutionError: If the computer cannot be put into hibernation.
+        """
+        try:
+            self.power_provider.hibernate()
+        except Exception as e:
+            raise ActionExecutionError(
+                "Failed to put the computer into hibernation"
+            ) from e
+
+
+class RebootAction:
+    def __init__(self, power_provider: PowerProvider):
+        self.power_provider = power_provider
+
+    def execute(self) -> None:
+        """Reboot the computer.
+
+        Raises:
+            ActionExecutionError: If the computer cannot be rebooted.
+        """
+        try:
+            self.power_provider.reboot()
+        except Exception as e:
+            raise ActionExecutionError("Failed to reboot the computer") from e

powerrules-0.1.0/src/powerrules/application/runtime.py

@@ -0,0 +1,100 @@
+import time
+from pathlib import Path
+
+from powerrules.config.builder import ConfigurationBuilder
+from powerrules.config.loader import ConfigurationLoader
+from powerrules.engine.models import Rule, RuleEvaluationResult
+from powerrules.engine.rule_engine import RuleEngine
+from powerrules.platform.windows.power import WindowsPowerProvider
+from powerrules.platform.windows.process import WindowsProcessProvider
+from powerrules.providers.clock import SystemClockProvider
+
+
+class PowerRulesRuntime:
+    """Coordinate PowerRules configuration loading and rule evaluation and action execution."""
+
+    def run_once(self, configuration_path: Path) -> RuleEvaluationResult:
+        """Load and evaluate the configured policy once.
+
+        The policy is loaded only for this evaluation.
+
+        Args:
+            configuration_path: Path to the PowerRules policy file.
+
+        Returns:
+            The result of the rule evaluation.
+        """
+        rule_engine = self._build_rule_engine(configuration_path)
+
+        return rule_engine.evaluate()
+
+    def run_continuously(
+        self,
+        configuration_path: Path,
+        evaluation_interval: float = 10.0,
+        stop_on_match: bool = False,
+    ) -> None:
+        """Load a policy once and continuously evaluate it.
+
+        The policy is loaded only once when the method starts.
+        Changes to the policy file are ignored until the process is restarted.
+
+        Args:
+            configuration_path: Path to the PowerRules policy file.
+            evaluation_interval: Delay between evaluations in seconds.
+            stop_on_match: Stop the evaluation when a rule matches.
+
+        Raises:
+            ValueError: If the evaluation interval is less than or equal to zero.
+            ConditionEvaluationError: If a condition cannot be evaluated.
+            ActionExecutionError: If a matching action cannot be executed.
+        """
+        if evaluation_interval <= 0:
+            raise ValueError("Evaluation interval must be greater than zero")
+
+        rule_engine = self._build_rule_engine(configuration_path)
+        last_matched_rule: Rule | None = None
+
+        while True:
+            matched_rule = rule_engine.find_match()
+
+            if matched_rule is None:
+                last_matched_rule = None
+
+            elif matched_rule is not last_matched_rule:
+                matched_rule.action.execute()
+                last_matched_rule = matched_rule
+
+                if stop_on_match:
+                    break
+
+            time.sleep(evaluation_interval)
+
+    @staticmethod
+    def _build_rule_engine(configuration_path: Path) -> RuleEngine:
+        """Build a rule engine from a policy file.
+
+        The policy is loaded and built exactly once per invocation.
+
+        Args:
+            configuration_path: Path to the PowerRules policy file.
+
+        Returns:
+            A configured rule engine.
+        """
+        configuration = ConfigurationLoader().load(configuration_path)
+
+        clock_provider = SystemClockProvider()
+        process_provider = WindowsProcessProvider()
+        power_provider = WindowsPowerProvider()
+
+        rule_set = ConfigurationBuilder(
+            # Information about the current date and time
+            clock_provider=clock_provider,
+            # Information about running processes
+            process_provider=process_provider,
+            # Basically an API to interact with the power state of the OS
+            power_provider=power_provider,
+        ).build(configuration)
+
+        return RuleEngine(rule_set.rules)

powerrules-0.1.0/src/powerrules/cli/app.py

@@ -0,0 +1,114 @@
+from importlib.metadata import version
+from pathlib import Path
+
+import typer
+
+from powerrules.application.runtime import PowerRulesRuntime
+from powerrules.cli.errors import cli_command
+from powerrules.config.loader import ConfigurationLoader
+
+# Main application
+app = typer.Typer(
+    name="pwru",
+    help="A rule-based computer power state management tool.",
+    no_args_is_help=True,
+)
+
+# Policy subcommand
+policy_app = typer.Typer(
+    name="policy",
+    help="Manage PowerRules policies.",
+    no_args_is_help=True,
+)
+
+app.add_typer(policy_app, name="policy")
+
+
+def version_callback(value: bool) -> None:
+    """Display the installed PowerRules version."""
+    if value:
+        typer.echo(f"PowerRules {version('powerrules')}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        help="Display the installed PowerRules version.",
+        callback=version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """A rule-based computer power state management tool."""
+
+
+@policy_app.command("validate")
+@cli_command
+def validate(
+    policy: Path = typer.Option(
+        Path("powerrules.yaml"),
+        "--policy",
+        "-p",
+        help="Path to the PowerRules policy file.",
+    ),
+) -> None:
+    """Validate a PowerRules policy file."""
+    ConfigurationLoader().load(policy)
+
+    typer.echo("[INFO] Policy is valid")
+
+
+@policy_app.command("show")
+@cli_command
+def show(
+    policy: Path = typer.Option(
+        Path("powerrules.yaml"),
+        "--policy",
+        "-p",
+        help="Path to the PowerRules policy file.",
+    ),
+) -> None:
+    """Display the configured rules of a PowerRules policy."""
+    policy_configuration = ConfigurationLoader().load(policy)
+
+    for index, rule in enumerate(policy_configuration.rules, start=1):
+        status = "enabled" if rule.enabled else "disabled"
+        typer.echo(f"{index}. {rule.name} [{status}]")
+
+
+@policy_app.command("run")
+@cli_command
+def run(
+    once: bool = typer.Option(
+        False,
+        "--once",
+        help="Evaluate the policy once and then exit.",
+    ),
+    stop_on_match: bool = typer.Option(
+        False,
+        "--stop-on-match",
+        help="Stop the continuous evaluation after the first rule match.",
+    ),
+    policy: Path = typer.Option(
+        Path("powerrules.yaml"),
+        "--policy",
+        "-p",
+        help="Path to the PowerRules policy file.",
+    ),
+) -> None:
+    """Evaluate a PowerRules policy continuously or once."""
+    runtime = PowerRulesRuntime()
+
+    if once:
+        result = runtime.run_once(configuration_path=policy)
+
+        if result.matched_rule is None:
+            typer.echo("[INFO] No rule matched")
+        else:
+            typer.echo(f"[INFO] Rule '{result.matched_rule.name}' matched")
+
+        return
+
+    runtime.run_continuously(configuration_path=policy, stop_on_match=stop_on_match)