proto module

The proto module contains the core classes for defining and managing parameters in params-proto.

Core Classes

ParamsProto

The main base class for creating parameter configurations. Inherit from this class to define your parameter schemas.

class params_proto.v2.ParamsProto

Bases: Bear

Key Methods

• parse(): Parse command-line arguments and update parameter values

• to_dict(): Convert the configuration to a dictionary

• _update(): Update parameter values programmatically

• __vars__: Property that returns nested dictionary representation

Usage Example

from params_proto.v2.proto import ParamsProto, Proto, Flag

class Config(ParamsProto):
    learning_rate = Proto("Learning rate", default=0.001)
    debug = Flag("Enable debug mode", default=False)

# Parse command line arguments
Config.parse()

# Access parameters
print(Config.learning_rate)  # 0.001
print(Config.debug)         # False

Proto

Defines a parameter with type, default value, help text, and environment variable support.

class params_proto.v2.proto.Proto

Bases: SimpleNamespace

default = None

help = None

dtype = None

property value

Parameters

• default: Default value for the parameter

• help: Help text displayed in CLI

• dtype: Type of the parameter (inferred from default if not specified)

• env: Environment variable name to read default from

• strict_parsing: Whether to raise error for unset environment variables

Usage Examples

# Basic parameter
name = Proto("Model name", default="resnet50")

# With type specification
epochs = Proto("Training epochs", default=100, dtype=int)

# With environment variable
data_path = Proto("Data directory", default="${DATA_DIR:/tmp/data}")

# With strict environment parsing
api_key = Proto("API key", env="API_KEY", strict_parsing=True)

Flag

A boolean parameter that can be enabled/disabled from command line.

class params_proto.v2.proto.Flag

Bases: Proto

Parameters

• help: Help text for the flag

• to_value: Value when flag is enabled (default: True)

• default: Default value when flag is not specified

Usage Examples

# Basic flag
debug = Flag("Enable debug logging")

# Custom flag value
verbose = Flag("Verbose output", to_value=2, default=0)

# Usage from command line:
# --Config.debug        # Sets debug=True
# --no-Config.debug     # Sets debug=False
# --Config.verbose      # Sets verbose=2

Utility Classes

PrefixProto

A ParamsProto with automatic prefix generation for nested configurations.

class params_proto.v2.proto.PrefixProto

Bases: ParamsProto

A ParamsProto class with prefix set to True.

Since we override the __init_subclass__ method, the returned classes instance is still a ParamsProto class. NOT a PrefixProto class.

Meta

The metaclass that powers ParamsProto functionality.

class params_proto.v2.proto.Meta

Bases: type

Advanced Features

Environment Variable Support

Proto supports reading default values from environment variables:

# Using environment variables
database_url = Proto("Database URL", env="DATABASE_URL")
debug_level = Proto("Debug level", env="DEBUG_LEVEL", dtype=int, default=0)

# With variable expansion
log_dir = Proto("Log directory", default="${HOME}/logs")

Nested Configurations

Create hierarchical parameter structures:

class DatabaseConfig(ParamsProto):
    host = Proto("Database host", default="localhost")
    port = Proto("Database port", default=5432)

class Config(ParamsProto):
    database = DatabaseConfig
    app_name = Proto("Application name", default="myapp")

Custom Validation

Override methods to add custom validation:

class Config(ParamsProto):
    learning_rate = Proto("Learning rate", default=0.001)
    
    @classmethod
    def validate(cls):
        assert 0 < cls.learning_rate < 1, "Learning rate must be between 0 and 1"

Complete Module Reference

params_proto.v2.proto.copy(x)

Shallow copy operation on arbitrary Python objects.

See the module’s __doc__ string for more info.

params_proto.v2.proto.cleandoc(doc)

Clean up indentation from docstrings.

Any whitespace that can be uniformly removed from the second line onwards is removed.

params_proto.v2.proto.warn()

Issue a warning, or maybe ignore it or raise an exception.

message

Text of the warning message.

category

The Warning category subclass. Defaults to UserWarning.

stacklevel

How far up the call stack to make this warning appear. A value of 2 for example attributes the warning to the caller of the code calling warn().

source

If supplied, the destroyed object which emitted a ResourceWarning

skip_file_prefixes

An optional tuple of module filename prefixes indicating frames to skip during stacklevel computations for stack frame attribution.

params_proto.v2.proto.all_available(template: str, strict=True) → bool

Check if all environment variables in the template are available in the current environment.

Parameters:

• template (str) – A string template that potentially contains environment variables in the format $VAR_NAME, ${VAR_NAME}, or similar.

• strict – If True, treat empty environment variables as undefined. Otherwise, treat them as defined.

Returns:

True if all environment variables are available, False otherwise.

Return type:

bool

params_proto.v2.proto.dot_to_deps(dot_dict, *prefixes)

class params_proto.v2.proto.Accumulant

Bases: Proto

used by neo_hyper to avoid reset.

accumulant = True

__init__(*args, **kwargs)

The proto object. The env attribute allows one to set the environment variable from which this proto reads value from.

Parameters:

• default

• help

• dtype

• metavar

• env – the environment variable for the default value – in the next version could be set automatically from the prefix of the class.

• strict_parsing – default to False, when true raises error for env var that are not set. this is passed onto the expandvars function as nounset.

• kwargs

class params_proto.v2.proto.StrType

Bases: type

thunk = None

help = None

class params_proto.v2.proto.Eval

Bases: Proto

thunk = None

__init__(default, help=None, **kwargs)

The proto object. The env attribute allows one to set the environment variable from which this proto reads value from.

Parameters:

• default

• help

• dtype

• metavar

• env – the environment variable for the default value – in the next version could be set automatically from the prefix of the class.

• strict_parsing – default to False, when true raises error for env var that are not set. this is passed onto the expandvars function as nounset.

• kwargs

params_proto.v2.proto.is_private(k: str) → bool

Filter Private Attributes.

Args:

k: <str> the key to be tested.

Returns True if key equals “_prefix”, or starts with “__” or “_<ParentClass>_”

Parameters:

k (str)

Return type:

bool

params_proto.v2.proto.get_children(__init__)

decorator to parse the dependencies into current scope, using the cls._prefix attribute of the namespace.

Allows one to use _prefix to override to original class._prefix

class params_proto.v2.proto.ArgFactory

Bases: object

The reason we do not inherit from argparse, is because the argument group returns new instances, so unless we patch those classes as well, we will not be able to intercept these calls. (I tried that first.)

For this reason we implement this as a funciton, with a stateful context.

groups = {}

last_group = None

__init__()

clear()

Initialize self. See help(type(self)) for accurate signature.

add_argument(proto, key, *name_or_flags, _argument_group=None, default=None, dtype=None, to_value=None, **kwargs)

add_argument_group(name, description)

parse_args(*args)

params_proto.v2.proto.find_ancestors(cls)

Find all ancestors of a class.

Args:

cls:

Returns:

params_proto.v2.proto.is_subclass(cls, *, ancestors=(<class 'params_proto.v2.proto.ParamsProto'>, <class 'params_proto.v2.proto.PrefixProto'>), extra=())

params_proto.v2.proto.is_base_class(cls, extra=())

Check if a class is a base class of ParamsProto.

Args:

cls:

Returns:

params_proto.v2.proto.update(Config: type | Meta | ParamsProto, override)

Update a ParamsProto namespace, or instance

by the override dictionary. Note the dictionary

is dot.separated

dot-keys are not yet implemented.

Args:

Config: override:

Returns:

Parameters:

Config (type | Meta | ParamsProto)