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, returnNone
.
-
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.
-
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
toTrue
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 ofio.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.
-
class
jouvence.html.
HtmlTextRenderer
¶ A text renderer for producing HTML markup.