Fountain-Py

A Python library for parsing Fountain markup, the screenwriting format. Fountain-Py converts Fountain scripts into structured Python objects and renders them as HTML, plain text, Fountain, Final Draft (FDX), PDF, or JSON, from Python or the fountain command line.

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 Output Formats: Renders to HTML (fragment, full page, or raw CSS), plain text, Fountain, Final Draft (FDX), or PDF
• JSON Interchange: Serializes a parsed script with to_json() and rebuilds it with from_json(), backed by a versioned schema
• Command-Line Interface: The fountain CLI validates and renders scripts without writing any Python
• Round-Trip: Writes a parsed script back to clean Fountain, preserving element structure and inline emphasis
• Type-Safe: Built with full type hints and strict mypy compliance
• Minimal Dependencies: Pure Python core with no runtime dependencies; PDF export is an optional pdf extra
• Well-Tested: Unit tests and doctests across every module, with high coverage enforced in CI
• Modern Python: Supports Python 3.11 through 3.15

Quick Start

Installation

pip install fountain-py

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

Running Tests

# The gate: lint, format check, mypy strict, and tests (module doctests included)
just check

# Run only the tests
just test

# Run tests with a coverage report
just test-cov

# Run the tests on every supported Python version
just test-all

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

Code Quality

just fmt          # Format code and auto-fix lint issues (ruff)

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