What Is the Purpose of core.py in holehe?

The core.py file functions as the central command-line driver and orchestration engine for the holehe email OSINT tool, handling everything from parsing CLI arguments and dynamically discovering website check modules to executing concurrent HTTP requests via Trio and formatting the final results.

The megadose/holehe repository is an open-source intelligence gathering utility designed to identify whether an email address is registered across hundreds of websites. The holehe/core.py file serves as the nerve center that binds all components together, transforming a simple email input into a comprehensive cross-platform investigation using asynchronous Python patterns.

Core Responsibilities of holehe core.py

The core.py module is not merely an entry point; it is a fully-fledged execution engine that implements the complete workflow from user input to final report generation.

CLI Argument Parsing (Lines 80‑96)

At startup, core.py defines the command-line interface using Python’s ArgumentParser. This section configures options such as --only-used to filter results to confirmed registrations only, --no-color for plain text output suitable for logging pipelines, and --csv to enable spreadsheet export. These arguments dictate the behavior of the subsequent verification workflow.

Dynamic Module Discovery (Lines 37‑47 and 50‑64)

Rather than hardcoding individual website checks, core.py discovers functionality dynamically. The import_submodules function (lines 37‑47) recursively imports every package within holehe.modules, while get_functions (lines 50‑64) introspects these packages to extract callable functions. This architecture allows new site checkers to be added to the modules/ directory without modifying the core logic.

Email Validation (Lines 94‑105)

Before launching network requests, the is_email function (lines 94‑105) validates that the user-supplied argument conforms to standard email syntax. This prevents wasted computation on malformed inputs and ensures downstream modules receive properly formatted data.

Asynchronous Execution Engine (Lines 78‑122)

The heart of core.py is the maincore async workflow (spanning lines 78‑84, 98‑110, and 114‑122). This function creates an httpx.AsyncClient for HTTP communication and leverages Trio to open a nursery. Inside this nursery, it spawns a coroutine for every discovered website-checking function, enabling hundreds of simultaneous network requests. Each coroutine operates independently, aggregating results into a shared collection without blocking the main thread.

Result Formatting and Display (Lines 106‑151)

Once checks complete, the print_result function (lines 106‑151) processes the raw output. It sorts the results and renders a color-coded terminal summary indicating whether an email exists on a given site, if account recovery information is available, or if the service returned rate-limit or error statuses. The color output can be suppressed via the --no-color flag parsed earlier.

CSV Export Functionality (Lines 154‑164)

For data persistence, the export_csv function (lines 154‑164) writes the aggregated results to a timestamped CSV file when the --csv flag is present. This produces machine-readable output suitable for further analysis in spreadsheet applications or SIEM tools.

Self-Update Mechanism (Lines 65‑87)

The check_update function (lines 65‑87) contacts the Python Package Index (PyPI) to determine if a newer version of holehe exists. If an update is detected, it automatically invokes pip to upgrade the package, ensuring users always run the latest version with the most recent site modules.

Entry Point (Lines 132‑134)

The main function (lines 132‑134) serves as the synchronous entry point that bridges the blocking CLI world with the async runtime. It simply invokes trio.run to execute the maincore async workflow, handling the transition between synchronous argument parsing and asynchronous network I/O.

How core.py Orchestrates the Workflow

Understanding the interplay between these functions clarifies how holehe transforms an email string into a full OSINT report. The execution flow follows this pattern:

• Parse: main() calls the argument parser (lines 80‑96) to interpret user input.
• Discover: import_submodules and get_functions (lines 37‑64) build a list of all available site checkers from holehe.modules.
• Validate: is_email (lines 94‑105) verifies the target address.
• Execute: maincore (lines 78‑122) initializes httpx.AsyncClient and uses Trio to run every site checker concurrently.
• Format: print_result (lines 106‑151) displays the terminal output, while export_csv (lines 154‑164) optionally writes to disk.

Practical Usage Examples

You can interact with core.py through the command-line interface or import its functions programmatically.

Command-Line Usage

# Basic check against all supported sites

holehe target@example.com

# Filter to show only confirmed registrations

holehe target@example.com --only-used

# Export results to CSV and disable colors for logging

holehe target@example.com --csv --no-color

Programmatic Execution

The following example demonstrates how to invoke the core logic directly from Python:

from holehe.core import import_submodules, get_functions
import httpx
import trio

async def check_email(email):
    # Load all website checking modules dynamically

    modules = import_submodules("holehe.modules")
    websites = get_functions(modules)
    
    client = httpx.AsyncClient(timeout=10)
    results = []
    
    async with trio.open_nursery() as nursery:
        for site_func in websites:
            nursery.start_soon(site_func, email, client, results)
    
    await client.aclose()
    return results

# Run the check

email = "test@example.com"
output = trio.run(check_email, email)
print(f"Found {len(output)} results")

Manual CSV Export

To export results manually when using the programmatic API:

from holehe.core import export_csv

# Assuming 'results' is the list returned from the async check

export_csv(results, args=type('Args', (), {'csvoutput': True}), email="test@example.com")

Summary

• holehe/core.py acts as the central orchestrator for the holehe OSINT tool, located at the root of the package structure.
• It dynamically discovers checking modules via import_submodules (lines 37‑47) and get_functions (lines 50‑64), eliminating the need to hardcode website targets.
• The file manages high-performance asynchronous execution using Trio and httpx.AsyncClient within the maincore workflow (lines 78‑122).
• Built-in utilities include email validation (is_email, lines 94‑105), color-coded terminal output (print_result, lines 106‑151), and CSV serialization (export_csv, lines 154‑164).
• It provides a self-updating mechanism (check_update, lines 65‑87) that queries PyPI and auto-upgrades the package when necessary.

Frequently Asked Questions

What does core.py do in holehe?

The core.py file serves as the main execution driver and CLI frontend for holehe. According to the megadose/holehe source code, it handles argument parsing, dynamically loads website checking modules from holehe.modules, validates email syntax, executes concurrent HTTP requests using Trio, and formats the results for terminal display or CSV export.

How does core.py load website checking modules?

Instead of maintaining a static list of supported sites, core.py uses the import_submodules function (lines 37‑47) to recursively import all packages in holehe/modules/, then extracts callable functions using get_functions (lines 50‑64). This plugin-style architecture allows developers to add new site checkers simply by dropping Python files into the modules directory.

What async library does holehe core.py use?

The core.py module uses Trio as its primary asynchronous I/O library, specifically using trio.run to execute the maincore async function and trio.open_nursery() to manage hundreds of concurrent website checks. It pairs this with httpx.AsyncClient for non-blocking HTTP requests.

Can I use core.py functions programmatically without the CLI?

Yes, you can import functions directly from holehe.core for use in other Python applications. Key functions like import_submodules, get_functions, and export_csv are available for import, allowing you to build custom workflows that leverage holehe’s module discovery and result formatting capabilities without invoking the command-line interface.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}