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.
@@ -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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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."""