pyautoscene 0.1.0__tar.gz

pyautoscene-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+explore/

pyautoscene-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.11.13
+    hooks:
+      - id: ruff-check
+        args: ["--extend-select", "I", "--fix"]
+      - id: ruff-format
+        args: ["--preview"]

pyautoscene-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

pyautoscene-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,186 @@
+# 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/examples/saucedemo/main.py

@@ -0,0 +1,68 @@
+import pyautogui as gui
+
+from pyautoscene import ReferenceImage, ReferenceText, Scene, Session
+from pyautoscene.utils import locate_and_click
+
+login = Scene(
+    "Login",
+    elements=[
+        ReferenceText("Welcome to Login"),
+        ReferenceImage("examples/saucedemo/references/login_button.png"),
+    ],
+    initial=True,
+)
+
+dashboard = Scene(
+    "Dashboard",
+    elements=[
+        ReferenceText("Swag Labs"),
+        ReferenceText("Products"),
+        ReferenceImage("examples/saucedemo/references/cart_icon.png"),
+    ],
+)
+
+cart = Scene(
+    "Cart",
+    elements=[
+        ReferenceText("Your Cart"),
+        ReferenceImage("examples/saucedemo/references/cart_icon.png"),
+    ],
+)
+
+
+@login.action(transitions_to=dashboard)
+def perform_login(username: str, password: str):
+    """Performs the login action to transition from Login to Dashboard."""
+    locate_and_click("examples/saucedemo/references/username.png")
+    gui.write(username, interval=0.1)
+    gui.press("tab")
+    gui.write(password, interval=0.1)
+    gui.press("enter")
+
+
+@dashboard.action()
+def add_products_to_cart(target: str):
+    """Adds products to the cart."""
+    locate_and_click(f"examples/saucedemo/references/{target}.png")
+    locate_and_click("examples/saucedemo/references/add_to_cart_button.png")
+
+
+@dashboard.action(transitions_to=cart)
+def view_cart():
+    """Views the cart."""
+    locate_and_click("examples/saucedemo/references/cart_icon.png")
+
+
+@cart.action()
+def checkout():
+    """Checks out the items in the cart."""
+    locate_and_click("examples/saucedemo/references/checkout_button.png")
+
+
+session = Session(scenes=[login, dashboard, cart])
+
+gui.hotkey("alt", "tab")
+session.expect(dashboard, username="standard_user", password="secret_sauce")
+session.invoke("add_products_to_cart", target="backpack")
+session.invoke("view_cart")
+session.invoke("checkout")

pyautoscene-0.1.0/examples/saucedemo/manual_flow.py

@@ -0,0 +1,72 @@
+import pyautogui as gui
+
+from pyautoscene import ReferenceImage, ReferenceText, Scene, Session
+from pyautoscene.utils import locate_and_click
+
+login = Scene(
+    "Login",
+    elements=[
+        ReferenceText("Welcome to Login"),
+        ReferenceImage("examples/saucedemo/references/login_button.png"),
+    ],
+    initial=True,
+)
+
+dashboard = Scene(
+    "Dashboard",
+    elements=[
+        ReferenceText("Swag Labs"),
+        ReferenceText("Products"),
+        ReferenceImage("examples/saucedemo/references/cart_icon.png"),
+    ],
+)
+
+cart = Scene(
+    "Cart",
+    elements=[
+        ReferenceText("Your Cart"),
+        ReferenceImage("examples/saucedemo/references/cart_icon.png"),
+    ],
+)
+
+
+@login.action(transitions_to=dashboard)
+def perform_login(username: str, password: str):
+    """Performs the login action to transition from Login to Dashboard."""
+    locate_and_click("examples/saucedemo/references/username.png")
+    gui.write(username, interval=0.1)
+    gui.press("tab")
+    gui.write(password, interval=0.1)
+    gui.press("enter")
+
+
+@dashboard.action()
+def add_products_to_cart(target: str):
+    """Adds products to the cart."""
+    locate_and_click(f"examples/saucedemo/references/{target}.png")
+    locate_and_click("examples/saucedemo/references/add_to_cart_button.png")
+
+
+@dashboard.action(transitions_to=cart)
+def view_cart():
+    """Views the cart."""
+    locate_and_click("examples/saucedemo/references/cart_icon.png")
+
+
+@cart.action()
+def checkout():
+    """Checks out the items in the cart."""
+    locate_and_click("examples/saucedemo/references/checkout_button.png")
+
+
+session = Session(scenes=[login, dashboard, cart])
+
+# test internal state machine
+gui.hotkey("alt", "tab")
+print(f"{session.current_scene=}")
+session.invoke("perform_login", username="standard_user", password="secret_sauce")
+print(f"After login: {session._sm.current_state=}")
+session.invoke("add_products_to_cart", target="backpack")
+session.invoke("view_cart")
+print(f"After adding to cart: {session._sm.current_state=}")
+session.invoke("checkout")

pyautoscene-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+authors = [
+  {name = "pritam-dey3", email = "pritam.pritamdey.984@gmail.com"},
+]
+dependencies = [
+  "networkx>=3.5",
+  "onnxruntime>=1.22.0",
+  "pillow>=11.3.0",
+  "pyautogui>=0.9.54",
+  "python-statemachine[diagrams]",
+  "rapidocr>=3.2.0",
+]
+description = "Advance GUI automation"
+name = "pyautoscene"
+readme = "README.md"
+requires-python = ">=3.13"
+version = "0.1.0"
+
+[project.scripts]
+pyautoscene = "pyautoscene:main"
+
+[build-system]
+build-backend = "hatchling.build"
+requires = ["hatchling"]
+
+[tool.uv.sources]
+python-statemachine = {git = "https://github.com/fgmacedo/python-statemachine.git", rev = "9a089edf61b4afd4abc08968b3cfa508fa332f7c"}
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.2.0",
+    "types-networkx>=3.5.0.20250712",
+]
+
+[tool.poe.tasks]
+precmt = "pre-commit run --all-files"

pyautoscene-0.1.0/src/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-0.1.0/src/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.")