# Python library layer

> How the `Optics` class wraps sessions and the keyword classes so Python code and Robot Framework can call Optics directly.

Optics has a Python library interface that gives code direct access to the framework. This page explains how the library is built, the usage patterns it supports, and how it uses the core framework. For a user's guide with a complete pytest example, see [Use Optics from Python](https://optics-framework.org/docs/create/python) and [Use Optics in Robot Framework](https://optics-framework.org/docs/create/robot).

## Overview

The library layer provides:

1. **Programmatic interface**: a direct Python API for test automation
2. **Robot Framework integration**: the same class works as a Robot Framework library
3. **Session management**: create and manage test sessions from code
4. **Keyword access**: direct access to all framework keywords
5. **Configuration management**: configuration from code or from files

## Library architecture

`What the Optics class wraps`:

```mermaid
graph TB
    A[Python Code] --> B[Optics Class]
    B --> C[SessionManager]
    B --> D[ActionKeyword]
    B --> E[AppManagement]
    B --> F[Verifier]
    B --> G[FlowControl]
    C --> H[Session]
    H --> I[OpticsBuilder]
    I --> J[Factories]
    J --> K[Drivers]
    J --> L[Element Sources]
    J --> M[Vision Models]
```

**Location:** `optics_framework/optics.py`

`from optics_framework import Optics` works because the package re-exports the class. The re-export is lazy: plain `import optics_framework` and imports of its submodules do not load the API and vision stack.

## Optics class

The `Optics` class is the main entry point for the Python library. It gives one interface that works both as a standalone Python library and as a Robot Framework library.

### Class structure

```python
@library(scope="GLOBAL")
class Optics:
    """
    A lightweight interface to interact with the Optics Framework.
    Provides direct access to app management, action, and verification keywords with a single setup
    method.
    Supports Robot Framework as a library when Robot Framework is installed.
    """

    def __init__(self, config: Optional[Dict[str, Any]] = None):
        """
        Initialize the Optics instance. Call setup() to configure the driver and sources.
        """

    @keyword("Setup")
    def setup(
        self,
        config: Union[str, Dict[str, Any], None] = None,
        driver_sources: Optional[List[Dict[str, Dict[str, Any]]]] = None,
        elements_sources: Optional[List[Dict[str, Dict[str, Any]]]] = None,
        image_detection: Optional[List[Dict[str, Dict[str, Any]]]] = None,
        text_detection: Optional[List[Dict[str, Dict[str, Any]]]] = None,
        execution_output_path_param: Optional[str] = None,
    ) -> None:
        """
        Configure the Optics Framework with required driver and element source settings.
        """
```

When Robot Framework is not installed, `@library` and `@keyword` are replaced by decorators that do nothing, so the class still imports.

### Initialization

You can create the `Optics` class with or without configuration.

**With configuration:**

```python
from optics_framework import Optics

config = {
    "driver_sources": [{"appium": {"enabled": True, "url": "http://localhost:4723"}}],
    "elements_sources": [{"appium_find_element": {"enabled": True}}]
}

optics = Optics(config=config)
```

**Without configuration (setup later):**

```python
from optics_framework import Optics

optics = Optics()
optics.setup(config=config)
```

`__init__` creates its own `SessionManager` and calls `setup(config)` when you give a config.

## Usage patterns

### Standalone Python script

You can use the library in a standalone Python script:

```python
from optics_framework import Optics

# Initialize and configure
optics = Optics()
optics.setup(config={
    "driver_sources": [{"appium": {"enabled": True, "url": "http://localhost:4723"}}],
    "elements_sources": [{"appium_find_element": {"enabled": True}}]
})

# Use keywords
optics.launch_app(app_identifier="com.example.app")
optics.press_element("submit_button")
optics.enter_text("username_field", "testuser")
optics.validate_element("welcome_message")

# Cleanup
optics.quit()
```

### Robot Framework library

When Robot Framework is installed, the `Optics` class works as a Robot Framework library. `Setup` takes the contents of a config, so read the file first:

```robotframework
*** Settings ***
Library    OperatingSystem
Library    optics_framework.optics.Optics

*** Test Cases ***
Example Test
    ${config}=    Get File    ${CURDIR}/config.yaml
    Setup    config=${config}
    Launch App    com.example.app
    Press Element    submit_button
    Enter Text    username_field    testuser
    Validate Element    welcome_message
    Quit
```

`Setup    driver_sources=[{"appium": {"enabled": True, "url": "http://localhost:4723"}}]` alone does not work: the separate source parameters need both `driver_sources` and `elements_sources`, and Robot passes the value as a string. Use `config=` or `Setup From File`.

### Configuration from file

Load configuration from YAML or JSON files:

```python
from optics_framework import Optics

# From YAML file
optics = Optics()
optics.setup_from_file("config.yaml")

# Or inline YAML/JSON string
yaml_config = """
driver_sources:
  - appium:
      enabled: true
      url: "http://localhost:4723"
elements_sources:
  - appium_find_element:
      enabled: true
"""
optics.setup(config=yaml_config)
```

`setup_from_file` reads the file and passes the parsed dict to `setup`. A missing file raises `FileNotFoundError`; any other read or parse failure raises `ValueError`.

## Component access

The `Optics` class gives direct access to the keywords of the underlying components. Every keyword is a snake_case method.

- Pass every value as a string. A number, such as `100`, raises `TypeError`.
- Pass locators: text, an XPath or an image name. A name from an elements file is not looked up, and `${name}` is not replaced in these methods.
- A list means "try these in order". To name several elements in one check, separate them with `|` in one string.

### Action keywords

```python
optics = Optics(config=config)

# Element interactions
optics.press_element("button_id")
optics.press_by_coordinates("100", "200")
optics.press_by_percentage("50", "50")

# Text input
optics.enter_text("input_field", "text")
optics.enter_text_direct("text")

# Gestures
optics.swipe("100", "200", "up", "50")
optics.scroll("down")
```

`swipe(coor_x, coor_y, direction="right", swipe_length="50")` starts at a point and moves in a direction. `scroll(direction="down")` takes only a direction.

### App management

```python
# App lifecycle
optics.launch_app(app_identifier="com.example.app")
optics.launch_other_app("com.other.app")
optics.close_and_terminate_app()
optics.force_terminate_app("com.example.app")

# App information
version = optics.get_app_version()
session_id = optics.get_driver_session_id()
```

### Verification

```python
# Element validation
optics.validate_element("element_id")
optics.assert_presence("element1|element2", rule="all")

# Screen validation
optics.validate_screen("element1|element2")

# Screenshots and page source
screenshot = optics.capture_screenshot()
page_source = optics.capture_pagesource()
```

`capture_screenshot` returns a base64 PNG. `capture_pagesource` returns a dict with `page_source` and `timestamp`.

### Flow control

Flow-control methods work on variables and modules in the session. `condition` and `run_loop` run modules, which you add with `add_module`.

```python
# Conditional execution
optics.condition("${variable} == 'value'", "module_name")

# Data operations
data = optics.read_data("${data}", "data.csv")
result = optics.invoke_api("collection.api_name")

# Loops
optics.run_loop("module_name", "5")

# Evaluation
value = optics.evaluate("${total}", "${var1} + ${var2}")
date = optics.date_evaluate("${tomorrow}", "04/25/2025", "+1 day")
```

- `condition(*args)` takes condition-target pairs and an optional else target. A condition is an expression or a module name.
- `read_data(element, source, query="")` stores the rows under `element`. The source is a `.csv` or `.json` file or a 2D list.
- `invoke_api(api)` calls an API from the definitions you load with `add_api`, by `collection.api_name`.
- `run_loop(target, *args)` runs a module a number of times, or once for each value of a variable.
- `evaluate(param1, param2)` stores the result of the expression `param2` under `param1`.
- `date_evaluate(param1, param2, param3, param4="%d %B")` stores the date `param2` moved by `param3`, in the format `param4`.

See the [flow control keywords](https://optics-framework.org/docs/reference/keywords/flow) for every rule.

## Session management

### Session lifecycle

The library manages sessions internally:

```python
optics = Optics()

# Setup creates a session
optics.setup(config=config)  # Session created automatically

# All operations use the active session
optics.press_element("button")

# Quit terminates the session
optics.quit()  # Session terminated and cleaned up
```

`setup()` creates a session automatically, all operations use the active session, and `quit()` terminates the session and cleans it up.

### Multiple sessions

For advanced use, you can run more than one session:

```python
from optics_framework import Optics
from optics_framework.common.session_manager import SessionManager

# Create multiple Optics instances for different sessions
optics1 = Optics(config=config1)
optics2 = Optics(config=config2)

# Each instance has its own session
optics1.launch_app(app_identifier="app1")
optics2.launch_app(app_identifier="app2")
```

Each `Optics` instance has its own `SessionManager` and its own session.

## Configuration

### Configuration formats

The library supports more than one configuration format. A config must have `driver_sources` and `elements_sources`, both lists.

**Dictionary:**

```python
config = {
    "driver_sources": [{"appium": {"enabled": True, "url": "http://localhost:4723"}}],
    "elements_sources": [{"appium_find_element": {"enabled": True}}],
    "text_detection": [{"easyocr": {"enabled": True}}],
    "image_detection": [{"templatematch": {"enabled": True}}],
    "project_path": "/path/to/project"
}
optics.setup(config=config)
```

With `project_path`, setup searches that folder for image files (`.png`, `.jpg`, `.jpeg`, `.bmp`, `.tiff`, `.tif`) to use as templates.

**YAML string:**

```python
yaml_config = """
driver_sources:
  - appium:
      enabled: true
      url: "http://localhost:4723"
      capabilities:
        platformName: "Android"
elements_sources:
  - appium_find_element:
      enabled: true
"""
optics.setup(config=yaml_config)
```

**JSON string:**

```python
json_config = """
{
  "driver_sources": [{"appium": {"enabled": true, "url": "http://localhost:4723"}}],
  "elements_sources": [{"appium_find_element": {"enabled": true}}]
}
"""
optics.setup(config=json_config)
```

A string that starts with `{` or `[` is parsed as JSON, and any other string as YAML. A string that does not parse raises `OpticsError` with `E0503`.

**File path:**

```python
optics.setup_from_file("config.yaml")
```

### Configuration parameters

You can also pass the configuration as separate parameters. This form is deprecated and logs a warning; use `config=` instead. It needs both `driver_sources` and `elements_sources`.

```python
optics.setup(
    driver_sources=[{"appium": {"enabled": True, "url": "http://localhost:4723"}}],
    elements_sources=[{"appium_find_element": {"enabled": True}}],
    text_detection=[{"easyocr": {"enabled": True}}],
    image_detection=[{"templatematch": {"enabled": True}}],
    execution_output_path_param="/path/to/output"
)
```

## Element management

### Adding elements

You can add and read elements from code:

```python
# Add element
optics.add_element("submit_button", "//button[@id='submit']")

# Get element value
element_value = optics.get_element_value("submit_button")

# Use element in keywords: pass the locator, not the name
optics.press_element("//button[@id='submit']")
```

`get_element_value` returns the list of values stored under the name. Action methods such as `press_element` do not look the name up, so pass the locator itself.

### Element variables

Flow-control methods and modules refer to elements with the `${variable}` syntax:

```python
optics.add_element("button", "//button[@id='submit']")

# Resolve variable: ${button} resolves to the stored element value inside a module
optics.add_module("Submit", [("Press Element", ["${button}"])])
optics.run_loop("Submit", "1")
```

When the module runs, `${button}` resolves to the stored element value. `optics.press_element("${button}")` does not resolve it.

## Fallback parameters

The library supports fallback parameters for resilience:

```python
# Single fallback value
optics.press_element(["button1", "button2", "button3"])

# Multiple fallback parameters
optics.press_element(
    element=["btn1", "btn2"],
    index=["0", "1"]
)
```

The `@fallback_params` decorator finds the parameters typed `fallback_str` (`Union[str, List[str]]`) and tries their combinations in order, through `fallback.run` in `optics_framework/common/fallback.py`. It moves to the next combination only when the element is not found, and it stops after 20 combinations.

## Integration with core framework

### Session manager integration

The library uses `SessionManager` internally:

```python
# Optics class creates and manages sessions
optics = Optics()
optics.setup(config)  # Creates session via SessionManager

# Session is accessible
session_id = optics.session_id
session = optics.session_manager.get_session(session_id)
```

`setup()` creates the session through `SessionManager`, and the session is then accessible.

### Builder integration

The library uses `OpticsBuilder` to construct components:

```python
# Builder is created during setup
optics.setup(config)

# Components are built via OpticsBuilder
# Access to built components:
driver = optics.session_manager.get_session(optics.session_id).driver
```

The session builds its components through `OpticsBuilder` during setup. `setup()` then builds `ActionKeyword`, `AppManagement` and `Verifier` with `session.optics.build(...)`, creates `FlowControl` over the same keyword map, and registers all four in a `KeywordRegistry`.

### API class integration

The library hands each call to an API class:

```python
# Optics class wraps API classes
optics.press_element("button")
# Internally calls: optics.action_keyword.press_element("button")

optics.validate_element("element")
# Internally calls: optics.verifier.validate_element("element")
```

## Error handling

The library uses the framework's error handling system:

```python
from optics_framework.common.error import OpticsError, Code

try:
    optics.press_element("nonexistent_element")
except OpticsError as e:
    print(f"Error code: {e.code}")
    print(f"Error message: {e.message}")
    print(f"Error details: {e.details}")
```

A keyword called before `setup()` raises `ValueError("Setup not complete. Call setup() first.")` (the `INVALID_SETUP` message), not an `OpticsError`. See [Errors](https://optics-framework.org/docs/contribute/errors).

## Robot Framework integration

### Library registration

When Robot Framework is installed, the `Optics` class is registered as a library:

```python
@library(scope="GLOBAL")
class Optics:
    # Class implementation
    ...
```

### Keyword discovery

Robot Framework discovers the methods decorated with `@keyword`:

```python
@keyword("Press Element")
@fallback_params
def press_element(
    self,
    element: fallback_str,
    repeat: fallback_str = "1",
    ...
) -> None:
    ...
```

The `Optics` class also has keywords that the suite files do not have, such as `Setup`, `Setup From File`, `Add Element`, `Get Element Value`, `Add API`, `Add Testcase`, `Add Module`, `Add Error Definitions`, `Capture And Detect Errors` and `Quit`.

### Scope management

The library uses `GLOBAL` scope, so one instance is shared across all test cases:

```robotframework
*** Settings ***
Library    optics_framework.optics.Optics

*** Test Cases ***
Test 1
    Setup From File    config.yaml
    Press Element    button1

Test 2
    # Uses same Optics instance from Test 1
    Press Element    button2
```

## Best practices

### Configuration management

- Use configuration files for complex setups
- Keep sensitive data (URLs, credentials) in environment variables
- Use project-specific configuration files

### Session lifecycle

- Always call `quit()` when done to clean up resources
- Use a context manager for automatic cleanup. `Optics` is one: `with Optics(config) as optics:` calls `quit()` at the end of the block. You can also write your own:

```python
from contextlib import contextmanager

@contextmanager
def optics_session(config):
    optics = Optics()
    optics.setup(config=config)
    try:
        yield optics
    finally:
        optics.quit()

with optics_session(config) as optics:
    optics.press_element("button")
```

### Error handling

- Wrap operations in `try`/`except` blocks
- Handle `OpticsError` for framework errors
- Check the session state before operations

### Element management

- Store elements that you use often
- Use descriptive element names
- Use fallback parameters for resilience

### Code organization

- Keep configuration apart from test logic
- Use helper functions for common operations
- Put keywords into logical groups

## Performance considerations

### Session reuse

- Reuse `Optics` instances across many operations
- Do not create a new instance for each operation

### Lazy initialization

- `OpticsBuilder` creates each engine the first time something asks for it (`get_driver()`, `get_element_source()` and so on). In practice that is during `setup()`: the session asks for the driver, and the keyword classes ask for the element source, text detection and image detection when `setup()` builds them.
- What waits for first use is the connection: the Appium driver opens its session only when `launch_app` starts the app. So `launch_app` can be slower than the calls after it.

### Resource cleanup

- Always call `quit()` to release resources
- Driver connections close on quit

## Troubleshooting

### Setup not complete

**Problem:** `ValueError: Setup not complete. Call setup() first.` (`INVALID_SETUP`) when you call keywords.

**Solutions:**

1. Make sure you call `setup()` before you use keywords.
2. Make sure the configuration is valid.
3. Make sure at least one driver is enabled.

### Element not found

**Problem:** Optics cannot find an element.

**Solutions:**

1. Make sure the element identifier is correct.
2. Make sure the element is visible on screen.
3. Use fallback parameters for more than one strategy.
4. Increase the timeout if needed.

### Session errors

**Problem:** Session errors.

**Solutions:**

1. Make sure the session was created successfully.
2. Make sure the session was not terminated.
3. Make sure `quit()` was not called too early.

### Robot Framework integration issues

**Problem:** Keywords are not available in Robot Framework.

**Solutions:**

1. Make sure Robot Framework is installed.
2. Make sure the library import path is correct.
3. Make sure the `@keyword` decorators are present.
4. Read the Robot Framework logs.

## Related pages

- [Component architecture](https://optics-framework.org/docs/contribute/components#optics-class): `Optics` class details
- [Session management](https://optics-framework.org/docs/contribute/components#sessionmanager): the session lifecycle
- [config.yaml reference](https://optics-framework.org/docs/reference/config): configuration
- [Use Optics from Python](https://optics-framework.org/docs/create/python) and the [keyword reference](https://optics-framework.org/docs/reference/keywords/): Python API and keyword reference
- [HTTP API reference](https://optics-framework.org/docs/reference/http-api): REST API endpoints
- [Strategies](https://optics-framework.org/docs/contribute/strategies): self-healing strategies
- [Errors](https://optics-framework.org/docs/contribute/errors): error codes and handling
