pyintents

PyIntents package.

exception pyintents.IntentConfigurationError[source]

Bases: IntentError

Raised when namespace or decorator configuration is invalid.

exception pyintents.IntentError[source]

Bases: Exception

Base class for all PyIntents errors.

exception pyintents.IntentParseError(func_name, message)[source]

Bases: IntentError

Raised when function source cannot be parsed or is unavailable.

Parameters:

  • func_name (str)

  • message (str)

Return type:

None

__init__(func_name, message)[source]
Parameters:

  • func_name (str)

  • message (str)

Return type:

None

exception pyintents.IntentShadowingError(desc)[source]

Bases: IntentError

Raised when a protected name is shadowed in the local scope.

Parameters:

desc (str)

Return type:

None

__init__(desc)[source]
Parameters:

desc (str)

Return type:

None

class pyintents.Capability(handler, validate)[source]

Bases: object

Trusted synchronous handler and a mandatory resource/argument validator.

The validator must return exactly True to authorize a payload. Validators must be pure: authorization is completed before the handler is invoked.

Parameters:
handler: Callable[[dict[str, Any]], Any]
validate: Callable[[dict[str, Any]], bool]
__init__(handler, validate)
Parameters:
Return type:

None

class pyintents.IntentDispatcher(capabilities, *, grants, deny=(), max_nodes=10000, max_depth=32, max_bytes=1000000)[source]

Bases: object

A fixed registry with fixed, trusted grants and bounded JSON-like data.

Construct one dispatcher per trusted authorization context. Never derive grants from an unauthenticated request. Registry entries and grants cannot be extended through dispatch(). Resource limits cover data traversal, not handler runtime, memory allocation by the transport, or external effects.

Parameters:
__init__(capabilities, *, grants, deny=(), max_nodes=10000, max_depth=32, max_bytes=1000000)[source]
Parameters:
Return type:

None

_reject(name, reason)[source]
Parameters:
Return type:

None

_copy_data(value, name)[source]
Parameters:
Return type:

Any

dispatch(name, payload)[source]

Authorize, copy, validate, invoke once, and copy the result.

Handler exceptions propagate. There is no retry, rollback, or ACID guarantee; a rejected result does not undo a completed handler effect.

Parameters:
Return type:

Any

exception pyintents.IntentViolationError(func_name, violation, *, path=())[source]

Bases: IntentError

Raised when a function violates declared capabilities.

Parameters:
Return type:

None

__init__(func_name, violation, *, path=())[source]
Parameters:
Return type:

None

class pyintents.IntentNamespace(uses=None, *, recursive=True, without=None, uselocals=False, usemodule=False, deny=None, allow_unknown=False, deny_dynamic_primitives=True, only_warnings=False, strict=True, max_nodes=10000, analysis_depth=100)[source]

Bases: object

Declarative capability policy for Python functions.

Security defaults: - recursive=True - allow_unknown=False - deny_dynamic_primitives=True

usemodule:

Allows functions defined in the same module as the decorated function. Works only with recursive=True.

Parameters:

  • uses (Iterable[Rule] | None)

  • recursive (bool)

  • without (Iterable[Rule] | None)

  • uselocals (bool)

  • usemodule (bool)

  • deny (Iterable[Rule] | None)

  • allow_unknown (bool)

  • deny_dynamic_primitives (bool)

  • only_warnings (bool)

  • strict (bool)

  • max_nodes (int)

  • analysis_depth (int)

__init__(uses=None, *, recursive=True, without=None, uselocals=False, usemodule=False, deny=None, allow_unknown=False, deny_dynamic_primitives=True, only_warnings=False, strict=True, max_nodes=10000, analysis_depth=100)[source]
Parameters:
Return type:

None

intent(uses=None, *, recursive=None, without=None, uselocals=None, usemodule=None, deny=None, allow_unknown=None)[source]
Parameters:
Return type:

Callable[[Callable[[…], Any]], Callable[[…], Any]]

_violation(node, path)[source]
Parameters:
Return type:

None

_validate_tree(root, policy, *, root_module=None)[source]
Parameters:

  • root (CallNode)

  • policy (_EffectivePolicy)

  • root_module (str | None)

Return type:

None

static _is_allowed(node, policy, *, root_module=None)[source]
Parameters:

  • node (CallNode)

  • policy (_EffectivePolicy)

  • root_module (str | None)

Return type:

bool

class pyintents.CallNode(identity, call_name, lineno=None, col_offset=None, resolved_func=None, is_local_definition=False, is_dynamic=False, is_unresolved=False, is_source_available=True, is_cycle=False, children=<factory>)[source]

Bases: object

Node in a call graph.

Parameters:
identity: str
call_name: str
lineno: int | None = None
col_offset: int | None = None
resolved_func: Callable[[...], Any] | None = None
is_local_definition: bool = False
is_dynamic: bool = False
is_unresolved: bool = False
is_source_available: bool = True
is_cycle: bool = False
children: list[CallNode]
walk()[source]

Yield this node and all descendants.

Return type:

Iterator[CallNode]

__init__(identity, call_name, lineno=None, col_offset=None, resolved_func=None, is_local_definition=False, is_dynamic=False, is_unresolved=False, is_source_available=True, is_cycle=False, children=<factory>)
Parameters:
Return type:

None

class pyintents.CallTree(func, max_depth=1, resolver=None, protected_names=None, *, strict=False, max_nodes=10000, analysis_depth=100)[source]

Bases: object

Build a call graph for a function.

Root function must have source code available. Child functions without source are represented as opaque nodes.

Parameters:

  • func (Callable[..., Any])

  • max_depth (int | float)

  • resolver (SafeResolver | None)

  • protected_names (set[str] | None)

  • strict (bool)

  • max_nodes (int)

  • analysis_depth (int)

__init__(func, max_depth=1, resolver=None, protected_names=None, *, strict=False, max_nodes=10000, analysis_depth=100)[source]
Parameters:
Return type:

None

_local_ids: dict[int, str]
_local_blocked: dict[int, set[str]]
max_depth: int | float
_check_budget(depth)[source]
Parameters:

depth (int)

Return type:

None

has_call(name)[source]

Check whether call graph contains exact call name or identity.

Parameters:

name (str)

Return type:

bool

find_calls(name)[source]

Find nodes by exact call name or identity.

Parameters:

name (str)

Return type:

list[CallNode]

_build_from_callable(func, depth, stack, require_source)[source]
Parameters:
Return type:

CallNode

_build_from_ast(func_def, name, depth, stack, parent_func, local_defs, owner_identity)[source]
Parameters:
Return type:

CallNode

_expand_node(node, func_def, depth, stack, parent_func, local_defs)[source]
Parameters:
Return type:

CallNode

_build_child(call, parent_func, local_defs, depth, stack, owner_identity)[source]
Parameters:
Return type:

CallNode