Python library for creating and parsing HSReplay XML files
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Build Status PyPI

A python module for HSReplay support.


The library is available on PyPI. pip install hsreplay will install it.


  • hearthstone
  • hslog
  • lxml (optional) for faster XML parsing and writing. Will use xml.etree if not available.
  • aniso8601 or dateutil for timestamp parsing


The main document class is hsreplay.document.HSReplayDocument. That class contains all the necessary functionality to import and export HSReplay files.

Reading/Writing HSReplay XML files

The classmethod from_xml_file(fp) takes a file-like object and will return a document. If you already have an ElementTree object, you can call the from_xml(xml) classmethod instead.

To export to an HSReplay XML document, the HSReplayDocument.toxml(pretty=False) method can be used to obtain a UTF8-encoded string containing the document.

Reading directly from a log file

The library integrates directly with the python-hearthstone library to produce HSReplayDocument objects directly from a log file or a parser instance.

Use the helper classmethods from_log_file(fp, processor="GameState", date=None, build=None) and from_parser(parser, build=None), respectively.

Exporting back to a PacketTree

It is possible to export HSReplayDocument objects back into a PacketTree with the to_packet_tree() method. This therefore allows lossless conversion from a PacketTree, into HSReplayDocument, then back into a PacketTree.

This is especially interesting because of the native functionality in python-hearthstone which is able to export to a Game tree and allows exploring the game state. By converting HSReplayDocument objects to a PacketTree, it's very easy to follow the replay at a gameplay level, explore the state of the various entities and even hook into the exporter in order to programmatically analyze it.