Aiviro Utils

Aiviro utils are additional constants, methods and objects 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: aiviro.core.constants.ui_constants.AiviroCoreElementLabels = AiviroCoreElementLabels.DEFAULT, score: float = 0.0, extra: Optional[Dict] = 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: int)

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 = FindMethod.EQUAL

Comparison of text is based on equality. Texts have to be equal with every character to pass

SUBSTRING = FindMethod.SUBSTRING

Comparison of text is based on substring equality. Text has to be equal to a substring with every character to pass

SIMILAR = FindMethod.SIMILAR

Comparison of text is based on their respective similarity. The texts can have minor changes and still pass.

REGEX = FindMethod.REGEX

Comparison of text is based on regular expression. Text has to exactly match the regular expression to pass.

CASE_INSENSITIVE = FindMethod.CASE_INSENSITIVE

Comparison of text is case-insensitive. This option is ignored for REGEX.

EXCLUSIVE = FindMethod.EXCLUSIVE

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

GLOBAL = FindMethod.GLOBAL

Returns all occurences in line not only the first one.

USER_NORMALIZATION = FindMethod.USER_NORMALIZATION

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: int)

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 = TableAnchor.LEFT

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

RIGHT = TableAnchor.RIGHT

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

MIDDLE = TableAnchor.MIDDLE

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

DISTANCE = TableAnchor.DISTANCE

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 = TableAnchor.THRESHOLD

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

NONE = TableAnchor.NONE

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: int)

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 = BoundaryType.DEFAULT

Both boundaries included into the resulting box

RIGHT_EDGE = BoundaryType.RIGHT_EDGE

Expand right side to the edge of the display

TOP_EDGE = BoundaryType.TOP_EDGE

Expand top side to the edge of the display

BOTTOM_EDGE = BoundaryType.BOTTOM_EDGE

Expand bottom side to the edge of the display

LEFT_EDGE = BoundaryType.LEFT_EDGE

Expand left side to the edge of the display

EXCLUDE_FIRST_WIDTH = BoundaryType.EXCLUDE_FIRST_WIDTH

Exclude width of the first boundary (uses right side of the boundary instead of left)

EXCLUDE_FIRST_HEIGHT = BoundaryType.EXCLUDE_FIRST_HEIGHT

Exclude height of the first boundary (uses bottom side of the boundary instead of top)

EXCLUDE_SECOND_WIDTH = BoundaryType.EXCLUDE_SECOND_WIDTH

Exclude width of the second boundary (uses left side of the boundary instead of right)

EXCLUDE_SECOND_HEIGHT = BoundaryType.EXCLUDE_SECOND_HEIGHT

Exclude height of the second boundary (uses top side of the boundary instead of bottom)

TOP_LEFT_CORNER = BoundaryType.TOP_LEFT_CORNER

Expand boundary to the top left corner of the screen

TOP_RIGHT_CORNER = BoundaryType.TOP_RIGHT_CORNER

Expand boundary to the top right corner of the screen

BOTTOM_LEFT_CORNER = BoundaryType.BOTTOM_LEFT_CORNER

Expand boundary to the bottom left corner of the screen

BOTTOM_RIGHT_CORNER = BoundaryType.BOTTOM_RIGHT_CORNER

Expand boundary to the bottom right corner of the screen

BOTH_WIDTH = BoundaryType.BOTH_WIDTH

Expand boundary to both vertical sides of the screen

BOTH_HEIGHT = BoundaryType.BOTH_HEIGHT

Expand boundary to both horizontal sides of the screen

EXCLUDE_FIRST = BoundaryType.EXCLUDE_FIRST

Exclude the whole first boundary

EXCLUDE_SECOND = BoundaryType.EXCLUDE_SECOND

Exclude the whole second boundary

EXCLUDE_BOTH_WIDTH = BoundaryType.EXCLUDE_BOTH_WIDTH

Exclude width of both boundaries

EXCLUDE_BOTH_HEIGHT = BoundaryType.EXCLUDE_BOTH_HEIGHT

Exclude height of both boundaries

EXCLUDE_BOTH = BoundaryType.EXCLUDE_BOTH

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: str)

can be used with the alias aiviro.key.

ESCAPE = BaseKey.escape
F1 = BaseKey.f1
F2 = BaseKey.f2
F3 = BaseKey.f3
F4 = BaseKey.f4
F5 = BaseKey.f5
F6 = BaseKey.f6
F7 = BaseKey.f7
F8 = BaseKey.f8
F9 = BaseKey.f9
F10 = BaseKey.f10
F11 = BaseKey.f11
F12 = BaseKey.f12
GRAVE = BaseKey.`
KEY_1 = BaseKey.1
KEY_2 = BaseKey.2
KEY_3 = BaseKey.3
KEY_4 = BaseKey.4
KEY_5 = BaseKey.5
KEY_6 = BaseKey.6
KEY_7 = BaseKey.7
KEY_8 = BaseKey.8
KEY_9 = BaseKey.9
KEY_0 = BaseKey.0
MINUS = BaseKey.-
EQUAL = BaseKey.=
DOUBLE_HYPHEN = BaseKey.=
BACKSPACE = BaseKey.
TAB = BaseKey.
KEY_Q = BaseKey.q
KEY_W = BaseKey.w
KEY_E = BaseKey.e
KEY_R = BaseKey.r
KEY_T = BaseKey.t
KEY_Y = BaseKey.y
KEY_U = BaseKey.u
KEY_I = BaseKey.i
KEY_O = BaseKey.o
KEY_P = BaseKey.p
LEFT_SQUARE_BRACKET = BaseKey.[
RIGHT_SQUARE_BRACKET = BaseKey.]
ENTER = BaseKey.enter
CAPS_LOCK = BaseKey.capslock
KEY_A = BaseKey.a
KEY_S = BaseKey.s
KEY_D = BaseKey.d
KEY_F = BaseKey.f
KEY_G = BaseKey.g
KEY_H = BaseKey.h
KEY_J = BaseKey.j
KEY_K = BaseKey.k
KEY_L = BaseKey.l
SEMICOLON = BaseKey.;
APOSTROPHE = BaseKey.'
LEFT_SHIFT = BaseKey.shiftleft
KEY_Z = BaseKey.z
KEY_X = BaseKey.x
KEY_C = BaseKey.c
KEY_V = BaseKey.v
KEY_B = BaseKey.b
KEY_N = BaseKey.n
KEY_M = BaseKey.m
COMMA = BaseKey.,
PERIOD = BaseKey..
SLASH = BaseKey./
RIGHT_SHIFT = BaseKey.shiftright
BACKSLASH = BaseKey.\
LEFT_CONTROL = BaseKey.ctrlleft
LEFT_WINDOW = BaseKey.winleft
LEFT_ALT = BaseKey.altleft
SPACE = BaseKey.
RIGHT_ALT = BaseKey.altright
MENU = BaseKey.menu
RIGHT_WINDOW = BaseKey.winright
RIGHT_CONTROL = BaseKey.ctrlright
INSERT = BaseKey.insert
DELETE = BaseKey.delete
HOME = BaseKey.home
END = BaseKey.end
PAGE_UP = BaseKey.pageup
PAGE_DOWN = BaseKey.pagedown
LEFT_ARROW = BaseKey.left
RIGHT_ARROW = BaseKey.right
UP_ARROW = BaseKey.up
DOWN_ARROW = BaseKey.down
NUMPAD_0 = BaseKey.kp0
NUMPAD_1 = BaseKey.kp1
NUMPAD_2 = BaseKey.kp2
NUMPAD_3 = BaseKey.kp3
NUMPAD_4 = BaseKey.kp4
NUMPAD_5 = BaseKey.kp5
NUMPAD_6 = BaseKey.kp6
NUMPAD_7 = BaseKey.kp7
NUMPAD_8 = BaseKey.kp8
NUMPAD_9 = BaseKey.kp9
NUMPAD_DECIMAL = BaseKey.kp.
NUMPAD_DIVIDE = BaseKey.kp/
NUMPAD_ASTERISK = BaseKey.kp*
NUMPAD_MINUS = BaseKey.kp-
NUMPAD_PLUS = BaseKey.kp+
NUMPAD_ENTER = BaseKey.kpenter

aiviro.init_logging

logging.init_logging() None

Initialize Aiviro logging

Example

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

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: Union[str, aiviro.core.utils.secret.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