Ir para o conteúdo

Python

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

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

Aqui está um exemplo muito breve de um bot que abre o site da Botcity usando o Google Chrome e o WebDriver do chromedriver para controlar remotamente o navegador.

from botcity.web import WebBot


def main():
    # Instancia o WebBot
    bot = WebBot()

    # Configure se deseja ou não executar no modo headless.
    bot.headless = False

    # Defina o caminho do WebDriver
    bot.driver_path = "<path to your WebDriver binary>"

    # Abre o site do BotCity.
    bot.browse("https://www.botcity.dev")

    # Aguarde 3 segundos antes de fechar.
    bot.wait(3000)

    # Concluir e limpar o navegador da Web.
    bot.stop_browser()


if __name__ == '__main__':
    main()

botcity.web.bot.WebBot (BaseBot)

browser property writable

The web browser to be used.

Returns:

Type Description
browser (Browser)

The web browser to be used.

capabilities property writable

The capabilities to be passed down to the WebDriver when starting the browser.

Returns:

Type Description
capabilities (Dict)

The browser specific capabilities to be used.

driver property readonly

The WebDriver driver instance.

Returns:

Type Description
driver (WebDriver)

The WebDriver driver instance.

headless property writable

Controls whether or not the bot will run headless.

Returns:

Type Description
headless (bool)

Whether or not to run the browser on headless mode.

options property writable

The options to be passed down to the WebDriver when starting the browser.

Returns:

Type Description
options (Options)

The browser specific options to be used.

page_load_strategy: PageLoadStrategy property writable

The page load strategy to be used.

Returns:

Type Description
page_load_strategy (PageLoadStrategy)

The page load strategy to be used.

activate_tab(self, handle)

Activate a tab given by the handle.

Parameters:

Name Type Description Default
handle str

The tab or window handle.

required

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

back(self)

Goes one step backward in the browser history.

backspace(self, wait=0)

Press Backspace key

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

browse(self, url)

Opens the browser on the given URL.

Parameters:

Name Type Description Default
url str

The URL to be visited.

required

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'. Defaults to 'left'

'left'

click_at(self, x, y, *, clicks=1, interval_between_clicks=0, button='left')

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
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'. Defaults to 'left'

'left'

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'. Defaults to 'left'

'left'

close_page(self)

Close the current active page (tab or window).

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

Press keys CTRL+V

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

create_tab(self, url)

Create a new tab and navigate to the given URL.

Parameters:

Name Type Description Default
url str

The desired URL.

required

create_window(self, url)

Creates a new window with the given URL.

Parameters:

Name Type Description Default
url str

The desired URL.

required

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)

Press key Enter

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

enter_iframe(self, iframe)

Switch the WebBot driver to the specified iframe.

Parameters:

Name Type Description Default
iframe WebElement

The desired iFrame.

required

execute_javascript(self, code)

Execute the given javascript code.

Parameters:

Name Type Description Default
code str

The code to be executed.

required

Returns:

Type Description
value (object)

Returns the code output or None if not available or if an error happens.

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, as_list=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
as_list bool, Optional

If True, returns a list of element coordinates instead of a generator. Use set_active_element() to be able to interact with the found elements. This parameter must be True if you intend to run multiple find_all() concurrently. Defaults to False.

False

Returns:

Type Description
elements (collections.Iterable[NamedTuple])

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

find_element(self, selector, by='css selector', waiting_time=10000, ensure_visible=False, ensure_clickable=False)

Find an element using the specified selector with selector type specified by by. If more than one element is found, the first instance is returned.

Parameters:

Name Type Description Default
selector str

The selector string to be used.

required
by str

Selector type. Defaults to By.CSS_SELECTOR. See more

'css selector'
waiting_time int

Maximum wait time (ms) to search for a hit. Defaults to 10000ms (10s).

10000
ensure_visible bool

Whether to wait for the element to be visible. Defaults to False.

False
ensure_clickable bool

Whether to wait for the element to be clickable. Defaults to False. If True, ensure_clickable takes precedence over ensure_visible.

False

Returns:

Type Description
WebElement

The element found.

Example:

from botcity.web import By
...
# Find element by ID
elem = self.find_element("my_elem", By.ID)
# Find element by XPath
elem = self.find_element("//input[@type='submit']", By.XPATH)
...

find_elements(self, selector, by='css selector', waiting_time=10000, ensure_visible=True)

Find elements using the specified selector with selector type specified by by.

Parameters:

Name Type Description Default
selector str

The selector string to be used.

required
by str

Selector type. Defaults to By.CSS_SELECTOR. See more

'css selector'
waiting_time int

Maximum wait time (ms) to search for a hit. Defaults to 10000ms (10s).

10000
ensure_visible bool

Whether to wait for the element to be visible. Defaults to True.

True

Returns:

Type Description
List[WebElement]

List of elements found.

Example:

from botcity.web import By
...
# Find element by ID
all_cells = self.find_elements("//td", By.XPATH)
...

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_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.

forward(self)

Goes one step forward in the browser history.

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_file_count(self, path=None, file_extension='')

Get the total number of files of the same type.

Parameters:

Name Type Description Default
path str

The path of the folder where the files are saved.

None
file_extension str

The extension of the files to be searched for (e.g., .pdf, .txt).

''

Returns:

Type Description
int

the number of files of the given type

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_js_dialog(self)

Return the last found dialog. Invoke first the find_js_dialog method to look up.

Returns:

Type Description
dialog (dict)

The dialog information or None if not available. See https://chromedevtools.github.io/devtools-protocol/tot/Page/#event-javascriptDialogOpening

get_last_created_file(self, path=None, file_extension='')

Returns the last created file in a specific folder path.

Parameters:

Name Type Description Default
path str

The path of the folder where the file is expected. Defaults to None.

None
file_extension str

The extension of the file to be searched for (e.g., .pdf, .txt).

''

Returns:

Type Description
str

the path of the last created file

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_screen_image(self, region=None)

Capture and returns a screenshot from the browser.

Parameters:

Name Type Description Default
region tuple

A tuple containing the left, top, width and height to crop the screen image.

None

Returns:

Type Description
image (Image)

The screenshot Image object.

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

get_tabs(self)

Get a list of tab handlers

Returns:

Type Description
list

List of tab handlers

get_viewport_size(self)

Returns the browser current viewport size.

Returns:

Type Description
width (int)

The current viewport width. height (int): The current viewport height.

handle_js_dialog(self, accept=True, prompt_text=None)

Accepts or dismisses a JavaScript initiated dialog (alert, confirm, prompt, or onbeforeunload). This also cleans the dialog information in the local buffer.

Parameters:

Name Type Description Default
accept bool

Whether to accept or dismiss the dialog.

True
prompt_text str

The text to enter into the dialog prompt before accepting. Used only if this is a prompt dialog.

None

hold_shift(self, wait=0)

Hold key Shift

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

install_firefox_extension(self, extension)

Install an extension in the Firefox browser. This will start the browser if it was not started yet.

Parameters:

Name Type Description Default
extension str

The path of the .xpi extension to be loaded.

required

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

Press key Home

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

leave_iframe(self)

Leave the iframe and switch the WebBot driver to the default content.

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)

Mouse the move 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

move_to(self, x, y)

Move the mouse relative to its current position.

Parameters:

Name Type Description Default
x int

The X coordinate

required
y int

The Y coordinate

required

navigate_to(self, url, is_retry=False)

Opens the browser on the given URL.

Parameters:

Name Type Description Default
url str

The URL to be visited.

required
is_retry bool

Whether or not this is a retry attempt.

False

page_down(self, wait=0)

Press Page Down key

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

page_source(self)

Returns the active page source.

Returns:

Type Description
soup (BeautifulSoup)

BeautifulSoup object for the page source.

page_title(self)

Returns the active page title.

Returns:

Type Description
title (str)

The page title.

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

print_pdf(self, path=None, print_options=None)

Print the current page as a PDF file.

Parameters:

Name Type Description Default
path str

The path for the file to be saved. Defaults to None.

None
print_options dict

Print options as defined at. Defaults to None.

None

Returns:

Type Description
str

the saved file path

refresh(self)

Refreshes the current page.

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_element(self, element, steps=100, interval=500, start=0, end=None)

Scrolls down an element by its scroll height or a given amount defined by start and end.

This is useful for scrolling down a page to load more content or to scroll down a dynamically loaded element.

Parameters:

Name Type Description Default
element WebElement

The element to scroll.

required
steps int

Number of steps in which to conclude the scroll. Defaults to 100.

100
interval float

Time interval between each step. Defaults to 500ms.

500
start int

Start position. Defaults to 0.

0
end int

End position. Defaults to None.

None

scroll_up(self, clicks)

Scroll Up n clicks

Parameters:

Name Type Description Default
clicks int

Number of times to scroll up.

required

set_current_element(self, element)

Changes the current screen element the bot will interact when using click(), move(), and similar methods.

This method is equivalent to self.state.element = element.

Parameters:

Name Type Description Default
element Box

A screen element from self.state.element or the find_all(as_list=True) method.

required

set_file_input_element(self, element, filepath)

Configure the filepath for upload in a file element. Note: This method does not submit the form.

Parameters:

Name Type Description Default
element WebElement

The file upload element.

required
filepath str

The path to the file to be uploaded.

required

Example:

...
# Find element
elem = self.find_element("body > form > input[type=file]")
# Set the filepath
self.set_file_input_element(elem, "./test.txt")
...

set_screen_resolution(self, width=None, height=None)

Configures the browser dimensions.

Parameters:

Name Type Description Default
width int

The desired width.

None
height int

The desired height.

None

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

start_browser(self)

Starts the selected browser.

stop_browser(self)

Stops the Chrome browser and clean up the User Data Directory.

Warning

After invoking this method, you will need to reassign your custom options and capabilities.

tab(self, wait=0)

Press key Tab

Parameters:

Name Type Description Default
wait int

Wait interval (ms) after task

0

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_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

wait(self, interval)

Wait / Sleep for a given interval.

Parameters:

Name Type Description Default
interval int

Interval in milliseconds

required

wait_for_downloads(self, timeout=120000)

Wait for all downloads to be finished. Beware that this method replaces the current page with the downloads window.

Parameters:

Name Type Description Default
timeout int

Timeout in millis. Defaults to 120000.

120000

wait_for_element_visibility(self, element, visible=True, waiting_time=10000)

Wait for the element to be visible or hidden.

Parameters:

Name Type Description Default
element WebElement

The element to wait for.

required
visible bool

Whether to wait for the element to be visible. Defaults to True.

True
waiting_time int

Maximum wait time (ms) to search for a hit. Defaults to 10000ms (10s).

10000

wait_for_file(self, path, timeout=60000)

Wait for a file to be available on disk.

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 60000ms (60s).

60000

Returns:

Type Description
status (bool)

Whether or not the file was available before the timeout

wait_for_new_file(self, path=None, file_extension='', current_count=0, timeout=60000)

Wait for a new file to be available on disk without the file path.

Parameters:

Name Type Description Default
path str

The path of the folder where the file is expected. Defaults to None.

None
file_extension str

The extension of the file to be searched for (e.g., .pdf, .txt).

''
current_count int

The current number of files in the folder of the given type. Defaults to 0 files

0
timeout int

Maximum wait time (ms) to search for a hit. Defaults to 60000ms (60s).

60000

Returns:

Type Description
str

the path of the last created file of the given type

wait_for_new_page(self, waiting_time=10000, activate=True)

Context manager to wait for a new page to load and activate it.

Parameters:

Name Type Description Default
waiting_time int

The maximum waiting time. Defaults to 10000.

10000
activate bool

Whether or not to activate the new page. Defaults to True.

True

wait_for_stale_element(self, element, timeout=10000)

Wait until the WebElement element becomes stale (outdated).

Parameters:

Name Type Description Default
element WebElement

The element to monitor for staleness.

required
timeout int

Timeout in millis. Defaults to 120000.

10000

Módulos específicos do navegador

Aqui está a documentação para os métodos mencionados acima para cada um dos navegadores suportados.

Chrome

botcity.web.browsers.chrome.default_options(headless=False, download_folder_path=None, user_data_dir=None, page_load_strategy='normal')

Retrieve the default options for this browser curated by BotCity.

Parameters:

Name Type Description Default
headless bool

Whether or not to use the headless mode. Defaults to False.

False
download_folder_path str

The default path in which to save files. If None, the current directory is used. Defaults to None.

None
user_data_dir [type]

The directory to use as user profile. If None, a new temporary directory is used. Defaults to None.

None
page_load_strategy str

The page load strategy. Defaults to "normal".

'normal'

Returns:

Type Description
ChromeOptions

The Chrome options.

botcity.web.browsers.chrome.default_capabilities()

Fetch the default capabilities for this browser.

Returns:

Type Description
Dict

Dictionary with the default capabilities defined.

Firefox

botcity.web.browsers.firefox.default_options(headless=False, download_folder_path=None, user_data_dir=None, page_load_strategy='normal')

Retrieve the default options for this browser curated by BotCity.

Parameters:

Name Type Description Default
headless bool

Whether or not to use the headless mode. Defaults to False.

False
download_folder_path str

The default path in which to save files. If None, the current directory is used. Defaults to None.

None
user_data_dir [type]

The directory to use as user profile. If None, a new temporary directory is used. Defaults to None.

None
page_load_strategy str

The page load strategy to use.

'normal'

Returns:

Type Description
FirefoxOptions

The Firefox options.

botcity.web.browsers.firefox.default_capabilities()

Fetch the default capabilities for this browser.

Returns:

Type Description
Dict

Dictionary with the default capabilities defined.

Edge

botcity.web.browsers.edge.default_options(headless=False, download_folder_path=None, user_data_dir=None, page_load_strategy='normal')

Retrieve the default options for this browser curated by BotCity.

Parameters:

Name Type Description Default
headless bool

Whether or not to use the headless mode. Defaults to False.

False
download_folder_path str

The default path in which to save files. If None, the current directory is used. Defaults to None.

None
user_data_dir [type]

The directory to use as user profile. If None, a new temporary directory is used. Defaults to None.

None
page_load_strategy str

The page load strategy. Defaults to "normal".

'normal'

Returns:

Type Description
EdgeOptions

The Edge options.

botcity.web.browsers.edge.default_capabilities()

Fetch the default capabilities for this browser.

Returns:

Type Description
Dict

Dictionary with the default capabilities defined.

IE

botcity.web.browsers.ie.default_options(headless=False, download_folder_path=None, user_data_dir=None, page_load_strategy='normal')

Retrieve the default options for this browser curated by BotCity.

Returns:

Type Description
Options

The Internet Explorer options.

botcity.web.browsers.ie.default_capabilities()

Fetch the default capabilities for this browser.

Returns:

Type Description
Dict

Dictionary with the default capabilities defined.

Form Utilities

botcity.web.util.element_as_select(element)

Wraps a WebElement in a Select object.

Parameters:

Name Type Description Default
element WebElement

The element to wrap.

required

Returns:

Type Description
Select

The Select object.

Parsers

Tables

botcity.web.parsers.table_to_dict(table, has_header=True, skip_rows=0, header_tag='th', cell_xpath=None)

Convert a table WebElement to a dict of lists.

Parameters:

Name Type Description Default
table WebElement

The table element.

required
has_header bool

Whether or not to parse a header. Defaults to True.

True
skip_rows int

Number of rows to skip from the top. Defaults to 0.

0
header_tag str

The HTML tag associated with the header cell. Defaults to "th".

'th'
cell_xpath str

Optional cell XPath selector for complex row constructions. If cell_xpath is not informed, the row data will come from <td> elements.

None

Returns:

Type Description
list

List with dict for each row.