pyautoscene 0.1.0__py3-none-any.whl

pyautoscene/__init__.py

@@ -0,0 +1,5 @@
+from .references import ReferenceImage, ReferenceText
+from .scene import Scene
+from .session import Session
+
+__all__ = ["Scene", "Session", "ReferenceImage", "ReferenceText"]

pyautoscene/references.py

@@ -0,0 +1,38 @@
+from abc import ABC, abstractmethod
+
+import pyautogui as gui
+from pyscreeze import Box
+
+
+class ReferenceElement(ABC):
+    """Base class for reference elements used to identify scenes."""
+
+    @abstractmethod
+    def is_visible(self):
+        """Detect the presence of the reference element."""
+        raise NotImplementedError("Subclasses must implement this method")
+
+
+class ReferenceImage(ReferenceElement):
+    """Reference element that identifies a scene by an image."""
+
+    def __init__(self, image_path: str):
+        self.image_path = image_path
+
+    def is_visible(self, region: Box | None = None):
+        """Method to detect the presence of the image in the current screen."""
+        try:
+            return gui.locateOnScreen(self.image_path, region=region)
+        except gui.ImageNotFoundException:
+            return None
+
+
+class ReferenceText(ReferenceElement):
+    """Reference element that identifies a scene by text."""
+
+    def __init__(self, text: str):
+        self.text = text
+
+    def is_visible(self):
+        """Method to detect the presence of the text in the current screen."""
+        raise NotImplementedError("Text recognition is not implemented yet.")

pyautoscene/scene.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import Callable, TypedDict
+
+from pyscreeze import Box
+from statemachine import State
+
+from pyautoscene.utils import is_valid_variable_name
+
+from .references import ReferenceElement, ReferenceImage
+
+
+class ActionInfo(TypedDict):
+    """Type definition for action information in a scene."""
+
+    action: Callable[..., None]
+    transitions_to: Scene | None
+
+
+class Scene(State):
+    """A scene represents a state in the GUI automation state machine."""
+
+    def __init__(
+        self,
+        name: str,
+        elements: list[ReferenceElement] | None = None,
+        initial: bool = False,
+    ):
+        assert is_valid_variable_name(name), (
+            f"Invalid scene name: {name}, must be a valid Python identifier."
+        )
+        super().__init__(name, initial=initial)
+        self.elements = elements or []
+        self.actions: dict[str, ActionInfo] = {}
+
+    def action(self, transitions_to: Scene | None = None):
+        """Decorator to register an action for this scene."""
+
+        def decorator(func: Callable[..., None]) -> Callable[..., None]:
+            if func.__name__ not in self.actions:
+                action_name = func.__name__
+                self.actions[action_name] = {
+                    "action": func,
+                    "transitions_to": transitions_to,
+                }
+            return func
+
+        return decorator
+
+    def get_action(self, action_name: str) -> ActionInfo | None:
+        """Get an action by name."""
+        return self.actions.get(action_name)
+
+    def is_on_screen(self, region: Box | None = None) -> bool:
+        """Check if any reference element is currently on screen."""
+        # TODO: Refactor after text recognition is implemented
+        elements = (elem for elem in self.elements if isinstance(elem, ReferenceImage))
+        return all(elem.is_visible(region) for elem in elements)
+
+    def __repr__(self):
+        return f"Scene({self.name!r}, elements={len(self.elements)})"

pyautoscene/session.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+from typing import Callable
+
+import networkx as nx
+from pyscreeze import Box
+from statemachine import State, StateMachine
+from statemachine.factory import StateMachineMetaclass
+from statemachine.states import States
+from statemachine.transition_list import TransitionList
+
+from .scene import Scene
+
+
+class SceneRecognitionError(Exception):
+    pass
+
+
+def build_dynamic_state_machine(
+    scenes: list[Scene],
+) -> tuple[StateMachine, dict[str, TransitionList], dict[str, Callable]]:
+    """Create a dynamic StateMachine class from scenes using StateMachineMetaclass."""
+
+    states = {scene.name: scene for scene in scenes}
+    transitions = {}
+    leaf_actions = {}
+    for scene in scenes:
+        for action_name, action_info in scene.actions.items():
+            target_scene = action_info["transitions_to"]
+            if target_scene is not None:
+                event_name = f"event_{action_name}"
+                new_transition = scene.to(target_scene, event=event_name)
+                new_transition.on(action_info["action"])
+                transitions[event_name] = new_transition
+            else:
+                leaf_actions[action_name] = action_info["action"]
+
+    SessionSM = StateMachineMetaclass(
+        "SessionSM",
+        (StateMachine,),
+        {"states": States(states), **transitions},  # type: ignore[call-arg]
+    )
+    session_sm: StateMachine = SessionSM()  # type: ignore[no-redef]
+
+    return session_sm, transitions, leaf_actions
+
+
+def get_current_scene(scenes: list[Scene], region: Box | None = None) -> Scene:
+    """Get the current scene from the list of scenes."""
+    current_scenes = [scene for scene in scenes if scene.is_on_screen(region)]
+    if len(current_scenes) == 1:
+        return current_scenes[0]
+    elif len(current_scenes) > 1:
+        raise SceneRecognitionError(
+            f"Multiple scenes are currently on screen.\n{' '.join(str(scene) for scene in current_scenes)}"
+        )
+    else:
+        raise SceneRecognitionError("No scene is currently on screen.")
+
+
+class Session:
+    """A session manages the state machine for GUI automation scenes."""
+
+    def __init__(self, scenes: list[Scene]):
+        self._scenes_list = scenes
+        self._scenes_dict = {scene.name: scene for scene in scenes}
+
+        # Create dynamic StateMachine class and instantiate it
+        self._sm, self.transitions, self.leaf_actions = build_dynamic_state_machine(
+            scenes
+        )
+        self.graph: nx.MultiDiGraph = nx.nx_pydot.from_pydot(self._sm._graph())
+
+    @property
+    def current_scene(self) -> State:
+        """Get the current state."""
+        return self._sm.current_state
+
+    def expect(self, target_scene: Scene, **kwargs):
+        """Navigate to a specific scene."""
+        if target_scene.is_on_screen():
+            return
+
+        present_scene = get_current_scene(self._scenes_list)
+        all_paths = list(
+            nx.all_simple_paths(
+                self.graph,
+                source=present_scene.name,
+                target=target_scene.name,
+            )
+        )
+        if len(all_paths) == 0:
+            raise SceneRecognitionError(
+                f"No path found from {present_scene.name} to {target_scene.name}"
+            )
+        elif len(all_paths) > 1:
+            raise SceneRecognitionError(
+                f"Multiple paths found from {present_scene.name} to {target_scene.name}"
+            )
+
+        path = all_paths[0]
+        events: list[str] = [
+            self.graph.get_edge_data(path[i], path[i + 1])[0]["label"]  # type: ignore
+            for i in range(len(path) - 1)
+        ]
+
+        for event in events:
+            self._sm.send(event, **kwargs)
+
+    def invoke(self, action_name: str, **kwargs):
+        """Invoke an action in the current scene."""
+        event_name = f"event_{action_name}"
+        transition = next(
+            (tr for tr_name, tr in self.transitions.items() if tr_name == event_name),
+            None,
+        )
+        if transition:
+            return self._sm.send(event_name, **kwargs)
+
+        leaf_action = next(
+            (
+                action
+                for name, action in self.leaf_actions.items()
+                if name == action_name
+            ),
+            None,
+        )
+        if leaf_action:
+            return leaf_action(**kwargs)
+
+        raise ValueError(
+            f"Action '{action_name}' not found in current scene '{self.current_scene.name}'"
+        )
+
+    def __repr__(self):
+        current = self.current_scene
+        current_name = current.name if current else "None"
+        return (
+            f"Session(scenes={list(self._scenes_dict.keys())}, current={current_name})"
+        )

pyautoscene/utils.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import time
+from keyword import iskeyword
+from typing import Literal
+
+import pyautogui as gui
+
+LOCATE_AND_CLICK_DELAY = 0.2
+
+
+def locate_and_click(
+    filename: str, clicks: int = 1, button: Literal["left", "right"] = "left"
+):
+    time.sleep(LOCATE_AND_CLICK_DELAY)
+    locate = gui.locateOnScreen(filename, grayscale=True)
+    assert locate is not None, f"Could not locate {filename} on screen."
+    locate_center = (locate.left + locate.width // 2), (locate.top + locate.height // 2)
+    gui.moveTo(*locate_center, 0.6, gui.easeInOutQuad)  # type: ignore
+    gui.click(clicks=clicks, button=button)
+    time.sleep(LOCATE_AND_CLICK_DELAY)
+
+
+def is_valid_variable_name(name):
+    return name.isidentifier() and not iskeyword(name)

pyautoscene-0.1.0.dist-info/METADATA

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: pyautoscene
+Version: 0.1.0
+Summary: Advance GUI automation
+Author-email: pritam-dey3 <pritam.pritamdey.984@gmail.com>
+Requires-Python: >=3.13
+Requires-Dist: networkx>=3.5
+Requires-Dist: onnxruntime>=1.22.0
+Requires-Dist: pillow>=11.3.0
+Requires-Dist: pyautogui>=0.9.54
+Requires-Dist: python-statemachine[diagrams]
+Requires-Dist: rapidocr>=3.2.0
+Description-Content-Type: text/markdown
+
+# PyAutoScene
+
+**Advanced GUI Automation with Scene-Based State Management**
+
+PyAutoScene is a Python library that provides a declarative approach to GUI automation by modeling application interfaces as scenes and transitions. It combines element detection with state machine patterns to create robust, maintainable automation scripts.
+
+## 🌟 Features
+
+- **Scene-Based Architecture**: Model your application as a collection of scenes with defined elements and transitions
+- **Visual Element Detection**: Supports both image-based element recognition. (Text recognition support coming soon!)
+- **Automatic Navigation**: Intelligent pathfinding between scenes using graph algorithms
+- **Action Decorators**: Clean, declarative syntax for defining scene actions and transitions
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+pip install pyautoscene
+```
+
+### Basic Example
+
+Here's how to automate a simple login flow:
+
+```python
+import pyautogui as gui
+from pyautoscene import ReferenceImage, ReferenceText, Scene, Session
+from pyautoscene.utils import locate_and_click
+
+# Define scenes
+login = Scene(
+    "Login",
+    elements=[
+        ReferenceText("Welcome to Login"),
+        ReferenceImage("references/login_button.png"),
+    ],
+    initial=True,
+)
+
+dashboard = Scene(
+    "Dashboard",
+    elements=[
+        ReferenceText("Dashboard"),
+        ReferenceImage("references/user_menu.png"),
+    ],
+)
+
+# Define actions with transitions
+@login.action(transitions_to=dashboard)
+def perform_login(username: str, password: str):
+    """Performs login and transitions to dashboard."""
+    locate_and_click("references/username_field.png")
+    gui.write(username, interval=0.1)
+    gui.press("tab")
+    gui.write(password, interval=0.1)
+    gui.press("enter")
+
+# Create session and navigate
+session = Session(scenes=[login, dashboard])
+session.expect(dashboard, username="user", password="pass")
+```
+
+## 📖 Core Concepts
+
+### Scenes
+
+A **Scene** represents a distinct state in your application's UI. Each scene contains:
+
+- **Elements**: Visual markers that identify when the scene is active
+- **Actions**: Functions that can be performed in this scene
+- **Transitions**: Connections to other scenes
+
+```python
+scene = Scene(
+    "SceneName",
+    elements=[
+        ReferenceImage("path/to/image.png"),
+        ReferenceText("Expected Text"),
+    ],
+    initial=False  # Set to True for starting scene
+)
+```
+
+### Reference Elements
+
+PyAutoScene supports two types of reference elements:
+
+#### ReferenceImage
+
+Detects scenes using image matching:
+
+```python
+ReferenceImage("path/to/reference/image.png")
+```
+
+#### ReferenceText
+(Coming soon)
+Detects scenes using text recognition:
+
+```python
+ReferenceText("Expected text on screen")
+```
+
+### Actions and Transitions
+
+Actions are decorated functions that define what can be done in a scene:
+
+```python
+@scene.action(transitions_to=target_scene)  # Action that changes scenes
+def action_with_transition():
+    # Perform GUI operations
+    pass
+
+@scene.action()  # Action that stays in current scene
+def action_without_transition():
+    # Perform GUI operations
+    pass
+```
+
+### Session Management
+
+The **Session** class manages the state machine and provides navigation:
+
+```python
+session = Session(scenes=[scene1, scene2, scene3])
+
+# Navigate to a specific scene (finds optimal path)
+session.expect(target_scene, **action_params)
+
+# Invoke an action in the current scene
+session.invoke("action_name", **action_params)
+
+# Get current scene
+current = session.current_scene
+```
+
+### Automatic Scene Detection
+
+PyAutoScene automatically detects which scene is currently active:
+
+```python
+from pyautoscene.session import get_current_scene
+
+current_scene = get_current_scene(scenes)
+print(f"Currently on: {current_scene.name}")
+```
+
+### Path Finding
+
+The library uses NetworkX to find optimal paths between scenes:
+
+```python
+# This will automatically navigate: Login → Dashboard → Cart
+session.expect(cart_scene, username="user", password="pass")
+```
+
+### Error Handling
+
+```python
+from pyautoscene.session import SceneRecognitionError
+
+try:
+    session.expect(target_scene)
+except SceneRecognitionError as e:
+    print(f"Navigation failed: {e}")
+```
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature-name`
+3. Make your changes and add tests
+4. Run pre-commit hooks: `pre-commit run --all-files`
+5. Submit a pull request
+
+## 📝 License
+
+This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
+
+## 🔮 Roadmap
+
+- [ ] Text recognition implementation
+- [ ] Enhanced image matching algorithms
+- [ ] Multiple session support
+

pyautoscene-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pyautoscene/__init__.py,sha256=4ppGaF-TV-r874c4Q679n6gkSflveKTFu_u-eCpG5yU,175
+pyautoscene/references.py,sha256=wAKZIIrZX2gXnuHsXb-eliF6xk-taVG_ZOvWUj8QLV0,1224
+pyautoscene/scene.py,sha256=Koc2hTQQvNOVRfoYvPwtEYNosb1aRuhpo-3KKOuoWfw,2063
+pyautoscene/session.py,sha256=D-YKH8HJNjpqxqV9HdxZA-cbsbYf8_iMR59Tl3IRph4,4862
+pyautoscene/utils.py,sha256=yc6jkaz-X_sUaOpRS9UG42UnFumhMN7648BunRp2PXM,794
+pyautoscene-0.1.0.dist-info/METADATA,sha256=gHbgYywzt8pw1_uSU5YFiKK9EhRL6b73k7bH4uZnCnk,5080
+pyautoscene-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pyautoscene-0.1.0.dist-info/entry_points.txt,sha256=6aKjylfDivCRMrJasIIi7ICU4fZR-8HjcOHhRmHpYpQ,49
+pyautoscene-0.1.0.dist-info/RECORD,,

pyautoscene-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pyautoscene-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyautoscene = pyautoscene:main