Installation¶

This guide covers installing provide.foundation and setting up your development environment.

🤖 AI-Generated Content

This documentation was generated with AI assistance and is still being audited. Some, or potentially a lot, of this information may be inaccurate. Learn more.

Requirements¶

Python 3.11 or higher - Foundation uses modern Python features
pip or uv - Package manager for installation
Virtual environment (recommended) - For isolated dependencies

Basic Installation¶

Using pip¶

The simplest installation provides core logging functionality:

pip install provide-foundation

This installs the base package with essential dependencies: - structlog - Structured logging foundation - attrs - Data class utilities - aiofiles - Async file I/O operations - tomli_w - TOML file writing

Using uv (Recommended for Development)¶

For faster dependency resolution:

# Install uv if you haven't already
pip install uv

# Install Foundation
uv pip install provide-foundation

Installation Options¶

Foundation offers modular installation through "extras" that add optional features:

All Features¶

For the complete experience:

pip install "provide-foundation[all]"

Specific Features¶

Install only what you need:

CLI Framework¶

pip install "provide-foundation[cli]"

Adds: click for command-line interface building

Use when: Building command-line tools, developer utilities

Cryptography¶

pip install "provide-foundation[crypto]"

Adds: cryptography library for secure operations

Use when: Need hashing, signatures, or certificate management

HTTP Transport¶

pip install "provide-foundation[transport]"

Adds: httpx for HTTP client operations

Use when: Making HTTP requests with middleware and error handling

OpenTelemetry¶

pip install "provide-foundation[opentelemetry]"

Adds: OpenTelemetry SDK for distributed tracing

Use when: Building microservices with distributed tracing needs

Compression¶

pip install "provide-foundation[compression]"

Adds: zstandard for high-performance compression

Use when: Need fast compression for archives and data transfer

Platform Utilities¶

pip install "provide-foundation[platform]"

Adds: psutil, py-cpuinfo for system information

Use when: Need OS/hardware detection and system monitoring

Process Utilities¶

pip install "provide-foundation[process]"

Adds: psutil, setproctitle for process control

Use when: Need process management and lifecycle control

Extended Utilities¶

pip install "provide-foundation[extended]"

Adds: Combination of platform and process utilities

Use when: Need comprehensive system-level utilities

Combining Extras¶

Install multiple features:

pip install "provide-foundation[cli,crypto]"

Virtual Environment Setup¶

Using venv (Standard Library)¶

# Create virtual environment
python -m venv .venv

# Activate on macOS/Linux
source .venv/bin/activate

# Activate on Windows
.venv\Scripts\activate

# Install Foundation
pip install "provide-foundation[all]"

Using uv venv (Faster)¶

# Create and activate environment
uv venv
source .venv/bin/activate  # macOS/Linux
# or: .venv\Scripts\activate  # Windows

# Install Foundation
uv pip install "provide-foundation[all]"

Verify Installation¶

Check that Foundation is installed correctly:

python -c "from provide.foundation import logger; logger.info('Installation successful!')"

You should see a formatted log message confirming the installation.

Development Installation¶

For contributing to Foundation or running examples from source:

# Clone the repository
git clone https://github.com/provide-io/provide-foundation.git
cd provide-foundation

# Create virtual environment
uv venv
source .venv/bin/activate  # macOS/Linux

# Install with development dependencies
uv sync

# Run tests to verify
pytest

Dependency Overview¶

Core Dependencies (Always Installed)¶

aiofiles (>=23.2.1) - Async file I/O operations
attrs (>=23.1.0) - Data class utilities
structlog (>=25.3.0) - Structured logging engine
tomli_w (>=1.0.0) - TOML file writing

Optional Dependencies¶

Extra	Key Dependencies	Purpose
`cli`	click >=8.1.7	CLI framework
`compression`	zstandard >=0.22.0	High-performance compression
`crypto`	cryptography >=45.0.7	Cryptographic operations
`transport`	httpx >=0.27.0	HTTP client
`opentelemetry`	opentelemetry-sdk >=1.22.0	Distributed tracing
`platform`	psutil, py-cpuinfo	System/OS info utilities
`process`	psutil, setproctitle	Process control and lifecycle
`extended`	(combines platform + process)	Extended system utilities
`all`	(all extras above)	Complete feature set

Platform-Specific Notes¶

macOS¶

Requires macOS 10.13 or higher
Xcode Command Line Tools recommended for cryptography
Apple Silicon (M1/M2) fully supported

Linux¶

Works on most distributions (Ubuntu, Debian, RHEL, Alpine)
Requires gcc and libffi-dev for cryptography on some systems
Container images: Use Python 3.11+ base images

Windows¶

Windows 10 or higher recommended
Microsoft C++ Build Tools required for cryptography
PowerShell or Command Prompt supported

Troubleshooting¶

Import Errors¶

Problem: ModuleNotFoundError: No module named 'provide'

Solution: Ensure virtual environment is activated and Foundation is installed:

source .venv/bin/activate
pip list | grep provide-foundation

Cryptography Installation Fails¶

Problem: Build errors when installing [crypto] extra

Solution: Install platform-specific build tools:

macOS:

xcode-select --install

Ubuntu/Debian:

sudo apt-get install build-essential libffi-dev python3-dev

RHEL/CentOS:

sudo yum install gcc libffi-devel python3-devel

Version Conflicts¶

Problem: Dependency version conflicts with existing packages

Solution: Use a fresh virtual environment or update conflicting packages:

pip install --upgrade pip
pip install "provide-foundation[all]" --upgrade

Next Steps¶

After installation:

Quick Start - Write your first Foundation code
First Application - Build a complete CLI tool
Examples - Explore feature-specific examples

Need help? Check the GitHub Issues or ask a question.