# What Does `holehe/core.py` Do? Understanding the Main Engine of Holehe

> Discover what holehe/core.py does. This file orchestrates the Holehe OSINT tool, managing modules, concurrency, and results for efficient email verification.

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

---

**[`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) serves as the central orchestrator of the megadose/holehe OSINT tool, handling CLI argument parsing, dynamic discovery of email-verification modules, concurrent asynchronous execution via Trio, and formatted result presentation.**

The megadose/holehe repository provides an open-source intelligence utility that checks whether an email address exists across hundreds of online services. The [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) file acts as the glue between user input and the modular probe system, managing everything from version checks to CSV export.

## Command-Line Interface and Argument Parsing

The file configures the user-facing CLI using Python’s `ArgumentParser` at lines [80‑96](https://github.com/megadose/holehe/blob/master/holehe/core.py#L80). This setup processes flags such as:

- `--only-used` – Filter results to show only services where the email was found
- `--no-color` – Disable ANSI color codes in terminal output
- `--csv` – Export findings to a comma-separated values file

The parser validates the supplied email address via an `is_email` helper before proceeding to the execution phase.

## Self-Update Mechanism

Before launching probes, [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) queries the Python Package Index (PyPI) to determine whether the local installation is outdated. The `check_update()` function (lines [65‑87](https://github.com/megadose/holehe/blob/master/holehe/core.py#L65)) compares the installed version against the latest release. If a mismatch is detected, the function triggers an automatic `pip upgrade` to ensure users run the most recent probe definitions.

## Dynamic Module Discovery and Loading

Rather than hard-coding service checks, the engine dynamically discovers capabilities by introspecting the `holehe.modules` package. Two key functions drive this process at lines [37‑64](https://github.com/megadose/holehe/blob/master/holehe/core.py#L37):

- **`import_submodules()`** – Recursively walks the `holehe/modules` directory tree and imports every submodule
- **`get_functions()`** – Extracts callable probe functions from the imported modules

This architecture allows developers to add new service checks by simply dropping Python files into the modules directory without modifying [`core.py`](https://github.com/megadose/holehe/blob/main/core.py) itself.

## Asynchronous Execution Engine

The core concurrency model relies on **Trio** for structured concurrency and **httpx** for HTTP traffic. At lines [66‑84](https://github.com/megadose/holehe/blob/master/holehe/core.py#L66) and [18‑22](https://github.com/megadose/holehe/blob/master/holehe/core.py#L18), the `maincore()` function:

1. Instantiates an `httpx.AsyncClient` for connection pooling
2. Creates a Trio nursery to manage task lifetimes
3. Spawns each probe via **`launch_module()`**, passing the shared HTTP client and results list
4. Attaches the **`TrioProgress`** instrument (defined in [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py)) to render a live progress bar during execution

This parallel approach ensures that hundreds of services are queried simultaneously rather than sequentially, dramatically reducing runtime.

## Result Handling and Output Formatting

Once the nursery completes, [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) aggregates outcomes and delegates formatting to dedicated helpers at lines [6‑52](https://github.com/megadose/holehe/blob/master/holehe/core.py#L6) and [54‑66](https://github.com/megadose/holehe/blob/master/holehe/core.py#L54):

- **`print_result()`** – Renders color-coded symbols (green for found, red for not found, yellow for rate-limited) in the terminal
- **`export_csv()`** – Writes machine-readable output when the `--csv` flag is present

The file also re-displays the credit banner before exiting, ensuring attribution remains visible.

## Practical Usage Examples

*Running holehe from the command line:*

```bash
python -m holehe core.py email@example.com --csv --no-color

```

*Using the core programmatically:*

```python
import trio
import httpx
from holehe.core import import_submodules, get_functions, launch_module

async def run_one_probe(email):
    modules = import_submodules("holehe.modules")
    funcs = get_functions(modules)          # list of probe callables

    client = httpx.AsyncClient()
    results = []
    for fn in funcs:
        await launch_module(fn, email, client, results)
    await client.aclose()
    return results

```

## Summary

- **[`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py)** is the execution engine of the megadose/holehe tool, residing at the repository root.
- It parses CLI arguments including `--csv` and `--no-color` using `ArgumentParser` (lines 80‑96).
- The **`check_update()`** function (lines 65‑87) ensures the tool is current against PyPI.
- **`import_submodules()`** and **`get_functions()`** (lines 37‑64) dynamically load verification logic from `holehe/modules`.
- Concurrent execution uses Trio nurseries, `httpx.AsyncClient`, and **`launch_module()`** (lines 66‑84).
- Results are rendered via **`print_result()`** and optionally exported via **`export_csv()`**.

## Frequently Asked Questions

### What is the entry point function in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py)?

The synchronous entry point is **`main()`** at line 33, which immediately delegates to the asynchronous **`maincore()`** function via `trio.run(maincore)`. This pattern bridges Python’s synchronous CLI requirements with Trio’s async runtime.

### How does [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) handle concurrent module execution?

It creates a Trio nursery that spawns each service probe as a separate task. All tasks share a single `httpx.AsyncClient` instance for efficient connection reuse. The `TrioProgress` instrument (from [`holehe/instruments.py`](https://github.com/megadose/holehe/blob/main/holehe/instruments.py)) hooks into Trio’s event loop to display a live progress bar as tasks complete.

### Can I use [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) functions in my own Python scripts?

Yes. You can import **`import_submodules()`**, **`get_functions()`**, and **`launch_module()`** to programmatically execute probes without invoking the CLI. You must provide your own `httpx.AsyncClient`, manage the Trio event loop with `trio.run()`, and handle the results list manually, as shown in the example above.

### What output formats does [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) support?

By default, it produces human-readable terminal output with color-coded status symbols. When invoked with the `--csv` flag, the **`export_csv()`** function (lines 54‑66) writes results to a comma-separated file suitable for spreadsheet or database ingestion.