nshconfig v3

Typed Python configuration with editable drafts, live interpolation, and independent read-only snapshots. Config files, presets, and execution are ordinary Python modules and functions.

pip install 'nshconfig==3.0.0'

import nshconfig as C

class Pairformer(C.Config):
    c_z: int = C.interp(lambda c: c.root(Run).c_z)

class Run(C.Config):
    project: str
    run_name: str
    c_z: int = 128
    pairformer: Pairformer = Pairformer()

config = Run.draft()
config.project = "af3"
config.run_name = "wide"
config.c_z = 256
assert config.pairformer.c_z == 256

ready = config.finalize()
config.c_z = 384
assert ready.pairformer.c_z == 256
assert config.pairformer.c_z == 384

For short configs, Run(project="af3", run_name="wide", c_z=256) also creates an editable draft. Constructors have checked keyword signatures; .draft() permits required fields to be populated later. Both use .finalize() before execution.

Composition is Python

def wide(config: Run) -> None:
    config.c_z = 256

def experiment() -> Run:
    config = Run(project="af3", run_name="wide")
    wide(config)
    return config

# In your ordinary Python entry point:
# train(experiment().finalize())

The runnable AF3 example demonstrates shared model dimensions, presets, nested configs, and training-set/weight validation in a reduced configuration.

Validation and ownership

Writes defer validation. Reads validate requested values and their dependencies; declaration order does not matter. Use Pydantic Annotated metadata for field-local normalization and constraints, and @C.check for final cross-field checks:

from typing import Annotated

class Data(C.Config):
    batch_size: Annotated[int, C.Field(gt=0)] = 1
    train_sets: list[str] = ["pdb"]
    weights: list[float] = [1.0]

    @C.check
    def aligned(self) -> None:
        if len(self.train_sets) != len(self.weights):
            raise ValueError("train_sets and weights must align")

Explicit child assignment preserves identity and requires a single owner. Use .copy() for reuse. Declared defaults are copied automatically per parent. Plain incoming lists/dicts become managed containers; aliases read from a config stay live. Final snapshots and computed subtrees reject nested mutation at runtime.

The same schema type describes drafts and finals. ty, Pyright, and mypy check names and value types; completeness and read-only state are runtime guarantees. Managed list/dict values implement sequence/mapping interfaces and are not built-in list/dict instances. Arbitrary mutable opaque leaves are unsupported.

Python 3.10-3.14 and Pydantic 2.13 through the latest 2.x are supported. Install nshconfig[transport] for trusted cloudpickle transport of notebook-defined schemas. v3 is an intentional breaking redesign of v2.

See the design contract, the upgrade guide, the documentation for guides, and SKILL.md for agent usage.

Metadata

Release files for nshconfig 3.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nshconfig 3.0.0
File	Size	Uploaded
nshconfig-3.0.0.tar.gz	13.4 kB	Oct 12, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for nshconfig 3.0.0
File	Interpreter	ABI	Platform	Reset
nshconfig-3.0.0-py3-none-any.whl 14.7 kB Oct 12, 2026	Python 3	none	any	Details

Total release size: 28.0 kB

Release files / nshconfig-3.0.0.tar.gz

Download URL	nshconfig-3.0.0.tar.gz
Size	13.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`0573f3bbea11805e2dc49b99573bf8541450f1716ce383cc18cc28b0a53f9b19`
BLAKE2b-256 checksum How to use checksums	`e837a5ca20780f003ebe76998f32ed5265363873d897e517e1722cd17db68cfc`
Upload date	Oct 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / nshconfig-3.0.0-py3-none-any.whl

Download URL	nshconfig-3.0.0-py3-none-any.whl
Size	14.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`895dcebc5e090443e8d9f111d21b80c49393c6fc72f23f9c50aadb960c2825e0`
BLAKE2b-256 checksum How to use checksums	`0780c5f2c3cf4f19b809e6b114817375c4aec389a661ad8f95e893882d02485e`
Upload date	Oct 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`