"""Axis definitions for axis-aware NeuroWeave arrays."""

from __future__ import annotations

from typing import Any

import numpy as np


class Axis:
    """Represent a single named axis for an :class:`AxisArray`.

    Parameters
    ----------
    name : str
        Name of the axis.
    size : int
        Size of the axis.
    coords : np.ndarray | None, optional
        Coordinate labels associated with the axis.
    metadata : dict[str, Any] | None, optional
        Additional metadata describing the axis.
    """

    def __init__(
        self,
        name: str,
        size: int,
        coords: np.ndarray | None = None,
        metadata: dict[str, Any] | None = None,
    ) -> None:
        self.name = name
        self.size = size
        self.coords = coords
        self.metadata = metadata if metadata is not None else {}

    def summary(self) -> str:
        """Summarize the axis definition.

        Returns
        -------
        str
            Human-readable summary of the axis.
        """

        raise NotImplementedError()

    def index_of(self, value: Any) -> int:
        """Return the integer index for a coordinate value.

        Parameters
        ----------
        value : Any
            Coordinate value to resolve.

        Returns
        -------
        int
            Integer index corresponding to the coordinate value.
        """

        raise NotImplementedError()
