compile_book#

Import

from scenet import compile_book

Defined in

scenet.pipeline (source)

Install

pip install scenet

Since

0.10

Stability

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

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

Compile a scene and lay its panels out on pages.

A page decides two things about each panel on it – the size of its frame, and the height its type size is a fraction of – and nothing else. Each panel is still compiled on its own, so a panel on a page is exactly that panel compiled alone at that size, and a panel’s composition never depends on what sits beside it.

Parameters:
  • text (str) – A scene document. One with no pages: compiles exactly as compile_scene always has.

  • 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 document 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:

The compiled panels and pages.

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

Every panel is compiled, whether a page places it or not. A panel a page places is compiled at its frame’s shape, so it can differ from the same panel compiled alone.

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_book
>>> book = compile_book(
...     "pages: [{tiers: [{panels: [a, b]}]}]\n"
...     "panels: {a: {cast: {x: {reference: alice}}}, b: {over: a}}"
... )
>>> [(frame.panel, frame.width) for frame in book.pages[0].frames]
[('a', 880.0), ('b', 880.0)]
>>> book.panels["a"].core.width
880.0

See also

render_pages and render_pdf, to draw its pages. compile_book_file, to read a file of any kind. compile_script, for a comic script.

Added in version 0.11: The base parameter.