API Reference

Auto-generated from docstrings via mkdocstrings. For prose explanations of the same APIs, see Programmatic API.

Public API (hermetic)

The top-level package re-exports the two intended entry points:

from hermetic import hermetic_blocker, with_hermetic

hermetic

Public package exports for hermetic.

hermetic_blocker(_config=None, *, block_network=False, block_subprocess=False, fs_readonly=False, fs_root=None, block_environment=False, block_code_exec=False, block_interpreter_mutation=False, block_native=False, allow_localhost=False, allow_domains=(), deny_imports=(), trace=False, sealed=False, profile=None)

Build a blocker that applies the requested hermetic guards.

Can be called in three ways::

# 1. Keyword arguments (original API)
hermetic_blocker(block_network=True)

# 2. Pre-built BlockConfig object
hermetic_blocker(BlockConfig(block_network=True))

# 3. Named profile
hermetic_blocker(profile="net-hermetic")

with_hermetic(_config=None, **kwargs)

Mirror hermetic_blocker under a decorator-friendly name.

options: members: - hermetic_blocker - with_hermetic - version

Blocker (hermetic.blocker)

hermetic.blocker

Context managers and decorators for process-wide guard activation.

BlockConfig dataclass

Describe the guard policy contributed by one blocker instance.

from_kwargs(**kw) classmethod

Normalize accepted keyword aliases into a config instance.

__or__(other)

Merge two policies; stricter settings win. Alias for merged_with.

merged_with(other)

Combine two policies so the stricter settings win.

hermetic_blocker(_config=None, *, block_network=False, block_subprocess=False, fs_readonly=False, fs_root=None, block_environment=False, block_code_exec=False, block_interpreter_mutation=False, block_native=False, allow_localhost=False, allow_domains=(), deny_imports=(), trace=False, sealed=False, profile=None)

Build a blocker that applies the requested hermetic guards.

Can be called in three ways::

# 1. Keyword arguments (original API)
hermetic_blocker(block_network=True)

# 2. Pre-built BlockConfig object
hermetic_blocker(BlockConfig(block_network=True))

# 3. Named profile
hermetic_blocker(profile="net-hermetic")

with_hermetic(_config=None, **kwargs)

Mirror hermetic_blocker under a decorator-friendly name.

options: members: - hermetic_blocker - with_hermetic - BlockConfig

Errors (hermetic.errors)

hermetic.errors

Exception types raised by hermetic guard setup and enforcement.

HermeticError

Bases: RuntimeError

Base for hermetic failures.

PolicyViolation

Bases: HermeticError

Raised when a guard blocks an action.

Attributes:
  • guard (Optional[str]) –

    Machine-readable guard name (e.g. "network", "subprocess", "filesystem", "environment", "code_exec", "interpreter", "imports"). None when the violation originates from code that predates this attribute.

  • target (Optional[str]) –

    Optional detail about what was blocked (host, path, import name…).

__init__(message, *, guard=None, target=None)

Create a policy violation with an optional machine-readable guard name.

BootstrapError

Bases: HermeticError

Raised when bootstrap mode fails.

Profiles (hermetic.profiles)

hermetic.profiles

Named guard presets and helpers for combining them.

GuardConfig dataclass

Capture the guard settings used to run a target.

Fields use the CLI-style no_* prefix for historical reasons. The block_* aliases (e.g. block_network, block_subprocess) are available as read-only properties for parity with BlockConfig.

block_network property

Alias for no_network.

block_subprocess property

Alias for no_subprocess.

block_environment property

Alias for no_environment.

block_code_exec property

Alias for no_code_exec.

block_interpreter_mutation property

Alias for no_interpreter_mutation.

apply_profile(base, name)

Overlay a named profile onto an existing guard config.

options: members: - GuardConfig - PROFILES - apply_profile

CLI (hermetic.cli)

hermetic.cli

Command-line parsing and entry points for hermetic.

build_parser()

Create the CLI parser for hermetic's own flags.

parse_hermetic_args(argv)

Translate CLI flags into a guard configuration.

main(argv=None)

Run the CLI and dispatch to the requested target.

options: members: - main - build_parser - parse_hermetic_args

Runner (hermetic.runner)

hermetic.runner

Target execution helpers for in-process and bootstrap modes.

config_to_flags(cfg)

Convert a guard config into bootstrap-compatible flag data.

run(target, target_argv, cfg)

Run a target under the requested guard configuration.

options: members: - run - config_to_flags

Resolver (hermetic.resolver)

hermetic.resolver

Resolve targets into importable or bootstrapable execution specs.

TargetSpec dataclass

Describe how hermetic should launch a requested target.

resolve(target)

Choose the execution strategy for a target string.

invoke_inprocess(spec)

Import or run a target directly inside the current interpreter.

options: members: - TargetSpec - resolve - invoke_inprocess

Bootstrap (hermetic.bootstrap)

hermetic.bootstrap

Bootstrap helpers for installing guards in a foreign interpreter.

write_sitecustomize(flags)

Write a temporary sitecustomize module that installs bootstrap guards.

options: members: - write_sitecustomize

Guards

These submodules implement the actual monkey-patches. They are public for advanced users who want to install one guard at a time without going through hermetic_blocker, but most callers should use the public API above.

hermetic.guards

hermetic.guards

Guard module orchestration for bulk install and uninstall operations.

install_all(**kwargs)

Install every requested guard using grouped keyword options.

uninstall_all()

Remove installed guards in reverse dependency order.

options: members: - install_all - uninstall_all

hermetic.guards.network

hermetic.guards.network

Guards that block outbound networking and unsafe bind targets.

install(*, allow_localhost, allow_domains, trace=False)

Patch networking APIs while keeping socket.socket subclassable.

uninstall()

Restore the original networking APIs.

options: members: - install - uninstall

hermetic.guards.subprocess_guard

hermetic.guards.subprocess_guard

Guards that block subprocess creation and process-spawning helpers.

install(*, trace=False)

Patch subprocess entry points so process creation is denied.

uninstall()

Restore the original subprocess and spawn entry points.

options: members: - install - uninstall

hermetic.guards.filesystem

hermetic.guards.filesystem

Guards that make filesystem access readonly and optionally rooted.

install(*, fs_root=None, trace=False)

Patch filesystem APIs to deny writes and optional out-of-root reads.

uninstall()

Restore the original filesystem APIs.

options: members: - install - uninstall

hermetic.guards.imports_guard

hermetic.guards.imports_guard

Guards that block native extensions and denied imports.

install(*, block_native=True, trace=False, block_subprocess_libs=False, block_pickle=False, deny_imports=())

Patch import machinery to reject configured modules and FFI surfaces.

uninstall()

Restore the original import machinery and patched attributes.

options: members: - install - uninstall