class documentation

Matcher that is used to match modules and members during restriction and pass through checks.

This class is intentionally immutable. Changes need to be made as new instances.

Static Method nested_child Create a matcher where the given child is put at the given path.
Method __or__ Combine this matcher with another.
Method __post_init__ Post initialization validations.
Method access_matcher Perform a match check and return matcher.
Method child_matcher Return a child matcher for the given path.
Method match_access Perform a match check.
Method with_child_unrestricted Create new matcher with the given child path removed.
Class Variable access Immutable set of names to match access.
Class Variable all Shortcut for an always-matched matcher.
Class Variable all_runtime Shortcut for an always-runtime-matched matcher.
Class Variable all_uses Shortcut for a matcher that matches any use.
Class Variable all_uses_runtime Shortcut for a matcher that matches any use at runtime.
Class Variable children Immutable mapping of child matchers.
Class Variable leaf_message Override message to use in error/warning. Defaults to a common message. This is only applicable to leafs, so this must only be set when match_self is True and this matcher is on children of a parent.
Class Variable leaf_warning If set, issues a warning instead of raising an error. This is only applicable to leafs, so this must only be set when match_self is True and this matcher is on children of a parent.
Class Variable match_self If True, this matcher matches.
Class Variable none Shortcut for a never-matched matcher.
Class Variable only_runtime If True, any matches on this matcher only apply at runtime, not import time.
Class Variable use Immutable set of names to match use.
@staticmethod
def nested_child(path: Sequence[str], child: SandboxMatcher) -> SandboxMatcher: (source)

Create a matcher where the given child is put at the given path.

Parameters
path:Sequence[str]Path to the child.
child:SandboxMatcherChild matcher to set
Returns
SandboxMatcherCreated matcher.
def __or__(self, other: SandboxMatcher) -> SandboxMatcher: (source)

Combine this matcher with another.

def __post_init__(self): (source)

Post initialization validations.

def access_matcher(self, context: RestrictionContext, *child_path: str, include_use: bool = False) -> Optional[SandboxMatcher]: (source)

Perform a match check and return matcher.

Parameters
context:RestrictionContextCurrent restriction context.
*child_path:strFull path to the child being accessed.
include_use:boolWhether to include the use set in the check.
Returns
Optional[SandboxMatcher]The matcher if matched.
def child_matcher(self, *child_path: str) -> Optional[SandboxMatcher]: (source)

Return a child matcher for the given path.

Unlike match_access, this will match if in py`use` in addition to access. If in neither, it uses the child mapping.

Parameters
*child_path:strFull path to the child to get matcher for.
Returns
Optional[SandboxMatcher]Matcher that can be used to check children.
def match_access(self, context: RestrictionContext, *child_path: str, include_use: bool = False) -> bool: (source)

Perform a match check.

Parameters
context:RestrictionContextCurrent restriction context.
*child_path:strFull path to the child being accessed.
include_use:boolWhether to include the use set in the check.
Returns
boolTrue if matched.
def with_child_unrestricted(self, *child_path: str) -> SandboxMatcher: (source)

Create new matcher with the given child path removed.

Traverses the child mapping, if present, until on leaf of path where it is removed from access, use, and children.

Parameters
*child_path:strFull path to the child to remove restrictions for.
Returns
SandboxMatcherCopied matcher from this matcher without this child restricted.
access: Set[str] = (source)

Immutable set of names to match access.

This is often only used for pass through checks and not member restrictions. If this is used for member restrictions, even importing/accessing the value will fail as opposed to use which is for when it is used.

An string containing a single asterisk can be used to match all.

Shortcut for an always-matched matcher.

all_runtime: ClassVar[SandboxMatcher] = (source)

Shortcut for an always-runtime-matched matcher.

all_uses: ClassVar[SandboxMatcher] = (source)

Shortcut for a matcher that matches any use.

all_uses_runtime: ClassVar[SandboxMatcher] = (source)

Shortcut for a matcher that matches any use at runtime.

children: Mapping[str, SandboxMatcher] = (source)

Immutable mapping of child matchers.

leaf_message: Optional[str] = (source)

Override message to use in error/warning. Defaults to a common message. This is only applicable to leafs, so this must only be set when match_self is True and this matcher is on children of a parent.

leaf_warning: Optional[Type[Warning]] = (source)

If set, issues a warning instead of raising an error. This is only applicable to leafs, so this must only be set when match_self is True and this matcher is on children of a parent.

match_self: bool = (source)

If True, this matcher matches.

Shortcut for a never-matched matcher.

only_runtime: bool = (source)

If True, any matches on this matcher only apply at runtime, not import time.

use: Set[str] = (source)

Immutable set of names to match use.

This is best used for member restrictions on functions/classes because the restriction will not apply to referencing/importing the item, just when it is used.

An string containing a single asterisk can be used to match all.