Saltar a contenido

Python

El módulo botcity.core contiene implementaciones especializadas orientadas a la automatización Desktop, como DesktopBot, que se describe a continuación.

Al instanciar un DesktopBot, tendrás acceso a los métodos responsables de automatizar aplicaciones y procesos Desktop.

Aquí tienes un ejemplo muy breve de un bot que abre el sitio web de BotCity:

from botcity.core import DesktopBot


def main():
    # Instantiate the DesktopBot
    bot = DesktopBot()
    # Opens the BotCity website.
    bot.browse("http://www.botcity.dev")


if __name__ == '__main__':
    main()

botcity.core.bot.DesktopBot (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:

Type Description
app (Application)

The connected Application instance.

add_image(self, 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(self, wait=0)

Press keys Alt+E

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

alt_f(self, wait=0)

Press keys Alt+F

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

alt_f4(self, wait=0)

Press keys Alt+F4

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

alt_r(self, wait=0)

Press keys Alt+R

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

alt_space(self, wait=0)

Press keys Alt+Space

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

alt_u(self, wait=0)

Press keys Alt+U

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

backspace(self, wait=0)

Press Backspace key

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

browse(self, 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:

Type Description
bool

Whether or not the request was successful

click(self, wait_after=300, *, 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.

300
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(self, 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(self, label)

Click on the element.

Parameters:

Name Type Description Default
label str

The image identifier

required

click_relative(self, x, y, wait_after=300, *, 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.

300
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(self, backend=<Backend.WIN_32: 'win32'>, 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').

<Backend.WIN_32: 'win32'>
timeout int

Maximum wait time (ms) to wait for connection. Defaults to 60000ms (60s).

60000
**connection_selectors

Attributes that can be used to connect to an application. See more details about the available selectors .

{}

Returns app (Application): The Application instance.

control_a(self, wait=0)

Press keys CTRL+A

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

control_c(self, wait=0)

Press keys CTRL+C

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

control_end(self, wait=0)

Press keys CTRL+End

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

control_f(self, wait=0)

Press keys CTRL+F

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

control_home(self, wait=0)

Press keys CTRL+Home

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

control_key(self, 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(self, wait=0)

Press keys CTRL+P

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

control_r(self, wait=0)

Press keys CTRL+R

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

control_s(self, wait=0)

Press keys CTRL+S

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

control_shift_j(self, wait=0)

Press keys CTRL+Shift+J

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

control_shift_p(self, wait=0)

Press keys CTRL+Shift+P

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

control_t(self, wait=0)

Press keys CTRL+T

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

control_u(self, wait=0)

Press keys CTRL+U

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

control_v(self, wait=0)

Press keys CTRL+V

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

control_w(self, wait=0)

Press keys CTRL+W

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

copy_to_clipboard(self, 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(self, wait=0)

Press Delete key

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

display_size(self)

Returns the display size in pixels.

Returns:

Type Description
size (Tuple)

The screen dimension (width and height) in pixels.

double_click(self, wait_after=300)

Double Click on the last found element.

Parameters:

Name Type Description Default
wait_after int

Interval to wait after clicking on the element.

300

double_click_relative(self, x, y, interval_between_clicks=0, wait_after=300)

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.

300

enter(self, 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(self, 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(self, 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:

Type Description
element (NamedTuple)

The element coordinates. None if not found.

find_all(self, 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:

Type Description
elements (collections.Iterable[NamedTuple])

A generator with all element coordinates fount. None if not found.

find_app_element(self, 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

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(self, 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

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(self, labels, x=None, y=None, 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.

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:

Type Description
results (dict)

A dictionary in which the key is the label and value are the element coordinates in a NamedTuple.

find_process(self, 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

Returns:

Type Description
process (psutil.Process)

A Process instance.

find_text(self, 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:

Type Description
element (NamedTuple)

The element coordinates. None if not found.

find_until(self, 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:

Type Description
element (NamedTuple)

The element coordinates. None if not found.

get_clipboard(self)

Get the current content in the clipboard.

Returns:

Type Description
text (str)

Current clipboard content

get_element_coords(self, 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:

Type Description
coords (Tuple)

A tuple containing the x and y coordinates for the element.

get_element_coords_centered(self, 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:

Type Description
coords (Tuple)

A tuple containing the x and y coordinates for the center of the element.

get_image_from_map(self, label)

Return an image from teh state image map.

Parameters:

Name Type Description Default
label str

The image identifier

required

Returns:

Type Description
Image

The Image object

get_last_element(self)

Return the last element found.

Returns:

Type Description
element (NamedTuple)

The element coordinates (left, top, width, height)

get_last_x(self)

Get the last X position for the mouse.

Returns:

Type Description
x (int)

The last x position for the mouse.

get_last_y(self)

Get the last Y position for the mouse.

Returns:

Type Description
y (int)

The last y position for the mouse.

get_screenshot(self, 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:

Type Description
Image

The screenshot Image object

hold_shift(self, wait=0)

Hold key Shift

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

kb_type(self, 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(self, wait=0)

Press key End

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

key_enter(self, wait=0)

Press key Enter

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

key_esc(self, wait=0)

Press key Esc

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

key_right(self, wait=0)

Press key Right

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

maximize_window(self)

Shortcut to maximize window on Windows OS.

mouse_down(self, wait_after=300, *, button='left')

Holds down the requested mouse button.

Parameters:

Name Type Description Default
wait_after int

Interval to wait after clicking on the element.

300
button str

One of 'left', 'right', 'middle'. Defaults to 'left'

'left'

mouse_move(self, 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(self, wait_after=300, *, button='left')

Releases the requested mouse button.

Parameters:

Name Type Description Default
wait_after int

Interval to wait after clicking on the element.

300
button str

One of 'left', 'right', 'middle'. Defaults to 'left'

'left'

move(self)

Move to the center position of last found item.

move_random(self, 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(self, 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(self, wait=0)

Press Page Down key

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

page_up(self, wait=0)

Press Page Up key

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

paste(self, 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(self)

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

right_click(self, wait_after=300, *, 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.

300
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(self, 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(self, x, y, interval_between_clicks=0, wait_after=300)

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.

300

save_screenshot(self, 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(self, x, y, width=None, height=None)

Capture a screenshot from a region of the screen.

Parameters:

Name Type Description Default
x int

region start position x

required
y int

region start position y

required
width int

region width

None
height int

region height

None

Returns:

Type Description
Image

The screenshot Image object

screenshot(self, 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:

Type Description
Image

The screenshot Image object

scroll_down(self, clicks)

Scroll Down n clicks

Parameters:

Name Type Description Default
clicks int

Number of times to scroll down.

required

scroll_up(self, clicks)

Scroll Up n clicks

Parameters:

Name Type Description Default
clicks int

Number of times to scroll up.

required

shift_tab(self, wait=0)

Press keys Shift+Tab

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

sleep(self, interval)

Wait / Sleep for a given interval.

Parameters:

Name Type Description Default
interval int

Interval in milliseconds

required

space(self, wait=0)

Press Space key

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

tab(self, 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(self, process)

Terminate the process via the received Process object.

Parameters:

Name Type Description Default
process psutil.Process

The process to terminate.

required

triple_click(self, wait_after=300)

Triple Click on the last found element.

Parameters:

Name Type Description Default
wait_after int

Interval to wait after clicking on the element.

300

triple_click_relative(self, x, y, interval_between_clicks=0, wait_after=300)

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.

300

type_down(self, wait=0)

Press Down key

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

type_key(self, 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(self, 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(self, 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(self, wait=0)

Press Left key

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

type_right(self, wait=0)

Press Right key

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

type_up(self, wait=0)

Press Up key

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

type_windows(self, wait=0)

Press Win logo key

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

wait(self, interval)

Wait / Sleep for a given interval.

Parameters:

Name Type Description Default
interval int

Interval in milliseconds

required

wait_for_file(self, 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