croco-selenium

Name	croco-selenium JSON
Version	0.1.6 JSON
	download
home_page	https://github.com/blnkoff/croco-selenium
Summary	The package providing ways to interact with Selenium Web Driver actions, such as clicking, sending keys etc.
upload_time	2024-04-07 01:49:44
maintainer	None
docs_url	None
author	Alexey
requires_python	<4.0,>=3.11
license	MIT
keywords
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # croco-selenium
[![Croco Logo](https://i.ibb.co/G5Pjt6M/logo.png)](https://t.me/crocofactory)

The package providing ways to interact with Selenium Web Driver actions, such as clicking, sending keys etc.
    

- **[Telegram channel](https://t.me/crocofactory)**
- **[Bug reports](https://github.com/blnkoff/croco-selenium/issues)**
- **[Actions Overview](#actions-overview)**

When we use Selenium, it's not convenient to use WebDriverWait with its cluttered chain actions. Instead of many imports 
and instances (By, WebDriverWait, expected_conditions) you can use fast and robust actions.

Package's source code is made available under the [MIT License](LICENSE)

# Quick Start
     
You can use actions, by the following way.

```python
from selenium.webdriver.chrome.webdriver import WebDriver
from croco_selenium import click
driver = WebDriver()
click(driver, 10, '//input[@type="submit"]')
```

If you don't want to pass driver every using of actions, you can create an instance of ActionPerformer

```python
from selenium.webdriver.chrome.webdriver import WebDriver
from croco_selenium import ActionPerformer
driver = WebDriver()
action_performer = ActionPerformer(driver)
timeout = 10

action_performer.send_keys(timeout, '//input[@type="password"]', 'password')
action_performer.click(timeout, '//input[@type="submit"]')
```

One of the best ways to use actions is create an instance of ChromeDriver and perform 
actions by calling methods on it. That class derived from ActionPerformer and ChromiumDriver

```python
import os
from croco_selenium import ChromeDriver, Proxy
proxy = Proxy(host='123.89.46.72', port=8000, username='croco', password='webDriver')
project_dir = os.path.dirname(os.path.abspath(__file__))
extension_paths = [os.path.join(project_dir, 'extensions/metamask.crx')]

driver = ChromeDriver(proxy=proxy, extension_paths=extension_paths)
driver.get('https://facebook.com')
driver.send_keys(15, '//input[@id="email"]', 'hello@world.com')
```

# Actions Overview
You can perform the following [actions](#actions), using croco-selenium:

- **[add_cookies](#add_cookies)**
- **[click](#click)**
- **[close_tabs](#close_tabs)**
- **[get_element](#get_element)**
- **[get_elements](#get_elements)**
- **[get_element_attribute](#get_element_attribute)**
- **[get_element_text](#get_element_text)**
- **[send_keys](#send_keys)**
- **[silent_send_keys](#silent_send_keys)**
- **[switch_to_another_window](#switch_to_another_window)**
- **[switch_to_frame](#switch_to_frame)**
- **[switch_to_parent_frame](#switch_to_parent_frame)**
- **[wait_for_invisibility](#wait_for_invisibility)**
- **[wait_for_windows](#wait_for_windows)**

And there are 3 useful [decorators](#decorators):

- **[handle_pop_up](#handle_pop_up)**
- **[handle_in_new_tab](#handle_in_new_tab)**
- **[handle_new_tab](#handle_new_tab)**
         
## Actions

<h3 id="add_cookies">add_cookies</h3>
Adds cookies to a current page. It takes valid string containing json, list of cookies or one cookie as dictionary.

```python
from croco_selenium import ChromeDriver

timeout = 10
driver = ChromeDriver()

cookies = '{"domain":".facebook.com","expirationDate":1689249734,"httpOnly":true,"name":"c_user","path":"/","secure":true,"value":"100083466604886"}'
driver.get('facebook.com')
driver.add_cookies(cookies)
```

<h3 id="click">click</h3>
Clicks on element in browser

```python
from croco_selenium import ChromeDriver

timeout = 10
driver = ChromeDriver()
driver.click(timeout, '//input[@type="submit"]')
```

<h3 id="close_tabs">close_tabs</h3>
Closes all tabs in browser. It's convenient to use, when you add extensions to your browser and their windows occur with 
starting a driver.

```python
import os
from croco_selenium import ChromeDriver

project_dir = os.path.dirname(os.path.abspath(__file__))
extension_paths = [os.path.join(project_dir, 'extensions/metamask.crx')]

driver = ChromeDriver(extension_paths=extension_paths)
driver.close_tabs()
driver.get('https://facebook.com')
driver.send_keys(15, '//input[@id="email"]', 'hello@world.com')
```

<h3 id="get_element">get_element</h3>
Returns an element in browser

```python
from croco_selenium import ChromeDriver

timeout = 10
driver = ChromeDriver()

element = driver.get_element(timeout, '//input[@type="submit"]')
element.click()
```

<h3 id="get_elements">get_elements</h3>
Returns an elements in browser

```python
from croco_selenium import ChromeDriver

timeout = 10
driver = ChromeDriver()

elements = driver.get_elements(timeout, '//input')

for element in elements:
    element.click()
```

<h3 id="get_element_attribute">get_element_attribute</h3>
Returns an element's attribute in browser

```python
from croco_selenium import ChromeDriver

timeout = 10
driver = ChromeDriver()

assert driver.get_element_attribute(timeout, '//input[@type="checkbox"]', 'checked')
```

<h3 id="get_element_text">get_element_text</h3>
Returns element's text in browser

```python
from croco_selenium import ChromeDriver

timeout = 10
driver = ChromeDriver()

print(driver.get_element_text(timeout, '//h1'))
```

<h3 id="send_keys">send_keys</h3>
Sends keys in browser

```python
from croco_selenium import ChromeDriver

timeout = 10
driver = ChromeDriver()

driver.send_keys(timeout, '//input[@type="password"]', 'password')
driver.click(timeout, '//input[@type="submit"]')
```

<h3 id="silent_send_keys">silent_send_keys</h3>
Sends keys with delay between characters in browser. It's convenient to use when you would like to hide your bot activity

```python
from croco_selenium import ChromeDriver

timeout = 10
driver = ChromeDriver()

driver.silent_send_keys(timeout, '//input[@type="password"]', 'password')
driver.click(timeout, '//input[@type="submit"]')
```

<h3 id="switch_to_another_window">switch_to_another_window</h3>
Switches to a different window from current window in browser. It's convenient to use, when you have two windows to be handled

```python
from croco_selenium import ChromeDriver

timeout = 10
driver = ChromeDriver()

driver.silent_send_keys(timeout, '//input[@type="password"]', 'password')
driver.click(timeout, '//input[@type="submit"]')
driver.switch_to_another_window(timeout)

driver.click(timeout, '//input[@type="submit"]')
driver.switch_to_another_window(timeout)
```

<h3 id="switch_to_frame">switch_to_frame</h3>
Switches to the frame

```python
from croco_selenium import ChromeDriver

timeout = 10
driver = ChromeDriver()

driver.switch_to_frame(timeout, '//iframe[@data-hcaptcha-widget-id]')
driver.click(timeout, '//input[@type="submit"]')
```

<h3 id="switch_to_parent_frame">switch_to_parent_frame</h3>
Switches to the parent frame

```python
from croco_selenium import ChromeDriver

timeout = 10
driver = ChromeDriver()

driver.switch_to_frame(timeout, '//iframe[@data-hcaptcha-widget-id]')
driver.click(timeout, '//input[@type="submit"]')
driver.switch_to_parent_frame()
```

<h3 id="wait_for_invisibility">wait_for_invisibility</h3>
Wait for element's invisibility in browser

```python
from croco_selenium import ChromeDriver

timeout = 10
driver = ChromeDriver()

driver.click(timeout, '//button')
driver.wait_for_invisibility(timeout, '//*[@id="popup"]')
```
      
<h3 id="wait_for_windows">wait_for_windows</h3>
Wait for occurring of number of windows

```python
from croco_selenium import ChromeDriver

timeout = 10
driver = ChromeDriver()

driver.wait_for_windows(timeout, 2)
```

## Decorators
<h3 id="handle_pop_up">handle_pop_up</h3>
Switches to another window, performs decorated function and switches back. Pop up has to be closed after performing
decorated function.

This decorator is usually used for browser extensions' pop-ups. Example of function performing
a third-party Metamask connection:

```python
from croco_selenium import ChromeDriver, handle_pop_up
from selenium.common import TimeoutException

@handle_pop_up()
def connect(driver: ChromeDriver, password: str) -> None:
    try:
        password_xpath = '//*[@id="password"]'
        driver.send_keys(7, password_xpath, password)

        unlock_xpath = '//button[@data-testid="unlock-submit"]'
        driver.click(5, unlock_xpath)
    except TimeoutException:
        pass

    for _ in range(3):
        next_xpath = '//button[@data-testid="page-container-footer-next"]'
        driver.click(10, next_xpath, ignored_exceptions=TimeoutException)
```

<h3 id="handle_in_new_tab">handle_in_new_tab</h3>
Opens new tab, performs decorated function, closes new tab and switches back. Here is example of function performing 
getting of 2FA code from browser extension.

```python
from croco_selenium import ChromeDriver, handle_in_new_tab

@handle_in_new_tab()
def get_code(driver: ChromeDriver, account) -> str:
    timeout = 15

    driver.get('<EXTENSION_URL>')

    code_field_xpath = '//*[contains(@class, "code")]'
    code_fields = driver.get_elements(timeout, code_field_xpath)

    code_field = code_fields[account.id]

    code = code_field.text
    return code
```

<h3 id="handle_new_tab">handle_new_tab</h3>
Performs decorated function in new tab and switches back. New tab has to be opened during performing decorated function.


# Installing croco-selenium

To install the package from PyPi you can use:   

```sh
pip install croco-selenium
```
   
To install the package from GitHub you can use:

```sh
pip install git+https://github.com/blnkoff/croco-selenium.git
```

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/blnkoff/croco-selenium",
    "name": "croco-selenium",
    "maintainer": null,
    "docs_url": null,
    "requires_python": "<4.0,>=3.11",
    "maintainer_email": null,
    "keywords": null,
    "author": "Alexey",
    "author_email": "abelenkov2006@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/46/e0/a534349b3b6ef7b3b8c4e3ab4e22f5843b734eaec6f07a9dc3b8a9b2999b/croco_selenium-0.1.6.tar.gz",
    "platform": null,
    "description": "# croco-selenium\n[![Croco Logo](https://i.ibb.co/G5Pjt6M/logo.png)](https://t.me/crocofactory)\n\nThe package providing ways to interact with Selenium Web Driver actions, such as clicking, sending keys etc.\n    \n\n- **[Telegram channel](https://t.me/crocofactory)**\n- **[Bug reports](https://github.com/blnkoff/croco-selenium/issues)**\n- **[Actions Overview](#actions-overview)**\n\nWhen we use Selenium, it's not convenient to use WebDriverWait with its cluttered chain actions. Instead of many imports \nand instances (By, WebDriverWait, expected_conditions) you can use fast and robust actions.\n\nPackage's source code is made available under the [MIT License](LICENSE)\n\n# Quick Start\n     \nYou can use actions, by the following way.\n\n```python\nfrom selenium.webdriver.chrome.webdriver import WebDriver\nfrom croco_selenium import click\ndriver = WebDriver()\nclick(driver, 10, '//input[@type=\"submit\"]')\n```\n\nIf you don't want to pass driver every using of actions, you can create an instance of ActionPerformer\n\n```python\nfrom selenium.webdriver.chrome.webdriver import WebDriver\nfrom croco_selenium import ActionPerformer\ndriver = WebDriver()\naction_performer = ActionPerformer(driver)\ntimeout = 10\n\naction_performer.send_keys(timeout, '//input[@type=\"password\"]', 'password')\naction_performer.click(timeout, '//input[@type=\"submit\"]')\n```\n\nOne of the best ways to use actions is create an instance of ChromeDriver and perform \nactions by calling methods on it. That class derived from ActionPerformer and ChromiumDriver\n\n```python\nimport os\nfrom croco_selenium import ChromeDriver, Proxy\nproxy = Proxy(host='123.89.46.72', port=8000, username='croco', password='webDriver')\nproject_dir = os.path.dirname(os.path.abspath(__file__))\nextension_paths = [os.path.join(project_dir, 'extensions/metamask.crx')]\n\ndriver = ChromeDriver(proxy=proxy, extension_paths=extension_paths)\ndriver.get('https://facebook.com')\ndriver.send_keys(15, '//input[@id=\"email\"]', 'hello@world.com')\n```\n\n# Actions Overview\nYou can perform the following [actions](#actions), using croco-selenium:\n\n- **[add_cookies](#add_cookies)**\n- **[click](#click)**\n- **[close_tabs](#close_tabs)**\n- **[get_element](#get_element)**\n- **[get_elements](#get_elements)**\n- **[get_element_attribute](#get_element_attribute)**\n- **[get_element_text](#get_element_text)**\n- **[send_keys](#send_keys)**\n- **[silent_send_keys](#silent_send_keys)**\n- **[switch_to_another_window](#switch_to_another_window)**\n- **[switch_to_frame](#switch_to_frame)**\n- **[switch_to_parent_frame](#switch_to_parent_frame)**\n- **[wait_for_invisibility](#wait_for_invisibility)**\n- **[wait_for_windows](#wait_for_windows)**\n\nAnd there are 3 useful [decorators](#decorators):\n\n- **[handle_pop_up](#handle_pop_up)**\n- **[handle_in_new_tab](#handle_in_new_tab)**\n- **[handle_new_tab](#handle_new_tab)**\n         \n## Actions\n\n<h3 id=\"add_cookies\">add_cookies</h3>\nAdds cookies to a current page. It takes valid string containing json, list of cookies or one cookie as dictionary.\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\ncookies = '{\"domain\":\".facebook.com\",\"expirationDate\":1689249734,\"httpOnly\":true,\"name\":\"c_user\",\"path\":\"/\",\"secure\":true,\"value\":\"100083466604886\"}'\ndriver.get('facebook.com')\ndriver.add_cookies(cookies)\n```\n\n<h3 id=\"click\">click</h3>\nClicks on element in browser\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\ndriver.click(timeout, '//input[@type=\"submit\"]')\n```\n\n<h3 id=\"close_tabs\">close_tabs</h3>\nCloses all tabs in browser. It's convenient to use, when you add extensions to your browser and their windows occur with \nstarting a driver.\n\n```python\nimport os\nfrom croco_selenium import ChromeDriver\n\nproject_dir = os.path.dirname(os.path.abspath(__file__))\nextension_paths = [os.path.join(project_dir, 'extensions/metamask.crx')]\n\ndriver = ChromeDriver(extension_paths=extension_paths)\ndriver.close_tabs()\ndriver.get('https://facebook.com')\ndriver.send_keys(15, '//input[@id=\"email\"]', 'hello@world.com')\n```\n\n<h3 id=\"get_element\">get_element</h3>\nReturns an element in browser\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\nelement = driver.get_element(timeout, '//input[@type=\"submit\"]')\nelement.click()\n```\n\n<h3 id=\"get_elements\">get_elements</h3>\nReturns an elements in browser\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\nelements = driver.get_elements(timeout, '//input')\n\nfor element in elements:\n    element.click()\n```\n\n<h3 id=\"get_element_attribute\">get_element_attribute</h3>\nReturns an element's attribute in browser\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\nassert driver.get_element_attribute(timeout, '//input[@type=\"checkbox\"]', 'checked')\n```\n\n<h3 id=\"get_element_text\">get_element_text</h3>\nReturns element's text in browser\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\nprint(driver.get_element_text(timeout, '//h1'))\n```\n\n<h3 id=\"send_keys\">send_keys</h3>\nSends keys in browser\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\ndriver.send_keys(timeout, '//input[@type=\"password\"]', 'password')\ndriver.click(timeout, '//input[@type=\"submit\"]')\n```\n\n<h3 id=\"silent_send_keys\">silent_send_keys</h3>\nSends keys with delay between characters in browser. It's convenient to use when you would like to hide your bot activity\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\ndriver.silent_send_keys(timeout, '//input[@type=\"password\"]', 'password')\ndriver.click(timeout, '//input[@type=\"submit\"]')\n```\n\n<h3 id=\"switch_to_another_window\">switch_to_another_window</h3>\nSwitches to a different window from current window in browser. It's convenient to use, when you have two windows to be handled\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\ndriver.silent_send_keys(timeout, '//input[@type=\"password\"]', 'password')\ndriver.click(timeout, '//input[@type=\"submit\"]')\ndriver.switch_to_another_window(timeout)\n\ndriver.click(timeout, '//input[@type=\"submit\"]')\ndriver.switch_to_another_window(timeout)\n```\n\n<h3 id=\"switch_to_frame\">switch_to_frame</h3>\nSwitches to the frame\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\ndriver.switch_to_frame(timeout, '//iframe[@data-hcaptcha-widget-id]')\ndriver.click(timeout, '//input[@type=\"submit\"]')\n```\n\n<h3 id=\"switch_to_parent_frame\">switch_to_parent_frame</h3>\nSwitches to the parent frame\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\ndriver.switch_to_frame(timeout, '//iframe[@data-hcaptcha-widget-id]')\ndriver.click(timeout, '//input[@type=\"submit\"]')\ndriver.switch_to_parent_frame()\n```\n\n<h3 id=\"wait_for_invisibility\">wait_for_invisibility</h3>\nWait for element's invisibility in browser\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\ndriver.click(timeout, '//button')\ndriver.wait_for_invisibility(timeout, '//*[@id=\"popup\"]')\n```\n      \n<h3 id=\"wait_for_windows\">wait_for_windows</h3>\nWait for occurring of number of windows\n\n```python\nfrom croco_selenium import ChromeDriver\n\ntimeout = 10\ndriver = ChromeDriver()\n\ndriver.wait_for_windows(timeout, 2)\n```\n\n## Decorators\n<h3 id=\"handle_pop_up\">handle_pop_up</h3>\nSwitches to another window, performs decorated function and switches back. Pop up has to be closed after performing\ndecorated function.\n\nThis decorator is usually used for browser extensions' pop-ups. Example of function performing\na third-party Metamask connection:\n\n```python\nfrom croco_selenium import ChromeDriver, handle_pop_up\nfrom selenium.common import TimeoutException\n\n@handle_pop_up()\ndef connect(driver: ChromeDriver, password: str) -> None:\n    try:\n        password_xpath = '//*[@id=\"password\"]'\n        driver.send_keys(7, password_xpath, password)\n\n        unlock_xpath = '//button[@data-testid=\"unlock-submit\"]'\n        driver.click(5, unlock_xpath)\n    except TimeoutException:\n        pass\n\n    for _ in range(3):\n        next_xpath = '//button[@data-testid=\"page-container-footer-next\"]'\n        driver.click(10, next_xpath, ignored_exceptions=TimeoutException)\n```\n\n<h3 id=\"handle_in_new_tab\">handle_in_new_tab</h3>\nOpens new tab, performs decorated function, closes new tab and switches back. Here is example of function performing \ngetting of 2FA code from browser extension.\n\n```python\nfrom croco_selenium import ChromeDriver, handle_in_new_tab\n\n@handle_in_new_tab()\ndef get_code(driver: ChromeDriver, account) -> str:\n    timeout = 15\n\n    driver.get('<EXTENSION_URL>')\n\n    code_field_xpath = '//*[contains(@class, \"code\")]'\n    code_fields = driver.get_elements(timeout, code_field_xpath)\n\n    code_field = code_fields[account.id]\n\n    code = code_field.text\n    return code\n```\n\n<h3 id=\"handle_new_tab\">handle_new_tab</h3>\nPerforms decorated function in new tab and switches back. New tab has to be opened during performing decorated function.\n\n\n# Installing croco-selenium\n\nTo install the package from PyPi you can use:   \n\n```sh\npip install croco-selenium\n```\n   \nTo install the package from GitHub you can use:\n\n```sh\npip install git+https://github.com/blnkoff/croco-selenium.git\n```\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "The package providing ways to interact with Selenium Web Driver actions, such as clicking, sending keys etc.",
    "version": "0.1.6",
    "project_urls": {
        "Homepage": "https://github.com/blnkoff/croco-selenium",
        "Repository": "https://github.com/blnkoff/croco-selenium"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "21c86773e122a06e7941d8706023f12b9877fd2932eb9a1542313a4f64ea2f53",
                "md5": "26f0150eefd4f1d33c1a3c7073a10a53",
                "sha256": "b22cfa7693a46b62764f444cdd179a5fec038613c27debfa7b5b487bec561580"
            },
            "downloads": -1,
            "filename": "croco_selenium-0.1.6-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "26f0150eefd4f1d33c1a3c7073a10a53",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<4.0,>=3.11",
            "size": 11870,
            "upload_time": "2024-04-07T01:49:42",
            "upload_time_iso_8601": "2024-04-07T01:49:42.452321Z",
            "url": "https://files.pythonhosted.org/packages/21/c8/6773e122a06e7941d8706023f12b9877fd2932eb9a1542313a4f64ea2f53/croco_selenium-0.1.6-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "46e0a534349b3b6ef7b3b8c4e3ab4e22f5843b734eaec6f07a9dc3b8a9b2999b",
                "md5": "f3e99a33e790880918569021fb02093a",
                "sha256": "ac5e620e1f4e6bae42a6b203e2bc19a42ce68ca672073ff796076338e7ae195d"
            },
            "downloads": -1,
            "filename": "croco_selenium-0.1.6.tar.gz",
            "has_sig": false,
            "md5_digest": "f3e99a33e790880918569021fb02093a",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<4.0,>=3.11",
            "size": 10582,
            "upload_time": "2024-04-07T01:49:44",
            "upload_time_iso_8601": "2024-04-07T01:49:44.299946Z",
            "url": "https://files.pythonhosted.org/packages/46/e0/a534349b3b6ef7b3b8c4e3ab4e22f5843b734eaec6f07a9dc3b8a9b2999b/croco_selenium-0.1.6.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-04-07 01:49:44",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "blnkoff",
    "github_project": "croco-selenium",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "croco-selenium"
}

Alexey