loadstructure

A versatile Python library for loading and managing configuration files (JSON, YAML, XML, TOML, and INI/DEF-style) with attribute-style access, merging capabilities.

✨ Features

• Multiple Formats: Load configurations from JSON, YAML, XML, TOML, and INI/DEF files.
• Attribute Access: Access settings using dot notation (e.g., config.server.port).
• Auto-Creation: Automatically creates nested keys if they do not exist.
• Schema Validation: Enforce types and structure with optional schema support.
• Merging: Merge multiple configuration files, with later files overriding earlier settings.
• Update & Replace: Update partial configs with .update() or replace entire configs with .replace().
• Saving: Save your configuration back to the original or new file format.

Installation

Using uv:

uv add loadstructure

Using pip

pip install loadstructure

📦 Dependencies

The following dependencies are required and will be installed automatically if you use standard Python packaging practices:

• YAML: pyyaml >=6.0.3
• TOML: toml >=0.10.2
• XML: xmltodict >=1.0.2

📖 Usage

Basic Loading

Instantiate ConfigManager with the path to your config file and call .load().

config.json:

{
  "app": {
    "name": "App",
    "version": "1.0.0",
    "features": {
      "login": true,
      "analytics": false,
      "dark_mode": true,
      "notifications": true
    },
    "ui": {
      "theme": "light",
      "language": "en"
    }
  },
  "modules": {
    "editor": {
      "enabled": true,
      "autosave_interval": 5
    },
    "export": {
      "formats": ["pdf", "html", "md"],
      "compress_output": false
    }
  }
}

Load a configuration file

from loadstructure import ConfigManager

config = ConfigManager("app_config.json")
cfg = config.load()

# Attribute-style access
print(cfg.app.name)                       # App
print(cfg.app.ui.theme)                   # light
print(cfg.modules.editor.autosave_interval)  # 5

# Dictionary-style access
print(cfg["app"]["features"]["dark_mode"])  # True

Nested key access using dotted paths

theme = cfg.get("app.ui.theme")
print(theme)  # light

Schema validation

config = ConfigManager("config.json", schema={
    "app": {"name": str, "version": str},
    "modules": dict
})
cfg = config.load()

cfg.app.name = "MyApp"  # valid
cfg.app.version = 2      # raises SchemaError because type must be str

Updating and replacing configurations

# Update part of the config
cfg.update({
    "app": {
        "version": "1.1.0"
    }
})

# Replace entire config
cfg.replace({
    "app": {
        "name": "NewApp",
        "version": "2.0.0"
    }
})

Modifying and saving values

cfg.app.features.analytics = True
cfg.modules.export.compress_output = True
fg.app.tech = {
    'frontend':'(html,css,js)',
    'backend':'electron'
}

# Save changes back to JSON
config.save()

Merging multiple configuration files

# app_config_override.json can override some settings
merged_cfg = ConfigManager.merge(["app_config.json", "app_config_override.json"])
print(merged_cfg.app.features.analytics)

License

This project is licensed under the MIT License for full details.