pybroker.portfolio module

Contains portfolio related functionality, such as portfolio metrics and placing orders.

class Entry(id: int, date: ~numpy.datetime64, symbol: str, shares: ~decimal.Decimal, price: ~decimal.Decimal, type: ~typing.Literal['long', 'short'], bars: int = 0, stops: list[~pybroker.portfolio.Stop] = <factory>, mae: ~decimal.Decimal = <factory>, mfe: ~decimal.Decimal = <factory>)[source]

Bases: object

Contains information about an entry into a Position.

id

Unique identifier.

Type:: int

date

Date of the entry.

Type:: numpy.datetime64

symbol

Symbol of the entry.

Type:: str

shares

Number of shares.

Type:: decimal.Decimal

price

Share price of the entry.

Type:: decimal.Decimal

type

Type of Position, either long or short.

Type:: Literal[‘long’, ‘short’]

bars

Current number of bars since entry.

Type:: int

stops

Stops set on the entry.

Type:: list[pybroker.portfolio.Stop]

mae

Maximum adverse excursion (MAE).

Type:: decimal.Decimal

mfe

Maximum favorable excursion (MFE).

Type:: decimal.Decimal

mae: Decimal

mfe: Decimal

class Order(id: int, type: Literal['buy', 'sell'], symbol: str, date: datetime64, shares: Decimal, limit_price: Decimal | None, fill_price: Decimal, fees: Decimal)[source]

Bases: NamedTuple

Holds information about a filled order.

id

Unique identifier.

Type:: int

type

Type of order, either buy or sell.

Type:: Literal[‘buy’, ‘sell’]

symbol

Ticker symbol of the order.

Type:: str

date

Date the order was filled.

Type:: numpy.datetime64

shares

Number of shares bought or sold.

Type:: decimal.Decimal

limit_price

Limit price that was used for the order.

Type:: decimal.Decimal | None

fill_price

Price that the order was filled at.

Type:: decimal.Decimal

fees

Brokerage fees for order.

Type:: decimal.Decimal

class Portfolio(cash: float, fee_mode: FeeMode | Callable[[FeeInfo], Decimal] | None = None, fee_amount: float | None = None, subtract_fees: bool = False, enable_fractional_shares: bool = False, max_long_positions: int | None = None, max_short_positions: int | None = None, record_stops: bool | None = False)[source]

Bases: object

Class representing a portfolio of holdings. The portfolio contains information about open positions and balances, and is also used to place buy and sell orders.

Parameters:

cash – Starting cash balance.
fee_mode – Brokerage fee mode.
fee_amount – Brokerage fee amount.
subtract_fees – Whether to subtract fees from the cash balance after an order is filled.
enable_fractional_shares – Whether to enable trading fractional shares.
max_long_positions – Maximum number of long Positions that can be held at a time. If None, then unlimited.
max_short_positions – Maximum number of short Positions that can be held at a time. If None, then unlimited.
record_stops – Whether to record stop data per-bar.

cash: Current cash balance.

equity: Current amount of equity.

market_value: Current market value. The market value is defined as the amount of equity held in cash and long positions added together with the unrealized PnL of all open short positions.

fees: Current brokerage fees.

fee_amount: Brokerage fee amount.

subtract_fees: Whether to subtract fees from the cash balance.

enable_fractional_shares: Whether to enable trading fractional shares.

orders: deque of all filled orders, sorted in ascending chronological order.

margin: Current amount of margin held in open positions.

pnl: Realized profit and loss (PnL).

long_positions: dict mapping ticker symbols to open long Positions.

short_positions: dict mapping ticker symbols to open short Positions.

symbols: Ticker symbols of all currently open positions.

bars: deque of snapshots of Portfolio state on every bar, sorted in ascending chronological order.

position_bars: deque of snapshots of Position states on every bar, sorted in ascending chronological order.

win_rate: Running win rate of trades.

loss_rate: Running loss rate of trades.

buy(date: datetime64, symbol: str, shares: Decimal, fill_price: Decimal, limit_price: Decimal | None = None, stops: Iterable[Stop] | None = None) → Order | None[source]

Places a buy order.

Parameters:

date – Date when the Order is placed.
symbol – Ticker symbol to buy.
shares – Number of shares to buy.
fill_price – If filled, the price used to fill the Order.
limit_price – Limit price of the Order.
stops – Stops to set on the Entry created from the Order, if filled.

Returns:

Order if the order was filled, otherwise None.

capture_bar(date: datetime64, df: DataFrame)[source]

Captures portfolio state of the current bar.

Parameters:

date – Date of current bar.
df – pandas.DataFrame containing close prices.

check_stops(date: datetime64, price_scope: PriceScope)[source]: Checks whether stops are triggered.

exit_position(date: datetime64, symbol: str, buy_fill_price: Decimal, sell_fill_price: Decimal)[source]: Exits any long and short positions for symbol at buy_fill_price and sell_fill_price.

incr_bars()[source]: Increments the number of bars held by every trade entry.

remove_stop(stop_id: int) → bool[source]: Removes a Stop with stop_id.

remove_stops(val: str | Position | Entry, stop_type: StopType | None = None)[source]

Removes Stops.

Parameters:

val – Ticker symbol, Position, or Entry for which to cancel stops.
stop_type – pybroker.common.StopType.

sell(date: datetime64, symbol: str, shares: Decimal, fill_price: Decimal, limit_price: Decimal | None = None, stops: Iterable[Stop] | None = None) → Order | None[source]

Places a sell order.

Parameters:

date – Date when the Order is placed.
symbol – Ticker symbol to sell.
shares – Number of shares to sell.
fill_price – If filled, the price used to fill the Order.
limit_price – Limit price of the Order.
stops – Stops to set on the Entry created from the Order, if filled.

Returns:

Order if the order was filled, otherwise None.

class PortfolioBar(date: datetime64, cash: Decimal, equity: Decimal, margin: Decimal, market_value: Decimal, pnl: Decimal, unrealized_pnl: Decimal, fees: Decimal)[source]

Bases: NamedTuple

Snapshot of Portfolio state, captured per bar.

date

Date of bar.

Type:: numpy.datetime64

cash

Amount of cash in Portfolio.

Type:: decimal.Decimal

equity

Amount of equity in Portfolio.

Type:: decimal.Decimal

margin

Amount of margin in Portfolio.

Type:: decimal.Decimal

market_value

Market value of Portfolio.

Type:: decimal.Decimal

pnl

Realized profit and loss (PnL) of Portfolio.

Type:: decimal.Decimal

unrealized_pnl

Unrealized profit and loss (PnL) of Portfolio.

Type:: decimal.Decimal

fees

Brokerage fees.

Type:: decimal.Decimal

class Position(symbol: str, shares: ~decimal.Decimal, type: ~typing.Literal['long', 'short'], close: ~decimal.Decimal = <factory>, equity: ~decimal.Decimal = <factory>, market_value: ~decimal.Decimal = <factory>, margin: ~decimal.Decimal = <factory>, pnl: ~decimal.Decimal = <factory>, entries: ~collections.deque[~pybroker.portfolio.Entry] = <factory>, bars: int = 0)[source]

Bases: object

Contains information about an open position in symbol.

symbol

Ticker symbol of the position.

Type:: str

shares

Number of shares.

Type:: decimal.Decimal

type

Type of position, either long or short.

Type:: Literal[‘long’, ‘short’]

close

Last close price of symbol.

Type:: decimal.Decimal

equity

Equity in the position.

Type:: decimal.Decimal

market_value

Market value of position.

Type:: decimal.Decimal

margin

Amount of margin in position.

Type:: decimal.Decimal

pnl

Unrealized profit and loss (PnL).

Type:: decimal.Decimal

entries

deque of position Entrys sorted in ascending chronological order.

Type:: collections.deque[pybroker.portfolio.Entry]

bars

Current number of bars since entry.

Type:: int

class PositionBar(symbol: str, date: datetime64, long_shares: Decimal, short_shares: Decimal, close: Decimal, equity: Decimal, market_value: Decimal, margin: Decimal, unrealized_pnl: Decimal)[source]

Bases: NamedTuple

Snapshot of an open Position‘s state, captured per bar.

symbol

Ticker symbol of Position.

Type:: str

date

Date of bar.

Type:: numpy.datetime64

long_shares

Number of shares long in Position.

Type:: decimal.Decimal

short_shares

Number of shares short in Position.

Type:: decimal.Decimal

close

Last close price of symbol.

Type:: decimal.Decimal

equity

Amount of equity in Position.

Type:: decimal.Decimal

market_value

Market value of Position.

Type:: decimal.Decimal

margin

Amount of margin in Position.

Type:: decimal.Decimal

unrealized_pnl

Unrealized profit and loss (PnL) of Position.

Type:: decimal.Decimal

Bases: NamedTuple

Contains information about a stop set on Entry.

id

Unique identifier.

Type:: int

symbol

Symbol of the stop.

Type:: str

stop_type

StopType.

Type:: pybroker.common.StopType

pos_type

Type of Position, either long or short.

Type:: Literal[‘long’, ‘short’]

percent

Percent from entry price.

Type:: decimal.Decimal | None

points

Cash amount from entry price.

Type:: decimal.Decimal | None

bars

Number of bars after which to trigger the stop.

Type:: int | None

fill_price

Price that the stop will be filled at.

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

limit_price

Limit price to use for the stop.

Type:: decimal.Decimal | None

exit_price

Exit pybroker.common.PriceType to use for the stop exit. If set, the stop is checked against the exit_price and exits at the exit_price when triggered.

Type:: pybroker.common.PriceType | None

stop_type: StopType: Alias for field number 2

Bases: NamedTuple

Records per-bar data about a stop.

date

Date of the bar.

Type:: numpy.datetime64

symbol

Symbol of the stop.

Type:: str

stop_id

Unique identifier.

Type:: int

stop_type

StopType.

Type:: str

pos_type

Type of Position, either long or short.

Type:: Literal[‘long’, ‘short’]

curr_value

Current value of the stop.

Type:: decimal.Decimal | None

curr_bars

Current bars of the stop.

Type:: int | None

percent

Percent from entry price.

Type:: decimal.Decimal | None

points

Cash amount from entry price.

Type:: decimal.Decimal | None

bars

Number of bars after which to trigger the stop.

Type:: int | None

fill_price

Price that the stop will be filled at.

Type:: decimal.Decimal | None

limit_price

Limit price to use for the stop.

Type:: decimal.Decimal | None

exit_price

Exit pybroker.common.PriceType to use for the stop exit. If set, the stop is checked against the exit_price and exits at the exit_price when triggered.

Type:: pybroker.common.PriceType | None

curr_value: Decimal | None: Alias for field number 5

stop_type: str: Alias for field number 3

class Trade(id: int, type: Literal['long', 'short'], symbol: str, entry_date: datetime64, exit_date: datetime64, entry: Decimal, exit: Decimal, shares: Decimal, pnl: Decimal, return_pct: Decimal, agg_pnl: Decimal, bars: int, pnl_per_bar: Decimal, stop: Literal['bar', 'loss', 'profit', 'trailing'] | None, mae: Decimal, mfe: Decimal)[source]