Where to Find Example Modules in the holehe Repository: A Complete Guide

All example modules in the holehe repository are located in the holehe/modules/ directory, organized by service category such as shopping, music, and transport.

The megadose/holehe project provides a modular Python framework for verifying whether email addresses are registered on specific online services. Each integration ships as a self-contained example module under the holehe/modules/ package, demonstrating the exact implementation pattern required to check credentials against individual platforms.

Locating Example Modules in the holehe Repository

The example modules reside in the holehe/modules/ directory, categorized by service type. This architecture allows developers to locate reference implementations quickly and understand how the core runner discovers available services.

Module Categories and File Paths

Each subdirectory represents a different industry or service type, containing individual Python files for specific platforms:

• Transport: holehe/modules/transport/blablacar.py
• Shopping: holehe/modules/shopping/amazon.py and holehe/modules/shopping/ebay.py
• Music: holehe/modules/music/spotify.py and holehe/modules/music/soundcloud.py
• CRM: holehe/modules/crm/hubspot.py and holehe/modules/crm/amocrm.py
• Forums: holehe/modules/forum/mybb.py and holehe/modules/forum/thevapingforum.py

Every .py file in these subdirectories constitutes a complete, runnable example module that the core system can import and execute automatically.

Anatomy of an Example Module

Each module inherits from BaseModule, defined in holehe/core.py, and implements standardized methods for email verification. The Amazon class in holehe/modules/shopping/amazon.py illustrates this mandatory structure:

# Example: holehe/modules/shopping/amazon.py

from holehe.core import BaseModule

class Amazon(BaseModule):
    name = "Amazon"
    url = "https://www.amazon.com/ap/forgotpassword"
    # … service-specific implementation details …

This inheritance ensures that HoleheRunner can interact with every service using a uniform interface, while allowing custom logic for each platform's unique password recovery endpoints.

Running Example Modules

You can execute these modules either via the command-line interface or directly within Python scripts.

Command Line Execution

Run a specific module using the --module flag followed by the service identifier:

holehe email@example.com --module amazon

This command invokes only the Amazon checker defined in holehe/modules/shopping/amazon.py, bypassing the full module suite.

Programmatic Usage

Import modules individually and execute them using HoleheRunner:

from holehe.modules.shopping.amazon import Amazon
from holehe.core import HoleheRunner

runner = HoleheRunner(email="email@example.com")
amazon_check = Amazon()
result = runner.run_module(amazon_check)
print(result)   # → {"status": "found", "details": "..."}

Listing Available Modules

Dynamically discover all installed example modules by importing the package's __all__ variable:

from holehe.modules import __all__ as available_modules
print("Available modules:", available_modules)

This list is populated in holehe/modules/__init__.py and reflects all discovered modules in the repository.

Key Files Supporting the Module System

Several core files work together to power the example module architecture:

• holehe/modules/__init__.py: Exposes the complete list of available modules through the __all__ variable.
• holehe/core.py: Contains both the BaseModule class that all modules inherit and the HoleheRunner class that orchestrates execution.
• holehe/instruments.py: Provides HTTP request helpers, HTML parsing utilities, and other instruments used by multiple modules.
• holehe/localuseragent.py: Defines the default user-agent string used by the request layer to avoid detection.

Summary

• All example modules live in holehe/modules/, organized by service category such as transport, shopping, and music.
• Each module inherits from BaseModule in holehe/core.py and implements service-specific email verification logic.
• Execute modules via CLI using the --module flag or programmatically instantiate them with HoleheRunner.
• The holehe/modules/__init__.py file exports all available modules for dynamic discovery through the __all__ variable.

Frequently Asked Questions

Where exactly are example modules stored in the holehe repository?

All example modules are stored in the holehe/modules/ directory of the megadose/holehe repository. They are organized into subdirectories by category, such as shopping/, music/, and transport/, with each service implemented in its own Python file like holehe/modules/shopping/amazon.py.

What base class do holehe modules inherit from?

All modules inherit from BaseModule, which is defined in holehe/core.py. This base class provides the standard interface that HoleheRunner expects, ensuring consistent initialization and execution patterns across different service implementations.

How can I list all available example modules programmatically?

Import the __all__ variable from holehe.modules to retrieve the complete list of registered modules. This variable is populated in holehe/modules/__init__.py and reflects all discovered modules within the package structure.

Can I run a single example module without executing the full suite?

Yes. Use the --module flag followed by the module name when running the holehe CLI command. For example, holehe user@example.com --module amazon runs only the Amazon checker defined in holehe/modules/shopping/amazon.py, ignoring all other services.

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