Python¶

The botcity.web module contains specialized implementations aimed at Web automation such as WebBot which is described below.

When instantiating a WebBot, you will have access to the methods responsible for automating applications and processes in the browser.

Here is a very brief example of a bot that opens the BotCity website using Google Chrome and the ChromeDriver WebDriver to remote control the browser.

from botcity.web import WebBot


def main():
    # Instantiate the WebBot
    bot = WebBot()

    # Configure whether or not to run on headless mode
    bot.headless = False

    # Set the WebDriver path
    bot.driver_path = "<path to your WebDriver binary>"

    # Opens the BotCity website.
    bot.browse("https://www.botcity.dev")

    # Wait 3 seconds before closing
    bot.wait(3000)

    # Finish and clean up the Web Browser
    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`

Specific Browser Modules¶

Here are the documentation for the methods mentioned above for each of the supported browsers.

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.

Python¶

botcity.web.bot.WebBot (BaseBot) ¶

browser property writable ¶

capabilities property writable ¶

driver property readonly ¶

headless property writable ¶

options property writable ¶

page_load_strategy: PageLoadStrategy property writable ¶

activate_tab(self, handle) ¶

add_image(self, label, path) ¶

back(self) ¶

backspace(self, wait=0) ¶

browse(self, url) ¶

click(self, wait_after=300, *, clicks=1, interval_between_clicks=0, button='left') ¶

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

click_on(self, label) ¶

click_relative(self, x, y, wait_after=300, *, clicks=1, interval_between_clicks=0, button='left') ¶

close_page(self) ¶

control_a(self, wait=0) ¶

control_c(self, wait=0) ¶

control_v(self, wait=0) ¶

copy_to_clipboard(self, text, wait=0) ¶

create_tab(self, url) ¶

create_window(self, url) ¶

delete(self, wait=0) ¶

display_size(self) ¶

double_click(self, wait_after=300) ¶

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

enter(self, wait=0) ¶

enter_iframe(self, iframe) ¶

execute_javascript(self, code) ¶

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

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_element(self, selector, by='css selector', waiting_time=10000, ensure_visible=False, ensure_clickable=False) ¶

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

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_text(self, label, x=None, y=None, width=None, height=None, *, threshold=None, matching=0.9, waiting_time=10000, best=True) ¶

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

forward(self) ¶

get_clipboard(self) ¶

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

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

get_file_count(self, path=None, file_extension='') ¶

get_image_from_map(self, label) ¶

get_js_dialog(self) ¶

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

get_last_element(self) ¶

get_last_x(self) ¶

get_last_y(self) ¶

get_screen_image(self, region=None) ¶

get_screenshot(self, filepath=None, region=None) ¶

get_tabs(self) ¶

get_viewport_size(self) ¶

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

hold_shift(self, wait=0) ¶

install_firefox_extension(self, extension) ¶

kb_type(self, text, interval=0) ¶

key_end(self, wait=0) ¶

key_enter(self, wait=0) ¶

key_esc(self, wait=0) ¶

key_home(self, wait=0) ¶

key_right(self, wait=0) ¶

leave_iframe(self) ¶

maximize_window(self) ¶

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

mouse_move(self, x, y) ¶

mouse_up(self, wait_after=300, *, button='left') ¶

move(self) ¶

move_random(self, range_x, range_y) ¶

move_relative(self, x, y) ¶

move_to(self, x, y) ¶

navigate_to(self, url, is_retry=False) ¶

page_down(self, wait=0) ¶

page_source(self) ¶

page_title(self) ¶

page_up(self, wait=0) ¶

paste(self, text=None, wait=0) ¶

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

refresh(self) ¶

release_shift(self) ¶

`botcity.web.bot.WebBot (BaseBot)` ¶

`browser` `property` `writable` ¶

`capabilities` `property` `writable` ¶

`driver` `property` `readonly` ¶

`headless` `property` `writable` ¶

`options` `property` `writable` ¶

`page_load_strategy: PageLoadStrategy` `property` `writable` ¶

`activate_tab(self, handle)` ¶

`add_image(self, label, path)` ¶

`back(self)` ¶

`backspace(self, wait=0)` ¶

`browse(self, url)` ¶

`click(self, wait_after=300, *, clicks=1, interval_between_clicks=0, button='left')` ¶

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

`click_on(self, label)` ¶

`click_relative(self, x, y, wait_after=300, *, clicks=1, interval_between_clicks=0, button='left')` ¶

`close_page(self)` ¶

`control_a(self, wait=0)` ¶

`control_c(self, wait=0)` ¶

`control_v(self, wait=0)` ¶

`copy_to_clipboard(self, text, wait=0)` ¶

`create_tab(self, url)` ¶

`create_window(self, url)` ¶

`delete(self, wait=0)` ¶

`display_size(self)` ¶

`double_click(self, wait_after=300)` ¶

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

`enter(self, wait=0)` ¶

`enter_iframe(self, iframe)` ¶

`execute_javascript(self, code)` ¶

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

`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_element(self, selector, by='css selector', waiting_time=10000, ensure_visible=False, ensure_clickable=False)` ¶

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

`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_text(self, label, x=None, y=None, width=None, height=None, *, threshold=None, matching=0.9, waiting_time=10000, best=True)` ¶

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

`forward(self)` ¶

`get_clipboard(self)` ¶

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

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

`get_file_count(self, path=None, file_extension='')` ¶

`get_image_from_map(self, label)` ¶

`get_js_dialog(self)` ¶

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

`get_last_element(self)` ¶

`get_last_x(self)` ¶

`get_last_y(self)` ¶

`get_screen_image(self, region=None)` ¶

`get_screenshot(self, filepath=None, region=None)` ¶

`get_tabs(self)` ¶

`get_viewport_size(self)` ¶

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

`hold_shift(self, wait=0)` ¶

`install_firefox_extension(self, extension)` ¶

`kb_type(self, text, interval=0)` ¶

`key_end(self, wait=0)` ¶

`key_enter(self, wait=0)` ¶

`key_esc(self, wait=0)` ¶

`key_home(self, wait=0)` ¶

`key_right(self, wait=0)` ¶

`leave_iframe(self)` ¶

`maximize_window(self)` ¶

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

`mouse_move(self, x, y)` ¶

`mouse_up(self, wait_after=300, *, button='left')` ¶

`move(self)` ¶

`move_random(self, range_x, range_y)` ¶

`move_relative(self, x, y)` ¶

`move_to(self, x, y)` ¶

`navigate_to(self, url, is_retry=False)` ¶

`page_down(self, wait=0)` ¶

`page_source(self)` ¶

`page_title(self)` ¶

`page_up(self, wait=0)` ¶

`paste(self, text=None, wait=0)` ¶

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

`refresh(self)` ¶

`release_shift(self)` ¶

`right_click(self, wait_after=300, *, clicks=1, interval_between_clicks=0)` ¶