screenspot 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- screenspot-0.1.0/LICENSE +21 -0
- screenspot-0.1.0/PKG-INFO +213 -0
- screenspot-0.1.0/README.md +183 -0
- screenspot-0.1.0/pyproject.toml +61 -0
- screenspot-0.1.0/setup.cfg +4 -0
- screenspot-0.1.0/src/screenspot/__init__.py +45 -0
- screenspot-0.1.0/src/screenspot/bundle.py +106 -0
- screenspot-0.1.0/src/screenspot/capture.py +29 -0
- screenspot-0.1.0/src/screenspot/errors.py +19 -0
- screenspot-0.1.0/src/screenspot/geometry.py +46 -0
- screenspot-0.1.0/src/screenspot/matching.py +84 -0
- screenspot-0.1.0/src/screenspot/overlay.py +87 -0
- screenspot-0.1.0/src/screenspot/pointer.py +41 -0
- screenspot-0.1.0/src/screenspot/py.typed +0 -0
- screenspot-0.1.0/src/screenspot/screen.py +393 -0
- screenspot-0.1.0/src/screenspot.egg-info/PKG-INFO +213 -0
- screenspot-0.1.0/src/screenspot.egg-info/SOURCES.txt +21 -0
- screenspot-0.1.0/src/screenspot.egg-info/dependency_links.txt +1 -0
- screenspot-0.1.0/src/screenspot.egg-info/requires.txt +7 -0
- screenspot-0.1.0/src/screenspot.egg-info/top_level.txt +1 -0
- screenspot-0.1.0/tests/test_bundle.py +73 -0
- screenspot-0.1.0/tests/test_matching.py +85 -0
- screenspot-0.1.0/tests/test_screen_flow.py +236 -0
screenspot-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 screenspot contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: screenspot
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Locate template images on screen and act on them with fluent, chainable calls.
|
|
5
|
+
Author: screenspot contributors
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://pypi.org/project/screenspot/
|
|
8
|
+
Keywords: automation,gui-testing,opencv,template-matching,screen,pyautogui
|
|
9
|
+
Classifier: Development Status :: 3 - Alpha
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
12
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Topic :: Software Development :: Testing
|
|
19
|
+
Classifier: Typing :: Typed
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Requires-Dist: numpy>=1.24
|
|
24
|
+
Requires-Dist: opencv-python>=4.8
|
|
25
|
+
Requires-Dist: mss>=9
|
|
26
|
+
Requires-Dist: pyautogui>=0.9.54
|
|
27
|
+
Provides-Extra: test
|
|
28
|
+
Requires-Dist: pytest>=8; extra == "test"
|
|
29
|
+
Dynamic: license-file
|
|
30
|
+
|
|
31
|
+
# screenspot
|
|
32
|
+
|
|
33
|
+
Locate template images on screen and act on them with fluent, chainable calls.
|
|
34
|
+
|
|
35
|
+
`screenspot` is a small, independent library for visual GUI automation: it captures the
|
|
36
|
+
screen with [mss](https://github.com/BoboTiG/python-mss), finds a template image with
|
|
37
|
+
[OpenCV](https://opencv.org/) template matching, and drives the mouse with
|
|
38
|
+
[PyAutoGUI](https://github.com/asweigart/pyautogui).
|
|
39
|
+
|
|
40
|
+
```python
|
|
41
|
+
from screenspot import Screen
|
|
42
|
+
|
|
43
|
+
screen = Screen(bundle_path="assets/images")
|
|
44
|
+
|
|
45
|
+
screen.wait("login.png", timeout=10).highlight().click()
|
|
46
|
+
screen.click("ok.png").wait_vanish(timeout=5)
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
* **Chainable** — every action on a match returns the same `Spot`, so calls read left to right.
|
|
50
|
+
* **Bare image names** — set a bundle path once; `"login.png"` resolves against it.
|
|
51
|
+
* **Scoped lookups** — `screen.region(x, y, w, h)` limits capture and matching to a rectangle.
|
|
52
|
+
* **Testable** — capture, matching, highlighting, and mouse control are injectable.
|
|
53
|
+
* **No recording, no keyboard layer** — just screen lookup and pointer actions.
|
|
54
|
+
|
|
55
|
+
Requires Python 3.10+ and a real desktop session (Windows or Linux X11).
|
|
56
|
+
|
|
57
|
+
## Install
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
pip install screenspot
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Dependencies: `numpy`, `opencv-python`, `mss`, `pyautogui`. Highlighting additionally uses
|
|
64
|
+
`tkinter` and is skipped gracefully when it is unavailable.
|
|
65
|
+
|
|
66
|
+
## Quick start
|
|
67
|
+
|
|
68
|
+
```python
|
|
69
|
+
from pathlib import Path
|
|
70
|
+
from screenspot import Screen
|
|
71
|
+
|
|
72
|
+
# One Screen per test session; it owns the capture handle.
|
|
73
|
+
screen = Screen(bundle_path=Path("assets/images"))
|
|
74
|
+
|
|
75
|
+
# Wait for an image, then click it.
|
|
76
|
+
screen.wait("login_button.png", timeout=10).click()
|
|
77
|
+
|
|
78
|
+
# Click, then wait for the button to disappear.
|
|
79
|
+
screen.click("save.png").wait_vanish(timeout=10)
|
|
80
|
+
|
|
81
|
+
# Find once and inspect the result.
|
|
82
|
+
spot = screen.find("status.png")
|
|
83
|
+
if spot is None:
|
|
84
|
+
print("not on screen")
|
|
85
|
+
else:
|
|
86
|
+
print(spot.center, spot.score, spot.box)
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Chaining
|
|
90
|
+
|
|
91
|
+
`Screen.find / wait / click` all return a `Spot` (or `None` for `find`):
|
|
92
|
+
|
|
93
|
+
```python
|
|
94
|
+
screen.wait("menu.png", timeout=5) \
|
|
95
|
+
.highlight(duration=0.6, mark_center=True) \
|
|
96
|
+
.hover() \
|
|
97
|
+
.click(button="left") \
|
|
98
|
+
.wait_vanish(timeout=5, strict=False)
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
| `Spot` member | Description |
|
|
102
|
+
|---|---|
|
|
103
|
+
| `box` | matched rectangle (`Box`) in absolute screen pixels |
|
|
104
|
+
| `center` | `(x, y)` of the match center |
|
|
105
|
+
| `score` | normalized match score in `[0.0, 1.0]` |
|
|
106
|
+
| `highlight(...)` | draw a temporary border; `mark_center=True` adds a cross |
|
|
107
|
+
| `click(button="left", hold=None, highlight=False)` | click the center |
|
|
108
|
+
| `double_click()`, `right_click()` | convenience wrappers |
|
|
109
|
+
| `hover(highlight=True, duration=None)` | move the pointer to the center |
|
|
110
|
+
| `wait_vanish(timeout, strict=True)` | wait until the image is gone |
|
|
111
|
+
|
|
112
|
+
## Bundle path
|
|
113
|
+
|
|
114
|
+
Relative image names are resolved against a configurable bundle path:
|
|
115
|
+
|
|
116
|
+
```python
|
|
117
|
+
import screenspot
|
|
118
|
+
|
|
119
|
+
screenspot.set_bundle_path("assets/images")
|
|
120
|
+
screenspot.get_bundle_path() # -> .../assets/images
|
|
121
|
+
screenspot.resolve_path("ok.png") # -> .../assets/images/ok.png
|
|
122
|
+
|
|
123
|
+
screenspot.config.bundle_path = None # clear; relative names resolve against the cwd
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
The value is process-wide. `Screen(bundle_path=...)` sets a per-screen override that wins
|
|
127
|
+
over the global value:
|
|
128
|
+
|
|
129
|
+
```python
|
|
130
|
+
screen = Screen(bundle_path="suite_a/images") # only this screen uses suite_a
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Absolute paths always bypass the bundle path. `resolve_path()` does not check that the file
|
|
134
|
+
exists, so it is the quickest way to verify a change.
|
|
135
|
+
|
|
136
|
+
## Scoped regions
|
|
137
|
+
|
|
138
|
+
```python
|
|
139
|
+
panel = screen.region(1200, 100, 600, 800) # absolute top-left corner + size
|
|
140
|
+
panel.wait("save.png", timeout=5).click()
|
|
141
|
+
|
|
142
|
+
# Spot coordinates are still absolute, so clicks land in the right place.
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
`RegionView` supports `find`, `wait`, `click`, and `wait_vanish`; it does not nest.
|
|
146
|
+
|
|
147
|
+
## API overview
|
|
148
|
+
|
|
149
|
+
| Call | Returns | Notes |
|
|
150
|
+
|---|---|---|
|
|
151
|
+
| `Screen(bundle_path=None, threshold=0.85, interval=0.25)` | `Screen` | components are injectable for tests |
|
|
152
|
+
| `screen.find(image, threshold=None, region=None)` | `Spot \| None` | single lookup |
|
|
153
|
+
| `screen.wait(image, timeout=10, ...)` | `Spot` | raises `WaitTimeout` |
|
|
154
|
+
| `screen.click(image, timeout=10, ...)` | `Spot` | wait + click |
|
|
155
|
+
| `screen.wait_vanish(image, timeout=10, strict=True)` | `bool` | raises `VanishTimeout` when strict |
|
|
156
|
+
| `screen.region(x, y, width, height)` | `RegionView` | scoped proxy |
|
|
157
|
+
| `screen.close()` | `None` | releases the capture handle |
|
|
158
|
+
|
|
159
|
+
Exceptions: `ScreenSpotError` (base), `TemplateNotFound`, `WaitTimeout`, `VanishTimeout`.
|
|
160
|
+
|
|
161
|
+
## How it works
|
|
162
|
+
|
|
163
|
+
1. `Grabber` captures the monitor or a region as a BGR `numpy` frame (`mss`).
|
|
164
|
+
2. `Matcher` runs `cv2.matchTemplate(..., TM_CCOEFF_NORMED)` and returns the best score and
|
|
165
|
+
top-left corner; template images are cached by path and modification time.
|
|
166
|
+
3. Coordinates are converted to absolute screen space, then `Spot` exposes fluent actions.
|
|
167
|
+
4. `Pointer` lazily imports `pyautogui` for clicks and pointer moves.
|
|
168
|
+
|
|
169
|
+
Highlighting is best effort: on a desktop without `tkinter`, or when
|
|
170
|
+
`SCREENSPOT_NO_OVERLAY=1` is set, matching and clicking still work.
|
|
171
|
+
|
|
172
|
+
## Platform notes
|
|
173
|
+
|
|
174
|
+
- Windows and Linux X11 are the supported targets; Wayland-only and headless sessions are not.
|
|
175
|
+
- High-DPI scaling can shift coordinates; make sure screenshots/templates match the
|
|
176
|
+
effective resolution.
|
|
177
|
+
- Screen recording and keyboard automation are intentionally out of scope.
|
|
178
|
+
|
|
179
|
+
## Development
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
python -m venv .venv
|
|
183
|
+
.venv/Scripts/pip install -e ".[test]" # Windows
|
|
184
|
+
# .venv/bin/pip install -e ".[test]" # Linux
|
|
185
|
+
python -m pytest
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
## Publishing to PyPI
|
|
189
|
+
|
|
190
|
+
The distribution name `screenspot` was unclaimed on PyPI when this project was created;
|
|
191
|
+
re-check before the first release.
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
python -m pip install --upgrade build twine
|
|
195
|
+
python -m build
|
|
196
|
+
twine check dist/*
|
|
197
|
+
|
|
198
|
+
# Dry run against TestPyPI first
|
|
199
|
+
twine upload --repository testpypi dist/*
|
|
200
|
+
python -m pip install --index-url https://test.pypi.org/simple/ screenspot
|
|
201
|
+
|
|
202
|
+
# Real release
|
|
203
|
+
twine upload dist/*
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
Use a PyPI API token (account settings → API tokens) as the password with username
|
|
207
|
+
`__token__`, preferably via `~/.pypirc` or the `TWINE_PASSWORD` environment variable. Never
|
|
208
|
+
commit tokens or paste them into chat.
|
|
209
|
+
|
|
210
|
+
## License
|
|
211
|
+
|
|
212
|
+
MIT — see [LICENSE](LICENSE). This is an independent implementation; it does not contain code
|
|
213
|
+
from any proprietary library.
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
# screenspot
|
|
2
|
+
|
|
3
|
+
Locate template images on screen and act on them with fluent, chainable calls.
|
|
4
|
+
|
|
5
|
+
`screenspot` is a small, independent library for visual GUI automation: it captures the
|
|
6
|
+
screen with [mss](https://github.com/BoboTiG/python-mss), finds a template image with
|
|
7
|
+
[OpenCV](https://opencv.org/) template matching, and drives the mouse with
|
|
8
|
+
[PyAutoGUI](https://github.com/asweigart/pyautogui).
|
|
9
|
+
|
|
10
|
+
```python
|
|
11
|
+
from screenspot import Screen
|
|
12
|
+
|
|
13
|
+
screen = Screen(bundle_path="assets/images")
|
|
14
|
+
|
|
15
|
+
screen.wait("login.png", timeout=10).highlight().click()
|
|
16
|
+
screen.click("ok.png").wait_vanish(timeout=5)
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
* **Chainable** — every action on a match returns the same `Spot`, so calls read left to right.
|
|
20
|
+
* **Bare image names** — set a bundle path once; `"login.png"` resolves against it.
|
|
21
|
+
* **Scoped lookups** — `screen.region(x, y, w, h)` limits capture and matching to a rectangle.
|
|
22
|
+
* **Testable** — capture, matching, highlighting, and mouse control are injectable.
|
|
23
|
+
* **No recording, no keyboard layer** — just screen lookup and pointer actions.
|
|
24
|
+
|
|
25
|
+
Requires Python 3.10+ and a real desktop session (Windows or Linux X11).
|
|
26
|
+
|
|
27
|
+
## Install
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
pip install screenspot
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Dependencies: `numpy`, `opencv-python`, `mss`, `pyautogui`. Highlighting additionally uses
|
|
34
|
+
`tkinter` and is skipped gracefully when it is unavailable.
|
|
35
|
+
|
|
36
|
+
## Quick start
|
|
37
|
+
|
|
38
|
+
```python
|
|
39
|
+
from pathlib import Path
|
|
40
|
+
from screenspot import Screen
|
|
41
|
+
|
|
42
|
+
# One Screen per test session; it owns the capture handle.
|
|
43
|
+
screen = Screen(bundle_path=Path("assets/images"))
|
|
44
|
+
|
|
45
|
+
# Wait for an image, then click it.
|
|
46
|
+
screen.wait("login_button.png", timeout=10).click()
|
|
47
|
+
|
|
48
|
+
# Click, then wait for the button to disappear.
|
|
49
|
+
screen.click("save.png").wait_vanish(timeout=10)
|
|
50
|
+
|
|
51
|
+
# Find once and inspect the result.
|
|
52
|
+
spot = screen.find("status.png")
|
|
53
|
+
if spot is None:
|
|
54
|
+
print("not on screen")
|
|
55
|
+
else:
|
|
56
|
+
print(spot.center, spot.score, spot.box)
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Chaining
|
|
60
|
+
|
|
61
|
+
`Screen.find / wait / click` all return a `Spot` (or `None` for `find`):
|
|
62
|
+
|
|
63
|
+
```python
|
|
64
|
+
screen.wait("menu.png", timeout=5) \
|
|
65
|
+
.highlight(duration=0.6, mark_center=True) \
|
|
66
|
+
.hover() \
|
|
67
|
+
.click(button="left") \
|
|
68
|
+
.wait_vanish(timeout=5, strict=False)
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
| `Spot` member | Description |
|
|
72
|
+
|---|---|
|
|
73
|
+
| `box` | matched rectangle (`Box`) in absolute screen pixels |
|
|
74
|
+
| `center` | `(x, y)` of the match center |
|
|
75
|
+
| `score` | normalized match score in `[0.0, 1.0]` |
|
|
76
|
+
| `highlight(...)` | draw a temporary border; `mark_center=True` adds a cross |
|
|
77
|
+
| `click(button="left", hold=None, highlight=False)` | click the center |
|
|
78
|
+
| `double_click()`, `right_click()` | convenience wrappers |
|
|
79
|
+
| `hover(highlight=True, duration=None)` | move the pointer to the center |
|
|
80
|
+
| `wait_vanish(timeout, strict=True)` | wait until the image is gone |
|
|
81
|
+
|
|
82
|
+
## Bundle path
|
|
83
|
+
|
|
84
|
+
Relative image names are resolved against a configurable bundle path:
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
import screenspot
|
|
88
|
+
|
|
89
|
+
screenspot.set_bundle_path("assets/images")
|
|
90
|
+
screenspot.get_bundle_path() # -> .../assets/images
|
|
91
|
+
screenspot.resolve_path("ok.png") # -> .../assets/images/ok.png
|
|
92
|
+
|
|
93
|
+
screenspot.config.bundle_path = None # clear; relative names resolve against the cwd
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
The value is process-wide. `Screen(bundle_path=...)` sets a per-screen override that wins
|
|
97
|
+
over the global value:
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
screen = Screen(bundle_path="suite_a/images") # only this screen uses suite_a
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Absolute paths always bypass the bundle path. `resolve_path()` does not check that the file
|
|
104
|
+
exists, so it is the quickest way to verify a change.
|
|
105
|
+
|
|
106
|
+
## Scoped regions
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
panel = screen.region(1200, 100, 600, 800) # absolute top-left corner + size
|
|
110
|
+
panel.wait("save.png", timeout=5).click()
|
|
111
|
+
|
|
112
|
+
# Spot coordinates are still absolute, so clicks land in the right place.
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
`RegionView` supports `find`, `wait`, `click`, and `wait_vanish`; it does not nest.
|
|
116
|
+
|
|
117
|
+
## API overview
|
|
118
|
+
|
|
119
|
+
| Call | Returns | Notes |
|
|
120
|
+
|---|---|---|
|
|
121
|
+
| `Screen(bundle_path=None, threshold=0.85, interval=0.25)` | `Screen` | components are injectable for tests |
|
|
122
|
+
| `screen.find(image, threshold=None, region=None)` | `Spot \| None` | single lookup |
|
|
123
|
+
| `screen.wait(image, timeout=10, ...)` | `Spot` | raises `WaitTimeout` |
|
|
124
|
+
| `screen.click(image, timeout=10, ...)` | `Spot` | wait + click |
|
|
125
|
+
| `screen.wait_vanish(image, timeout=10, strict=True)` | `bool` | raises `VanishTimeout` when strict |
|
|
126
|
+
| `screen.region(x, y, width, height)` | `RegionView` | scoped proxy |
|
|
127
|
+
| `screen.close()` | `None` | releases the capture handle |
|
|
128
|
+
|
|
129
|
+
Exceptions: `ScreenSpotError` (base), `TemplateNotFound`, `WaitTimeout`, `VanishTimeout`.
|
|
130
|
+
|
|
131
|
+
## How it works
|
|
132
|
+
|
|
133
|
+
1. `Grabber` captures the monitor or a region as a BGR `numpy` frame (`mss`).
|
|
134
|
+
2. `Matcher` runs `cv2.matchTemplate(..., TM_CCOEFF_NORMED)` and returns the best score and
|
|
135
|
+
top-left corner; template images are cached by path and modification time.
|
|
136
|
+
3. Coordinates are converted to absolute screen space, then `Spot` exposes fluent actions.
|
|
137
|
+
4. `Pointer` lazily imports `pyautogui` for clicks and pointer moves.
|
|
138
|
+
|
|
139
|
+
Highlighting is best effort: on a desktop without `tkinter`, or when
|
|
140
|
+
`SCREENSPOT_NO_OVERLAY=1` is set, matching and clicking still work.
|
|
141
|
+
|
|
142
|
+
## Platform notes
|
|
143
|
+
|
|
144
|
+
- Windows and Linux X11 are the supported targets; Wayland-only and headless sessions are not.
|
|
145
|
+
- High-DPI scaling can shift coordinates; make sure screenshots/templates match the
|
|
146
|
+
effective resolution.
|
|
147
|
+
- Screen recording and keyboard automation are intentionally out of scope.
|
|
148
|
+
|
|
149
|
+
## Development
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
python -m venv .venv
|
|
153
|
+
.venv/Scripts/pip install -e ".[test]" # Windows
|
|
154
|
+
# .venv/bin/pip install -e ".[test]" # Linux
|
|
155
|
+
python -m pytest
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
## Publishing to PyPI
|
|
159
|
+
|
|
160
|
+
The distribution name `screenspot` was unclaimed on PyPI when this project was created;
|
|
161
|
+
re-check before the first release.
|
|
162
|
+
|
|
163
|
+
```bash
|
|
164
|
+
python -m pip install --upgrade build twine
|
|
165
|
+
python -m build
|
|
166
|
+
twine check dist/*
|
|
167
|
+
|
|
168
|
+
# Dry run against TestPyPI first
|
|
169
|
+
twine upload --repository testpypi dist/*
|
|
170
|
+
python -m pip install --index-url https://test.pypi.org/simple/ screenspot
|
|
171
|
+
|
|
172
|
+
# Real release
|
|
173
|
+
twine upload dist/*
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Use a PyPI API token (account settings → API tokens) as the password with username
|
|
177
|
+
`__token__`, preferably via `~/.pypirc` or the `TWINE_PASSWORD` environment variable. Never
|
|
178
|
+
commit tokens or paste them into chat.
|
|
179
|
+
|
|
180
|
+
## License
|
|
181
|
+
|
|
182
|
+
MIT — see [LICENSE](LICENSE). This is an independent implementation; it does not contain code
|
|
183
|
+
from any proprietary library.
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "screenspot"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Locate template images on screen and act on them with fluent, chainable calls."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.10"
|
|
13
|
+
authors = [
|
|
14
|
+
{ name = "screenspot contributors" }
|
|
15
|
+
]
|
|
16
|
+
keywords = [
|
|
17
|
+
"automation",
|
|
18
|
+
"gui-testing",
|
|
19
|
+
"opencv",
|
|
20
|
+
"template-matching",
|
|
21
|
+
"screen",
|
|
22
|
+
"pyautogui",
|
|
23
|
+
]
|
|
24
|
+
classifiers = [
|
|
25
|
+
"Development Status :: 3 - Alpha",
|
|
26
|
+
"Intended Audience :: Developers",
|
|
27
|
+
"Operating System :: Microsoft :: Windows",
|
|
28
|
+
"Operating System :: POSIX :: Linux",
|
|
29
|
+
"Programming Language :: Python :: 3",
|
|
30
|
+
"Programming Language :: Python :: 3.10",
|
|
31
|
+
"Programming Language :: Python :: 3.11",
|
|
32
|
+
"Programming Language :: Python :: 3.12",
|
|
33
|
+
"Programming Language :: Python :: 3.13",
|
|
34
|
+
"Topic :: Software Development :: Testing",
|
|
35
|
+
"Typing :: Typed",
|
|
36
|
+
]
|
|
37
|
+
dependencies = [
|
|
38
|
+
"numpy>=1.24",
|
|
39
|
+
"opencv-python>=4.8",
|
|
40
|
+
"mss>=9",
|
|
41
|
+
"pyautogui>=0.9.54",
|
|
42
|
+
]
|
|
43
|
+
|
|
44
|
+
[project.optional-dependencies]
|
|
45
|
+
test = ["pytest>=8"]
|
|
46
|
+
|
|
47
|
+
[project.urls]
|
|
48
|
+
Homepage = "https://pypi.org/project/screenspot/"
|
|
49
|
+
|
|
50
|
+
[tool.setuptools]
|
|
51
|
+
package-dir = { "" = "src" }
|
|
52
|
+
|
|
53
|
+
[tool.setuptools.package-data]
|
|
54
|
+
screenspot = ["py.typed"]
|
|
55
|
+
|
|
56
|
+
[tool.setuptools.packages.find]
|
|
57
|
+
where = ["src"]
|
|
58
|
+
|
|
59
|
+
[tool.pytest.ini_options]
|
|
60
|
+
testpaths = ["tests"]
|
|
61
|
+
addopts = "-ra"
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
"""screenspot - locate template images on screen and act on them fluently.
|
|
2
|
+
|
|
3
|
+
Basic usage::
|
|
4
|
+
|
|
5
|
+
from screenspot import Screen
|
|
6
|
+
|
|
7
|
+
screen = Screen(bundle_path="assets/images")
|
|
8
|
+
screen.wait("login.png", timeout=10).highlight().click()
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
from .bundle import (
|
|
14
|
+
BundleConfig,
|
|
15
|
+
config,
|
|
16
|
+
get_bundle_path,
|
|
17
|
+
resolve_path,
|
|
18
|
+
set_bundle_path,
|
|
19
|
+
)
|
|
20
|
+
from .errors import (
|
|
21
|
+
ScreenSpotError,
|
|
22
|
+
TemplateNotFound,
|
|
23
|
+
VanishTimeout,
|
|
24
|
+
WaitTimeout,
|
|
25
|
+
)
|
|
26
|
+
from .geometry import Box
|
|
27
|
+
from .screen import RegionView, Screen, Spot
|
|
28
|
+
|
|
29
|
+
__version__ = "0.1.0"
|
|
30
|
+
|
|
31
|
+
__all__ = [
|
|
32
|
+
"Box",
|
|
33
|
+
"BundleConfig",
|
|
34
|
+
"RegionView",
|
|
35
|
+
"Screen",
|
|
36
|
+
"ScreenSpotError",
|
|
37
|
+
"Spot",
|
|
38
|
+
"TemplateNotFound",
|
|
39
|
+
"VanishTimeout",
|
|
40
|
+
"WaitTimeout",
|
|
41
|
+
"config",
|
|
42
|
+
"get_bundle_path",
|
|
43
|
+
"resolve_path",
|
|
44
|
+
"set_bundle_path",
|
|
45
|
+
]
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
"""Resolution of template image names against a configurable bundle path.
|
|
2
|
+
|
|
3
|
+
A *bundle path* is a folder that holds template images. Setting it once lets
|
|
4
|
+
callers pass bare names such as ``"ok.png"`` instead of absolute paths::
|
|
5
|
+
|
|
6
|
+
import screenspot
|
|
7
|
+
|
|
8
|
+
screenspot.set_bundle_path("assets/images")
|
|
9
|
+
screenspot.resolve_path("ok.png") # -> .../assets/images/ok.png
|
|
10
|
+
screenspot.get_bundle_path() # -> .../assets/images
|
|
11
|
+
|
|
12
|
+
Absolute names always bypass the bundle path. Without a bundle path, relative
|
|
13
|
+
names resolve against the current working directory.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
from pathlib import Path
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def normalize_bundle(path: str | Path | None) -> Path | None:
|
|
22
|
+
"""Normalize a bundle path value, validating it when it exists.
|
|
23
|
+
|
|
24
|
+
Args:
|
|
25
|
+
path: Folder holding template images, or ``None`` / ``""`` to clear.
|
|
26
|
+
|
|
27
|
+
Returns:
|
|
28
|
+
The absolute folder path, or ``None`` when cleared.
|
|
29
|
+
|
|
30
|
+
Raises:
|
|
31
|
+
NotADirectoryError: If ``path`` exists but is not a directory.
|
|
32
|
+
"""
|
|
33
|
+
if path is None or str(path).strip() == "":
|
|
34
|
+
return None
|
|
35
|
+
|
|
36
|
+
candidate = Path(path).expanduser().resolve()
|
|
37
|
+
if candidate.exists() and not candidate.is_dir():
|
|
38
|
+
raise NotADirectoryError(f"bundle path is not a directory: {candidate}")
|
|
39
|
+
return candidate
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def resolve_against(image: str | Path, bundle_path: Path | None) -> Path:
|
|
43
|
+
"""Resolve one image reference against an explicit bundle path."""
|
|
44
|
+
candidate = Path(image).expanduser()
|
|
45
|
+
if candidate.is_absolute():
|
|
46
|
+
return candidate.resolve()
|
|
47
|
+
if bundle_path is None:
|
|
48
|
+
return candidate.resolve()
|
|
49
|
+
return (bundle_path / candidate).resolve()
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
class BundleConfig:
|
|
53
|
+
"""Process-wide template image configuration.
|
|
54
|
+
|
|
55
|
+
Assign :attr:`bundle_path` directly for a quick change, or use the
|
|
56
|
+
module-level :func:`set_bundle_path` helper. Instances are not needed:
|
|
57
|
+
the package exposes a ready-made :data:`config` object.
|
|
58
|
+
"""
|
|
59
|
+
|
|
60
|
+
__slots__ = ("_bundle_path",)
|
|
61
|
+
|
|
62
|
+
def __init__(self, bundle_path: str | Path | None = None) -> None:
|
|
63
|
+
self._bundle_path = normalize_bundle(bundle_path)
|
|
64
|
+
|
|
65
|
+
@property
|
|
66
|
+
def bundle_path(self) -> Path | None:
|
|
67
|
+
"""Current bundle path, or ``None`` when unset."""
|
|
68
|
+
return self._bundle_path
|
|
69
|
+
|
|
70
|
+
@bundle_path.setter
|
|
71
|
+
def bundle_path(self, value: str | Path | None) -> None:
|
|
72
|
+
self._bundle_path = normalize_bundle(value)
|
|
73
|
+
|
|
74
|
+
def resolve(self, image: str | Path) -> Path:
|
|
75
|
+
"""Resolve an image reference against the configured bundle path."""
|
|
76
|
+
return resolve_against(image, self._bundle_path)
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
config = BundleConfig()
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def set_bundle_path(path: str | Path | None) -> Path | None:
|
|
83
|
+
"""Set or clear the bundle path used for relative image names.
|
|
84
|
+
|
|
85
|
+
Args:
|
|
86
|
+
path: Folder holding template images, or ``None`` / ``""`` to clear.
|
|
87
|
+
|
|
88
|
+
Returns:
|
|
89
|
+
The normalized bundle path, or ``None`` when cleared.
|
|
90
|
+
"""
|
|
91
|
+
config.bundle_path = path
|
|
92
|
+
return config.bundle_path
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def get_bundle_path() -> Path | None:
|
|
96
|
+
"""Return the current bundle path, or ``None`` when unset."""
|
|
97
|
+
return config.bundle_path
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def resolve_path(image: str | Path) -> Path:
|
|
101
|
+
"""Return the absolute path used for ``image``.
|
|
102
|
+
|
|
103
|
+
The file is not checked for existence; this is also the simplest way to
|
|
104
|
+
verify that :func:`set_bundle_path` took effect.
|
|
105
|
+
"""
|
|
106
|
+
return config.resolve(image)
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
"""Screen capture backend built on :mod:`mss`."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import numpy as np
|
|
6
|
+
|
|
7
|
+
from .geometry import Box
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class Grabber:
|
|
11
|
+
"""Captures the primary monitor, or a sub-region, as a BGR frame."""
|
|
12
|
+
|
|
13
|
+
def __init__(self) -> None:
|
|
14
|
+
import mss
|
|
15
|
+
|
|
16
|
+
self._sct = mss.mss()
|
|
17
|
+
|
|
18
|
+
def grab(self, region: Box | None = None) -> np.ndarray:
|
|
19
|
+
"""Return a BGR ``numpy`` array for ``region`` (or the whole monitor)."""
|
|
20
|
+
monitor = region.to_mss() if region is not None else self._sct.monitors[1]
|
|
21
|
+
shot = self._sct.grab(monitor)
|
|
22
|
+
frame = np.asarray(shot, dtype=np.uint8)
|
|
23
|
+
return np.ascontiguousarray(frame[:, :, :3])
|
|
24
|
+
|
|
25
|
+
def close(self) -> None:
|
|
26
|
+
"""Release the underlying capture handle."""
|
|
27
|
+
close = getattr(self._sct, "close", None)
|
|
28
|
+
if close is not None:
|
|
29
|
+
close()
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
"""Exception hierarchy for :mod:`screenspot`."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class ScreenSpotError(Exception):
|
|
7
|
+
"""Base class for every error raised by this package."""
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class TemplateNotFound(ScreenSpotError, FileNotFoundError):
|
|
11
|
+
"""Raised when a template image is missing on disk or cannot be decoded."""
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class WaitTimeout(ScreenSpotError):
|
|
15
|
+
"""Raised when an image does not appear before the timeout expires."""
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class VanishTimeout(WaitTimeout):
|
|
19
|
+
"""Raised when an image is still visible after the timeout expires."""
|