pybroker.slippage 模块

实现滑点模型。

class FixedSlippageModel(bps: float = 5)

基类：SlippageModel

对成交价格施加确定性的固定基点滑点。

买入成交价会向上调整（变差）；卖出成交价会向下调整（变差）。适用于多头入场、空头入场、多头离场和空头回补。

参数:

bps -- 以基点表示的不利滑点。 0 表示不产生任何效果。必须小于 10000 （100%），否则会使卖出成交价变为非正数。

adjust_fill_price(side: Literal['buy', 'sell'], fill_price: Decimal) → Decimal

返回根据 side 调整后的 fill_price，不使用额外的上下文信息。

apply_slippage(ctx: SlippageContext) → tuple[Decimal, Decimal]

使用成交 K 线的数据施加滑点。

返回的股数可以减少以模拟部分成交，但不能增加：如果返回值超过 ctx.shares （或为负数），会在成交时引发 ValueError。

返回:

滑点调整后的 (shares, fill_price) 元组。

property is_fill_noop: bool

对于该模型，apply_slippage() 是否不产生任何效果。

class SlippageContext(side: Literal['buy', 'sell'], symbol: str, shares: Decimal, fill_price: Decimal, col_scope: ColumnScope | None, ind_scope: IndicatorScope | None, sym_end_index: Mapping[str, int] | None, enable_fractional_shares: bool = True)

基类：object

传递给滑点调整逻辑的上下文。

side

订单方向，为 buy 或 sell。

类型:

Literal['buy', 'sell']

symbol

该订单的股票代码。

类型:

str

shares

滑点调整前待成交的股数。

类型:

decimal.Decimal

fill_price

在成交 K 线上确定的基础成交价格。

类型:

decimal.Decimal

col_scope

覆盖整个测试窗口的列作用域（column scope）—— 未 预先切片到成交 K 线。因果读取时，每次获取都必须使用成交 K 线的索引进行限定，例如 ctx.col_scope.fetch(ctx.symbol, "close", end_index=ctx.sym_end_index[ctx.symbol])；不带 end_index 的获取会返回整个窗口，包括成交之后的 K 线。当 K 线数据不可用时为 None，此时基于成交量和波动率的模型将不对成交进行调整。

类型:

pybroker.scope.ColumnScope | None

ind_scope

覆盖整个测试窗口的指标作用域（indicator scope）—— 与 col_scope 相同，同样需要使用 end_index 进行限定。当指标数据不可用时为 None，此时基于指标的模型将不对成交进行调整。

类型:

pybroker.scope.IndicatorScope | None

sym_end_index

每个品种当前的 K 线索引，不可用时为 None。

类型:

Mapping[str, int] | None

enable_fractional_shares

是否启用碎股（fractional shares）。为 False 时，调用方会将返回的股数截断为整数；该标志使模型能够根据实际将要成交的数量来计算与价格相关的值（例如成交量参与度）。

类型:

bool

class SlippageModel

基类：ABC

用于实现滑点模型的基类。

滑点模型可以在 apply_slippage() 中使用成交 K 线的数据，调整成交价格、股数，或两者同时调整。

apply_slippage() 会在以下情况下被调用：已排定的买入和卖出订单、止损离场（止损、止盈、移动止损和 K 线止损），以及 pybroker.portfolio.Portfolio.exit_position() 成交。止损和离场成交仅应用返回的 成交价格；返回的股数会被忽略，因为这些路径会全部平掉一笔入场。

adjust_fill(side: Literal['buy', 'sell'], symbol: str, shares: Decimal, fill_price: Decimal, col_scope: ColumnScope | None = None, ind_scope: IndicatorScope | None = None, sym_end_index: Mapping[str, int] | None = None, enable_fractional_shares: bool = True) → tuple[Decimal, Decimal]

构建一个 SlippageContext，并对其应用 apply_slippage()。

提供此方法是为了让无法导入 pybroker.slippage 的调用方（例如 pybroker.portfolio）仍然能够对成交施加滑点。

返回:

滑点调整后的 (shares, fill_price) 元组。

apply_slippage(ctx: SlippageContext) → tuple[Decimal, Decimal]

使用成交 K 线的数据施加滑点。

返回的股数可以减少以模拟部分成交，但不能增加：如果返回值超过 ctx.shares （或为负数），会在成交时引发 ValueError。

返回:

滑点调整后的 (shares, fill_price) 元组。

property is_fill_noop: bool

对于该模型，apply_slippage() 是否不产生任何效果。

validate(strategy: Strategy) → None

在回测开始前验证模型配置。

class VolatilitySlippageModel(atr_period: int = 14, scale: float = 0.1)

基类：SlippageModel

基于 ATR 缩放的成交价格滑点。

不利价格调整等于成交 K 线上的 scale * ATR，其中平均真实波幅（Average True Range）是基于截至成交 K 线为止的 atr_period 根 K 线计算的（参见 pybroker.vect.atr()）。在预热期内（即没有完整 ATR 窗口的前 atr_period 根 K 线）成交，或 ATR 为 NaN 的 K 线上成交，均不会被调整。

参数:

• atr_period -- ATR 的回溯 K 线数量。默认为 14。

• scale -- 施加于 ATR 值的乘数。

apply_slippage(ctx: SlippageContext) → tuple[Decimal, Decimal]

使用成交 K 线的数据施加滑点。

返回的股数可以减少以模拟部分成交，但不能增加：如果返回值超过 ctx.shares （或为负数），会在成交时引发 ValueError。

返回:

滑点调整后的 (shares, fill_price) 元组。

property is_fill_noop: bool

对于该模型，apply_slippage() 是否不产生任何效果。

class VolumeSlippageModel(price_impact: float = 0.1, volume_limit: float | None = 0.025)

基类：SlippageModel

基于成交量的参与度上限与平方律价格冲击。

股数可能会被限制在 volume_limit * bar_volume 以内。价格冲击为 price_impact * (filled_shares / bar_volume) ** 2。传入 0 或 None 可禁用其中任一效应。

需要一个 volume 数据列，该列在 PyBroker 中是可选的。成交量缺失或为 NaN 的 K 线不会被调整。

参数:

• price_impact -- 平方律冲击系数。 0 表示禁用冲击。

• volume_limit -- 作为 K 线成交量比例的最大参与度。 None 或 0 表示禁用该上限。

apply_slippage(ctx: SlippageContext) → tuple[Decimal, Decimal]

使用成交 K 线的数据施加滑点。

返回的股数可以减少以模拟部分成交，但不能增加：如果返回值超过 ctx.shares （或为负数），会在成交时引发 ValueError。

返回:

滑点调整后的 (shares, fill_price) 元组。

property is_fill_noop: bool

对于该模型，apply_slippage() 是否不产生任何效果。

validate(strategy: Strategy) → None

在回测开始前验证模型配置。