compile_source#

Import

from scenet import compile_source

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_source(text, *, source=None, base=None, library=None, metrics=None)[source]#

Compile one panel from a source string.

The usual entry point, and the one to reach for first.

Parameters:
  • text (str) – A single-panel document in the YAML surface syntax.

  • source (Path | None) – Path the text came from, used to prefix error messages and to find the files it names beside it. Pass it when you have one; the diagnostics are much more useful with 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 font that ships as a dependency of this package.

Return type:

CompileResult

Returns:

The compiled panel, with the intermediate results kept for inspection.

Raises:
  • PanelSyntaxError – The document 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

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.

One panel only: a document with panels: or pages: is refused. Compile it with compile_book.

Example

>>> from scenet import compile_source, render
>>> result = compile_source(
...     "{cast: {alice: {reference: alice}}, script: [{say: {by: alice, text: Hello.}}]}"
... )
>>> len(result.core.balloons)
1
>>> result.core.balloons[0].lines
('Hello.',)
>>> svg = render(result.core)

See also

compile_file, to read from disk. compile_scene, for multi-panel documents. compile_document, to dispatch on extension and accept any supported syntax.

Added in version 0.11: The base parameter.