Python

O módulo botcity.core contém implementações especializadas destinadas à automação Desktop como DesktopBot, que é descrito abaixo.

Ao instanciar um DesktopBot, você terá acesso aos métodos responsáveis por automatizar aplicações e processos Desktop.

Aqui está um exemplo muito breve de um bot que abre o site da BotCity:

from botcity.core import DesktopBot


def main():
    # Instancia o DesktopBot
    bot = DesktopBot()
    # Abre o site da BotCity.
    bot.browse("http://www.botcity.dev")


if __name__ == '__main__':
    main()

botcity.core.bot.DesktopBot

Bases: BaseBot

Base class for Desktop Bots. Users must implement the action method in their classes.

Attributes:

Name	Type	Description
state	State	The internal state of this bot.
maestro	BotMaestroSDK	an instance to interact with the BotMaestro server.

app property writable

The connected application instance to be used.

Returns:

Name	Type	Description
app	Application | WindowSpecification	The connected Application/Window instance.

add_image(label, path)

Add an image into the state image map.

Parameters:

Name	Type	Description	Default
label	str	The image identifier	required
path	str	The path for the image on disk	required

alt_e(wait=0)

Press keys Alt+E

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

alt_f(wait=0)

Press keys Alt+F

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

alt_f4(wait=0)

Press keys Alt+F4

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

alt_r(wait=0)

Press keys Alt+R

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

alt_space(wait=0)

Press keys Alt+Space

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

alt_u(wait=0)

Press keys Alt+U

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

backspace(wait=0)

Press Backspace key

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

browse(url, location=0)

Invoke the default browser passing an URL

Parameters:

Name	Type	Description	Default
url	str	The URL to be visited.	required
location	int	If possible, open url in a location determined by new: * 0: the same browser window (the default) * 1: a new browser window * 2: a new browser page ("tab")	0

Returns:

Name	Type	Description
bool	bool	Whether or not the request was successful

click(wait_after=config.DEFAULT_SLEEP_AFTER_ACTION, *, clicks=1, interval_between_clicks=0, button='left')

Click on the last found element.

Parameters:

Name	Type	Description	Default
wait_after	int	Interval to wait after clicking on the element.	DEFAULT_SLEEP_AFTER_ACTION
clicks	int	Number of times to click. Defaults to 1.	1
interval_between_clicks	int	The interval between clicks in ms. Defaults to 0.	0
button	str	One of 'left', 'right', 'middle'. Defaults to 'left'	'left'

click_at(x, y)

Click at the coordinate defined by x and y

Parameters:

Name	Type	Description	Default
x	int	The X coordinate	required
y	int	The Y coordinate	required

click_on(label)

Click on the element.

Parameters:

Name	Type	Description	Default
label	str	The image identifier	required

click_relative(x, y, wait_after=config.DEFAULT_SLEEP_AFTER_ACTION, *, clicks=1, interval_between_clicks=0, button='left')

Click Relative on the last found element.

Parameters:

Name	Type	Description	Default
x	int	Horizontal offset	required
y	int	Vertical offset	required
wait_after	int	Interval to wait after clicking on the element.	DEFAULT_SLEEP_AFTER_ACTION
clicks	int	Number of times to click. Defaults to 1.	1
interval_between_clicks	int	The interval between clicks in ms. Defaults to 0.	0
button	str	One of 'left', 'right', 'middle'. Defaults to 'left'	'left'

connect_to_app(backend=Backend.WIN_32, timeout=60000, **connection_selectors)

Connects to an instance of an open application. Use this method to be able to access application windows and elements.

Parameters:

Name	Type	Description	Default
backend	Backend	The accessibility technology defined in the Backend class that could be used for your application. Defaults to Backend.WIN_32 ('win32').	WIN_32
timeout	int	Maximum wait time (ms) to wait for connection. Defaults to 60000ms (60s).	60000
**connection_selectors	dict[str, Any]	Attributes that can be used to connect to an application. See more details about the available selectors .	{}

Returns app (Application): The Application/Window instance.

control_a(wait=0)

Press keys CTRL+A

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

control_c(wait=0)

Press keys CTRL+C

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

control_end(wait=0)

Press keys CTRL+End

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

control_f(wait=0)

Press keys CTRL+F

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

control_home(wait=0)

Press keys CTRL+Home

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

control_key(key_to_press, wait=0)

Press CTRL and one more simple key to perform a keyboard shortcut

Parameters:

Name	Type	Description	Default
key_to_press	str	The key that will be pressed with the CTRL.	required
wait	int	Wait interval (ms) after task.	0

control_p(wait=0)

Press keys CTRL+P

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

control_r(wait=0)

Press keys CTRL+R

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

control_s(wait=0)

Press keys CTRL+S

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

control_shift_j(wait=0)

Press keys CTRL+Shift+J

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

control_shift_p(wait=0)

Press keys CTRL+Shift+P

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

control_t(wait=0)

Press keys CTRL+T

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

control_u(wait=0)

Press keys CTRL+U

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

control_v(wait=0)

Press keys CTRL+V

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

control_w(wait=0)

Press keys CTRL+W

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

copy_to_clipboard(text, wait=0)

Copy content to the clipboard.

Parameters:

Name	Type	Description	Default
text	str	The text to be copied.	required
wait	int	Wait interval (ms) after task	0

delete(wait=0)

Press Delete key

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

display_size()

Returns the display size in pixels.

Returns:

Name	Type	Description
size	Tuple	The screen dimension (width and height) in pixels.

double_click(wait_after=config.DEFAULT_SLEEP_AFTER_ACTION)

Double Click on the last found element.

Parameters:

Name	Type	Description	Default
wait_after	int	Interval to wait after clicking on the element.	DEFAULT_SLEEP_AFTER_ACTION

double_click_relative(x, y, interval_between_clicks=0, wait_after=config.DEFAULT_SLEEP_AFTER_ACTION)

Double Click Relative on the last found element.

Parameters:

Name	Type	Description	Default
x	int	Horizontal offset	required
y	int	Vertical offset	required
interval_between_clicks	int	The interval between clicks in ms. Defaults to 0.	0
wait_after	int	Interval to wait after clicking on the element.	DEFAULT_SLEEP_AFTER_ACTION

enter(wait=0, presses=1)

Press key Enter

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0
presses	int	Number of times to press the key. Defaults to 1.	1

execute(file_path)

Invoke the system handler to open the given file.

Parameters:

Name	Type	Description	Default
file_path	str	The path for the file to be executed	required

find(label, x=None, y=None, width=None, height=None, *, threshold=None, matching=0.9, waiting_time=10000, best=True, grayscale=False)

Find an element defined by label on screen until a timeout happens.

Parameters:

Name	Type	Description	Default
label	str	The image identifier	required
x	int	Search region start position x. Defaults to 0.	None
y	int	Search region start position y. Defaults to 0.	None
width	int	Search region width. Defaults to screen width.	None
height	int	Search region height. Defaults to screen height.	None
threshold	int	The threshold to be applied when doing grayscale search. Defaults to None.	None
matching	float	The matching index ranging from 0 to 1. Defaults to 0.9.	0.9
waiting_time	int	Maximum wait time (ms) to search for a hit. Defaults to 10000ms (10s).	10000
best	bool	Whether or not to keep looking until the best matching is found. Defaults to True.	True
grayscale	bool	Whether or not to convert to grayscale before searching. Defaults to False.	False

Returns:

Name	Type	Description
element	NamedTuple	The element coordinates. None if not found.

find_all(label, x=None, y=None, width=None, height=None, *, threshold=None, matching=0.9, waiting_time=10000, grayscale=False)

Find all elements defined by label on screen until a timeout happens.

Parameters:

Name	Type	Description	Default
label	str	The image identifier	required
x	int	Search region start position x. Defaults to 0.	None
y	int	Search region start position y. Defaults to 0.	None
width	int	Search region width. Defaults to screen width.	None
height	int	Search region height. Defaults to screen height.	None
threshold	int	The threshold to be applied when doing grayscale search. Defaults to None.	None
matching	float	The matching index ranging from 0 to 1. Defaults to 0.9.	0.9
waiting_time	int	Maximum wait time (ms) to search for a hit. Defaults to 10000ms (10s).	10000
grayscale	bool	Whether or not to convert to grayscale before searching. Defaults to False.	False

Returns:

Name	Type	Description
elements	Iterable[NamedTuple]	A generator with all element coordinates fount. None if not found.

find_app_element(from_parent_window=None, waiting_time=10000, **selectors)

Find a element of the currently connected application using the available selectors. You can pass the context window where the element is contained.

Parameters:

Name	Type	Description	Default
from_parent_window	WindowSpecification	The element's parent window.	None
waiting_time	int	Maximum wait time (ms) to search for a hit. Defaults to 10000ms (10s).	10000
**selectors	dict[str, Any]	Attributes that can be used to filter an element. See more details about the available selectors .	{}

Returns element (WindowSpecification): The element/control found.

find_app_window(waiting_time=10000, **selectors)

Find a window of the currently connected application using the available selectors.

Parameters:

Name	Type	Description	Default
waiting_time	int	Maximum wait time (ms) to search for a hit. Defaults to 10000ms (10s).	10000
**selectors	dict[str, Any]	Attributes that can be used to filter an element. See more details about the available selectors .	{}

Returns dialog (WindowSpecification): The window or control found.

find_multiple(labels, x=0, y=0, width=None, height=None, *, threshold=None, matching=0.9, waiting_time=10000, best=True, grayscale=False)

Find multiple elements defined by label on screen until a timeout happens.

Parameters:

Name	Type	Description	Default
labels	list	A list of image identifiers	required
x	int	Search region start position x. Defaults to 0.	0
y	int	Search region start position y. Defaults to 0.	0
width	int	Search region width. Defaults to screen width.	None
height	int	Search region height. Defaults to screen height.	None
threshold	int	The threshold to be applied when doing grayscale search. Defaults to None.	None
matching	float	The matching index ranging from 0 to 1. Defaults to 0.9.	0.9
waiting_time	int	Maximum wait time (ms) to search for a hit. Defaults to 10000ms (10s).	10000
best	bool	Whether or not to keep looking until the best matching is found. Defaults to True.	True
grayscale	bool	Whether or not to convert to grayscale before searching. Defaults to False.	False

Returns:

Name	Type	Description
results	dict	A dictionary in which the key is the label and value are the element coordinates in a NamedTuple.

find_process(name=None, pid=None)

Find a process by name or PID

Parameters:

Name	Type	Description	Default
name	str	The process name.	None
pid	str) or (int	The PID (Process Identifier).	None

Return

process (psutil.Process): A Process instance.

find_text(label, x=None, y=None, width=None, height=None, *, threshold=None, matching=0.9, waiting_time=10000, best=True)

Find an element defined by label on screen until a timeout happens.

Parameters:

Name	Type	Description	Default
label	str	The image identifier	required
x	int	Search region start position x. Defaults to 0.	None
y	int	Search region start position y. Defaults to 0.	None
width	int	Search region width. Defaults to screen width.	None
height	int	Search region height. Defaults to screen height.	None
threshold	int	The threshold to be applied when doing grayscale search. Defaults to None.	None
matching	float	The matching index ranging from 0 to 1. Defaults to 0.9.	0.9
waiting_time	int	Maximum wait time (ms) to search for a hit. Defaults to 10000ms (10s).	10000
best	bool	Whether or not to keep looking until the best matching is found. Defaults to True.	True

Returns:

Name	Type	Description
element	NamedTuple	The element coordinates. None if not found.

find_until(label, x=None, y=None, width=None, height=None, *, threshold=None, matching=0.9, waiting_time=10000, best=True, grayscale=False)

Find an element defined by label on screen until a timeout happens.

Parameters:

Name	Type	Description	Default
label	str	The image identifier	required
x	int	Search region start position x. Defaults to 0.	None
y	int	Search region start position y. Defaults to 0.	None
width	int	Search region width. Defaults to screen width.	None
height	int	Search region height. Defaults to screen height.	None
threshold	int	The threshold to be applied when doing grayscale search. Defaults to None.	None
matching	float	The matching index ranging from 0 to 1. Defaults to 0.9.	0.9
waiting_time	int	Maximum wait time (ms) to search for a hit. Defaults to 10000ms (10s).	10000
best	bool	Whether or not to keep looking until the best matching is found. Defaults to True.	True
grayscale	bool	Whether or not to convert to grayscale before searching. Defaults to False.	False

Returns:

Name	Type	Description
element	NamedTuple	The element coordinates. None if not found.

get_clipboard()

Get the current content in the clipboard.

Returns:

Name	Type	Description
text	str	Current clipboard content

get_element_coords(label, x=None, y=None, width=None, height=None, matching=0.9, best=True)

Find an element defined by label on screen and returns its coordinates.

Parameters:

Name	Type	Description	Default
label	str	The image identifier	required
x	int	X (Left) coordinate of the search area.	None
y	int	Y (Top) coordinate of the search area.	None
width	int	Width of the search area.	None
height	int	Height of the search area.	None
matching	float	Minimum score to consider a match in the element image recognition process. Defaults to 0.9.	0.9
best	bool	Whether or not to search for the best value. If False the method returns on the first find. Defaults to True.	True

Returns:

Name	Type	Description
coords	Tuple	A tuple containing the x and y coordinates for the element.

get_element_coords_centered(label, x=None, y=None, width=None, height=None, matching=0.9, best=True)

Find an element defined by label on screen and returns its centered coordinates.

Parameters:

Name	Type	Description	Default
label	str	The image identifier	required
x	int	X (Left) coordinate of the search area.	None
y	int	Y (Top) coordinate of the search area.	None
width	int	Width of the search area.	None
height	int	Height of the search area.	None
matching	float	Minimum score to consider a match in the element image recognition process. Defaults to 0.9.	0.9
best	bool	Whether or not to search for the best value. If False the method returns on the first find. Defaults to True.	True

Returns:

Name	Type	Description
coords	Tuple	A tuple containing the x and y coordinates for the center of the element.

get_image_from_map(label)

Return an image from teh state image map.

Parameters:

Name	Type	Description	Default
label	str	The image identifier	required

Returns:

Name	Type	Description
Image	Image	The Image object

get_last_element()

Return the last element found.

Returns:

Name	Type	Description
element	NamedTuple	The element coordinates (left, top, width, height)

get_last_x()

Get the last X position for the mouse.

Returns:

Name	Type	Description
x	int	The last x position for the mouse.

get_last_y()

Get the last Y position for the mouse.

Returns:

Name	Type	Description
y	int	The last y position for the mouse.

get_screenshot(filepath=None, region=None)

Capture a screenshot.

Parameters:

Name	Type	Description	Default
filepath	str	The filepath in which to save the screenshot. Defaults to None.	None
region	tuple	Bounding box containing left, top, width and height to crop screenshot.	None

Returns:

Name	Type	Description
Image	Image	The screenshot Image object

hold_shift(wait=0)

Hold key Shift

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

kb_type(text, interval=0)

Type a text char by char (individual key events).

Parameters:

Name	Type	Description	Default
text	str	text to be typed.	required
interval	int	interval (ms) between each key press. Defaults to 0	0

key_end(wait=0)

Press key End

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

key_enter(wait=0)

Press key Enter

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

key_esc(wait=0)

Press key Esc

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

key_right(wait=0)

Press key Right

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

maximize_window()

Shortcut to maximize window on Windows OS.

mouse_down(wait_after=config.DEFAULT_SLEEP_AFTER_ACTION, *, button='left')

Holds down the requested mouse button.

Parameters:

Name	Type	Description	Default
wait_after	int	Interval to wait after clicking on the element.	DEFAULT_SLEEP_AFTER_ACTION
button	str	One of 'left', 'right', 'middle'. Defaults to 'left'	'left'

mouse_move(x, y)

Move the mouse to the coordinate defined by x and y

Parameters:

Name	Type	Description	Default
x	int	The X coordinate	required
y	int	The Y coordinate	required

mouse_up(wait_after=config.DEFAULT_SLEEP_AFTER_ACTION, *, button='left')

Releases the requested mouse button.

Parameters:

Name	Type	Description	Default
wait_after	int	Interval to wait after clicking on the element.	DEFAULT_SLEEP_AFTER_ACTION
button	str	One of 'left', 'right', 'middle'. Defaults to 'left'	'left'

move()

Move to the center position of last found item.

move_random(range_x, range_y)

Move randomly along the given x, y range.

Parameters:

Name	Type	Description	Default
range_x	int	Horizontal range	required
range_y	int	Vertical range	required

move_relative(x, y)

Move the mouse relative to its current position.

Parameters:

Name	Type	Description	Default
x	int	Horizontal offset	required
y	int	Vertical offset	required

page_down(wait=0)

Press Page Down key

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

page_up(wait=0)

Press Page Up key

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

paste(text=None, wait=0)

Paste content from the clipboard.

Parameters:

Name	Type	Description	Default
text	str	The text to be pasted. Defaults to None	None
wait	int	Wait interval (ms) after task	0

release_shift()

Release key Shift. This method needs to be invoked after holding Shift or similar.

right_click(wait_after=config.DEFAULT_SLEEP_AFTER_ACTION, *, clicks=1, interval_between_clicks=0)

Right click on the last found element.

Parameters:

Name	Type	Description	Default
wait_after	int	Interval to wait after clicking on the element.	DEFAULT_SLEEP_AFTER_ACTION
clicks	int	Number of times to click. Defaults to 1.	1
interval_between_clicks	int	The interval between clicks in ms. Defaults to 0.	0

right_click_at(x, y)

Right click at the coordinate defined by x and y

Parameters:

Name	Type	Description	Default
x	int	The X coordinate	required
y	int	The Y coordinate	required

right_click_relative(x, y, interval_between_clicks=0, wait_after=config.DEFAULT_SLEEP_AFTER_ACTION)

Right Click Relative on the last found element.

Parameters:

Name	Type	Description	Default
x	int	Horizontal offset	required
y	int	Vertical offset	required
interval_between_clicks	int	The interval between clicks in ms. Defaults to 0.	0
wait_after	int	Interval to wait after clicking on the element.	DEFAULT_SLEEP_AFTER_ACTION

save_screenshot(path)

Saves a screenshot in a given path.

Parameters:

Name	Type	Description	Default
path	str	The filepath in which to save the screenshot	required

screen_cut(x=0, y=0, width=None, height=None)

Capture a screenshot from a region of the screen.

Parameters:

Name	Type	Description	Default
x	int	region start position x	0
y	int	region start position y	0
width	int	region width	None
height	int	region height	None

Returns:

Name	Type	Description
Image	Image	The screenshot Image object

screenshot(filepath=None, region=None)

Capture a screenshot.

Parameters:

Name	Type	Description	Default
filepath	str	The filepath in which to save the screenshot. Defaults to None.	None
region	tuple	Bounding box containing left, top, width and height to crop screenshot.	None

Returns:

Name	Type	Description
Image	Image	The screenshot Image object

scroll_down(clicks)

Scroll Down n clicks

Parameters:

Name	Type	Description	Default
clicks	int	Number of times to scroll down.	required

scroll_up(clicks)

Scroll Up n clicks

Parameters:

Name	Type	Description	Default
clicks	int	Number of times to scroll up.	required

shift_tab(wait=0)

Press keys Shift+Tab

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

sleep(interval)

Wait / Sleep for a given interval.

Parameters:

Name	Type	Description	Default
interval	int	Interval in milliseconds	required

space(wait=0)

Press Space key

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

tab(wait=0, presses=1)

Press key Tab

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0
presses	int	Number of times to press the key. Defaults to 1.	1

terminate_process(process)

Terminate the process via the received Process object.

Parameters:

Name	Type	Description	Default
process	Process	The process to terminate.	required

triple_click(wait_after=config.DEFAULT_SLEEP_AFTER_ACTION)

Triple Click on the last found element.

Parameters:

Name	Type	Description	Default
wait_after	int	Interval to wait after clicking on the element.	DEFAULT_SLEEP_AFTER_ACTION

triple_click_relative(x, y, interval_between_clicks=0, wait_after=config.DEFAULT_SLEEP_AFTER_ACTION)

Triple Click Relative on the last found element.

Parameters:

Name	Type	Description	Default
x	int	Horizontal offset	required
y	int	Vertical offset	required
interval_between_clicks	int	The interval between clicks in ms. Defaults to 0.	0
wait_after	int	Interval to wait after clicking on the element.	DEFAULT_SLEEP_AFTER_ACTION

type_down(wait=0)

Press Down key

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

type_key(text, interval=0)

Type a text char by char (individual key events).

Parameters:

Name	Type	Description	Default
text	str	text to be typed.	required
interval	int	interval (ms) between each key press. Defaults to 0	0

type_keys(keys)

Press a sequence of keys. Hold the keys in the specific order and releases them.

Parameters:

Name	Type	Description	Default
keys	list	List of keys to be pressed	required

type_keys_with_interval(interval, keys)

Press a sequence of keys. Hold the keys in the specific order and releases them.

Parameters:

Name	Type	Description	Default
interval	int	Interval (ms) in which to press and release keys	required
keys	list	List of keys to be pressed	required

type_left(wait=0)

Press Left key

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

type_right(wait=0)

Press Right key

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

type_up(wait=0)

Press Up key

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

type_windows(wait=0)

Press Win logo key

Parameters:

Name	Type	Description	Default
wait	int	Wait interval (ms) after task	0

wait(interval)

Wait / Sleep for a given interval.

Parameters:

Name	Type	Description	Default
interval	int	Interval in milliseconds	required

wait_for_file(path, timeout=10000)

Invoke the system handler to open the given file.

Parameters:

Name	Type	Description	Default
path	str	The path for the file to be executed	required
timeout	int	Maximum wait time (ms) to search for a hit. Defaults to 10000ms (10s).	10000

Returns status (bool): Whether or not the file was available before the timeout