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 |
|
Defined in |
|
Install |
|
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:
ScenetErrorA puppet or a font that is missing, unreadable or self-inconsistent.
Not itself a
ValueError: a puppet the library does not hold is aUnknownPuppetError, aKeyError, and anexcept ValueErrorwritten for bad values should not catch a lookup miss. A file that is there and wrong is aMalformedAssetError, which is aValueError.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 |
|
Defined in |
|
Install |
|
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:
SolverErrorNo 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-placementis 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 |
|
Defined in |
|
Install |
|
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:
SourceErrorA
panels:document whoseover:inheritance cannot be resolved.Raised for a panel inheriting from one that does not exist, and for a cycle –
aoverbovera– 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 wholepanels:block.
See also
compile_scene, which resolvesover:.
CoreSyntaxError#
Import |
|
Defined in |
|
Install |
|
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:
SourceErrorA Panel Core or Page Core document that does not read back.
Raised by
PanelCore.from_jsonandPageCore.from_jsonfor 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.JSONDecodeErrorand pydantic’sValidationError.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 |
|
Defined in |
|
Install |
|
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,OSErrorA 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_puppetand the rest – when the system refuses to read it. A file a document names, beside it, is the document’s fault instead: aPanelSyntaxErrorthat says where it was named.Also an
OSError, carrying what the system said:errno,strerrorandfilenameare those of the system’s own error, which is kept as__cause__. A file that is not there at all is aMissingFileError, which is also aFileNotFoundError.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:
- Returns:
A
MissingFileErrorfor a file that is not there, and aFileReadErrorfor any other reason.
LayoutError#
Import |
|
Defined in |
|
Install |
|
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:
SolverErrorA 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 |
|
Defined in |
|
Install |
|
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,ValueErrorA 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’sValidationError, and a font with no character map a plainValueError.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
Nonefor 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.
MissingFileError#
Import |
|
Defined in |
|
Install |
|
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,FileNotFoundErrorA file a call names that is not there.
Also a
FileNotFoundError, which is what reading it raised before, so anexcept FileNotFoundErroraround 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 |
|
Defined in |
|
Install |
|
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:
SourceErrorA 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 reachscenet checkasinvalid-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
locform: in a scene, it starts withpanelsand the panel’s name. Empty means the document as a whole. When validation found several faults, the message lists each, andruleandlocare 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 catalogueruleis 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 |
|
Defined in |
|
Install |
|
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,ValueErrorA 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=orimages=;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.fontsandBook.images, what a renderer is handed back.
ScenetError#
Import |
|
Defined in |
|
Install |
|
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:
ExceptionRoot 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
ValueErrorfrom 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.
ScriptSyntaxError#
Import |
|
Defined in |
|
Install |
|
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:
PanelSyntaxErrorA comic script that could not be parsed.
A subclass of
PanelSyntaxErrorrather 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.
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.
SfxPlacementError#
Import |
|
Defined in |
|
Install |
|
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:
SolverErrorNo 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. Rulesfx-placement.Example
>>> from scenet import SfxPlacementError, SolverError >>> issubclass(SfxPlacementError, SolverError) True
See also
SfxEvent, whosesizeis usually the fix.
SolverError#
Import |
|
Defined in |
|
Install |
|
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,ValueErrorA document that is valid but cannot be laid out.
The distinction from
SourceErrormatters: 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,BalloonPlacementErrorandSfxPlacementError, its three kinds.
SourceError#
Import |
|
Defined in |
|
Install |
|
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,ValueErrorA 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
Nonefor 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.
UnknownActorError#
Import |
|
Defined in |
|
Install |
|
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,KeyErrorA Panel Core asked for an actor or a speaker it does not hold.
Raised by
PanelCore.actorandPanelCore.speaker. Also aKeyError, as a lookup miss has always been.Note
KeyErrorstringifies asrepr(args[0]), sostr(exc)comes out quoted. Readexc.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 |
|
Defined in |
|
Install |
|
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,KeyErrorA cast member’s
expressionnaming one its puppet does not declare.The counterpart of
UnknownPoseErrorforPuppetSpec.expression_states, and deliberately identical in shape – an expression is selected by name exactly as a pose is.Note
KeyErrorstringifies asrepr(args[0]), sostr(exc)comes out quoted. Readexc.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 |
|
Defined in |
|
Install |
|
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,KeyErrorA cast member’s
posenaming one its puppet does not declare.Also a
KeyError, for the same reason asUnknownPuppetError: a pose lookup has always failed this way, andPuppetSpec.pose_angles’s documentedRaises: KeyErrorstays true.except KeyErrorkeeps working; a caller that wants the rule and location this now carries catchesUnknownPoseError(orAssetError) instead.Note
KeyErrorstringifies asrepr(args[0]), sostr(exc)comes out quoted. Readexc.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 |
|
Defined in |
|
Install |
|
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,KeyErrorA 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
KeyErrorstringifies asrepr(args[0]), sostr(exc)comes out quoted. Readexc.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.