dataclass-dsl 1.0.1

Dataclass runtime machinery for declarative DSLs

dataclass-dsl

Build declarative Python DSLs where infrastructure and configuration look like this:

from . import *

class LogBucketEncryption:
    resource: s3.Bucket.BucketEncryption
    server_side_encryption_configuration = [LogBucketEncryptionRule]

class LogBucket:
    resource: s3.Bucket
    bucket_encryption = LogBucketEncryption
    public_access_block_configuration = LogBucketPublicAccessBlock
    versioning_configuration = LogBucketVersioning

No decorators. No function calls. No boilerplate.

The Pattern

Domain packages built on dataclass-dsl share three properties:

Property	What it means
Single import	from . import * — everything available, loaded in dependency order
Zero decorators	Classes are plain declarations, machinery is invisible
Flat wrappers	Each class wraps a resource type with simple attribute assignments

The result reads like configuration, but with full Python power: IDE autocomplete, type checking, refactoring, and the ability to use variables, loops, and conditionals when needed.

What This Enables

Reference other resources by class name:

class AppSubnet:
    resource: Subnet
    vpc = AppVPC                    # Reference to another resource
    cidr_block = "10.0.1.0/24"

Reference specific attributes:

class LambdaFunction:
    resource: Function
    role_arn = ExecutionRole.Arn    # Gets the Arn of ExecutionRole

Compose nested configurations:

class BucketEncryption:
    resource: s3.Bucket.BucketEncryption
    server_side_encryption_configuration = [EncryptionRule]

class MyBucket:
    resource: s3.Bucket
    bucket_encryption = BucketEncryption

Use lists and maps of references:

class LoadBalancer:
    resource: ALB
    subnets = [SubnetA, SubnetB, SubnetC]
    security_groups = [WebSecurityGroup]

How It Works

dataclass-dsl provides the runtime machinery that makes this pattern possible:

• Automatic dependency detection — References between classes are detected at runtime
• Topological ordering — Resources are serialized in dependency order
• Multi-file support — setup_resources() loads files in the right order, enabling from . import *
• IDE stub generation — Full autocomplete and type checking despite dynamic imports

Domain packages use these primitives to create decorators and loaders that are invisible to end users.

Installation

uv add dataclass-dsl

Using a Domain Package

If you're using a domain package built on dataclass-dsl (like an AWS CDK alternative or Kubernetes manifest generator), follow that package's documentation. You'll write clean declarative classes without needing to understand the internals.

Building a Domain Package

If you're creating a domain package, see the Internals Guide for:

• Creating a domain-specific decorator with create_decorator()
• Setting up multi-file packages with setup_resources()
• Implementing a Provider for your target format
• Generating IDE stubs for from . import *

Also see the AWS S3 example to see what a domain package produces.

Documentation

• Core Concepts — The wrapper pattern, references, and templates
• Internals Guide — Building domain packages
• Specification — Formal specification
• CLI Framework — CLI utilities for domain packages

License

MIT