# pcko1/etherscan-python architecture

> Architecture diagram of the GitHub repository pcko1/etherscan-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pcko1/etherscan-python
- Repository: https://github.com/pcko1/etherscan-python

## Overview

##### Project type and purpose
- This is a Python client library (SDK) wrapping the Etherscan.io REST APIs. It exposes all “standard” and “pro” endpoints for Ethereum mainnet and testnets (Kovan, Rinkeby, Ropsten). It has no UI; it’s intended for other Python code to import and call.

##### File structure
- Top-level:
- setup.py, MANIFEST.in — packaging
- run_tests.sh — regenerates JSON logs via live API calls
- .github/workflows — CI: build, greetings, publish
- Source package (etherscan/):
- configs/ — per-network JSON files (MAIN, RINKEBY, etc.) hold base URLs & defaults
- enums/ — constants for modules, actions, tags, fields to ensure valid parameters
- modules/ — one Python file per API module (accounts.py, blocks.py, transactions.py, tokens.py, etc.); each defines thin wrappers around endpoints
- etherscan.py — central Etherscan class that
– loads config (network, API key)
– imports enums
– exposes public methods by delegating to module functions
– handles HTTP requests/responses
- utils/ — conversion/parsing helpers for JSON, units, hex
- logs/ — sample JSON responses per method (split in standard/ and pro/), used by tests
- test/ — pytest module(s) that invoke each endpoint and compare against logs

##### README for additional insights
- Confirms structure: you instantiate Etherscan(YOUR_API_KEY, net="ropsten")
- Enumerates every endpoint by category
- Describes usage of run_tests.sh to refresh logs

##### Capturing essential details
- Network configs as a distinct block, since the client picks the correct base URL
- Enums as a validation/filtering layer around parameters
- Don’t omit the logs/ → test/ feedback loop; it’s key to quality

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Library
    User["User Code"]:::external
    Client["Etherscan Client"]:::core
    subgraph "Module Layer"
        A["Accounts Module"]:::core
        B["Blocks Module"]:::core
        C["Contracts Module"]:::core
        D["Transactions Module"]:::core
        E["Tokens Module"]:::core
        F["Proxy Module"]:::core
        G["GasTracker Module"]:::core
        H["Stats Module"]:::core
        I["Pro Module"]:::core
    end
    Utils["Utils (Conversions & Parsing)"]:::core

    %% Configuration Layer
    subgraph "Configuration Layer"
        MAIN["MAIN-stable.json"]:::config
        KOVAN["KOVAN-stable.json"]:::config
        RINKEBY["RINKEBY-stable.json"]:::config
        ROPSTEN["ROPSTEN-stable.json"]:::config
        GOERLI["GOERLI-stable.json"]:::config
    end

    %% Enums Layer
    subgraph "Enums Layer"
        ME["modules_enum.py"]:::config
        AE["actions_enum.py"]:::config
        FE["fields_enum.py"]:::config
        TE["tags_enum.py"]:::config
    end

    %% HTTP & External
    HTTP["HTTP Transport"]:::external
    ExternalAPI["Etherscan.io API"]:::external

    %% Testing & Logging
    subgraph "Testing & Logging"
        RunTests["run_tests.sh"]:::support
        Logs["Logs (standard/pro)"]:::support
        Tests["pytest Harness"]:::support
    end

    %% CI/CD & Packaging
    subgraph "CI/CD & Packaging"
        CI["GitHub Actions"]:::support
        Packaging["setup.py & MANIFEST.in"]:::support
    end

    %% Data Flow
    User -->|calls| Client
    Client -->|loads| MAIN
    Client -->|loads| KOVAN
    Client -->|loads| RINKEBY
    Client -->|loads| ROPSTEN
    Client -->|loads| GOERLI
    Client -->|loads| ME
    Client -->|loads| AE
    Client -->|loads| FE
    Client -->|loads| TE
    Client -->|delegates| A
    Client -->|delegates| B
    Client -->|delegates| C
    Client -->|delegates| D
    Client -->|delegates| E
    Client -->|delegates| F
    Client -->|delegates| G
    Client -->|delegates| H
    Client -->|delegates| I

    A -->|calls HTTP| HTTP
    B -->|calls HTTP| HTTP
    C -->|calls HTTP| HTTP
    D -->|calls HTTP| HTTP
    E -->|calls HTTP| HTTP
    F -->|calls HTTP| HTTP
    G -->|calls HTTP| HTTP
    H -->|calls HTTP| HTTP
    I -->|calls HTTP| HTTP

    HTTP -->|sends request| ExternalAPI
    ExternalAPI -->|returns response| HTTP
    HTTP -->|parsed by| Utils
    Utils -->|returns data| Client
    Client -->|returns result| User

    RunTests -->|invokes| Client
    RunTests -->|writes| Logs
    Tests -->|reads| Logs
    Tests -->|validates| Client

    CI -->|runs| RunTests
    CI -->|runs| Tests
    CI -->|publishes| Packaging

    %% Click Events
    click Client "https://github.com/pcko1/etherscan-python/blob/master/etherscan/etherscan.py"
    click A "https://github.com/pcko1/etherscan-python/blob/master/etherscan/modules/accounts.py"
    click B "https://github.com/pcko1/etherscan-python/blob/master/etherscan/modules/blocks.py"
    click C "https://github.com/pcko1/etherscan-python/blob/master/etherscan/modules/contracts.py"
    click D "https://github.com/pcko1/etherscan-python/blob/master/etherscan/modules/transactions.py"
    click E "https://github.com/pcko1/etherscan-python/blob/master/etherscan/modules/tokens.py"
    click F "https://github.com/pcko1/etherscan-python/blob/master/etherscan/modules/proxy.py"
    click G "https://github.com/pcko1/etherscan-python/blob/master/etherscan/modules/gastracker.py"
    click H "https://github.com/pcko1/etherscan-python/blob/master/etherscan/modules/stats.py"
    click I "https://github.com/pcko1/etherscan-python/blob/master/etherscan/modules/pro.py"
    click MAIN "https://github.com/pcko1/etherscan-python/blob/master/etherscan/configs/MAIN-stable.json"
    click KOVAN "https://github.com/pcko1/etherscan-python/blob/master/etherscan/configs/KOVAN-stable.json"
    click RINKEBY "https://github.com/pcko1/etherscan-python/blob/master/etherscan/configs/RINKEBY-stable.json"
    click ROPSTEN "https://github.com/pcko1/etherscan-python/blob/master/etherscan/configs/ROPSTEN-stable.json"
    click GOERLI "https://github.com/pcko1/etherscan-python/blob/master/etherscan/configs/GOERLI-stable.json"
    click ME "https://github.com/pcko1/etherscan-python/blob/master/etherscan/enums/modules_enum.py"
    click AE "https://github.com/pcko1/etherscan-python/blob/master/etherscan/enums/actions_enum.py"
    click FE "https://github.com/pcko1/etherscan-python/blob/master/etherscan/enums/fields_enum.py"
    click TE "https://github.com/pcko1/etherscan-python/blob/master/etherscan/enums/tags_enum.py"
    click Utils "https://github.com/pcko1/etherscan-python/blob/master/etherscan/utils/conversions.py"
    click RunTests "https://github.com/pcko1/etherscan-python/blob/master/run_tests.sh"
    click Tests "https://github.com/pcko1/etherscan-python/blob/master/test/test_modules.py"
    click CI "https://github.com/pcko1/etherscan-python/blob/master/.github/workflows/build.yml"
    click CI "https://github.com/pcko1/etherscan-python/blob/master/.github/workflows/greetings.yml"
    click CI "https://github.com/pcko1/etherscan-python/blob/master/.github/workflows/python-publish.yml"

    %% Styles
    classDef core fill:#D0E6FF,stroke:#0366d6,color:#0366d6,stroke-width:1px;
    classDef config fill:#E6FFEB,stroke:#28a745,color:#28a745,stroke-width:1px;
    classDef external fill:#FFF4E5,stroke:#d26a00,color:#d26a00,stroke-width:1px;
    classDef support fill:#F0F0F0,stroke:#6a737d,color:#6a737d,stroke-width:1px;
```
