You're Invited:Meet the Socket Team at BlackHat and DEF CON in Las Vegas, Aug 4-6.RSVP
Socket
Book a DemoInstallSign in
Socket

pyshotter

Package Overview
Dependencies
Maintainers
1
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

pyshotter

PyShotter: Smart, annotated, and shareable screenshots for Python.

1.0.0
Source
pipPyPI
Maintainers
1

PyShotter

PyPI version Tests workflow Downloads

[!TIP] PyShotter - Smart, annotated, and shareable screenshots for Python.

from pyshotter import pyshotter

# The simplest use, save a screenshot of the 1st monitor
with pyshotter() as sct:
    sct.shot()

An ultra-fast cross-platform screenshot library that makes it easy to capture, annotate, and share screenshots from your Python code.

Features

Smart Detection

  • Code Region Detection - Automatically detect code blocks and windows using computer vision
  • Window Detection - Smart identification of application windows and UI elements
  • OCR Text Extraction - Extract text from screenshots using Tesseract OCR engine
  • Content Analysis - Intelligent analysis of screenshot content for better processing

Rich Annotation

  • Text Annotations - Add text with custom fonts, sizes, and colors
  • Shape Drawing - Rectangles, circles, arrows, and custom geometric shapes
  • Smart Highlighting - Semi-transparent overlays for emphasis and focus
  • Quick Markup - One-line annotation commands for rapid screenshot editing
  • Layer Management - Multiple annotation layers with proper compositing

Easy Sharing

  • Clipboard Copy - Copy screenshots directly to system clipboard
  • Shareable Links - Generate instant shareable URLs for screenshots
  • Cloud Upload - Upload to cloud services with embedded metadata
  • Cross-Platform - Works seamlessly on Windows, macOS, and Linux
  • Metadata Support - Rich metadata embedding for better organization

Advanced Features

  • Sensitive Data Redaction - Automatically blur emails, phone numbers, credit cards, and SSNs
  • Multi-Monitor Panorama - Stitch all monitors into one panoramic image
  • Change Detection - Highlight changes between screenshots with configurable sensitivity
  • Customizable Hotkeys - Set global hotkeys for screenshot capture and annotation
  • Screenshot History & Search - Searchable history with metadata and OCR text indexing
  • High Performance - Optimized for speed and efficiency using ctypes
  • Thread-Safe - Safe for multi-threaded applications

Installation

python -m pip install -U --user pyshotter

Optional Dependencies

For enhanced features, install additional dependencies:

# For OCR and advanced image processing
python -m pip install pyshotter[ocr]

# For annotation features
python -m pip install pyshotter[annotation]

# For sharing features
python -m pip install pyshotter[sharing]

# For cloud upload capabilities
python -m pip install pyshotter[cloud]

# For development
python -m pip install pyshotter[dev]

Quick Start

Basic Screenshot Capture

from pyshotter import pyshotter

# Take a screenshot of the first monitor
with pyshotter() as sct:
    sct.shot()

# Take screenshots of all monitors
with pyshotter() as sct:
    for i, monitor in enumerate(sct.monitors):
        sct.shot(mon=i)

Smart Detection and Analysis

from pyshotter import pyshotter, SmartDetectionFeature, OCRFeature

with pyshotter() as sct:
    screenshot = sct.grab(sct.monitors[0])
    
    # Detect code regions and windows
    detector = SmartDetectionFeature()
    code_regions = detector.detect_code_regions(screenshot)
    windows = detector.detect_windows(screenshot)
    
    print(f"Found {len(code_regions)} code regions")
    print(f"Found {len(windows)} windows")
    
    # Extract text using OCR
    ocr = OCRFeature()
    text = ocr.extract_text(screenshot)
    print(f"Extracted text: {text}")

Rich Annotation

from pyshotter import pyshotter, AnnotationFeature

with pyshotter() as sct:
    screenshot = sct.grab(sct.monitors[0])
    
    # Initialize annotation
    annotator = AnnotationFeature()
    
    # Add text annotation
    annotated = annotator.add_text(
        screenshot, 
        "Important Code Here!", 
        (100, 100),
        font_size=24,
        color=(255, 0, 0)  # Red text
    )
    
    # Add rectangle around a region
    annotated = annotator.add_rectangle(
        annotated,
        (50, 50),      # Top-left corner
        (400, 200),    # Bottom-right corner
        color=(0, 255, 0),  # Green rectangle
        thickness=3
    )
    
    # Add arrow pointing to something
    annotated = annotator.add_arrow(
        annotated,
        (150, 150),    # Start point
        (300, 100),    # End point
        color=(0, 0, 255),  # Blue arrow
        thickness=2
    )
    
    # Add circle highlight
    annotated = annotator.add_circle(
        annotated,
        (200, 150),    # Center point
        30,             # Radius
        color=(255, 255, 0),  # Yellow circle
        thickness=2
    )
    
    # Add highlight overlay
    annotated = annotator.add_highlight(
        annotated,
        (100, 100, 200, 100),  # (x, y, width, height)
        color=(255, 255, 0),    # Yellow highlight
        alpha=0.3               # 30% transparency
    )
    
    # Save the annotated screenshot
    annotated.save("annotated_screenshot.png")

Easy Sharing

from pyshotter import pyshotter, SharingFeature

with pyshotter() as sct:
    screenshot = sct.grab(sct.monitors[0])
    
    # Initialize sharing
    sharer = SharingFeature()
    
    # Copy to clipboard
    if sharer.copy_to_clipboard(screenshot):
        print("Screenshot copied to clipboard!")
    
    # Generate shareable link
    link = sharer.generate_shareable_link(screenshot)
    print(f"Shareable link: {link}")
    
    # Save with metadata
    metadata = {
        "title": "My Screenshot",
        "description": "Screenshot taken with PyShotter",
        "tags": ["python", "screenshot", "demo"],
        "author": "Abdoullah Ndao",
        "timestamp": "2024-12-19"
    }
    
    sharer.save_with_metadata(screenshot, "screenshot.png", metadata)

Sensitive Data Redaction

from pyshotter import pyshotter, RedactionFeature

with pyshotter() as sct:
    screenshot = sct.grab(sct.monitors[0])
    
    # Initialize redaction
    redaction = RedactionFeature()
    
    # Redact sensitive data
    clean_screenshot = redaction.redact_sensitive_data(screenshot)
    clean_screenshot.save("clean_screenshot.png")

Multi-Monitor Panorama

from pyshotter import pyshotter, PanoramaFeature

with pyshotter() as sct:
    # Capture all monitors
    screenshots = []
    for monitor in sct.monitors:
        screenshot = sct.grab(monitor)
        screenshots.append(screenshot)
    
    # Create panoramic image
    panorama = PanoramaFeature()
    panoramic_screenshot = panorama.create_panorama(screenshots)
    panoramic_screenshot.save("panorama.png")

Change Detection

import time
from pyshotter import pyshotter, ChangeDetectionFeature

with pyshotter() as sct:
    # Take first screenshot
    previous = sct.grab(sct.monitors[0])
    
    # Wait for changes
    time.sleep(5)
    
    # Take second screenshot
    current = sct.grab(sct.monitors[0])
    
    # Detect changes
    detector = ChangeDetectionFeature()
    changes = detector.detect_changes(current, previous, threshold=0.1)
    changes.save("changes.png")
from pyshotter import pyshotter, ScreenshotHistory

# Initialize history manager
history = ScreenshotHistory()

with pyshotter() as sct:
    screenshot = sct.grab(sct.monitors[0])
    
    # Add to history with metadata
    screenshot_id = history.add_screenshot(
        screenshot,
        metadata={
            "tags": ["desktop", "work"],
            "window_title": "Example Window",
            "description": "Sample screenshot for demonstration"
        }
    )
    
    # Search history
    results = history.search_history("work")
    for result in results:
        print(f"Found: {result['id']} - {result['timestamp']}")

API Reference

Core Functions

pyshotter(**kwargs)

Factory function that returns a platform-specific screenshot instance.

Parameters:

  • mon (int): Monitor index (default: 0)
  • output (str): Output filename pattern
  • with_cursor (bool): Include cursor in screenshot
  • compression_level (int): PNG compression level (0-9)

Returns:

  • Platform-specific screenshot instance

sct.shot(**kwargs)

Take a screenshot and save it to a file.

Parameters:

  • mon (int): Monitor index or monitor dict
  • output (str): Output filename
  • with_cursor (bool): Include cursor

Returns:

  • List of saved filenames

sct.grab(monitor)

Capture a screenshot without saving.

Parameters:

  • monitor (dict): Monitor configuration

Returns:

  • ScreenShot object

Smart Detection Features

SmartDetectionFeature.detect_code_regions(screenshot)

Detect code-like regions in screenshots.

Parameters:

  • screenshot (ScreenShot): Screenshot to analyze

Returns:

  • List of dictionaries with bounding boxes and confidence scores

SmartDetectionFeature.detect_windows(screenshot)

Detect application windows in screenshots.

Parameters:

  • screenshot (ScreenShot): Screenshot to analyze

Returns:

  • List of dictionaries with window bounding boxes

Annotation Features

AnnotationFeature.add_text(screenshot, text, position, font_size, color)

Add text annotation to a screenshot.

Parameters:

  • screenshot (ScreenShot): Screenshot to annotate
  • text (str): Text to add
  • position (tuple): (x, y) position
  • font_size (int): Font size
  • color (tuple): RGB color tuple

Returns:

  • Annotated ScreenShot object

AnnotationFeature.add_rectangle(screenshot, top_left, bottom_right, color, thickness)

Add rectangle annotation to a screenshot.

Parameters:

  • screenshot (ScreenShot): Screenshot to annotate
  • top_left (tuple): Top-left corner (x, y)
  • bottom_right (tuple): Bottom-right corner (x, y)
  • color (tuple): RGB color tuple
  • thickness (int): Line thickness

Returns:

  • Annotated ScreenShot object

Sharing Features

SharingFeature.copy_to_clipboard(screenshot)

Copy screenshot to system clipboard.

Parameters:

  • screenshot (ScreenShot): Screenshot to copy

Returns:

  • bool: Success status

SharingFeature.generate_shareable_link(screenshot, service)

Generate a shareable link for the screenshot.

Parameters:

  • screenshot (ScreenShot): Screenshot to share
  • service (str): Sharing service name

Returns:

  • str: Shareable URL or None

Examples

Basic Usage

from pyshotter import pyshotter

# Simple screenshot
with pyshotter() as sct:
    sct.shot()

# Screenshot with cursor
with pyshotter(with_cursor=True) as sct:
    sct.shot()

# Screenshot of specific monitor
with pyshotter() as sct:
    sct.shot(mon=1)  # Second monitor

Advanced Usage

from pyshotter import pyshotter, AnnotationFeature, SharingFeature

with pyshotter() as sct:
    # Capture screenshot
    screenshot = sct.grab(sct.monitors[0])
    
    # Annotate
    annotator = AnnotationFeature()
    annotated = annotator.add_text(screenshot, "Hello World!", (100, 100))
    annotated = annotator.add_rectangle(annotated, (50, 50), (300, 200))
    
    # Share
    sharer = SharingFeature()
    sharer.copy_to_clipboard(annotated)
    
    # Save
    annotated.save("final_screenshot.png")

Development

Setup Development Environment

git clone https://github.com/utachicodes/pyshotter.git
cd pyshotter
python -m pip install -e ".[dev]"

Running Tests

python -m pytest

Code Quality Checks

# Format code
ruff format src/

# Lint code
ruff check src/

# Type checking
mypy src/

# Run all checks
ruff check src/ && mypy src/ && python -m pytest

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Guidelines

  • Code Style: Follow PEP 8 and use Ruff for formatting
  • Type Hints: All functions should have proper type annotations
  • Documentation: Add docstrings for all public functions
  • Tests: Write tests for new features
  • Examples: Update examples when adding new features

License

This project is licensed under the MIT License - see the LICENSE.txt file for details.

Author

Abdoullah Ndao - GitHub - abdoullahaljersi@gmail.com

Acknowledgments

  • Built with love for the Python community
  • Cross-platform compatibility using ctypes
  • Smart features for modern development workflows
  • Inspired by the need for better screenshot tools in Python

Support

PyShotter - Making screenshots smart, annotated, and shareable!

Keywords

annotation

FAQs

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts