Skip to content

API Reference

Complete API documentation for provide.foundation — auto-generated from source code docstrings and type hints.

🚀 Quick Access

Most commonly used functions and classes:

Essential Functions

from provide.foundation import logger, pout, perr, get_hub
from provide.foundation.hub import register_command
from provide.foundation.resilience import retry
Import Purpose Documentation
logger Global logger instance for structured logging logger docs
pout() User-facing output to stdout (with colors) console docs
perr() User-facing errors to stderr (with colors) console docs
get_hub() Access the central component registry hub docs
@register_command Register CLI commands CLI docs
@retry Retry decorator with exponential backoff resilience docs

Configuration Classes

from provide.foundation.config import BaseConfig, env_field
from provide.foundation.logger.config import TelemetryConfig, LoggingConfig
Class Purpose Documentation
BaseConfig Base class for configuration objects config docs
TelemetryConfig Configure logging and telemetry logger config docs
LoggingConfig Detailed logging configuration logger config docs

Utilities

from provide.foundation.utils.environment import get_bool, get_int, get_str
from provide.foundation.file import atomic_write
from provide.foundation.serialization import provide_dumps, provide_loads
from provide.foundation.eventsets.display import show_event_matrix
from provide.foundation import shutdown_foundation
Function Purpose Documentation
get_bool(), get_int(), get_str() Environment variable helpers environment docs
atomic_write() Safe atomic file writes file docs
provide_dumps(), provide_loads() JSON serialization serialization docs
show_event_matrix() Display event set emoji matrix eventsets docs
shutdown_foundation() Graceful shutdown and cleanup setup docs

Advanced Features

from provide.foundation.hub import injectable
from provide.foundation.hub.container import Container, create_container
from provide.foundation.eventsets.types import EventSet, EventMapping
Feature Purpose Documentation
@injectable Mark classes for dependency injection hub docs
Container Dependency injection container container docs
EventSet Define custom event sets with emojis eventsets docs
EventMapping Map events to emoji representations eventsets docs

Quick Navigation

Core Components

  • logger - Structured logging system with emoji-enhanced output
  • hub - Central component registry and dependency injection
  • config - Configuration management with environment variable support
  • errors - Error handling and custom exception types

CLI & Console

  • cli - Command-line interface framework
  • console - Console I/O with colors and formatting

Resilience & Observability

  • resilience - Retry patterns, circuit breakers, and failure handling
  • metrics - Metrics collection and OpenTelemetry integration
  • tracer - Distributed tracing support

Data & Files

  • file - Atomic file operations and change detection
  • archive - Archive creation and extraction (tar, zip, gzip)
  • serialization - JSON serialization with type safety

Security & Crypto

  • crypto - Cryptographic operations (keys, signatures, certificates)
  • security - Security utilities and path validation

Utilities

  • utils - General utilities (async, caching, formatting, timing)
  • process - Safe subprocess execution
  • platform - Platform detection and system information
  • transport - HTTP client utilities
  • parsers - Data parsing utilities

Browse All Modules

For a complete hierarchical view of all modules, classes, and functions:

📑 Full Module Index - Complete navigation tree

Module Count

This reference documents 36 foundation modules with 352 API pages.

Tip: Use your browser's search (Ctrl+F / Cmd+F) within individual module pages to quickly find specific functions or classes.