Metadata-Version: 2.5
Name: fountain-py
Version: 0.2.0
Summary: A Python library for parsing Fountain markup, the screenwriting format
Project-URL: Homepage, https://github.com/MasonEgger/fountain-py
Project-URL: Repository, https://github.com/MasonEgger/fountain-py
Project-URL: Documentation, https://masonegger.github.io/fountain-py/
Project-URL: Issues, https://github.com/MasonEgger/fountain-py/issues
Author-email: Mason Egger <mason@masonegger.com>
License-File: LICENSE
Keywords: fountain,parser,screenplay,screenwriting,script,theater
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.10
Provides-Extra: pdf
Requires-Dist: fpdf2>=2.7; extra == 'pdf'
Description-Content-Type: text/markdown

# Fountain-Py

[![CI](https://github.com/MasonEgger/fountain-py/workflows/CI/badge.svg)](https://github.com/MasonEgger/fountain-py/actions?query=workflow%3ACI)
[![PyPI version](https://img.shields.io/pypi/v/fountain-py.svg)](https://pypi.org/project/fountain-py/)
[![Python versions](https://img.shields.io/pypi/pyversions/fountain-py.svg)](https://pypi.org/project/fountain-py/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

A Python library for parsing [Fountain markup](https://fountain.io/), 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.10 through 3.14

## Quick Start

### Installation

```bash
pip install fountain-py
```

### Basic Usage

```python
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

```python
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

```python
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](https://masonegger.github.io/fountain-py/).

- [Installation Guide](https://masonegger.github.io/fountain-py/installation.html)
- [Quick Start Tutorial](https://masonegger.github.io/fountain-py/quickstart.html)
- [API Reference](https://masonegger.github.io/fountain-py/api/index.html)

## Development

### Setup

```bash
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

```bash
# 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

```bash
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](CONTRIBUTING.md) for details.

## Fountain Format

Fountain is a simple markup syntax for writing, editing and sharing screenplays in plain text. Learn more at [fountain.io](https://fountain.io/).

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- The [Fountain](https://fountain.io/) format creators
- The screenwriting community for feedback and testing
