# What Is the Purpose of core.py in holehe?

> Discover the purpose of core.py in holehe. This file orchestrates the email OSINT tool, handling arguments, modules, requests, and results for efficient data gathering.

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

---

**The [`core.py`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/core.py) through the command-line interface or import its functions programmatically.

### Command-Line Usage

```bash

# 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:

```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:

```python
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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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`](https://github.com/megadose/holehe/blob/main/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.