# What Is `holehe/instruments.py`? Inside Holehe's Async Progress Instrumentation

> Explore holehe/instruments.py and its TrioProgress class, which enhances async email scans with real-time Rich progress bars in the Holehe OSINT tool for better user feedback.

- Repository: [Palenath/holehe](https://github.com/megadose/holehe)
- Tags: internals
- Published: 2026-09-10

---

**[`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py) provides the `TrioProgress` class that wraps the Rich progress-bar library to deliver real-time visual feedback during asynchronous email scans in the Holehe OSINT tool.**

The `megadose/holehe` repository is an open-source intelligence (OSINT) framework that verifies email addresses across hundreds of platforms. The [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py) file serves as the instrumentation layer, transforming silent asynchronous HTTP requests into observable progress updates for the command-line interface.

## The Role of [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py) in Email Scanning

This module supplies the **runtime instrumentation** required to monitor scan progress without blocking concurrent operations. When Holehe queries services like Facebook, GitHub, or Spotify simultaneously, these requests execute asynchronously via the Trio library. Without the instrumentation provided by [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py), the CLI would offer no indication of which services are being checked or when individual checks complete.

The file solves this visibility gap by implementing `TrioProgress`, a specialized adapter that integrates Rich's terminal rendering capabilities with Trio's structured concurrency model.

## The `TrioProgress` Class Architecture

At the heart of [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py) lies the `TrioProgress` class. This thin wrapper handles task registration, progress updates, and graceful cancellation for the multi-service scanning process.

### Rich Integration for Visual Feedback

The class initializes a Rich `Progress` instance configured with columns for task descriptions, bar visualization, and percentage completion. It stores the target `email` and HTTP `client` references to maintain context throughout the scan lifecycle.

### Trio Integration for Async Coordination

Unlike standard progress bars, `TrioProgress` operates within Trio's nursery system. It manages an internal task registry that aligns with Trio's cancellation semantics, ensuring that progress updates occur safely across asynchronous boundaries without introducing race conditions or blocking the event loop.

## How [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) Orchestrates Progress Tracking

The main entry point in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) imports `TrioProgress` from [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py) to coordinate the scan workflow. During execution, the core module instantiates the progress tracker, registers individual tasks for each OSINT module (e.g., `facebook`, `github`, `spotify`), and invokes the concurrent runner.

Individual service modules located in `holehe/modules/*/*.py` receive the progress object instance as a parameter, allowing them to signal completion directly to the Rich interface as each asynchronous request finishes.

## Implementation Details and Code Examples

The `TrioProgress` implementation in [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py) exposes specific methods for task lifecycle management.

Here is the simplified class structure found in the source:

```python

# Inside holehe/instruments.py (simplified)

class TrioProgress:
    def __init__(self, email, client):
        self.progress = Progress(
            "[progress.description]{task.description}",
            BarColumn(),
            "[progress.percentage]{task.percentage:>3.0f}%"
        )
        self.email = email
        self.client = client

    def add_task(self, description: str):
        return self.progress.add_task(description)

    async def run_all(self, modules):
        async with self.progress:
            async with trio.open_nursery() as nursery:
                for mod in modules:
                    nursery.start_soon(self._run_module, mod)

    async def _run_module(self, mod):
        await mod(self.email, self.client, self.progress)

```

When `holehe.core` executes a scan, it utilizes the instrumentation as follows:

```python

# Typical usage inside holehe.core

from holehe.instruments import TrioProgress

async def run_scan(email):
    # Initialise a progress bar that knows about the async client

    prog = TrioProgress(email=email, client=client)

    # Register a task for each module we are about to query

    for mod in modules_to_check:
        prog.add_task(mod.__name__)

    # Run the async checks; each module will call prog.update(task_id) when done

    await prog.run_all(modules_to_check)

```

## Summary

- **[`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py)** implements the `TrioProgress` class, providing the visual instrumentation layer for the Holehe scanner.
- **`TrioProgress`** acts as a bridge between the Rich progress-bar library and Trio's asynchronous runtime, handling task registration and updates safely across concurrent service checks.
- **[`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py)** imports and instantiates `TrioProgress` to track the status of individual OSINT modules located in `holehe/modules/*/*.py`.
- The module handles **cancellation and clean-up** when scans are interrupted, ensuring terminal state remains consistent even during abrupt exits.

## Frequently Asked Questions

### What is the primary function of [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py)?

[`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py) provides the `TrioProgress` class, which supplies real-time visual feedback during email scans. It wraps the Rich library to render progress bars while adapting the interface for Trio's asynchronous concurrency model.

### How does `TrioProgress` differ from standard progress bars?

Standard progress bars typically block or use threading, but `TrioProgress` is specifically designed for **structured concurrency** via Trio. It manages task updates across multiple concurrent OSINT checks without blocking the event loop, and it respects Trio's cancellation semantics for clean shutdowns.

### Which files interact with [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py) during a scan?

The **[`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py)** file imports `TrioProgress` to orchestrate the overall scan workflow. Additionally, every service-specific module in **`holehe/modules/*/*.py`** (such as [`facebook.py`](https://github.com/megadose/holehe/blob/main/facebook.py) or [`github.py`](https://github.com/megadose/holehe/blob/main/github.py)) receives the progress object instance to report when their individual asynchronous requests complete.

### Does `TrioProgress` handle task cancellation?

Yes, the implementation in [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py) handles cancellation and clean-up when a scan is interrupted. Because it operates within Trio's nursery system, it ensures that all progress bar tasks are properly closed and terminal state is restored even if the user stops the scan prematurely.