Skip to content

Welcome to Pyvider CTY

A powerful and flexible type system for Python, compatible with HashiCorp's go-cty.

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.

Alpha Software - Active Development

pyvider-cty is in active alpha development. APIs may change, and some features are experimental.

  • Current version: v0.0.1026
  • Status: Alpha (Development Status: 3)
  • Production use: Use with caution

Part of the pyvider framework ecosystem.

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.

When to Use Pyvider CTY

✅ Use pyvider-cty when:

  • Building Terraform providers in Python - You're developing custom providers using pyvider
  • Working with HCL configurations - You need to parse and validate HCL data in Python
  • Type-safe value handling - You require Terraform-compatible type validation
  • Implementing Terraform-like tools - You're building infrastructure tools that need cty compatibility
  • Cross-language interoperability - You need MessagePack serialization compatible with go-cty
  • Terraform data structures - You're working with Terraform values programmatically

❌ Don't use pyvider-cty when:

  • General JSON/YAML parsing → Use standard Python libraries (json, pyyaml)
  • Building non-Terraform tools → Use native Python types (dict, list, etc.)
  • Don't need Terraform compatibility → Simpler type systems will be easier
  • Simple data validation → Consider pydantic or attrs for general validation
  • No HCL/Terraform involvement → The cty type system is specifically for Terraform

Typical Users

1. Terraform Provider Developers - Building providers with the pyvider framework - pyvider-cty is automatically included as a dependency - Handles type conversion and validation behind the scenes

2. HCL Tool Developers - Creating tools that read/write Terraform configurations - Need type-safe parsing of HCL values - Require validation against Terraform schemas

3. Infrastructure Engineers - Working with Terraform values programmatically - Building automation around Terraform configurations - Need to parse and manipulate Terraform state/plans

4. DevOps Tool Authors - Creating linters, validators, or analyzers for Terraform - Building custom Terraform configuration generators - Developing infrastructure testing tools

  • Using pyvider? → pyvider-cty is automatically included, no separate installation needed
  • Need HCL parsing? → See pyvider-hcl for HCL string parsing with cty integration
  • Building providers? → See pyvider for the full provider framework
  • View ecosystem? → See Ecosystem Overview for how all projects relate

Why Pyvider CTY?

⚡ Expressive and Flexible

  • Rich Type System: A comprehensive set of primitive, collection, and structural types to model your data accurately.
  • Dynamic Types: Handle data with unknown or varying structures using the dynamic type.
  • Capsule Types: Encapsulate and protect foreign data types within the cty system.

🛠️ Developer Experience

  • Modern Python: Leverages Python 3.11+ features with complete type annotations.
  • Clear and Concise API: A simple and intuitive API for defining types, validating data, and working with values.
  • Detailed Diagnostics: Get detailed error messages and validation diagnostics to quickly identify and fix issues.

🏗️ Robust and Reliable

  • Immutable Values: cty values are immutable, ensuring data integrity and preventing unintended side effects.
  • Thoroughly Tested: A comprehensive test suite ensures the library is reliable and production-ready.
  • Battle-Tested Concepts: Based on the well-established cty type system from HashiCorp's Terraform.

🔄 Cross-Language Compatibility

  • Go-Cty Interoperability: Serialize and deserialize data in MessagePack format compatible with go-cty.
  • Terraform Integration: Parse Terraform type strings and work with Terraform data structures.

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)
print(f"Name: {user_val['name'].raw_value}")

Where to Start

  • Getting Started

    Install pyvider.cty and learn the basics in 5 minutes

  • User Guide

    Comprehensive guide to types, values, and advanced features

  • How-To Guides

    Practical guides for common tasks and use cases

  • API Reference

    Complete API documentation for all types and functions

Installation

# With uv (recommended)
uv add pyvider-cty

# With pip
pip install pyvider-cty

Features at a Glance

  • 🎯 Complete Type System: Primitives, collections, and structural types
  • 🔄 Cross-Language Compatibility: Interoperates with go-cty via MessagePack
  • 🛡️ Type Safety: Strong validation at value creation
  • 🏷️ Marks System: Attach metadata without modifying values
  • 🗺️ Path Navigation: Type-safe access to nested data
  • ⚡ Full Standard Library: Comprehensive suite of functions for data manipulation

Community and Support

License

Apache License 2.0. See LICENSE for details.