crosslocator 0.2.0__py3-none-any.whl

crosslocator/__init__.py

@@ -0,0 +1,29 @@
+"""crosslocator — define a UI selector once, resolve it on every platform."""
+from .appium import use_appium
+from .locator import (
+    CrossLocatorError,
+    Locator,
+    LocatorNotFound,
+    PlatformNotSet,
+)
+from .platform import (
+    Platform,
+    get_current_platform,
+    set_current_platform,
+    set_platform_provider,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Locator",
+    "Platform",
+    "get_current_platform",
+    "set_current_platform",
+    "set_platform_provider",
+    "use_appium",
+    "CrossLocatorError",
+    "LocatorNotFound",
+    "PlatformNotSet",
+    "__version__",
+]

crosslocator/appium.py

@@ -0,0 +1,55 @@
+"""Automatic platform detection from a live Appium session.
+
+crosslocator stays framework-agnostic: this module only reads the session
+capabilities and translates them into a :class:`~crosslocator.platform.Platform`.
+"""
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+from .platform import Platform, set_platform_provider
+
+
+def platform_from_capabilities(
+    capabilities: Optional[Mapping[str, Any]],
+) -> Optional[Platform]:
+    """Translate Appium capabilities into a :class:`Platform`.
+
+    Returns ``None`` when the platform cannot be determined.
+    """
+    if not capabilities:
+        return None
+    name = str(
+        capabilities.get("platformName")
+        or capabilities.get("appium:platformName")
+        or ""
+    ).strip().lower()
+    device = str(
+        capabilities.get("deviceName")
+        or capabilities.get("appium:deviceName")
+        or ""
+    ).lower()
+    if name == "android":
+        return Platform.ANDROID
+    if name in ("ios", "iphoneos", "iphone os"):
+        return Platform.IPAD if "ipad" in device else Platform.IOS
+    if name in ("windows", "win"):
+        return Platform.WINDOWS
+    return None
+
+
+def use_appium(driver: Optional[Any]) -> None:
+    """Detect the current platform automatically from an Appium ``driver``.
+
+    Registers a provider that reads ``driver.capabilities`` on each resolution,
+    so you no longer need to call :func:`set_current_platform` by hand. Pass
+    ``None`` to stop using the driver.
+    """
+    if driver is None:
+        set_platform_provider(None)
+        return
+
+    def provider() -> Optional[Platform]:
+        return platform_from_capabilities(getattr(driver, "capabilities", None))
+
+    set_platform_provider(provider)

crosslocator/locator.py

@@ -0,0 +1,107 @@
+"""The :class:`Locator` type: define a selector once, resolve it per platform."""
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+from .platform import (
+    Platform,
+    PlatformLike,
+    get_current_platform,
+    normalize_platform,
+)
+
+
+class CrossLocatorError(Exception):
+    """Base class for all crosslocator errors."""
+
+
+class PlatformNotSet(CrossLocatorError):
+    """Raised when a resolution needs the current platform but none is set."""
+
+
+class LocatorNotFound(CrossLocatorError, LookupError):
+    """Raised when no selector is available for the requested platform."""
+
+
+# A platform inherits from the next one in its chain when it has no own selector.
+_FALLBACK_CHAINS: Dict[Platform, tuple] = {
+    Platform.IPAD: (Platform.IPAD, Platform.IOS),
+}
+
+
+class Locator:
+    """A UI selector declared once for several platforms.
+
+    Define a selector per platform plus an optional shared ``default``. At
+    runtime, :meth:`resolve` (or :meth:`for_platform`) returns the right
+    selector string. crosslocator only *routes* strings — it never parses them
+    nor touches your driver.
+    """
+
+    __slots__ = ("_selectors", "_default")
+
+    def __init__(
+        self,
+        *,
+        android: Optional[str] = None,
+        ios: Optional[str] = None,
+        ipad: Optional[str] = None,
+        windows: Optional[str] = None,
+        web: Optional[str] = None,
+        default: Optional[str] = None,
+    ) -> None:
+        self._selectors: Dict[Platform, Optional[str]] = {
+            Platform.ANDROID: android,
+            Platform.IOS: ios,
+            Platform.IPAD: ipad,
+            Platform.WINDOWS: windows,
+            Platform.WEB: web,
+        }
+        self._default = default
+        if default is None and not any(self._selectors.values()):
+            raise ValueError(
+                "A Locator needs at least one platform selector or a default."
+            )
+
+    def for_platform(self, platform: PlatformLike) -> str:
+        """Return the selector for ``platform``, applying fallbacks.
+
+        Resolution order: the platform's own selector, then its fallback chain
+        (e.g. iPad -> iOS), then ``default``. Raises :class:`LocatorNotFound`
+        if nothing matches.
+        """
+        target = normalize_platform(platform)
+        for candidate in _FALLBACK_CHAINS.get(target, (target,)):
+            value = self._selectors.get(candidate)
+            if value is not None:
+                return value
+        if self._default is not None:
+            return self._default
+        raise LocatorNotFound(
+            f"No selector defined for platform {target.value!r} and no default set."
+        )
+
+    def resolve(self) -> str:
+        """Return the selector for the current platform.
+
+        Raises :class:`PlatformNotSet` when the current platform is unknown.
+        """
+        platform = get_current_platform()
+        if platform is None:
+            raise PlatformNotSet(
+                "No current platform set. Use set_current_platform(...) or the "
+                "CROSSLOCATOR_PLATFORM environment variable."
+            )
+        return self.for_platform(platform)
+
+    def __repr__(self) -> str:
+        parts = {p.value: v for p, v in self._selectors.items() if v is not None}
+        if self._default is not None:
+            parts["default"] = self._default
+        inner = ", ".join(f"{k}={v!r}" for k, v in parts.items())
+        return f"Locator({inner})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Locator):
+            return NotImplemented
+        return self._selectors == other._selectors and self._default == other._default

crosslocator/platform.py

@@ -0,0 +1,89 @@
+"""Platform identification and current-platform state.
+
+crosslocator resolves selectors against a *current platform*. This module owns
+the small enum of supported platforms, alias normalization, and the resolution
+of the current platform from (in priority order):
+
+1. an explicit value set via :func:`set_current_platform`
+2. the ``CROSSLOCATOR_PLATFORM`` environment variable
+3. a registered provider (e.g. reading a live Appium session)
+"""
+from __future__ import annotations
+
+import os
+from enum import Enum
+from typing import Callable, Optional, Union
+
+
+class Platform(Enum):
+    """A UI platform a selector can target."""
+
+    ANDROID = "android"
+    IOS = "ios"
+    IPAD = "ipad"
+    WINDOWS = "windows"
+    WEB = "web"
+
+
+PlatformLike = Union[Platform, str]
+
+ENV_VAR = "CROSSLOCATOR_PLATFORM"
+
+_ALIASES = {
+    "android": Platform.ANDROID,
+    "ios": Platform.IOS,
+    "iphone": Platform.IOS,
+    "ipad": Platform.IPAD,
+    "ipados": Platform.IPAD,
+    "windows": Platform.WINDOWS,
+    "win": Platform.WINDOWS,
+    "web": Platform.WEB,
+    "browser": Platform.WEB,
+}
+
+_current: Optional[Platform] = None
+_provider: Optional[Callable[[], Optional[PlatformLike]]] = None
+
+
+def normalize_platform(value: PlatformLike) -> Platform:
+    """Return the :class:`Platform` for ``value``, accepting common aliases.
+
+    Raises :class:`ValueError` for unknown platforms.
+    """
+    if isinstance(value, Platform):
+        return value
+    key = str(value).strip().lower()
+    try:
+        return _ALIASES[key]
+    except KeyError:
+        raise ValueError(f"Unknown platform: {value!r}") from None
+
+
+def set_current_platform(value: Optional[PlatformLike]) -> None:
+    """Set (or clear, with ``None``) the platform used to resolve selectors."""
+    global _current
+    _current = None if value is None else normalize_platform(value)
+
+
+def set_platform_provider(
+    provider: Optional[Callable[[], Optional[PlatformLike]]],
+) -> None:
+    """Register a callable returning the current platform (e.g. from Appium).
+
+    Pass ``None`` to unregister.
+    """
+    global _provider
+    _provider = provider
+
+
+def get_current_platform() -> Optional[Platform]:
+    """Resolve the current platform, or ``None`` if it cannot be determined."""
+    if _current is not None:
+        return _current
+    env = os.environ.get(ENV_VAR)
+    if env:
+        return normalize_platform(env)
+    if _provider is not None:
+        result = _provider()
+        return None if result is None else normalize_platform(result)
+    return None

crosslocator/robot.py

@@ -0,0 +1,51 @@
+"""Robot Framework integration for crosslocator.
+
+Import in a suite with::
+
+    Library    crosslocator.robot.CrossLocator
+
+Locators are plain Python objects: define them in a Python variable file and
+import them, then resolve them with the keywords below.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from .locator import Locator
+from .platform import get_current_platform, set_current_platform
+
+
+class CrossLocator:
+    """Robot Framework library exposing crosslocator as keywords."""
+
+    ROBOT_LIBRARY_SCOPE = "GLOBAL"
+
+    def set_current_platform(self, platform: str) -> None:
+        """Set the platform used to resolve locators.
+
+        Accepts ``android``, ``ios``, ``ipad``, ``windows`` or ``web``.
+        """
+        set_current_platform(platform)
+
+    def get_current_platform(self) -> str:
+        """Return the current platform name, or an empty string if unset."""
+        platform = get_current_platform()
+        return platform.value if platform is not None else ""
+
+    def resolve_locator(self, locator: Locator, platform: Optional[str] = None) -> str:
+        """Resolve a ``Locator`` to a selector string.
+
+        Uses ``platform`` when given, otherwise the current platform.
+        """
+        if platform:
+            return locator.for_platform(platform)
+        return locator.resolve()
+
+    def use_appium_session(self) -> None:
+        """Auto-detect the platform from the active AppiumLibrary session."""
+        from robot.libraries.BuiltIn import BuiltIn
+
+        from .appium import use_appium
+
+        appium_lib = BuiltIn().get_library_instance("AppiumLibrary")
+        use_appium(appium_lib._current_application())

crosslocator-0.2.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: crosslocator
+Version: 0.2.0
+Summary: Define a UI selector once, resolve it on every platform (Android, iOS, iPadOS, Windows, web).
+Project-URL: Homepage, https://github.com/julien-becheny/crosslocator
+Project-URL: Repository, https://github.com/julien-becheny/crosslocator
+Project-URL: Issues, https://github.com/julien-becheny/crosslocator/issues
+Author: Julien Becheny
+License: MIT
+License-File: LICENSE
+Keywords: android,appium,ios,locators,mobile-testing,playwright,robotframework,selectors,test-automation,windows
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Robot Framework :: Library
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# crosslocator
+
+**Define a UI selector once. Resolve it on every platform.**
+
+Cross-platform test automation means maintaining the same element for Android,
+iOS, iPadOS, Windows and the web. Most teams end up either duplicating selectors
+or scattering `if platform == ...` branches through their page objects.
+
+`crosslocator` lets you declare a selector **once**, per platform, and resolves
+the right one at runtime — from **pure Python (Appium), Robot Framework, or any
+other framework**. It only routes selector *strings*; it never wraps your driver.
+
+```python
+from crosslocator import Locator
+
+ADD_PATIENT = Locator(
+    android="accessibility_id=add_patient",
+    ios="add_patient",
+    windows='//Button[@Name="Add"]',
+    default="id=add",
+)
+
+ADD_PATIENT.for_platform("ios")   # -> "add_patient"
+```
+
+## Installation
+
+```bash
+pip install crosslocator
+```
+
+Zero runtime dependencies.
+
+## Why
+
+- **One source of truth** per element — no duplicated selectors, no platform `if/else`.
+- **Framework-agnostic** — Appium in plain Python, Robot Framework, or anything else.
+- **Sensible fallbacks** — iPad inherits from iOS, and a shared `default` covers the rest.
+- **Typed** and dependency-free.
+
+## Quick start (Python)
+
+```python
+from crosslocator import Locator, set_current_platform
+
+ADD_PATIENT = Locator(
+    android="accessibility_id=add_patient",
+    ios="add_patient",
+    windows='//Button[@Name="Add"]',
+)
+
+set_current_platform("android")   # usually done once, at session start
+ADD_PATIENT.resolve()             # -> "accessibility_id=add_patient"
+```
+
+## Robot Framework
+
+```robotframework
+*** Settings ***
+Library     crosslocator.robot.CrossLocator
+Variables   locators.py        # ADD_PATIENT defined as a Locator here
+
+*** Test Cases ***
+Open Add Patient
+    Set Current Platform    android
+    ${selector}=    Resolve Locator    ${ADD_PATIENT}
+    # -> pass ${selector} to AppiumLibrary / Browser as usual
+```
+
+## How the platform is resolved
+
+`resolve()` determines the current platform in this order:
+
+1. an explicit `set_current_platform(...)`
+2. the `CROSSLOCATOR_PLATFORM` environment variable
+3. a registered provider — typically an Appium session (see below)
+
+## Automatic platform detection (Appium)
+
+Let crosslocator read the platform straight from a live Appium session, so you
+never call `set_current_platform` by hand.
+
+**Python (Appium-Python-Client):**
+
+```python
+from crosslocator import use_appium
+
+use_appium(driver)      # your Appium webdriver
+LOGIN_BUTTON.resolve()  # platform detected from the session capabilities
+```
+
+**Robot Framework (AppiumLibrary):**
+
+```robotframework
+Open Application    ${REMOTE_URL}    platformName=Android    ...
+Use Appium Session
+${selector}=    Resolve Locator    ${LOGIN_BUTTON}
+```
+
+iPad is detected from the session device name and resolves to iPad selectors
+(falling back to iOS when none are defined).
+
+## Fallback rules
+
+- `ipad` → falls back to `ios` when no iPad-specific selector is set
+- any platform → falls back to `default`
+- nothing found → `LocatorNotFound`
+
+## Examples
+
+Runnable examples (no device needed) live in the [`examples/`](examples/) folder —
+a login screen resolved across Android, iOS, iPadOS and Windows, plus a Robot
+Framework suite.
+
+## Roadmap
+
+- **v0.1:** the core `Locator` type, platform resolution, Robot Framework keywords.
+- **v0.2 (current):** automatic platform detection from a live Appium session.
+- **Next:** Playwright/Browser helpers, and declarative loading of whole screens from YAML/dict.
+
+Issues and contributions are welcome.
+
+## License
+
+MIT © 2026 Julien Becheny

crosslocator-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+crosslocator/__init__.py,sha256=APhm-eLujcLCQDuSEZMbzQlL7g0iryzuElSkulXXtHQ,622
+crosslocator/appium.py,sha256=F-nzbMgO6Ennf7XTWJTSrtSgNTrLDSqBnVRSmgK65Yw,1793
+crosslocator/locator.py,sha256=PoNZeHAkD4bGlVIQZwC8D5aVrU_aXyFTMNEftz3sR2k,3762
+crosslocator/platform.py,sha256=c9or-XWVoG4GA6pIMuFKh2oG070d8G1-PJcKxo_W-Zc,2601
+crosslocator/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+crosslocator/robot.py,sha256=g8e3GKhxb9qGY86GRqG23br2wg49ts-dao4mALQiUEo,1729
+crosslocator-0.2.0.dist-info/METADATA,sha256=9vGHNdMnu9N5Ceb-2KK5dVEijOmQQLRkzI2NANToN2k,4823
+crosslocator-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+crosslocator-0.2.0.dist-info/licenses/LICENSE,sha256=FWUI76-_E-wL4KfLcr4hKvTb_2-iS6XTMdLHfV8atfs,1092
+crosslocator-0.2.0.dist-info/RECORD,,

crosslocator-0.2.0.dist-info/WHEEL

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

crosslocator-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julien Becheny
+
+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.