Fountain-Py

A Python library for parsing Fountain markup, the screenwriting format. Fountain-Py converts Fountain scripts into structured Python objects and can render them as HTML.

Features

• Full Fountain Support: Parses all Fountain elements including scenes, dialogue, action, transitions, notes, dual dialogue, lyrics, and inline emphasis
• Validation: Reports structural problems (unclosed comments and notes, orphaned character cues) through a validation API
• Multiple Render Modes: HTML fragments for embedding, full pages with CSS, or raw CSS for custom styling
• Round-Trip and Export: Write a parsed script back to clean Fountain, or export it to JSON
• Type-Safe: Built with full type hints and strict mypy compliance
• Zero Dependencies: Pure Python with no runtime dependencies
• Well-Tested: Unit tests and doctests across every module, with high coverage enforced in CI
• Modern Python: Supports Python 3.10 through 3.14

Quick Start

Installation

Fountain-Py is not on PyPI yet (the 0.1.0 release is pending), so install it from source:

pip install git+https://github.com/MasonEgger/fountain-py.git

Once it is published, pip install fountain-py will work.

Basic Usage

from fountain import FountainParser
from fountain.renderer import HTMLRenderer

# Parse a Fountain script
parser = FountainParser()
document = parser.parse("""Title: My Screenplay
Author: Jane Writer

INT. COFFEE SHOP - DAY

SARAH enters, looking tired.

SARAH
One large cappuccino, please!
""")

# Access parsed data
print(document.metadata["title"])       # "My Screenplay"
print(document.get_characters())        # ["SARAH"]
print(len(document.elements))           # 3

# Render as HTML fragment (for embedding in web pages)
renderer = HTMLRenderer()
html_fragment = renderer.render(document)

# Render as standalone HTML file with embedded CSS
html_page = renderer.render_page(document)

# Get raw CSS for external stylesheets
css = renderer.get_css()

Rendering Modes

renderer = HTMLRenderer()

# Fragment — no <style> tags, just the screenplay markup
# Use this for embedding in web pages, docs, or CMS systems
fragment = renderer.render(document)

# Full page — self-contained HTML with embedded CSS
# Use this for saving as .html files or previewing
page = renderer.render_page(document)

# Raw CSS — for custom stylesheet integration
# Use this with mkdocs, static site generators, or your own build pipeline
css = renderer.get_css()

Round-Trip Conversion

from fountain.renderer import FountainRenderer

# Convert back to Fountain markup
fountain_renderer = FountainRenderer()
fountain_text = fountain_renderer.render(document)

The round trip preserves element structure and inline emphasis. Scene headings, action, character cues, parentheticals, dialogue, transitions, dual dialogue, lyrics, sections, synopses, and notes all keep their element types through parse(render(parse(text))), and the blank lines that separate structural blocks survive so blocks are not merged on re-parse.

Inline emphasis is re-emitted too. The parser records the bold (**), italic (*), and underline (_) delimiters as formatting spans, and FountainRenderer restores them, so a **bold** word round-trips as **bold**, including nested emphasis and backslash-escaped literals.

Documentation

Full documentation is available at masonegger.github.io/fountain-py.

• Installation Guide
• Quick Start Tutorial
• API Reference

Development

Setup

git clone https://github.com/MasonEgger/fountain-py.git
cd fountain-py

# Install with development and docs dependencies
just dev && uv sync --group docs

Running Tests

# Run comprehensive quality checks (tests, coverage, doctests, lint, type check)
just test

# Run only unit tests
just unit-test

# Run tests with coverage
just unit-test-cov

# Run specific tests
uv run pytest tests/test_parser.py

Code Quality

just lint         # Lint check (ruff)
just format       # Format code (ruff)
just type-check   # Type checking (mypy strict)

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Fountain Format

Fountain is a simple markup syntax for writing, editing and sharing screenplays in plain text. Learn more at fountain.io.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• The Fountain format creators
• The screenwriting community for feedback and testing