Frontends#

Text in, validated IR out. Two syntaxes, one IR – which is what lets a comic script and a YAML document compile identically without anything downstream knowing there is more than one.

scenet.frontends.yaml_front#

.. py:module:: scenet.frontends.yaml_front

The YAML surface syntax: text in, validated IR out.

This is one frontend among several planned – a comic-script frontend will target the same IR. Keeping parsing separate from the IR is what makes that possible without touching anything downstream.

.. py:function:: parse_panel(text, *, source=None)

module:

scenet.frontends.yaml_front

Parse panel source into validated IR.

rtype:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.PanelIR``

.. py:function:: load_panel(path)

module:

scenet.frontends.yaml_front

Read and validate a single-panel document from disk.

type path:
sphinx_autodoc_typehints_type:

\:py\:class\:\~pathlib.Path``

param path:

A *.panel.yaml file.

rtype:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.ir.PanelIR``

returns:

The validated scene graph. No coordinates yet – that is the solver’s job.

raises OSError:

The file cannot be read.

raises PanelSyntaxError:

The document is malformed or invalid. The path is included in the message.

.. py:class:: SceneDocument

module:

scenet.frontends.yaml_front

Bases: :py:class:object

A scene, read: its panels, and the pages they are laid out on.

.. attribute:: panels

Panel name to validated IR, in declaration order – which is reading order. A single-panel document has one, named panel.

.. attribute:: layout

The page format and the pages. layout.pages is empty for a document that lays nothing out, which is every document written before pages existed.

.. py:attribute:: SceneDocument.panels

module:

scenet.frontends.yaml_front

type:

dict[str, ~scenet.ir.PanelIR]

.. py:attribute:: SceneDocument.layout

module:

scenet.frontends.yaml_front

type:

~scenet.ir.PageLayout

.. py:method:: SceneDocument.init(panels, layout)

module:

scenet.frontends.yaml_front

.. py:function:: parse_scene(text, *, source=None)

module:

scenet.frontends.yaml_front

Parse a multi-panel document, resolving over inheritance.

A document with a top-level panels: mapping holds a sequence; anything else is treated as a single panel named “panel”, so the two forms share one entry point and a single-panel file needs no ceremony.

Panel order follows declaration order, which is reading order. page: and pages: are read and checked, but only the panels come back: see

func:

parse_scene_document <scenet.frontends.yaml_front.parse_scene_document>.

rtype:
sphinx_autodoc_typehints_type:

\:py\:class\:\dict`\ \[:py:class:`str`, :py:class:`~scenet.ir.PanelIR`]`

.. py:function:: parse_scene_document(text, *, source=None)

module:

scenet.frontends.yaml_front

Parse a scene and the pages it is laid out on.

page: and pages: are not panel defaults, unlike every other key beside panels:, so they are taken out before the defaults are applied.

type text:
sphinx_autodoc_typehints_type:

\:py\:class\:\str``

param text:

The document source.

type source:
sphinx_autodoc_typehints_type:

\:py\:class\:\~pathlib.Path` | :py:obj:`None``

param source:

Path it came from, used only to prefix error messages.

rtype:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.frontends.yaml_front.SceneDocument``

returns:

The panels and the layout.

raises PanelSyntaxError:

A panel or the layout is malformed. A placement naming a panel that does not exist, or one placed twice, is rule page-layout.

raises CompositionError:

An over: chain is unresolvable or cyclic.

.. py:function:: load_scene(path)

module:

scenet.frontends.yaml_front

Read and validate a multi-panel document from disk.

type path:
sphinx_autodoc_typehints_type:

\:py\:class\:\~pathlib.Path``

param path:

A *.scene.yaml file. A single-panel document also works and comes back as one entry named panel.

rtype:
sphinx_autodoc_typehints_type:

\:py\:class\:\dict`\ \[:py:class:`str`, :py:class:`~scenet.ir.PanelIR`]`

returns:

Panel name to scene graph, in declaration order – which is reading order.

raises OSError:

The file cannot be read.

raises PanelSyntaxError:

A panel is malformed or invalid.

raises CompositionError:

An over: chain is unresolvable or cyclic.

.. py:function:: load_scene_document(path)

module:

scenet.frontends.yaml_front

Read a scene and the pages it is laid out on, from disk.

type path:
sphinx_autodoc_typehints_type:

\:py\:class\:\~pathlib.Path``

param path:

A *.scene.yaml file, or any YAML document the frontend reads.

rtype:
sphinx_autodoc_typehints_type:

\:py\:class\:\~scenet.frontends.yaml_front.SceneDocument``

returns:

The panels and the layout.

raises OSError:

The file cannot be read.

raises PanelSyntaxError:

A panel or the layout is malformed.

raises CompositionError:

An over: chain is unresolvable or cyclic.

scenet.frontends.script_front#

.. py:module:: scenet.frontends.script_front

A frontend for comic script, the format writers already use.

Checked before building this: Fountain has no native panel, caption or SFX support, and there is no standardised comic script format at all. But the informal industry convention is stable across publishers – PANEL 1, a prose description, a character cue in capitals, the dialogue beneath it – so that is what this parses.

The honest limitation. A prose description like “Alice and Bob face each other on a rainy street corner” cannot be compiled. Turning that into staging needs natural language understanding, and guessing would produce panels that are confidently wrong – far worse than refusing. So descriptions are preserved but not interpreted, and anything the compiler must know is declared explicitly: cast and staging in a front-matter block, per-panel settings as @ directives.

   ---
   cast:
     ALICE: {reference: alice, at: left_third}
     BOB:   {reference: bob,   at: right_third}
   staging:
     - ALICE left_of BOB
   ---

   PANEL 1
   @shot: full_shot
   CAPTION: Midnight. The docks.
   Alice and Bob face each other on a rainy street corner.

   ALICE
   You forgot your umbrella!

   BOB (whisper)
   I know.

.. py:function:: parse_script(text, *, source=None)

module:

scenet.frontends.script_front

Parse comic script into one validated panel per PANEL heading.

rtype:
sphinx_autodoc_typehints_type:

\:py\:class\:\dict`\ \[:py:class:`str`, :py:class:`~scenet.ir.PanelIR`]`

.. py:function:: load_script(path)

module:

scenet.frontends.script_front

Read and validate a comic script from disk.

type path:
sphinx_autodoc_typehints_type:

\:py\:class\:\~pathlib.Path``

param path:

A *.script file in the comic-script format writers already use.

rtype:
sphinx_autodoc_typehints_type:

\:py\:class\:\dict`\ \[:py:class:`str`, :py:class:`~scenet.ir.PanelIR`]`

returns:

Panel name to scene graph, in the order the panels appear.

raises OSError:

The file cannot be read.

raises ScriptSyntaxError:

The script cannot be parsed – dialogue before the first PANEL heading, or no PANEL headings at all.