Context API#

Context objects and helpers control backend, dtype, and validation behavior.

`spacecore.backend.Context`	Backend execution context for SpaceCore objects.
`spacecore.set_context`	Set the process-wide default SpaceCore context.
`spacecore.get_context`	Return the current process-wide default SpaceCore context.
`spacecore.resolve_context_priority`	Resolve the context assigned to a newly created object.
`spacecore.register_ops`	Register a backend operations implementation.
`spacecore.set_resolution_policy`	Set the policy for cross-backend context conversion.
`spacecore.set_dtype_resolution_policy`	Set the policy for dtype handling during context conversion.

Context#

class spacecore.backend.Context(ops, dtype=None, enable_checks=True)[source]#

Bases: object

Backend execution context for SpaceCore objects.

A context collects the backend operations object, default dtype, and runtime validation policy used by spaces, linear operators, and context-bound values. It is intentionally small: it does not own arrays, but it defines how new arrays are created and how existing arrays are checked or converted for a backend family.

Parameters:

ops (spacecore.backend._ops.BackendOps) – Backend operations implementation. This must be an instance of spacecore.backend.BackendOps, such as spacecore.backend.NumpyOps or spacecore.backend.JaxOps.
dtype (Any | None) – Default dtype used by asarray() and assparse(). The value is normalized through ops.sanitize_dtype during initialization.
enable_checks (bool) – Whether spaces and linear operators using this context should perform membership and compatibility checks before operations.

Notes

Context is frozen and slot-based. Methods that convert values return new backend arrays or sparse objects; they do not mutate the context itself.

Equality compares backend family and enable_checks. It currently does not compare dtype.

ops: BackendOps#

dtype: Any | None#

enable_checks: bool#

assert_dense(x)[source]#

Return x after verifying that it is a dense array for this backend.

Parameters:: x (Any) – Object to validate.
Returns:: The original object, typed as a dense array.
Return type:: DenseArray
Raises:: TypeError – If x is not recognized as a dense array by self.ops.

assert_sparse(x)[source]#

Return x after verifying that it is a sparse array for this backend.

Parameters:: x (Any) – Object to validate.
Returns:: The original object, typed as a sparse array.
Return type:: SparseArray
Raises:: TypeError – If the backend does not allow sparse arrays or if x is not recognized as a sparse array by self.ops.

asarray(x)[source]#

Convert x to a dense backend array using this context’s dtype.

Parameters:: x (Any) – Array-like object accepted by the backend implementation.
Returns:: Backend-native dense array with dtype self.dtype.
Return type:: DenseArray

assparse(x)[source]#

Convert x to a sparse backend object using this context’s dtype.

Parameters:: x (Any) – Array-like or sparse object accepted by the backend implementation.
Returns:: Backend-native sparse object with dtype self.dtype.
Return type:: SparseArray
Raises:: TypeError – If the backend implementation does not support sparse conversion.

convert(x)[source]#

Convert an existing backend array to this context.

Dense inputs are converted with asarray(); sparse inputs are converted with assparse().

Parameters:: x (Any) – Dense or sparse backend array recognized by self.ops.
Returns:: Converted dense or sparse backend object.
Return type:: ArrayLike
Raises:: NotImplementedError – If x is neither dense nor sparse according to this backend.

Context helpers#

spacecore.set_context(ctx=None, dtype=None, enable_checks=None)[source]#

Set the process-wide default SpaceCore context.

Parameters:

ctx (Context | BackendFamily | str | None) – Context specification to make default. This may be a concrete spacecore.backend.Context, a backend family enum, a backend family string such as "numpy" or "jax", or None.
dtype (Any) – Optional dtype used when ctx is a backend family string or enum. Ignored when ctx is None or already a concrete Context.
enable_checks (bool | None) – Optional validation flag used when constructing a context from a backend family. Ignored when ctx is None or already a concrete Context.

Return type:

None

Notes

Objects created without an explicit context use this default context. Existing spaces, operators, and contexts are not modified.

spacecore.get_context()[source]#

Return the current process-wide default SpaceCore context.

Returns:: The default context used by constructors when no explicit context can be inferred or provided.
Return type:: Context

spacecore.resolve_context_priority(priority_ctx=None, *other_ctx)[source]#

Resolve the context assigned to a newly created object.

Parameters:

priority_ctx (Context | BackendFamily | str | None) – Explicit context supplied by the caller. If this is not None, it wins over every inferred context.
*other_ctx (object) – Objects that may carry a ctx attribute or be backend-native arrays. These are used for context inference when no explicit context is supplied.

Returns:

The resolved context.

Return type:

Context

Notes

This is the public entry point for SpaceCore’s context-priority resolution. User code should call this function instead of accessing the internal context manager singleton.

spacecore.register_ops(ops)[source]#

Register a backend operations implementation.

Parameters:

ops (type[BackendOps]) – Backend operations class to register. It must be a subclass of spacecore.backend.BackendOps and define a unique backend family key.

Returns:

The registered class. Returning the class allows this function to be used as a decorator.

Return type:

type[BackendOps]

Raises:

TypeError – If ops is not a BackendOps subclass.
ContextConflictError – If another backend with the same family key is already registered.

Examples

register_ops can be used as a decorator:

@register_ops
class MyOps(BackendOps):
    ...

spacecore.set_resolution_policy(policy=None)[source]#

Set the policy for cross-backend context conversion.

Parameters:: policy (ContextPolicy | str | None) – Conversion policy to use. Accepted values are "warning", "error", "silent", matching ContextPolicy, or None to restore the default policy.
Return type:: None

Notes

The resolution policy is consulted when SpaceCore detects conversion from one backend family to another. It does not prevent explicit construction of contexts.

Policy values are:

"warning": allow backend conversion and issue a warning.
"error": reject backend conversion.
"silent": allow backend conversion without warning.

spacecore.get_resolution_policy()[source]#

Return the active cross-backend conversion policy.

Returns:: Policy name, one of "warning", "error", or "silent".
Return type:: str

spacecore.set_dtype_resolution_policy(policy=None)[source]#

Set the policy for dtype handling during context conversion.

Parameters:: policy (DtypePreservePolicy | str | None) – Dtype policy to use. Accepted values are "keep_native" and "convert", matching DtypePreservePolicy, or None to restore the default policy.
Return type:: None

Notes

"keep_native" preserves the source dtype where possible when converting context-bound objects. "convert" follows normal target-context dtype resolution.

Policy values are:

"keep_native": preserve the object’s dtype by mapping it to an equivalent dtype in the target backend.
"convert": use the dtype provided by the resolved target context.

spacecore.get_dtype_resolution_policy()[source]#

Return the active dtype conversion policy.

Returns:: Policy name, one of "keep_native" or "convert".
Return type:: str