backtrader.linebuffer module

LineBuffer Module - Circular buffer storage for time-series data.

This module provides the LineBuffer class which implements a circular buffer for storing time-series data. The buffer allows efficient operations like appending, forwarding, rewinding, and resetting.

Key Features:

• Index 0 always points to the current active value

• Positive indices fetch past values (left-hand side)

• Negative indices fetch future values (right-hand side)

• Automatic memory management with qbuffer

• Line bindings for automatic value propagation

Classes:

LineBuffer: Core circular buffer implementation. LineActions: Base class for line objects with multiple lines. LineActionsMixin: Mixin providing line operations. LineActionsCache: Cache system for performance optimization. PseudoArray: Wrapper for non-array iterables. LinesOperation: Operations on multiple lines. LineOwnOperation: Operations on owned lines.

Example

Basic buffer usage: >>> buf = LineBuffer() >>> buf.home() # Reset to beginning >>> buf.forward() # Move to next position >>> buf[0] = 100.0 # Set current value >>> print(buf[0]) # Get current value 100.0 >>> print(buf[-1]) # Get previous value

class backtrader.linebuffer.LineBuffer

Bases: LineSingle, LineRootMixin

LineBuffer defines an interface to an “array.array” (or list) in which index 0 points to the item which is active for input and output.

Positive indices fetch values from the past (left-hand side) Negative indices fetch values from the future (if the array has been extended on the right-hand side)

With this behavior, no index has to be passed around to entities which have to work with the current value produced by other entities: the value is always reachable at “0”.

Likewise, storing the current value produced by “self” is done at 0.

Additional operations to move the pointer (home, forward, extend, rewind, advance getzero) are provided

The class can also hold “bindings” to other LineBuffers. When a value is set in this class, it will also be set in the binding.

UnBounded = 0

QBuffer = 1

__init__()

Initialize the LineBuffer instance.

Sets up all internal attributes including the array storage, index pointer, buffer mode, and performance optimization flags.

get_idx()

Get the current index position.

Returns:

The current index in the buffer.

Return type:

int

set_idx(idx, force=False)

Set the index position.

Parameters:

• idx – The new index value.

• force – If True, force set even in QBuffer mode at lenmark.

Note

In QBuffer mode, when at lenmark, the index stays at 0 unless force is True. This allows resampling operations.

property idx

Get the current index position.

Returns:

The current index in the buffer.

Return type:

int

reset()

Resets the internal buffer structure and the indices

qbuffer(savemem=0, extrasize=0)

Enable queued buffer mode for memory-efficient storage.

Parameters:

• savemem – Memory saving mode (0=normal, >0=enable cache mode).

• extrasize – Extra buffer size for resampling/replay operations.

Note

In QBuffer mode, only the last maxlen values are kept, reducing memory usage for long backtests.

getindicators()

Get list of indicators using this line buffer.

Returns:

Empty list for base LineBuffer (override in subclasses).

Return type:

list

minbuffer(size)

The linebuffer must guarantee the minimum requested size to be available.

In non-dqbuffer mode, this is always true (of course, until data is filled at the beginning, there are fewer values, but minperiod in the framework should account for this.

In dqbuffer mode, the buffer has to be adjusted for this if currently less than requested

__len__()

Return the linebuffer’s length counter.

Performance optimization: Restore master branch’s simple implementation - Directly return self.lencount (pre-calculated length value) - Remove all recursion checks, hasattr calls and complex logic - Performance improvement: from 0.611s to ~0.05s (92% improvement)

buflen()

Real data that can be currently held in the internal buffer

The internal buffer can be longer than the actual stored data to allow for “lookahead” operations. The real amount of data that is held/can be held in the buffer is returned

__getitem__(ago)

Get the value at a specified offset - optimized for hot path.

Parameters:

ago (int) – Relative offset from current index (0=current, -1=previous, 1=next)

Returns:

Value at the specified position

get(ago=0, size=1)

Returns a slice of the array relative to ago

Keyword Arguments:

• ago (int) – Point of the array to which size will be added

• size (to return the slice) – size of the slice to return,

• negative (can be positive or)

If size is positive ago will mark the end of the iterable and vice versa if size is negative

Returns:

A slice of the underlying buffer

getzeroval(idx=0)

Returns a single value of the array relative to the real zero of the buffer

Keyword Arguments:

• idx (int) – Where to start relative to the real start of the buffer

• size (int) – size of the slice to return

Returns:

A slice of the underlying buffer

getzero(idx=0, size=1)

Returns a slice of the array relative to the real zero of the buffer

Keyword Arguments:

• idx (int) – Where to start relative to the real start of the buffer

• size (int) – size of the slice to return

Returns:

A slice of the underlying buffer

__setitem__(ago, value)

Sets a value at position “ago” and executes any associated bindings

Keyword Arguments:

• ago (int) – Point of the array to which size will be added to return

• slice (the)

• value (variable) – value to be set

Performance optimization: Use pre-calculated flags to avoid repeated hasattr and string operations

set(value, ago=0)

Sets a value at position “ago” and executes any associated bindings

Keyword Arguments:

• value (variable) – value to be set

• ago (int) – Point of the array to which size will be added to return

• slice (the)

PERF: Uses pre-calculated _is_datetime_line and _default_value flags instead of hasattr/isinstance checks on every call.

home()

Rewinds the logical index to the beginning

The underlying buffer remains untouched and the actual len can be found out with buflen

forward(value=nan, size=1)

Moves the logical index forward and enlarges the buffer as much as needed

Keyword Arguments:

• value (variable) – value to be set in new positions

• size (int) – How many extra positions to enlarge the buffer

backwards(size=1, force=False)

Moves the logical index backwards and reduces the buffer as much as needed

Keyword Arguments:

• size (int) – How many extra positions to rewind the buffer

• force (bool) – Whether to force the reduction of the logical buffer regardless of the minperiod

safe_backwards(size=1)

Safely move the index backwards without raising errors.

Parameters:

size – Number of positions to move backwards.

Returns:

True if index is still >= 0 after moving, False otherwise.

Return type:

bool

rewind(size=1)

Rewind the buffer by decreasing idx and lencount.

Parameters:

size – Number of positions to rewind.

advance(size=1)

Advances the logical index without touching the underlying buffer

extend(value=nan, size=0)

Extends the underlying array with positions that the index will not reach

Keyword Arguments:

• value (variable) – value to be set in new positins

• size (int) – How many extra positions to enlarge the buffer

The purpose is to allow for lookahead operations or to be able to set values in the buffer “future”

addbinding(binding)

Adds another line binding

Keyword Arguments:

• binding (LineBuffer) – another line that must be set when this line

• value (becomes a)

plot(idx=0, size=None)

Returns a slice of the array relative to the real zero of the buffer

Keyword Arguments:

• idx (int) – Where to start relative to the real start of the buffer

• size (int) – size of the slice to return

This is a variant of getzero that unless told otherwise returns the entire buffer, which is usually the idea behind plottint (all must be plotted)

Returns:

A slice of the underlying buffer

plotrange(start, end)

Get a slice of data from the array.

Parameters:

• start – Start index of the slice.

• end – End index of the slice.

Returns:

Slice of data from start to end.

Return type:

list or array

oncebinding()

Executes the bindings when running in “once” mode

bind2lines(binding=0)

Stores a binding to another line. “Binding” can be an index or a name

bind2line(binding=0)

Stores a binding to another line. “Binding” can be an index or a name

__call__(ago=None)

Returns either the current value (ago=None) or a delayed LineBuffer that fetches the value which is “ago” periods before. Useful to have the closing price 5 bars before: close(-5)

datetime(ago=0, tz=None, naive=True)

Get the datetime value at the specified offset.

Parameters:

• ago – Number of periods to look back (0=current, -1=previous).

• tz – Timezone to apply. If None, uses self._tz.

• naive – If True, return naive datetime without timezone info.

Returns:

Datetime object representing the timestamp.

Return type:

datetime

Raises:

IndexError – If the requested position is out of bounds for data feeds.

date(ago=0, tz=None, naive=True)

Get the date component of the datetime value at the specified offset.

Parameters:

• ago – Number of periods to look back (0=current, -1=previous).

• tz – Timezone to apply. If None, uses self._tz.

• naive – If True, return naive date without timezone info.

Returns:

Date object representing the date portion of the timestamp.

Return type:

date

Raises:

IndexError – If the requested position is out of bounds for data feeds.

time(ago=0, tz=None, naive=True)

Get the time component of the datetime value at the specified offset.

Parameters:

• ago – Number of periods to look back (0=current, -1=previous).

• tz – Timezone to apply. If None, uses self._tz.

• naive – If True, return naive time without timezone info.

Returns:

Time object representing the time portion of the timestamp.

Return type:

time

dt(ago=0)

Alias to avoid the extra chars in “datetime” for this field

tm_raw(ago=0)

Returns a localtime/gmtime like time.struct_time object which is compatible with strftime formatting.

The time zone of the struct_time is naive

tm(ago=0)

Returns a localtime/gmtime like time.struct_time object which is compatible with strftime formatting.

The time zone of the struct_time is naive

tm_lt(other, ago=0)

Returns True if the time carried by this line’s index “ago” is lower than the time carried by the “other” line

tm_le(other, ago=0)

Returns True if the time carried by this line’s index “ago” is lower than or equal to the time carried by the “other” line

tm_eq(other, ago=0)

Returns True if the time carried by this line’s index “ago” is equal to the time carried by the “other” line

tm_gt(other, ago=0)

Returns True if the time carried by this line’s index “ago” is greater than the time carried by the “other” line

tm_ge(other, ago=0)

Returns True if the time carried by this line’s index “ago” is greater than or equal to the time carried by the “other” line

tm2dtime(tm, ago=0)

Returns the passed tm (time.struct_time) in a datetime using the timezone (if any) of the line

tm2datetime(tm, ago=0)

Returns the passed tm (time.struct_time) in a datetime using the timezone (if any) of the line

class backtrader.linebuffer.LineActionsCache

Bases: object

Cache system for LineActions to avoid repetitive calculations

classmethod enable_cache(enable=True)

Enable or disable the cache.

Parameters:

enable – True to enable caching, False to disable.

classmethod clear_cache()

Clear all cached values.

classmethod get_cache_key(*args)

Generate cache key from arguments

class backtrader.linebuffer.LineActionsMixin

Bases: object

Mixin to provide LineActions functionality without metaclass

classmethod dopreinit(_obj, *args, **kwargs)

Pre-initialization processing for LineActions

classmethod dopostinit(_obj, *args, **kwargs)

Post-initialization processing for LineActions

class backtrader.linebuffer.PseudoArray

Bases: object

Wrapper for non-array iterables to provide array-like access.

This class wraps iterables (including itertools.repeat) and provides array-like indexing access. It handles cases where the wrapped object doesn’t support direct indexing.

wrapped

The wrapped iterable object.

_minperiod

Minimum period inherited from the wrapped object.

Example

>>> from itertools import repeat
>>> pseudo = PseudoArray(repeat(1.0))
>>> print(pseudo[0])
1.0

__init__(wrapped)

Initialize PseudoArray with a wrapped iterable.

Parameters:

wrapped – The iterable object to wrap.

property array

Get the array representation of the wrapped object.

Returns:

Array representation of the wrapped object.

Return type:

list or array

class backtrader.linebuffer.LineActions

Bases: LineBuffer, LineActionsMixin, ParamsMixin

Base class for Line Clases with different lines, derived from a LineBuffer

plotlines = <object object>

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

Handle data processing for indicators and other LineActions objects

__init__(*args, **kwargs)

Initialize the LineBuffer instance.

Sets up all internal attributes including the array storage, index pointer, buffer mode, and performance optimization flags.

getindicators()

Get list of indicators using this line actions object.

Returns:

Empty list for base LineActions (override in subclasses).

Return type:

list

qbuffer(savemem=0)

Enable queued buffer mode for memory-efficient storage.

Parameters:

savemem – Memory saving mode (0=normal, >0=enable cache mode).

plotlabel()

Return the plot label for this line object

static arrayize(obj)

Convert an object to an array-compatible object.

Parameters:

obj – Object to convert. Can be a value, iterable, or array-like.

Returns:

The original object if it has an array attribute, otherwise a LineNum or PseudoArray wrapper.

classmethod cleancache()

Clean the cache - called by cerebro

classmethod usecache(enable=True)

Enable or disable the cache

frompackages = ()

packages = ()

backtrader.linebuffer.LineDelay(a, ago=0, **kwargs)

Create a delayed line object.

Parameters:

• a – Source line object.

• ago – Number of periods to delay. Negative for lookback.

• **kwargs – Additional keyword arguments.

Returns:

A delayed line object.

Return type:

_LineDelay or _LineForward

backtrader.linebuffer.LineNum(num)

Create a constant line from a number.

Parameters:

num – The constant value.

Returns:

A line object that always returns the constant value.

Return type:

_LineDelay

class backtrader.linebuffer.LinesOperation

Bases: LineActions

Operation between two line objects (binary operations).

This class represents binary operations (addition, subtraction, etc.) between two line objects. The result is a new line that contains the element-wise operation result.

operation

The binary function to apply (e.g., operator.add).

a

First operand (left-hand side).

b

Second operand (right-hand side).

r

If True, reverse operation order.

_parent_a

Parent indicator for operand a.

_parent_b

Parent indicator for operand b.

Example

>>> result = LinesOperation(indicator1, indicator2, operator.sub)
>>> # result[0] = indicator1[0] - indicator2[0]

__init__(*args, **kwargs)

Initialize the LineBuffer instance.

Sets up all internal attributes including the array storage, index pointer, buffer mode, and performance optimization flags.

__getitem__(ago)

CRITICAL FIX: Override __getitem__ to compute value dynamically from source operands.

This ensures correct values in runonce mode where LinesOperation’s _idx may not be properly advanced because it’s not registered as IndType.

next()

Calculate and set the operation result for the current bar.

Performs the binary operation on the current values of both operands and stores the result at position 0.

once(start, end)

Calculate operation results in batch mode (runonce).

Parameters:

• start – Starting index.

• end – Ending index.

frompackages = ()

packages = ()

class backtrader.linebuffer.LineOwnOperation

Bases: LineActions

Operation on a single line object (unary operations).

This class represents unary operations (negation, absolute value, etc.) on a single line object. The result is a new line that contains the element-wise operation result.

operation

The unary function to apply (e.g., operator.neg).

a

The operand (line object).

_parent_a

Parent indicator for the operand.

Example

>>> result = LineOwnOperation(indicator, operator.neg)
>>> # result[0] = -indicator[0]

__init__(*args, **kwargs)

Initialize the LineBuffer instance.

Sets up all internal attributes including the array storage, index pointer, buffer mode, and performance optimization flags.

frompackages = ()

packages = ()

__getitem__(ago)

CRITICAL FIX: Override __getitem__ to compute value dynamically from source operand.

next()

Calculate and set the unary operation result for the current bar.

Performs the unary operation on the current value of the operand and stores the result at position 0.

once(start, end)

Calculate unary operation results in batch mode (runonce).

Parameters:

• start – Starting index.

• end – Ending index.

size()

Return the number of lines in this LineActions object