Environment Setup Playbook¶

This playbook covers environment setup, configuration, and troubleshooting for the Mangetamain project.

Table of Contents¶

Initial Environment Setup
Virtual Environment with UV
Jupyter Kernel Configuration
Dependency Management
Troubleshooting

Initial Environment Setup¶

Requirements¶

Python 3.12 (required to avoid TensorFlow incompatibility)
UV package manager
VS Code (recommended)

Create Project Structure¶

# Initialize project with package structure
uv init --package  # Creates src/ and pyproject.toml

# Create virtual environment with Python 3.12
uv venv --python 3.12

Install Development Dependencies¶

# Add essential development tools
uv add --dev ruff mypy pytest black ipykernel jupyterlab ipython

# Sync all dependencies
uv sync

Virtual Environment with UV¶

Basic UV Commands¶

# Sync dependencies from pyproject.toml and lock file
uv sync

# Sync including development dependencies
uv sync --group dev

# Build distribution packages (wheel + sdist)
uv build

Quality Assurance Tools¶

# Check code formatting issues
uv run ruff check .

# Auto-fix formatting errors
uv run ruff format .

# Type checking for consistency
uv run mypy .

# Run unit tests
uv run pytest

Jupyter Kernel Configuration¶

Install Jupyter Kernel for VS Code¶

Create a custom kernel for the project:

uv run ipython kernel install --user \
  --name=venv-3.12-mangetamain \
  --display-name "Python 3.12 (mangetamain)"

Useful Kernel Management Commands¶

# List all available Jupyter kernels
uv run jupyter kernelspec list

# Remove old/unused kernel
uv run jupyter kernelspec uninstall python3

Configuration Notes¶

Adapt dependencies in pyproject.toml after kernel installation
The kernel name venv-3.12-mangetamain should match your project structure
Reference: Create Virtual Environments with UV for Jupyter in VS Code

Dependency Management¶

Python Version Configuration¶

Edit pyproject.toml:

[tool.uv]
python = "3.12.*"

Standard Dependencies¶

# Add runtime dependencies
uv add package-name

# Add development-only dependencies
uv add --dev package-name

# Remove dependencies
uv remove package-name

Troubleshooting¶

PyArrow Installation Issues¶

If you encounter PyArrow compatibility issues:

Problem: PyArrow binary build failures or version conflicts

Solution:

Modify pyproject.toml:
```
[tool.uv]
python = "3.12.*"
```

Force binary-only installation:

# Set environment variable to use pre-built binaries only
export UV_PIP_ONLY_BINARY=":all:"
# Alternative:
export PIP_ONLY_BINARY=":all:"

Install compatible PyArrow version:

# Recreate virtual environment
uv venv --recreate

# Install PyArrow with version constraint
uv add "pyarrow>=16,<18" --no-sync

# Sync all dependencies
uv sync

Common Environment Issues¶

Issue: Dependencies Not Found After Installation¶

Solution:

# Clear cache and reinstall
uv cache clean
uv sync --reinstall

Issue: Virtual Environment Not Activated¶

Solution:

# Check if virtual environment exists
ls .venv

# Activate manually (if needed)
source .venv/bin/activate  # Unix/macOS
# or
.venv\Scripts\activate  # Windows

Issue: Python Version Mismatch¶

Solution:

# Recreate venv with specific Python version
uv venv --recreate --python 3.12

# Verify Python version
uv run python --version

Issue: Jupyter Kernel Not Appearing in VS Code¶

Solution:

# Reinstall kernel
uv run jupyter kernelspec uninstall venv-3.12-mangetamain
uv run ipython kernel install --user \
  --name=venv-3.12-mangetamain \
  --display-name "Python 3.12 (mangetamain)"

# Restart VS Code
# Select the correct kernel in notebook interface

Environment Variables¶

When working with Google Cloud or other services requiring credentials:

# Load environment variables from .env file
set -a && source .env && set +a

Best Practices¶

Always sync after modifying dependencies:
```
uv sync
```
Use specific Python versions to avoid compatibility issues
Keep development dependencies separate using --dev flag
Regularly update dependencies:
```
uv sync --upgrade
```
Use virtual environments to isolate project dependencies
Document custom requirements in pyproject.toml comments