compile_scene#

Import

from scenet import compile_scene

Defined in

scenet.pipeline (source)

Install

pip install scenet

Since

0.1

Stability

Public: follows semantic versioning. Below 1.0, a minor release may change it, and the CHANGELOG says how.

scenet.pipeline.compile_scene(text, *, source=None, base=None, library=None, metrics=None)[source]#

Compile every panel in a multi-panel document.

Each panel is compiled independently. A panel’s composition must not depend on what sits beside it, or the same source would compile differently in isolation – which would make panels non-reusable and golden tests meaningless. A panel that a page lays out is compiled at its frame’s size; see compile_book, which also returns the pages.

Parameters:
  • text (str) – A panels: document, each panel optionally inheriting another with over:.

  • source (Path | None) – Path the text came from, prefixed to error messages and used to find the files it names beside it.

  • base (Path | Mapping[str, bytes] | None) – The folder files the document names are read from, when it is not the one source is in – or when there is no source at all.

  • library (PuppetLibrary | None) – Characters to draw from. Defaults to the two shipped puppets.

  • metrics (FontMetrics | None) – Font to measure lettering against. Defaults to the shipped one.

Return type:

dict[str, CompileResult]

Returns:

Panel name to its compiled result, in the order the document wrote them.

Raises:
  • PanelSyntaxError – The document is malformed or invalid, or a file it names cannot be read or is not what it says.

  • CompositionError – An over: names a panel that does not exist, or the chain is a cycle.

  • UnknownPuppetError – A cast member references a puppet the library lacks.

  • UnknownPoseError – A cast member’s pose is one its puppet does not declare.

  • UnknownExpressionError – A cast member’s expression is one its puppet does not declare.

  • LayoutError – The staging cannot be satisfied: a depth order that is a cycle, or a panel with no cast to place.

  • BalloonPlacementError – A balloon or a caption has no legal position.

  • SfxPlacementError – A sound effect has no legal position.

Note

A scene’s pages: are not laid out here: compile_book does that, and returns these panels too.

Deterministic: the same text, puppets and fonts give the same Core, byte for byte. A compile reads no file but those the document names, and those only from base or the folder of source; text with neither can name none. It is safe to call from several threads; see the Guarantees page for the caches they share.

Example

>>> from scenet import compile_scene
>>> panels = compile_scene(
...     "panels:\n"
...     "  wide: {cast: {a: {reference: alice}}, camera: {shot: full_shot}}\n"
...     "  close: {over: wide, camera: {shot: close_up}}"
... )
>>> list(panels)
['wide', 'close']
>>> panels["close"].core.camera.shot
<ShotType.CLOSE_UP: 'close_up'>

See also

compile_book, for the panels and their pages. parse_scene, to stop at the IR.

Added in version 0.11: The base parameter.