Skip to content

Welcome to provide.foundation

provide.foundation is a comprehensive Python 3.11+ library for building robust, operationally excellent applications. It provides a cohesive, "batteries-included" toolkit that addresses common challenges in modern application development.

🤖 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.

Built on industry-standard libraries like structlog, click, and attrs, provide.foundation offers a superior developer experience with beautiful console output, powerful error handling, and cross-platform system utilities.

Beta Status

provide-foundation is in beta. Core features are stable, but the API may evolve.

  • Current version: v0.0.1026
  • Status: Beta (Development Status: 4)
  • Production use: Use with caution; API may change

Why provide.foundation?

For Developers For Teams
✅ Zero Configuration: Works beautifully out of the box. 🤝 Consistent: Standardized patterns across all services.
✅ Type Safe: Full type hints and runtime validation. 🔭 Observable: Structured logs ready for analysis.
✅ Fast: Optimized for production (>14,000 msg/sec). 🛠️ Maintainable: Clean, well-documented APIs.
✅ Testable: Built-in testing utilities and patterns. 🧩 Extensible: Plugin system for customization.

Learning Path

This documentation is structured to help you learn effectively, whether you're a beginner or an expert.

🎓 Tutorials

Step-by-step lessons to get you started. Perfect for new users.

Start Learning →

📖 How-To Guides

Practical, goal-oriented recipes to solve specific problems.

Solve a Problem →

🧠 Concepts

Deep dives into the concepts and architecture behind the framework.

Understand the "Why" →

📖 Reference

Complete API documentation for all modules, classes, and functions.

Browse API Docs →

Quick Example

from provide.foundation import logger, pout, get_hub
from provide.foundation.hub import register_command
from provide.foundation.resilience import retry
from provide.foundation.errors import NetworkError

# Initialize the framework (optional - logger auto-initializes on first use)
# For advanced configuration:
# get_hub().initialize_foundation()

# Structured logging with event enrichment
logger.info("application_startup", version="1.0.0", emoji="🚀")

# User-facing console output
pout("✅ Configuration loaded successfully.", color="green")

# Resilient functions
@retry(max_attempts=3, exceptions=(NetworkError,))
def fetch_data_from_api():
    logger.info("api_call_start", endpoint="/data", emoji="📡")
    # ... API call logic that might fail ...
    # if failed:
    #     raise NetworkError("API is unavailable")
    logger.info("api_call_complete", status=200, emoji="✅")

# Declarative CLI commands
@register_command("process")
def process_data(file: str, force: bool = False):
    """Process the given data file."""
    pout(f"Processing {file} with force={force}...")
    fetch_data_from_api()

Part of the provide.io Ecosystem

This project is part of a larger ecosystem of tools for Python and Terraform development.

View Ecosystem Overview →

Understand how provide-foundation, pyvider, flavorpack, and other projects work together.

System Requirements

  • Python 3.11 or higher
  • Works on Linux, macOS, and Windows
  • Minimal core dependencies (structlog, attrs, click)

Ready to get started? Head to the Quick Start Tutorial.