Documentation
¶
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Venv ¶
Venv gives the sandbox its own Python virtual environment for project, kept in the layout's cache (see layout.Layout) rather than in the project, and keeps it away from the project's own .venv.
A virtualenv in a writable project is code the host runs: its python, activate scripts and console scripts are what the host gets the next time it works in the project. So the sandbox's environment is the layout's cache for owner venv-<project name>-<hash of its path>, and the project's .venv is read-only, or, if there is none, sealed so that the sandbox can't create one. The empty mount point bwrap leaves for the seal on Linux is removed when the session closes.
The environment is created when the session starts, if it doesn't exist, with the host's active python3 (see With, which the sandbox needs as well if that Python is installed under home). It is created inside a separate, minimal sandbox that can write nothing but the environment, because sandboxes using the key write there, and a previous one could have left a symlink pointing at the host. Each project's environment is an owner of its own, so a sandbox can write only its project's, not another's under the same key. VIRTUAL_ENV and UV_PROJECT_ENVIRONMENT name it, and its bin directory is put on PATH, so pip, uv (uv sync, uv run) and Poetry use it. A host .venv can still be read, e.g. to see what's installed.
It needs sandbox.Start, and a working sandbox backend to create the environment.
Example ¶
Venv keeps the sandbox's virtualenv in the layout's storage, not the project, so nothing the sandbox installs ends up in a .venv the host runs later.
package main
import (
"os"
sandbox "bitbucket.org/conistonit/sandbox/pkg"
"bitbucket.org/conistonit/sandbox/pkg/layout"
"bitbucket.org/conistonit/sandbox/pkg/toolchain/python"
)
func main() {
home, _ := os.UserHomeDir()
project := "/path/to/project"
key, _ := layout.NewKey(layout.KeyDir(project))
l, _ := layout.NewLayout(home, "sandbox", key)
_ = sandbox.Compose(
sandbox.WithReadWrite(project),
python.With(l, layout.CacheIsolated),
python.Venv(l, project), // VIRTUAL_ENV, UV_PROJECT_ENVIRONMENT, PATH
)
}
Output:
func With ¶
With makes the host's active Python usable in the sandbox: the `python3` the host runs in home, which may be a pyenv or uv-managed one, found by asking it for sys.base_prefix. It is asked from home, not the project, so a project's .python-version, uv.toml or pyproject.toml doesn't choose the Python or the caches (see sandbox.Host), and run isolated (python3 -I), so nothing in home is imported. If that install lives under home, which the sandbox hides, its bin, lib and include directories are bound read-only (not the whole prefix: see toolchain.InstallBinds) and bin is put on PATH. A prefix that isn't an absolute path, or is home itself, is refused.
A `uv` under home must be in a bin directory (<prefix>/bin, or uv's documented install directories ~/.local/bin and ~/.cargo/bin): that directory is bound read-only and put on PATH, so other programs in it become visible read-only too. A uv elsewhere under home (~/Downloads/uv) is refused, since binding its directory would show everything beside it. uv's managed Pythons (`uv python dir`) are bound read-only as well, so uv can use them but not install more; they must be inside uv's default data directory (~/.local/share/uv) or the UV_PYTHON_INSTALL_DIR the user set, and neither home nor a directory directly in it, or uv is refused. Settings in ~/.config/pip and ~/.config/uv stay hidden.
- CacheIsolated: pip and uv caches in the layout's cache for owner python (see layout.Layout). uv copies packages into virtualenvs instead of hard-linking them, so a project's virtualenv shares no files with the cache.
- CacheReadHost: not supported, because neither pip nor uv can use a cache it can't write to.
- CacheShareHost: the host's pip and uv caches, read-write. Built wheels aren't re-checked when reused, and uv hard-links cached files into virtualenvs, so a change to one changes every host environment using it. Each cache must be inside ~/.cache (~/Library/Caches), or it is refused rather than shared.
It allows pypi.org and files.pythonhosted.org on port 443 as network rules, which apply under sandbox.NetProxied; another index needs its own allow rule.
It needs sandbox.Start.
Types ¶
This section is empty.