compile_script#

Import

from scenet import compile_script

Defined in

scenet.pipeline (source)

Install

pip install scenet

Since

0.11

Stability

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

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

Compile a comic script, every panel and page of it.

The one way a script is compiled, whoever asks: scenet build, scenet check --deep, the MCP server and the playground used to each assemble one by hand, and would have drifted apart the day a script laid out pages.

Parameters:
  • text (str) – The script.

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

  • base (Path | Mapping[str, bytes] | None) – The folder files the script names are read from, in place of the one source is in.

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

  • metrics (FontMetrics | None) – Font to measure lettering against.

Return type:

Book

Returns:

Every panel, and the pages they are laid out on – none yet, for a script.

Raises:
  • ScriptSyntaxError – The script cannot be parsed – no PANEL heading, dialogue before the first – or a panel does not validate.

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

  • 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 script is written in the comic-script format writers already use; its front matter is YAML. It has no pages: a page heading groups panels for reading.

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_script
>>> book = compile_script("---\ncast: {A: {reference: alice}}\n---\nPANEL 1\nA\nHi.\n")
>>> list(book.panels)
['1']

See also

parse_script, to stop at the IR. compile_book, for a YAML scene.