turndown-py

A Python port of Turndown (v7.2.4), an HTML to Markdown converter originally written in JavaScript by Dom Christie.

Project Status

Conversion fidelity: 203 tests passing — 147 golden test cases ported from upstream (all match JS output), 39 internal/unit tests, 14 API tests.

• ✅ ruff check — clean
• ✅ ruff format — clean
• ✅ pytest tests/ — 203/203 passed

🎉 Additional tests in tests/test_internals.py:

• Pickle serialization — TurndownService round-trips through pickle.dumps/loads (required for Spark UDFs)
• Thread safety — 8 concurrent threads converting different HTML inputs produce correct, isolated results
• Statelessness — repeated calls with same input yield identical output
• Reference link isolation — per-call references state prevents cross-call contamination

Installation

pip install turndown-py

Requires Python 3.7+.

Development

# Clone and enter the repo
git clone https://github.com/M-Intelligence/turndown-py
cd turndown-py

# Create virtualenv and install dev dependencies
uv sync

# Run tests
uv run pytest

# Lint and format
uv run ruff check .
uv run ruff format .

Package Structure

Usage

from turndown import TurndownService

ts = TurndownService()
markdown = ts.turndown('<h1>Hello <em>world</em></h1>')
# => 'Hello _world_\n============='

License

GPL-3.0-or-later. The original turndown.js MIT license is retained in LICENSE_MIT. Attribution in CREDITS.