# Patitas

URL: /patitas/
Description: A Python Markdown parser and CommonMark parser for typed ASTs, directives, frontmatter, and notebook content

---

> For a complete page index, fetch /patitas/llms.txt.

## Python Markdown Parser for Modern Content

**CommonMark. Typed AST. Secure parsing.**

Patitas is a pure-Python Markdown parser for HTML rendering, content pipelines, and
Markdown tooling. It uses a state-machine lexer with O(n) guaranteed parsing, exposes a
typed AST, and supports directives, frontmatter, notebook parsing, and LLM-safe output.

```python
from patitas import Markdown

md = Markdown()
html = md("# Hello **World**")
# Output: <h1>Hello <strong>World</strong></h1>
```

---

## Why Use Patitas

:::{cards}
:columns: 2
:gap: medium

:::{card} State-Machine Lexer
:icon: cpu
No regex catastrophic backtracking. O(n) guaranteed parsing with predictable performance on any input.
:::{/card}

:::{card} Free-Threading Ready
:icon: zap
Built for Python 3.14t (PEP 703). Parse documents concurrently without the GIL.
:::{/card}

:::{card} CommonMark Compliant
:icon: check-circle
Passes all 652 CommonMark 0.31.2 specification tests. Standards-first design.
:::{/card}

:::{card} Zero Dependencies
:icon: package
Pure Python with no runtime dependencies. Optional extras for directives and syntax highlighting.
:::{/card}

:::{/cards}

## Common Use Cases

- Parsing Markdown to HTML in Python applications
- Extracting typed structure from Markdown for analysis or transforms
- Handling YAML frontmatter and notebook content in publishing pipelines
- Replacing regex-heavy Markdown parsers in security-sensitive systems
- Powering docs stacks with directives, syntax highlighting, and incremental parsing

---

## Performance

- **652 CommonMark examples** — low tens of milliseconds in recent Python 3.14 local runs
- **Incremental parsing** — For small edits in large documents, `parse_incremental` can be much faster than full re-parse
- **Parallel scaling** — Free-threaded speedups vary by Python build, hardware, and corpus

Patitas prioritizes **safety over raw speed**: O(n) guaranteed parsing, typed AST, and full thread-safety.

---

## Typed AST

Every node is a frozen dataclass with full type information:

```python
from patitas import parse

doc = parse("# Hello **World**")
heading = doc[0]

# Type-safe access
print(heading.level)      # 1
print(heading.children)   # [Text, Strong]

# IDE autocompletion works
heading.level  # int
heading.children[1].children  # Sequence[Inline]
```

---

## The Bengal Ecosystem

A structured reactive stack — every layer written in pure Python for 3.14t free-threading.

| | | | |
|--:|---|---|---|
| **ᓚᘏᗢ** | [Bengal](https://github.com/lbliii/bengal) | Static site generator | [Docs](https://lbliii.github.io/bengal/) |
| **∿∿** | [Purr](https://github.com/lbliii/purr) | Content runtime | — |
| **⌁⌁** | [Chirp](https://github.com/lbliii/chirp) | Web framework | [Docs](https://lbliii.github.io/chirp/) |
| **=^..^=** | [Pounce](https://github.com/lbliii/pounce) | ASGI server | [Docs](https://lbliii.github.io/pounce/) |
| **)彡** | [Kida](https://github.com/lbliii/kida) | Template engine | [Docs](https://lbliii.github.io/kida/) |
| **ฅᨐฅ** | **Patitas** | Markdown parser ← You are here | [Docs](https://lbliii.github.io/patitas/) |
| **⌾⌾⌾** | [Rosettes](https://github.com/lbliii/rosettes) | Syntax highlighter | [Docs](https://lbliii.github.io/rosettes/) |

Python-native. Free-threading ready. No npm required.