Trades Module

The Trades value object wraps a trades DataFrame together with its metadata (trade type, data origin and column map). It proxies attribute and item access to the underlying DataFrame, so Symbol.agg_trades / Symbol.atomic_trades keep behaving like DataFrames in notebooks (s.agg_trades['Quantity'], .empty, .head() …) while also exposing .df, .trade_type, .origin and helpers.

Trades value object.

Wraps a trades pandas.DataFrame together with its metadata (trade type, data origin, the column map and raw API response it was built from). A single Symbol can hold two independent instances at once, e.g. atomic trades from one origin and aggregated trades from another.

It proxies attribute and item access to the underlying DataFrame, so it can be used like one in notebooks:

s.agg_trades['Quantity']     # -> pandas Series  (delegated to .df)
s.agg_trades.empty           # -> bool
s.agg_trades.head()          # -> DataFrame      (delegated to .df)
s.agg_trades.df              # -> the raw pandas DataFrame
s.agg_trades.trade_type      # -> 'agg'

Heavy domain logic (indicators, plotting) is NOT placed here to keep this module dependency-free (pandas only) and avoid import cycles with analysis/plotting. Only the small, repeated bits live here: the empty check, the time-range filter and the metadata.

Classes:

Trades([df, trade_type, origin, columns, ...])

A trades DataFrame plus its metadata.

class Trades(df: DataFrame = None, *, trade_type: str = 'agg', origin: str = None, columns: dict = None, symbol: str = None, time_zone: str = None, raw: list = None)

Bases: object

A trades DataFrame plus its metadata.

Parameters:

• df (pd.DataFrame) – The parsed trades DataFrame. If None, an empty frame is created (using columns for its column names when provided).

• trade_type (str) – 'agg' (aggregated) or 'atomic'/'trade'.

• origin (str) – Where the data came from: 'binance_api', 'csv', 'binbase' or 'postgresql'.

• columns (dict) – Column map (raw API field -> BinPan column name).

• symbol (str) – The symbol, e.g. 'BTCUSDT'.

• time_zone (str) – IANA time zone of the index, e.g. 'Europe/Madrid'.

• raw (list) – The raw API response (list of dicts) it was parsed from.

Attributes:

is_agg	True if these are aggregated trades.
label	Human label: 'aggregated' or 'atomic'.
empty_msg	Message suggesting how to fetch the data when empty.
empty	True if the underlying DataFrame is empty.

Methods:

filtered([start_time, end_time, time_col])	Return a copy of the DataFrame filtered by the timestamp column.
with_df(df)	Return a new Trades carrying the same metadata but a different DataFrame.

property is_agg: bool

True if these are aggregated trades.

property label: str

Human label: 'aggregated' or 'atomic'.

property empty_msg: str

Message suggesting how to fetch the data when empty.

filtered(start_time: int = None, end_time: int = None, time_col: str = 'Timestamp') → DataFrame

Return a copy of the DataFrame filtered by the timestamp column.

Parameters:

• start_time (int) – Inclusive lower bound (ms). Ignored if falsy.

• end_time (int) – Inclusive upper bound (ms). Ignored if falsy.

• time_col (str) – Timestamp column name. Default 'Timestamp'.

Return pd.DataFrame:

Filtered (deep) copy.

with_df(df: DataFrame) → Trades

Return a new Trades carrying the same metadata but a different DataFrame.

property empty: bool

True if the underlying DataFrame is empty.