API reference#

Everything a user is allowed to depend on is named in scenet.__all__ and imported straight from the top level:

from scenet import compile_source, render

result = compile_source("cast: {a: {reference: alice}}")
svg = render(result.core)

Each public name has an entry of its own: a card with its import line, the module that defines it, what to install and the release it appeared in, then its signature, what it does, what it raises, its limits, an example and where to look next.

The public surface at a glance#

Names

Compiling

Book · CompileNote · CompileResult · compile_book · compile_book_file · compile_document · compile_file · compile_ir · compile_scene · compile_scene_file · compile_script · compile_source

Parsing, without compiling

load_panel · SceneDocument · load_scene · load_scene_document · load_script · parse_panel · parse_scene · parse_scene_document · parse_script

Rendering

render · render_conditioning · Conditioning · render_debug · render_page · render_pages · render_pdf · render_strip

Measuring lettering

FontMetrics

The intermediate tiers

PageCore · PanelCore · PanelIR

Describing a panel

AnchorX · BalloonKind · CameraAngle · CameraSpec · CaptionEvent · CaptionKind · CaptionTone · CastMember · Direction · Facing · FontSpec · LetteringSpec · Mark · Palette · PanelSpec · PlacementZone · Predicate · Relation · SayEvent · SfxEvent · SfxSize · ShotType · Side

Laying panels out on pages

PageFormat · PageLayout · PageSpec · PanelPlacement · Tier · Column · StackedPanel · Inset · Corner · InsetOrder

Describing where and when it happens

PLACES · Fit · Horizon · Mass · MassKind · Place · Plane · SettingSpec · Spans · TimeOfDay · TypeSize · Weather

Puppets

Landmark · PuppetLibrary · PuppetSpec · default_library · load_puppet

Errors

AssetError · BalloonPlacementError · CompositionError · CoreSyntaxError · FileReadError · LayoutError · MalformedAssetError · MissingFileError · PanelSyntaxError · RenderError · ScenetError · ScriptSyntaxError · SfxPlacementError · SolverError · SourceError · UnknownActorError · UnknownExpressionError · UnknownPoseError · UnknownPuppetError

Metadata

__version__

Guarantees#

What holds for every public name: what stays stable, what is deterministic, what threads may share, which files a compile reads, and how long it takes. See Guarantees.

Types the API returns and takes#

Some types reach you without being in scenet.__all__:

  • The Panel Core types, CoreActor, CoreBalloon, CoreFrame and the rest, are what you read off result.core and book.pages. They have a page of their own. Import one from scenet.core to annotate with it; its fields are the Panel Core format’s, and change only as the format does.

  • base=, on the functions that compile text, takes a folder: a pathlib.Path, or a mapping of each file’s relative path to its bytes. Its type is the alias scenet.paths.Folder; you never need to name it.

Types#

Scenet ships a py.typed marker, so mypy, pyright, ty and basedpyright read these annotations directly from the installed package. No stubs to install, nothing to configure.

Internals#

Names outside __all__ are internal. They are still documented here, by the module that defines them – the decisions inside the solver are the interesting part of this project – but they are outside semantic versioning: a minor release may rename, move or remove any of them without notice.