🌊🪢 Pyvider CTY

Pure-Python implementation of the go-cty type system for Terraform tooling

pyvider.cty provides strong type validation and serialization capabilities for configuration data, designed to work seamlessly with Terraform providers and HashiCorp ecosystem tools.

✨ Key Features

• 🎯 Complete Type System - Full implementation of go-cty primitives, collections, and structural types
• 🔄 Cross-Language Compatibility - JSON/MessagePack serialization for Go interoperability
• ✅ Type-Safe Validation - Strong validation with detailed error messages
• 🏷️ Marks System - Attach metadata to values without modification
• 🧭 Path Navigation - Type-safe access to nested data structures
• 📚 Standard Library - Comprehensive collection of type functions

Quick Start

Note: pyvider-cty is in pre-release (v0.x.x). APIs and features may change before 1.0 release.

1. Install: uv add pyvider-cty
2. Follow the Getting Started guide.
3. See the Quick Example below.

Documentation

Comprehensive documentation is available in the docs/ directory:

• Getting Started - Quick start and installation guide
• User Guide - Complete guide to all features
• How-To Guides - Practical task-oriented guides
• API Reference - Complete API documentation

Or start with the documentation index.

Development

Quick Start

# Set up environment
uv sync

# Run common tasks
make test         # Run tests
make lint         # Check code
make format       # Format code
make help         # See all available targets

See AGENTS.md for detailed development instructions and architecture information.

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

License

Apache License 2.0. See LICENSE for details.

Overview

pyvider.cty is a pure-Python implementation of the go-cty type system, providing strong type validation and serialization capabilities for configuration data. It's designed to work seamlessly with Terraform providers and other HashiCorp ecosystem tools.

Key Features: Complete type system, cross-language compatibility via MessagePack, type-safe validation, marks system, path navigation, and comprehensive standard library.

Installation

uv add pyvider-cty

Quick Example

from pyvider.cty import CtyObject, CtyString, CtyNumber, CtyList

# Define a type schema
user_type = CtyObject(
    attribute_types={
        "name": CtyString(),
        "age": CtyNumber(),
        "hobbies": CtyList(element_type=CtyString()),
    },
    optional_attributes={"age"},
)

# Validate data
user_data = {"name": "Alice", "hobbies": ["reading", "hiking"]}
user_val = user_type.validate(user_data)

# Access validated data
print(f"Name: {user_val['name'].raw_value}")  # Output: Alice

Known Limitations

• Python 3.11+ Required: Due to modern type features and syntax used.
• Performance: The library is not optimized for performance-critical applications involving very large or deeply nested data structures. Performance is reasonable for typical use cases.

Copyright (c) provide.io LLC.