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.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)[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)

__init__(uses=None, *, recursive=True, without=None, uselocals=False, usemodule=False, deny=None, allow_unknown=False, deny_dynamic_primitives=True, only_warnings=False)[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]]

_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)[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)

__init__(func, max_depth=1, resolver=None, protected_names=None)[source]
Parameters:
Return type:

None

max_depth: int | float
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