Skip to content

Welcome to Pyvider Documentation

Alpha Software - v0.0.x

Pyvider is currently in alpha (v0.0.1000). While functional and actively developed, please note:

  • APIs may change before the 1.0 release
  • Some documented features may not be fully implemented yet
  • Best suited for internal tooling, experimentation, and early adopters
  • See Roadmap for feature status and future plans

For production use, test thoroughly and be prepared for potential breaking changes in future releases.

Pyvider is a revolutionary Python framework that enables you to build production-ready Terraform providers using pure Python. By combining Python's elegance with Terraform's infrastructure management capabilities, Pyvider opens up provider development to the vast Python ecosystem while maintaining full compatibility with Terraform's Plugin Protocol v6.

🎯 Our Mission

To democratize Terraform provider development by making it accessible to Python developers worldwide, enabling them to leverage their existing skills and Python's rich ecosystem to build robust infrastructure automation tools.

✨ Why Choose Pyvider?

For Python Developers

  • 🐍 Native Python Experience: Write providers using familiar Python patterns and idioms
  • 📚 Rich Ecosystem: Access thousands of Python libraries for cloud APIs, databases, and services
  • 🎓 Gentle Learning Curve: No need to learn Go or complex protocol details
  • 🧪 Familiar Testing: Use pytest and your favorite Python testing tools

For Infrastructure Teams

  • ⚡ Rapid Development: Build providers 3-5x faster than traditional Go implementations
  • 🔒 Type Safety: Leverage Python's type hints and attrs for robust, maintainable code
  • 📊 Better Observability: Built-in structured logging with provide.foundation
  • 🚀 Production Ready: Battle-tested with comprehensive error handling and state management

For Organizations

  • 💼 Lower Barrier to Entry: Tap into your existing Python talent pool
  • 🔄 Faster Iteration: Quick prototyping and development cycles
  • 🎯 Focused Development: Decorators handle protocol complexity—teams focus on business logic
  • ✅ Enterprise Ready: Full Terraform compatibility with no compromises

📚 Documentation Overview

Our documentation is organized to help you quickly find what you need:

🚀 Getting Started

New to Pyvider? Start here! - Installation - Set up Pyvider in your environment - Quick Start - Build your first provider in 5 minutes - Pyvider Components - 100+ working examples

🏛️ Core Concepts

Understand Pyvider's foundation - Architecture - System design and data flow - Component Model - Hub-based discovery system - Schema System - Type-safe data modeling

📖 Developer Guides

Deep dives into building providers - Creating Providers - Provider configuration and lifecycle - Creating Resources - CRUD operations and state management - Creating Data Sources - Read-only data fetching - Creating Functions - Callable transformations - Testing Providers - Testing strategies and best practices - Best Practices - Production-ready patterns - Error Handling - Robust error management - Logging - Structured logging with foundation - Debugging - Troubleshooting providers - Security Best Practices - Secure provider development - Performance Optimization - Building fast providers

🎓 Examples & Tutorials

Learn by building real providers - Quick Start Guide - Build your first provider in 5 minutes - Building an HTTP API Provider - Intermediate tutorial - Pyvider Components Examples - 100+ working examples - Resources: file_content, local_directory, timed_token - Data Sources: env_variables, http_api, lens_jq - Functions: String, numeric, and JQ operations

📘 API Reference

Complete API documentation - Schema API - Attributes, blocks, and validation - CLI Commands - Command-line interface reference - Common Types - Type system reference

📦 Schema System

Type-safe data modeling - Overview - Schema system introduction - Types - Available schema types - Attributes - Attribute definitions - Blocks - Nested blocks - Validators - Input validation

🔌 Capabilities (Experimental)

Planned composition mechanism for code reuse - Overview - Experimental capabilities system (not fully implemented) - For working code reuse patterns, see Best Practices

🤝 Contributing

Join the Pyvider community - Contribution Guidelines - How to contribute - Code of Conduct - Community standards

🔮 Development

Project roadmap and planned features - Roadmap - Future features and CLI commands

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.

🎯 Quick Navigation

By Component Type

🏗️ Providers

📦 Resources

📊 Data Sources

⚡ Functions

By Task

📦 Ready-to-Use Components

Looking for pre-built components? Check out pyvider-components!

The pyvider-components repository provides a comprehensive collection of production-ready components:

  • Resources: file_content, local_directory, timed_token, and more
  • Data Sources: env_variables, file_info, http_api, lens_jq, and more
  • Functions: String manipulation, numeric operations, JQ transformations, and more
  • 100+ Working Examples: Complete Terraform configurations with documentation
  • Installation: pip install pyvider-components

Perfect for: - Learning by example - Quick prototyping - Production use - Understanding best practices

🚦 Prerequisites

Before diving into Pyvider, you should have:

  • Python 3.11+ installed
  • Basic understanding of Terraform concepts (providers, resources, state)
  • Familiarity with Python type hints and attrs (helpful but not required)
  • Git for version control

🛠️ Development Tools

Pyvider integrates seamlessly with modern Python development tools:

  • uv - Fast Python package manager (recommended)
  • pytest - Testing framework
  • mypy/pyright - Type checking
  • ruff - Fast Python linter and formatter
  • provide.foundation - Structured logging
  • flavor - Provider packaging tool

📊 Comparison with Traditional Providers

Feature Pyvider (Python) Traditional (Go)
Language Python 3.11+ Go
Learning Curve Gentle (Python devs) Steep
Development Speed Fast Moderate
Ecosystem Vast (PyPI) Growing
Type Safety Type hints + attrs Static typing
Testing pytest go test
Debugging Python debuggers delve
Performance Excellent Excellent
Protocol Support v6 (latest) v5/v6

🌟 Early Adopters

Pyvider is currently in alpha and being used by early adopters for:

  • Internal tooling: Building custom providers for company-specific infrastructure
  • Rapid prototyping: Testing provider concepts before committing to Go implementations
  • Python-first teams: Leveraging existing Python expertise for IaC
  • Educational projects: Teaching Terraform provider development concepts

🚀 Ready to Start?

📦 Install Pyvider 🚀 Quick Start Guide 📚 Browse Examples

💬 Community & Support

Note: As an alpha project, the best way to get support is through GitHub Issues and Discussions.

📈 Project Status

  • Current Version: 0.0.1000 (Alpha)
  • Protocol Version: Terraform Plugin Protocol v6
  • Python Support: 3.11+
  • License: Apache 2.0
  • Status: Alpha - Under Active Development
  • Stability: API may change before 1.0 release
  • Documentation: Some features documented may not be fully implemented - check Roadmap

Made with ❤️ by the team at Provide