Exceptions

`flaui.lib.exceptions`

This module contains the set of custom FlaUI's exceptions.

The Python exceptions mirror the C# FlaUI.Core.Exceptions inheritance tree so that except clauses behave the same way they do in FlaUI:

.. code-block:: text

Exception
└── FlaUIException
    ├── ElementNotAvailableException
    ├── ElementNotEnabledException
    ├── ElementNotFound                 (Python-only convenience)
    ├── MethodNotSupportedException
    ├── NoClickablePointException
    ├── NotSupportedByFrameworkException
    ├── ProxyAssemblyNotLoadedException
    ├── NotCachedException
    │   ├── PatternNotCachedException    (carries ``pattern_id``)
    │   └── PropertyNotCachedException   (carries ``property_id``)
    └── NotSupportedException
        ├── PatternNotSupportedException  (carries ``pattern_id``)
        └── PropertyNotSupportedException (carries ``property_id``)

SystemException is intentionally kept outside the FlaUIException tree: it wraps a raw System.Exception that is not a FlaUI error, so except FlaUIException should not catch it.

`ElementNotAvailableException(message='Element not available')`

Bases: FlaUIException

Python equivalent of C# ElementNotAvailableException (the element is no longer available).

Initialise the exception.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error description.	`'Element not available'`

Source code in flaui/lib/exceptions.py

def __init__(self, message: str = "Element not available") -> None:
    """Initialise the exception.

    :param message: Human-readable error description.
    """
    super().__init__(message)

`ElementNotEnabledException(message='Element not enabled')`

Bases: FlaUIException

Python equivalent of C# ElementNotEnabledException (the element is disabled).

Initialise the exception.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error description.	`'Element not enabled'`

Source code in flaui/lib/exceptions.py

def __init__(self, message: str = "Element not enabled") -> None:
    """Initialise the exception.

    :param message: Human-readable error description.
    """
    super().__init__(message)

`ElementNotFound(message='Element not found')`

Bases: FlaUIException

Raised when an automation element cannot be found (Python-only convenience, no C# equivalent).

Initialise the exception.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error description.	`'Element not found'`

Source code in flaui/lib/exceptions.py

def __init__(self, message: str = "Element not found") -> None:
    """Initialise the exception.

    :param message: Human-readable error description.
    """
    super().__init__(message)

`FlaUIException(message='FlaUI exception')`

Bases: Exception

Base exception for all FlaUI errors (mirrors C# FlaUI.Core.Exceptions.FlaUIException).

Store the message and initialise the base Exception.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error description.	`'FlaUI exception'`

Source code in flaui/lib/exceptions.py

def __init__(self, message: str = "FlaUI exception") -> None:
    """Store the message and initialise the base ``Exception``.

    :param message: Human-readable error description.
    """
    self.message = message
    super().__init__(self.message)

`MethodNotSupportedException(message='Method not supported')`

Bases: FlaUIException

Python equivalent of C# MethodNotSupportedException (the method is not supported).

Initialise the exception.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error description.	`'Method not supported'`

Source code in flaui/lib/exceptions.py

def __init__(self, message: str = "Method not supported") -> None:
    """Initialise the exception.

    :param message: Human-readable error description.
    """
    super().__init__(message)

`NoClickablePointException(message='No clickable point')`

Bases: FlaUIException

Python equivalent of C# NoClickablePointException (no clickable point was found).

Initialise the exception.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error description.	`'No clickable point'`

Source code in flaui/lib/exceptions.py

def __init__(self, message: str = "No clickable point") -> None:
    """Initialise the exception.

    :param message: Human-readable error description.
    """
    super().__init__(message)

`NotCachedException(message='Not cached')`

Bases: FlaUIException

Python equivalent of C# NotCachedException (requested data was not in the cache).

Initialise the exception.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error description.	`'Not cached'`

Source code in flaui/lib/exceptions.py

def __init__(self, message: str = "Not cached") -> None:
    """Initialise the exception.

    :param message: Human-readable error description.
    """
    super().__init__(message)

`NotSupportedByFrameworkException(message='Not supported by framework')`

Bases: FlaUIException

Python equivalent of C# NotSupportedByFrameworkException (unsupported by the chosen UIA framework).

Initialise the exception.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error description.	`'Not supported by framework'`

Source code in flaui/lib/exceptions.py

def __init__(self, message: str = "Not supported by framework") -> None:
    """Initialise the exception.

    :param message: Human-readable error description.
    """
    super().__init__(message)

`NotSupportedException(message='Not supported')`

Bases: FlaUIException

Python equivalent of C# NotSupportedException (the requested feature is not supported).

Initialise the exception.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error description.	`'Not supported'`

Source code in flaui/lib/exceptions.py

def __init__(self, message: str = "Not supported") -> None:
    """Initialise the exception.

    :param message: Human-readable error description.
    """
    super().__init__(message)

`PatternNotCachedException(message='The requested pattern is not cached', pattern_id=None)`

Bases: NotCachedException

Python equivalent of C# PatternNotCachedException; carries the offending pattern_id.

Initialise the exception.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error description.	`'The requested pattern is not cached'`
`pattern_id`	`Optional[Any]`	The C# `PatternId` that is not cached, when known.	`None`

Source code in flaui/lib/exceptions.py

def __init__(self, message: str = "The requested pattern is not cached", pattern_id: Optional[Any] = None) -> None:
    """Initialise the exception.

    :param message: Human-readable error description.
    :param pattern_id: The C# ``PatternId`` that is not cached, when known.
    """
    self.pattern_id = pattern_id
    super().__init__(message)

`PatternNotSupportedException(message='The requested pattern is not supported', pattern_id=None)`

Bases: NotSupportedException

Python equivalent of C# PatternNotSupportedException; carries the offending pattern_id.

Initialise the exception.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error description.	`'The requested pattern is not supported'`
`pattern_id`	`Optional[Any]`	The C# `PatternId` that is not supported, when known.	`None`

Source code in flaui/lib/exceptions.py

def __init__(
    self, message: str = "The requested pattern is not supported", pattern_id: Optional[Any] = None
) -> None:
    """Initialise the exception.

    :param message: Human-readable error description.
    :param pattern_id: The C# ``PatternId`` that is not supported, when known.
    """
    self.pattern_id = pattern_id
    super().__init__(message)

`PropertyNotCachedException(message='The requested property is not cached', property_id=None)`

Bases: NotCachedException

Python equivalent of C# PropertyNotCachedException; carries the offending property_id.

Initialise the exception.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error description.	`'The requested property is not cached'`
`property_id`	`Optional[Any]`	The C# `PropertyId` that is not cached, when known.	`None`

Source code in flaui/lib/exceptions.py

def __init__(
    self, message: str = "The requested property is not cached", property_id: Optional[Any] = None
) -> None:
    """Initialise the exception.

    :param message: Human-readable error description.
    :param property_id: The C# ``PropertyId`` that is not cached, when known.
    """
    self.property_id = property_id
    super().__init__(message)

`PropertyNotSupportedException(message='The requested property is not supported', property_id=None)`

Bases: NotSupportedException

Python equivalent of C# PropertyNotSupportedException; carries the offending property_id.

Initialise the exception.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error description.	`'The requested property is not supported'`
`property_id`	`Optional[Any]`	The C# `PropertyId` that is not supported, when known.	`None`

Source code in flaui/lib/exceptions.py

def __init__(
    self, message: str = "The requested property is not supported", property_id: Optional[Any] = None
) -> None:
    """Initialise the exception.

    :param message: Human-readable error description.
    :param property_id: The C# ``PropertyId`` that is not supported, when known.
    """
    self.property_id = property_id
    super().__init__(message)

`ProxyAssemblyNotLoadedException(message='Proxy assembly not loaded')`

Bases: FlaUIException

Python equivalent of C# ProxyAssemblyNotLoadedException (the UIA proxy assembly is missing).

Initialise the exception.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error description.	`'Proxy assembly not loaded'`

Source code in flaui/lib/exceptions.py

def __init__(self, message: str = "Proxy assembly not loaded") -> None:
    """Initialise the exception.

    :param message: Human-readable error description.
    """
    super().__init__(message)

`SystemException(message='System exception')`

Bases: Exception

Wraps a raw C# System.Exception that is not a FlaUI error (kept outside the FlaUIException tree).

Initialise the exception.

Parameters:

Name	Type	Description	Default
`message`	`str`	Human-readable error description.	`'System exception'`

Source code in flaui/lib/exceptions.py

def __init__(self, message: str = "System exception") -> None:
    """Initialise the exception.

    :param message: Human-readable error description.
    """
    self.message = message
    super().__init__(self.message)

`handle_csharp_exceptions(func)`

Wrap a function so C# FlaUI exceptions are re-raised as their Python equivalents.

The C# exception text is preserved in the re-raised message, and the offending PropertyId/PatternId is forwarded to property_id/pattern_id where available. except clauses are ordered most-derived first so subclasses are not swallowed by their base.

Parameters:

Name	Type	Description	Default
`func`		The function to wrap.	required

Returns:

Type	Description
	The wrapped function.

Raises:

Type	Description
`PropertyNotSupportedException`	When the C# call raises `PropertyNotSupportedException`.
`PatternNotSupportedException`	When the C# call raises `PatternNotSupportedException`.
`NotSupportedException`	When the C# call raises `NotSupportedException`.
`PropertyNotCachedException`	When the C# call raises `PropertyNotCachedException`.
`PatternNotCachedException`	When the C# call raises `PatternNotCachedException`.
`NotCachedException`	When the C# call raises `NotCachedException`.
`NotSupportedByFrameworkException`	When the C# call raises `NotSupportedByFrameworkException`.
`ProxyAssemblyNotLoadedException`	When the C# call raises `ProxyAssemblyNotLoadedException`.
`NoClickablePointException`	When the C# call raises `NoClickablePointException`.
`MethodNotSupportedException`	When the C# call raises `MethodNotSupportedException`.
`ElementNotEnabledException`	When the C# call raises `ElementNotEnabledException`.
`ElementNotAvailableException`	When the C# call raises `ElementNotAvailableException`.
`FlaUIException`	When the C# call raises any other `FlaUIException`.
`SystemException`	When the C# call raises a non-FlaUI `System.Exception`.

Source code in flaui/lib/exceptions.py

def handle_csharp_exceptions(func):
    """Wrap a function so C# FlaUI exceptions are re-raised as their Python equivalents.

    The C# exception text is preserved in the re-raised message, and the offending
    ``PropertyId``/``PatternId`` is forwarded to ``property_id``/``pattern_id`` where available.
    ``except`` clauses are ordered most-derived first so subclasses are not swallowed by their base.

    :param func: The function to wrap.
    :return: The wrapped function.
    :raises PropertyNotSupportedException: When the C# call raises ``PropertyNotSupportedException``.
    :raises PatternNotSupportedException: When the C# call raises ``PatternNotSupportedException``.
    :raises NotSupportedException: When the C# call raises ``NotSupportedException``.
    :raises PropertyNotCachedException: When the C# call raises ``PropertyNotCachedException``.
    :raises PatternNotCachedException: When the C# call raises ``PatternNotCachedException``.
    :raises NotCachedException: When the C# call raises ``NotCachedException``.
    :raises NotSupportedByFrameworkException: When the C# call raises ``NotSupportedByFrameworkException``.
    :raises ProxyAssemblyNotLoadedException: When the C# call raises ``ProxyAssemblyNotLoadedException``.
    :raises NoClickablePointException: When the C# call raises ``NoClickablePointException``.
    :raises MethodNotSupportedException: When the C# call raises ``MethodNotSupportedException``.
    :raises ElementNotEnabledException: When the C# call raises ``ElementNotEnabledException``.
    :raises ElementNotAvailableException: When the C# call raises ``ElementNotAvailableException``.
    :raises FlaUIException: When the C# call raises any other ``FlaUIException``.
    :raises SystemException: When the C# call raises a non-FlaUI ``System.Exception``.
    """

    @wraps(func)
    def wrapper(*args, **kwargs) -> Any:
        """Invoke ``func`` and translate any C# exception into its Python equivalent."""
        try:
            return func(*args, **kwargs)
        except System.Exception as e:
            _raise_translated(e, func.__name__)

    return wrapper

`translate_exceptions(arg=None)`

Translate C# FlaUI exceptions into their Python equivalents (decorator or context manager).

This is the Pythonic, user-facing entry point. It supports three forms:

.. code-block:: python

# 1. Bare decorator
@translate_exceptions
def do_thing(): ...

# 2. Decorator with a context label
@translate_exceptions("clicking the button")
def click(): ...

# 3. Context manager around an arbitrary block of interop code
with translate_exceptions("reading the value"):
    value = element.raw_element.Value

Parameters:

Name	Type	Description	Default
`arg`	`Union[Callable[..., Any], str, None]`	When used as a bare decorator this is the wrapped function; when used as a context manager (or parametrized decorator) this is an optional human-readable context label.	`None`

Returns:

Type	Description
`Any`	The wrapped function (bare-decorator form) or a context manager that doubles as a parametrized decorator.

Source code in flaui/lib/exceptions.py

def translate_exceptions(arg: Union[Callable[..., Any], str, None] = None) -> Any:
    """Translate C# FlaUI exceptions into their Python equivalents (decorator or context manager).

    This is the Pythonic, user-facing entry point. It supports three forms:

    .. code-block:: python

        # 1. Bare decorator
        @translate_exceptions
        def do_thing(): ...

        # 2. Decorator with a context label
        @translate_exceptions("clicking the button")
        def click(): ...

        # 3. Context manager around an arbitrary block of interop code
        with translate_exceptions("reading the value"):
            value = element.raw_element.Value

    :param arg: When used as a bare decorator this is the wrapped function; when used as a context
        manager (or parametrized decorator) this is an optional human-readable context label.
    :return: The wrapped function (bare-decorator form) or a context manager that doubles as a
        parametrized decorator.
    """
    if callable(arg):
        # Form 1: used directly as @translate_exceptions
        return handle_csharp_exceptions(arg)
    # Forms 2 & 3: the contextmanager result is also usable as a decorator (ContextDecorator).
    return _translate_exceptions_block(arg or "operation")