Configuration

Declare parameters on a class or function, expose them as a CLI, and apply overrides without threading configuration through every call.

python

from params_proto import proto

@proto
class Config:
    learning_rate: float = 0.001
    batch_size: int = 32

with proto.bind(learning_rate=0.01):
    print(Config.learning_rate)

Public entry point	Definition
`@proto`	proto
`@proto.cli`	cli
`@proto.prefix`	prefix_decorator
`proto.bind`	bind
`proto.parse`	parse
`proto.partial`	partial

proto exposes these helpers as attributes. The names below are their definitions in source. For decorator order and examples, see configuration patterns and CLI applications.

API index

Name	Kind	Defined in
`ProtoResult`	class	`params_proto.proto`
`ProtoWrapper`	class	`params_proto.proto`
`ptype`	class	`params_proto.proto`
`proto`	function	`params_proto.proto`
`cli_decorator`	function	`params_proto.proto`
`prefix_decorator`	function	`params_proto.proto`
`BindContext`	class	`params_proto.proto`
`bind`	function	`params_proto.proto`
`parse`	function	`params_proto.proto`
`cli`	function	`params_proto.proto`
`partial`	function	`params_proto.proto`

params_proto.proto

params-proto v3 API

Core decorators and functionality for declarative parameter management.

`ProtoResult`

classparams_proto.proto.ProtoResultSource ↗

ProtoResult(data: dict)

Result object that provides attribute access to function results.

Parameters

Parameter	Type / default	Description
`data`	`dict` required	—

`ProtoResult.init`

methodparams_proto.proto.ProtoResult.__init__Source ↗

ProtoResult.__init__(data: dict)

Parameters

Parameter	Type / default	Description
`data`	`dict` required	—

`ProtoWrapper`

classparams_proto.proto.ProtoWrapperSource ↗

ProtoWrapper(func: Callable, is_cli: bool = False, is_prefix: bool = False, prog: str = None)

Wrapper for proto-decorated functions.

Parameters

Parameter	Type / default	Description
`func`	`Callable` required	—
`is_cli`	`bool` = False	—
`is_prefix`	`bool` = False	—
`prog`	`str` = None	—

`ProtoWrapper.init`

methodparams_proto.proto.ProtoWrapper.__init__Source ↗

ProtoWrapper.__init__(func: Callable, is_cli: bool = False, is_prefix: bool = False, prog: str = None)

Parameters

Parameter	Type / default	Description
`func`	`Callable` required	—
`is_cli`	`bool` = False	—
`is_prefix`	`bool` = False	—
`prog`	`str` = None	—

`ptype`

classparams_proto.proto.ptypeSource ↗

class ptype(type)

Bases: type

Metaclass for proto-decorated classes that intercepts attribute access.

`proto`

functionparams_proto.proto.protoSource ↗

proto(cls_or_func: Callable = None, *, cli: bool = False, prefix: bool = False, prefix_name: str = None, prog: str = None)

Main proto decorator that converts a class or function into a proto config object.

Parameters

Parameter	Type / default	Description
`cls_or_func`	`Callable` = None	The class or function to decorate
`cli`	`bool` = False	If True, this is a CLI entry point (generates help)
`prefix`	`bool` = False	If True, creates a singleton instance with prefix in CLI
`prefix_name`	`str` = None	Custom prefix name (defaults to lowercase class/function name)
`prog`	`str` = None	Optional program name override for help generation (useful for testing)

Returns

Decorated class/function with attribute setting and calling support

`cli_decorator`

functionparams_proto.proto.cli_decoratorSource ↗

cli_decorator(cls_or_func)

Decorator for CLI entry points.

Parameters

Parameter	Type / default	Description
`cls_or_func`	`—` required	—

`prefix_decorator`

functionparams_proto.proto.prefix_decoratorSource ↗

prefix_decorator(cls_or_func = None, name: str = None)

Decorator for prefixed singleton configs.

Examples

python

@proto.prefix
class Config: ...

@proto.prefix("custom")
class Config: ...

Parameters

Parameter	Type / default	Description
`cls_or_func`	`—` = None	The class or function to decorate (or prefix name if called with string)
`name`	`str` = None	Optional custom prefix name (defaults to lowercase class/function name)

`BindContext`

classparams_proto.proto.BindContextSource ↗

BindContext(prev_state, **kwargs)

Context manager for parameter bindings that also works as a direct call.

Parameters

Parameter	Type / default	Description
`prev_state`	`—` required	—
`**kwargs`	`—` variadic	—

`BindContext.init`

methodparams_proto.proto.BindContext.__init__Source ↗

BindContext.__init__(prev_state, **kwargs)

Parameters

Parameter	Type / default	Description
`prev_state`	`—` required	—
`**kwargs`	`—` variadic	—

`bind`

functionparams_proto.proto.bindSource ↗

bind(**kwargs)

Bind parameter overrides.

Can be used as context manager:

python

with proto.bind(seed=42, **{"train.lr": 0.01}):
    result = main()

Or as direct call (sets global bindings):

python

proto.bind(seed=42, **{"train.lr": 0.01})
result = main()

Parameters

Parameter	Type / default	Description
`**kwargs`	`—` variadic	—

`parse`

functionparams_proto.proto.parseSource ↗

parse(func: Callable, **kwargs)

Parse overrides and call a function.

Parameters

Parameter	Type / default	Description
`func`	`Callable` required	The function to call
`**kwargs`	`—` variadic	Override values (can use dot notation)

Returns

Result of calling func with overrides applied

`cli`

functionparams_proto.proto.cliSource ↗

cli(obj: Any = None, *, prog: str = None)

Set up an object as a CLI entry point.

By default, subcommand attributes don't require prefix (--epochs works). If the subcommand class is decorated with @proto.prefix, prefix is required (--config.epochs).

Parameters

Parameter	Type / default	Description
`obj`	`Any` = None	The class, function, or Union type to setup as CLI. If None, returns a decorator.
`prog`	`str` = None	Optional program name override for help generation (useful for testing)

Returns

The object with CLI capabilities, or a decorator if obj is None

`partial`

functionparams_proto.proto.partialSource ↗

partial(config_class: Type, method: bool = False)

Decorator that injects parameter defaults from a config class into a function.

This allows you to define a plain class with type-annotated attributes and their defaults, then use those defaults to populate function parameters automatically.

Example

python

class Config:
  lr: float = 0.01
  batch_size: int = 32

@proto.partial(Config)
def train() -> None:
  print(f"Learning Rate: {Config.lr}")
  print(f"Batch Size: {Config.batch_size}")

# Supports direct attribute modification:
Config.lr = 0.001
train()  # Uses updated lr value

# Supports hyperparameter sweeps:
for Config.lr in [0.01, 0.001, 0.0001]:
  train()

Parameters

Parameter	Type / default	Description
`config_class`	`Type` required	A class with type-annotated attributes serving as parameter defaults
`method`	`bool` = False	If True, wraps as a method (for class methods)

Returns

Decorated function with config values injected as defaults