"""PeriodId value object for representing temporal period identifiers."""


class PeriodId:
    """A lightweight immutable identifier for a temporal period."""

    __slots__ = ("_value",)

    # A unique object to ensure only Artip can create instances
    _creation_token = object()

    def __init__(self, value: int, token: object):
        if token is not self._creation_token:
            raise TypeError("PeriodId cannot be instantiated directly. Use Artip.make_period_id().")
        self._value = value

    @classmethod
    def _create(cls, value: int) -> "PeriodId":
        """Internal factory used by Artip to create PeriodId instances."""
        return cls(value, cls._creation_token)

    @property
    def value(self) -> int:
        """The numeric value of the period identifier."""
        return self._value

    def __setattr__(self, name: str, value: object) -> None:
        if name == "_value" and hasattr(self, "_value"):
            raise AttributeError("PeriodId is immutable")
        super().__setattr__(name, value)

    def __str__(self) -> str:
        """Return string representation of the period identifier."""
        return str(self._value)

    def __repr__(self) -> str:
        """Return detailed representation."""
        return f"PeriodId(value={self._value})"

    def __eq__(self, other: object) -> bool:
        """Support equality comparison."""
        if not isinstance(other, PeriodId):
            return NotImplemented
        return self._value == other._value

    def __hash__(self) -> int:
        """Support use as dictionary key or in sets."""
        return hash(self._value)
