ghostconfig 0.1.0

A config system that is lazily validated as parameters are used

ghostconfig

A config system that is lazily validated as parameters are used.

Installation

pip install ghostconfig

Usage

Creating a config

import ghostconfig

# From a YAML file (OmegaConf interpolations supported)
config = ghostconfig.GhostConfig("path/to/config.yaml")

# From a JSON file
config = ghostconfig.GhostConfig("path/to/config.json")

# From a plain Python dict
config = ghostconfig.GhostConfig({"num_epochs": 10, "learning_rate": 0.001})

Reading values

get(key) with no default returns a GhostConfig sub-config (real or ghost). get(key, default) returns the leaf value (type inferred from the default).

# Given config.yaml:
# model:
#   layers: 4
#   block: resnet
# dataset:
#   path: my/data/
#   augmentations: [crop]

model_config = config.get("model")    # GhostConfig
layers = model_config.get("layers", 1)  # 4

# Accessing a key that doesn't exist in the YAML is fine at this point —
# a "ghost" GhostConfig is returned and the access is recorded.
training_config = config.get("training")
learning_rate = training_config.get("learning_rate", 0.001)  # returns 0.001

Validating at setup time

Call check() once all parameters have been read. It raises MissingConfigError with a suggestion showing exactly what to add to your config file.

config.check()
# MissingConfigError:
# The following parameters were used but missing from the config.
# Since this started from a yaml (path/to/config.yaml), you should add:
#
# training:
#   learning_rate: 0.001

If multiple keys are missing they are merged into a single suggestion block. The format matches the source: YAML for .yaml files, JSON for .json files, and a Python dict literal for dict-based configs.

Development

Setup

pip install -e ".[dev]"

Or install with test dependencies:

pip install pytest
pip install -e .

Running Tests

pytest

To run with verbose output:

pytest -v

Building and Publishing to PyPI

Prerequisites

pip install build twine

Build the distribution

python -m build

This creates a dist/ directory containing a .whl and .tar.gz file.

Upload to PyPI

First, upload to TestPyPI to verify everything looks correct:

twine upload --repository testpypi dist/*

When ready, upload to the real PyPI:

twine upload dist/*

You will be prompted for your PyPI credentials. It is recommended to use an API token instead of your password.

To avoid entering credentials each time, create a ~/.pypirc file:

[pypi]
  username = __token__
  password = pypi-your-api-token-here