The language#

The intermediate representation: a validated semantic scene graph, and the real definition of the language. Nothing here carries a coordinate.

scenet.ir#

The intermediate representation: a validated semantic scene graph.

This is the language’s real definition. The YAML surface syntax is one way to produce it; a comic-script frontend will be another. Nothing here carries a coordinate – computing those is the solver’s job.

Validation is strict on purpose. Panel sources are untrusted input, and a typo in a predicate or an actor id should be a clear error at parse time rather than a silently wrong picture.

class scenet.ir.Face[source]#

Bases: StrEnum

Which face of the lettering family a run of text is set in.

Not something an author writes: a caption’s kind decides between roman and italic, and a word written between underscores is set in bold italic. It is recorded in Panel Core, run by run, so the emitter draws each run in the face it was measured in.

Face

Used for

regular

Dialogue, and spoken captions

italic

Every other caption kind

bold_italic

Emphasis, in either – Blambot’s rule for a stressed word

display

Sound effects: letters that are part of the picture

Each is a real font file of the same family. A synthetic slant or a stroked-out bold would measure as the roman face and draw as neither, which is the disagreement between measurement and rendering that lettering as outlines exists to prevent.

REGULAR = 'regular'#
ITALIC = 'italic'#
BOLD_ITALIC = 'bold_italic'#
DISPLAY = 'display'#
class scenet.ir.Strict[source]#

Bases: BaseModel

Reject unknown keys everywhere.

A misspelled key that is silently ignored produces a panel that is subtly wrong with no indication of why, which is the worst possible failure for a language meant to be precise.

Non-finite numbers are refused for the same reason. .inf and .nan are valid YAML floats, but every number in a document is a length, a weight or a fraction, and an infinite one reached the solver – where kiwisolver ended the interpreter without an exception to report.

scenet.ir.Text#

Text, as an author wrote it. Scenet YAML types 1984, 1.50 and true as a number and a boolean (scenet.safe_yaml), but where the language expects text that is what they are: text: 1984 letters 1984, and by: 1984 names the actor keyed 1984. The schema says so, or an editor validating with it would flag a line that compiles.

Every str a document can reach is one of these, and every bool and number is strict – StrictBool, StrictFloat – or pydantic would read the text yes as true and 01750 as 1750, the very mistypings the profile exists to prevent. A test walks every model to hold both.

alias of str

scenet.ir.check_placements(layout, panels)[source]#

Check that every placement names a panel, and that none is placed twice.

A panel that is on no page is allowed: it may exist only to be inherited from.

Parameters:
  • layout (PageLayout) – The validated pages.

  • panels (Sequence[str]) – The names the document’s panels: defines.

Raises:

RuleViolationError – Rule page-layout, located at the placement at fault.

Return type:

None

scenet.places#

The named-place library. A preset expands into a mass list an author could have written themselves, which is what keeps it a library rather than a second, opaque format – and the expansion happens in the frontend, so nothing downstream ever sees a place.

The place library: named settings, and what each expands into.

The thing an author wants to write is where the scene is, not a list of shapes. So the headline surface is a named place:

setting:
  place: docks

The rule that keeps that honest: a preset expands into a mass list the author could have written themselves, and is never a second opaque format. A library for convenience, not a parallel language. The expansion happens in the frontend, so by the time anything downstream sees a backdrop there is exactly one representation of it – the same treatment alice left_of bob gets on its way to a Relation.

Free prose is deliberately not offered. setting: "a rainy street corner at midnight" needs language understanding, and frontends/script_front.py already refuses to interpret prose on the grounds that guessing produces panels that are confidently wrong. A named place is the honest middle: it reads like a description and resolves deterministically.

Within a place, masses are listed back to front. Draw order comes from the plane, so the listing order only decides ties within one plane – but reading the list in the order it will be painted is what makes a preset reviewable.

scenet.places.place_of(masses)[source]#

The named place a list of masses is, or None for a list no place expands into.

A place reaches the IR as its masses and nothing else, so this is how a place is named again afterwards: by its masses, whether place: wrote them or an author wrote the same list out by hand. The description reads it, and Panel Core records it.

Example

>>> from scenet import PLACES, Place
>>> from scenet.places import place_of
>>> place_of(PLACES[Place.DOCKS])
<Place.DOCKS: 'docks'>
>>> place_of(()) is None
True
Return type:

Place | None

scenet.schema#

The JSON Schema an editor validates a document against, made from the IR itself.

The JSON Schema for Scenet documents, as people write them.

The pydantic models in scenet.ir are the language’s real definition, and PanelIR.model_json_schema() describes them faithfully. It does not describe what anybody types. The YAML frontend accepts conveniences that normalise and merge remove before the models see the document:

  • staging written as a sentence, alice left_of bob;

  • script entries tagged by verb, - say: {by: alice, text: ...};

  • a setting that names a place instead of listing masses;

  • in a scene, panels that state only what differs from what they inherit;

  • null for a cast member, which leaves an inherited one out (settle).

Publishing the IR’s schema made an editor flag every one of those as an error – 21 of the 22 gallery documents, on lines that compiled. So the published schema starts from the IR’s and puts each convenience back, next to a note of the code it mirrors. Every field, enum and docstring still comes from the models; only the shape changes.

Example

>>> from scenet.schema import panel_schema
>>> schema = panel_schema()
>>> sorted(schema["properties"]["script"]["items"]["anyOf"][0]["properties"])
['say']
scenet.schema.artwork_schema()[source]#

The schema for an artwork contract, a *.art.yaml file beside its picture.

A contract is written as the model reads it, with no conveniences to put back, so this is the model’s own schema. What it cannot say – every point on the picture, every region a simple polygon, the size the picture’s own – scenet check does.

Return type:

dict[str, Any]

Returns:

A JSON Schema (draft 2020-12) for an artwork contract.

Example

>>> from scenet.schema import artwork_schema
>>> sorted(artwork_schema()["properties"])
['figures', 'keep_out', 'size']
scenet.schema.panel_schema()[source]#

The schema for a single-panel document.

Return type:

dict[str, Any]

Returns:

A JSON Schema (draft 2020-12) that accepts exactly the surface syntax a .panel.yaml file is written in.

scenet.schema.puppet_schema()[source]#

The schema for a puppet file, a *.puppet.yaml a cast member names by its path.

A puppet is written as the model reads it, so this is the model’s own schema, plus what of its validators a schema can state: every landmark is there, head_top is zero, and the default pose is declared. What it cannot say – landmarks increasing downward, a skeleton that is a tree, every joint a part or a pose names declared – scenet check does, in the puppet file, on a document that casts it.

Return type:

dict[str, Any]

Returns:

A JSON Schema (draft 2020-12) for a puppet file.

Example

>>> from scenet.schema import puppet_schema
>>> puppet_schema()["required"]
['name', 'units_per_head', 'landmarks', 'joints', 'face', 'poses']
scenet.schema.scene_schema()[source]#

The schema for a multi-panel document.

Built from the panel schema rather than declared separately, so the two can never describe different languages. A scene allows the same keys as a panel – there they act as defaults every panel inherits – plus panels, whose members may additionally carry over.

Return type:

dict[str, Any]

Returns:

A JSON Schema (draft 2020-12) for a .scene.yaml file.

scenet.emphasis#

How a stressed word is written: between underscores, by Markdown’s rules for them. Used by the IR to refuse emphasis that is never closed, and by the solver to decide which face each character is measured and drawn in – one function, so the two cannot disagree.

Emphasis in lettering: the words a script underlines, and a letterer sets in bold italic.

Blambot’s Comic Book Grammar & Tradition: “There’s almost no plain bold in comics dialogue. Typically, bold italic is used when emphasis is placed on a word.” Dark Horse’s script format asks writers to underline the words they want stressed. Plain text has no underline, so an author writes the word between underscores – I _told_ you – which is what this module reads.

Underscores, and only underscores. Markdown’s other marker, *, starts an alias in YAML when it opens a plain value (text: *told* you does not parse), and it is one of the characters a typed grawlix is made of. An underscore has neither problem.

The rules are Markdown’s for an underscore, which is what keeps snake_case literal:

  • an underscore opens a span when nothing alphanumeric is before it and something other than a space is after it;

  • inside a span, an underscore closes it when something other than a space is before it and nothing alphanumeric is after it;

  • any other underscore is just an underscore – so is one beside another, as in __init__ – and _ writes one anywhere;

  • spans do not nest, and may run across words: _told you_.

A span opened and never closed is refused rather than guessed at. It is almost always a missing underscore, and setting the rest of the line in bold italic would be a confident wrong answer.

Pure and dependency-free on purpose: the IR uses it to refuse an unclosed span while the source is still in view, and the solver uses it to decide which face each character is measured and drawn in. The two cannot disagree, because they call the same function.

scenet.emphasis.MARKER = '_'#

What opens and closes a span.

exception scenet.emphasis.EmphasisError[source]#

Bases: ValueError

A span was opened and never closed.

position#

Index of the opening underscore in the text as written.

__init__(text, position)[source]#

Build the error, naming where the span opened.

Parameters:
  • text (str) – The text as written.

  • position (int) – Index of the opening underscore.

class scenet.emphasis.Span[source]#

Bases: object

A stretch of text, emphasised or not.

text#

What is lettered, markers and escapes already removed.

Type:

str

emphasised#

Whether it is set in the emphasis face.

Type:

bool

__init__(text, emphasised)#
scenet.emphasis.parse(text)[source]#

Split text into emphasised and plain spans.

Parameters:

text (str) – A line of dialogue or a caption, as the author wrote it.

Return type:

tuple[Span, ...]

Returns:

The spans in order, each non-empty, adjacent ones never alike. Text with no marker in it is one plain span.

Raises:

EmphasisError – A span was opened and never closed.

Example

>>> from scenet.emphasis import parse
>>> [(span.text, span.emphasised) for span in parse("I _told_ you")]
[('I ', False), ('told', True), (' you', False)]
scenet.emphasis.plain(text)[source]#

The text as it is read: markers and escapes removed.

Parameters:

text (str) – As the author wrote it.

Return type:

str

Returns:

What is lettered.

Raises:

EmphasisError – A span was opened and never closed.

Example

>>> from scenet.emphasis import plain
>>> plain("I _told_ you")
'I told you'

scenet.lettering#

An author’s lettering face: reading the font files a document declares, and what stands in for a face it does not name.

An author’s lettering face, read from the font files a document declares.

The shipped face is Source Sans Pro, which THIRD_PARTY_NOTICES.md already calls a placeholder. The faces letterers actually use – Blambot’s, Comicraft’s – are commercial or free only on their own terms, so the project can never ship one; an author can declare one. lettering: {font: ...} names the files, and this module reads them.

Two choices are made here and nowhere else:

  • A font is known by its bytes. Files are cached by the digest of what is in them, not by where they are, so a file replaced in place – the playground does it on every upload – is read again; and Panel Core records the digest, so a drawing can refuse a file that merely shares a name with the one that was measured.

  • A face the document does not name stands in from one it does. Italic captions fall back to the regular face, emphasis to the italic and then the regular: a family drawn from one file is a whole family, which a mix of the author’s face and the shipped one would not be. The compiler says so when a stand-in is actually used. The display face is the exception: sound effects are not text, so an author’s text faces never stand in for it, and it stays Bangers unless the document names one of its own.

Every failure – a path that is absolute or has no folder to be read from, a file that is missing, a file that is not a font – is rule font-file, located at the face it names.

scenet.lettering.FONT_RULE = 'font-file'#

The rule every font fault is reported under.

class scenet.lettering.Lettering[source]#

Bases: object

A panel’s lettering family, read.

typeface#

Every face, the author’s where they named one.

Type:

Typeface

declared#

The faces the document named a file for. Empty when it named none and letters in the shipped family.

Type:

frozenset[Face]

stands_in(face)[source]#

Whether face is set in another face, because the document named no file for it.

Return type:

bool

__init__(typeface, declared=frozenset({}))#
scenet.lettering.load_font(declared, base, *, loc)[source]#

Read one declared font file.

Parameters:
  • declared (str) – The path as the document wrote it.

  • base (Path | Mapping[str, bytes] | None) – The document’s folder, or the files sent with it.

  • loc (tuple[str | int, ...]) – Where in the document it was written, for the finding.

Return type:

FontMetrics

Returns:

Its metrics, shared with every other document declaring the same bytes.

Raises:

PanelSyntaxError – Rule font-file. The message names the path as written, never as resolved: findings are output too, and an absolute path in one would make it differ between two checkouts.

scenet.lettering.typeface_for(spec, base)[source]#

The family a panel letters in: the shipped one, or the files it declares.

Parameters:
  • spec (LetteringSpec) – The panel’s lettering block.

  • base (Path | Mapping[str, bytes] | None) – The document’s folder, the files sent with it, or None for text with neither.

Return type:

Lettering

Returns:

The family, and which faces were named.

Raises:

PanelSyntaxError – Rule font-file, for the first face that cannot be read.

Example

>>> from scenet import LetteringSpec
>>> from scenet.lettering import typeface_for
>>> typeface_for(LetteringSpec(), None).declared
frozenset()

scenet.paths#

Files a document names, found beside the document – never by an absolute path.

Files a document names, found beside the document.

A document may point at a file it does not contain – a lettering face, or a picture to letter over. Every such path is read relative to the folder the document is in, the way a link in a web page is, and never as an absolute path. That is what lets a document and the files it names travel together and compile the same anywhere, and what stops a server compiling documents it was sent from being steered at files of its own.

The folder is the document’s, not the working directory’s: scenet build comics/one.panel.yaml reads fonts/x.ttf from comics/fonts/, wherever it was run from. Text compiled with no file behind it has no folder, and can name no file unless the caller says which folder it belongs to – or hands over the files themselves, by the path the document writes, which is how a server is sent them: it never reads a folder of its own. Both are read the same way, ./art/a.png and art/a.png alike.

Nothing here reaches the output. A resolved path is used to open a file and is then forgotten; what a Core records about a font is what is in it.

Some of those files are text an author writes: a picture’s artwork contract, a puppet a cast member names. read_model reads one the same way for both, and a fault in it is a NamedFileError, located in the file as well as where the document names it.

scenet.paths.Folder = pathlib.Path | collections.abc.Mapping[str, bytes]#

Where the files a document names are: the folder it is in, or the files themselves, by the path the document writes.

exception scenet.paths.NamedFileError[source]#

Bases: PanelSyntaxError

A file a document names, there and wrong: located in it, as well as where it is named.

A fault inside an artwork contract or a puppet file is fixed in that file, so scenet check reports it there when the document was checked as a file. Checked as text – the playground, a model over MCP – there is no such file to open, and it is reported where the document names it, with the file’s own line in the message.

Each kind of file is a subclass, which says what the file is called and the rule its faults are reported under: ContractError and PuppetFileError.

file#

The file’s path, relative to the document, as the document reaches it.

inner#

Where in the file the fault is, in pydantic’s loc form; empty for the file as a whole.

region#

The fault’s span in the file’s text, when it was parsed far enough to find it.

KIND: ClassVar[str]#

What a file of this kind is called in a message, before its path.

RULE: ClassVar[str]#

The rule every fault in a file of this kind is reported under.

__init__(message, *, file, inner=(), region=None, loc=())[source]#

Build the error.

Parameters:
  • message (str) – What is wrong, without the file’s name.

  • file (str) – The file’s path, relative to the document.

  • inner (tuple[str | int, ...]) – Where in the file.

  • region (Region | None) – Where in its text.

  • loc (tuple[str | int, ...]) – Where in the document the file is named.

scenet.paths.check_relative(declared, *, what, rule, loc=())[source]#

Refuse a path that could not be read the same way on every system, or at all.

Everything resolve_relative() refuses but the want of a folder: for a path that is kept rather than opened, as Panel Core keeps a picture’s.

Raises:

PanelSyntaxError – The path is empty or absolute, or has a backslash or a control character in it.

Return type:

None

scenet.paths.read_document(path, *, error=<class 'scenet.errors.PanelSyntaxError'>)[source]#

Read a document a caller names, as UTF-8 text.

Parameters:
Return type:

str

Returns:

Its text, read as pathlib.Path.read_text() reads it.

Raises:
  • FileReadError – The system will not read it.

  • PanelSyntaxError – Rule syntax: it is not UTF-8, so it is no document at all. Raised as error.

scenet.paths.read_file(path)[source]#

Read a file a caller names – not one a document names – whole.

Parameters:

path (Path) – The file, as the caller gave it.

Return type:

bytes

Returns:

Its bytes.

Raises:

FileReadError – The system will not read it. A MissingFileError when it is not there; either keeps the system’s errno, strerror and filename, and is an OSError.

scenet.paths.read_model[M: BaseModel](declared, base, model, *, what, error, holds, unknown_key, loc=(), tags=frozenset({}))[source]#

Read a YAML file a document names, and validate it, each fault located in it.

Parameters:
  • declared (str) – The path as the document writes it.

  • base (Path | Mapping[str, bytes] | None) – The document’s folder, or the files sent with it, or None for text with neither.

  • model (type[M]) – What the file holds.

  • what (str) – What the file is, for a message about its path: puppet, say.

  • error (type[NamedFileError]) – The kind of file, which says how a fault inside it is reported.

  • holds (str) – What its top-level mapping holds, for the message when it is not one.

  • unknown_key (str) – The message for a key the model does not have.

  • loc (tuple[str | int, ...]) – Where in the document the file is named.

  • tags (frozenset[str]) – The tags of a tagged union the model validates a list’s items with. pydantic puts one in a fault’s location after the item’s index, where the file has no key, so it is left out to locate the fault where it is written.

Return type:

tuple[M, str, bytes]

Returns:

What the file declares, its text, and its bytes.

Raises:
  • PanelSyntaxError – Under the error’s rule, for a path that cannot be read, as read_relative reports it – located where the document names the file.

  • NamedFileError – The error given, for a file that is there and wrong, located in it too: not UTF-8 text, not YAML, a key written twice, not a mapping, or not what the model allows – the first fault, at the key that is wrong.

scenet.paths.read_relative(declared, base, *, what, rule, loc=())[source]#

Read a file a document names, from its folder or from the files sent with it.

Parameters:
  • declared (str) – The path as written, with / between folders.

  • base (Path | Mapping[str, bytes] | None) – The document’s folder; or the files beside it, by the path the document writes, when it was sent as text; or None when it has neither.

  • what (str) – What the file is, for the message: font, say.

  • rule (str) – The rule every failure is reported under.

  • loc (tuple[str | int, ...]) – Where in the document the path was written.

Return type:

bytes

Returns:

The file’s bytes.

Raises:

PanelSyntaxError – Anything resolve_relative() refuses, or the file is not there, or cannot be read. The message names the path as written, never as resolved: a finding is output too, and a folder in it would differ between two checkouts.

Example

>>> from scenet.paths import read_relative
>>> read_relative("./art/a.png", {"art/a.png": b"..."}, what="image", rule="image-file")
b'...'
scenet.paths.record_dependency(path)[source]#

Report a filesystem path to the active compilation, including missing paths.

Return type:

None

scenet.paths.resolve_relative(declared, base, *, what, rule, loc=())[source]#

Resolve a path a document wrote against the folder the document is in.

Parameters:
  • declared (str) – The path as written, with / between folders.

  • base (Path | None) – The document’s folder, or None when the text has no file behind it.

  • what (str) – What the file is, for the message: font, say.

  • rule (str) – The rule a bad path breaks, for the finding.

  • loc (tuple[str | int, ...]) – Where in the document the path was written.

Return type:

Path

Returns:

The file’s path. Not checked to exist – whoever opens it says what it found.

Raises:

PanelSyntaxError – The path is empty or absolute, has a backslash or a control character in it, or there is no folder to read it from.

Example

>>> from pathlib import Path
>>> from scenet.paths import resolve_relative
>>> found = resolve_relative("fonts/a.ttf", Path("comic"), what="font", rule="font-file")
>>> found.as_posix()
'comic/fonts/a.ttf'
scenet.paths.track_dependencies(dependencies)[source]#

Collect filesystem paths read during one compilation, without changing its result.

Return type:

Generator[None, None, None]

scenet.images#

A picture to letter over: how big it is, read from its PNG or JPEG header, and nothing else.

A picture to letter over, read from a file the document names.

setting: {image: art/p01.png} puts a picture drawn elsewhere behind the cast. The solver never sees artwork, so what this module takes from the file is a fact about it, not its content: how many pixels across and how many down, read from the header. The compiler never decodes the pixels; only the print emitter carries them, unchanged, into a PDF (scenet.emit.pdf_images).

Two formats, PNG and JPEG, because they are what SVG 2 requires every viewer to draw. They are told apart by their first bytes, never by the file’s name. Both headers take a few lines to read, so no imaging library is involved: one would have to pass the licence gate, and ship in the playground’s Pyodide, to answer two questions.

One more fact is read, and refused rather than used: an EXIF orientation saying the picture is to be shown turned. Renderers disagree on obeying it – Chromium turns an SVG <image> by it, gdk-pixbuf does not unless asked – so a picture carrying one would be upright in one viewer and on its side in the next. EXIF that cannot be read is ignored, as every renderer ignores it.

Every failure – the path, the file, the header, the orientation – is rule image-file, located where the image is named.

scenet.images.IMAGE_RULE = 'image-file'#

The rule every image fault is reported under.

scenet.images.MediaType#

The two media types, as a data: URI names them.

alias of Literal[‘image/png’, ‘image/jpeg’]

class scenet.images.SuppliedImage[source]#

Bases: object

A picture a document names, read.

href#

The path exactly as the document wrote it. A linked SVG points at it by this, so it reaches the output as written and nothing else about the file’s location does.

Type:

str

media_type#

image/png or image/jpeg, from the file’s own first bytes.

Type:

Literal['image/png', 'image/jpeg']

sha256#

The digest of its bytes, which is what it is known by – as a font is.

Type:

str

width#

Pixels across.

Type:

int

height#

Pixels down.

Type:

int

data#

The bytes, for a renderer asked to embed them.

Type:

bytes

__init__(href, media_type, sha256, width, height, data)#
scenet.images.load_image(declared, base, *, loc)[source]#

Read the picture a document names, and how big it is.

Parameters:
  • declared (str) – The path as the document wrote it.

  • base (Path | Mapping[str, bytes] | None) – The document’s folder, the files sent with it, or None for text with neither.

  • loc (tuple[str | int, ...]) – Where in the document it was named, for the finding.

Return type:

SuppliedImage

Returns:

The picture, with its size.

Raises:

PanelSyntaxError – Rule image-file, naming the path as written.

Example

>>> from scenet.images import load_image
>>> photo = bytes.fromhex("ffd8 ffc0000b080bb80fa001011100 ffd9")
>>> image = load_image("art/photo.jpg", {"art/photo.jpg": photo}, loc=())
>>> image.media_type, image.width, image.height
('image/jpeg', 4000, 3000)
scenet.images.measure(data)[source]#

A picture’s media type and size in pixels, from its header.

Parameters:

data (bytes) – The file’s bytes.

Return type:

tuple[Literal['image/png', 'image/jpeg'], int, int]

Returns:

(media_type, width, height).

Raises:

ValueError – The bytes are not a PNG or JPEG whose size its header gives, or the picture is turned by its EXIF orientation. The message finishes a sentence that begins with the file’s name.

Example

>>> from scenet.images import measure
>>> measure(bytes.fromhex("ffd8 ffc0000b080bb80fa001011100 ffd9"))
('image/jpeg', 4000, 3000)