backtrader.parameters module

New Parameter System for Backtrader

This module implements a modern parameter system that replaces the metaclass-based parameter handling with descriptor-based approach. This provides better type safety, validation, and maintainability while maintaining backward compatibility.

Key Components: - ParameterDescriptor: Core descriptor for parameter handling - ParameterManager: Parameter storage and management - ParameterizedBase: Base class for parameterized objects (without metaclass) - Type checking and validation mechanisms - Python 3.6+ __set_name__ support

class backtrader.parameters.ParameterDescriptor

基类：object

Advanced parameter descriptor with type checking and validation.

This descriptor replaces the metaclass-based parameter system with a more modern and maintainable approach. It provides:

• Automatic type checking and conversion

• Value validation

• Default value handling

• Documentation support

• Python 3.6+ __set_name__ support

__init__(default=None, type_=None, validator=None, doc=None, name=None, required=False)

Initialize parameter descriptor.

参数:

• default (Any) -- Default value for the parameter

• type -- Expected type for the parameter (enables type checking)

• validator (Callable[[Any], bool] | None) -- Function to validate parameter values

• doc (str | None) -- Documentation string for the parameter

• name (str | None) -- Parameter name (usually set by __set_name__)

• required (bool) -- Whether this parameter is required (no default allowed)

• type_ (Type | None)

__set_name__(owner, name)

Called when the descriptor is assigned to a class attribute. This is a Python 3.6+ feature that automatically sets the parameter name.

__get__(obj, objtype=None)

Get parameter value from object instance.

__set__(obj, value)

Set parameter value on object instance with validation.

__delete__(obj)

Delete parameter value, reverting to default.

validate(value)

Validate a value for this parameter.

参数:

value (Any) -- Value to validate

返回:

True if value is valid, False otherwise

返回类型:

bool

get_type_info()

Get type information for this parameter.

返回类型:

Dict[str, Any]

class backtrader.parameters.ParameterManager

基类：object

Enhanced Parameter storage and management system.

This class manages parameter values for an object, replacing the functionality of AutoInfoClass. It provides efficient storage, inheritance support, batch operations, and advanced features like change tracking, callbacks, and transactional updates.

New Features in Day 32-33: - Parameter change history and tracking - Change callbacks and notifications - Parameter locking mechanism - Parameter groups for organization - Advanced inheritance with conflict resolution - Lazy default value evaluation - Transactional batch updates

__init__(descriptors, initial_values=None, enable_history=True, enable_callbacks=True)

Initialize parameter manager.

参数:

• descriptors (Dict[str, ParameterDescriptor]) -- Dictionary of parameter descriptors

• initial_values (Dict[str, Any] | None) -- Initial parameter values

• enable_history (bool) -- Whether to track parameter change history

• enable_callbacks (bool) -- Whether to enable change callbacks

get(name, default=None, _MISSING=<object object>)

Get parameter value with optimized caching and lazy evaluation support.

参数:

• name (str) -- Parameter name

• default (Any) -- Default value if parameter not found

返回:

Parameter value

返回类型:

Any

set(name, value, force=False, trigger_callbacks=True, skip_validation=False)

Set parameter value with validation and dependency updates.

参数:

• name (str) -- Parameter name

• value (Any) -- Parameter value

• force (bool) -- Force setting even if parameter is locked

• trigger_callbacks (bool) -- Whether to trigger change callbacks

• skip_validation (bool) -- Skip validation (use with caution)

返回类型:

None

reset(name, force=False)

Reset parameter to its default value.

参数:

• name (str) -- Parameter name

• force (bool) -- Force reset even if parameter is locked

返回类型:

None

update(values, force=False, validate_all=True)

Update multiple parameters at once.

参数:

• values (Dict[str, Any] | ParameterManager) -- Dictionary of parameter values or another ParameterManager

• force (bool) -- Force update even for locked parameters

• validate_all (bool) -- Validate all parameters before updating any

返回类型:

None

to_dict()

Convert parameter manager to dictionary.

返回:

Dictionary of current parameter values

返回类型:

Dict[str, Any]

keys()

Get parameter names.

items()

Get parameter name-value pairs.

values()

Get parameter values.

copy()

Create a copy of this parameter manager.

返回:

New ParameterManager instance with same values

返回类型:

ParameterManager

inherit_from(parent, strategy='merge', conflict_resolution='parent', selective=None)

Inherit parameters from another ParameterManager.

参数:

• parent (ParameterManager) -- Parent ParameterManager to inherit from

• strategy (str) -- Inheritance strategy ('merge', 'replace', 'add_only', 'selective')

• conflict_resolution (str) -- How to resolve conflicts ('parent', 'child', 'error', 'raise')

• selective (List[str] | None) -- Only inherit specific parameters (list of names)

返回类型:

None

get_inheritance_info(name)

Get inheritance information for a parameter.

参数:

name (str) -- Parameter name

返回:

Dictionary with inheritance information, or None if not available

返回类型:

Dict[str, Any] | None

lock_parameter(name)

Lock a parameter to prevent modification.

参数:

name (str)

返回类型:

None

unlock_parameter(name)

Unlock a parameter to allow modification.

参数:

name (str)

返回类型:

None

is_locked(name)

Check if a parameter is locked.

参数:

name (str)

返回类型:

bool

get_locked_parameters()

Get list of locked parameter names.

返回类型:

List[str]

create_group(group_name, param_names)

Create a parameter group.

参数:

• group_name (str) -- Name of the group

• param_names (List[str]) -- List of parameter names to include in the group

返回类型:

None

get_group(group_name)

Get parameter names in a group.

参数:

group_name (str)

返回类型:

List[str]

get_parameter_group(param_name)

Get the group name for a parameter.

参数:

param_name (str)

返回类型:

str | None

set_group(group_name, values)

Set values for all parameters in a group.

参数:

• group_name (str)

• values (Dict[str, Any])

返回类型:

None

get_group_values(group_name)

Get values for all parameters in a group.

参数:

group_name (str)

返回类型:

Dict[str, Any]

set_lazy_default(name, lazy_func)

Set a lazy default function for a parameter.

参数:

• name (str) -- Parameter name

• lazy_func (Callable[[], Any]) -- Function that returns the default value when called

返回类型:

None

clear_lazy_default(name)

Clear lazy default for a parameter.

参数:

name (str)

返回类型:

None

add_change_callback(callback, param_name=None)

Add a callback function that will be called when parameters change.

参数:

• callback (Callable[[str, Any, Any], None]) -- Function to call with (param_name, old_value, new_value)

• param_name (str | None) -- Specific parameter to watch, or None for all parameters

返回类型:

None

remove_change_callback(callback, param_name=None)

Remove a change callback.

参数:

• callback (Callable[[str, Any, Any], None])

• param_name (str | None)

返回类型:

None

get_change_history(name, limit=None)

Get change history for a parameter.

参数:

• name (str) -- Parameter name

• limit (int | None) -- Maximum number of history entries to return

返回:

List of history entries (newest first) in format (old_value, new_value, timestamp)

返回类型:

List[tuple]

clear_history(name=None)

Clear change history.

参数:

name (str | None) -- Specific parameter name, or None to clear all history

返回类型:

None

add_dependency(param_name, dependent_param)

Add a dependency relationship between parameters.

参数:

• param_name (str) -- Parameter that others depend on

• dependent_param (str) -- Parameter that depends on param_name

返回类型:

None

remove_dependency(param_name, dependent_param)

Remove a dependency relationship.

参数:

• param_name (str)

• dependent_param (str)

返回类型:

None

get_dependencies(param_name)

Get list of parameters that depend on the given parameter.

参数:

param_name (str)

返回类型:

List[str]

get_dependents(param_name)

Get list of parameters that this parameter depends on.

参数:

param_name (str)

返回类型:

List[str]

begin_transaction()

Begin a parameter transaction.

返回类型:

None

commit_transaction()

Commit the current transaction.

返回类型:

None

rollback_transaction()

Rollback the current transaction.

返回类型:

None

is_in_transaction()

Check if currently in a transaction.

返回类型:

bool

class backtrader.parameters.ParameterAccessor

基类：object

Parameter accessor that provides dict-like and attribute-like access to parameters.

This class serves as a bridge between the new parameter system and the old MetaParams-style parameter access patterns. It provides backward compatibility by supporting both attribute access (obj.p.param_name) and dict-like access.

__init__(param_manager)

Initialize with a parameter manager.

NOTE: Originally attempted to pre-create instance attributes for performance, but this causes parameter synchronization issues. When parameters are modified through other means (like broker.set_cash()), instance attributes won't update. Therefore maintain dynamic lookup to ensure latest values are always retrieved.

参数:

param_manager (ParameterManager)

__getattr__(name)

Get parameter value via attribute access.

Always get latest value from param_manager to ensure consistency. All parameter accesses are dynamically looked up to guarantee latest values.

__setattr__(name, value)

Set parameter value via attribute access.

__getitem__(name)

Get parameter value via dict-like access.

__setitem__(name, value)

Set parameter value via dict-like access.

__contains__(name)

Check if parameter exists.

__iter__()

Iterate over parameter names.

__len__()

Get number of parameters.

__repr__()

String representation showing parameter values.

class backtrader.parameters.ParameterizedBase

基类：object

Enhanced base class for objects with parameters - without metaclass.

This class provides the modern parameter system interface while maintaining backward compatibility with the old MetaParams-based system. It uses regular class mechanisms instead of metaclass.

classmethod __init_subclass__(**kwargs)

Called when a class is subclassed. Replaces metaclass functionality.

This method sets up the class for lazy parameter descriptor resolution to avoid inheritance contamination issues.

__init__(**kwargs)

Initialize the parameterized object.

get_param(name, default=None)

Get parameter value with fallback.

参数:

• name (str) -- Parameter name

• default (Any) -- Default value if parameter not found

返回:

Parameter value

返回类型:

Any

set_param(name, value, validate=True)

Set parameter value with optional validation.

参数:

• name (str) -- Parameter name

• value (Any) -- Parameter value

• validate (bool) -- Whether to perform validation

抛出:

• AttributeError -- If parameter manager not initialized

• ValueError -- If validation fails

返回类型:

None

get_param_info()

Get comprehensive information about all parameters.

返回:

Dictionary with parameter information

返回类型:

Dict[str, Dict[str, Any]]

validate_params()

Validate all parameters and return list of validation errors.

返回:

List of validation error messages (empty if all valid)

返回类型:

List[str]

reset_param(name)

Reset parameter to its default value.

参数:

name (str) -- Parameter name

抛出:

• AttributeError -- If parameter manager not initialized

• ValueError -- If parameter doesn't exist or is locked

返回类型:

None

reset_all_params()

Reset all parameters to their default values.

返回类型:

None

get_modified_params()

Get parameters that have been modified from their defaults.

返回:

Dictionary of modified parameter names and values

返回类型:

Dict[str, Any]

copy_params_from(other, param_names=None, exclude=None)

Copy parameters from another ParameterizedBase instance.

参数:

• other (ParameterizedBase) -- Source object to copy parameters from

• param_names (List[str] | None) -- Specific parameter names to copy (None for all)

• exclude (List[str] | None) -- Parameter names to exclude from copying

返回类型:

None

__repr__()

Enhanced string representation with parameter information.

返回类型:

str

backtrader.parameters.Int(min_val=None, max_val=None)

Create an integer validator function.

参数:

• min_val (int | None) -- Minimum allowed value

• max_val (int | None) -- Maximum allowed value

返回:

Validator function for integer parameters

返回类型:

Callable[[Any], bool]

backtrader.parameters.Float(min_val=None, max_val=None)

Create a float validator function.

参数:

• min_val (float | None) -- Minimum allowed value

• max_val (float | None) -- Maximum allowed value

返回:

Validator function for float parameters

返回类型:

Callable[[Any], bool]

backtrader.parameters.FloatParam(default=None, min_val=None, max_val=None, doc=None)

Create a float parameter descriptor with validation.

参数:

• min_val (float | None)

• max_val (float | None)

• doc (str)

返回类型:

ParameterDescriptor

backtrader.parameters.BoolParam(default=None, doc=None)

Create a boolean parameter descriptor.

参数:

doc (str)

返回类型:

ParameterDescriptor

backtrader.parameters.StringParam(default=None, min_length=None, max_length=None, doc=None)

Create a string parameter descriptor with length validation.

参数:

• min_length (int | None)

• max_length (int | None)

• doc (str)

返回类型:

ParameterDescriptor

backtrader.parameters.String(min_length=None, max_length=None)

Create a string validator function.

参数:

• min_length (int | None) -- Minimum allowed string length

• max_length (int | None) -- Maximum allowed string length

返回:

Validator function for string parameters

返回类型:

Callable[[Any], bool]

backtrader.parameters.Bool()

Create a boolean validator function.

返回:

Validator function for boolean parameters

返回类型:

Callable[[Any], bool]

backtrader.parameters.OneOf(*choices)

Create a validator that checks if value is one of the given choices.

参数:

*choices -- Allowed values

返回:

Validator function

返回类型:

Callable[[Any], bool]

backtrader.parameters.create_param_descriptor(name, default=None, doc=None)

Create a basic parameter descriptor.

参数:

• name (str) -- Parameter name

• default (Any) -- Default value

• doc (str) -- Documentation string

返回:

ParameterDescriptor instance

返回类型:

ParameterDescriptor

backtrader.parameters.derive_params(base_params, new_params, other_base_params=None)

Derive parameters by combining base parameters with new ones.

参数:

• base_params -- Base parameter descriptors or tuples

• new_params -- New parameter descriptors or tuples

• other_base_params -- Additional base parameters

返回:

Dictionary of combined parameter descriptors

class backtrader.parameters.ParamsBridge

基类：object

Bridge class for transitioning from MetaParams to new parameter system.

This class provides utilities for converting between the old MetaParams system and the new descriptor-based system during the migration period.

static extract_params_from_metaparams_class(cls)

Extract parameter descriptors from a MetaParams-based class.

参数:

cls -- Class with MetaParams-based parameters

返回:

Dictionary of parameter descriptors

返回类型:

Dict[str, ParameterDescriptor]

static convert_legacy_params_tuple(params_tuple)

Convert legacy params tuple to parameter descriptors.

参数:

params_tuple -- Legacy params tuple like (('param1', 10), ('param2', 'value'))

返回:

Dictionary of parameter descriptors

返回类型:

Dict[str, ParameterDescriptor]

static create_compatibility_wrapper(metaparams_class)

Create a compatibility wrapper for MetaParams-based classes.

参数:

metaparams_class -- Original MetaParams-based class

返回:

New class that uses the modern parameter system

exception backtrader.parameters.ParameterValidationError

基类：ValueError

Specific exception for parameter validation errors.

__init__(parameter_name, value, expected_type=None, additional_info='')

Initialize a parameter validation error.

参数:

• parameter_name (str) -- Name of the parameter that failed validation.

• value (Any) -- The invalid value that was provided.

• expected_type (Type | None) -- Expected type for the parameter (optional).

• additional_info (str) -- Additional error information (optional).

exception backtrader.parameters.ParameterAccessError

基类：AttributeError

Specific exception for parameter access errors.

__init__(parameter_name, class_name, available_params)

Initialize a parameter access error.

参数:

• parameter_name (str) -- Name of the parameter that was not found.

• class_name (str) -- Name of the class where access was attempted.

• available_params (List[str]) -- List of available parameter names.

backtrader.parameters.validate_parameter_compatibility(old_class, new_class)

Validate compatibility between old MetaParams class and new descriptor-based class.

参数:

• old_class -- Original MetaParams-based class

• new_class -- New descriptor-based class

返回:

Dictionary with compatibility analysis results

返回类型:

Dict[str, Any]