import "../autodoc.css"
# 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](#params_proto.proto--proto) |
| `@proto.cli` | [cli](#params_proto.proto--cli) |
| `@proto.prefix` | [prefix_decorator](#params_proto.proto--prefix_decorator) |
| `proto.bind` | [bind](#params_proto.proto--bind) |
| `proto.parse` | [parse](#params_proto.proto--parse) |
| `proto.partial` | [partial](#params_proto.proto--partial) |
`proto` exposes these helpers as attributes. The names below are their definitions in source. For decorator order and examples, see [configuration patterns](/key_concepts/configuration-patterns) and [CLI applications](/examples/cli_applications).
## API index
| Name | Kind | Defined in |
| --- | --- | --- |
| [`ProtoResult`](/reference/configuration#params_proto.proto--protoresult) | class | `params_proto.proto` |
| [`ProtoWrapper`](/reference/configuration#params_proto.proto--protowrapper) | class | `params_proto.proto` |
| [`ptype`](/reference/configuration#params_proto.proto--ptype) | class | `params_proto.proto` |
| [`proto`](/reference/configuration#params_proto.proto--proto) | function | `params_proto.proto` |
| [`cli_decorator`](/reference/configuration#params_proto.proto--cli_decorator) | function | `params_proto.proto` |
| [`prefix_decorator`](/reference/configuration#params_proto.proto--prefix_decorator) | function | `params_proto.proto` |
| [`BindContext`](/reference/configuration#params_proto.proto--bindcontext) | class | `params_proto.proto` |
| [`bind`](/reference/configuration#params_proto.proto--bind) | function | `params_proto.proto` |
| [`parse`](/reference/configuration#params_proto.proto--parse) | function | `params_proto.proto` |
| [`cli`](/reference/configuration#params_proto.proto--cli) | function | `params_proto.proto` |
| [`partial`](/reference/configuration#params_proto.proto--partial) | function | `params_proto.proto` |
## params_proto.proto
params-proto v3 API
Core decorators and functionality for declarative parameter management.
### `ProtoResult`
class
params_proto.proto.ProtoResult
Source ↗
ProtoResult(data: dict)
Result object that provides attribute access to function results.
Parameters
| Parameter | Type / default | Description |
|---|
data | dict
required | — |
method
params_proto.proto.ProtoResult.__init__
Source ↗
ProtoResult.__init__(data: dict)
Parameters
| Parameter | Type / default | Description |
|---|
data | dict
required | — |
### `ProtoWrapper`
class
params_proto.proto.ProtoWrapper
Source ↗
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 | — |
method
params_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`
class ptype(type)
Bases: type
Metaclass for proto-decorated classes that intercepts attribute access.
### `proto`
function
params_proto.proto.proto
Source ↗
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
function
params_proto.proto.cli_decorator
Source ↗
cli_decorator(cls_or_func)
Decorator for CLI entry points.
Parameters
| Parameter | Type / default | Description |
|---|
cls_or_func | —
required | — |
function
params_proto.proto.prefix_decorator
Source ↗
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) |
class
params_proto.proto.BindContext
Source ↗
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 | — |
method
params_proto.proto.BindContext.__init__
Source ↗
BindContext.__init__(prev_state, **kwargs)
Parameters
| Parameter | Type / default | Description |
|---|
prev_state | —
required | — |
**kwargs | —
variadic | — |
### `bind`
function
params_proto.proto.bind
Source ↗
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 | — |
function
params_proto.proto.parse
Source ↗
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
function
params_proto.proto.cli
Source ↗
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
function
params_proto.proto.partial
Source ↗
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