pybroker.context 模块

包含与上下文相关的类。上下文在 pybroker.strategy.Strategy 的执行过程中提供数据。

class ExecContext(symbol: str, config: StrategyConfig, portfolio: Portfolio, col_scope: ColumnScope, ind_scope: IndicatorScope, interval_scope: IntervalScope, declared_intervals: frozenset[int | Literal['daily', 'weekly', 'monthly', 'quarterly', 'yearly'] | str], input_scope: ModelInputScope, pred_scope: PredictionScope, pending_order_scope: PendingOrderScope, models: Mapping[ModelSymbol, TrainedModel], sym_end_index: Mapping[str, int], session: MutableMapping, run_hyperparams: Mapping[str, Any] | None = None, allowed_hyperparam_names: frozenset[str] = frozenset({}), rotation_enabled: bool = False)[源代码]

基类：object

包含 pybroker.strategy.Strategy 执行过程中的上下文数据。包括当前 K 线、投资组合头寸以及其他相关上下文的数据。该类也用于设置买入和卖出信号以下单。

该类中包含的数据是已完成的最新一根 K 线的数据。下单会在由 pybroker.config.StrategyConfig.buy_delay 和 pybroker.config.StrategyConfig.sell_delay 指定的未来某根 K 线上执行。

config: pybroker.config.StrategyConfig。

symbol: 该执行函数当前的股票代码。

buy_fill_price: symbol 买入（做多）订单使用的成交价格。

buy_shares: symbol 要买入的股数。

buy_limit_price: symbol 买入（做多）订单使用的限价。

buy_timeout_bars: 未成交的买入限价单在首次尝试后重试的 K 线数量。 None 表示仅尝试一次， -1 表示无限期保留，正整数表示有限的重试 K 线数量。

sell_fill_price: symbol 卖出（做空）订单使用的成交价格。

sell_shares: symbol 要卖出的股数。

sell_limit_price: symbol 卖出（做空）订单使用的限价。

sell_timeout_bars: 未成交的卖出限价单在首次尝试后重试的 K 线数量。 None 表示仅尝试一次， -1 表示无限期保留，正整数表示有限的重试 K 线数量。

hold_bars: 持有多头或空头仓位的 K 线数量，超过后该仓位会自动平仓。

long_score: 在对买入和回补信号进行排序时用于给 symbol 打分。订单会为 long_score 值最高的品种下达，pybroker.portfolio.Portfolio 中任一时刻持有的多头仓位数量由 pybroker.strategy.Strategy.set_max_long_positions() 指定。当通过 pybroker.strategy.Strategy.enable_rotation() 启用了轮动时， long_score 会驱动多头轮动，而 pybroker.strategy.Execution 中设置的订单会被忽略。

short_score: 在对卖出信号进行排序时用于给 symbol 打分。订单会为 short_score 值最高的品种下达，pybroker.portfolio.Portfolio 中任一时刻持有的空头仓位数量由 pybroker.strategy.Strategy.set_max_short_positions() 指定。当通过 pybroker.strategy.Strategy.enable_rotation() 启用了轮动时， short_score 会驱动空头轮动，而 pybroker.strategy.Execution 中设置的订单会被忽略。

session: 用于存储自定义数据的 dict，在 pybroker.strategy.Strategy的执行过程中按每根 K 线持久化。

stop_loss: 在新的 pybroker.portfolio.Entry 上设置止损，其值以距入场价格的点数衡量。

stop_loss_pct: 在新的 pybroker.portfolio.Entry 上设置止损，其值以距入场价格的百分比衡量。

stop_loss_limit: 该止损使用的限价。

stop_loss_exit_price: 止损离场时使用的离场 pybroker.common.PriceType。如果设置了该值，止损会依据 exit_price 进行判定，并在触发时以 exit_price 离场。

stop_profit: 在新的 pybroker.portfolio.Entry 上设置止盈，其值以距入场价格的点数衡量。

stop_profit_pct: 在新的 pybroker.portfolio.Entry 上设置止盈，其值以距入场价格的百分比衡量。

stop_profit_limit: 该止盈使用的限价。

stop_profit_exit_price: 止盈离场时使用的离场 pybroker.common.PriceType。如果设置了该值，止盈会依据 exit_price 进行判定，并在触发时以 exit_price 离场。

stop_trailing: 在新的 pybroker.portfolio.Entry 上设置移动止损，其值以距入场价格的点数衡量。

stop_trailing_pct: 在新的 pybroker.portfolio.Entry 上设置移动止损，其值以距入场价格的百分比衡量。

stop_trailing_limit: 该移动止损使用的限价。

stop_trailing_exit_price: 移动止损离场时使用的离场 pybroker.common.PriceType。如果设置了该值，止损会依据 exit_price 进行判定，并在触发时以 exit_price 离场。

property bars: int: 已完成的数据 K 线数量。

property buying_power: Decimal

在给定 pybroker.config.StrategyConfig.leverage 的情况下，可用于多头和空头订单的购买力。

这正是 pybroker.portfolio.Portfolio 在成交时用来限定订单的依据。而 calc_target_shares() 则是按可部署资本（权益乘以杠杆）来确定规模的，因此一旦有仓位开仓，两者可能会出现差异。

calc_target_shares(target_size: float, price: float | None = None, cash: float | None = None) → Decimal | int[源代码]

根据 target_size 分配比例和股票 price，计算股数。

参数:

target_size -- 用于计算股数的可部署资本比例，其中 target_size 的最大值为 1。例如， target_size 为 0.1 表示可部署资本的 10%。
price -- 用于计算股数的股价。如果为 None，则使用 ExecContext的 symbol 的股价。
cash -- 用于计算股数的资本。如果为 None，则使用可部署资本，定义为投资组合权益乘以 pybroker.config.StrategyConfig.leverage。生成的订单在下达时仍会受到 buying_power 的限制。

返回:

根据 target_size 和股票 price 计算出的股数。如果 pybroker.config.StrategyConfig.enable_fractional_shares 为 True，则返回一个 Decimal。

cancel_all_pending_orders(symbol: str | None = None)[源代码]: 取消 symbol 的所有 pybroker.scope.PendingOrder。当 symbol 为 None 时，取消所有待处理订单。

cancel_pending_order(order_id: int) → bool[源代码]: 取消 ID 为 order_id 的 pybroker.scope.PendingOrder。

cancel_stop(stop_id: int) → bool[源代码]: 取消 ID 为 stop_id 的 pybroker.portfolio.Stop。

cancel_stops(val: str | Position | Entry, stop_type: StopType | None = None)[源代码]

取消 pybroker.portfolio.Stop。

参数:

val -- 要取消止损的股票代码、pybroker.portfolio.Position 或 pybroker.portfolio.Entry。
stop_type -- pybroker.common.StopType。

property cash: Decimal: pybroker.portfolio.Portfolio 中当前持有的现金总额。

property close: NDArray[float64]: 当前 K 线的收盘价。

property close_price: float: 当前 K 线的收盘价（标量形式）。

cover_all_shares()[源代码]: 回补 ExecContext.symbol 的全部空头股份。

property cover_fill_price: int | float | floating | Decimal | PriceType | Callable[[str, BarData], int | float | Decimal] | None: buy_fill_price 的别名。设置后，会使买入订单在任何卖出订单之前下达。

property cover_limit_price: int | float | Decimal | None: buy_limit_price 的别名。设置后，会使买入订单在任何卖出订单之前下达。

property cover_shares: int | float | Decimal | None: buy_shares 的别名。设置后，会使买入订单在任何卖出订单之前下达。

property dt: datetime: 以 datetime 表示的当前 K 线日期。

foreign(symbol: str, col: str | None = None) → BarData | NDArray | None[源代码]

获取另一个股票代码的 K 线数据。

参数:

symbol -- 该 K 线数据的股票代码。
col -- 要获取的数据列名称。如果为 None，则以 pybroker.common.BarData 形式返回所有数据列。

返回:

如果 col 为 None，则返回一个 pybroker.common.BarData 实例，其中包含截至当前 K 线为止所有 K 线的数据。否则，返回一个包含 col 列值的 numpy.ndarray。

has_long_positions() → bool[源代码]: 返回当前是否存在任何未平仓多头头寸。

has_short_positions() → bool[源代码]: 返回当前是否存在任何未平仓空头头寸。

property high: NDArray[float64]: 当前 K 线的最高价。

property high_price: float: 当前 K 线的最高价（标量形式）。

hyperparam(name: str) → Any[源代码]

返回该执行函数的一个超参数值。

该名称必须已通过 pybroker.strategy.Strategy.add_execution() 上的 hyperparams=[...] 附加。

indicator(name: str, symbol: str | None = None) → NDArray[float64][源代码]

返回指标数据。

参数:

name -- 用于标识该指标的名称，通过 pybroker.indicator.indicator() 注册。
symbol -- 用于生成该指标数据的股票代码。如果为 None，则使用 ExecContext的 symbol。

返回:

截至当前 K 线为止所有 K 线的指标值 numpy.ndarray，按时间先后升序排列。

input(model_name: str, symbol: str | None = None) → DataFrame[源代码]

返回用于进行预测的模型输入数据。

参数:

model_name -- 该输入数据对应模型的名称。
symbol -- 该输入数据对应模型的股票代码。如果为 None，则使用 ExecContext的 symbol。

返回:

包含输入数据的 pandas.DataFrame，每一行代表截至当前 K 线为止序列中的一根 K 线。各行按时间先后升序排列。

interval(interval: int | Literal['daily', 'weekly', 'monthly', 'quarterly', 'yearly'] | str) → IntervalContext[源代码]

返回 interval 压缩 K 线数据的只读视图。

interval 必须与该执行函数在 pybroker.strategy.Strategy.add_execution() 中通过 intervals 声明的值匹配，或者与通过 pybroker.model.ModelSource.intervals() / pybroker.indicator.Indicator.intervals() 绑定到其某个模型或指标的区间匹配。区间的作用域限定在各自的执行函数内：读取另一个执行函数声明的区间会引发 ValueError，这与 hyperparam() 受该执行函数的 hyperparams 限定的方式相同。支持相同的 TimeframeInterval 形式：

每 n 根 K 线 （int）：例如 ctx.interval(5) 表示由每 5 根基础 K 线形成的 K 线。
时长（str）：例如 ctx.interval("5m") 表示固定时长的分箱（数字加单位字母）。
日历（str）：例如 ctx.interval("weekly") 表示日历周线 K 线。周从周一开始，月从每月 1 日开始，季度从 1、4、7、10 月开始，年从 1 月 1 日开始。

例如:

strategy.add_execution(
    exec_fn,
    "SPY",
    indicators=[sma20.intervals("weekly")],
    intervals=["5m"],
)
strategy.walkforward(windows=1, timeframe="1m")

def exec_fn(ctx):
    weekly = ctx.interval("weekly")
    five_min = ctx.interval("5m")
    if len(weekly.close) > 0:
        wk_sma = weekly.indicator("sma20")

参数:: interval -- 该执行函数通过 pybroker.strategy.Strategy.add_execution() 声明的压缩区间，或绑定到其某个模型或指标的区间。
返回:: 公开压缩 K 线上只读 OHLCV、指标和模型输出的 pybroker.context.IntervalContext。

long_pos(symbol: str | None = None) → Position | None[源代码]

获取 symbol 当前的多头 pybroker.portfolio.Position。

参数:: symbol -- 要返回的头寸的股票代码。如果为 None，则使用 ExecContext的 symbol。默认为 None。
返回:: 如果存在则为 pybroker.portfolio.Position，否则为 None。

long_positions(symbol: str | None = None) → Iterator[Position][源代码]

获取所有当前的多头头寸。

参数:: symbol -- 用于过滤头寸的股票代码。如果为 None，则返回所有品种的多头头寸。默认为 None。
返回:: 当前持有的多头 pybroker.portfolio.Position 的 Iterator。

property loss_rate: Decimal: 交易的滚动败率。

property low: NDArray[float64]: 当前 K 线的最低价。

property low_price: float: 当前 K 线的最低价（标量形式）。

property margin_loan: Decimal: 用于多头和空头杠杆仓位的借入资金。

model(name: str, symbol: str | None = None) → Any[源代码]

返回一个已训练的模型。

参数:

name -- 用于标识该模型的名称，通过 pybroker.model.model() 注册。
symbol -- 用于训练该模型的数据所对应的股票代码。如果为 None，则使用 ExecContext的 symbol。

返回:

已训练模型的实例。

property net_cash_balance: Decimal: 净现金余额（cash - margin_loan）。

property open: NDArray[float64]: 当前 K 线的开盘价。

property open_price: float: 当前 K 线的开盘价（标量形式）。

orders() → Iterator[Order][源代码]: 所有已下达并成交的 pybroker.portfolio.Order的 Iterator。

pending_orders(symbol: str | None = None) → Iterator[PendingOrder][源代码]

pos(symbol: str, pos_type: Literal['long', 'short']) → Position | None[源代码]

获取 symbol 当前的多头或空头 pybroker.portfolio.Position。

参数:

symbol -- 要返回的头寸的股票代码。
pos_type -- 指定要返回 long 还是 short 头寸。

返回:

如果存在则为 pybroker.portfolio.Position，否则为 None。

positions(symbol: str | None = None, pos_type: Literal['long', 'short'] | None = None) → Iterator[Position][源代码]

获取所有当前的头寸。

参数:

symbol -- 用于过滤头寸的股票代码。如果为 None，则返回所有品种的头寸。默认为 None。
pos_type -- 要返回的头寸类型。如果为 None，则同时返回 long 和 short 头寸。

返回:

当前持有的 pybroker.portfolio.Position 的 Iterator。

preds(model_name: str, symbol: str | None = None) → NDArray[源代码]

返回模型预测结果。

参数:

model_name -- 做出该预测的模型名称。
symbol -- 做出该预测的模型所对应的股票代码。如果为 None，则使用 ExecContext的 symbol。

返回:

包含截至当前 K 线为止模型预测结果序列的 numpy.ndarray。按时间先后升序排列。

sell_all_shares()[源代码]: 卖出 ExecContext.symbol 的全部多头股份。

set_target_shares(target: float, *, dir: Literal['long', 'short'])[源代码]

设置订单以达到多头或空头敞口的目标配置。

使用 calc_target_shares() 计算达到 target 所需的股数。

参数:

target -- 目标配置，以可部署资本的比例表示，定义为投资组合权益乘以 pybroker.config.StrategyConfig.leverage。 target 的最大值为 1。
dir -- 要再平衡的敞口方向。 "long" 会设置 buy_shares 或 sell_shares。 "short" 会设置 sell_shares 以增加空头敞口，或设置 cover_shares 以减少空头敞口。

short_pos(symbol: str | None = None) → Position | None[源代码]

获取 symbol 当前的空头 pybroker.portfolio.Position。

参数:: symbol -- 要返回的头寸的股票代码。如果为 None，则使用 ExecContext的 symbol。默认为 None。
返回:: 如果存在则为 pybroker.portfolio.Position，否则为 None。

short_positions(symbol: str | None = None) → Iterator[Position][源代码]

获取所有当前的空头头寸。

参数:: symbol -- 用于过滤头寸的股票代码。如果为 None，则返回所有品种的空头头寸。默认为 None。
返回:: 当前持有的空头 pybroker.portfolio.Position 的 Iterator。

to_result() → ExecResult | None[源代码]: 根据设置在 ExecContext 上的数据创建一个 ExecResult。

property total_equity: Decimal: pybroker.portfolio.Portfolio 中当前持有的权益总额。

property total_margin: Decimal: pybroker.portfolio.Portfolio 中当前持有的保证金总额。

property total_market_value: Decimal: pybroker.portfolio.Portfolio 中当前持有的总市值。市值定义为以现金和多头头寸形式持有的权益金额，加上所有未平仓空头头寸的未实现盈亏。

trades() → Iterator[Trade][源代码]: 所有已完成的 pybroker.portfolio.Trade的 Iterator。

property volume: NDArray[float64] | None: 当前 K 线的成交量。

property volume_value: float | None: 当前 K 线的成交量（标量形式）。

property vwap: NDArray[float64] | None: 当前 K 线的成交量加权平均价（VWAP）。

property vwap_value: float | None: 当前 K 线的 VWAP（标量形式）。

property win_rate: Decimal: 交易的滚动胜率。

基类：object

保存 pybroker.strategy.Strategy 执行过程中设置的数据。

symbol

该执行函数所使用的股票代码。

类型:: str

date

该执行函数所使用 K 线的时间戳。

类型:: numpy.datetime64

buy_fill_price

symbol 买入（做多）订单使用的成交价格。

类型:: int | float | numpy.floating | decimal.Decimal | pybroker.common.PriceType | Callable[[str, pybroker.common.BarData], int | float | decimal.Decimal]

sell_fill_price

symbol 卖出（做空）订单使用的成交价格。

类型:: int | float | numpy.floating | decimal.Decimal | pybroker.common.PriceType | Callable[[str, pybroker.common.BarData], int | float | decimal.Decimal]

long_score

在对买入和回补信号进行排序时用于给 symbol 打分。订单会为 long_score 值最高的品种下达，pybroker.portfolio.Portfolio 中任一时刻持有的多头仓位数量由 pybroker.strategy.Strategy.set_max_long_positions() 指定。当通过 pybroker.strategy.Strategy.enable_rotation() 启用了轮动时， long_score 会驱动多头轮动，而 pybroker.strategy.Execution 中设置的订单会被忽略。

类型:: float | None

short_score

在对卖出信号进行排序时用于给 symbol 打分。订单会为 short_score 值最高的品种下达，pybroker.portfolio.Portfolio 中任一时刻持有的空头仓位数量由 pybroker.strategy.Strategy.set_max_short_positions() 指定。当通过 pybroker.strategy.Strategy.enable_rotation() 启用了轮动时， short_score 会驱动空头轮动，而 pybroker.strategy.Execution 中设置的订单会被忽略。

类型:: float | None

hold_bars

持有多头或空头仓位的 K 线数量，超过后该仓位会自动平仓。

类型:: int | None

buy_shares

symbol 要买入的股数。

类型:: decimal.Decimal | None

buy_limit_price

symbol 买入（做多）订单使用的限价。

类型:: decimal.Decimal | None

buy_timeout_bars

未成交的买入限价单在首次尝试后重试的 K 线数量。 None 表示仅尝试一次， -1 表示无限期保留，正整数表示有限的重试 K 线数量。

类型:: int | None

sell_shares

symbol 要卖出的股数。

类型:: decimal.Decimal | None

sell_limit_price

symbol 卖出（做空）订单使用的限价。

类型:: decimal.Decimal | None

sell_timeout_bars

未成交的卖出限价单在首次尝试后重试的 K 线数量。 None 表示仅尝试一次， -1 表示无限期保留，正整数表示有限的重试 K 线数量。

类型:: int | None

long_stops

多头 pybroker.portfolio.Entry的止损。

类型:: frozenset[pybroker.portfolio.Stop] | None

short_stops

空头 pybroker.portfolio.Entry的止损。

类型:: frozenset[pybroker.portfolio.Stop] | None

cover

buy_shares 是否用于回补空头仓位。如果为 True，生成的买入订单会在卖出订单之前下达。

类型:: bool

pending_order_id

已创建的 pybroker.scope.PendingOrder 的 ID。

类型:: int | None

exit_pos_type

该订单所平掉的 pybroker.portfolio.Position 类型，为 long 或 short；当该订单不是离场订单时为 None。由 ExecContext.sell_all_shares()、ExecContext.cover_all_shares()，以及目标为零的 ExecContext.set_target_shares() 设置。携带该值的订单在成交时会被限定在仍持有的股数以内，因此只能平仓，永远不会将仓位翻转。

类型:: Literal['long', 'short'] | None

class IntervalContext(symbol: str, interval: int | Literal['daily', 'weekly', 'monthly', 'quarterly', 'yearly'] | str, interval_scope: IntervalScope, sym_end_index: Mapping[str, int], models: Mapping[ModelSymbol, TrainedModel])[源代码]