API

The Jouvence API is fairly simple, and includes:

  • A Fountain parser that returns a screenplay object.
  • Several renderers, for formatting a screenplay object into something you can display on screen or elsewhere.
  • A screenplay object that you can manipulate for custom rendering, analysis, and more.

Parser

class jouvence.parser.JouvenceParser

Parses a Fountain document and returns a JouvenceDocument instance.

parse(filein)

Parses a file or stream. This must either be a Python file object, or the path to file on disk. Returns a JouvenceDocument instance.

parseString(text)

Parses a string. Returns a JouvenceDocument instance.

exception jouvence.parser.JouvenceParserError(line_no, message)

Document

class jouvence.document.JouvenceDocument

Represents a Fountain screenplay in a structured way.

A screenplay contains:

  • A title page (optional) with a key/value dictionary of settings.
  • A list of scenes.
  • Each scene contains a list of paragraphs of various types.
title_values

The title page key/values dictionary.

scenes

The list of scenes in the screenplay.

Most screenplays start with some “free text” before the first scene. In this case, the first scene would have no header, and would contain this text.

addScene(header=None)

Adds a scene with the specified header.

lastParagraph()

Gets the last paragraph of the last scene in the screenplay.

If there’s no scene in the screenplay, return None.

lastScene(auto_create=True)

Gets the last scene in the screenplay.

auto_create
If True, and the screenplay has no scenes, create a scene with an empty header text. Otherwise, return None.
class jouvence.document.JouvenceScene

A scene in a screenplay.

header

The header text of the scene, _e.g._ “EXT. JAMES’ HOUSE - DAY”.

paragraphs

The list of paragraphs in the scene. Each paragraph is an instance of JouvenceSceneElement.

addAction(text)

Adds an action (paragraph with TYPE_ACTION type).

addCenteredAction(text)

Adds a centered action (paragraph with TYPE_CENTEREDACTION type).

addCharacter(text)

Adds a character line (paragraph with TYPE_CHARACTER type).

addDialog(text)

Adds a dialog line (paragraph with TYPE_DIALOG type).

addParenthetical(text)

Adds a parenthetical (paragraph with TYPE_PARENTHETICAL type).

addTransition(text)

Adds a transition (paragraph with TYPE_TRANSITION type).

addLyrics(text)

Adds some lyrics (paragraph with TYPE_LYRICS type).

addSynopsis(text)

Adds a synopsis (paragraph with TYPE_SYNOPSIS type).

addPageBreak()

Adds a page break (paragraph with TYPE_PAGEBREAK type).

addSection(depth, text)

Adds a section (a JouvenceSceneSection instance).

class jouvence.document.JouvenceSceneElement(el_type, text)

An element of a screenplay scene, _e.g._ an action, a dialogue line, a parenthetical, etc.

type

The type of this element. Could be any of:

  • TYPE_ACTION
  • TYPE_CENTEREDACTION
  • TYPE_CHARACTER
  • TYPE_DIALOG
  • TYPE_PARENTHETICAL
  • TYPE_TRANSITION
  • TYPE_LYRICS
  • TYPE_PAGEBREAK
  • TYPE_SECTION
  • TYPE_SYNOPSIS
text

The text for this paragraph.

class jouvence.document.JouvenceSceneSection(depth, text)

Screenplay sections have their own class because they have a depth attribute in addition to a type and text.

depth

The depth, or level, of the section.

Renderers

class jouvence.renderer.BaseDocumentRenderer(text_renderer=None)

The base class for document renderers.

Document renderers are given a document to transform into whatever format they’re responsible for.

force_title_page

By default, if there are no title page values in a screenplay, no title page will be produced. Set force_title_page to True to force rendering a title page with default/placeholder values.

text_renderer

The BaseTextRenderer instance that this document renderer is using to handle text.

render_doc(doc, out)

Renders the given document (doc) into the given buffer (out).

The output buffer must be a file-like object, like the return value of the open() built-in function, or an instance of io.StringIO, among others.

class jouvence.renderer.BaseTextRenderer

A class responsible for rendering text, including such things as italics, bold, or underline.

render_text(text)

Processes the given text, and returns the formatted data.

The jouvence.html module contains utilities for turning a Fountain screenplay into a web page, along with other web-related features.

jouvence.html.get_css()

Gets the default CSS screenplay theme that Jouvence uses.

class jouvence.html.HtmlDocumentRenderer(standalone=True)

A document renderer that formats a screenplay into a web page.

get_css()

Gets the default CSS screenplay theme that Jouvence uses.

This is the same as get_css().

class jouvence.html.HtmlTextRenderer

A text renderer for producing HTML markup.