xa11y 0.1.0__tar.gz

xa11y-0.1.0/Cargo.toml

@@ -0,0 +1,27 @@
+[workspace]
+members = [
+    "xa11y-core",
+    "xa11y-macos",
+    "xa11y-windows",
+    "xa11y-linux",
+    "xa11y",
+    "xa11y-test-app",
+    "xa11y-fuzz",
+]
+exclude = ["xa11y-python"]
+resolver = "2"
+
+[workspace.package]
+version = "0.1.1"
+edition = "2021"
+license = "MIT"
+repository = "https://github.com/xa11y/xa11y"
+
+[workspace.dependencies]
+xa11y-core = { path = "xa11y-core", version = "0.1.1" }
+xa11y-macos = { path = "xa11y-macos", version = "0.1.1" }
+xa11y-windows = { path = "xa11y-windows", version = "0.1.1" }
+xa11y-linux = { path = "xa11y-linux", version = "0.1.1" }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+thiserror = "2"

xa11y-0.1.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: xa11y
+Version: 0.1.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Testing
+Summary: Cross-platform accessibility client library
+Keywords: accessibility,a11y,automation,screen-reader
+License-Expression: MIT
+Requires-Python: >=3.9
+Project-URL: Homepage, https://github.com/xa11y/xa11y
+Project-URL: Repository, https://github.com/xa11y/xa11y

xa11y-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["maturin>=1.0,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "xa11y"
+requires-python = ">=3.9"
+dynamic = ["version"]
+description = "Cross-platform accessibility client library"
+license = "MIT"
+keywords = ["accessibility", "a11y", "automation", "screen-reader"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Rust",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Testing",
+]
+
+[project.urls]
+Homepage = "https://github.com/xa11y/xa11y"
+Repository = "https://github.com/xa11y/xa11y"
+
+[tool.maturin]
+features = ["pyo3/extension-module", "pyo3/abi3-py39"]
+module-name = "xa11y._native"
+manifest-path = "xa11y-python/Cargo.toml"
+python-source = "python"
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "SIM", # flake8-simplify
+    "RUF", # ruff-specific
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

xa11y-0.1.0/python/xa11y/__init__.py

@@ -0,0 +1,62 @@
+"""xa11y — Cross-Platform Accessibility Client Library for Python.
+
+Quick start:
+    >>> import xa11y
+    >>> tree = xa11y.app("Safari")
+    >>> for button in tree.query("button"):
+    ...     print(button.name)
+    >>> tree.press("button[name='OK']")
+
+With explicit provider:
+    >>> with xa11y.connect() as provider:
+    ...     tree = provider.app("Safari")
+    ...     loc = tree.locator("button[name='Submit']")
+    ...     loc.press()
+"""
+
+from xa11y._native import (
+    ActionNotSupportedError,
+    AppInfo,
+    AppNotFoundError,
+    InvalidSelectorError,
+    Locator,
+    Node,
+    NormalizedRect,
+    PermissionDeniedError,
+    PlatformError,
+    # Classes
+    Provider,
+    Rect,
+    SelectorNotMatchedError,
+    TimeoutError,
+    Tree,
+    # Exceptions
+    XA11yError,
+    app,
+    check_permissions,
+    # Convenience functions
+    connect,
+    list_apps,
+)
+
+__all__ = [
+    "ActionNotSupportedError",
+    "AppInfo",
+    "AppNotFoundError",
+    "InvalidSelectorError",
+    "Locator",
+    "Node",
+    "NormalizedRect",
+    "PermissionDeniedError",
+    "PlatformError",
+    "Provider",
+    "Rect",
+    "SelectorNotMatchedError",
+    "TimeoutError",
+    "Tree",
+    "XA11yError",
+    "app",
+    "check_permissions",
+    "connect",
+    "list_apps",
+]

xa11y-0.1.0/python/xa11y/_native.pyi

@@ -0,0 +1,278 @@
+"""Type stubs for the xa11y native extension module."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from types import TracebackType
+
+# ── Exceptions ───────────────────────────────────────────────────────────────
+
+class XA11yError(Exception): ...
+class PermissionDeniedError(XA11yError): ...
+class AppNotFoundError(XA11yError): ...
+class SelectorNotMatchedError(XA11yError): ...
+class ActionNotSupportedError(XA11yError): ...
+class TimeoutError(XA11yError): ...
+class InvalidSelectorError(XA11yError): ...
+class PlatformError(XA11yError): ...
+
+# ── Data Classes ─────────────────────────────────────────────────────────────
+
+class Rect:
+    @property
+    def x(self) -> int: ...
+    @property
+    def y(self) -> int: ...
+    @property
+    def width(self) -> int: ...
+    @property
+    def height(self) -> int: ...
+    def __repr__(self) -> str: ...
+    def __eq__(self, other: object) -> bool: ...
+
+class NormalizedRect:
+    @property
+    def left(self) -> float: ...
+    @property
+    def top(self) -> float: ...
+    @property
+    def right(self) -> float: ...
+    @property
+    def bottom(self) -> float: ...
+    def __repr__(self) -> str: ...
+
+class AppInfo:
+    @property
+    def name(self) -> str: ...
+    @property
+    def pid(self) -> int: ...
+    @property
+    def bundle_id(self) -> str | None: ...
+    def __repr__(self) -> str: ...
+
+# ── Node ─────────────────────────────────────────────────────────────────────
+
+class Node:
+    @property
+    def role(self) -> str: ...
+    @property
+    def name(self) -> str | None: ...
+    @property
+    def value(self) -> str | None: ...
+    @property
+    def description(self) -> str | None: ...
+    @property
+    def depth(self) -> int: ...
+    @property
+    def numeric_value(self) -> float | None: ...
+    @property
+    def min_value(self) -> float | None: ...
+    @property
+    def max_value(self) -> float | None: ...
+    @property
+    def stable_id(self) -> str | None: ...
+    @property
+    def actions(self) -> list[str]: ...
+    @property
+    def bounds(self) -> Rect | None: ...
+    @property
+    def bounds_normalized(self) -> NormalizedRect | None: ...
+    @property
+    def enabled(self) -> bool: ...
+    @property
+    def visible(self) -> bool: ...
+    @property
+    def focused(self) -> bool: ...
+    @property
+    def checked(self) -> str | None: ...
+    @property
+    def selected(self) -> bool: ...
+    @property
+    def expanded(self) -> bool | None: ...
+    @property
+    def editable(self) -> bool: ...
+    @property
+    def focusable(self) -> bool: ...
+    @property
+    def modal(self) -> bool: ...
+    @property
+    def required(self) -> bool: ...
+    @property
+    def busy(self) -> bool: ...
+    def __repr__(self) -> str: ...
+    def __str__(self) -> str: ...
+    def __len__(self) -> int: ...
+
+# ── Target type for action methods ───────────────────────────────────────────
+
+_Target = Node | str
+
+# ── Tree ─────────────────────────────────────────────────────────────────────
+
+class Tree:
+    @property
+    def app_name(self) -> str: ...
+    @property
+    def pid(self) -> int | None: ...
+    @property
+    def screen_size(self) -> tuple[int, int]: ...
+    @property
+    def root(self) -> Node: ...
+    def children(self, node: Node) -> list[Node]: ...
+    def parent(self, node: Node) -> Node | None: ...
+    def query(self, selector: str) -> list[Node]: ...
+    def find_by_role(self, role: str) -> list[Node]: ...
+    def find_by_name(self, pattern: str) -> list[Node]: ...
+    def perform(
+        self,
+        target: _Target,
+        action: str,
+        *,
+        value: str | None = None,
+        numeric_value: float | None = None,
+        direction: str | None = None,
+        amount: float | None = None,
+        start: int | None = None,
+        end: int | None = None,
+    ) -> None: ...
+    def press(self, target: _Target) -> None: ...
+    def focus(self, target: _Target) -> None: ...
+    def blur(self, target: _Target) -> None: ...
+    def toggle(self, target: _Target) -> None: ...
+    def expand(self, target: _Target) -> None: ...
+    def collapse(self, target: _Target) -> None: ...
+    def select(self, target: _Target) -> None: ...
+    def increment(self, target: _Target) -> None: ...
+    def decrement(self, target: _Target) -> None: ...
+    def show_menu(self, target: _Target) -> None: ...
+    def scroll_into_view(self, target: _Target) -> None: ...
+    def set_value(self, target: _Target, value: str) -> None: ...
+    def set_numeric_value(self, target: _Target, value: float) -> None: ...
+    def type_text(self, target: _Target, text: str) -> None: ...
+    def scroll(self, target: _Target, direction: str, amount: float = 1.0) -> None: ...
+    def select_text(self, target: _Target, start: int, end: int) -> None: ...
+    def locator(
+        self,
+        selector: str,
+        *,
+        max_depth: int | None = None,
+        max_elements: int | None = None,
+        visible_only: bool = False,
+        roles: list[str] | None = None,
+        include_raw: bool = False,
+    ) -> Locator: ...
+    def dump(self) -> str: ...
+    def __len__(self) -> int: ...
+    def __iter__(self) -> Iterator[Node]: ...
+    def __repr__(self) -> str: ...
+    def __str__(self) -> str: ...
+
+# ── Provider ─────────────────────────────────────────────────────────────────
+
+class Provider:
+    def __init__(self) -> None: ...
+    def app(
+        self,
+        name: str | None = None,
+        *,
+        pid: int | None = None,
+        max_depth: int | None = None,
+        max_elements: int | None = None,
+        visible_only: bool = False,
+        roles: list[str] | None = None,
+        include_raw: bool = False,
+    ) -> Tree: ...
+    def all_apps(
+        self,
+        *,
+        max_depth: int | None = None,
+        max_elements: int | None = None,
+        visible_only: bool = False,
+        roles: list[str] | None = None,
+        include_raw: bool = False,
+    ) -> Tree: ...
+    def list_apps(self) -> list[AppInfo]: ...
+    def check_permissions(self) -> str: ...
+    def locator(
+        self,
+        name: str | None = None,
+        *,
+        pid: int | None = None,
+        selector: str,
+        max_depth: int | None = None,
+        max_elements: int | None = None,
+        visible_only: bool = False,
+        roles: list[str] | None = None,
+        include_raw: bool = False,
+    ) -> Locator: ...
+    def __enter__(self) -> Provider: ...
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None = None,
+        exc_val: BaseException | None = None,
+        exc_tb: TracebackType | None = None,
+    ) -> bool: ...
+    def __repr__(self) -> str: ...
+
+# ── Locator ──────────────────────────────────────────────────────────────────
+
+class Locator:
+    @property
+    def selector(self) -> str: ...
+    def nth(self, n: int) -> Locator: ...
+    def first(self) -> Locator: ...
+    def child(self, selector: str) -> Locator: ...
+    def descendant(self, selector: str) -> Locator: ...
+    def role(self) -> str: ...
+    def name(self) -> str | None: ...
+    def value(self) -> str | None: ...
+    def description(self) -> str | None: ...
+    def is_visible(self) -> bool: ...
+    def is_enabled(self) -> bool: ...
+    def is_focused(self) -> bool: ...
+    def exists(self) -> bool: ...
+    def count(self) -> int: ...
+    def get(self) -> Node: ...
+    def press(self) -> None: ...
+    def focus(self) -> None: ...
+    def blur(self) -> None: ...
+    def toggle(self) -> None: ...
+    def expand(self) -> None: ...
+    def collapse(self) -> None: ...
+    def select_item(self) -> None: ...
+    def show_menu(self) -> None: ...
+    def scroll_into_view(self) -> None: ...
+    def increment(self) -> None: ...
+    def decrement(self) -> None: ...
+    def set_value(self, value: str) -> None: ...
+    def set_numeric_value(self, value: float) -> None: ...
+    def type_text(self, text: str) -> None: ...
+    def select_text(self, start: int, end: int) -> None: ...
+    def scroll(self, direction: str, amount: float = 1.0) -> None: ...
+    def wait_visible(self, timeout: float = 5.0) -> None: ...
+    def wait_attached(self, timeout: float = 5.0) -> None: ...
+    def wait_detached(self, timeout: float = 5.0) -> None: ...
+    def wait_enabled(self, timeout: float = 5.0) -> None: ...
+    def wait_hidden(self, timeout: float = 5.0) -> None: ...
+    def __repr__(self) -> str: ...
+
+# ── Module-level functions ───────────────────────────────────────────────────
+
+def connect() -> Provider: ...
+def app(
+    name: str | None = None,
+    *,
+    pid: int | None = None,
+    max_depth: int | None = None,
+    max_elements: int | None = None,
+    visible_only: bool = False,
+    roles: list[str] | None = None,
+    include_raw: bool = False,
+) -> Tree: ...
+def list_apps() -> list[AppInfo]: ...
+def check_permissions() -> str: ...
+
+# ── Test helpers ─────────────────────────────────────────────────────────────
+
+def _make_test_tree() -> Tree: ...
+def _make_test_provider() -> Provider: ...

xa11y-0.1.0/xa11y/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "xa11y"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+description = "Cross-platform accessibility client library — unified API for reading and interacting with accessibility trees"
+
+[dependencies]
+xa11y-core = { workspace = true }
+
+[target.'cfg(target_os = "macos")'.dependencies]
+xa11y-macos = { workspace = true }
+
+[target.'cfg(target_os = "windows")'.dependencies]
+xa11y-windows = { workspace = true }
+
+[target.'cfg(target_os = "linux")'.dependencies]
+xa11y-linux = { workspace = true }
+
+[dev-dependencies]
+serde_json = { workspace = true }

xa11y-0.1.0/xa11y/src/lib.rs

@@ -0,0 +1,91 @@
+//! xa11y — Cross-Platform Accessibility Client Library
+//!
+//! Provides a unified API for reading and interacting with accessibility trees
+//! across desktop platforms (macOS, Windows, Linux).
+//!
+//! # Quick Start
+//!
+//! ```no_run
+//! use xa11y::*;
+//!
+//! let provider = create_provider().expect("Failed to create provider");
+//! let status = provider.check_permissions().expect("Permission check failed");
+//!
+//! match status {
+//!     PermissionStatus::Granted => {
+//!         let tree = provider.get_app_tree(
+//!             &AppTarget::ByName("Safari".to_string()),
+//!             &QueryOptions::default(),
+//!         ).expect("Failed to get tree");
+//!
+//!         let buttons = tree.query("button").expect("Query failed");
+//!         println!("Found {} buttons", buttons.len());
+//!     }
+//!     PermissionStatus::Denied { instructions } => {
+//!         eprintln!("Accessibility not enabled: {}", instructions);
+//!     }
+//! }
+//! ```
+
+// Re-export all core types
+pub use xa11y_core::*;
+
+// Platform-specific provider creation
+
+/// Create a platform-appropriate accessibility provider.
+///
+/// Returns a boxed `Provider` trait object for the current platform.
+/// On unsupported platforms, returns a `Platform` error.
+pub fn create_provider() -> Result<Box<dyn Provider>> {
+    #[cfg(target_os = "macos")]
+    {
+        Ok(Box::new(xa11y_macos::MacOSProvider::new()?))
+    }
+
+    #[cfg(target_os = "windows")]
+    {
+        Ok(Box::new(xa11y_windows::WindowsProvider::new()?))
+    }
+
+    #[cfg(target_os = "linux")]
+    {
+        Ok(Box::new(xa11y_linux::LinuxProvider::new()?))
+    }
+
+    #[cfg(not(any(target_os = "macos", target_os = "windows", target_os = "linux")))]
+    {
+        Err(Error::Platform {
+            code: -1,
+            message: format!("Unsupported platform: {}", std::env::consts::OS),
+        })
+    }
+}
+
+/// Create a platform-appropriate event provider (supports subscribe/wait).
+///
+/// Returns a boxed `EventProvider` trait object for the current platform.
+/// EventProvider extends Provider with event subscription capabilities.
+pub fn create_event_provider() -> Result<Box<dyn EventProvider>> {
+    #[cfg(target_os = "macos")]
+    {
+        Ok(Box::new(xa11y_macos::MacOSProvider::new()?))
+    }
+
+    #[cfg(target_os = "windows")]
+    {
+        Ok(Box::new(xa11y_windows::WindowsProvider::new()?))
+    }
+
+    #[cfg(target_os = "linux")]
+    {
+        Ok(Box::new(xa11y_linux::LinuxProvider::new()?))
+    }
+
+    #[cfg(not(any(target_os = "macos", target_os = "windows", target_os = "linux")))]
+    {
+        Err(Error::Platform {
+            code: -1,
+            message: format!("Unsupported platform: {}", std::env::consts::OS),
+        })
+    }
+}