Utility methods

Aiviro utility are additional constants, methods and classes which can be used as arguments for Search Objects or are return values in Robot’s methods.

aiviro.Area

class aiviro.Area(x_min: int, y_min: int, x_max: int, y_max: int)

Rectangular area defined in x and y axes.

Parameters:

x_min – Lower x-axis coordinate.
y_min – Lower y-axis coordinate.
x_min – Upper x-axis coordinate.
y_min – Upper y-axis coordinate.

Example:

>>> import aiviro
>>> r = aiviro.create_desktop_robot()
>>> r.add_mask(aiviro.Area(750, 850, 1100, 950))

class aiviro.BoundBox(x_min: int, y_min: int, x_max: int, y_max: int, label: AiviroCoreElementLabels = AiviroCoreElementLabels.DEFAULT, score: float = 0.0, extra: Dict | None = None)

Bounding box, object returned after finding an element.

Example:

>>> import aiviro
>>> r = aiviro.create_desktop_robot()
>>> box = r.get(
...     aiviro.Text(r"^\d\d\.\d\d\.\d\d\d\d$", aiviro.find_method.REGEX),
... )
>>> box.text
'13.11.2020'
>>> box.normalized_text
'13 . 11 . 2020'

>>> import aiviro
>>> r = aiviro.create_desktop_robot()
>>> or_box = r.get(
...     aiviro.Or(aiviro.Text("not-found"), aiviro.Text("found"))
... )
>>> or_box.or_index
1

aiviro.find_method

class aiviro.core.constants.ui_constants.FindMethod(value)

Different methods to process texts can be used with the alias aiviro.find_method.

Example:

>>> import aiviro
>>> aiviro.Button("Log in", aiviro.find_method.EQUAL)
>>> aiviro.Text(r"^\d\d$", aiviro.find_method.REGEX)
>>> aiviro.Button("OK", aiviro.find_method.EQUAL.CASE_INSENSITIVE)
>>> aiviro.Text(
...     "Total",
...     aiviro.find_method.EQUAL.EXCLUSIVE.CASE_INSENSITIVE
... )

>>> import aiviro
>>> from typing import Tuple
>>> def my_text_normalization(ocr_text: str) -> str:
...     return ocr_text.replace("O", "0")
...
>>> aiviro.user_config.text_normalization = my_text_normalization
>>> aiviro.Text(r"^\d+$", aiviro.find_method.REGEX.USER_NORMALIZATION)

EQUAL = 1: Comparison of text is based on equality. Texts have to be equal with every character to pass

SUBSTRING = 2: Comparison of text is based on substring equality. Text has to be equal to a substring with every character to pass

SIMILAR = 4: Comparison of text is based on their respective similarity. The texts can have minor changes and still pass.

REGEX = 8: Comparison of text is based on regular expression. Text has to exactly match the regular expression to pass.

CASE_INSENSITIVE = 16: Comparison of text is case-insensitive. This option is ignored for REGEX.

EXCLUSIVE = 32: Find elements that contain only the specified text and nothing else. Can be combined with any other comparison method.

GLOBAL = 64: Returns all occurences in line not only the first one.

USER_NORMALIZATION = 128: Apply user’s normalization for text. See UserConfig for more information. Can be combined with any other comparison method.

aiviro.table_anchor

class aiviro.core.utils.search_objects.TableAnchor(value)

Table anchors can be used with the alias aiviro.table_anchor. It defines which anchor of the element should be used for finding Above or Below elements.

Example:

>>> import aiviro
>>> aiviro.Below(
...     aiviro.Text(r'^\d\w\d$', aiviro.find_method.REGEX),
...     aiviro.Text("Column-header"),
...     aiviro.table_anchor.RIGHT
... )
>>> aiviro.Below(
...     aiviro.Text(""),
...     aiviro.Text("Records on the right"),
...     aiviro.table_anchor.RIGHT.THRESHOLD
... )
>>> aiviro.Below(
...     aiviro.RegexText(r"\d{8}"),
...     aiviro.Text("Customer No."),
...     aiviro.table_anchor.MIDDLE.DISTANCE
... )

LEFT = 1: The distance between the most left point of reference and other objects is calculated, based on x-axis, to find the closest elements.

RIGHT = 2: The distance between the most right points of reference and other objects is calculated, based on x-axis, to find the closest elements.

MIDDLE = 4: The distance between the middle point of reference and other objects is calculated, based on x-axis, to find the closest elements.

DISTANCE = 8: The distance option must be used with a LEFT, RIGHT, MIDDLE option, it calculates the distance between reference and other objects based on both axis.

THRESHOLD = 16: The threshold is applied for distance between reference and searching object, it finds strictly aligned objects, based on the selected anchor

NONE = 32: All elements Below or Above from reference object are found.

aiviro.layout_anchor

class aiviro.core.constants.ui_constants.LayoutAnchor(value)

Anchor positions can be used with the alias aiviro.layout_anchor.

Example:

>>> import aiviro
>>> r = aiviro.create_desktop_robot()
>>> r.check_are_in_column(  # elements are in column with alignment on the left
...     aiviro.Input("Username"),
...     aiviro.Input("Password"),
...     anchor=aiviro.layout_anchor.LEFT
... )

LEFT = 'LEFT': Use left points of bounding boxes as anchor points

RIGHT = 'RIGHT': Use right points of bounding boxes as anchor points

MIDDLE = 'MIDDLE': Use center points of bounding boxes as anchor points

TOP = 'TOP': Use top points of bounding boxes as anchor points

BOTTOM = 'BOTTOM': Use bottom points of bounding boxes as anchor points

BOTH = 'BOTH': Use both left and right or top and bottom points of bounding boxes as anchor points

aiviro.layout_positions

class aiviro.core.constants.ui_constants.LayoutPositions(value)

Layout positioning can be used with the alias aiviro.layout_positions.

IS_ABOVE = 0: Above a position

IS_BELOW = 1: Below a position

IS_RIGHT_OF = 2: Right of a position

IS_LEFT_OF = 3: Left of a position

aiviro.layout_comparison_mode

class aiviro.core.constants.ui_constants.LayoutComparisonMode(value)

Layout comparison modes can be used with the alias aiviro.layout_comparison_mode.

Example:

>>> import aiviro
>>> r = aiviro.create_desktop_robot()
>>> r.check_is_positioned(  # the whole Button object is below Input field
...     aiviro.Button("Log in"),
...     aiviro.Input("Username"),
...     direction_type=aiviro.layout_positions.IS_BELOW,
...     comparison_mode=aiviro.layout_comparison_mode.WHOLE
... )

WHOLE = 'COMPARISON_WHOLE': The entire area is strictly in the specified direction from given object

CENTER = 'COMPARISON_CENTER': The center is in specified direction from the center of the given object

EXTREME = 'COMPARISON_EXTREME': there is at least one pixel in the specified direction from the given object

aiviro.scroll_option

class aiviro.core.constants.ui_constants.ScrollOption(value)

Layout positioning can be used with the alias aiviro.scroll_option.

MOUSE_UP = 'up': Scroll with the mouse up

MOUSE_DOWN = 'down': Scroll with the mouse down

PAGE_UP = 'page_up': Use page up as a scroll

PAGE_DOWN = 'page_down': Use page down as a scroll

aiviro.boundary_type

class aiviro.core.constants.ui_constants.BoundaryType(value)

Can be used with the alias aiviro.boundary_type.

Example:

>>> import aiviro
>>> r = aiviro.create_desktop_robot()
>>> r.set_working_area(aiviro.BoundaryArea(
...     aiviro.Button("Login"),
...     aiviro.Button("Cancel"),
...     aiviro.boundary_type.DEFAULT
... ))
>>> r.add_mask(aiviro.BoundaryArea(
...     aiviro.Button("Login"),
...     aiviro.Button("Cancel"),
...     aiviro.boundary_type.EXCLUDE_FIRST.RIGHT_EDGE
... ))

DEFAULT = 1: Both boundaries included into the resulting box

RIGHT_EDGE = 2: Expand right side to the edge of the display

TOP_EDGE = 4: Expand top side to the edge of the display

BOTTOM_EDGE = 8: Expand bottom side to the edge of the display

LEFT_EDGE = 16: Expand left side to the edge of the display

EXCLUDE_FIRST_WIDTH = 32: Exclude width of the first boundary (uses right side of the boundary instead of left)

EXCLUDE_FIRST_HEIGHT = 64: Exclude height of the first boundary (uses bottom side of the boundary instead of top)

EXCLUDE_SECOND_WIDTH = 128: Exclude width of the second boundary (uses left side of the boundary instead of right)

EXCLUDE_SECOND_HEIGHT = 256: Exclude height of the second boundary (uses top side of the boundary instead of bottom)

TOP_LEFT_CORNER = 20: Expand boundary to the top left corner of the screen

TOP_RIGHT_CORNER = 6: Expand boundary to the top right corner of the screen

BOTTOM_LEFT_CORNER = 24: Expand boundary to the bottom left corner of the screen

BOTTOM_RIGHT_CORNER = 10: Expand boundary to the bottom right corner of the screen

BOTH_WIDTH = 18: Expand boundary to both vertical sides of the screen

BOTH_HEIGHT = 12: Expand boundary to both horizontal sides of the screen

EXCLUDE_FIRST = 96: Exclude the whole first boundary

EXCLUDE_SECOND = 384: Exclude the whole second boundary

EXCLUDE_BOTH_WIDTH = 160: Exclude width of both boundaries

EXCLUDE_BOTH_HEIGHT = 320: Exclude height of both boundaries

EXCLUDE_BOTH = 480: Exclude both boundaries

aiviro.working_area_limit

class aiviro.core.constants.ui_constants.WorkingAreaLimit(value)

Can be used with the alias aiviro.working_area_limit.

Example:

>>> import aiviro
>>> r = aiviro.create_desktop_robot()
>>> # set some working-area
>>> r.limit_working_area(
...     aiviro.Text("Cancel"),
...     top=aiviro.working_area_limit.MIN,
...     right=aiviro.working_area_limit.MAX
... )
>>> # set another working-area
>>> r.limit_working_area(
...     aiviro.Text("Cancel"),
...     bottom=aiviro.working_area_limit.MAX,
...     right=aiviro.working_area_limit.MIN
... )

MIN = 'min': Use MIN option for selected axis

MAX = 'max': Use MAX option for selected axis

aiviro.key

class aiviro.core.services.device.keyboard.BaseKey(value)

can be used with the alias aiviro.key.

ESCAPE = ('escape',)

F1 = ('f1',)

F2 = ('f2',)

F3 = ('f3',)

F4 = ('f4',)

F5 = ('f5',)

F6 = ('f6',)

F7 = ('f7',)

F8 = ('f8',)

F9 = ('f9',)

F10 = ('f10',)

F11 = ('f11',)

F12 = ('f12',)

GRAVE = ('`',)

KEY_1 = ('1',)

KEY_2 = ('2',)

KEY_3 = ('3',)

KEY_4 = ('4',)

KEY_5 = ('5',)

KEY_6 = ('6',)

KEY_7 = ('7',)

KEY_8 = ('8',)

KEY_9 = ('9',)

KEY_0 = ('0',)

MINUS = ('-',)

EQUAL = ('=',)

DOUBLE_HYPHEN = ('=',)

BACKSPACE = ('\x08',)

TAB = ('\t',)

KEY_Q = ('q',)

KEY_W = ('w',)

KEY_E = ('e',)

KEY_R = ('r',)

KEY_T = ('t',)

KEY_Y = ('y',)

KEY_U = ('u',)

KEY_I = ('i',)

KEY_O = ('o',)

KEY_P = ('p',)

LEFT_SQUARE_BRACKET = ('[',)

RIGHT_SQUARE_BRACKET = (']',)

ENTER = ('enter',)

CAPS_LOCK = ('capslock',)

KEY_A = ('a',)

KEY_S = ('s',)

KEY_D = ('d',)

KEY_F = ('f',)

KEY_G = ('g',)

KEY_H = ('h',)

KEY_J = ('j',)

KEY_K = ('k',)

KEY_L = ('l',)

SEMICOLON = (';',)

APOSTROPHE = ("'",)

LEFT_SHIFT = ('shiftleft',)

KEY_Z = ('z',)

KEY_X = ('x',)

KEY_C = ('c',)

KEY_V = ('v',)

KEY_B = ('b',)

KEY_N = ('n',)

KEY_M = ('m',)

COMMA = (',',)

PERIOD = ('.',)

SLASH = ('/',)

RIGHT_SHIFT = ('shiftright',)

BACKSLASH = ('\\',)

LEFT_CONTROL = ('ctrlleft',)

LEFT_WINDOW = ('winleft',)

LEFT_ALT = ('altleft',)

SPACE = (' ',)

RIGHT_ALT = ('altright',)

MENU = ('menu',)

RIGHT_WINDOW = ('winright',)

RIGHT_CONTROL = ('ctrlright',)

INSERT = ('insert',)

DELETE = ('delete',)

HOME = ('home',)

END = ('end',)

PAGE_UP = ('pageup',)

PAGE_DOWN = ('pagedown',)

LEFT_ARROW = ('left',)

RIGHT_ARROW = ('right',)

UP_ARROW = ('up',)

DOWN_ARROW = ('down',)

NUMPAD_0 = ('kp0',)

NUMPAD_1 = ('kp1',)

NUMPAD_2 = ('kp2',)

NUMPAD_3 = ('kp3',)

NUMPAD_4 = ('kp4',)

NUMPAD_5 = ('kp5',)

NUMPAD_6 = ('kp6',)

NUMPAD_7 = ('kp7',)

NUMPAD_8 = ('kp8',)

NUMPAD_9 = ('kp9',)

NUMPAD_DECIMAL = ('kp.',)

NUMPAD_DIVIDE = ('kp/',)

NUMPAD_ASTERISK = ('kp*',)

NUMPAD_MINUS = ('kp-',)

NUMPAD_PLUS = ('kp+',)

NUMPAD_ENTER = ('kpenter',)

aiviro.init_logging

logging.init_logging(config_file: GlobalConfig | None = None) → LoggingContext

Initialize Aiviro logging.

Returns:: LoggingContext instance, which can be used to add additional handlers
Example:

>>> import aiviro
>>> if __name__ == "__main__":
>>>     aiviro.init_logging()
>>>     # some code

>>> import aiviro
>>> from typing import List
>>> from logging import StreamHandler, DEBUG, Filter, LogRecord
>>>
>>> class LoggerNameFilter(Filter):
...     def __init__(self, loggers_name: List[str]):
...         super().__init__()
...         self._loggers_name = loggers_name
...
...     def filter(self, record: LogRecord) -> bool:
...         return record.name in self._loggers_name
...
>>> if __name__ == "__main__":
>>>     log_ctx = aiviro.init_logging()
>>>
>>>     # you can add additional handlers, for example
>>>     # this handler will print only logs from specified loggers to stdout
>>>     stdout_handler = StreamHandler(stream=sys.stdout)
>>>     stdout_handler.setLevel(DEBUG)
>>>     stdout_handler.addFilter(
...         LoggerNameFilter([
...             "aiviro.module.pdf.robot",
...             "aiviro.core.find.GetElements",
...             "aiviro.core.services.SearchObjectService",
...         ])
...     )
>>>     log_ctx.base_logger.addHandler(stdout_handler)

aiviro.log_prefect_markdown_text

logging.log_prefect_markdown_text() → None

Method will add text in Markdown format into prefect artifact.

Example:

>>> import aiviro
>>> md_text = "## Title\nLooooong text"
>>> aiviro.log_prefect_markdown_text(md_text)

aiviro.Secret

class aiviro.core.utils.secret.Secret(value: str | Secret)

Holds a string value that should not be revealed in logs, tracebacks, etc. To retrieve the value use the str() function.

Example:

>>> Secret("some string")
Secret('********')
>>> str(Secret("some string"))
some string

Note

If you use print() (or its variants) directly with this object it is automatically cast to str(), so it will display the secret value. Use cast repr() to avoid this functionality.

aiviro.exceptions

Every exception can be access by aiviro.*Error notation.

>>> import aiviro
>>> try:
...     # some code
>>> except aiviro.CheckCommandError:
...     # process exception

exception aiviro.core.utils.exceptions.SearchObjectError

exception aiviro.core.utils.exceptions.CheckCommandError

exception aiviro.core.utils.exceptions.TooManyElementsError

exception aiviro.core.utils.exceptions.ElementIndexError

exception aiviro.core.utils.exceptions.ReferenceElementError

exception aiviro.core.utils.exceptions.AndElementError

exception aiviro.core.utils.exceptions.WorkingAreaError

exception aiviro.core.utils.exceptions.ScreenNotStableError

exception aiviro.core.utils.exceptions.ScrollEndException

exception aiviro.core.utils.exceptions.ImageNotSetError

exception aiviro.core.utils.exceptions.BoundaryElementError

aiviro.constants

Every constant can be access by aiviro.* notation.

>>> import aiviro
>>> DB_NAME = "production" if aiviro.AIVIRO_DEBUG_VALUE else "testing"

aiviro.core.constants.utils_constants.AIVIRO_DEBUG_KEY = 'AIVIRO_DEBUG': The name of the environment variable that indicates whether the debug mode is on or off.

aiviro.core.constants.utils_constants.AIVIRO_DEBUG_VALUE = 1: The integer value that indicates whether the debug mode is on or off.

aiviro.core.constants.utils_constants.IS_RUNNING_IN_PREFECT = False: The boolean value that indicates whether script is running in Prefect environment.

aiviro.core.constants.utils_constants.SCENARIO_CONFIG_FOLDER_KEY = 'AIVIRO__CONFIG_FOLDER': The name of the environment variable that indicates the path to the scenario configuration folder.

aiviro.core.constants.utils_constants.SCENARIO_CONFIG_FOLDER_PATH = None: The path to the folder containing the scenario configuration files.