Python API

Windows

exception RPA.Desktop.Windows.ElementNotFoundError

Bases: Exception

Raised when expected element is not found

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception RPA.Desktop.Windows.MenuItemNotFoundError

Bases: Exception

Raised when expected menu item is not found

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception RPA.Desktop.Windows.UnknownWindowsBackendError

Bases: Exception

Raised when unknown Windows backend is set

args
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class RPA.Desktop.Windows.Windows(backend: str = 'uia')

Bases: RPA.Desktop.OperatingSystem.OperatingSystem

Windows is a library for managing the Windows operating system.

Running Windows applications

Windows applications can be started in several ways. The library supports the following keywords:

  • Open Application (dispatch Office applications)

  • Open File (open the file as process which opens the associated application)

  • Open Executable (uses pywinauto start)

  • Open Using Run Dialog (uses Windows run dialog)

  • Open From Search (uses Windows search dialog)

Locators

Locator is used to identify the element for interaction - usually for a mouse click.

Locators can investigated for application once it has been opened by calling the keyword get_windows_elements which can store locator information into JSON file and screenshot of the element into an image file.

Identifying locator

The element needs to be identified by a unique method, for example, “Three” for button 3 in the Calculator application. It can be given either as Three or name:Three.

Possible search criterias:

  • name

  • class (class_name)

  • type (control_type)

  • id (automation_id)

  • any if none was defined

The current method of inspecting elements on Windows is inspect.exe which is part of Windows SDK.

Keyboard

The keyword send_keys can be used to send keys to the active window. The keyword type_keys sends keys to the active window element.

Special key codes are documented on pywinauto documentation page.

FAQ

  1. I see error message AttributeError: module ‘win32com.gen_py.00020813-0000-0000-C000-000000000046x0x1x9’ has no attribute ‘CLSIDToClassMap’

  1. From PowerShell run this command: Remove-Item -path $env:LOCALAPPDATATempgen_py -recurse

Examples

Robot Framework

*** Settings ***
Library          RPA.Desktop.Windows
Suite Teardown   Close all applications

*** Tasks ***
Open Calculator using run dialog
    ${result}=              Open using run dialog    calc.exe   Calculator
    ${result}=              Get Window Elements
    Send Keys               5*2=
    ${result}=              Get element             partial name:Display is
    Log Many                ${result}
    ${result}=              Get element rich text   id:CalculatorResults
    Should Be Equal As Strings  ${result}  Display is 10
    ${result}=              Get element rectangle   partial name:Display is
    ${result}=              Is Element Visible      CalculatorResults
    ${result}=              Is Element Enabled      partial name:Display is

Python

from RPA.Desktop.Windows import Windows

win = Windows()

def open_calculator():
    win.open_from_search("calc.exe", "Calculator")
    elements = win.get_window_elements()

def make_calculations(expression):
    win.send_keys(expression)
    result = win.get_element_rich_text('id:CalculatorResults')
    return int(result.strip('Display is '))

if __name__ == "__main__":
    open_calculator()
    exp = '5*2='
    result = make_calculations(exp)
    print(f"Calculation result of '{exp}' is '{result}'")
    win.close_all_applications()
ROBOT_LIBRARY_DOC_FORMAT = 'REST'
ROBOT_LIBRARY_SCOPE = 'GLOBAL'
boot_time_in_seconds_from_epoch() → str

Get machine boot time

Returns

boot time in seconds from Epoch

Example:

${epoch}  Boot Time In Seconds From Epoch
calculate_rectangle_center(rectangle: Any) → Any

Calculate x and y center coordinates from rectangle.

Parameters

rectangle – element rectangle coordinates

Returns

x and y coordinates of rectangle center

Example:

Open Using Run Dialog   calc  Calculator
&{rect}=        Get Element Rectangle    CalculatorResults
${x}  ${y}=     Calculate Rectangle Center   ${rect}
click_type(x: int = None, y: int = None, click_type: str = 'click') → None

Mouse click on coordinates x and y.

Default click type is click meaning left

Parameters
  • x – horizontal coordinate for click, defaults to None

  • y – vertical coordinate for click, defaults to None

  • click_type – “click”, “right” or “double”, defaults to “click”

Raises

ValueError – if coordinates are not valid

Example:

Click Type  x=450  y=100
Click Type  x=450  y=100  click_type=right
Click Type  x=450  y=100  click_type=double
close_all_applications() → None

Close all applications

Example:

Open Application   Excel
Open Application   Word
Open Executable    notepad.exe   Untitled - Notepad
Close All Applications
connect_by_handle(handle: str, windowtitle: str = None, existing_app: bool = False) → Any

Connect to application by its handle

Parameters

handle – handle of the application

Example:

${appid}  Connect By Handle  88112
connect_by_pid(app_pid: str, windowtitle: str = None) → Any

Connect to application by its pid

Parameters

app_pid – process id of the application

Example:

${appid}  Connect By PID  3231
drag_and_drop(src: Any, target: Any, src_locator: str, target_locator: str = None, handle_ctrl_key: bool = False, drop_delay: float = 2.0) → None

Drag elements from source and drop them on target.

Please note that if CTRL is not pressed down during drag and drop then operation is MOVE operation, on CTRL down the operation is COPY operation.

There will be also overwrite notification if dropping over existing files.

Parameters
  • src – application object or instance id

  • target – application object or instance id

  • src_locator – elements to move

  • handle_ctrl_key – True if keyword should press CTRL down dragging

  • drop_delay – how many seconds to wait until releasing mouse drop, default 2.0

Raises

ValueError – on validation errors

Example:

${app1}=        Open Using Run Dialog    explorer.exe{VK_SPACE}C:\workfiles\movethese   movethese
${app2}=        Open Using Run Dialog    wordpad.exe   Document - WordPad
Drag And Drop   ${app1}   ${app2}   regexp:testfile_\d.txt  name:Rich Text Window   handle_ctrl_key=${True}
Drag And Drop   ${app1}   ${app1}   regexp:testfile_\d.txt  name:subdir  handle_ctrl_key=${True}
find_element(locator: str, search_criteria: str = None) → Any

Find element from window by locator and criteria.

Parameters
  • locator – name of the locator

  • search_criteria – criteria by which element is matched

Returns

list of matching elements and locators that were found on the window

Example:

@{elements}   Find Element   CalculatorResults
Log Many  ${elements[0]}     # list of matching elements
Log Many  ${elements[1]}     # list of all available locators
get_app(app_id: int = None) → Any

Get application object by id

By default returns active_application application object.

Parameters

app_id – id of the application to get, defaults to None

Returns

application object

Example:

${app1}        Open Application   Excel
&{appdetails}  Get App   ${app1}
get_boot_time(as_datetime: bool = False, datetime_format: str = '%Y-%m-%d %H:%M:%S') → str

Get computer boot time in seconds from Epoch or in datetime string.

Parameters
  • as_datetime – if True returns datetime string, otherwise seconds, defaults to False

  • datetime_format – datetime string format, defaults to “%Y-%m-%d %H:%M:%S”

Returns

seconds from Epoch or datetime string

Example:

${boottime}  Get Boot Time
${boottime}  Get Boot Time   as_datetime=True
${boottime}  Get Boot Time   as_datetime=True  datetime_format=%d.%m.%Y
get_dialog_rectangle(ctrl: Any = None, as_dict: bool = False) → Any

Get dialog rectangle coordinates

If ctrl is None then get coordinates from dialog :param ctrl: name of the window control object, defaults to None :return: coordinates: left, top, right, bottom

Example:

${left}  ${top}  ${right}  ${bottom}=  Get Dialog Rectangle
&{coords}  Get Dialog Rectangle  as_dict=True
Log  top=${coords.top} left=${coords.left}
get_element(locator: str, screenshot: bool = False, open_dialog: bool = True) → Any

Get element by locator.

Parameters
  • locator – name of the locator

  • screenshot – takes element screenshot if True, defaults to False

  • open_dialog – True if dialog should be reopened, default to True

Returns

element if element was identified, else False

Example:

${element}  Get Element  CalculatorResults
${element}  Get Element  Result      screenshot=True
get_element_center(element: dict) → Any

Get element center coordinates

Parameters

element – dictionary of element items

Returns

coordinates, x and y

Example:

@{element}   Find Element  CalculatorResults
${x}  ${y}=  Get Element Center  ${elements[0][0]}
get_element_rectangle(locator: str, as_dict: bool = False) → Any

Get value of element rectangle attribute.

Parameters
  • locator – element locator

  • as_dict – return values in a dictionary, default False

Returns

(left, top, right, bottom) values if found, else False

Example:

${left}  ${top}  ${right}  ${bottom}=  Get Element Rectangle  CalculatorResults
&{coords}  Get Element Rectangle  CalculatorResults  as_dict=True
Log  top=${coords.top} left=${coords.left}
get_element_rich_text(locator: str) → Any

Get value of element rich text attribute.

Parameters

locator – element locator

Returns

rich_text value if found, else False

Example:

${text}  Get Element Rich Text  CalculatorResults
get_machine_name() → str

Get machine name

Returns

machine name as string

Example:

${machine}  Get Machine Name
get_memory_stats(humanized: bool = True) → dict

Get computer memory stats and return those in bytes or in humanized memory format.

Parameters

humanized – if False returns memory information in bytes, defaults to True

Returns

memory information in dictionary format

Example:

&{mem}     Get Memory Stats
&{mem}     Get Memory Stats   humanized=False
get_open_applications()

Get list of all open applications

Returns a dictionary

Example:

${app1}    Open Application   Excel
${app2}    Open Executable    calc.exe  Calculator
${app3}    Open File          /path/to/myfile.txt
&{apps}    Get Open Applications
get_spaced_string(text)

Replace spaces in a text with pywinauto.keyboard space characters {VK_SPACE}

Parameters

text – replace spaces in this string

Example:

${txt}    Get Spaced String   My name is Bond
# ${txt} = My{VK_SPACE}name{VK_SPACE}is{VK_SPACE}Bond
get_text(locator: str) → dict

Get text from element

Parameters

locator – element locator

Example:

Open Using Run Dialog  calc     Calculator
Type Into    CalculatorResults   11
Type Into    CalculatorResults   55
&{val}       Get Text   CalculatorResults
get_username() → str

Get username of logged in user

Returns

username as string

Example:

${user}  Get Username
get_window_elements(screenshot: bool = False, element_json: bool = False, outline: bool = False) → Any

Get element information about all window dialog controls and their descendants.

Parameters
  • screenshot – save element screenshot if True, defaults to False

  • element_json – save element json if True, defaults to False

  • outline – highlight elements if True, defaults to False

Returns

all controls and all elements

Example:

@{elements}   Get Window Elements
Log Many      ${elements[0]}     # list of all available locators
Log Many      ${elements[1]}     # list of matching elements
@{elements}   Get Window Elements  screenshot=True  element_json=True  outline=True
get_window_list()

Get list of open windows

Window dictionaries contain:

  • automation_id

  • control_id

  • title

  • pid

  • handle

  • is_active

  • keyboard_focus

  • rectangle

Returns

list of window dictionaries

Example:

@{windows}    Get Window List
FOR  ${window}  IN  @{windows}
    Log Many  ${window}
END
is_element_enabled(locator: str) → bool

Is element enabled.

Parameters

locator – element locator

Returns

True if enabled, else False

Example:

${res}=   Is Element Enabled  CalculatorResults
is_element_matching(itemdict: dict, locator: str, criteria: str, wildcard: bool = False) → bool

Is element matching. Check if locator is found in any field or criteria field in the window items.

Parameters
  • itemDict – dictionary of element items

  • locator – name of the locator

  • criteria – criteria on which to match element

  • wildcard – whether to do reg exp match or not, default False

Returns

True if element is matching locator and criteria, False if not

is_element_visible(locator: str) → bool

Is element visible.

Parameters

locator – element locator

Returns

True if visible, else False

Example:

${res}=   Is Element Visible  CalculatorResults
kill_process(process_name: str) → bool

Kill process by name

Parameters

process_name – name of the process

Returns

True if succeeds False if not

Example:

${process}  Process Exists  calc  strict=False
${status}   Kill Process    ${process.name()}
kill_process_by_pid(pid: int) → None

Kill process by pid

Parameters

pid – process identifier

Example:

${process}  Process Exists  calc  strict=False
${status}   Kill Process    ${process.pid}
lock_screen() → None

Put windows into lock mode

Example:

Lock Screen
log_in(username: str, password: str, domain: str = '.') → str

Log into Windows domain with username and password.

Parameters
  • username – name of the user

  • password – password of the user

  • domain – windows domain for the user, defaults to “.”

Returns

handle

Example:

Log In  username=myname  password=mypassword  domain=company
menu_select(menuitem: str) → None

Select item from menu

Parameters

menuitem – name of the menu item

Example:

Open Using Run Dialog   notepad     Untitled - Notepad
Menu Select             File->Print
minimize_dialog(windowtitle: str = None) → None

Minimize window by its title

Parameters

windowtitle – name of the window, default None means that active window is going to be minimized

Example:

Open Using Run Dialog  calc     Calculator
Open Using Run Dialog  notepad  Untitled - Notepad
Minimize Dialog    # Current window (Notepad)
Minimize Dialog    Calculator
mouse_click(locator: str = None, x: int = 0, y: int = 0, off_x: int = 0, off_y: int = 0, image: str = None, method: str = 'locator', ctype: str = 'click', **kwargs) → None

Mouse click locator, coordinates, or image

When using method locator,`image` or ocr mouse is clicked by default at center coordinates.

Click types are:

  • click normal left button mouse click

  • double

  • right

Parameters
  • locator – element locator on active window

  • x – coordinate x on desktop

  • y – coordinate y on desktop

  • off_x – offset x (used for locator and image clicks)

  • off_y – offset y (used for locator and image clicks)

  • image – image to click on desktop

  • method – one of the available methods to mouse click, default “locator”

  • ctype – type of mouse click

  • kwargs – these keyword arguments can be used to pass arguments to underlying Images library to finetune image template matching, for example. tolerance=0.5 would adjust image tolerance for the image matching

Example:

Mouse Click  method=coordinates  100   100
Mouse Click  CalculatorResults
Mouse Click  method=image  image=myimage.png  off_x=10  off_y=10  ctype=right
Mouse Click  method=image  image=myimage.png  tolerance=0.8
${elements}  ${other}=     Find Element  class:Button
FOR  ${element}  IN  @{elements}
    Run Keyword If   ${element}[visible]   Mouse Click  ${element}
END
mouse_click_coords(x: int, y: int, ctype: str = 'click', delay_time: float = None) → None

Click at coordinates on desktop

Parameters
  • x – horizontal coordinate on the windows to click

  • y – vertical coordinate on the windows to click

  • ctype – click type “click”, “right” or “double”, defaults to “click”

  • delay – delay in seconds after, default is no delay

Example:

Mouse Click Coords  x=450  y=100
Mouse Click Coords  x=300  y=300  ctype=right
Mouse Click Coords  x=450  y=100  delay=5.0
mouse_click_image(template: str, off_x: int = 0, off_y: int = 0, ctype: str = 'click', **kwargs) → None

Click at template image on desktop

Parameters
  • image – image to click on desktop

  • off_x – horizontal offset from top left corner to click on

  • off_y – vertical offset from top left corner to click on

  • ctype – type of mouse click

  • kwargs – these keyword arguments can be used to pass arguments to underlying Images library to finetune image template matching, for example. tolerance=0.5 would adjust image tolerance for the image matching

Example:

Mouse Click  image=myimage.png  off_x=10  off_y=10  ctype=right
Mouse Click  image=myimage.png  tolerance=0.8
open_application(application: str) → int

Open application by dispatch method

This keyword is used to launch Microsoft applications like Excel, Word, Outlook and Powerpoint.

Parameters

application – name of the application as str

Returns

application instance id

Example:

${app1}    Open Application   Excel
${app2}    Open Application   Word
open_dialog(windowtitle: str = None, highlight: bool = False, timeout: int = 10, existing_app: bool = False) → Any

Open window by its title.

Parameters
  • windowtitle – name of the window, defaults to active window if None

  • highlight – draw outline for window if True, defaults to False

  • timeout – time to wait for dialog to appear

Example:

Open Dialog       Untitled - Notepad
Open Dialog       Untitled - Notepad   highlight=True   timeout=5
open_executable(executable: str, windowtitle: str, backend: str = None, work_dir: str = None) → int

Open Windows executable. Window title name is required to get handle on the application.

Parameters
  • executable – name of the executable

  • windowtitle – name of the window

  • backend – set Windows backend, default None means using library default value

  • work_dir – path to working directory, default None

Returns

application instance id

Example:

${app1}    Open Executable   calc.exe  Calculator
open_file(filename: str) → bool

Open associated application when opening file

Parameters

filename – path to file

Returns

True if application is opened, False if not

Example:

${app1}    Open File   /path/to/myfile.txt

Open application using Windows search dialog. Window title name is required to get handle on the application.

Parameters
  • executable – name of the executable

  • windowtitle – name of the window

  • timeout – time to wait for dialog to appear

Returns

application instance id

Example:

${app1}    Open From Search  calculator  Calculator
open_using_run_dialog(executable: str, windowtitle: str, timeout: int = 10) → int

Open application using Windows run dialog. Window title name is required to get handle on the application.

Parameters
  • executable – name of the executable

  • windowtitle – name of the window

  • timeout – time to wait for dialog to appear

Returns

application instance id

Example:

${app1}    Open Using Run Dialog  notepad  Untitled - Notepad
process_exists(process_name: str, strict: bool = True) → Any

Check if process exists by its name

Parameters
  • process_name – search for this process

  • strict – defines how match is made, default True which means that process name needs to be exact match and False does inclusive matching

Returns

process instance or False

Example:

${process}  Process Exists  calc
${process}  Process Exists  calc  strict=False
put_system_to_sleep() → None

Put Windows into sleep mode

Example:

Put System To Sleep
quit_application(app_id: str = None, send_keys: bool = False) → None

Quit an application by application id or active application if app_id is None.

Parameters

app_id – application_id, defaults to None

Example:

${app1}   Open Application   Excel
${app2}   Open Application   Word
Quit Application  ${app1}
restore_dialog(windowtitle: str = None) → None

Restore window by its title

Parameters

windowtitle – name of the window, default None means that active window is going to be restored

Example:

Open Using Run Dialog  notepad  Untitled - Notepad
Minimize Dialog
Sleep             1s
Restore Dialog
Sleep             1s
Restore Dialog    Untitled - Notepad
screenshot(filename: str, element: dict = None, ctrl: Any = None, desktop: bool = False, overwrite: bool = False) → None

Save screenshot into filename.

Parameters
  • filename – name of the file

  • element – take element screenshot, defaults to None

  • ctrl – take control screenshot, defaults to None

  • desktop – take desktop screenshot if True, defaults to False

  • overwrite – file is overwritten if True, defaults to False

Example:

@{element}   Find Element  CalculatorResults
Screenshot   element.png   ${elements[0][0]}
Screenshot   desktop.png   desktop=True
Screenshot   desktop.png   desktop=True  overwrite=True
send_keys(keys: str) → None

Send keys into active windows.

Parameters

keys – list of keys to send

Example:

Open Executable  calc.exe  Calculator
Send Keys        2{+}3=
send_keys_to_input(keys_to_type: str, with_enter: bool = True, send_delay: float = 0.5, enter_delay: float = 1.5) → None

Send keys to windows and add ENTER if with_enter is True

At the end of send_keys there is by default 0.5 second delay. At the end of ENTER there is by default 1.5 second delay.

Parameters
  • keys_to_type – keys to type into Windows

  • with_enter – send ENTER if with_enter is True

  • send_delay – delay after send_keys

  • enter_delay – delay after ENTER

Example:

${txt}    Get Spaced String   My name is Bond, James Bond
Send Keys To Input  ${txt}    with_enter=False
Send Keys To Input  {ENTER}THE   send_delay=5.0  with_enter=False
Send Keys To Input  {VK_SPACE}-{VK_SPACE}END   enter_delay=5.0
set_windows_backend(backend: str) → None

Set Windows backend which is used to interact with Windows applications

Allowed values defined by SUPPORTED_BACKENDS

Parameters

backend – name of the backend to use

Example:

Set Windows Backend   uia
Open Executable   calc.exe  Calculator
Set Windows Backend   win32
Open Executable   calc.exe  Calculator
switch_to_application(app_id: int) → None

Switch to application by id.

Parameters

app_id – application’s id

Raises

ValueError – if application is not found by given id

Example:

${app1}    Open Application   Excel
${app2}    Open Application   Word
Switch To Application   ${app1}
type_into(locator: str, keys: str, empty_field: bool = False) → None

Type keys into element matched by given locator.

Parameters
  • locator – element locator

  • keys – list of keys to type

Example:

Open Executable  calc.exe  Calculator
Type Into        CalculatorResults  11
Type Into        CalculatorResults  22  empty_field=True
type_keys(keys: str) → None

Type keys into active window element.

Parameters

keys – list of keys to type

Example:

Open Executable  notepad.exe  Untitled - Notepad
Type Keys   My text
wait_for_element(locator: str, search_criteria: str = None, timeout: float = 30.0, interval: float = 2.0) → Any

Wait for element to appear into the window.

Can return 1 or more elements matching locator, or raises ElementNotFoundError if element is not found within timeout.

Parameters
  • locator – name of the locator

  • search_criteria – criteria by which element is matched

  • timeout – defines how long to wait for element to appear, defaults to 30.0 seconds

  • interval – how often to poll for element, defaults to 2.0 seconds (minimum is 0.5 seconds)

Example:

@{elements}  Wait For Element  CalculatorResults
@{elements}  Wait For Element  Results   timeout=10  interval=1.5
RPA.Desktop.Windows.write_element_info_as_json(elements: Any, filename: str, path: str = 'output/json') → None

Write list of elements into json file

Parameters
  • elements – list of elements to write

  • filename – output file name

  • path – output directory, defaults to “output/json”