PyModeller

PyModeller is a DevOps-oriented CLI tool designed to synchronize infrastructure requirements with Python application code. By utilizing a single YAML "Source of Truth," PyModeller automates the generation of Pydantic models, Peewee ORM classes, and .env templates, ensuring your configuration and database schemas never drift from your documentation.

Core Features

• Code Generation: Instant creation of typed Pydantic models or Peewee schemas from YAML.
• Traceable Settings: Automatically generates a BaseTraceableSettings class. All settings inherit from this, enabling data source tracking and native YAML loading capabilities.
• Environment Templates: Auto-generate .env.example files for seamless developer onboarding.
• Validation & Safety: Verify local .env files against specifications to catch errors before runtime.
• Drift Detection: Identify discrepancies between your YAML definitions and existing Python code.

Project Initialization & Core Models

By default, PyModeller looks for a py_modeller.yaml file in the root of your project. This file must contain two main sections: config and sections.

The 'General' Section

For Pydantic model generation, it is required to define a section named General. This section is used to generate the general_setting class, which serves as the primary configuration entry point.

• Centralized Access: This allows you to import the global configuration state from anywhere in your application.
• Project Metadata: It typically holds flags like LOCAL_DEV, N_THREADS, or global API keys.

Installation

Install the package using uv or pip:

 uv add pymodeller

Usage

The CLI provides four main commands to manage your development workflow:

1. Generate models

Generate typed Pydantic models or Peewee code for your project.

pymodeller codegen

2. Example Environment Generation

Generate a template .env.example file based on your YAML specification to help collaborators set up their environment.

pymodeller example

3. Environment Check

Validate your current .env file against the YAML specification to ensure all required variables are present and correctly formatted.

pymodeller check

4. Drift Detection

Check for "drift" between your YAML specification and the code already generated. This ensures that your Python models haven't fallen out of date.

pymodeller drift

CLI Command Reference

Data Loading & Specification

The project uses a structured YAML-to-Object mapping to manage environment variables and database schemas. The py_modeller.yaml acts as the Single Source of Truth, which is parsed into an EnvSpec instance.

Environment Data Model Specification (YAML)

This document defines the schema for the py_modeller.yaml file. This file is used by the loader.py to generate typed Python dataclasses and manage environment variables, settings, and database schemas.

Validation

The loading process includes a mandatory validate_no_duplicates() call which ensures:

1. No two environment variables share the same env_name.
2. No two Python attributes (aliases) collide within the same section.

Technical Specification

BaseTraceableSettings

Every generated settings class inherits from BaseTraceableSettings. This core class provides:

• Source Tracking: Maintains a record of where each setting value originated (Environment, YAML, or Default).
• YAML Loader: Built-in methods to populate settings directly from structured YAML files.

1. Global Config (config)

Defines the output paths for generated files.

2. Root Structure

The YAML must contain a top-level sections key which is a list of environment groups.

sections:
- name: "ExampleSection"
  variables: []

3. Section Schema (EnvSection)

4. Variable Specification (EnvVarSpec)

Supported Types

The loader normalizes the following types:

• Primitives: string, integer, number (float), boolean, datetime.
• Special: secret (shortcut for str + secret: true), path, list.
• Numpy Arrays: pnd.NpNDArrayUint8, pnd.NpNDArrayInt8, pnd.NpNDArrayFp32.

Note: We are actively working on expanding this list to support additional data types and specialized structures in future releases.

5. Database Specification (DBSpec)

Defined at the section level for Peewee/ORM metadata.

6. Database Field Specification (DBField)

Defined under the db_spec key within a variable.

Example Usage

sections:
- name: "Network"
  env_prefix: "NET"
  type: "settings"
  variables:
    - name: "host_address"
      type: "string"
      default: "0.0.0.0"
      alias: "serverHost"

- name: "UsersTable"
  type: "peewee"
  database:
    table_name: "app_users"
  variables:
    - name: "id"
      type: "integer"
      db_spec:
        primary_key: true
    - name: "api_key"
      type: "secret"
      required: true

Contributing

Contributions are welcome! We value your help in making PyModeller better.

Before you get started, please refer to our Contributing Guide for details on our development workflow, coding standards, and how to submit pull requests.

If you encounter a bug or have a feature request, feel free to open an issue.

License

This project is licensed under the MIT License.