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.yamlfile.- 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:
objectA 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.pagesis 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
overinheritance.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:andpages: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:andpages:are not panel defaults, unlike every other key besidepanels:, 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.yamlfile. A single-panel document also works and comes back as one entry namedpanel.- 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.yamlfile, 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
*.scriptfile 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
PANELheading, or noPANELheadings at all.