Source code for kaxanuk.attribution_analysis.entities.ticker

"""
Security ticker value object for use in all entities and aggregates.
"""

import dataclasses
import re

from kaxanuk.attribution_analysis.exceptions import EntityValueError



@dataclasses.dataclass(frozen=True, slots=True)
class Ticker:
    """
    Immutable value object representing a security ticker symbol.

    Validation performed automatically on construction:

    * `symbol` must be a `str`.
    * `symbol` must match the allowed ticker character set
      (letters, digits, ``.``, ``*``, ``-``, ``^``).

    Parameters
    ----------
    symbol : str
        The ticker symbol (e.g. ``"AAPL"``, ``"BRK.B"``).

    Raises
    ------
    EntityValueError
        If `symbol` is not a string, or does not match the expected
        ticker format.
    """

    symbol: str

    def __post_init__(self) -> None:
        """
        Validate `symbol` immediately after construction.

        Raises
        ------
        EntityValueError
            If `symbol` is not a string, or does not match the expected
            ticker format.
        """
        if not isinstance(self.symbol, str):
            raise EntityValueError("Ticker symbol must be a string")

        ticker_pattern = re.compile(r"^[A-Za-z0-9.*-^]+$")
        if ticker_pattern.fullmatch(self.symbol) is None:
            msg = f"Incorrect ticker symbol format: {self.symbol}"
            raise EntityValueError(msg)