pywinauto.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 must Application.Start()
that
application or Application.Connect()
to a running instance of that
application.
Once you have an Application instance you can access dialogs in that application either by using one of the methods below.
dlg = app.YourDialogTitle
dlg = app.ChildWindow(title = "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.ChildWindow(title = "Your control", classname = "Button", ...)
ctrl = dlg["Your control"]
Note
For attribute access of controls and dialogs you do not have to have the title of the control exactly, it does a best match of the available dialogs or controls.
See also
pywinauto.findwindows.find_windows()
for the keyword arguments that
can be passed to both: Application.Window_()
and
WindowSpecification.Window()
-
exception
pywinauto.application.
AppNotConnected
¶ Bases:
Exception
Application has not been connected to a process yet
-
exception
pywinauto.application.
AppStartError
¶ Bases:
Exception
There was a problem starting the Application
-
class
pywinauto.application.
Application
(backend='win32', datafilename=None)¶ Bases:
object
Represents an application
-
__getattribute__
(attr_name)¶ Find the specified dialog of the application
-
__getitem__
(key)¶ Find the specified dialog of the application
-
CPUUsage
(interval=None)¶ Return CPU usage percent during specified number of seconds
-
Connect
(**kwargs)¶ Connects to an already running process
-
Connect_
(**kwargs)¶ Deprecated method. Performs PendingDeprecationWarning before calling the .connect(). Should be also removed in 0.6.X.
-
GetMatchHistoryItem
(index)¶ Should not be used - part of application data implementation
-
Kill_
()¶ 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 in task manager.
-
Start
(cmd_line, timeout=None, retry_interval=None, create_new_console=False, wait_for_idle=True)¶ Starts the application giving in cmd_line
-
Start_
(*args, **kwargs)¶ Deprecated method. Performs PendingDeprecationWarning before calling the .start(). Should be also removed in 0.6.X.
-
WaitCPUUsageLower
(threshold=2.5, timeout=None, usage_interval=None)¶ Wait until process CPU usage percentage is less than specified threshold
-
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.
-
Windows_
(**kwargs)¶ Return list of wrapped top level windows of the application
-
WriteAppData
(filename)¶ Should not be used - part of application data implementation
-
active_
()¶ Return the active window of the application
-
connect
(**kwargs)¶ Connects to an already running process
-
connect_
(**kwargs)¶ Deprecated method. Performs PendingDeprecationWarning before calling the .connect(). Should be also removed in 0.6.X.
-
cpu_usage
(interval=None)¶ Return CPU usage percent during specified number of seconds
-
is64bit
()¶ Return True if running process is 64-bit
-
kill_
()¶ 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 in task manager.
-
start
(cmd_line, timeout=None, retry_interval=None, create_new_console=False, wait_for_idle=True)¶ Starts the application giving in cmd_line
-
start_
(*args, **kwargs)¶ Deprecated method. Performs PendingDeprecationWarning before calling the .start(). Should be also removed in 0.6.X.
-
top_window_
()¶ Return the 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 specified threshold
-
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.
-
windows_
(**kwargs)¶ Return list of wrapped top level windows of the application
-
-
pywinauto.application.
AssertValidProcess
(process_id)¶ Raise ProcessNotFound error if process_id is not a valid process id
-
exception
pywinauto.application.
ProcessNotFoundError
¶ Bases:
Exception
Could not find that process
-
class
pywinauto.application.
WindowSpecification
(search_criteria)¶ 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.
-
ChildWindow
(**criteria)¶ Add criteria for a control
When this window specification is resolved then this will be used to match against a control.
-
Exists
(timeout=None, retry_interval=None)¶ Check if the window exists, return True if the control exists
Parameters: - timeout – the maximum amount of time to wait for the
control to exists. Defaults to
Timings.exists_timeout
- retry_interval – The control is checked for existance this number
of seconds.
Defaults to Timings.exists_retry
- timeout – the maximum amount of time to wait for the
control to exists. Defaults to
-
PrintControlIdentifiers
(depth=2)¶ Prints the ‘identifiers’
Prints identifiers for the control and for its descendants to a depth of depth.
Note
The identifiers printed 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”.
-
WAIT_CRITERIA_MAP
= {'visible': ('is_visible',), 'enabled': ('is_enabled',), 'ready': ('is_visible', 'is_enabled'), 'active': ('is_active',), 'exists': ('Exists',)}¶
-
Wait
(wait_for, timeout=None, retry_interval=None)¶ Wait for the window to be in a particular state/states.
Parameters: - 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
- timeout – Raise an
pywinauto.timings.TimeoutError()
if the window is not in the appropriate state after this number of seconds. - 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_for –
-
WaitNot
(wait_for_not, timeout=None, retry_interval=None)¶ Wait for the window to not be in a particular state/states.
Parameters: - 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
- timeout – Raise an
pywinauto.timings.TimeoutError()
if the window is sill in the state after this number of seconds. - 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")
- wait_for_not –
-
Window
(**criteria)¶ Deprecated alias of child_window()
-
Window_
(**criteria)¶ Deprecated alias of child_window()
-
WrapperObject
()¶ Allow the calling code to get the HwndWrapper object
-
child_window
(**criteria)¶ Add criteria for a control
When this window specification is resolved then this will be used to match against a control.
-
exists
(timeout=None, retry_interval=None)¶ Check if the window exists, return True if the control exists
Parameters: - timeout – the maximum amount of time to wait for the
control to exists. Defaults to
Timings.exists_timeout
- retry_interval – The control is checked for existance this number
of seconds.
Defaults to Timings.exists_retry
- timeout – the maximum amount of time to wait for the
control to exists. Defaults to
-
print_control_identifiers
(depth=2)¶ Prints the ‘identifiers’
Prints identifiers for the control and for its descendants to a depth of depth.
Note
The identifiers printed 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”.
-
wait
(wait_for, timeout=None, retry_interval=None)¶ Wait for the window to be in a particular state/states.
Parameters: - 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
- timeout – Raise an
pywinauto.timings.TimeoutError()
if the window is not in the appropriate state after this number of seconds. - 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_for –
-
wait_not
(wait_for_not, timeout=None, retry_interval=None)¶ Wait for the window to not be in a particular state/states.
Parameters: - 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
- timeout – Raise an
pywinauto.timings.TimeoutError()
if the window is sill in the state after this number of seconds. - 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")
- wait_for_not –
-
window_
(**criteria)¶ Deprecated alias of child_window()
-
wrapper_object
()¶ Allow the calling code to get the HwndWrapper object
-
-
pywinauto.application.
assert_valid_process
(process_id)¶ Raise ProcessNotFound error if process_id is not a valid process id
-
pywinauto.application.
process_from_module
(module)¶ Return the running process with path module
-
pywinauto.application.
process_get_modules
()¶ Return the list of processes as tuples (pid, exe_path)
-
pywinauto.application.
process_module
(process_id)¶ Return the string module name of this process