Configuration Formats

nshconfig supports multiple formats for creating and serializing configurations, making it flexible for different use cases.

Python File/Module Support

nshconfig supports loading configurations directly from Python files and modules:

from mypackage import ModelConfig

# Load from Python file
config1 = ModelConfig.from_python_file("model_config.py")

# Load from Python module
config2 = ModelConfig.from_python_module("myapp.configs.model")

The Python file or module should export either:

• A __config__ variable containing an instance of the configuration class

• A __create_config__ function that returns an instance of the configuration class

Example configuration file:

# model_config.py
from mypackage import ModelConfig

# Option 1: Using __config__ variable
__config__ = ModelConfig(
    hidden_size=256,
    num_layers=4
)

# Option 2: Using __create_config__ function
def __create_config__():
    return ModelConfig(
        hidden_size=256,
        num_layers=4
    )

JSON Support

You can create and save configurations using JSON:

import nshconfig as C

class ModelConfig(C.Config):
    hidden_size: int
    num_layers: int

# Create from JSON string
config1 = ModelConfig.from_json_str('{"hidden_size": 256, "num_layers": 4}')

# Load from JSON file
config2 = ModelConfig.from_json_file("model_config.json")

# Save to JSON string
json_str = config1.to_json_str()

# Save to JSON file
config1.to_json_file("model_config.json")

YAML Support

YAML support requires installing the pydantic-yaml package:

pip install "nshconfig[extra]"  # Installs all extras
pip install "nshconfig[yaml]"   # Installs only the YAML extra
pip install pydantic-yaml       # Or install directly

Then you can work with YAML formats:

class ModelConfig(C.Config):
    hidden_size: int
    num_layers: int

# Create from YAML string
config1 = ModelConfig.from_yaml_str("""
hidden_size: 256
num_layers: 4
""")

# Load from YAML file
config2 = ModelConfig.from_yaml("model_config.yaml")

# Save to YAML string
yaml_str = config1.to_yaml_str()

# Save to YAML file
config1.to_yaml_file("model_config.yaml")

Type-Safe Adapters

For more fine-grained control over configuration conversion and validation, nshconfig provides a type-safe Adapter class that wraps Pydantic’s TypeAdapter functionality. While Config classes provide their own serialization methods, the Adapter class allows you to validate and serialize any type - including complex nested types and non-Config types:

from nshconfig import Config
from nshconfig.adapter import Adapter

class ModelConfig(Config):
    hidden_size: int
    num_layers: int

# Create adapters for different types
model_adapter = Adapter(ModelConfig)
tuple_adapter = Adapter(tuple[ModelConfig, int, str])
dict_adapter = Adapter(dict[str, ModelConfig])

# Validate and convert different data structures
config = model_adapter.from_dict({
    "hidden_size": 256,
    "num_layers": 4
})

# Validate tuple of (ModelConfig, int, str)
validated = tuple_adapter.from_dict([
    {"hidden_size": 256, "num_layers": 4},
    42,
    "hello"
])

# Validate dictionary of ModelConfigs
configs = dict_adapter.from_dict({
    "model1": {"hidden_size": 256, "num_layers": 4},
    "model2": {"hidden_size": 512, "num_layers": 8}
})

The adapter provides type-safe conversion between different formats while maintaining all validation rules. This is particularly useful when you need to:

• Load configuration files in different formats

• Save configuration state to disk

• Convert between different representations of your data while ensuring type safety

• Validate external data against complex types

• Work with collections of configurations

Each conversion method accepts additional parameters to customize the serialization/deserialization process, such as excluding certain fields, handling defaults, or controlling validation strictness. See Pydantic’s TypeAdapter documentation for more details on the underlying functionality.

Schema References

When saving to JSON or YAML, you can include schema references that enable better IDE support:

# Include schema reference in JSON
config.to_json_file("config.json", with_schema=True)

# Include schema reference in YAML
config.to_yaml_file("config.yaml", with_schema=True)

The schema references help IDEs provide autocompletion and validation when editing the configuration files.