beacon.asset¶

Financial asset definitions: the immutable Asset base dataclass and its Bond, Commodity, and Equity subclasses, plus AssetView, a queryable wrapper pairing an asset identifier with a DataFetcher.

asset ¶

The init.py for the 'asset' module.

This module defines and manages 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.

The index pipeline accepts only :class:~beacon.asset.equity.Equity (BN-185). 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.

This is the only asset type the index pipeline accepts (BN-185). 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

Source code in build/cache/py-beacon-2c9c3936c65abdb6b8403c50a023f58355be30ee/src/beacon/asset/view.py

def __init__(self,
             asset_id: str,
             data_fetcher: DataFetcher):
    if not asset_id:
        raise ValueError("asset_id cannot be empty.")
    if data_fetcher is None:
        raise ValueError("data_fetcher must be provided.")

    self._asset_id = asset_id
    self._data_fetcher = data_fetcher

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.

Source code in build/cache/py-beacon-2c9c3936c65abdb6b8403c50a023f58355be30ee/src/beacon/asset/view.py

def prices(self,
           start: str,
           end: str) -> pd.DataFrame:
    """Retrieve historical OHLCV price data.

    Args:
        start: Start date (YYYY-MM-DD).
        end: End date (YYYY-MM-DD).

    Returns:
        pd.DataFrame: Price data indexed by date.
    """
    return self._data_fetcher.fetch_market_data(self._asset_id, start, end)

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.

Source code in build/cache/py-beacon-2c9c3936c65abdb6b8403c50a023f58355be30ee/src/beacon/asset/view.py

def returns(self,
            start: str,
            end: str,
            frequency: str = "daily",
            price_column: str = "CLOSE") -> pd.Series:
    """Calculate a return series from price data.

    Args:
        start: Start date (YYYY-MM-DD).
        end: End date (YYYY-MM-DD).
        frequency: One of ``"daily"``, ``"weekly"``, or ``"monthly"``.
        price_column: Column name to use for return calculation. Defaults
            to ``"CLOSE"``.

    Returns:
        pd.Series: Percentage returns indexed by date.

    Raises:
        ValueError: If *frequency* is not one of the supported values.
    """
    supported = ("daily", "weekly", "monthly")
    if frequency not in supported:
        raise ValueError(
            f"Unsupported frequency '{frequency}'. Must be one of {supported}."
        )

    prices = self._data_fetcher.fetch_market_data(
        self._asset_id, start, end, columns=[price_column]
    )

    if prices.empty:
        return pd.Series(dtype=float)

    series = prices[price_column]

    resample_map = {"daily": None, "weekly": "W", "monthly": "ME"}
    rule = resample_map[frequency]
    if rule is not None:
        series = series.resample(rule).last().dropna()

    return series.pct_change().dropna()

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.

Source code in build/cache/py-beacon-2c9c3936c65abdb6b8403c50a023f58355be30ee/src/beacon/asset/view.py

def reference_data(self,
                   date: str | None = None) -> pd.DataFrame:
    """Fetch static reference data (e.g. name, sector, exchange).

    Args:
        date: Point-in-time date for the reference snapshot.

    Returns:
        pd.DataFrame: Reference data for this asset.
    """
    return self._data_fetcher.fetch_reference_data(self._asset_id, date)

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.

Source code in build/cache/py-beacon-2c9c3936c65abdb6b8403c50a023f58355be30ee/src/beacon/asset/view.py

def corporate_actions(self,
                      start: str,
                      end: str) -> pd.DataFrame:
    """Retrieve corporate action events (dividends, splits, etc.).

    Args:
        start: Start date (YYYY-MM-DD).
        end: End date (YYYY-MM-DD).

    Returns:
        pd.DataFrame: Corporate actions within the date range.
    """
    return self._data_fetcher.fetch_market_data(
        self._asset_id, start, end, columns=["DIVIDEND", "SPLIT"]
    )

beacon.asset¶

asset ¶

Asset dataclass ¶

Bond dataclass ¶

Commodity dataclass ¶

Equity dataclass ¶

AssetView ¶

prices ¶

returns ¶

reference_data ¶

corporate_actions ¶

Asset `dataclass` ¶

Bond `dataclass` ¶

Commodity `dataclass` ¶

Equity `dataclass` ¶