compile_source#
Import |
|
Defined in |
|
Install |
|
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 onesourceis in – or when there is nosourceat 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:
- 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
poseis one its puppet does not declare.UnknownExpressionError – A cast member’s
expressionis 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
baseor the folder ofsource; 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:orpages:is refused. Compile it withcompile_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
baseparameter.