Errors#

Every error a public function raises is one of these, and a ScenetError: except ScenetError catches them all. Each also keeps the built-in exception it would have been, so except ValueError keeps working. See scenet.errors for what the promise covers.

AssetError#

Import

from scenet import AssetError

Defined in

scenet.errors (source)

Install

pip install scenet

Since

0.1

Stability

Public: follows semantic versioning. Below 1.0, a minor release may change it, and the CHANGELOG says how.

exception scenet.errors.AssetError[source]#

Bases: ScenetError

A puppet or a font that is missing, unreadable or self-inconsistent.

Not itself a ValueError: a puppet the library does not hold is a UnknownPuppetError, a KeyError, and an except ValueError written for bad values should not catch a lookup miss. A file that is there and wrong is a MalformedAssetError, which is a ValueError.

Example

>>> from scenet import AssetError, compile_source
>>> try:
...     compile_source("cast: {a: {reference: nobody}}")
... except AssetError as exc:
...     print(type(exc).__name__)
UnknownPuppetError

See also

UnknownPuppetError, for a puppet not there. MalformedAssetError, for a file that is wrong.

BalloonPlacementError#

Import

from scenet import BalloonPlacementError

Defined in

scenet.errors (source)

Install

pip install scenet

Since

0.1

Stability

Public: follows semantic versioning. Below 1.0, a minor release may change it, and the CHANGELOG says how.

exception scenet.errors.BalloonPlacementError[source]#

Bases: SolverError

No legal position exists for a balloon or a caption.

Every candidate position was rejected: it covered a face, left the panel, overlapped a box already placed, or would have broken reading order. Usually this means too many words for the panel size – widen the panel, shorten the line, or split it across two panels.

Captions raise this too. They obey the same hard rules and are placed in the same pass, so the failure is the same failure; the name is kept because the rule id balloon-placement is stable across releases.

Example

>>> from scenet import BalloonPlacementError, compile_source
>>> try:
...     compile_source(
...         "lettering: {size: 400}\ncast: {a: {reference: alice}}\n"
...         "script: [{say: {by: a, text: Hello.}}]"
...     )
... except BalloonPlacementError as exc:
...     print(type(exc).__name__)
BalloonPlacementError

See also

SfxPlacementError, the same for a sound effect.

CompositionError#

Import

from scenet import CompositionError

Defined in

scenet.errors (source)

Install

pip install scenet

Since

0.1

Stability

Public: follows semantic versioning. Below 1.0, a minor release may change it, and the CHANGELOG says how.

exception scenet.errors.CompositionError[source]#

Bases: SourceError

A panels: document whose over: inheritance cannot be resolved.

Raised for a panel inheriting from one that does not exist, and for a cycle – a over b over a – which has no fixed point to resolve to.

Example

>>> from scenet import CompositionError, compile_scene
>>> try:
...     compile_scene("panels: {a: {over: b}, b: {over: a}}")
... except CompositionError as exc:
...     print(exc)
'over' chain is cyclic: a -> b -> a
loc#

Path to the over: at fault, such as ("panels", "b", "over"), so a finding can point at the key rather than the whole panels: block.

See also

compile_scene, which resolves over:.

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

Build the error, keeping where it is as data as well as prose.

Parameters:
  • message (str) – What went wrong.

  • source (Path | None) – Path the document came from, if it was read from disk.

  • loc (tuple[str | int, ...]) – Path to the over: at fault.

CoreSyntaxError#

Import

from scenet import CoreSyntaxError

Defined in

scenet.errors (source)

Install

pip install scenet

Since

0.13

Stability

Public: follows semantic versioning. Below 1.0, a minor release may change it, and the CHANGELOG says how.

exception scenet.errors.CoreSyntaxError[source]#

Bases: SourceError

A Panel Core or Page Core document that does not read back.

Raised by PanelCore.from_json and PageCore.from_json for text that is not JSON, or JSON that is not a Core of that kind. The message names each field at fault.

Also a ValueError, as both of those were: json.JSONDecodeError and pydantic’s ValidationError.

Example

>>> from scenet import CoreSyntaxError, PanelCore
>>> try:
...     PanelCore.from_json('{"width": 100}')
... except CoreSyntaxError as exc:
...     print(exc)
invalid Panel Core:
  at height: Field required

See also

PanelCore.to_json, what reads back.

FileReadError#

Import

from scenet import FileReadError

Defined in

scenet.errors (source)

Install

pip install scenet

Since

0.13

Stability

Public: follows semantic versioning. Below 1.0, a minor release may change it, and the CHANGELOG says how.

exception scenet.errors.FileReadError[source]#

Bases: ScenetError, OSError

A file a call names that cannot be read: a document, a puppet, a font.

Raised by the functions that take a path – compile_file, load_panel, load_puppet and the rest – when the system refuses to read it. A file a document names, beside it, is the document’s fault instead: a PanelSyntaxError that says where it was named.

Also an OSError, carrying what the system said: errno, strerror and filename are those of the system’s own error, which is kept as __cause__. A file that is not there at all is a MissingFileError, which is also a FileNotFoundError.

Example

>>> from pathlib import Path
>>> from scenet import FileReadError, compile_file
>>> try:
...     compile_file(Path("no-such.panel.yaml"))
... except FileReadError as exc:
...     print(exc.filename, "--", exc.strerror)
no-such.panel.yaml -- No such file or directory

See also

MissingFileError, for a file that is not there.

static of(error)[source]#

The Scenet error for one the system raised, keeping what it said.

Parameters:

error (OSError) – What reading the file raised.

Return type:

FileReadError

Returns:

A MissingFileError for a file that is not there, and a FileReadError for any other reason.

LayoutError#

Import

from scenet import LayoutError

Defined in

scenet.errors (source)

Install

pip install scenet

Since

0.1

Stability

Public: follows semantic versioning. Below 1.0, a minor release may change it, and the CHANGELOG says how.

exception scenet.errors.LayoutError[source]#

Bases: SolverError

A panel whose required constraints cannot all be satisfied.

Actor placement runs a Cassowary solver in which non-overlap and declared left-to-right ordering are required constraints. If those genuinely conflict – two actors each required to be left of the other – there is no solution and this is raised. Panel bounds are deliberately not required, so a merely crowded panel lets figures bleed off the edge instead of failing.

Example

>>> from scenet import LayoutError, compile_source
>>> try:
...     compile_source(
...         "cast: {a: {reference: alice}, b: {reference: bob}}\n"
...         "staging: [a in_front_of b, b in_front_of a]"
...     )
... except LayoutError as exc:
...     print(exc)
depth ordering is cyclic around 'a'

See also

Relation, the staging a layout must satisfy.

MalformedAssetError#

Import

from scenet import MalformedAssetError

Defined in

scenet.errors (source)

Install

pip install scenet

Since

0.13

Stability

Public: follows semantic versioning. Below 1.0, a minor release may change it, and the CHANGELOG says how.

exception scenet.errors.MalformedAssetError[source]#

Bases: AssetError, ValueError

A puppet or a font file that is there, and is not what it says it is.

Raised for a puppet file that is not YAML, not a mapping, or not a well-formed puppet – an out-of-order landmark, a skeleton that is not a tree; for a folder of puppets that declares one name twice; and for a font file that cannot be measured, because it is not a TrueType or OpenType font or has no Unicode character map.

Also a ValueError, as each of those was before it had a name: a malformed puppet was pydantic’s ValidationError, and a font with no character map a plain ValueError.

Example

>>> from pathlib import Path
>>> from tempfile import TemporaryDirectory
>>> from scenet import MalformedAssetError, load_puppet
>>> with TemporaryDirectory() as folder:
...     path = Path(folder) / "x.puppet.yaml"
...     _ = path.write_text("name: x", encoding="utf-8")
...     try:
...         load_puppet(path)
...     except MalformedAssetError as exc:
...         print(exc.detail.splitlines()[0])
invalid puppet:
source#

The file at fault, or None for bytes read from no file.

detail#

The message without the path, for a report that names the file separately.

See also

load_puppet, which raises it. PanelSyntaxError, what a malformed file a document names is instead: the fault is then the document’s.

__init__(message, *, source=None)[source]#

Build the error, prefixing the file’s path when there is one.

Parameters:
  • message (str) – What is wrong with the file.

  • source (Path | None) – The file, if it was read from disk.

MissingFileError#

Import

from scenet import MissingFileError

Defined in

scenet.errors (source)

Install

pip install scenet

Since

0.13

Stability

Public: follows semantic versioning. Below 1.0, a minor release may change it, and the CHANGELOG says how.

exception scenet.errors.MissingFileError[source]#

Bases: FileReadError, FileNotFoundError

A file a call names that is not there.

Also a FileNotFoundError, which is what reading it raised before, so an except FileNotFoundError around a compile keeps working.

Example

>>> from pathlib import Path
>>> from scenet import MissingFileError, load_panel
>>> try:
...     load_panel(Path("no-such.panel.yaml"))
... except FileNotFoundError as exc:
...     print(isinstance(exc, MissingFileError), exc.filename)
True no-such.panel.yaml

See also

FileReadError, for any other reason a file is unread.

PanelSyntaxError#

Import

from scenet import PanelSyntaxError

Defined in

scenet.errors (source)

Install

pip install scenet

Since

0.1

Stability

Public: follows semantic versioning. Below 1.0, a minor release may change it, and the CHANGELOG says how.

exception scenet.errors.PanelSyntaxError[source]#

Bases: SourceError

A panel document that could not be parsed or validated.

Carries the source path when one is known, so the message reads path/to/duel.panel.yaml: invalid panel: ... rather than losing the file it came from.

rule#

Identifier from the catalogue in RULES, when the frontend knows which rule was broken. Most surface faults reach scenet check as invalid-field, which is honest for a value pydantic rejected; but a check the frontend performs itself – a place that does not exist, a setting that names one and lists masses too – knows exactly what it found, and saying so is the whole point of having a rule catalogue.

loc#

Path to the offending value, from the top of the document, in pydantic’s loc form: in a scene, it starts with panels and the panel’s name. Empty means the document as a whole. When validation found several faults, the message lists each, and rule and loc are the first’s.

Example

>>> from scenet import PanelSyntaxError, compile_source
>>> try:
...     compile_source("panel: {size: [0, 100]}")
... except PanelSyntaxError as exc:
...     print(exc)
invalid panel:
  at panel: panel size must be positive

See also

RULES, the catalogue rule is from. ScriptSyntaxError, the same for a comic script.

__init__(message, *, source=None, rule=None, loc=())[source]#

Build the error, keeping the rule and location as data as well as prose.

Parameters:
  • message (str) – What went wrong, phrased for whoever wrote the document.

  • source (Path | None) – Path the document came from, if it was read from disk.

  • rule (str | None) – Catalogue identifier, when the frontend knows which rule was broken.

  • loc (tuple[str | int, ...]) – Path to the offending value within the panel.

RenderError#

Import

from scenet import RenderError

Defined in

scenet.errors (source)

Install

pip install scenet

Since

0.13

Stability

Public: follows semantic versioning. Below 1.0, a minor release may change it, and the CHANGELOG says how.

exception scenet.errors.RenderError[source]#

Bases: ScenetError, ValueError

A renderer that was not handed what the drawing needs.

The Core is fine; the call is not. Raised when:

  • the Core was lettered in a font of the document’s own, and that font was not handed back as fonts= – drawing its lettering in another face would draw text that does not fit the balloons measured for it;

  • a supplied picture is to be embedded or printed, and its bytes were not handed over as embed= or images=;

  • a page places a panel that was not given;

  • there is nothing to draw: no panels for a strip, no pages for a spread;

  • panels or pages read in two directions are laid side by side;

  • a picture is one the print PDF cannot carry: a lossless or 12-bit JPEG, or a PNG whose data is cut short.

Also a ValueError, as each of these was before it had a name.

Example

>>> from scenet import RenderError, render_strip
>>> try:
...     render_strip([])
... except RenderError as exc:
...     print(exc)
a strip needs at least one panel

See also

Book.fonts and Book.images, what a renderer is handed back.

ScenetError#

Import

from scenet import ScenetError

Defined in

scenet.errors (source)

Install

pip install scenet

Since

0.1

Stability

Public: follows semantic versioning. Below 1.0, a minor release may change it, and the CHANGELOG says how.

exception scenet.errors.ScenetError[source]#

Bases: Exception

Root of every error Scenet raises.

Catch this to handle anything the compiler can go wrong with, without having to enumerate the specific cases or accidentally swallowing an unrelated ValueError from elsewhere in your program.

Example

>>> from scenet import ScenetError, compile_source
>>> try:
...     compile_source("{panel: {size: [1000, 1000]}, cast: {ghost: {reference: nobody}}}")
... except ScenetError as exc:
...     print(type(exc).__name__)
UnknownPuppetError

See also

SourceError, for the “bad document” branch. SolverError, for the “impossible layout” branch.

panel#

The panel being compiled when it was raised, set as it passes out of a whole document’s compile, so a finding can say which panel it is about; None when it was not raised compiling one.

Type:

str | None

ScriptSyntaxError#

Import

from scenet import ScriptSyntaxError

Defined in

scenet.errors (source)

Install

pip install scenet

Since

0.1

Stability

Public: follows semantic versioning. Below 1.0, a minor release may change it, and the CHANGELOG says how.

exception scenet.errors.ScriptSyntaxError[source]#

Bases: PanelSyntaxError

A comic script that could not be parsed.

A subclass of PanelSyntaxError rather than a sibling, because both frontends produce the same IR and a caller handling “bad input” should not have to care which syntax it was written in.

line#

One-based line the fault is on, when the parser knows it. The comic-script frontend is line-oriented, so it usually does – but it had only ever put the number into the message text, which is fine to read and useless to an editor drawing a squiggle. Structured diagnostics need it as a number. There is no column: a script line is prose, and pointing at a character within it would imply a precision the parser does not have.

columns#

One-based first column and the column just past the last, for a fault in the front matter, which is YAML and is located as exactly as a YAML document’s: a tag or an anchor the profile refuses. None everywhere else.

Example

>>> from scenet import ScriptSyntaxError, compile_script
>>> try:
...     compile_script("No panel heading anywhere.")
... except ScriptSyntaxError as exc:
...     print(exc.line, exc.rule)
None None

See also

parse_script, which raises it.

__init__(message, *, source=None, line=None, rule=None, columns=None)[source]#

Build the error, keeping the line number as data as well as prose.

Parameters:
  • message (str) – What went wrong, phrased for whoever wrote the script.

  • source (Path | None) – Path the script came from, if it was read from disk.

  • line (int | None) – One-based line the fault is on, if known.

  • rule (str | None) – Catalogue identifier, when the parser knows which rule was broken.

  • columns (tuple[int, int] | None) – Where on that line the fault is, for one in the front matter.

SfxPlacementError#

Import

from scenet import SfxPlacementError

Defined in

scenet.errors (source)

Install

pip install scenet

Since

0.11

Stability

Public: follows semantic versioning. Below 1.0, a minor release may change it, and the CHANGELOG says how.

exception scenet.errors.SfxPlacementError[source]#

Bases: SolverError

No legal position exists for a sound effect.

Every candidate covered a face, left the panel, lay under an inset or over another sound effect. Usually the effect is too big for the panel: make it small, shorten it, or give the panel more room. Rule sfx-placement.

Example

>>> from scenet import SfxPlacementError, SolverError
>>> issubclass(SfxPlacementError, SolverError)
True

See also

SfxEvent, whose size is usually the fix.

SolverError#

Import

from scenet import SolverError

Defined in

scenet.errors (source)

Install

pip install scenet

Since

0.1

Stability

Public: follows semantic versioning. Below 1.0, a minor release may change it, and the CHANGELOG says how.

exception scenet.errors.SolverError[source]#

Bases: ScenetError, ValueError

A document that is valid but cannot be laid out.

The distinction from SourceError matters: nothing is misspelled and nothing is missing, but the panel as described has no solution – a cast with nowhere left to stand, or a balloon with no legal position. The fix is an editorial change to the panel, not a correction to its syntax.

Also a ValueError.

Example

>>> from scenet import SolverError, compile_source
>>> try:
...     compile_source(
...         "lettering: {size: 400}\ncast: {a: {reference: alice}}\n"
...         "script: [{say: {by: a, text: Hello.}}]"
...     )
... except SolverError as exc:
...     print(type(exc).__name__)
BalloonPlacementError

See also

LayoutError, BalloonPlacementError and SfxPlacementError, its three kinds.

SourceError#

Import

from scenet import SourceError

Defined in

scenet.errors (source)

Install

pip install scenet

Since

0.1

Stability

Public: follows semantic versioning. Below 1.0, a minor release may change it, and the CHANGELOG says how.

exception scenet.errors.SourceError[source]#

Bases: ScenetError, ValueError

A document that could not be understood.

Raised whenever the input is at fault: malformed YAML, an unknown predicate, a reference to a panel that does not exist, a negative panel size. The message names the location and the reason, and is written to be shown directly to whoever wrote the document – no traceback required.

Also a ValueError, since that is what a malformed value has always been.

source#

Path the document was read from, or None for a string compiled in memory. Prefixed to the message when present, so a diagnostic never loses the file it came from.

detail#

The message without that prefix, for a report that names the file separately – a finding’s location does, and the path as typed could be absolute.

Example

>>> from scenet import SourceError, compile_source
>>> try:
...     compile_source("panel: {size: [0, 100]}")
... except SourceError as exc:
...     print(exc.detail.splitlines()[0])
invalid panel:

See also

PanelSyntaxError, which most document faults are. SolverError, for a document that is valid and impossible.

__init__(message, *, source=None)[source]#

Build the error, prefixing the source path when there is one.

Parameters:
  • message (str) – What went wrong, phrased for the person who wrote the document.

  • source (Path | None) – Path the document came from, if it was read from disk.

UnknownActorError#

Import

from scenet import UnknownActorError

Defined in

scenet.errors (source)

Install

pip install scenet

Since

0.13

Stability

Public: follows semantic versioning. Below 1.0, a minor release may change it, and the CHANGELOG says how.

exception scenet.errors.UnknownActorError[source]#

Bases: ScenetError, KeyError

A Panel Core asked for an actor or a speaker it does not hold.

Raised by PanelCore.actor and PanelCore.speaker. Also a KeyError, as a lookup miss has always been.

Note

KeyError stringifies as repr(args[0]), so str(exc) comes out quoted. Read exc.args[0] for the bare message.

Example

>>> from scenet import UnknownActorError, compile_source
>>> core = compile_source("cast: {a: {reference: alice}}").core
>>> try:
...     core.actor("b")
... except UnknownActorError as exc:
...     print(exc.args[0])
no actor 'b' in panel

See also

PanelCore.actors, every actor a panel holds.

UnknownExpressionError#

Import

from scenet import UnknownExpressionError

Defined in

scenet.errors (source)

Install

pip install scenet

Since

0.13

Stability

Public: follows semantic versioning. Below 1.0, a minor release may change it, and the CHANGELOG says how.

exception scenet.errors.UnknownExpressionError[source]#

Bases: AssetError, KeyError

A cast member’s expression naming one its puppet does not declare.

The counterpart of UnknownPoseError for PuppetSpec.expression_states, and deliberately identical in shape – an expression is selected by name exactly as a pose is.

Note

KeyError stringifies as repr(args[0]), so str(exc) comes out quoted. Read exc.args[0] for the bare message.

Example

>>> from scenet import UnknownExpressionError, compile_source
>>> try:
...     compile_source("cast: {a: {reference: alice, expression: smug}}")
... except UnknownExpressionError as exc:
...     print(type(exc).__name__)
UnknownExpressionError

See also

PuppetSpec.expression_states, which raises it.

UnknownPoseError#

Import

from scenet import UnknownPoseError

Defined in

scenet.errors (source)

Install

pip install scenet

Since

0.13

Stability

Public: follows semantic versioning. Below 1.0, a minor release may change it, and the CHANGELOG says how.

exception scenet.errors.UnknownPoseError[source]#

Bases: AssetError, KeyError

A cast member’s pose naming one its puppet does not declare.

Also a KeyError, for the same reason as UnknownPuppetError: a pose lookup has always failed this way, and PuppetSpec.pose_angles’s documented Raises: KeyError stays true. except KeyError keeps working; a caller that wants the rule and location this now carries catches UnknownPoseError (or AssetError) instead.

Note

KeyError stringifies as repr(args[0]), so str(exc) comes out quoted. Read exc.args[0] for the bare message.

Example

>>> from scenet import UnknownPoseError, compile_source
>>> try:
...     compile_source("cast: {a: {reference: alice, pose: cartwheel}}")
... except UnknownPoseError as exc:
...     print(type(exc).__name__)
UnknownPoseError

See also

PuppetSpec.pose_angles, which raises it.

UnknownPuppetError#

Import

from scenet import UnknownPuppetError

Defined in

scenet.errors (source)

Install

pip install scenet

Since

0.1

Stability

Public: follows semantic versioning. Below 1.0, a minor release may change it, and the CHANGELOG says how.

exception scenet.errors.UnknownPuppetError[source]#

Bases: AssetError, KeyError

A cast member referencing a puppet the library does not contain.

Also a KeyError, because that is what a lookup miss has always been, and because the library is a mapping in all but name.

Note

KeyError stringifies as repr(args[0]), so str(exc) comes out quoted. Read exc.args[0] for the bare message – which is what the CLI does.

Example

>>> from scenet import UnknownPuppetError, compile_source
>>> try:
...     compile_source("cast: {a: {reference: nobody}}")
... except UnknownPuppetError as exc:
...     print(exc.args[0])
unknown character 'nobody'; the library has ['alice', 'bob']

See also

PuppetLibrary.names, the puppets a library holds.