pywinauto.application module¶
pywinauto.base_application module¶
The application module is the main one that users will use first.
When starting to automate an application you must initialize an instance
of the Application class. Then you have to start the program with
Application.start
or connect to a runing process of an application with:
Application.connect
Once you have an Application instance you can access dialogs in that application by using one of the methods below.
dlg = app.YourDialogTitle
dlg = app.window(name="your title", classname="your class", ...)
dlg = app['Your Dialog Title']
Similarly once you have a dialog you can get a control from that dialog in almost exactly the same ways.
ctrl = dlg.YourControlTitle
ctrl = dlg.child_window(name="Your control", classname="Button", ...)
ctrl = dlg["Your control"]
Note
For attribute access of controls and dialogs you do not have to specify the exact name/title/text of the control. Pywinauto automatically performs a best match of the available dialogs or controls.
With introducing the cross-platform support in pywinauto, the Application class is automatically created with the platform default backend. For MS Windows OS it is ‘win32’ and for Linux OS it is ‘atspi’.
See also
pywinauto.findwindows.find_elements()
for the keyword arguments that
can be passed to both:
WindowSpecification.child_window
and
WindowSpecification.window
pywinauto.windows.application.Application
for the ‘win32’ and ‘uia’ backends
pywinauto.linux.application.Application
for the ‘atspi’ backend
-
exception
pywinauto.base_application.
AppNotConnected
¶ Bases:
Exception
Application has not been connected to a process yet
-
exception
pywinauto.base_application.
AppStartError
¶ Bases:
Exception
There was a problem starting the Application
-
class
pywinauto.base_application.
BaseApplication
¶ Bases:
object
Represents an application
-
__getattribute__
(attr_name)¶ Find the specified dialog of the application
-
__getitem__
(key)¶ Find the specified dialog of the application
-
Window_
(**kwargs)¶ Return a window of the application
You can specify the same parameters as findwindows.find_windows. It will add the process parameter to ensure that the window is from the current process.
See
pywinauto.findwindows.find_elements()
for the full parameters description.
-
active
()¶ Return WindowSpecification for an active window of the application
-
connect
(**kwargs)¶ Connect to an already running process
The action is performed according to only one of parameters
Parameters: - pid – a process ID of the target
- handle – a window handle of the target
- path – a path used to launch the target
- timeout – a timeout for process start (relevant if path is specified)
See also
pywinauto.findwindows.find_elements()
- the keyword arguments that are also can be used instead of pid, handle or path
-
cpu_usage
(interval=None)¶ Return CPU usage percent during specified number of seconds
-
is_process_running
()¶ Checks that process is running.
Can be called before start/connect.
Returns True if process is running otherwise - False
-
kill
(soft=False)¶ Try to close and kill the application
Dialogs may pop up asking to save data - but the application will be killed anyway - you will not be able to click the buttons. This should only be used when it is OK to kill the process like you would do in task manager.
-
start
(cmd_line, timeout=None, retry_interval=None, create_new_console=False, wait_for_idle=True, work_dir=None)¶ Start the application as specified by cmd_line
Parameters: - cmd_line – a string with a path to launch the target
- timeout – a timeout for process to start (optional)
- retry_interval – retry interval (optional)
- create_new_console – create a new console (optional)
- wait_for_idle – wait for idle (optional)
- work_dir – working directory (optional)
-
top_window
()¶ Return WindowSpecification for a current top window of the application
-
wait_cpu_usage_lower
(threshold=2.5, timeout=None, usage_interval=None)¶ Wait until process CPU usage percentage is less than the specified threshold
-
wait_for_process_exit
(timeout=None, retry_interval=None)¶ Waits for process to exit until timeout reaches
Raises TimeoutError exception if timeout was reached
-
window
(**kwargs)¶ Return a window of the application
You can specify the same parameters as findwindows.find_windows. It will add the process parameter to ensure that the window is from the current process.
See
pywinauto.findwindows.find_elements()
for the full parameters description.
-
window_
(**kwargs)¶ Return a window of the application
You can specify the same parameters as findwindows.find_windows. It will add the process parameter to ensure that the window is from the current process.
See
pywinauto.findwindows.find_elements()
for the full parameters description.
-
windows
(**kwargs)¶ Return a list of wrapped top level windows of the application
-
-
exception
pywinauto.base_application.
ProcessNotFoundError
¶ Bases:
Exception
Could not find that process
-
class
pywinauto.base_application.
WindowSpecification
(search_criteria, allow_magic_lookup=True)¶ Bases:
object
A specification for finding a window or control
Windows are resolved when used. You can also wait for existance or non existance of a window
-
__getattribute__
(attr_name)¶ Attribute access for this class
If we already have criteria for both dialog and control then resolve the control and return the requested attribute.
If we have only criteria for the dialog but the attribute requested is an attribute of DialogWrapper then resolve the dialog and return the requested attribute.
Otherwise delegate functionality to
__getitem__()
- which sets the appropriate criteria for the control.
-
__getitem__
(key)¶ Allow access to dialogs/controls through item access
This allows:
app['DialogTitle']['ControlTextClass']
to be used to access dialogs and controls.
Both this and
__getattribute__()
use the rules outlined in the HowTo document.
-
WAIT_CRITERIA_MAP
= {'visible': <function WindowSpecification.<lambda> at 0x7efda5af6320>, 'enabled': <function WindowSpecification.<lambda> at 0x7efda5af63b0>, 'active': <function WindowSpecification.<lambda> at 0x7efda5af6440>}¶
-
WAIT_NOT_CRITERIA_MAP
= {'visible': <function WindowSpecification.<lambda> at 0x7efda5af64d0>, 'enabled': <function WindowSpecification.<lambda> at 0x7efda5af6560>, 'active': <function WindowSpecification.<lambda> at 0x7efda5af65f0>}¶
-
by
(**criteria)¶ Add criteria for a control
When this window specification is resolved it will be used to match against a control.
-
dump_tree
(depth=10, max_width=10, filename=None)¶ Dump the ‘identifiers’ to console or a file
Dump identifiers for the control and for its descendants to a depth of depth (the whole subtree if None).
Parameters: - depth – Max depth level of an element tree to dump (None: unlimited).
- max_width – Max number of children of each element to dump (None: unlimited).
- filename – Save tree to a specified file (None: print to stdout).
Note
The identifiers dumped by this method have been made unique. So if you have 2 edit boxes, they won’t both have “Edit” listed in their identifiers. In fact the first one can be referred to as “Edit”, “Edit0”, “Edit1” and the 2nd should be referred to as “Edit2”.
-
exists
(timeout=None, retry_interval=None)¶ Wait for the window exists, return True if the control exists.
Parameters: - timeout – how much time (in seconds) to try to find the control.
Default:
Timings.exists_timeout
. - retry_interval – how long to wait between each retry.
Default:
Timings.exists_retry
.
- timeout – how much time (in seconds) to try to find the control.
Default:
-
find
(timeout=None, retry_interval=None)¶ Find a control using criteria. The returned control matches conditions from criteria[-1].
criteria - a list with dictionaries
1st element is search criteria for the dialog
other elements are search criteria for a control of the dialog
timeout - maximum length of time to try to find the controls (default 5)
retry_interval - how long to wait between each retry (default .2)
-
find_all
(timeout=None, retry_interval=None)¶ Find all controls using criteria. The returned controls match conditions from criteria[-1]. Parent controls are assumed to exist in a single instance. Otherwise it will result in an ElementAmbiguousError.
criteria - a list with dictionaries
1st element is search criteria for the dialog
other elements are search criteria for a control of the dialog
timeout - maximum length of time to try to find the controls (default 5)
retry_interval - how long to wait between each retry (default .09)
-
not_exists
(timeout=None, retry_interval=None)¶ Wait for the window does not exist, return True if the control does not exist.
Parameters: - timeout – how much time (in seconds) to wait until the control exists.
Default:
Timings.exists_timeout
. - retry_interval – how long to wait between each retry.
Default:
Timings.exists_retry
.
- timeout – how much time (in seconds) to wait until the control exists.
Default:
-
print_control_identifiers
(*args, **kwargs)¶
-
print_ctrl_ids
(*args, **kwargs)¶
-
wait
(wait_for, timeout=None, retry_interval=None)¶ (DEPRECATED) Wait for the window to be in a particular state/states. :param wait_for: The state to wait for the window to be in. It can
- be any of the following states, also you may combine the states by space key.
- ‘exists’ means that the window is a valid handle
- ‘visible’ means that the window is not hidden
- ‘enabled’ means that the window is not disabled
- ‘ready’ means that the window is visible and enabled
- ‘active’ means that the window is active
Parameters: - timeout – Raise an
pywinauto.timings.TimeoutError()
if the window is not in the appropriate state after this number of seconds. Default:pywinauto.timings.Timings.window_find_timeout
. - retry_interval – How long to sleep between each retry.
Default:
pywinauto.timings.Timings.window_find_retry
.
An example to wait until the dialog exists, is ready, enabled and visible:
self.Dlg.wait("exists enabled visible ready")
-
wait_not
(wait_for, timeout=None, retry_interval=None)¶ (DEPRECATED)Wait for the window to not be in a particular state/states. :param wait_for_not: The state to wait for the window to not be in. It can be any
- of the following states, also you may combine the states by space key.
- ‘exists’ means that the window is a valid handle
- ‘visible’ means that the window is not hidden
- ‘enabled’ means that the window is not disabled
- ‘ready’ means that the window is visible and enabled
- ‘active’ means that the window is active
Parameters: - timeout – Raise an
pywinauto.timings.TimeoutError()
if the window is sill in the state after this number of seconds. Default:pywinauto.timings.Timings.window_find_timeout
. - retry_interval – How long to sleep between each retry.
Default:
pywinauto.timings.Timings.window_find_retry
.
- An example to wait until the dialog is not ready, enabled or visible: ::
- self.Dlg.wait_not(“enabled visible ready”)
-