# hearthsim/python-hearthstone architecture

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

- Interactive diagram: https://gitdiagram.com/hearthsim/python-hearthstone
- Repository: https://github.com/hearthsim/python-hearthstone

## Overview

##### Project type and purpose
- This is a Python library (open-source tool) named “python-hearthstone” that provides:
- XML parsers for various Hearthstone data files (CardDefs.xml, DbfXml, MercenaryXml, BountyXml, StringsFile)
- A deck code encoder/decoder (deckstrings)
- Enum definitions for Hearthstone elements
- Utility routines for XML and data processing
- It ships on PyPI, has a CLI script for “dump_reprints,” and can optionally pull runtime data from the separate `hearthstone_data` package.

##### File structure
- Top-level: packaging/config files (`setup.py`, `setup.cfg`, `tox.ini`, CI pipeline `.github/workflows/ci.yml`), the `hearthstone/` source package, `scripts/`, and `tests/`.
- `hearthstone/` modules break down by domain:
- `cardxml.py`, `dbf.py`, `mercenaryxml.py`, `bountyxml.py`, `stringsfile.py` – each handles a specific XML format
- `deckstrings.py` – deck code encoding/decoding
- `enums.py` – IntEnum definitions
- `entities.py`, `types.py` – core data models
- `xmlutils.py`, `utils/` – shared parsing helpers
- `scripts/dump_reprints.py` – standalone script
- `tests/` verifies each module in isolation and end-to-end.

##### Key insights from the README
- Core dependencies: Python ≥3.6, `lxml` for XML processing
- Optional external data source: `hearthstone_data` package or runtime download
- No backend service or database – purely a client-side library.

##### Main components
a. Library modules:
- XML Parsers (CardXML, DbfXml, MercenaryXML, BountyXML, StringsFile)
- DeckStrings encoder/decoder
- Enums & Entities (data models)
- Utils & XMLUtils (shared helpers)
b. External dependencies:
- lxml (XML parsing)
- Optional `hearthstone_data` package or HTTP endpoint for raw XML
- Python runtime
c. Scripts & tests:
- `scripts/dump_reprints.py`
- `tests/` harness (unit tests)
d. Packaging/CI:
- setup.py / setup.cfg
- GitHub Actions CI

##### Relationships and interactions
- User code or CLI script → imports deckstrings, parsers, enums
- Parsers read raw XML (from local files or downloaded via `hearthstone_data`) → use xmlutils + lxml → produce Python objects (entities, types)
- Deckstrings module uses enums and entities to encode/decode deck codes
- Utils provide auxiliary functions (caching, file I/O)
- Tests invoke each module directly, mocking XML inputs from `tests/res`.

##### Architectural patterns and design principles
- Modular design: one parser per XML domain
- Clear separation: core logic (models, enums) vs. I/O (xmlutils, utils)
- Dependency injection for data source (local vs. external)
- Single responsibility: deck code logic isolated from parsing logic

- Core modules (blue)
- External dependencies (green)
- Scripts/tests (orange)
- Packaging/CI (gray)

##### Final reminder
- Be as detailed as possible: capture each parser, the shared utilities, data flow from raw XML to Python objects, and the deck code transformations.
- Avoid over-complicating: focus on clear separation of concerns and module interactions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        LXML["lxml"]:::external
        HS_DATA["hearthstone_data package"]:::external
        HTTP["HTTP XML Endpoint"]:::external
        PYTHON["Python Runtime ≥3.6"]:::external
    end

    %% Shared Utilities
    subgraph "Utilities" 
        direction TB
        XMLUTIL["XML Utilities"]:::core
        SHAREDUTIL["Shared Utils"]:::core
    end

    %% Parsers
    subgraph "XML Parsers" 
        direction TB
        CARDXML["CardXML Parser"]:::core
        DBFXML["DbfXml Parser"]:::core
        MERCXML["MercenaryXML Parser"]:::core
        BOUNTYXML["BountyXML Parser"]:::core
        STRINGS["StringsFile Parser"]:::core
    end

    %% Models
    subgraph "Data Models"
        direction TB
        ENUMS["Enum Definitions"]:::core
        ENTITIES["Entities"]:::core
        TYPES["Types"]:::core
    end

    %% Deck code logic
    DECK["DeckStrings Encoder/Decoder"]:::core

    %% Scripts & Tests
    subgraph "Scripts & Tests"
        direction TB
        CLI["dump_reprints CLI"]:::script
        TESTS["Test Suite"]:::script
    end

    %% Packaging & CI
    subgraph "Packaging & CI"
        direction TB
        SETUPPY["setup.py"]:::meta
        SETUPCFG["setup.cfg"]:::meta
        TOX["tox.ini"]:::meta
        CI["GitHub Actions CI"]:::meta
    end

    %% Data flow
    HS_DATA -->|optional| XMLUTIL
    HTTP -->|optional| XMLUTIL
    LXML --> XMLUTIL
    PYTHON --> DECK
    PYTHON --> ENUMS
    XMLUTIL --> CARDXML
    XMLUTIL --> DBFXML
    XMLUTIL --> MERCXML
    XMLUTIL --> BOUNTYXML
    XMLUTIL --> STRINGS
    SHAREDUTIL --> CARDXML
    SHAREDUTIL --> DBFXML
    SHAREDUTIL --> MERCXML
    SHAREDUTIL --> BOUNTYXML
    SHAREDUTIL --> STRINGS
    CARDXML --> ENTITIES
    DBFXML --> ENTITIES
    MERCXML --> ENTITIES
    BOUNTYXML --> ENTITIES
    STRINGS --> ENTITIES
    ENTITIES --> DECK
    TYPES --> DECK
    ENUMS --> DECK
    CLI --> CARDXML
    CLI --> DECK
    TESTS -.-> CARDXML
    TESTS -.-> DBFXML
    TESTS -.-> MERCXML
    TESTS -.-> BOUNTYXML
    TESTS -.-> STRINGS
    TESTS -.-> DECK
    TESTS -.-> ENUMS
    TESTS -.-> ENTITIES
    TESTS -.-> TYPES
    SETUPPY -->|publishes| PYPI["PyPI"]:::external
    SETUPCFG -->|configures| SETUPPY
    TOX -->|tests via| TESTS
    CI --> SETUPPY
    CI --> TESTS

    %% Click events
    click CARDXML "https://github.com/hearthsim/python-hearthstone/blob/master/hearthstone/cardxml.py"
    click DBFXML "https://github.com/hearthsim/python-hearthstone/blob/master/hearthstone/dbf.py"
    click MERCXML "https://github.com/hearthsim/python-hearthstone/blob/master/hearthstone/mercenaryxml.py"
    click BOUNTYXML "https://github.com/hearthsim/python-hearthstone/blob/master/hearthstone/bountyxml.py"
    click STRINGS "https://github.com/hearthsim/python-hearthstone/blob/master/hearthstone/stringsfile.py"
    click DECK "https://github.com/hearthsim/python-hearthstone/blob/master/hearthstone/deckstrings.py"
    click ENUMS "https://github.com/hearthsim/python-hearthstone/blob/master/hearthstone/enums.py"
    click ENTITIES "https://github.com/hearthsim/python-hearthstone/blob/master/hearthstone/entities.py"
    click TYPES "https://github.com/hearthsim/python-hearthstone/blob/master/hearthstone/types.py"
    click XMLUTIL "https://github.com/hearthsim/python-hearthstone/blob/master/hearthstone/xmlutils.py"
    click SHAREDUTIL "https://github.com/hearthsim/python-hearthstone/tree/master/hearthstone/utils/"
    click CLI "https://github.com/hearthsim/python-hearthstone/blob/master/scripts/dump_reprints.py"
    click TESTS "https://github.com/hearthsim/python-hearthstone/tree/master/tests/"
    click SETUPPY "https://github.com/hearthsim/python-hearthstone/blob/master/setup.py"
    click SETUPCFG "https://github.com/hearthsim/python-hearthstone/blob/master/setup.cfg"
    click TOX "https://github.com/hearthsim/python-hearthstone/blob/master/tox.ini"
    click CI "https://github.com/hearthsim/python-hearthstone/blob/master/.github/workflows/ci.yml"

    %% Styles
    classDef core fill:#D0E1FF,stroke:#0366d6,color:#0366d6
    classDef external fill:#DFFFE0,stroke:#28A745,color:#28A745
    classDef script fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00
    classDef meta fill:#E0E0E0,stroke:#6A737D,color:#6A737D
```
