Native extension (types, VM)

Native extension module for Koskari

class koskari.lib.Arena

Bases: object

one chunk of a CodeAllocator’s storage for Code blocks, sealed read-only once filled

CHUNK = 65536

UNIT = 32

sealed

True once the arena has been sealed read-only

size

whole chunk units while open, the whole pages the code fills once sealed

Type:

mapped bytes

used

end of the newest reservation in bytes

class koskari.lib.AsyncGenerator

Bases: _KosEvaluated

Koskari async generator wrapper

aclose()

Close the async generator; returns an awaitable

asend(object, /)

Send a value into the async generator; returns an awaitable

athrow()

Throw an exception into the async generator; returns an awaitable

class koskari.lib.AttributeRef

Bases: Ref

attr

str; attribute name

clear()

R.clear() => None

deref()

R.deref() => V

empty

bool; whether this reference is empty

obj

object; object to reference attribute from

store(object, /)

R.store(V) => None

class koskari.lib.BoundMethod

Bases: _KosEvaluated

Bound method wrapper. Calls its function with self ahead of the call arguments.

class koskari.lib.Code

Bases: object

allocation_bytes

int; total allocated bytes for sealed bytecode storage

arena

owning Arena when the block lives in one, else None

cache_slots

int; number of per-site cache slots allocated on this code

caches

bool; whether per-site opcode caches are enabled for this code (gate)

code_bytes

int; bytes used by hardened instruction array

constant(object, /)

C.constant(index) => object

constants_pool

tuple; constants pool

cpool_bytes

int; bytes reserved for constant pool pointer array

expression(parent_ns)=> Expression (callable that returns Coroutine)

extent_bytes

int; bytes used by static extent descriptor table

extra_bytes

int; bytes used by extra operand rows

extra_tuple(object, /)

C.extra_tuple(index) => (a0, a1, a2, a3) for EXTRA opcode operand row

extras

Mutable dict for compiler/runtime metadata; update in place

filename

The source filename of this Code

function(formals, parent_ns)=> Function (callable that returns Coroutine)

function_spec(object, /)

C.function_spec(formals_spec) => FunctionSpec

length()

C.length() => int

name

The name of this Code

namespace_spec

The baseline NamespaceSpec required for this Code

oparg(index)=> (op, arg)

padding_bytes

int; alignment padding bytes between storage regions

page_rounding_bytes

int; tail padding bytes added by page-size rounding

payload_bytes

int; sum of logical region bytes before padding

position(index)=> (line, col)

position_bytes

int; bytes used by source position table

protected

bool; whether the unified block is sealed read-only with mprotect

soften()

C.soften() => list of (opcode, arg) pairs with LABEL/POSITION pseudo-ops and pool/label values restored

top_extent_bytes

int; bytes reserved for top-extent lookup table

uses_fast

bool; whether this code uses fast-slot opcodes at root namespace scope

yields

bool; whether this code will yield like a generator

class koskari.lib.CodeAllocator

Bases: object

CodeAllocator() => the arena chunks one module load places its function Code blocks into

chunks

tuple of the open chunks, in creation order; empty once sealed

seal()

C.seal() => tuple of Arena. Seal every chunk read-only and close the allocator; raises ValueError if already sealed

sealed

True once the allocator has been sealed

class koskari.lib.ConstantRef

Bases: Ref

clear()

R.clear() => <ValueError>

empty

bool; whether this reference is empty

name

str; name of this reference

store(object, /)

R.store(V) => <ValueError>

class koskari.lib.Context

Bases: object

An evaluator execution context: the dynamic chain, operand stacks, and namespaces of one running or suspended computation. Created by the runtime, never from Python.

dead

bool; the context completed or failed at its root

domain

The Domain this context resolves parameters against

namespace

The namespace the context is acting in, or None

running

bool; a drive is running on this context

snapshot() → dict

A picture of the context now: flags, suspension event, domain, the acting namespace, and one entry per dynamic chain node with its kind, namespace, operand stack, and payload.

suspension_event

int; why the last drive left the evaluator

class koskari.lib.Continuation

Bases: _KosEvaluated

Captured undelimited continuation

class koskari.lib.Coroutine

Bases: object

Koskari coroutine wrapper

close()

Close the coroutine

demand()

Run coroutine to completion from sync context on the demand path (no asyncio). Raises if the coroutine waits on a Python awaitable.

send(object, /)

Send a value into the coroutine

throw()

Throw an exception into the coroutine

koskari.lib.Datum

alias of datum

class koskari.lib.DatumFrame

Bases: dict

Capture dict with source provenance

position

Source position from the frame start, or None

source

Matched source represented by this capture frame

class koskari.lib.DelimitedContinuation

Bases: _KosEvaluated

Captured delimited continuation

class koskari.lib.Domain

Bases: object

Domain(): the owner of one root parameter scope. Each thread has a default Domain of its own; a with-Domain block supplies another for its extent, and a bare parameter store made inside it is read by every later call in the block and by no other.

classmethod current_domain()

Return the Domain answering on this thread: the running context’s, else the innermost with-Domain scope’s, else the thread default

get_contexts()

Return the Context objects running on this thread under this Domain, innermost first; Context.snapshot() pictures each one

classmethod get_stack()

Return the Context objects running on this thread under any Domain, innermost first; Context.snapshot() pictures each one with its dynamic chain

param_scopes()

Return {‘shadow’: {name: cell}, ‘root’: {name: cell}} for this Domain

class koskari.lib.DynamicRef

Bases: Ref

clear()

R.clear() => None

deref()

R.deref() => V

empty

bool; whether this reference is empty

store(object, /)

R.store(V) => None

class koskari.lib.EvaluatorToken

Bases: object

class koskari.lib.Expression

Bases: _KosEvaluated

Callable(Code, namespace). Calling with () returns a Coroutine.

code

ns

koskari.lib.Function

alias of function

class koskari.lib.FunctionSpec

Bases: object

code

KosCode for function

formals_spec

formals spec for function

name

name for function

class koskari.lib.ItemRef

Bases: Ref

clear()

R.clear() => None

deref()

R.deref() => V

empty

bool; whether this reference is empty

key

object; item key

obj

object; object to reference item from

store(object, /)

R.store(V) => None

koskari.lib.KosAccumulate

alias of accumulate

koskari.lib.KosBatched

alias of batched

koskari.lib.KosChain

alias of chain

koskari.lib.KosCompress

alias of compress

koskari.lib.KosCycle

alias of cycle

koskari.lib.KosDropWhile

alias of dropwhile

koskari.lib.KosFilter

alias of filter

koskari.lib.KosFilterFalse

alias of filterfalse

koskari.lib.KosISlice

alias of islice

koskari.lib.KosMap

alias of map

koskari.lib.KosPairwise

alias of pairwise

koskari.lib.KosPartial

alias of partial

koskari.lib.KosProperty

alias of property

koskari.lib.KosStarMap

alias of starmap

koskari.lib.KosTakeWhile

alias of takewhile

koskari.lib.KosZip

alias of zip

koskari.lib.KosZipLongest

alias of zip-longest

exception koskari.lib.KoskariContinuationApply

Bases: BaseException

exception koskari.lib.KoskariContinuationDead

Bases: RuntimeError

exception koskari.lib.KoskariContinuationError

Bases: BaseException

exception koskari.lib.KoskariSyncViolation

Bases: TypeError

class koskari.lib.MemoizedRef

Bases: Ref

deref()

R.deref() => V

empty

bool; whether this reference is empty

name

str; name of this reference

store(V)

class koskari.lib.Module(name, doc=None)

Bases: ModuleType

class koskari.lib.ModuleNamespace

Bases: dict

bind()

NS.bind(K, R) => None sets the reference for a binding in this namespace

bound(object, /)

NS.bound(K) => bool True if K is bound in this module, holding a value or not; builtins do not count

builtins

mappingproxy; the builtins a symbol falls through to when this module holds no value for it

clear(object, /)

NS.clear(K) => None removes the value from a binding in this namespace

copy()

NS.copy() => dict a plain dict of the names holding a value and their values

deref(K) → V

the value K holds in this module; NameError when K is unbound or empty, builtins not consulted

find(object, /)

NS.find(K) => R traverses this namespace and its parents to find and return a reference, or returns None if no binding is found

get(K[, default]) → V

the value K holds in this module, or default (None) when K is unbound or empty; builtins not consulted

items()

NS.items() => list of (name, value) pairs for the names holding a value

keys()

NS.keys() => list of the names holding a value

name

str; namespace name

parent

Namespace; parent namespace

pop(K[, default]) → V

the value K holds, emptying the binding; default, or KeyError without one, when K holds no value

raw(object, /)

NS.raw(K) => bool True if the given binding is currently raw in this namespace; a module binding never is

ref(K) → R

the Ref bound to K in this module; on a miss binds a fresh Ref holding the builtin of that name, or empty when there is none

refs

NamespaceRefs; the names bound in this namespace and their Refs

resolve(K[, default]) → V

what a symbol K evaluated in this module sees: its value here, else the builtin; NameError, or default when given, on a miss

setdefault(K[, default]) → V

the value K holds, else bind K to default (None) and return it

store()

NS.store(K, V) => None assigns a value to a binding in this namespace

update()

NS.update([mapping], **kwds) => None store every item into the module’s bindings

values()

NS.values() => list of the values held

class koskari.lib.NamespaceRefs

Bases: object

Read-only view of the refs bound in a namespace

items()

R.items() => list of (name, Ref) pairs for every bound name

keys()

R.keys() => list of every bound name, emptied bindings included

values()

R.values() => list of the Ref behind every bound name

class koskari.lib.ParamRef

Bases: Ref

clear()

R.clear() => None

deref()

R.deref() => V

empty

bool; whether this reference is empty in the active domain

name

str; name of this reference

store(object, /)

R.store(V) => None

class koskari.lib.Parameterize

Bases: object

Parameterize(bindings): a context manager binding the named parameters for the extent of a Python block

class koskari.lib.Ref

Bases: object

clear()

R.clear() => None

deref()

R.deref() => V

empty

bool; whether this reference is empty

name

str; name of this reference

store(object, /)

R.store(V) => None

class koskari.lib.WeakRef

Bases: Ref

clear()

R.clear() => None

deref()

R.deref() => V

empty

bool; whether this reference is empty

name

str; name of this reference

store(object, /)

R.store(V) => None

class koskari.lib.accumulate

Bases: _KosEvaluated

KosAccumulate(iterable, func=None, *, initial=None) - native lazy accumulate; iterable both asynchronously (ambient await, koskari-flattened) and synchronously (demand path)

aclose()

Close; returns an awaitable

asend(object, /)

Send a value into the step; returns an awaitable

athrow()

Throw an exception in; returns an awaitable

class koskari.lib.batched

Bases: _KosEvaluated

KosBatched(iterable, n) - native lazy batched; iterable both asynchronously (ambient await, koskari-flattened) and synchronously (demand path)

aclose()

Close; returns an awaitable

asend(object, /)

Send a value into the step; returns an awaitable

athrow()

Throw an exception in; returns an awaitable

koskari.lib.bracket_cons(head, *tail) → new bracket-pair

Like cons, but builds bracket-pair cells. No args implies bracket-nil.

koskari.lib.break_recursive(pair) → None

Set the first link whose cdr is the head to nil, breaking the cycle.

koskari.lib.build_class(name, bases, namespace, metaclass=None) → type

Build a class using Koskari class-construction semantics.

koskari.lib.build_dict(*pairs, **kwargs) → dict

Build a dict from (key, value) pairs and keyword arguments.

koskari.lib.build_list(*args) → list

Build a list from arguments.

koskari.lib.build_set(*args) → set

Build a set from arguments.

koskari.lib.build_str(*args) → str

Join the str of each argument; an exact str is taken as it is.

koskari.lib.build_tuple(*args) → tuple

Build a tuple from arguments.

koskari.lib.car(P) → object

Returns the head element of a koskari pair instance P.

koskari.lib.cdr(P) → object

Returns the tail element of a koskari pair instance P.

class koskari.lib.chain

Bases: _KosEvaluated

KosChain(*iterables) - native lazy chain; each iterable is acquired only when the one before it runs out. Iterable both asynchronously (ambient await, koskari-flattened) and synchronously (demand path)

aclose()

Close; returns an awaitable

asend(object, /)

Send a value into the step; returns an awaitable

athrow()

Throw an exception in; returns an awaitable

koskari.lib.clear_trace_counters()

Reset all compile-time trace counters/timers for enabled build features (same as module init/clear)

class koskari.lib.compress

Bases: _KosEvaluated

KosCompress(data, selectors) - native lazy compress; iterable both asynchronously (ambient await, koskari-flattened) and synchronously (demand path)

aclose()

Close; returns an awaitable

asend(object, /)

Send a value into the step; returns an awaitable

athrow()

Throw an exception in; returns an awaitable

koskari.lib.cons(head, *tail) → new pair

Build a pair chain from the given sequence. No tail implies nil.

class koskari.lib.cycle

Bases: _KosEvaluated

KosCycle(iterable) - native endless cycle; iterable both asynchronously (ambient await, koskari-flattened) and synchronously (demand path)

aclose()

Close; returns an awaitable

asend(object, /)

Send a value into the step; returns an awaitable

athrow()

Throw an exception in; returns an awaitable

class koskari.lib.datum

Bases: object

Matched value with optional KosPair source position and capture binding name

binding

Capture slot name (str) or None

car

Underlying datum car (delegates to pair)

cdr

Underlying datum cdr (delegates to pair)

datum

Matched value

position

Source position from enclosing pair cell, or None

class koskari.lib.defer

Bases: object

close()

send(object, /)

throw()

class koskari.lib.demand

Bases: _KosEvaluated

Callable adapter that runs its wrapped callable on the demand path

koskari.lib.demand_apply()

Invoke Koskari callable on the demand path with tuple and optional dict args

koskari.lib.demand_call()

Invoke Koskari callable synchronously without suspension

koskari.lib.deref(object, /)

deref(ref) => value Call ref.deref() to obtain the value held by the reference.

koskari.lib.drive_async_loop(coro) → result

Run coroutine without asyncio.Runner SIGINT handling

class koskari.lib.dropwhile

Bases: _KosEvaluated

KosDropWhile(pred, iterable) - native lazy dropwhile; iterable both asynchronously (ambient await, koskari-flattened) and synchronously (demand path)

aclose()

Close; returns an awaitable

asend(object, /)

Send a value into the step; returns an awaitable

athrow()

Throw an exception in; returns an awaitable

class koskari.lib.filter

Bases: _KosEvaluated

KosFilter(func, iterable) - native lazy filter; a None func keeps truthy elements; iterable both asynchronously (ambient await, koskari-flattened) and synchronously (demand path)

aclose()

Close; returns an awaitable

asend(object, /)

Send a value into the step; returns an awaitable

athrow()

Throw an exception in; returns an awaitable

class koskari.lib.filterfalse

Bases: filter

KosFilterFalse(func, iterable) - native lazy filterfalse; keeps what filter would drop. A None func keeps falsey elements

class koskari.lib.function

Bases: _KosEvaluated

Callable(Code, base_namespace, FormalsSpec). Calling with (*args, **kwargs) binds formals and returns a Coroutine.

closures

code

formals

name

koskari.lib.get_trace_report()

Return a dict of compile-time tracing report (flags and per-feature data)

koskari.lib.getattr_star(obj, attrlist[, default]) → value

Chained attribute access through attrlist; optional default on AttributeError.

koskari.lib.getitem_star(obj, keylist[, default]) → value

Chained item access through keylist; optional default on LookupError.

koskari.lib.hasattr_star(obj, attrlist) → bool

Chained attribute presence test; false on first failed step.

koskari.lib.hasitem_star(obj, keylist) → bool

Chained item presence test; false on first failed step.

koskari.lib.identity(value) → value

Returns its argument unchanged.

koskari.lib.in()

(in VAL CONTAINER)

class koskari.lib.islice

Bases: _KosEvaluated

KosISlice(iterable, stop) or KosISlice(iterable, start, stop[, step]) - native lazy islice; iterable both asynchronously (ambient await, koskari-flattened) and synchronously (demand path)

aclose()

Close; returns an awaitable

asend(object, /)

Send a value into the step; returns an awaitable

athrow()

Throw an exception in; returns an awaitable

koskari.lib.kos_repr(obj) → str

Koskari-style string: str uses double quotes; then type registry; then __kos_repr__; otherwise repr(obj).

koskari.lib.kos_repr_register(type, handler) → None

Register a type-to-callable mapping for kos_repr. Handler receives the object and must return str.

koskari.lib.kos_repr_registry_clear() → None

Clear all kos_repr type registry entries.

koskari.lib.kos_repr_registry_snapshot() → dict

Return a shallow copy of the type registry for inspection.

koskari.lib.kos_repr_unregister(type) → None

Remove a type from the kos_repr registry if present.

koskari.lib.list_append(list, item) → None

Append item to list; TypeError when list is not a list.

koskari.lib.make_recursive(pair) → None

Set the tail-most link’s cdr to the head, making the chain circular.

class koskari.lib.map

Bases: _KosEvaluated

KosMap(func, iterable, *iterables) - native lazy map; func takes one element from each iterable per step and the shortest iterable ends it; iterable both asynchronously (ambient await, koskari-flattened) and synchronously (demand path)

aclose()

Close; returns an awaitable

asend(object, /)

Send a value into the step; returns an awaitable

athrow()

Throw an exception in; returns an awaitable

koskari.lib.nilp(value) → bool

True if value is an empty-list singleton (nil or bracket-nil).

class koskari.lib.pairwise

Bases: _KosEvaluated

KosPairwise(iterable) - native lazy pairwise; iterable both asynchronously (ambient await, koskari-flattened) and synchronously (demand path)

aclose()

Close; returns an awaitable

asend(object, /)

Send a value into the step; returns an awaitable

athrow()

Throw an exception in; returns an awaitable

koskari.lib.parameter()

parameter(name, default=…) => value Resolve the value bound to name: the enclosing parameterize extent first, then the root scope. Creates nothing and writes nothing. If unbound, return default when provided, otherwise raise NameError.

class koskari.lib.partial

Bases: _KosEvaluated

KosPartial(func, *args, **keywords) - native KosCallable with the behavior of functools.partial

args

tuple of arguments to future partial calls

func

function object to use in future partial calls

keywords

dictionary of keyword arguments to future partial calls

class koskari.lib.property(fget=None, fset=None, fdel=None, doc=None)

Bases: property

koskari.lib.reapply(func, data, count) → result

Calls data = func(data) count times, returns final result.

koskari.lib.setcar(P, obj) → None

Assigns the head element of a koskari pair instance P to obj.

koskari.lib.setcdr(P, obj) → None

Assigns the tail element of a koskari pair instance P to obj.

class koskari.lib.starmap

Bases: _KosEvaluated

KosStarMap(func, iterable) - native lazy starmap; iterable both asynchronously (ambient await, koskari-flattened) and synchronously (demand path)

aclose()

Close; returns an awaitable

asend(object, /)

Send a value into the step; returns an awaitable

athrow()

Throw an exception in; returns an awaitable

class koskari.lib.takewhile

Bases: _KosEvaluated

KosTakeWhile(pred, iterable) - native lazy takewhile; iterable both asynchronously (ambient await, koskari-flattened) and synchronously (demand path)

aclose()

Close; returns an awaitable

asend(object, /)

Send a value into the step; returns an awaitable

athrow()

Throw an exception in; returns an awaitable

class koskari.lib.values

Bases: _KosEvaluated

keys()

class koskari.lib.zip

Bases: _KosEvaluated

KosZip(*iterables) - native lazy zip; iterable both asynchronously (ambient await, koskari-flattened) and synchronously (demand path)

aclose()

Close; returns an awaitable

asend(object, /)

Send a value into the step; returns an awaitable

athrow()

Throw an exception in; returns an awaitable