Configuration

zap uses configuration files and directories to manage your projects and Python installations.

pyproject.toml

Standard Python project configuration file. zap reads and writes the [project] section.

[project]
name = "my-app"
version = "0.1.0"
requires-python = ">= 3.12"
dependencies = [
    "requests",
    "flask",
    "sqlalchemy",
    "mypackage @ git+https://github.com/user/repo",
]

Fields:

zap.lock

Lock file that records exact versions of installed packages. Auto-generated, do not edit manually.

# zap.lock - Fast and Safe Python Package Manager
# This file is auto-generated. Do not edit manually.

python = "3.12.1"

[[packages]]
name = "certifi"
version = "2024.2.2"

[[packages]]
name = "requests"
version = "2.31.0"

Directory Structure

zap uses the following directories:

Global Cache

Downloaded packages are cached globally:

~/.cache/zap/
  wheels/
    requests-2.31.0/
      requests-2.31.0-py3-none-any.whl
      extracted/
    certifi-2024.2.2/
      certifi-2024.2.2-py3-none-any.whl
      extracted/
  git-mypackage/
    mypackage-1.0.0-py3-none-any.whl

Python Installations

Managed Python versions are stored at:

~/.zap/python/
  3.12.8/
    bin/
      python3
      pip3
    lib/
      python3.12/
    include/
  3.11.11/
    ...

List installed versions:

zap python list

Project Virtual Environment

Each project has its own virtual environment at .venv/:

.venv/
  bin/
    python
    pip
    activate
  lib/
    python3.12/
      site-packages/
  pyvenv.cfg

Cache Management

Manage the global cache with zap cache commands:

# View cache location and size
zap cache info

# Clear all cached packages
zap cache clean

Using the Virtual Environment

You can activate it manually if needed:

source .venv/bin/activate

But zap run automatically uses the venv, so activation is usually unnecessary.

Git Dependencies

Git dependencies in pyproject.toml use PEP 440 URL syntax:

dependencies = [
    # From main branch
    "package @ git+https://github.com/user/repo",
    
    # Specific branch
    "package @ git+https://github.com/user/repo@main",
    
    # Specific tag
    "package @ git+https://github.com/user/repo@v1.0.0",
]

When adding via CLI, use the git= syntax:

zap append git=https://github.com/user/repo
zap append git=https://github.com/user/repo@main