▣ screenagents

Three lines, one import

screenshot() returns a Screenshot, not a path. All the metadata you would otherwise re-derive is already on it.

python
from screenagents import screenshot, Region shot = screenshot("desktop.png") # full screenshot = screenshot("corner.png", region="0,0,640,480") # x,y,width,heightshot = screenshot("right.png", region="1920x1080+1920+0", overwrite=True)shot = screenshot("second.png", monitor=2) # 1-based, where supported print(shot.width, shot.height, shot.backend, shot.bytes)print(shot.to_dict())

Force a backend, pass a region object

python
from screenagents import screenshot, Region crop = Region(x=100, y=100, width=400, height=300)shot = screenshot("crop.png", region=crop, backend="grim", overwrite=True) # Region accepts both notations, and round-trips them:crop.csv # "100,100,400,300"crop.geometry # "400x300+100+100"
Captures land in a screenagents-tmp-*.png temp file next to the destination and are renamed into place only after the backend exits cleanly — never a dotfile, which macOS screencapture refuses to write. A failed capture never leaves a half-written image, and never clobbers the file that was already there.

Errors you can act on

python
from screenagents import screenshot, NoBackendError, CaptureError try: shot = screenshot("shot.png")except NoBackendError as exc: print("no usable backend:", exc) # tells you what to installexcept CaptureError as exc: print("capture failed:", exc) # backend stderr is included

Everything a Screenshot knows