Assets

Asset definitions (Equity, Bond, Commodity) and AssetView, which pairs an asset with its data.

asset

Financial assets and the per-asset view.

Asset is the immutable base class holding a name, currency, identifier and asset type; Equity, Bond and Commodity extend it. The index pipeline accepts only Equity. AssetView pairs an asset identifier with a DataFetcher so you can ask one asset for its prices, returns, reference data and corporate actions.

Asset dataclass

Asset(
    name: str,
    currency: str,
    asset_id: str = "",
    asset_type: str = "",
)

Base class for a financial asset. An immutable metadata container.

Every field must be non-empty, or construction raises ValueError.

The index pipeline accepts only :class:~beacon.asset.equity.Equity. Subclasses such as :class:~beacon.asset.bond.Bond and :class:~beacon.asset.commodity.Commodity are usable as metadata, but a universe containing one is refused by selection, weighting, market values and corporate-action handling alike; see :func:~beacon.asset.equity.require_equity.

Bond dataclass

Bond(
    name: str,
    currency: str,
    asset_id: str = "",
    asset_type: str = "",
    coupon: float = 0.0,
    maturity_date: str = "",
    issuer: str = "",
    credit_rating: str | None = None,
    face_value: float = 1000.0,
)

Bases: Asset

Represents a bond security.

Commodity dataclass

Commodity(
    name: str,
    currency: str,
    asset_id: str = "",
    asset_type: str = "",
    commodity_type: str = "",
    contract_unit: str = "",
)

Bases: Asset

Represents a commodity asset.

Equity dataclass

Equity(
    name: str,
    currency: str,
    asset_id: str = "",
    asset_type: str = "",
    ticker: str = "",
    exchange: str = "",
    isin: str | None = None,
    sector: str | None = None,
    country: str | None = None,
)

Bases: Asset

Represents an equity security.

asset_id defaults to ticker and asset_type to "EQUITY"; ticker and exchange must be non-empty.

This is the only asset type the index pipeline accepts. Selection, weighting, market values and corporate-action divisor adjustments all read market data keyed by :attr:ticker and all reason in terms of shares outstanding and free float, none of which the other :class:~beacon.asset.base.Asset subclasses carry. A constituent that is not an equity is refused by :func:require_equity at whichever of those layers meets it first, rather than admitted, skipped, or zeroed.

AssetView

AssetView(asset_id: str, data_fetcher: DataFetcher)

Queryable wrapper that pairs an asset identifier with a DataFetcher.

Parameters:

Name	Type	Description	Default
asset_id	str	The identifier used to look up data in the DataFetcher.	required
data_fetcher	DataFetcher	The data provider instance.	required

prices

prices(start: str, end: str) -> pd.DataFrame

Retrieve historical OHLCV price data.

Parameters:

Name	Type	Description	Default
start	str	Start date (YYYY-MM-DD).	required
end	str	End date (YYYY-MM-DD).	required

Returns:

Type	Description
DataFrame	pd.DataFrame: Price data indexed by date.

returns

returns(
    start: str,
    end: str,
    frequency: str = "daily",
    price_column: str = "CLOSE",
) -> pd.Series

Calculate a return series from price data.

Parameters:

Name	Type	Description	Default
start	str	Start date (YYYY-MM-DD).	required
end	str	End date (YYYY-MM-DD).	required
frequency	str	One of "daily", "weekly", or "monthly".	'daily'
price_column	str	Column name to use for return calculation. Defaults to "CLOSE".	'CLOSE'

Returns:

Type	Description
Series	pd.Series: Percentage returns indexed by date.

Raises:

Type	Description
ValueError	If frequency is not one of the supported values.

reference_data

reference_data(date: str | None = None) -> pd.DataFrame

Fetch static reference data (e.g. name, sector, exchange).

Parameters:

Name	Type	Description	Default
date	str | None	Point-in-time date for the reference snapshot.	None

Returns:

Type	Description
DataFrame	pd.DataFrame: Reference data for this asset.

corporate_actions

corporate_actions(start: str, end: str) -> pd.DataFrame

Retrieve corporate action events (dividends, splits, etc.).

Parameters:

Name	Type	Description	Default
start	str	Start date (YYYY-MM-DD).	required
end	str	End date (YYYY-MM-DD).	required

Returns:

Type	Description
DataFrame	pd.DataFrame: Corporate actions within the date range.

base

Module defining the base class for financial assets.

Asset dataclass

Asset(
    name: str,
    currency: str,
    asset_id: str = "",
    asset_type: str = "",
)

Base class for a financial asset. An immutable metadata container.

Every field must be non-empty, or construction raises ValueError.

The index pipeline accepts only :class:~beacon.asset.equity.Equity. Subclasses such as :class:~beacon.asset.bond.Bond and :class:~beacon.asset.commodity.Commodity are usable as metadata, but a universe containing one is refused by selection, weighting, market values and corporate-action handling alike; see :func:~beacon.asset.equity.require_equity.

bond

Module defining the Bond asset class.

Bond dataclass

Bond(
    name: str,
    currency: str,
    asset_id: str = "",
    asset_type: str = "",
    coupon: float = 0.0,
    maturity_date: str = "",
    issuer: str = "",
    credit_rating: str | None = None,
    face_value: float = 1000.0,
)

Bases: Asset

Represents a bond security.

commodity

Module defining the Commodity asset class.

Commodity dataclass

Commodity(
    name: str,
    currency: str,
    asset_id: str = "",
    asset_type: str = "",
    commodity_type: str = "",
    contract_unit: str = "",
)

Bases: Asset

Represents a commodity asset.

equity

Module defining the Equity asset class, and the index pipeline's equity-only gate.

Equity dataclass

Equity(
    name: str,
    currency: str,
    asset_id: str = "",
    asset_type: str = "",
    ticker: str = "",
    exchange: str = "",
    isin: str | None = None,
    sector: str | None = None,
    country: str | None = None,
)

Bases: Asset

Represents an equity security.

asset_id defaults to ticker and asset_type to "EQUITY"; ticker and exchange must be non-empty.

This is the only asset type the index pipeline accepts. Selection, weighting, market values and corporate-action divisor adjustments all read market data keyed by :attr:ticker and all reason in terms of shares outstanding and free float, none of which the other :class:~beacon.asset.base.Asset subclasses carry. A constituent that is not an equity is refused by :func:require_equity at whichever of those layers meets it first, rather than admitted, skipped, or zeroed.

require_equity

require_equity(
    asset: Asset, calculation_name: str, action: str
) -> Equity

Return asset as an :class:Equity, or raise if it is not one.

Every stage of the index pipeline (selection, weighting, market values and corporate-action adjustments) calls this, so a non-equity constituent is refused rather than skipped, zeroed or silently admitted.

Parameters:

Name	Type	Description	Default
asset	Asset	The constituent to check.	required
calculation_name	str	What is refusing: a rule, scheme, or stage name.	required
action	str	The passive verb phrase completing "it cannot ..." ("be weighted", "be valued"), so the message says what could not be done.	required

Returns:

Name	Type	Description
Equity	Equity	asset, narrowed, so callers get the ticker-bearing type back
	Equity	rather than checking and casting separately.

Raises:

Type	Description
CalculationError	If asset is not an :class:Equity. The message names the asset and its actual type, because "not an equity" alone does not say which name in the universe to go and look at.

view

AssetView: a convenience wrapper that pairs an asset identifier with a DataFetcher, so one asset's prices, returns, reference data and corporate actions can be fetched without repeating the identifier.

AssetView

AssetView(asset_id: str, data_fetcher: DataFetcher)

Queryable wrapper that pairs an asset identifier with a DataFetcher.

Parameters:

Name	Type	Description	Default
asset_id	str	The identifier used to look up data in the DataFetcher.	required
data_fetcher	DataFetcher	The data provider instance.	required

prices

prices(start: str, end: str) -> pd.DataFrame

Retrieve historical OHLCV price data.

Parameters:

Name	Type	Description	Default
start	str	Start date (YYYY-MM-DD).	required
end	str	End date (YYYY-MM-DD).	required

Returns:

Type	Description
DataFrame	pd.DataFrame: Price data indexed by date.

returns

returns(
    start: str,
    end: str,
    frequency: str = "daily",
    price_column: str = "CLOSE",
) -> pd.Series

Calculate a return series from price data.

Parameters:

Name	Type	Description	Default
start	str	Start date (YYYY-MM-DD).	required
end	str	End date (YYYY-MM-DD).	required
frequency	str	One of "daily", "weekly", or "monthly".	'daily'
price_column	str	Column name to use for return calculation. Defaults to "CLOSE".	'CLOSE'

Returns:

Type	Description
Series	pd.Series: Percentage returns indexed by date.

Raises:

Type	Description
ValueError	If frequency is not one of the supported values.

reference_data

reference_data(date: str | None = None) -> pd.DataFrame

Fetch static reference data (e.g. name, sector, exchange).

Parameters:

Name	Type	Description	Default
date	str | None	Point-in-time date for the reference snapshot.	None

Returns:

Type	Description
DataFrame	pd.DataFrame: Reference data for this asset.

corporate_actions

corporate_actions(start: str, end: str) -> pd.DataFrame

Retrieve corporate action events (dividends, splits, etc.).

Parameters:

Name	Type	Description	Default
start	str	Start date (YYYY-MM-DD).	required
end	str	End date (YYYY-MM-DD).	required

Returns:

Type	Description
DataFrame	pd.DataFrame: Corporate actions within the date range.