bayesline.api.equity.PortfolioApi

class bayesline.api.equity.PortfolioApi

Abstract base class for portfolio APIs.

This class defines the interface for portfolio APIs that provide access to portfolio data and metadata.

__init__()

Methods

__init__()
get_coverage([names, by, metric, stats, ...])	Get coverage information for portfolios.
get_coverage_as_task([names, by, metric, ...])
get_dates([names, ffill, collapse])	Get the available dates for portfolios.
get_fof_graph()	Get the fund-of-funds graph for the underlying portfolio source(s).
get_id_types()	Get the available ID types for each portfolio.
get_immediate_holdings(name, date[, id_type])	Get the direct holdings for a single portfolio at a single date.
get_portfolio(names[, start_date, end_date, ...])	Get portfolios for the given names between given start and end dates.
get_portfolio_as_task(names[, start_date, ...])
get_portfolio_groups()	Get the portfolio groups.
get_portfolio_names()	Get the list of portfolio names.
get_portfolios()	Get the list of portfolios with per-portfolio metadata.

Attributes

name	Get the name of the portfolio.

abstract property name: str

Get the name of the portfolio.

Returns

str

The name of the portfolio.

abstract get_id_types() → dict[str, list[str]]

Get the available ID types for each portfolio.

Returns

dict[str, list[IdType]]

The available ID types that at least a portion of assets can be mapped to for each portfolio.

abstract get_coverage(names: str | list[str] | None = None, *, by: Literal['date', 'asset'] = 'date', metric: Literal['count', 'holding'] = 'count', stats: list[str] | None = None, start_date: str | date | datetime | None = None, end_date: str | date | datetime | None = None) → DataFrame

Get coverage information for portfolios.

Parameters

namesstr | list[str] | None, default=None

The names of the portfolios. If not given all portfolios will be calculated.

byLiteral[“date”, “asset”], default=”date”

The coverage aggregation, either by date or by asset.

metricLiteral[“count”, “holding”], default=”count”

The metric to calculate, either count of observations or sum of holding values.

statslist[str] | None, default=None

List of ‘min’, ‘max’, ‘mean’, collapses by into these stats.

start_dateDateLike | None, default=None

If given, only consider holdings on or after this date. Combined with end_date (e.g. both set to a portfolio’s latest holdings date) this scopes by="asset" coverage to a single day.

end_dateDateLike | None, default=None

If given, only consider holdings on or before this date.

Returns

pl.DataFrame

The dated coverage count for each id type. portfolio_group and portfolio are the first two columns. If stats given, collapses the by index to the given aggregations.

abstract get_coverage_as_task(names: str | list[str] | None = None, *, by: Literal['date', 'asset'] = 'date', metric: Literal['count', 'holding'] = 'count', stats: list[str] | None = None, start_date: str | date | datetime | None = None, end_date: str | date | datetime | None = None) → Task[DataFrame]

abstract get_portfolio_names() → list[str]

Get the list of portfolio names.

Returns

list[str]

The list of portfolio names.

abstract get_portfolios() → list[PortfolioName]

Get the list of portfolios with per-portfolio metadata.

Same identifiers as get_portfolio_names() plus per-portfolio metadata (currently fof_depth) that the GUI uses to render the picker with FoF awareness. The list is in the same order as get_portfolio_names().

Returns

list[PortfolioName]

The list of portfolios with metadata.

abstract get_portfolio_groups() → dict[str, list[str]]

Get the portfolio groups.

Returns

dict[str, list[str]]

A dictionary mapping group names to lists of portfolio names.

abstract get_fof_graph() → dict[str, list[str]]

Get the fund-of-funds graph for the underlying portfolio source(s).

Returns

dict[str, list[str]]

Mapping parent_portfolio_id -> list[child_portfolio_id]. Children are the asset_id values from rows where asset_id_type == "portfolio_id". Collapsed across dates. Empty dict when the source has no FoF rows.

abstract get_dates(names: list[str] | str | None = None, *, ffill: bool = False, collapse: bool = False) → dict[str, list[date]]

Get the available dates for portfolios.

Parameters

nameslist[str] | str | None, default=None

The portfolio names to get dates for.

ffillbool, default=False

Whether to forward fill the dates.

collapsebool, default=False

Whether to collapse the results.

Returns

dict[str, list[dt.date]]

A dictionary mapping portfolio names to lists of available dates.

abstract get_portfolio(names: list[str] | str, start_date: str | date | datetime | None = None, end_date: str | date | datetime | None = None, id_type: str | None = None, *, unpack: bool = False, ffill: bool = False, currency: str | None = None) → DataFrame

Get portfolios for the given names between given start and end dates.

Parameters

nameslist[str] | str

The list of portfolio names.

start_dateDateLike | None, default=None

The start date of the data to return, inclusive.

end_dateDateLike | None, default=None

The end date of the data to return, inclusive.

id_typeIdType | None, default=None

ID type to return the portfolio holdings in.

unpackbool, default=False

Whether to unpack the portfolio holdings. If True, the portfolio holdings with asset_id_type “portfolio_id” will be unpacked into the asset_id and asset_id_type columns.

ffillbool, default=False

Whether to forward fill the portfolio holdings in between holdings dates.

currencystr | None, default=None

The currency to return the portfolio holdings in. If None, the portfolio holdings will be returned in the listing currency of the underlying assets, and in USD for portfolio holdings.

Returns

pl.DataFrame

A dataframe with columns portfolio_group, portfolio, date, input_asset_id, input_asset_id_type, asset_id, asset_id_type and value.

If no id_type is given then the input ID space will be used unmapped. In this case the columns asset_id, asset_id_type will not be returned.

abstract get_portfolio_as_task(names: list[str] | str, start_date: str | date | datetime | None = None, end_date: str | date | datetime | None = None, id_type: str | None = None, *, unpack: bool = False, ffill: bool = False, currency: str | None = None) → Task[DataFrame]

abstract get_immediate_holdings(name: str, date: str | date | datetime, id_type: str | None = None) → DataFrame

Get the direct holdings for a single portfolio at a single date.

Returns the portfolio’s immediate holdings without any fund-of-funds lookthrough decomposition. For an FoF parent, rows with asset_id_type == "portfolio_id" reference its child portfolios; for a leaf portfolio, all rows reference assets directly.

Parameters

namestr

The portfolio name.

dateDateLike

The single date to fetch holdings for.

id_typeIdType | None, default=None

ID type to return leaf asset_ids in. Defaults to the dataset’s master id type. portfolio_id-typed rows are unaffected. Leaf asset_ids that have no mapping to id_type keep their master id type; the output asset_id_type column may therefore be heterogeneous.

Returns

pl.DataFrame

Columns: date, portfolio_id, asset_id, asset_id_type, currency, share_qty, nav, asset_name.

asset_name resolution differs by row type:

• Leaf rows resolve via the dataset’s id mapper. Unmapped leaves fall back to the raw asset_id (matching the convention used by the report engine) so the column is never null for leaves.

• portfolio_id rows resolve via the dataset’s portfolio name list. Unknown child references surface as null so callers can distinguish dangling references from valid ones.