Create Robot

A robot is a basic unit that allows us to create automation. We provide several types of robots that can automate different applications.

aiviro.core.robots.robot_factory.create_web_robot(headless: bool = False, resolution: tuple[int, int] = (1920, 1080), scale_factor: float = 1.0, additional_args: list[str] | None = None, keep_alive: bool = False, page_load_strategy: str = 'normal', pause: bool = False, webdriver_path: Path | str | None = None, webdriver_type: Literal['chrome', 'firefox', 'edge', 'safari'] = 'chrome') → WebRobot

Creates a robot for web applications.

Parameters:

headless – If it’s True, web-driver runs in headless mode
resolution – Only used for headless mode, set the resolution of the web-driver window
scale_factor – Scale factor of display
additional_args – Additional argument for web-driver
keep_alive – Don’t close the web-driver window after the script ends. Useful when chaining Aiviro with Selenium.
page_load_strategy – Web-driver page load strategy, supported values are “normal”, “eager”, “none”
pause – If True, robot will be paused, to use it you’ll have to call unpause method
webdriver_path – Path to the web-driver executable, it overrides the setting from the global configuration
webdriver_type – Type of the web-driver to use, supported values are “chrome”, “firefox”, “edge”, “safari”

Returns:

WebRobot

Example:

>>> import aiviro
>>> r = aiviro.create_web_robot()
... # creates headless web-robot
>>> r_headless = aiviro.create_web_robot(headless=True)

aiviro.core.robots.robot_factory.create_static_robot() → StaticRobot

Creates a static noninteractable robot.

Returns:: StaticRobot
Example:

>>> import aiviro
>>> from aiviro.core.utils import file_utils
>>> img = file_utils.load_image("path/to/image.png")
>>> r = aiviro.create_static_robot()
>>> box = r.get(aiviro.Text("some-text"), screen=img)

aiviro.core.robots.robot_factory.create_desktop_robot(display_id: int = 1, pause: bool = False) → DesktopRobot

Creates a robot for desktop applications.

Parameters:

display_id – Identifier to which display to connect
pause – If True, robot will be paused, to use it you’ll have to call unpause method

Returns:

DesktopRobot

Example:

>>> import aiviro
>>> r = aiviro.create_desktop_robot()

aiviro.core.robots.robot_factory.create_rdp_robot_v2(*, server: Connection | str | Path, shared_folder: SharedFolder | None = None, gateway: Connection | None = None, enable_auto_reconnect: bool = True, enable_unicode: bool = True, pause: bool = False, options: list[str] | None = None) → RDPRobot

Creates a robot for desktop applications connected remotely via RDP protocol.

Note

It’s required to install rdp from Optional dependencies section.

Parameters:

server – Connection settings to the remote computer you want to connect to. If a string or pathlib.Path is passed, it will be treated as a rdp connection file.
shared_folder – Shared folder settings for the remote computer
gateway – Gateway settings for the remote computer. Requires pyfreerdp 4.0+.
enable_auto_reconnect – Enables robot to auto-reconnect to the remote PC when a network issue occurs.
enable_unicode – Enables Unicode keyboard inputs. Default is True, it adds “/kbd:unicode:on” option.
pause – If True, robot will be paused, to use it you’ll have to call unpause method
options – Additional options passed to the xfreerdp command

Note

By default, xfreerdp is using /network:auto option, it adapts based on the network connection. But if you’re experiencing lag or degraded visual quality, try to add additional options as:

-wallpaper - disables wallpaper
/network:lan - high bandwidth usage and low latency, minimal compression, the best visual quality
/network:modem - minimal bandwidth usage and high latency, maximum compression

For more options check out the official documentation of xfreerdp .

Returns:: RDPRobot
Example:

>>> import aiviro
>>> r1 = aiviro.create_rdp_robot_v2(
...     server=aiviro.RDPDeviceSpecsV2.Connection(
...         host="<ip-address>",
...         username="<username>",
...         password="<password>",
...         domain="<domain>"
...     )
... )

>>> # Using robot with shared folder:
>>> r2 = aiviro.create_rdp_robot_v2(
...     server=aiviro.RDPDeviceSpecsV2.Connection(
...         host="<ip-address>",
...         username="<username>",
...         password="<password>",
...         domain="<domain>"
...     ),
...     shared_folder=aiviro.RDPDeviceSpecsV2.SharedFolder(
...         path=r"c:\path\dir\sub-dir"
...     )
... )
>>> # The above folder appears on the RDP machine as "\\tsclient\sub-dir"

>>> # Using robot with shared, renamed folder:
>>> r3 = aiviro.create_rdp_robot_v2(
...     server=aiviro.RDPDeviceSpecsV2.Connection(
...         host="<ip-address>",
...         username="<username>",
...         password="<password>",
...         domain="<domain>"
...     ),
...     shared_folder=aiviro.RDPDeviceSpecsV2.SharedFolder(
...         path=r"c:\path",
...         alias="my_name"
...     )
... )
>>> # The above folder appears on the RDP machine as "\\tsclient\my_name"

Creates a robot for desktop applications connected remotely via RDP protocol.

Warning

This method is deprecated and will be removed in the next major version. Use create_rdp_robot_v2() instead.

Note

It’s required to install rdp from Optional dependencies section.

Parameters:

remote_address – Address of the remote computer you want to connect to
username – Username of the computer
password – Password of the computer
domain – Domain name of which the username is part of. Use “.” for local users
port – Optional port to RDP server.
auto_reconnect – Enables robot to auto-reconnect to the remote PC when a network issue occurs. pyfreerdp 3+
shared_folder – Maps local folder to the remote machine. pyfreerdp 3+. Folder can be renamed on the remote machine by passing a tuple of (path, name). If the folder doesn’t exist, it will be created, but not its parents.
pause – If True, robot will be paused, to use it you’ll have to call unpause method

Returns:

RDPRobot

Example:

>>> import aiviro
>>> r1 = aiviro.create_rdp_robot(
...     "<ip-address>",
...     "<username>",
...     "<password>",
...     "<domain>"
... )

>>> # Using robot with shared folder:
>>> r2 = aiviro.create_rdp_robot(
...     "<ip-address>",
...     "<username>",
...     "<password>",
...     "<domain>",
...     shared_folder=r"c:\path\dir\sub-dir"
... )
>>> # The above folder appears on the RDP machine as "\\tsclient\sub-dir"

>>> # Using robot with shared, renamed folder:
>>> r3 = aiviro.create_rdp_robot(
...     "<ip-address>",
...     "<username>",
...     "<password>",
...     "<domain>",
...     shared_folder=(r"c:\path", "my_name")
... )
>>> # The above folder appears on the RDP machine as "\\tsclient\my_name"

aiviro.core.robots.robot_factory.create_env_robot(env_variable_name: str = 'AIVIRO_ROBOT_ENV') → DesktopRobot | WebRobot | RDPRobot

Creates a robot using data from environment variable.

Parameters:: env_variable_name – Name of the environment variable to use
Returns:: The instance of DesktopRobot, WebRobot or RDPRobot
Example:

{
    "robot_type": "rdp",
    "remote_address": "192.169.10.22",
    "username": "username",
    "password": "password",
    "domain": ".",
}

>>> # set-up value of the environment variable 'AIVIRO_ROBOT_ENV' based on the json-example above
>>> import aiviro
... # it creates rdo-robot
>>> r = aiviro.create_env_robot()

Create a noninteractable robot, which is primarily used for reading and parsing PDF files.

Note

It’s required to install pdf from Optional dependencies section.

Parameters:

pdf_path – Path or list of paths to a PDF file(s) this robot should read
pdf_convert_timeout – Timeout for reading PDF file. For more complex PDF files higher timeout should be used
dpi – Display resolution of pages from PDF
poppler_path – Path to poppler application. Can be ommited if poppler is included in PATH system variable
only_digital – If True, only PDF files which can be read digitally are processed. Files where OCR would have to be used are skipped

Raises:

FileNotFoundError – If the path doesn’t exist or points to a directory
TypeError – If the PDF file cannot be read successfully. In most cases non PDF file is in path

Returns:

PDFRobot or MultiPDFRobot

Example:

>>> from aiviro.modules.pdf import create_pdf_robot
>>> # returns PDFRobot, loads only one file
>>> r = create_pdf_robot().parse("path/to/file.pdf", skip_chars=["_"])

>>> # returns MultiPDFRobot, loads several files at once
>>> r = create_pdf_robot(
...     [
...         "path/to/pdf_1.pdf"
...         "path/to/pdf_2.pdf"
...         "path/to/pdf_3.pdf"
...         "path/to/pdf_4.pdf"
...     ]
... )
>>> r.add_file("path/to/pdf_5.pdf", skip_chars=["_"])  # parse additional file