Exceptions

koskari.exceptions

Base exception classes for Koskari.

exception koskari.exceptions.CodeBoundary

Bases: Exception

Marks a boundary between infrastructure and evaluated user code.

The cause holds the user-visible exception. Display formatters unwrap the boundary and omit infrastructure frames unless nofold is requested.

exception koskari.exceptions.CompilerError(message, source=None, position=None, filename=None)

Bases: KoskariException

Base class for compile-phase errors

attach_position(position=None, filename=None)

Fill in a position and a filename the raise site did not have: the innermost enclosing form’s position and the compiler’s file. What the error already carries is kept

explain()

User-facing error text for REPL and similar UIs

exception koskari.exceptions.FenceError(message, source=None, position=None, filename=None)

Bases: CompilerError

Fence expansion and foreign-source parse errors

exception koskari.exceptions.FormatStringSyntaxError(message, location=None, filename=None, text=None)

Bases: ReaderSyntaxError

Errors in format string (f-string) syntax

exception koskari.exceptions.KoskariContinuationError(message, prompt_id=None, operation=None)

Bases: KoskariException

Base class for continuation capture and transfer errors.

The catch target for the whole category. Deliberately not a RuntimeError subclass: an overbroad except RuntimeError around a continuation-using call must not silently swallow these

exception koskari.exceptions.KoskariException

Bases: Exception

Base class for error-driven Exceptions raised by Koskari.

exception koskari.exceptions.KoskariPromptNotFound(message, prompt_id=None, operation=None)

Bases: KoskariContinuationError

No prompt matching the requested id exists on the dynamic chain.

The construct in operation (shift) has no enclosing delimiter; establish one. prompt_id identifies the delimiter the capture was seeking, letting a library recognize a failure against its own delimiter and leave foreign failures alone

exception koskari.exceptions.KoskariPromptUnreachable(message, prompt_id=None, operation=None, boundary=None)

Bases: KoskariContinuationError

A matching prompt exists but a crossed node denied capture.

Adding a delimiter will not help; the region between the capture point and the delimiter must be restructured. boundary describes the denying node (for example a generator boundary)

exception koskari.exceptions.KoskariSyncViolation

Bases: TypeError

exception koskari.exceptions.KoskariSyntaxError(message, location=None, filename=None, text=None)

Bases: SyntaxError, KoskariException

An error in Koskari syntax, either during read or compile time.

explain()

User-facing error text for REPL and similar UIs

locate(filename, location=None, text=None)

Give the error the file, position and source text that name where it happened, the way SyntaxError prints them. Fills what the raise site did not have: a location or text the error already carries is kept

exception koskari.exceptions.LayoutError(message, location=None, filename=None, text=None)

Bases: ReaderError

Layout block structure errors

exception koskari.exceptions.NotYetImplemented

Bases: KoskariException

Raised as a placeholder for features that have not been implemented yet.

exception koskari.exceptions.ParametersError(message, source=None, position=None, filename=None)

Bases: CompilerError

Call-site parameter errors from koskari.compile.helpers.gather_parameters() validation

exception koskari.exceptions.ReaderEOF(message, location=None, filename=None, text=None)

Bases: ReaderError

Stream ended before a delimited or quoted form finished reading.

Distinct from top-level READ_EOF (no form started). REPL callers may treat this as incomplete input; file loaders should surface it as an error.

exception koskari.exceptions.ReaderError(message, location=None, filename=None, text=None)

Bases: KoskariSyntaxError

Base class for reader-phase errors

exception koskari.exceptions.ReaderSyntaxError(message, location=None, filename=None, text=None)

Bases: ReaderError

Low-level parse errors during s-expression or layout reading

exception koskari.exceptions.SpecialError(message, source=None, position=None, filename=None)

Bases: CompilerError

Special-form validation errors

exception koskari.exceptions.SyntaxMatchError(message, source=None, position=None, filename=None, *, syntax=None, patterns=None)

Bases: SpecialError

Syntax dispatch errors when no matcher arm matches the source form

explain()

User-facing error text for REPL and similar UIs

exception koskari.exceptions.UncaughtCompilerError(message, source=None, position=None, filename=None)

Bases: CompilerError

Wraps unexpected exceptions raised during compilation

koskari.exceptions.apply_sys_last_exc(exc_type, exc_val, tb=None)

Set sys.last_type, sys.last_value, and sys.last_traceback for REPL/debug

Parameters:

• exc_type – exception type

• exc_val – exception instance

• tb – traceback object or None

koskari.exceptions.format_code_boundary_exception(boundary, *, nofold=False, infrastructure_modules=None)

Format an exception behind a CodeBoundary wrapper

Unwraps boundary.__cause__ for display. Unless nofold is True, omits infrastructure frames from the cause traceback per infrastructure_modules. When nofold is True, includes the boundary wrapper traceback before the cause.

Parameters:

• boundary – CodeBoundary instance (e.g. REPLCodeBoundary)

• nofold – when True, inline the boundary wrapper traceback

• infrastructure_modules – module __name__ values to strip from cause tb

Returns:

(lines, exc_type, exc_val, tb) for sys.last_* and printing

koskari.exceptions.format_exception_with_koskari_trace(exc_type, exc_val, tb)

Format an exception traceback, rendering the koskari native frames where they sit

A synthetic native frame carries its own dynchain entry as __koskari_trace__, so one walk of the traceback renders every frame in order: a native frame from its entry, with the source line and column caret, any other frame as the standard traceback does. The frames of a raise that crossed Koskari, Python and Koskari again therefore print in their true nesting

Returns:

list[str], matching traceback.format_exception style

koskari.exceptions.format_run_exception(exc_val, *, full_trace=False, infrastructure_modules=frozenset({'asyncio', 'asyncio.base_events', 'asyncio.events', 'asyncio.runners', 'concurrent.futures', 'concurrent.futures._base', 'koskari.cli', 'koskari.importer', 'koskari.launcher', 'koskari.module'}))

Format an uncaught exception from a non-interactive CLI run

Mirrors the boundary cleaning the REPL applies per form, but for a single top-level run (a file, -c command, or .kio). Reader and compile errors render their own source-annotated explanation; runtime errors have infrastructure frames stripped (per infrastructure_modules) and their koskari frames rendered where they sit

When full_trace is True the raw traceback is kept and no filtering is applied, for debugging the runtime itself

Parameters:

• exc_val – the uncaught exception instance

• full_trace – when True, keep infrastructure frames

• infrastructure_modules – module __name__ values to strip

Returns:

(lines, tb) where lines is list[str] of traceback text and tb is the traceback to record via apply_sys_last_exc