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:
StrEnumWhich 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
regularDialogue, and
spokencaptionsitalicEvery other caption kind
bold_italicEmphasis, in either – Blambot’s rule for a stressed word
displaySound 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:
BaseModelReject 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.
.infand.nanare 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.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’spanels:defines.
- Raises:
RuleViolationError – Rule
page-layout, located at the placement at fault.- Return type:
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
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
placeinstead of listing masses;in a scene, panels that state only what differs from what they inherit;
nullfor 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.yamlfile 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 checkdoes.Example
>>> from scenet.schema import artwork_schema >>> sorted(artwork_schema()["properties"]) ['figures', 'keep_out', 'size']
- scenet.schema.puppet_schema()[source]#
The schema for a puppet file, a
*.puppet.yamla 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_topis 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 checkdoes, in the puppet file, on a document that casts it.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 carryover.
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:
ValueErrorA span was opened and never closed.
- position#
Index of the opening underscore in the text as written.
- class scenet.emphasis.Span[source]#
Bases:
objectA stretch of text, emphasised or not.
- __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:
- 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:
- 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:
objectA panel’s lettering family, read.
- declared#
The faces the document named a file for. Empty when it named none and letters in the shipped family.
- stands_in(face)[source]#
Whether
faceis set in another face, because the document named no file for it.- Return type:
- __init__(typeface, declared=frozenset({}))#
- scenet.lettering.load_font(declared, base, *, loc)[source]#
Read one declared font file.
- Parameters:
- Return type:
- 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:
- Return type:
- 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:
PanelSyntaxErrorA 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 checkreports 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:
ContractErrorandPuppetFileError.- 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
locform; 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.
- 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:
- scenet.paths.read_document(path, *, error=<class 'scenet.errors.PanelSyntaxError'>)[source]#
Read a document a caller names, as UTF-8 text.
- Parameters:
path (
Path) – The document.error (
type[PanelSyntaxError]) – What a document that is not UTF-8 is: aScriptSyntaxErrorfor a script.
- Return type:
- 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 aserror.
- 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:
- Returns:
Its bytes.
- Raises:
FileReadError – The system will not read it. A
MissingFileErrorwhen it is not there; either keeps the system’serrno,strerrorandfilename, and is anOSError.
- 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, orNonefor 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:
- 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_relativereports 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; orNonewhen 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:
- 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:
- 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, orNonewhen 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:
- 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.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:
objectA 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:
- media_type#
image/pngorimage/jpeg, from the file’s own first bytes.- Type:
Literal['image/png','image/jpeg']
- __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:
- Return type:
- 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:
- 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)