Python API reference

The public surface of the tn_venv package. Everything listed here is covered by backward-compatibility commitments; anything not listed here is internal.

tn_venv.create_venv

def create_venv(
    dest: str | os.PathLike = ".venv",
    *,
    python: str | list[str] | None = None,
    clear: bool = False,
    upgrade: bool = False,
    system_site_packages: bool = False,
    symlinks: bool | None = None,
    copies: bool | None = None,
    with_pip: bool = True,
    pip: str | None = None,
    setuptools: bool | str = False,
    wheel: bool | str = False,
    upgrade_pip: bool = False,
    packages: list[str] | None = None,
    requirements: list[str] | None = None,
    activators: list[str] | None = None,
    prompt: str | None = None,
    offline: bool = False,
    extra_search_dir: list[str] | None = None,
    quiet: bool = True,
) -> SessionResult

Create a virtual environment at dest and return a SessionResult. Keyword arguments mirror the CLI options documented in CLI reference; symlinks/copies of None select the platform default (copies on Windows, symlinks elsewhere). quiet=False streams progress to stdout at default verbosity.

tn_venv.cli_run

def cli_run(args: list[str] | None = None, *, environ: dict[str, str] | None = None) -> int

Run the full CLI in-process and return its exit code. args excludes the program name. environ replaces os.environ for configuration resolution (useful in tests).

tn_venv.SessionResult

Attribute	Type	Meaning
env_dir	Path	environment root directory
exe	Path	the environment’s Python executable
bin_path	Path	Scripts/ (Windows) or bin/ (POSIX)
site_packages	Path	the environment’s site-packages directory
prompt	str	prompt baked into the activation scripts
python	PythonInfo	probe of the base interpreter
activation_scripts	list[Path]	every activation script written
seed	SeedResult | None	seeder outcome (None when seeding was off)

tn_venv.seed.SeedResult

Attribute	Type	Meaning
pip	str | None	installed pip version
setuptools	str | None	"installed" when setuptools was installed
wheel	str | None	"installed" when wheel was installed
packages	list[str]	--with specifiers that were installed
requirements	list[str]	requirement files that were installed
skipped	bool	True when the seeder ran as a no-op

tn_venv.discovery.PythonInfo

Immutable description of a probed interpreter.

Attribute / property	Type	Meaning
executable	str	absolute path of the probed executable
base_executable	str	sys._base_executable — the real (non-venv) binary
version_info	tuple[int, int, int]	major, minor, micro
version_str	str	"3.14.7"-style rendering
major_minor	str	"3.14"-style rendering
implementation	str	cpython, pypy, …
prefix / base_prefix	str	installation prefixes
bits / is_64	int / bool	pointer width of the interpreter
is_freethreaded	bool	built with Py_GIL_DISABLED
is_python_build	bool	running from a build tree rather than an install
base_dir	str	directory of base_executable (the pyvenv.cfg home)
scripts_nt	str | None	directory holding venvlauncher.exe (Windows only)
matches(spec)	bool	whether this interpreter satisfies an InterpreterSpec

Construct with PythonInfo.from_current() (no subprocess) or PythonInfo.from_exe(path) (probes by executing path; results are cached per process).

tn_venv.discovery.discover

def discover(specs: str | list[str] | None = None, *, report: Reporter = SILENT) -> PythonInfo

Resolve the first satisfiable spec (see Choosing an interpreter) and return its probe. Raises InterpreterNotFoundError when nothing matches. discover_all() returns (PythonInfo, source) pairs for every candidate every provider can find.

Exceptions

TNError                     # base class
├── ConfigError             # bad options, env vars, or config file
├── DiscoverError           # interpreter probing failed
│   └── InterpreterNotFoundError   # .spec, .tried
├── CreateError             # could not lay down the environment
├── ActivateError           # activation script generation failed
├── SeedError               # ensurepip / pip step failed
├── LockError               # destination lock timed out
└── SubprocessError         # .cmd, .returncode, .output

All are importable from the package root (from tn_venv import TNError, …).