How hearthsim/python-hearthstone works
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.