Parsers

Parsers

This document describes the parsing system in pydantic-settings-export.

Overview

The parsing system is the foundation of pydantic-settings-export, responsible for:

1. Model Analysis

   • Extracts metadata from Pydantic models
   • Preserves type information
   • Maintains documentation
   • Handle inheritance

2. Type Management

   • Converts Python types to human-readable formats
   • Handles complex types (Union, Optional, etc)
   • Supports custom types
   • Preserves type constraints

3. Environment Integration

   • Processes environment variables
   • Handles prefixes and aliases
   • Supports nested configurations
   • Maintains variable hierarchy

4. Documentation Processing

   • Extracts docstrings and comments
   • Preserves formatting
   • Handles multi-line descriptions
   • Supports Markdown in documentation

Core Components

SettingsInfoModel

The central model that represents parsed settings:

class SettingsInfoModel:
    name: str  # Settings class name
    docs: str  # Class documentation
    env_prefix: str  # Environment variable prefix
    fields: list[FieldInfoModel]  # Settings fields
    child_settings: list[SettingsInfoModel]  # Nested settings

FieldInfoModel

Represents individual setting fields:

class FieldInfoModel:
    name: str  # Field name
    types: list[str]  # Field types
    default: str  # Default value
    description: str  # Field description
    examples: list[str]  # Example values
    aliases: list[str]  # Environment variable aliases
    deprecated: bool  # Deprecation status

Type Parsing

The system automatically converts Python types to human-readable formats:

Python Type	Parsed Format
str	"string"
int	"integer"
float	"number"
bool	"boolean"
list[str]	"array of strings"
dict[str, int]	"map of string to integer"
Union[str, int]	"string | integer"
Literal["a", "b"]	"'a' | 'b'"

See how these types are used in different output formats in Generators.

Special Features

Environment Variables

• Respects Pydantic's env_prefix setting
• Handles nested delimiters
• Supports multiple aliases
• Case conversion options

Nested Settings

• Recursive parsing of nested BaseSettings
• Maintains hierarchy information
• Proper prefix handling
• Documentation inheritance

Documentation

• Extracts docstrings
• Removes form feed characters
• Handles multi-line descriptions
• Preserves formatting

Default Values

• Handles complex default types
• Supports default factories
• Path normalization
• Special handling for collections

Usage Example

from pydantic_settings_export.models import SettingsInfoModel
from your_app.settings import AppSettings

# Parse settings model
settings_info = SettingsInfoModel.from_settings_model(
    AppSettings,
    global_settings=None,  # Optional PSESettings instance
    prefix="APP_",        # Optional prefix override
    nested_delimiter="_"  # Optional delimiter
)

# Access parsed information
print(f"Settings name: {settings_info.name}")
print(f"Environment prefix: {settings_info.env_prefix}")

for field in settings_info.fields:
    print(f"\nField: {field.name}")
    print(f"Type: {' | '.join(field.types)}")
    print(f"Default: {field.default}")
    print(f"Description: {field.description}")

Best Practices

1. Type Hints

   • Always use explicit type annotations
   • Prefer specific types to Any
   • Use appropriate container types

2. Documentation

   • Provide clear field descriptions
   • Include meaningful examples
   • Document deprecated fields

3. Environment Variables

   • Use consistent naming conventions
   • Set appropriate prefixes
   • Consider alias needs

4. Nested Settings

   • Structure logically
   • Maintain clear hierarchy
   • Use meaningful prefixes

Related Topics

• Configuration
• Generators