ORIONIS API REFERENCE

THE ORIONIS API

Build with clarity.

Explore the building blocks of an async-first Python framework. Every module, class, and method — connected, searchable, and ready to build with.

class documentation

class BootstrapEditor: (source)

Constructor: BootstrapEditor(path, base_path)

View In Hierarchy

Plan surgical Python edits and publish them without clobbering changes.

The editor deliberately does not execute user code. Unsupported or ambiguous construction flows fail before any file is changed.

Static Method _isConstructor Identify an application constructor beneath chained builder calls.
Static Method _rootName Resolve the named receiver beneath a fluent method-call chain.
Static Method _routingValue Find a context argument in a supported routing call.
Static Method _scopeNodes Walk a lexical scope without entering unrelated nested definitions.
Method __init__ Initialize a source-preserving application bootstrap edit session.
Method _after Plan an insertion after a standalone statement.
Method _appendKeyword Extend a routing argument list while retaining its source layout.
Method _applicationNames Collect supported application constructor and module aliases.
Method _argumentTail Find grouping parentheses beyond a positional argument AST node.
Method _before Plan an insertion before a statement and its leading comments.
Method _callbackImport Extend the visible import block without adding an empty import group.
Method _calls Collect editable calls to an application builder method.
Method _checkAssignments Reject application reassignments that obscure the selected receiver.
Method _checkIndirectRouting Reject later helpers that can replace the selected routing setup.
Method _checkRoutingOrder Reject routing configuration placed after application initialization.
Method _edited Apply planned source edits and validate the resulting Python module.
Method _end Locate the source character immediately after a syntax node.
Method _findApplication Locate the unique named application construction assignment.
Method _freshCallbackName Choose an unused callback import name in the application scope.
Method _hasLifespanRegistration Detect existing callback registration for the selected application.
Method _helperApplicationParameters Identify helper names that can reference the selected application.
Method _helperReplacesRouting Detect routing mutations through helper parameters or closures.
Method _importModule Resolve an import node to its absolute application module path.
Method _initializerCalls Collect fluent calls that construct the named application.
Method _lifespanBindings Recognize visible direct and module imports for lifespan callbacks.
Method _pathLiteral Encode a route path as a project-relative Python string literal.
Method _position Translate an AST byte position into a source character offset.
Method _registration Plan registration before application initialization or factory return.
Method _routingCall Find the final directly editable application routing call.
Method _start Locate the first source character belonging to a syntax node.
Method _statement Find the enclosing statement in the application construction scope.
Method commit Publish validated source atomically while preserving concurrent edits.
Method encode Encode planned source using the original coding cookie and BOM.
Method lifespan Import and register application callbacks before initialization.
Method routePaths Read literal route paths from the effective routing configuration.
Method routing Register a missing route context while preserving other arguments.
Instance Variable _lines Lines produced by self.source.splitlines.
Instance Variable _nodes Nodes produced by list.
Instance Variable _offsets Character offsets used to translate source positions into edit ranges.
Instance Variable _original Original produced by self.path.read_bytes.
Instance Variable _parents Parent node associated with each node in the parsed syntax tree.
Instance Variable app_name Assignment produced by self._findApplication.
Instance Variable assignment Assignment produced by self._findApplication.
Instance Variable base_path Application root used for relative route and import paths.
Instance Variable body HTTP response body or encoded payload returned to the client.
Instance Variable encoding Encoding produced by tokenize.detect_encoding.
Instance Variable newline Newline sequence preserved when rewriting the source file.
Instance Variable path Bootstrap Python module to inspect.
Instance Variable scope Dependency-injection scope associated with the current operation.
Instance Variable source Source produced by self._original.decode.
Instance Variable tree Tree produced by ast.parse.
Property hasRouting Report whether the application exposes a directly editable routing call.
def _isConstructor(node: ast.AST, constructors: set[str], modules: set[str]) -> bool: (source)

Identify an application constructor beneath chained builder calls.

Parameters
node:ast.ASTExpression to inspect.
constructors:set[str]Recognized direct application constructor names.
modules:set[str]Recognized imported application module names.
Returns
boolReturn whether the expression constructs the application.
def _rootName(node: ast.AST | None) -> str | None: (source)

Resolve the named receiver beneath a fluent method-call chain.

Parameters
node:ast.AST | NoneExpression to inspect, or None when no expression exists.
Returns
str | NoneReturn the receiver name, or None for an unnamed expression.
def _routingValue(call: ast.Call, context: str) -> ast.AST | None: (source)

Find a context argument in a supported routing call.

Parameters
call:ast.CallRouting call to inspect.
context:strRuntime context whose route argument is needed.
Returns
ast.AST | NoneReturn the argument expression, or None when it is absent.
def _scopeNodes(scope: ast.AST) -> Iterator[ast.AST]: (source)

Walk a lexical scope without entering unrelated nested definitions.

Parameters
scope:ast.ASTLexical scope or descendant node to traverse.
Returns
NoneFinish traversal without returning a value.
Yields
ast.ASTEmit nodes from the selected lexical scope.
def __init__(self, path: Path, base_path: Path): (source)

Initialize a source-preserving application bootstrap edit session.

Parameters
path:pathlib.PathBootstrap Python module to inspect.
base_path:pathlib.PathApplication root used for relative route and import paths.
Returns
NoneStore the original source, syntax tree, and application binding.
def _after(self, statement: ast.stmt, lines: list[str], *, separate: bool = True) -> tuple[int, int, str]: (source)

Plan an insertion after a standalone statement.

Parameters
statement:ast.stmtStandalone statement that precedes the inserted lines.
lines:list[str]Unindented source lines to insert.
separate:boolWhether to separate the insertion with a leading blank line.
Returns
tuple[int, int, str]Return the insertion offsets and correctly indented source text.
def _appendKeyword(self, call: ast.Call, context: str, literal: str) -> str: (source)

Extend a routing argument list while retaining its source layout.

Parameters
call:ast.CallRouting call whose argument list must be extended.
context:strRuntime context to add as a keyword argument.
literal:strValidated Python literal representing the route paths.
Returns
strReturn updated source with the additional routing keyword.
def _applicationNames(self) -> tuple[set[str], set[str]]: (source)

Collect supported application constructor and module aliases.

Returns
tuple[set[str], set[str]]Return constructor names and imported application module names.
def _argumentTail(self, last: ast.AST, call_end: int) -> tuple[int, bool]: (source)

Find grouping parentheses beyond a positional argument AST node.

Parameters
last:ast.ASTFinal argument node in the routing call.
call_end:intCharacter offset immediately before the closing parenthesis.
Returns
tuple[int, bool]Return the complete argument end offset and trailing-comma presence.
def _before(self, statement: ast.stmt, lines: list[str]) -> tuple[int, int, str]: (source)

Plan an insertion before a statement and its leading comments.

Parameters
statement:ast.stmtStandalone statement that follows the inserted lines.
lines:list[str]Unindented source lines to insert.
Returns
tuple[int, int, str]Return the insertion offsets and correctly indented source text.
def _callbackImport(self, import_line: str) -> tuple[int, int, str]: (source)

Extend the visible import block without adding an empty import group.

Parameters
import_line:strCallback import to insert in the application construction scope.
Returns
tuple[int, int, str]Return insertion offsets and source with existing spacing preserved.
def _calls(self, method: str) -> list[ast.Call]: (source)

Collect editable calls to an application builder method.

Parameters
method:strApplication method name to locate.
Returns
list[ast.Call]Return matching calls ordered by their source end offsets.
def _checkAssignments(self): (source)

Reject application reassignments that obscure the selected receiver.

Returns
NoneComplete validation without changing the application source.
def _checkIndirectRouting(self, routing: ast.Call | None): (source)

Reject later helpers that can replace the selected routing setup.

Parameters
routing:ast.Call | NoneSelected routing call, or None when registration is absent.
Returns
NoneComplete validation without changing the application source.
def _checkRoutingOrder(self, call: ast.Call): (source)

Reject routing configuration placed after application initialization.

Parameters
call:ast.CallRouting call whose initialization order must be validated.
Returns
NoneComplete validation without changing the application source.
def _edited(self, edits: list[tuple[int, int, str]]) -> str: (source)

Apply planned source edits and validate the resulting Python module.

Parameters
edits:list[tuple[int, int, str]]Start offsets, exclusive end offsets, and replacement text.
Returns
strReturn syntactically valid source in the original encoding.
def _end(self, node: ast.AST) -> int: (source)

Locate the source character immediately after a syntax node.

Parameters
node:ast.ASTSyntax node with complete source location information.
Returns
intReturn the exclusive end offset in the original source.
def _findApplication(self) -> tuple[ast.Assign | ast.AnnAssign, str]: (source)

Locate the unique named application construction assignment.

Returns
tuple[ast.Assign | ast.AnnAssign, str]Return the assignment node and its application variable name.
def _freshCallbackName(self) -> str: (source)

Choose an unused callback import name in the application scope.

Returns
strReturn the standard callback name or a collision-free generated alias.
def _hasLifespanRegistration(self, names: set[str], modules: set[str], custom_names: set[str]) -> bool: (source)

Detect existing callback registration for the selected application.

Parameters
names:set[str]Directly imported names for the requested callback function.
modules:set[str]Imported modules that expose the callback function.
custom_names:set[str]Custom callback names whose registrations are preserved.
Returns
boolReturn whether an unambiguous callback registration already exists.
def _helperApplicationParameters(self, helper: ast.FunctionDef | ast.AsyncFunctionDef, call: ast.Call) -> set[str]: (source)

Identify helper names that can reference the selected application.

Parameters
helper:ast.FunctionDef | ast.AsyncFunctionDefHelper definition whose argument bindings are inspected.
call:ast.CallInvocation that can pass the selected application.
Returns
set[str]Return parameter and closure names that can reference the application.
def _helperReplacesRouting(self, helper: ast.FunctionDef | ast.AsyncFunctionDef, parameters: set[str]) -> bool: (source)

Detect routing mutations through helper parameters or closures.

Parameters
helper:ast.FunctionDef | ast.AsyncFunctionDefHelper definition to inspect within its lexical scope.
parameters:set[str]Names that can still reference the application instance.
Returns
boolReturn whether the helper can replace application routing.
def _importModule(self, node: ast.ImportFrom) -> str | None: (source)

Resolve an import node to its absolute application module path.

Parameters
node:ast.ImportFromImport-from node whose module path must be resolved.
Returns
str | NoneReturn the dotted module path, or None for an invalid relative import.
def _initializerCalls(self) -> set[ast.Call]: (source)

Collect fluent calls that construct the named application.

Returns
set[ast.Call]Return the calls in the application assignment value chain.
def _lifespanBindings(self, module: str) -> tuple[set[str], set[str], set[str]]: (source)

Recognize visible direct and module imports for lifespan callbacks.

Parameters
module:strDotted module path that supplies the generated callbacks.
Returns
tuple[set[str], set[str], set[str]]Return direct names, module names, and custom callback names.
def _pathLiteral(self, path: Path) -> str: (source)

Encode a route path as a project-relative Python string literal.

Parameters
path:pathlib.PathEffective route file path to represent.
Returns
strReturn a quoted relative path, or an absolute path outside the root.
def _position(self, lineno: int, byte_column: int) -> int: (source)

Translate an AST byte position into a source character offset.

Parameters
lineno:intOne-based source line number.
byte_column:intZero-based UTF-8 byte column from the AST.
Returns
intReturn the absolute character offset in the original source.
def _registration(self, lines: list[str]) -> list[tuple[int, int, str]]: (source)

Plan registration before application initialization or factory return.

Parameters
lines:list[str]Unindented registration source lines to insert.
Returns
list[tuple[int, int, str]]Return source edits that preserve the initialization order.
def _routingCall(self) -> ast.Call | None: (source)

Find the final directly editable application routing call.

Returns
ast.Call | NoneReturn the effective routing call, or None when it is absent.
def _start(self, node: ast.AST) -> int: (source)

Locate the first source character belonging to a syntax node.

Parameters
node:ast.ASTSyntax node with source location information.
Returns
intReturn the absolute start offset in the original source.
def _statement(self, node: ast.AST) -> ast.stmt: (source)

Find the enclosing statement in the application construction scope.

Parameters
node:ast.ASTDescendant syntax node whose enclosing statement is needed.
Returns
ast.stmtReturn the statement that belongs directly to the selected scope.
def commit(self, source: str | None) -> bool: (source)

Publish validated source atomically while preserving concurrent edits.

Retry Windows access and sharing failures with bounded backoff, checking for concurrent source changes before each replacement attempt.

Parameters
source:str | NonePlanned source, or None when no update is required.
Returns
boolReturn whether updated source was written to the bootstrap module.
def encode(self, source: str) -> bytes: (source)

Encode planned source using the original coding cookie and BOM.

Parameters
source:strValidated Python source to encode.
Returns
bytesReturn source bytes in the original bootstrap encoding.
def lifespan(self, lifespan_path: Path) -> str | None: (source)

Import and register application callbacks before initialization.

Parameters
lifespan_path:pathlib.PathEffective Python module containing lifespan callbacks.
Returns
str | NoneReturn updated source, or None when callbacks are already registered.
def routePaths(self, context: str) -> list[str] | None: (source)

Read literal route paths from the effective routing configuration.

Parameters
context:strRuntime context whose configured paths are needed.
Returns
list[str] | NoneReturn literal paths, an empty list if unset, or None if dynamic.
def routing(self, context: str, route_path: Path | list[Path], *, registered: bool = False) -> str | None: (source)

Register a missing route context while preserving other arguments.

Parameters
context:strRuntime context to register.
route_path:pathlib.Path | list[pathlib.Path]Effective route file path or paths to register.
registered:boolWhether runtime paths confirm a dynamic registration.
Returns
str | NoneReturn updated source, or None when the context is already enabled.

Lines produced by self.source.splitlines.

Nodes produced by list.

_offsets: list[int] = (source)

Character offsets used to translate source positions into edit ranges.

_original = (source)

Original produced by self.path.read_bytes.

_parents = (source)

Parent node associated with each node in the parsed syntax tree.

app_name = (source)

Assignment produced by self._findApplication.

assignment = (source)

Assignment produced by self._findApplication.

base_path = (source)

Application root used for relative route and import paths.

HTTP response body or encoded payload returned to the client.

encoding = (source)

Encoding produced by tokenize.detect_encoding.

Newline sequence preserved when rewriting the source file.

Bootstrap Python module to inspect.

Dependency-injection scope associated with the current operation.

Source produced by self._original.decode.

Tree produced by ast.parse.

Report whether the application exposes a directly editable routing call.

Returns
boolReturn whether a supported routing call exists.