powerrules 0.1.0__py3-none-any.whl

powerrules/__main__.py

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

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/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/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/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)

powerrules/cli/errors.py

@@ -0,0 +1,113 @@
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, NoReturn, TypeVar
+
+import typer
+import yaml
+from pydantic import ValidationError
+
+from powerrules.engine.exceptions import (
+    ActionExecutionError,
+    ConditionEvaluationError,
+)
+
+EXIT_RUNTIME_ERROR = 1
+EXIT_POLICY_ERROR = 2
+
+ReturnType = TypeVar("ReturnType")
+
+
+def handle_cli_error(error: Exception) -> NoReturn:
+    """Handle a command execution error.
+
+    Args:
+        error: Exception raised during command execution.
+
+    Raises:
+        typer.Exit: Always raised after displaying the error.
+    """
+    # The policy file type is currently the only type being used in CLI commands
+    if isinstance(error, FileNotFoundError):
+        typer.echo(
+            f"[ERROR] Policy file not found: {error.filename}",
+            err=True,
+        )
+        raise typer.Exit(code=EXIT_POLICY_ERROR)
+
+    if isinstance(error, yaml.YAMLError):
+        typer.echo(
+            "[ERROR] Failed to parse policy file",
+            err=True,
+        )
+        raise typer.Exit(code=EXIT_POLICY_ERROR)
+
+    if isinstance(error, ValidationError):
+        typer.echo(
+            "[ERROR] Policy validation failed",
+            err=True,
+        )
+
+        # Output the cryptic Pydantic errors anyway. This should be reworked in the future for a nicer output
+        for validation_error in error.errors():
+            location = ".".join(str(item) for item in validation_error["loc"])
+            message = validation_error["msg"]
+
+            typer.echo(
+                f"[ERROR] {location}: {message}",
+                err=True,
+            )
+
+        raise typer.Exit(code=EXIT_POLICY_ERROR)
+
+    # The existing error messages for conditions and actions
+    if isinstance(error, ConditionEvaluationError):
+        typer.echo(
+            f"[ERROR] Failed to evaluate condition: {error}",
+            err=True,
+        )
+        raise typer.Exit(code=EXIT_RUNTIME_ERROR)
+
+    if isinstance(error, ActionExecutionError):
+        typer.echo(
+            f"[ERROR] Failed to execute action: {error}",
+            err=True,
+        )
+        raise typer.Exit(code=EXIT_RUNTIME_ERROR)
+
+    if isinstance(error, ValueError):
+        typer.echo(
+            f"[ERROR] {error}",
+            err=True,
+        )
+        raise typer.Exit(code=EXIT_RUNTIME_ERROR)
+
+    typer.echo(
+        f"[ERROR] Unexpected error: {error}",
+        err=True,
+    )
+    raise typer.Exit(code=EXIT_RUNTIME_ERROR)
+
+
+def cli_command(
+    function: Callable[..., ReturnType],
+) -> Callable[..., ReturnType]:
+    """Wrap a CLI command with centralized error handling.
+
+    Args:
+        function: CLI command function.
+
+    Returns:
+        Wrapped CLI command function.
+    """
+
+    @wraps(function)
+    def wrapper(*args: Any, **kwargs: Any) -> ReturnType:
+        try:
+            return function(*args, **kwargs)
+        except typer.Exit:
+            raise
+        except Exception as e:
+            # Handle errors which result from CLI commands. This avoids tracebacks and instead shows a readable error message
+            handle_cli_error(e)
+
+    return wrapper

powerrules/conditions/base.py

@@ -0,0 +1,14 @@
+from typing import Protocol
+
+
+class Condition(Protocol):
+    def evaluate(self) -> bool:
+        """Evaluate the condition.
+
+        Returns:
+            True if the condition matches, otherwise False.
+
+        Raises:
+            ConditionEvaluationError: If the condition cannot be evaluated.
+        """
+        ...

powerrules/conditions/datetime.py

@@ -0,0 +1,86 @@
+from dataclasses import dataclass
+from datetime import time
+from enum import StrEnum
+
+from powerrules.providers.clock import ClockProvider
+
+
+class Weekday(StrEnum):
+    """Represent all weekdays."""
+
+    MONDAY = "Monday"
+    TUESDAY = "Tuesday"
+    WEDNESDAY = "Wednesday"
+    THURSDAY = "Thursday"
+    FRIDAY = "Friday"
+    SATURDAY = "Saturday"
+    SUNDAY = "Sunday"
+
+
+@dataclass(frozen=True)
+class TimeRange:
+    """Represents a range of time within a day."""
+
+    start: time
+    end: time
+
+    def contains(self, current_time: time) -> bool:
+        """Return whether the given time is within the range.
+
+        The start time is inclusive and the end time is exclusive (6:00 is in the range 23:00-7:00, but 7:00 is not).
+
+        Ranges crossing midnight are supported.
+
+        Args:
+            current_time: Time to check.
+
+        Returns:
+            True if the time is within the range, otherwise False.
+        """
+        # The range does not cross midnight
+        if self.start <= self.end:
+            # Does the current_time fall within the range?
+            return self.start <= current_time < self.end
+
+        # The range crosses midnight (e.g., 23:00-7:00)
+        # Does the current_time fall within the range?
+        return current_time >= self.start or current_time < self.end
+
+
+class DateTimeCondition:
+    def __init__(
+        self,
+        clock_provider: ClockProvider,
+        *,
+        time_range: TimeRange | None = None,
+        weekdays: frozenset[Weekday] | None = None,
+    ):
+        self.clock_provider = clock_provider
+        self.time_range = time_range
+        self.weekdays = weekdays
+
+    def evaluate(self) -> bool:
+        """Evaluate the configured date and time condition.
+
+        Returns:
+            True if the current date and time matches the condition,
+            otherwise False.
+        """
+        current_datetime = self.clock_provider.now()
+
+        if self.time_range is not None:
+            return self.time_range.contains(current_datetime.time())
+
+        if self.weekdays is not None:
+            current_weekday = (
+                Weekday.MONDAY,
+                Weekday.TUESDAY,
+                Weekday.WEDNESDAY,
+                Weekday.THURSDAY,
+                Weekday.FRIDAY,
+                Weekday.SATURDAY,
+                Weekday.SUNDAY,
+            )[current_datetime.weekday()]
+            return current_weekday in self.weekdays
+
+        return False

powerrules/conditions/operators.py

@@ -0,0 +1,51 @@
+from collections.abc import Sequence
+
+from powerrules.conditions.base import Condition
+
+
+class AndCondition:
+    def __init__(self, conditions: Sequence[Condition]):
+        self.conditions = tuple(conditions)
+
+    def evaluate(self) -> bool:
+        """Evaluate all conditions using logical AND.
+
+        Returns:
+            True if all conditions match, otherwise False.
+
+        Raises:
+            ConditionEvaluationError: If a condition cannot be evaluated.
+        """
+        return all(condition.evaluate() for condition in self.conditions)
+
+
+class OrCondition:
+    def __init__(self, conditions: Sequence[Condition]):
+        self.conditions = tuple(conditions)
+
+    def evaluate(self) -> bool:
+        """Evaluate all conditions using logical OR.
+
+        Returns:
+            True if at least one condition matches, otherwise False.
+
+        Raises:
+            ConditionEvaluationError: If a condition cannot be evaluated.
+        """
+        return any(condition.evaluate() for condition in self.conditions)
+
+
+class NotCondition:
+    def __init__(self, condition: Condition):
+        self.condition = condition
+
+    def evaluate(self) -> bool:
+        """Evaluate the condition using logical NOT.
+
+        Returns:
+            True if the condition does not match, otherwise False.
+
+        Raises:
+            ConditionEvaluationError: If the condition cannot be evaluated.
+        """
+        return not self.condition.evaluate()

powerrules/conditions/process.py

@@ -0,0 +1,33 @@
+from powerrules.engine.exceptions import ConditionEvaluationError
+from powerrules.providers.process import ProcessProvider
+
+
+class ProcessCondition:
+    def __init__(
+        self,
+        process_name: str,
+        expected_running: bool,
+        # Basically a wrapper object to interact with the OS to provide information about the running processes
+        process_provider: ProcessProvider,
+    ):
+        self.process_name = process_name
+        self.expected_running = expected_running
+        self.process_provider = process_provider
+
+    def evaluate(self) -> bool:
+        """Evaluate whether the configured process is in the expected state.
+
+        Returns:
+            True if the process state matches the expected state.
+
+        Raises:
+            ConditionEvaluationError: If the process state cannot be determined.
+        """
+        try:
+            is_running = self.process_provider.is_running(self.process_name)
+        except Exception as e:
+            raise ConditionEvaluationError(
+                f"Failed to determine whether process '{self.process_name}' is running."
+            ) from e
+
+        return is_running == self.expected_running