Configuration
Declare parameters on a class or function, expose them as a CLI, and apply overrides without threading configuration through every call.
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
ProtoResult(data: dict)Result object that provides attribute access to function results.
Parameters
| Parameter | Type / default | Description |
|---|---|---|
data | dictrequired | — |
ProtoResult.__init__
ProtoResult.__init__(data: dict)Parameters
| Parameter | Type / default | Description |
|---|---|---|
data | dictrequired | — |
ProtoWrapper
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 | Callablerequired | — |
is_cli | bool= False | — |
is_prefix | bool= False | — |
prog | str= None | — |
ProtoWrapper.__init__
ProtoWrapper.__init__(func: Callable, is_cli: bool = False, is_prefix: bool = False, prog: str = None)Parameters
| Parameter | Type / default | Description |
|---|---|---|
func | Callablerequired | — |
is_cli | bool= False | — |
is_prefix | bool= False | — |
prog | str= None | — |
ptype
class ptype(type)Metaclass for proto-decorated classes that intercepts attribute access.
proto
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
cli_decorator(cls_or_func)Decorator for CLI entry points.
Parameters
| Parameter | Type / default | Description |
|---|---|---|
cls_or_func | —required | — |
prefix_decorator
prefix_decorator(cls_or_func = None, name: str = None)Decorator for prefixed singleton configs.
Examples
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
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__
BindContext.__init__(prev_state, **kwargs)Parameters
| Parameter | Type / default | Description |
|---|---|---|
prev_state | —required | — |
**kwargs | —variadic | — |
bind
bind(**kwargs)Bind parameter overrides.
Can be used as context manager:
Or as direct call (sets global bindings):
Parameters
| Parameter | Type / default | Description |
|---|---|---|
**kwargs | —variadic | — |
parse
parse(func: Callable, **kwargs)Parse overrides and call a function.
Parameters
| Parameter | Type / default | Description |
|---|---|---|
func | Callablerequired | The function to call |
**kwargs | —variadic | Override values (can use dot notation) |
Returns
Result of calling func with overrides applied
cli
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
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
Parameters
| Parameter | Type / default | Description |
|---|---|---|
config_class | Typerequired | 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