## Asyncronous implementation of web browser automation for Python.
Created to be used in a project, this package is published to github for ease of management and installation across different modules.
### Features
- **Asynchronous Execution**: Aselenium is inspired by the [HENNGE/arsenic](https://github.com/HENNGE/arsenic) project, enabling multiple browser sessions to run concurrently. This allows Python to execute other async tasks without being blocked by time-consuming browser actions.
- **Webdriver Management**: Aselenium integrates the webdriver installation and management, taking inspiration from the [SergeyPirogov/webdriver_manager](https://github.com/SergeyPirogov/webdriver_manager) project. It provides a simple interface for user to install the proper/desired webdriver for different browsers cross platforms.
- **Browser Support**: Aselenium supports popular browsers such as Chrome, Chromium, Edge, Firefox, and Safari.
### Installation
Install from `PyPi`
``` bash
pip install aselenium
```
Install from `github`
``` bash
pip install git+https://github.com/AresJef/Aselenium.git
```
### Compatibility
Only support for python 3.10 and above.
### Chrome Automation
``` python
from aselenium import Chrome
driver = Chrome(
# optional: the directory to store the webdrivers.
directory="/path/to/driver/cache/directory"
# optional: the maximum amount of webdrivers (and CTF browsers) to maintain.
max_cache_size=10
)
# Set options
driver.options.add_arguments('--headless', '--disable-gpu')
...
# Acquire a chrome session
async with driver.acquire("build", "dev") as session
# explain: install webdriver that has the same major & build
# version as the Chrome [dev] browser installed in the system,
# and start a new session with the dev browser.
await session.load("https://www.google.com")
# . do some automated tasks
...
# Acquire a CFT [Chrome for Testing] session
async with driver.acquire("119.0.6045", "cft") as session:
# explain: install both the webdriver and CFT browser with the
# same build version '119.0.6045', and start a new session with
# the CFT browser.
await session.load("https://www.google.com")
# . do some automated tasks
...
```
### Edge Automation
``` python
from aselenium import Edge
driver = Edge()
# Set options
driver.options.add_arguments('--headless', '--disable-gpu')
...
# Acquire an edge session
async with driver.acquire("build", "stable") as session:
# explain: install webdriver that has the same major & build
# version as the Edge [stable] browser installed in the system,
# and start a new session with the stable Edge browser.
await session.load("https://www.google.com")
# . do some automated tasks
...
```
### Firefox Automation
``` python
from aselenium import Firefox
driver = Firefox()
# Set options
driver.options.add_arguments('--headless', '--disable-gpu')
...
# Acquire a firefox session
async with driver.acquire("latest") as session:
# explain: install the latest geckodriver available at
# [Mozilla Github] repository that is compatible with
# the installed Firefox browser, and start a new session.
await session.load("https://www.google.com")
# . do some automated tasks
...
```
### Options configuration
Setting options for aselenium drivers does not require to import an Options class. Instead, the options can be accessed directly from the driver instance. The following example shows how to set options for Chrome, but the same method (if applicable) can also apply to other browsers.
``` python
from aselenium import Chrome, Proxy
driver = Chrome()
# . accept Insecure Certs
driver.options.accept_insecure_certs = True
# . page Load Strategy
driver.options.page_load_strategy = "eager"
# . proxy
proxy = Proxy(
http_proxy="http://127.0.0.1:7890",
https_proxy="http://127.0.0.1:7890",
socks_proxy="socks5://127.0.0.1:7890",
)
driver.options.proxy = proxy
# . timeout
driver.options.set_timeouts(implicit=5, pageLoad=10)
# . strict file interactability
driver.options.strict_file_interactability = True
# . prompt behavior
driver.options.unhandled_prompt_behavior = "dismiss"
# . arguments
driver.options.add_arguments("--disable-gpu", "--disable-dev-shm-usage")
# . preferences [Keywork Arguments]
driver.options.set_preferences(
**{
"download.default_directory": "/path/to/download/directory",
"download.prompt_for_download": False,
"download.directory_upgrade": True,
"safebrowsing.enabled": True
}
)
# . experimental options [Keywork Arguments]
driver.options.add_experimental_options(
excludeSwitches=["enable-automation", "enable-logging"]
)
...
```
### Profile configuration
The options of aselenium drivers provides the 'set_profile' method to configure the profile of the browser. By using this method, a cloned temporary profile will be created based on the specified profile directory, leaving the original profile untouched. When the driver is no longer in use, the temporary profile will be deleted automatically. The following example shows how to set profile for Chrome, but the same method (if applicable) can also apply to other browsers.
``` python
from aselenium import Chrome
driver = Chrome()
driver.options.set_profile(
# . the default profile directory for Chrome on MacOS
directory="~/Library/Application Support/Google/Chrome",
profile="Default",
)
```
### Navigation
``` python
from aselenium import Chrome
driver = Chrome()
async with driver.acquire() as session:
# . load a url
await session.load("https://www.google.com")
# . explicitly wait for page loading: url
res = await session.wait_until_url("contains", "google", timeout=10) # True / False
# . explicitly wait for page loading: title
res = await session.wait_until_title("startswith", "Google", timeout=10) # True / False
# . backward
await session.backward()
# . forward
await session.forward()
# . refresh
await session.refresh()
```
### Page Information
``` python
from aselenium import Chrome
driver = Chrome()
async with driver.acquire() as session:
await session.load("https://www.google.com")
# . access page url [property]
url = await session.url # https://www.google.com
# . access page title [property]
title = await session.title # Google
# . access page viewport [property]
viewport = await session.viewport # <Viewport (width=1200, height=776, x=0, y=2143)>
# . access page width [property]
width = await session.width # 1200
# . access page height [property]
height = await session.height # 776
# . access page source [property]
source = await session.source # <!DOCTYPE html><html itemscope="" itemtype="http://...
# . take screenshot
data = await session.screenshot() # b'\x89PNG\r\n\x1a\n\x00\x00\x00\...
# . save screenshot
await session.save_screenshot("~/path/to/screenshot.png") # True / False
# . print page
data = await session.print_page() # b'%PDF-1.4\n%\xe2\xe3\xcf\xd3\n1...
# . save page
await session.save_page("~/path/to/page.pdf") # True / False
```
### Session Timeouts
``` python
from aselenium import Chrome
driver = Chrome()
async with driver.acquire() as session:
# . access timeouts of the session [property]
timeouts = await options.timeouts
# <Timeouts (implicity=0, pageLoad=300000, script=30000, unit='ms')>
# . set timeouts of the session
timeouts = await session.set_timeouts(implicit=0.1, pageLoad=30, script=3)
# <Timeouts (implicity=100, pageLoad=30000, script=3000, unit='ms')>
# . reset timeouts of the session
timeouts = await session.reset_timeouts()
# <Timeouts (implicity=0, pageLoad=300000, script=30000, unit='ms')>
```
### Session Windows
``` python
from aselenium import Chrome
driver = Chrome()
async with driver.acquire() as session:
await session.load("https://www.google.com")
# . access the active window [property]
win = await session.active_window
# <Window (name='default', handle='CCEF49C484842CFE1AB855ECCA164858')>
# . rename a window
win = await session.rename_window("default", "google")
# <Window (name='google', handle='CCEF49C484842CFE1AB855ECCA164858')>
# . open a new window
win = await session.new_window("baidu", "tab")
# <Window (name='baidu', handle='B89293FA79B6389AF1657B972FBD6B26')>
await session.load("https://www.baidu.com")
# . access all opened windows [property]
wins = await session.windows
# [
# <Window (name='google', handle='CCEF49C484842CFE1AB855ECCA164858')>
# <Window (name='baidu', handle='B89293FA79B6389AF1657B972FBD6B26')>
# ]
# . close current window
await session.close_window(switch_to="google")
# <Window (name='google', handle='CCEF49C484842CFE1AB855ECCA164858')>
# . access window rect [property]
rect = await session.window_rect
# <WindowRect (width=1200, height=900, x=22, y=60)>
# . set window rect
rect = await session.set_window_rect(800, 500)
# <WindowRect (width=800, height=500, x=22, y=60)>
# . maximize window
await session.maximize_window()
# . minimize window
await session.minimize_window()
# . fullscreen window
await session.fullscreen_window()
```
### Active Window Cookies
``` python
from aselenium import Chrome, Cookie
driver = Chrome()
async with driver.acquire() as session:
await session.load("https://www.baidu.com")
# . access all cookies [property]
cookies = await session.cookies
# [
# <Cookie (name='ZFY', data={'domain': '.baidu.com', 'expiry': 1720493275, ...})>
# <Cookie (name='ZFK', data={'domain': '.baidu.com', 'expiry': 1720493275, ...})>
# ...
# ]
# . get a cookie
cookie = await session.get_cookie("ZFY")
# <Cookie (name='ZFY', data={'domain': '.baidu.com', 'expiry': 1720493275, ...})>
# . add a cookie
await session.add_cookie({"name": "test_cookie2", "value": "123456", "domain": ".baidu.com"})
# // or //
test_cookie2 = Cookie(name="test_cookie1", value="123456", domain=".baidu.com")
await session.add_cookie(test_cookie2)
# . delete a cookie
await session.delete_cookie("test_cookie1")
# // or //
await session.delete_cookie(test_cookie2)
```
### JavaScript Execution
Notice that some of the following methods are not async functions, therefore should not be awaited.
``` python
from aselenium import Chrome
driver = Chrome()
async with driver.acquire() as session:
await session.load("https://www.google.com")
# . execute a raw javascript
res = await session.execute_script("return document.title;") # Google
# . cache a javascript
js = session.cache_script("get_title", "return document.title;")
# <JavaScript (name='get_title', script='return document.title;', args=[])>
# . access all cached javascripts
scripts = session.scripts
# [<JavaScript (name='get_title', script='return document.title;', args=[])>]
# . get a cached javascript
js = session.get_script("get_title")
# <JavaScript (name='get_title', script='return document.title;', args=[])>
# . execute cached javascript
res = await session.execute_script(js) # Google
# // or //
res = await session.execute_script("get_title") # Google
# . rename cached javascript
js = session.rename_script("get_title", "access_title")
# // or //
js = session.rename_script(js, "access_title")
# <JavaScript (name='access_title', script='return document.title;', args=[])>
# . remove cached javascript
session.remove_script(js)
# // or //
session.remove_script("access_title")
```
### Element Interaction
``` python
from aselenium import Chrome
driver = Chrome()
async with driver.acquire() as session:
await session.load("https://www.baidu.com")
# . find element
element = await session.find_element("#kw", by="css")
# <Element (id='289DEC2B8885F15A2BDD2E92AC0404F3_element_1', session='1e78...', service='http://...')>
# . find elements
elements = await session.find_elements(".s_ipt", by="css")
# [
# <Element (id='289DEC2B8885F15A2BDD2E92AC0404F3_element_2', session='1e78...', service='http://...')>
# <Element (id='289DEC2B8885F15A2BDD2E92AC0404F3_element_3', session='1e78...', service='http://...')>
# ...
# ]
# . find the 1st located element among selectors
element = await session.find_1st_element("#kw", ".s_ipt", by="css")
# <Element (id='289DEC2B8885F15A2BDD2E92AC0404F3_element_1', session='1e78...', service='http://...')>
# . explicit wait for element
res = await session.wait_until_element("visible", "#kw", by="css", timeout=10) # True
res = await session.wait_until_element("gone", "#kw", by="css", timeout=10) # False
# . explicit wait for elements
res = await session.wait_until_elements(
"exist", "#kw", ".s_ipt", by="css", all_=True, timeout=10
) # True
res = await session.wait_until_elements(
"selected", "#kw", ".s_ipt", by="css", all_=True, timeout=10
) # False
# . access element properties
exists = await element.exists # True
visible = await element.visible # True
viewable = await element.viewable # True
enabled = await element.enabled # True
selected = await element.selected # False
tag = await element.tag # input
text = await element.text # None
rect = await element.rect # <ElementRect (width=500, height=22, x=522, y=217)>
aria_role = await element.aria_role # None
aria_label = await element.aria_label # None
...
# . element interaction
await element.click()
await element.send("Hello World!")
await element.clear()
await element.upload("~/path/to/file.png")
await element.scroll_into_view()
...
```
### Actions Chain
Actions chain allows the browser to perform a series of low-level interactions such as mouse movements, key presses, and wheel scrolls.
- For Chromium-based browsers like Chrome, Chromium, and Edge, the actions chain execution passes most tests, including 'drag_and_drop'.
- For Firefox, the actions chain execution fails the 'drag_and_drop' test. Additionally, user must explicitly block the code execution until all actions are completed. This is because geckodriver returns a response immediately after receiving the actions command (where chromedriver only returns a response when all actions are completed). To do so, user can choose to use the 'explicit_wait' argument in the 'perform()' method to wait the specified amount of seconds, or implement a custom logic right after the actions chain execution.
``` python
from aselenium import Chrome, KeyboardKeys
driver = Chrome()
async with driver.acquire() as session:
# Actions chain
await session.load("https://www.baidu.com")
search_button = await session.find_element("#su", by="css")
(
await session.actions()
# . move mouse to the element
.move_to(element=search_button)
# . click the element
.click(pause=1)
# . send text
.send_keys("Hello World!", pause=1)
# . select all (control + a)
.send_key_combo(KeyboardKeys.CONTROL, "a", pause=1)
# . cut (control + x)
.send_key_combo(KeyboardKeys.CONTROL, "x", pause=1)
# . paste (control + v)
.send_key_combo(KeyboardKeys.CONTROL, "v", pause=1)
# . enter
.send_keys(KeyboardKeys.ENTER, pause=1)
# . scroll wheel
.scroll_by(y=500, pause=1)
# . execute the actions chain
.perform()
# For Firefox, specify an explicit wait time to wait for the
# actions to complete: `.perform(explicit_wait=20)`.
)
# Drag and drop
await session.load("https://www.w3schools.com/html/html5_draganddrop.asp")
l_element = await session.find_element("#div1", by="css")
r_element = await session.find_element("#div2", by="css")
(
await session.actions()
# . drag and drop: left -> right
.drag_and_drop(drag=l_element, drop=r_element, pause=1)
# . drag and drop: right -> left
.drag_and_drop(drag=r_element, drop=l_element, pause=1)
# . execute the actions chain
.perform()
# For Firefox, `drag_and_drop` is not supported.
)
```
### Known Issues
- For Linux users, browsers installed through 'snap store' will failed due to the 'snap' sandbox. Snap version of the browsers lack the permissions to create and access a temporary profile out side of snap, which is required by the webdriver to start the browser. The most straight forward solution is to uninstall the snap version and re-install the browser through the official website.
- For Firefox, the actions chain does not work quite as expected. If actions chain is important for the project, consider using Chromium-based browsers instead.
- Safari is supported by aselenium, but limited to some basic functionalities, and not recommended to use for critical automations. The webdriver for Safari yeilds many unexpected errors and sometimes even crashes the browser and program.
### Acknowledgements
aselenium is based on several open-source repositories.
- [aiohttp](https://github.com/aio-libs/aiohttp)
- [psutil](https://github.com/giampaolo/psutil)
- [orjson](https://github.com/ijl/orjson)
aselenium is inspired from and makes modifications of the following open-source repositories:
- [arsenic](https://github.com/HENNGE/arsenic)
- [selenium](https://github.com/SeleniumHQ/selenium)
- [webdriver-manager](https://github.com/SergeyPirogov/webdriver_manager)
Raw data
{
"_id": null,
"home_page": "https://github.com/AresJef/Aselenium",
"name": "aselenium",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "async,asyncronous,automation,arsenic,selenium",
"author": "Jiefu Chen",
"author_email": "keppa1991@163.com",
"download_url": "https://files.pythonhosted.org/packages/f6/46/6c3f593ecf85c33720d4c8a4bfc07ed0d4f8fa8042005e3574190f871e83/aselenium-0.1.13.4.tar.gz",
"platform": null,
"description": "## Asyncronous implementation of web browser automation for Python.\n\nCreated to be used in a project, this package is published to github for ease of management and installation across different modules.\n\n### Features\n- **Asynchronous Execution**: Aselenium is inspired by the [HENNGE/arsenic](https://github.com/HENNGE/arsenic) project, enabling multiple browser sessions to run concurrently. This allows Python to execute other async tasks without being blocked by time-consuming browser actions.\n\n- **Webdriver Management**: Aselenium integrates the webdriver installation and management, taking inspiration from the [SergeyPirogov/webdriver_manager](https://github.com/SergeyPirogov/webdriver_manager) project. It provides a simple interface for user to install the proper/desired webdriver for different browsers cross platforms.\n\n- **Browser Support**: Aselenium supports popular browsers such as Chrome, Chromium, Edge, Firefox, and Safari.\n\n### Installation\nInstall from `PyPi`\n``` bash\npip install aselenium\n```\n\nInstall from `github`\n``` bash\npip install git+https://github.com/AresJef/Aselenium.git\n```\n\n### Compatibility\nOnly support for python 3.10 and above.\n\n### Chrome Automation\n``` python\nfrom aselenium import Chrome\ndriver = Chrome(\n # optional: the directory to store the webdrivers.\n directory=\"/path/to/driver/cache/directory\"\n # optional: the maximum amount of webdrivers (and CTF browsers) to maintain.\n max_cache_size=10\n)\n\n# Set options\ndriver.options.add_arguments('--headless', '--disable-gpu')\n...\n\n# Acquire a chrome session\nasync with driver.acquire(\"build\", \"dev\") as session\n # explain: install webdriver that has the same major & build\n # version as the Chrome [dev] browser installed in the system,\n # and start a new session with the dev browser.\n await session.load(\"https://www.google.com\")\n # . do some automated tasks\n ...\n\n# Acquire a CFT [Chrome for Testing] session\nasync with driver.acquire(\"119.0.6045\", \"cft\") as session:\n # explain: install both the webdriver and CFT browser with the \n # same build version '119.0.6045', and start a new session with \n # the CFT browser.\n await session.load(\"https://www.google.com\")\n # . do some automated tasks\n ...\n```\n\n### Edge Automation\n``` python\nfrom aselenium import Edge\ndriver = Edge()\n\n# Set options\ndriver.options.add_arguments('--headless', '--disable-gpu')\n...\n\n# Acquire an edge session\nasync with driver.acquire(\"build\", \"stable\") as session:\n # explain: install webdriver that has the same major & build\n # version as the Edge [stable] browser installed in the system,\n # and start a new session with the stable Edge browser.\n await session.load(\"https://www.google.com\")\n # . do some automated tasks\n ...\n```\n\n### Firefox Automation\n``` python\nfrom aselenium import Firefox\ndriver = Firefox()\n\n# Set options\ndriver.options.add_arguments('--headless', '--disable-gpu')\n...\n\n# Acquire a firefox session\nasync with driver.acquire(\"latest\") as session:\n # explain: install the latest geckodriver available at\n # [Mozilla Github] repository that is compatible with\n # the installed Firefox browser, and start a new session.\n await session.load(\"https://www.google.com\")\n # . do some automated tasks\n ...\n```\n\n### Options configuration\nSetting options for aselenium drivers does not require to import an Options class. Instead, the options can be accessed directly from the driver instance. The following example shows how to set options for Chrome, but the same method (if applicable) can also apply to other browsers.\n\n``` python\nfrom aselenium import Chrome, Proxy\ndriver = Chrome()\n# . accept Insecure Certs\ndriver.options.accept_insecure_certs = True\n# . page Load Strategy\ndriver.options.page_load_strategy = \"eager\"\n# . proxy\nproxy = Proxy(\n http_proxy=\"http://127.0.0.1:7890\",\n https_proxy=\"http://127.0.0.1:7890\",\n socks_proxy=\"socks5://127.0.0.1:7890\",\n)\ndriver.options.proxy = proxy\n# . timeout\ndriver.options.set_timeouts(implicit=5, pageLoad=10)\n# . strict file interactability\ndriver.options.strict_file_interactability = True\n# . prompt behavior\ndriver.options.unhandled_prompt_behavior = \"dismiss\"\n# . arguments\ndriver.options.add_arguments(\"--disable-gpu\", \"--disable-dev-shm-usage\")\n# . preferences [Keywork Arguments]\ndriver.options.set_preferences(\n **{\n \"download.default_directory\": \"/path/to/download/directory\",\n \"download.prompt_for_download\": False,\n \"download.directory_upgrade\": True,\n \"safebrowsing.enabled\": True\n }\n)\n# . experimental options [Keywork Arguments]\ndriver.options.add_experimental_options(\n excludeSwitches=[\"enable-automation\", \"enable-logging\"]\n)\n...\n```\n\n### Profile configuration\nThe options of aselenium drivers provides the 'set_profile' method to configure the profile of the browser. By using this method, a cloned temporary profile will be created based on the specified profile directory, leaving the original profile untouched. When the driver is no longer in use, the temporary profile will be deleted automatically. The following example shows how to set profile for Chrome, but the same method (if applicable) can also apply to other browsers.\n``` python\nfrom aselenium import Chrome\ndriver = Chrome()\ndriver.options.set_profile(\n # . the default profile directory for Chrome on MacOS\n directory=\"~/Library/Application Support/Google/Chrome\", \n profile=\"Default\",\n)\n```\n\n### Navigation\n``` python\nfrom aselenium import Chrome\ndriver = Chrome()\nasync with driver.acquire() as session:\n # . load a url\n await session.load(\"https://www.google.com\")\n # . explicitly wait for page loading: url\n res = await session.wait_until_url(\"contains\", \"google\", timeout=10) # True / False\n # . explicitly wait for page loading: title\n res = await session.wait_until_title(\"startswith\", \"Google\", timeout=10) # True / False\n # . backward\n await session.backward()\n # . forward\n await session.forward()\n # . refresh\n await session.refresh()\n```\n\n### Page Information\n``` python\nfrom aselenium import Chrome\ndriver = Chrome()\nasync with driver.acquire() as session:\n await session.load(\"https://www.google.com\")\n # . access page url [property]\n url = await session.url # https://www.google.com\n # . access page title [property]\n title = await session.title # Google\n # . access page viewport [property]\n viewport = await session.viewport # <Viewport (width=1200, height=776, x=0, y=2143)>\n # . access page width [property]\n width = await session.width # 1200\n # . access page height [property]\n height = await session.height # 776\n # . access page source [property]\n source = await session.source # <!DOCTYPE html><html itemscope=\"\" itemtype=\"http://...\n # . take screenshot\n data = await session.screenshot() # b'\\x89PNG\\r\\n\\x1a\\n\\x00\\x00\\x00\\...\n # . save screenshot\n await session.save_screenshot(\"~/path/to/screenshot.png\") # True / False\n # . print page\n data = await session.print_page() # b'%PDF-1.4\\n%\\xe2\\xe3\\xcf\\xd3\\n1...\n # . save page\n await session.save_page(\"~/path/to/page.pdf\") # True / False\n```\n\n### Session Timeouts\n``` python\nfrom aselenium import Chrome\ndriver = Chrome()\nasync with driver.acquire() as session:\n # . access timeouts of the session [property]\n timeouts = await options.timeouts\n # <Timeouts (implicity=0, pageLoad=300000, script=30000, unit='ms')>\n\n # . set timeouts of the session\n timeouts = await session.set_timeouts(implicit=0.1, pageLoad=30, script=3)\n # <Timeouts (implicity=100, pageLoad=30000, script=3000, unit='ms')>\n\n # . reset timeouts of the session\n timeouts = await session.reset_timeouts()\n # <Timeouts (implicity=0, pageLoad=300000, script=30000, unit='ms')>\n```\n\n### Session Windows\n``` python\nfrom aselenium import Chrome\ndriver = Chrome()\nasync with driver.acquire() as session:\n await session.load(\"https://www.google.com\")\n # . access the active window [property]\n win = await session.active_window\n # <Window (name='default', handle='CCEF49C484842CFE1AB855ECCA164858')>\n\n # . rename a window\n win = await session.rename_window(\"default\", \"google\")\n # <Window (name='google', handle='CCEF49C484842CFE1AB855ECCA164858')>\n\n # . open a new window\n win = await session.new_window(\"baidu\", \"tab\")\n # <Window (name='baidu', handle='B89293FA79B6389AF1657B972FBD6B26')>\n await session.load(\"https://www.baidu.com\")\n\n # . access all opened windows [property]\n wins = await session.windows\n # [\n # <Window (name='google', handle='CCEF49C484842CFE1AB855ECCA164858')>\n # <Window (name='baidu', handle='B89293FA79B6389AF1657B972FBD6B26')>\n # ]\n\n # . close current window\n await session.close_window(switch_to=\"google\")\n # <Window (name='google', handle='CCEF49C484842CFE1AB855ECCA164858')>\n\n # . access window rect [property]\n rect = await session.window_rect\n # <WindowRect (width=1200, height=900, x=22, y=60)>\n\n # . set window rect\n rect = await session.set_window_rect(800, 500)\n # <WindowRect (width=800, height=500, x=22, y=60)>\n\n # . maximize window\n await session.maximize_window()\n\n # . minimize window\n await session.minimize_window()\n\n # . fullscreen window\n await session.fullscreen_window()\n```\n\n### Active Window Cookies\n``` python\nfrom aselenium import Chrome, Cookie\ndriver = Chrome()\nasync with driver.acquire() as session:\n await session.load(\"https://www.baidu.com\")\n\n # . access all cookies [property]\n cookies = await session.cookies\n # [\n # <Cookie (name='ZFY', data={'domain': '.baidu.com', 'expiry': 1720493275, ...})>\n # <Cookie (name='ZFK', data={'domain': '.baidu.com', 'expiry': 1720493275, ...})>\n # ...\n # ]\n\n # . get a cookie\n cookie = await session.get_cookie(\"ZFY\")\n # <Cookie (name='ZFY', data={'domain': '.baidu.com', 'expiry': 1720493275, ...})>\n\n # . add a cookie\n await session.add_cookie({\"name\": \"test_cookie2\", \"value\": \"123456\", \"domain\": \".baidu.com\"})\n # // or //\n test_cookie2 = Cookie(name=\"test_cookie1\", value=\"123456\", domain=\".baidu.com\")\n await session.add_cookie(test_cookie2)\n\n # . delete a cookie\n await session.delete_cookie(\"test_cookie1\")\n # // or //\n await session.delete_cookie(test_cookie2)\n```\n\n### JavaScript Execution\nNotice that some of the following methods are not async functions, therefore should not be awaited.\n\n``` python\nfrom aselenium import Chrome\ndriver = Chrome()\nasync with driver.acquire() as session:\n await session.load(\"https://www.google.com\")\n # . execute a raw javascript\n res = await session.execute_script(\"return document.title;\") # Google\n\n # . cache a javascript\n js = session.cache_script(\"get_title\", \"return document.title;\")\n # <JavaScript (name='get_title', script='return document.title;', args=[])>\n\n # . access all cached javascripts\n scripts = session.scripts\n # [<JavaScript (name='get_title', script='return document.title;', args=[])>]\n\n # . get a cached javascript\n js = session.get_script(\"get_title\")\n # <JavaScript (name='get_title', script='return document.title;', args=[])>\n\n # . execute cached javascript\n res = await session.execute_script(js) # Google\n # // or //\n res = await session.execute_script(\"get_title\") # Google\n\n # . rename cached javascript\n js = session.rename_script(\"get_title\", \"access_title\")\n # // or //\n js = session.rename_script(js, \"access_title\")\n # <JavaScript (name='access_title', script='return document.title;', args=[])>\n\n # . remove cached javascript\n session.remove_script(js)\n # // or //\n session.remove_script(\"access_title\")\n```\n\n### Element Interaction\n``` python\nfrom aselenium import Chrome\ndriver = Chrome()\nasync with driver.acquire() as session:\n await session.load(\"https://www.baidu.com\")\n # . find element\n element = await session.find_element(\"#kw\", by=\"css\")\n # <Element (id='289DEC2B8885F15A2BDD2E92AC0404F3_element_1', session='1e78...', service='http://...')>\n\n # . find elements\n elements = await session.find_elements(\".s_ipt\", by=\"css\")\n # [\n # <Element (id='289DEC2B8885F15A2BDD2E92AC0404F3_element_2', session='1e78...', service='http://...')>\n # <Element (id='289DEC2B8885F15A2BDD2E92AC0404F3_element_3', session='1e78...', service='http://...')>\n # ...\n # ]\n\n # . find the 1st located element among selectors\n element = await session.find_1st_element(\"#kw\", \".s_ipt\", by=\"css\")\n # <Element (id='289DEC2B8885F15A2BDD2E92AC0404F3_element_1', session='1e78...', service='http://...')>\n \n # . explicit wait for element\n res = await session.wait_until_element(\"visible\", \"#kw\", by=\"css\", timeout=10) # True\n res = await session.wait_until_element(\"gone\", \"#kw\", by=\"css\", timeout=10) # False\n\n # . explicit wait for elements\n res = await session.wait_until_elements(\n \"exist\", \"#kw\", \".s_ipt\", by=\"css\", all_=True, timeout=10\n ) # True\n res = await session.wait_until_elements(\n \"selected\", \"#kw\", \".s_ipt\", by=\"css\", all_=True, timeout=10\n ) # False\n\n # . access element properties\n exists = await element.exists # True\n visible = await element.visible # True\n viewable = await element.viewable # True\n enabled = await element.enabled # True\n selected = await element.selected # False\n tag = await element.tag # input\n text = await element.text # None\n rect = await element.rect # <ElementRect (width=500, height=22, x=522, y=217)>\n aria_role = await element.aria_role # None\n aria_label = await element.aria_label # None\n ...\n\n # . element interaction\n await element.click()\n await element.send(\"Hello World!\")\n await element.clear()\n await element.upload(\"~/path/to/file.png\")\n await element.scroll_into_view()\n ...\n```\n\n### Actions Chain\nActions chain allows the browser to perform a series of low-level interactions such as mouse movements, key presses, and wheel scrolls.\n\n- For Chromium-based browsers like Chrome, Chromium, and Edge, the actions chain execution passes most tests, including 'drag_and_drop'.\n- For Firefox, the actions chain execution fails the 'drag_and_drop' test. Additionally, user must explicitly block the code execution until all actions are completed. This is because geckodriver returns a response immediately after receiving the actions command (where chromedriver only returns a response when all actions are completed). To do so, user can choose to use the 'explicit_wait' argument in the 'perform()' method to wait the specified amount of seconds, or implement a custom logic right after the actions chain execution.\n``` python\nfrom aselenium import Chrome, KeyboardKeys\ndriver = Chrome()\nasync with driver.acquire() as session:\n # Actions chain\n await session.load(\"https://www.baidu.com\")\n search_button = await session.find_element(\"#su\", by=\"css\")\n (\n await session.actions()\n # . move mouse to the element\n .move_to(element=search_button)\n # . click the element\n .click(pause=1)\n # . send text\n .send_keys(\"Hello World!\", pause=1)\n # . select all (control + a)\n .send_key_combo(KeyboardKeys.CONTROL, \"a\", pause=1)\n # . cut (control + x)\n .send_key_combo(KeyboardKeys.CONTROL, \"x\", pause=1)\n # . paste (control + v)\n .send_key_combo(KeyboardKeys.CONTROL, \"v\", pause=1)\n # . enter\n .send_keys(KeyboardKeys.ENTER, pause=1)\n # . scroll wheel\n .scroll_by(y=500, pause=1)\n # . execute the actions chain\n .perform() \n # For Firefox, specify an explicit wait time to wait for the \n # actions to complete: `.perform(explicit_wait=20)`.\n )\n\n # Drag and drop\n await session.load(\"https://www.w3schools.com/html/html5_draganddrop.asp\")\n l_element = await session.find_element(\"#div1\", by=\"css\")\n r_element = await session.find_element(\"#div2\", by=\"css\")\n (\n await session.actions()\n # . drag and drop: left -> right\n .drag_and_drop(drag=l_element, drop=r_element, pause=1)\n # . drag and drop: right -> left\n .drag_and_drop(drag=r_element, drop=l_element, pause=1)\n # . execute the actions chain\n .perform()\n # For Firefox, `drag_and_drop` is not supported.\n )\n```\n\n### Known Issues\n- For Linux users, browsers installed through 'snap store' will failed due to the 'snap' sandbox. Snap version of the browsers lack the permissions to create and access a temporary profile out side of snap, which is required by the webdriver to start the browser. The most straight forward solution is to uninstall the snap version and re-install the browser through the official website.\n- For Firefox, the actions chain does not work quite as expected. If actions chain is important for the project, consider using Chromium-based browsers instead.\n- Safari is supported by aselenium, but limited to some basic functionalities, and not recommended to use for critical automations. The webdriver for Safari yeilds many unexpected errors and sometimes even crashes the browser and program.\n\n### Acknowledgements\naselenium is based on several open-source repositories.\n- [aiohttp](https://github.com/aio-libs/aiohttp)\n- [psutil](https://github.com/giampaolo/psutil)\n- [orjson](https://github.com/ijl/orjson)\n\naselenium is inspired from and makes modifications of the following open-source repositories:\n- [arsenic](https://github.com/HENNGE/arsenic)\n- [selenium](https://github.com/SeleniumHQ/selenium)\n- [webdriver-manager](https://github.com/SergeyPirogov/webdriver_manager)\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Asyncronous implementation of web browser automation for Python.",
"version": "0.1.13.4",
"project_urls": {
"Homepage": "https://github.com/AresJef/Aselenium"
},
"split_keywords": [
"async",
"asyncronous",
"automation",
"arsenic",
"selenium"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7ff7cd15b1afb9addb4221aa34969db588a82dbd87b61da924a45fb81accd385",
"md5": "7a37626773b2d870d87cd11af99c9bfa",
"sha256": "e2a9a9404b59f0a833c56e656b7370eb14016933ed4c95354a1da00baf9f85d7"
},
"downloads": -1,
"filename": "aselenium-0.1.13.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7a37626773b2d870d87cd11af99c9bfa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 186776,
"upload_time": "2024-01-06T16:50:40",
"upload_time_iso_8601": "2024-01-06T16:50:40.271510Z",
"url": "https://files.pythonhosted.org/packages/7f/f7/cd15b1afb9addb4221aa34969db588a82dbd87b61da924a45fb81accd385/aselenium-0.1.13.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f6466c3f593ecf85c33720d4c8a4bfc07ed0d4f8fa8042005e3574190f871e83",
"md5": "2ef39270b6b8ccbafad68603bf14b944",
"sha256": "32a26d5a9c9f9a92142137962d48521eb99e5437f7ac131d8331cadd167ddb3e"
},
"downloads": -1,
"filename": "aselenium-0.1.13.4.tar.gz",
"has_sig": false,
"md5_digest": "2ef39270b6b8ccbafad68603bf14b944",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 158652,
"upload_time": "2024-01-06T16:50:42",
"upload_time_iso_8601": "2024-01-06T16:50:42.165155Z",
"url": "https://files.pythonhosted.org/packages/f6/46/6c3f593ecf85c33720d4c8a4bfc07ed0d4f8fa8042005e3574190f871e83/aselenium-0.1.13.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-06 16:50:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AresJef",
"github_project": "Aselenium",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "aiohttp",
"specs": [
[
">=",
"3.8.4"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"2.1.0"
]
]
},
{
"name": "psutil",
"specs": [
[
">=",
"5.8.0"
]
]
},
{
"name": "pyarrow",
"specs": [
[
">=",
"12.0.1"
]
]
},
{
"name": "orjson",
"specs": [
[
">=",
"3.9.5"
]
]
}
],
"lcname": "aselenium"
}
JSON
