backtrader.lineseries module

LineSeries Module - Multi-line time-series data management.

This module defines the LineSeries class and related descriptors for classes that hold multiple lines at once. It provides the infrastructure for managing collections of line objects with named access.

Key Classes:

LineSeries: Base class for objects with multiple lines. Lines: Container for multiple line objects with named access. LinesManager: Manages line operations and access. LineAlias: Descriptor for named line access. MinimalData/MinimalOwner/MinimalClock: Minimal implementations for edge cases.

Example

Accessing lines by name: >>> obj.lines.close # Access the ‘close’ line >>> obj.lines[0] # Access the first line

class backtrader.lineseries.MinimalData

Bases: object

Minimal data replacement for missing data0, data1, etc. attributes.

Performance optimization: define at module level, avoid repeatedly creating classes in __getattr__.

__init__()

Initialize minimal data with pre-filled array.

Creates a pre-filled array to prevent index errors when accessing missing data attributes.

__getitem__(key)

Get item from the array at the specified index offset.

Parameters:

key – Index offset from the current position (_idx).

Returns:

Value at the computed index, or 0.0 if index is invalid.

Return type:

float

__len__()

Return the length of the internal array.

Returns:

Length of the array.

Return type:

int

__getattr__(name)

Return None for any missing attributes to prevent further errors.

Parameters:

name – Name of the attribute being accessed.

Returns:

Always returns None for missing attributes.

Return type:

None

class backtrader.lineseries.MinimalOwner

Bases: object

Minimal owner implementation for observers and analyzers.

Performance optimization: define at module level, avoid repeatedly creating classes in __getattr__.

__init__()

Initialize minimal owner with default attributes.

Sets up basic attributes needed for observers and analyzers when the actual owner is not available.

class backtrader.lineseries.MinimalClock

Bases: object

Minimal clock implementation used as a fallback when _clock is not set.

CRITICAL FIX: Defined at module level to support pickling for multiprocessing. Previously this was defined as a local class inside __getattribute__, which caused pickle failures during strategy optimization.

__init__()

Initialize minimal clock with default attributes.

Sets up basic attributes needed for clock functionality when the actual clock is not available.

buflen()

Return buffer length.

Returns:

Always returns 1 for minimal clock.

Return type:

int

__len__()

Return the length of the minimal clock.

Returns:

Always returns 0 for minimal clock.

Return type:

int

__getattr__(name)

Return None for any missing attributes to prevent further errors.

Parameters:

name – Name of the attribute being accessed.

Returns:

Always returns None for missing attributes.

Return type:

None

__reduce__()

Support pickling for multiprocessing.

class backtrader.lineseries.LineAlias

Bases: object

Descriptor class that store a line reference and returns that line from the owner

Keyword Arguments:

• line (int) – reference to the line that will be returned from

• buffer (owner's lines)

As a convenience, the __set__ method of the descriptor is used not set the line reference because this is a constant along the live of the descriptor instance, but rather to set the value of the line at the instant ‘0’ (the current one)

__init__(line)

Initialize the line alias descriptor.

Parameters:

line – Index of the line in the owner’s lines buffer.

__get__(obj, cls=None)

Get the line from the owner’s lines buffer.

Parameters:

• obj – The object owning the lines (typically a Lines instance).

• cls – The class being accessed (unused).

Returns:

The line at the stored index.

Return type:

LineBuffer

__set__(obj, value)

A line cannot be “set” once it has been created. But the values inside the line can be “set”. This is achieved by adding a binding to the line inside “value”

class backtrader.lineseries.LinesManager

Bases: object

Manager for lines operations without metaclass

class backtrader.lineseries.Lines

Bases: object

Defines an “array” of lines which also has most of the interface of a LineBuffer class (forward, rewind, advance…).

This interface operations are passed to the lines held by self

The class can autosubclass itself (_derive) to hold new lines keeping them in the defined order.

classmethod getlinealiases()

Get all line aliases for this class.

Returns:

Tuple of line alias names.

Return type:

tuple

itersize()

Return an iterator over the lines.

Returns:

Iterator over lines from index 0 to size().

Return type:

iterator

__init__(initlines=None)

Create the lines recording during “_derive” or else use the provided “initlines”

__iter__()

Allow proper iteration over lines without calling __getitem__ for each index.

Returns:

Iterator over the lines list.

Return type:

iterator

__len__()

Return the number of lines.

Returns:

Number of lines in the lines list.

Return type:

int

size()

Return the number of lines excluding extra lines.

Returns:

Number of main lines.

Return type:

int

fullsize()

Return the total number of lines including extra lines.

Returns:

Total number of lines.

Return type:

int

extrasize()

Return the number of extra lines.

Returns:

Number of extra lines.

Return type:

int

__getitem__(line)

Get a line by index.

This method implements dynamic line creation - accessing an index beyond the current number of lines will create new lines up to a reasonable limit.

Parameters:

line – Index of the line to retrieve.

Returns:

The line at the specified index, or None if

the index exceeds the maximum reasonable limit.

Return type:

LineBuffer

get(ago=0, size=1, line=0)

Get a slice of values from a specific line.

Parameters:

• ago – Number of periods to look back (0=current).

• size – Number of values to return.

• line – Line index to get values from.

Returns:

Slice of values from the specified line.

Return type:

list or array

__setitem__(line, value)

Set a line by index with proper binding support.

This method handles different types of values: - Scalar values: Creates a LineNum (constant line) - Indicators: Binds the indicator’s output line to the parent’s line - LineBuffers: Adds binding for value propagation - Iterables: Creates a new line from the iterable values

Parameters:

• line – Line index or name to set.

• value – Value to assign (scalar, indicator, or iterable).

forward(value=0.0, size=1)

Forward all lines by the specified size.

Parameters:

• value – Value to use for forwarding (default: 0.0).

• size – Number of positions to forward (default: 1).

backwards(size=1, force=False)

Move all lines backward by the specified size.

Parameters:

• size – Number of positions to move backward (default: 1).

• force – If True, force the backward movement.

rewind(size=1)

Rewind all lines by decreasing idx and lencount.

Parameters:

size – Number of positions to rewind (default: 1).

extend(value=0.0, size=0)

Extend all lines with additional positions.

Parameters:

• value – Value to use for extension (default: 0.0).

• size – Number of positions to add (default: 0).

reset()

Reset all lines to their initial state.

home()

Reset all lines to the home position (beginning).

advance(size=1)

Advance all lines by increasing idx.

Parameters:

size – Number of positions to advance (default: 1).

buflen(line=0)

Get the buffer length of a specific line.

Parameters:

line – Index of the line (default: 0).

Returns:

Buffer length of the specified line.

Return type:

int

__getattr__(name)

Handle missing attributes, especially _owner for observers.

PERF OPTIMIZATIONS: - Class-level frozenset for critical attrs (was recreated every call) - name[0] == ‘_’ instead of startswith (2-3x faster) - Removed inspect.currentframe() stack walk (extremely expensive) - Reduced hasattr chains with try/except EAFP

__setattr__(name, value)

Handle attribute setting, especially _owner and line bindings

class backtrader.lineseries.LineSeriesMixin

Bases: object

Mixin to provide LineSeries functionality without metaclass

classmethod __init_subclass__(**kwargs)

Called when a class is subclassed - replaces metaclass functionality

class backtrader.lineseries.LineSeries

Bases: LineMultiple, LineSeriesMixin, ParamsMixin

Base class for objects with multiple time-series lines.

LineSeries provides the foundation for classes that manage multiple line objects, such as indicators with multiple output lines. It handles line creation, access, and management.

lines

Container object holding all line instances.

plotinfo

Plotting configuration object.

Example

Accessing lines by name or index: >>> obj = LineSeries() >>> obj.lines.close # Named access >>> obj.lines[0] # Index access

static __new__(cls, *args, **kwargs)

Instantiate lines class when creating LineSeries instances.

CRITICAL FIX: The lines attribute is set as a class by __init_subclass__, but it needs to be instantiated for each object instance.

class PlotInfoObj

Bases: object

Plot information object for LineSeries.

Stores plotting configuration attributes that control how the LineSeries is displayed in plots.

__init__()

Initialize plotinfo with default values.

Sets up default plotting attributes including plot status, plot master, and legend location.

get(key, default=None)

Standard get method for compatibility

Parameters:

• key – Attribute name.

• default – Default value if attribute not found.

Returns:

The attribute value or default.

__contains__(key)

Check if an attribute exists in the plotinfo object.

Parameters:

key – Attribute name to check.

Returns:

True if the attribute exists, False otherwise.

Return type:

bool

keys()

Return list of public attribute names.

Returns:

List of non-private, non-callable attribute names.

Return type:

list

plotinfo = <backtrader.lineseries.LineSeries.PlotInfoObj object>

class PlotLinesObj

Bases: object

Plot lines configuration object for LineSeries.

Stores configuration for individual lines in plots, such as colors, line styles, and other visual properties.

__init__()

Initialize plotlines container.

get(key, default=None)

Standard get method for compatibility

Parameters:

• key – Attribute name.

• default – Default value if attribute not found.

Returns:

The attribute value or default.

__contains__(key)

Check if an attribute exists in the plotlines object.

Parameters:

key – Attribute name to check.

Returns:

True if the attribute exists, False otherwise.

Return type:

bool

__getattr__(name)

Return an empty plotline object for missing attributes.

Parameters:

name – Name of the missing attribute.

Returns:

A default plotline object with safe defaults.

Return type:

PlotLineObj

plotlines = <backtrader.lineseries.LineSeries.PlotLinesObj object>

csv = True

property array

Get the array of the first line.

Returns:

The underlying array of the first line.

Return type:

array

property line

Return the first line (lines[0]) for single-line indicators.

Returns:

The first line in the lines collection.

Return type:

LineBuffer

property l

Alias for lines - used in indicator next() methods like self.l.sma[0].

Returns:

The lines container object.

Return type:

Lines

__getattr__(name)

High-frequency attribute resolution optimized for performance.

OPTIMIZATION NOTES: - Results are cached in __dict__ to avoid repeated lookups - Removed recursion guard overhead (rely on Python’s natural recursion limit) - Use direct __dict__ access instead of getattr() to avoid triggering __getattr__ - Use index check (name[0]) instead of startswith() for speed

__setattr__(name, value)

Optimized attribute setter with minimal type checking.

OPTIMIZATION NOTES: - Use type() instead of isinstance() - faster for simple types - Use EAFP (try/except) instead of hasattr() to avoid double lookups - Minimize attribute access on value object

__len__()

Return length of LineSeries (number of data points)

OPTIMIZATION NOTES: - Cache lines[0] reference to avoid repeated indexing - Called 11M+ times, so optimization is critical

__getitem__(key)

Get value at index from primary line.

OPTIMIZATION NOTES: - Cache reference to lines[0] to avoid repeated indexing - Use fast NaN detection without isinstance/math.isnan - Minimal exception handling

__setitem__(key, value)

Set a line value by index.

Delegates to the Lines.__setitem__ method which handles line assignments properly including binding for indicators.

Parameters:

• key – Line index or name.

• value – Value to set.

__init__(*args, **kwargs)

Initialize a LineMultiple instance.

Sets up the internal state for managing multiple lines, including line type indicator, lines collection, clock reference, and line iterator tracking.

Initializes:

_ltype: Line type indicator (None for base LineMultiple). lines: Collection of line objects (creates if not exists). _clock: Clock reference for synchronization. _lineiterators: Dictionary tracking registered lineiterators. _minperiod: Minimum period requirement (defaults to 1).

plotlabel()

Get the plot label for this LineSeries.

Returns:

The plot label string.

Return type:

str

__call__(ago=None, line=-1)

Return either a delayed line or the data for a given index/name

Possible calls:

• self() -> current line

• self(ago) -> delayed line by “ago” periods

• self(-1) -> current line

• self(line=-1) -> current line

• self(line=’close’) -> current line by name

forward(value=0.0, size=1)

Forward all lines by the specified size.

Parameters:

• value – Value to use for forwarding (default: 0.0).

• size – Number of positions to forward (default: 1).

backwards(size=1, force=False)

Move all lines backward by the specified size.

Parameters:

• size – Number of positions to move backward (default: 1).

• force – If True, force the backward movement.

rewind(size=1)

Rewind all lines by decreasing idx and lencount.

Parameters:

size – Number of positions to rewind (default: 1).

extend(value=0.0, size=0)

Extend all lines with additional positions.

Parameters:

• value – Value to use for extension (default: 0.0).

• size – Number of positions to add (default: 0).

reset(value=0.0)

Reset all lines to their initial state.

Parameters:

value – Value to use for reset (default: 0.0).

home()

Reset all lines to the home position (beginning).

advance(size=1)

Advance all lines by increasing idx.

Parameters:

size – Number of positions to advance (default: 1).

size()

Return the number of lines in this LineSeries.

Returns:

Number of main lines (excluding extra lines).

Return type:

int

property chkmin

Property to ensure chkmin is never None for TestStrategy.

This property provides a safe default value for chkmin, which is used in testing to validate minimum period requirements.

Returns:

The chkmin value, or 30 as a safe default.

Return type:

int

frompackages = ()

packages = ()

class backtrader.lineseries.LineSeriesStub

Bases: LineSeries

Simulates a LineMultiple object based on LineSeries from a single line

The index management operations are overriden to take into account if the line is a slave, i.e.:

• The line reference is a line from many in a LineMultiple object

• Both the LineMultiple object and the Line are managed by the same object

Were slave not to be taken into account, the individual line would, for example, be advanced twice:

• Once under when the LineMultiple object is advanced (because it advances all lines it is holding

• Again as part of the regular management of the object holding it

extralines = 1

__init__(*args, **kwargs)

Initialize a LineMultiple instance.

Sets up the internal state for managing multiple lines, including line type indicator, lines collection, clock reference, and line iterator tracking.

Initializes:

_ltype: Line type indicator (None for base LineMultiple). lines: Collection of line objects (creates if not exists). _clock: Clock reference for synchronization. _lineiterators: Dictionary tracking registered lineiterators. _minperiod: Minimum period requirement (defaults to 1).

forward(value=0.0, size=1)

Forward the line if not a slave.

Parameters:

• value – Value to use for forwarding (default: 0.0).

• size – Number of positions to forward (default: 1).

backwards(size=1, force=False)

Move the line backward if not a slave.

Parameters:

• size – Number of positions to move backward (default: 1).

• force – If True, force the backward movement.

rewind(size=1)

Rewind the line if not a slave.

Parameters:

size – Number of positions to rewind (default: 1).

extend(value=0.0, size=0)

Extend the line if not a slave.

Parameters:

• value – Value to use for extension (default: 0.0).

• size – Number of positions to add (default: 0).

reset()

Reset the line if not a slave.

home()

Reset the line to home position if not a slave.

advance(size=1)

Advance the line if not a slave.

Parameters:

size – Number of positions to advance (default: 1).

qbuffer()

Queue buffer operation (no-op for stub).

This method is a no-op in the stub implementation since the underlying line manages its own buffering.

minbuffer(size)

Set minimum buffer size (no-op for stub).

This method is a no-op in the stub implementation since the underlying line manages its own buffering.

Parameters:

size – Minimum buffer size (ignored in stub).

frompackages = ()

packages = ()

backtrader.lineseries.LineSeriesMaker(arg, slave=False)

Create a LineSeries from a single line or return existing LineSeries.

Parameters:

• arg – A single line or LineSeries object.

• slave – If True, mark the created stub as a slave.

Returns:

The original LineSeries if arg is already a LineSeries, otherwise a LineSeriesStub wrapping the line.