teehistorian-py 2025.2.2

Python bindings for teehistorian with event processing

teehistorian-py

High-performance Python bindings for parsing Teeworlds/DDNet teehistorian files. Built with Rust for speed and memory safety.

📚 Documentation | 🐛 Issue Tracker | 📦 PyPI

Features

• 🚀 Fast: Rust-powered parsing with minimal Python overhead
• 🔒 Memory Safe: No buffer overflows or memory leaks
• 📦 Simple API: Clean Python interface for easy integration
• 🧩 Extensible: Support for custom UUID handlers for mods
• 🎯 Complete: Covers all standard teehistorian chunk types

Installation

pip install teehistorian-py

Quick Start

import teehistorian_py as th

# Parse a teehistorian file (modern Pythonic way)
with th.open("server.teehistorian") as parser:
    for chunk in parser:
        if isinstance(chunk, th.Join):
            print(f"Player {chunk.client_id} joined")
        elif isinstance(chunk, th.Drop):
            print(f"Player {chunk.client_id} left: {chunk.reason}")
        elif isinstance(chunk, th.PlayerName):
            print(f"Player {chunk.client_id} is now called '{chunk.name}'")

Or with Python 3.10+ match statement:

import teehistorian_py as th

with th.open("server.teehistorian") as parser:
    for chunk in parser:
        match chunk:
            case th.Join(client_id=cid):
                print(f"Player {cid} joined")
            case th.Drop(client_id=cid, reason=reason):
                print(f"Player {cid} left: {reason}")
            case th.PlayerName(client_id=cid, name=name):
                print(f"Player {cid} is now called '{name}'")

See the full documentation for more examples and advanced usage.

Development

Building from Source

# Clone the repository
git clone https://github.com/KoG-teeworlds/teehistorian-py.git
cd teehistorian-py

# Install development dependencies
pip install -e ".[dev]"

# Build extension module
maturin develop --release

# Run tests with coverage
pytest tests/ --cov=src/python/teehistorian_py --cov-report=html --cov-report=term-missing

# View coverage report
open htmlcov/index.html  # On macOS
# or visit htmlcov/index.html in your browser

Code Coverage & Security

We maintain 80%+ code coverage with branch coverage enabled and modern security practices:

• Coverage: Branch coverage enabled with automatic PR reports via Codecov
• Security: OIDC trusted publishing (no API keys required)
• Modern CI/CD: GitHub Actions with hardened runners and security scanning
• Automated: Rust security audits, Python vulnerability scans, and dependency checks

Requirements

• Python 3.8+
• Rust 1.70+ (for building from source)

License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.

Credits

• Built on top of the excellent teehistorian Rust crate
• Part of the KoG-teeworlds ecosystem

Related Projects

• teehistorian - Original Rust implementation
• Teeworlds - The game that generates these files
• DDNet - Popular Teeworlds modification

---

Need help? Open an issue or check our documentation.