# Pysikuli
[](https://badge.fury.io/py/pysikuli)
This is a fast cross-platform python module for gui automation
## Introduction
Pysikuli initially inspired by [Sikuli Project](http://sikulix.com/) and secondly by python automation tools such as [pyautogui](https://github.com/asweigart/pyautogui) or [python-imagesearch](https://github.com/drov0/python-imagesearch). So if you already know about sikuli or pyautogui, but want to speed up your scripts to the max, you're in the right place.
Pysikuli helps to automate almost every user actions in Windows, Linux and MacOS.
In short, Pysikuli can :
- Search for an image on the entire screen as well as on a specific part of the screen (`Region`)
- Emulate user acivity via **Keyboard** and **Mouse**
- Make some manipulation with app's **window**s, e.g. **move**, **maximize** or **close**
- Use **clipboard**
- Call **popup**
- Delete files
## Quickstart
Once the installation is complete, import the main classes into your project:
```
import pysikuli as sik
from pysikuli import Key, Button, Region, config
```
### For keyboard presses use `tap()`, `write()` or `hotkey()`
```
sik.tap(Key.backspace)
sik.write("pysikuli")
sik.hotkey(Key.ctrl, Key.shift, Key.esc)
```
### For mouse movement use `click()`, `mouseMove()` or `scroll()`
```
sik.mouseMove((100,100))
sik.click(button=Button.left)
sik.scroll(duration=0.5, horizontal_speed=0.1, vertical_speed=0.1)
sik.dragDrop(destination_loc=(200, 200), start_location=(100, 100), speed=1)
```
### Image searching:
```
sik.find(image="/some_path", max_search_time=5)
sik.exist(image="/path_to_image")
sik.wait(image="/path_to_image")
sik.existAny()
```
The search functions will return a Match object (if found successfully), where you can get the center coordinates, set offset, show found image or region (more details in the documentation). Also, you can pass an image pattern to almost every mouse-related function, instead of Location.
### Clipboard management:
```
sik.copyToClip("test")
text = sik.pasteFromClip()
sik.paste("paste text directly in active window")
```
### Other useful functions:
```
sik.deleteFile("/file/path")
sik.popupAlert(text="some popup breakpoint in your script", title="alert")
sik.cleanupPics(pics_folder_path="/pics")
sik.activateWindow("Google Chrome")
sik.getWindowRegion("Google Chrome")
```
### Location
Location is a tuple with 2 values - **X** and **Y**, which represent posistion of one pixel on the screen. The **X** axis is directed from left side to right, as usual, but The **Y** is axis directed from top to bottom.
For example location with value (0, 0), located in the left top corner of the screen, and location with (1920, 1080) value located in the right bottom corner of the Full HD screen.
### Region
Region (rectangular pixel area on a screen) does not know anything about it’s visual content. It only knows the position on the screen and its dimension.
Region let to determine a specific screen are, where you want to find some GUI elements. It increase search speed and let you avoid missfinding similiar objects. Region is defined by top left and right bottom corner points of the area. (x1, y1, x2, y2)
For example how you can determine top left quarter of the Full HD screen:
```
# (x1, y1, x2, y2)
top_left_quarter = Region(0, 0, 960, 540)
```
And easilly use all search functions:
```
top_left_quarter.find(image="/some_path/to_image")
top_left_quarter.wait(image="/some_path/to_image")
```
### Capture Region and Location
You can use `getLocation()` which tracks the mouse position and after holding the mouse in the same location for 1.5 seconds (default) you will get the location printed in the terminal and already copied to your clipboard. `getRegion()` works in the same way, but uses 2 location to define the region.
To have quick and easy access to the `getRegion()` and `getLocation()` functions, I would recommend creating 2 `.py` files with the same names and put in the code below:
getRegion.py:
```
from pysikuli import getRegion
if __name__ == "__main__":
getRegion()
```
getLocation.py:
```
from pysikuli import getLocation
if __name__ == "__main__":
getLocation()
```
After that, you just run one of these `.py` files and you get the result
## Small Example
The code below runs the calculator, presses 2 + 2 and gets the result
```
import pysikuli as sik
from pysikuli import Region, Key, Button
if __name__ == "__main__":
sik.config.MOUSE_SPEED = 2
pic_2 = "pics/pic_2.png"
pic_plus = "pics/pic_plus.png"
pic_equal = "pics/pic_equal.png"
sik.tap(Key.win), sik.sleep(0.02)
sik.paste("calculator"), sik.sleep(0.3)
sik.tap(Key.enter)
sik.click(pic_2, precision=0.9)
sik.click(pic_plus)
sik.click(pic_2, precision=0.9)
sik.click(pic_equal)
```
## How reach the max speed?
Pysikuli has `config` variable, which one you can import in this way:
```
from pysikuli import config
```
Below is a list of parameters that can impact on search time:
- `config.COMPRESSION_RATIO`: default: 2 - resize image, e.g. if this variable was set to 2, it means that pics become 4 time smaller (height / 2) and (width / 2). Increase search speed almost double, but after the value 4 the speed increases slightly, but accuracy is lost significantly.
- `config.GRAYSCALE`: default: True - it turn on all pics to grayscale. Increase search speed by ~30%.
- `config.MIN_SLEEP_TIME`: default: 0.02 - is used as a constant minimum delay in some functions on macOS, changing this value may affect the correctness of the OS response.
Other ways to speed up:
- `config.MOUSE_SPEED`: default: 1, it is abstract measure and ≈ 1000 px per second. For instant move set to 1000 or 10000.
- use `Region`s to narrow the search area of your patterns
## Installation
```
pip install pysikuli
```
### External dependencies
External dependencies mostly belong to the playsound module, which is used to user-friendly capture Region or Location. However, pysikuli can work normally without them.
#### MacOS:
playsound dependencies:
- `brew install cairo pkg-config`
#### Linux:
playsound dependencies:
- on Ubuntu/Debian: `sudo apt install libgirepository1.0-dev libcairo2-dev`
- on Arch Linux: `sudo pacman -S cairo pkgconf`
- on Fedora: `sudo dnf install cairo-devel pkg-config python3-devel`
- on penSUSE: `sudo zypper install cairo-devel pkg-config python3-devel`
- evdev dependencies: `sudo apt-get install python3-dev or python3.x`, where x is version of your python
## Documentation
Full documentation is available here: [Documentation](pysikuli.readthedocs.io)
## VS Code add-ons
I would also recommend installing these VS Code's add-ons:
- [Paste Image](https://marketplace.visualstudio.com/items?itemName=mushan.vscode-paste-image), for pasting screenshots directly in the code from clipboard. You can also set up a specific folder to store your pics.
- [Image preview](https://marketplace.visualstudio.com/items?itemName=kisstkondoros.vscode-gutter-preview), for preview captured photos
- [luna-paint](https://marketplace.visualstudio.com/items?itemName=Tyriar.luna-paint), useful tool for fast cropping captured images inside VS Code
Raw data
{
"_id": null,
"home_page": "https://github.com/OlegSmoliakov/pysikuli",
"name": "pysikuli",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "gui,automation,desktop,RPA,test,testing,cross-platform,window,control,menu,title,name,geometry,size,position,move,resize,minimize,maximize,restore,hide,show,activate,raise,lower,close,screen-size,mouse-position,keyboard,mouse,cursor,click,press,keystroke,screen,screenshot,screencapture,screengrab,clipboard",
"author": "OlegSmoliakov",
"author_email": "smailzpro@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/27/64/ed634d6c8e5ee7ae002812a6dda6f492d9afd32e79168e20cdc9fdc658ee/pysikuli-0.0.17.tar.gz",
"platform": null,
"description": "# Pysikuli\n[](https://badge.fury.io/py/pysikuli)\nThis is a fast cross-platform python module for gui automation\n\n## Introduction\nPysikuli initially inspired by [Sikuli Project](http://sikulix.com/) and secondly by python automation tools such as [pyautogui](https://github.com/asweigart/pyautogui) or [python-imagesearch](https://github.com/drov0/python-imagesearch). So if you already know about sikuli or pyautogui, but want to speed up your scripts to the max, you're in the right place.\n\nPysikuli helps to automate almost every user actions in Windows, Linux and MacOS.\n\nIn short, Pysikuli can :\n- Search for an image on the entire screen as well as on a specific part of the screen (`Region`)\n- Emulate user acivity via **Keyboard** and **Mouse**\n- Make some manipulation with app's **window**s, e.g. **move**, **maximize** or **close**\n- Use **clipboard**\n- Call **popup**\n- Delete files\n\n## Quickstart\nOnce the installation is complete, import the main classes into your project:\n```\nimport pysikuli as sik\nfrom pysikuli import Key, Button, Region, config\n```\n### For keyboard presses use `tap()`, `write()` or `hotkey()`\n```\nsik.tap(Key.backspace)\nsik.write(\"pysikuli\")\nsik.hotkey(Key.ctrl, Key.shift, Key.esc)\n```\n### For mouse movement use `click()`, `mouseMove()` or `scroll()`\n```\nsik.mouseMove((100,100))\nsik.click(button=Button.left)\nsik.scroll(duration=0.5, horizontal_speed=0.1, vertical_speed=0.1)\nsik.dragDrop(destination_loc=(200, 200), start_location=(100, 100), speed=1)\n```\n### Image searching:\n```\nsik.find(image=\"/some_path\", max_search_time=5)\nsik.exist(image=\"/path_to_image\")\nsik.wait(image=\"/path_to_image\")\nsik.existAny()\n```\nThe search functions will return a Match object (if found successfully), where you can get the center coordinates, set offset, show found image or region (more details in the documentation). Also, you can pass an image pattern to almost every mouse-related function, instead of Location.\n### Clipboard management:\n```\nsik.copyToClip(\"test\")\ntext = sik.pasteFromClip()\nsik.paste(\"paste text directly in active window\")\n```\n### Other useful functions:\n```\nsik.deleteFile(\"/file/path\")\nsik.popupAlert(text=\"some popup breakpoint in your script\", title=\"alert\")\nsik.cleanupPics(pics_folder_path=\"/pics\")\nsik.activateWindow(\"Google Chrome\")\nsik.getWindowRegion(\"Google Chrome\")\n```\n\n### Location \nLocation is a tuple with 2 values - **X** and **Y**, which represent posistion of one pixel on the screen. The **X** axis is directed from left side to right, as usual, but The **Y** is axis directed from top to bottom. \n\nFor example location with value (0, 0), located in the left top corner of the screen, and location with (1920, 1080) value located in the right bottom corner of the Full HD screen.\n### Region\nRegion (rectangular pixel area on a screen) does not know anything about it\u2019s visual content. It only knows the position on the screen and its dimension.\nRegion let to determine a specific screen are, where you want to find some GUI elements. It increase search speed and let you avoid missfinding similiar objects. Region is defined by top left and right bottom corner points of the area. (x1, y1, x2, y2)\n\nFor example how you can determine top left quarter of the Full HD screen:\n```\n# (x1, y1, x2, y2) \ntop_left_quarter = Region(0, 0, 960, 540)\n```\nAnd easilly use all search functions:\n```\ntop_left_quarter.find(image=\"/some_path/to_image\")\ntop_left_quarter.wait(image=\"/some_path/to_image\")\n```\n### Capture Region and Location\nYou can use `getLocation()` which tracks the mouse position and after holding the mouse in the same location for 1.5 seconds (default) you will get the location printed in the terminal and already copied to your clipboard. `getRegion()` works in the same way, but uses 2 location to define the region.\n\nTo have quick and easy access to the `getRegion()` and `getLocation()` functions, I would recommend creating 2 `.py` files with the same names and put in the code below:\n\ngetRegion.py: \n\n```\nfrom pysikuli import getRegion\n\nif __name__ == \"__main__\":\n getRegion()\n\n```\ngetLocation.py:\n```\nfrom pysikuli import getLocation\n\nif __name__ == \"__main__\":\n getLocation()\n\n```\n\nAfter that, you just run one of these `.py` files and you get the result\n## Small Example \n\nThe code below runs the calculator, presses 2 + 2 and gets the result\n```\nimport pysikuli as sik\n\nfrom pysikuli import Region, Key, Button\n\nif __name__ == \"__main__\":\n\n sik.config.MOUSE_SPEED = 2\n\n pic_2 = \"pics/pic_2.png\"\n pic_plus = \"pics/pic_plus.png\"\n pic_equal = \"pics/pic_equal.png\"\n\n sik.tap(Key.win), sik.sleep(0.02)\n sik.paste(\"calculator\"), sik.sleep(0.3)\n sik.tap(Key.enter)\n\n sik.click(pic_2, precision=0.9)\n sik.click(pic_plus)\n sik.click(pic_2, precision=0.9)\n sik.click(pic_equal)\n```\n\n## How reach the max speed?\nPysikuli has `config` variable, which one you can import in this way:\n```\nfrom pysikuli import config\n``` \nBelow is a list of parameters that can impact on search time:\n- `config.COMPRESSION_RATIO`: default: 2 - resize image, e.g. if this variable was set to 2, it means that pics become 4 time smaller (height / 2) and (width / 2). Increase search speed almost double, but after the value 4 the speed increases slightly, but accuracy is lost significantly.\n- `config.GRAYSCALE`: default: True - it turn on all pics to grayscale. Increase search speed by ~30%. \n- `config.MIN_SLEEP_TIME`: default: 0.02 - is used as a constant minimum delay in some functions on macOS, changing this value may affect the correctness of the OS response.\n\nOther ways to speed up:\n- `config.MOUSE_SPEED`: default: 1, it is abstract measure and \u2248 1000 px per second. For instant move set to 1000 or 10000. \n- use `Region`s to narrow the search area of your patterns\n\n## Installation\n\n```\npip install pysikuli\n```\n### External dependencies\n\nExternal dependencies mostly belong to the playsound module, which is used to user-friendly capture Region or Location. However, pysikuli can work normally without them.\n\n#### MacOS:\nplaysound dependencies:\n- `brew install cairo pkg-config`\n\n#### Linux:\nplaysound dependencies:\n- on Ubuntu/Debian: `sudo apt install libgirepository1.0-dev libcairo2-dev`\n- on Arch Linux: `sudo pacman -S cairo pkgconf`\n- on Fedora: `sudo dnf install cairo-devel pkg-config python3-devel`\n- on penSUSE: `sudo zypper install cairo-devel pkg-config python3-devel`\n- evdev dependencies: `sudo apt-get install python3-dev or python3.x`, where x is version of your python\n\n## Documentation\nFull documentation is available here: [Documentation](pysikuli.readthedocs.io)\n\n## VS Code add-ons\nI would also recommend installing these VS Code's add-ons:\n- [Paste Image](https://marketplace.visualstudio.com/items?itemName=mushan.vscode-paste-image), for pasting screenshots directly in the code from clipboard. You can also set up a specific folder to store your pics.\n- [Image preview](https://marketplace.visualstudio.com/items?itemName=kisstkondoros.vscode-gutter-preview), for preview captured photos\n- [luna-paint](https://marketplace.visualstudio.com/items?itemName=Tyriar.luna-paint), useful tool for fast cropping captured images inside VS Code",
"bugtrack_url": null,
"license": "LGPL-3.0-only",
"summary": "Fast cross-platform RPA tool for GUI automation",
"version": "0.0.17",
"project_urls": {
"Documentation": "https://pysikuli.readthedocs.io",
"Homepage": "https://github.com/OlegSmoliakov/pysikuli",
"Repository": "https://github.com/OlegSmoliakov/pysikuli"
},
"split_keywords": [
"gui",
"automation",
"desktop",
"rpa",
"test",
"testing",
"cross-platform",
"window",
"control",
"menu",
"title",
"name",
"geometry",
"size",
"position",
"move",
"resize",
"minimize",
"maximize",
"restore",
"hide",
"show",
"activate",
"raise",
"lower",
"close",
"screen-size",
"mouse-position",
"keyboard",
"mouse",
"cursor",
"click",
"press",
"keystroke",
"screen",
"screenshot",
"screencapture",
"screengrab",
"clipboard"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "17695cf5c72e4b71094fa8c3d2761698c533ebb8d1e9456c8201c70eb0170481",
"md5": "251497d6650dc6179b7fca4310fb460e",
"sha256": "8eae7a2a5def50d3a0863ad96dfb3d398983cd48d8c857611aa0d5699f7d6dfd"
},
"downloads": -1,
"filename": "pysikuli-0.0.17-py3-none-any.whl",
"has_sig": false,
"md5_digest": "251497d6650dc6179b7fca4310fb460e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 51231,
"upload_time": "2024-02-05T19:32:38",
"upload_time_iso_8601": "2024-02-05T19:32:38.379164Z",
"url": "https://files.pythonhosted.org/packages/17/69/5cf5c72e4b71094fa8c3d2761698c533ebb8d1e9456c8201c70eb0170481/pysikuli-0.0.17-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2764ed634d6c8e5ee7ae002812a6dda6f492d9afd32e79168e20cdc9fdc658ee",
"md5": "0e433b85c3771c23f1e04b3f4de71682",
"sha256": "6155f21f2b87777ffdf7195a992336b39b5d36e91e629dee2ae436f9f30b0a21"
},
"downloads": -1,
"filename": "pysikuli-0.0.17.tar.gz",
"has_sig": false,
"md5_digest": "0e433b85c3771c23f1e04b3f4de71682",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 52211,
"upload_time": "2024-02-05T19:32:40",
"upload_time_iso_8601": "2024-02-05T19:32:40.159809Z",
"url": "https://files.pythonhosted.org/packages/27/64/ed634d6c8e5ee7ae002812a6dda6f492d9afd32e79168e20cdc9fdc658ee/pysikuli-0.0.17.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-05 19:32:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "OlegSmoliakov",
"github_project": "pysikuli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pysikuli"
}
JSON
