compile_book#
Import |
|
Defined in |
|
Install |
|
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 nopages:compiles exactly ascompile_scenealways 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 onesourceis in.library (
PuppetLibrary|None) – Characters to draw from. Defaults to the two shipped puppets.metrics (
FontMetrics|None) – Font to measure lettering against.
- Return type:
- 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
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
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
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.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_pagesandrender_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
baseparameter.