PyoMapping

class PyoMapping(PyoCollection[_K], Mapping[_K, _V_co], Generic[_K, _V_co]):  # pyright: ignore[reportImplicitAbstractClass]  # ruff:ignore[non-pep695-generic-class]
    """Extends `PyoCollection[K]` and `collections.abc.Mapping[K, V]`.

    Serves as a base class for pyochain mappings, such as `Dict`.

    Any concrete subclass must implement the required `Mapping` dunder methods:

    - `__getitem__`
    - `__iter__`
    - `__len__`
    """

    @abstractmethod
    @override
    def __getitem__(self, key: _K, /) -> _V_co: ...
    @override
    def __contains__(self, key: object, /) -> bool: ...
    @override
    def __eq__(self, other: object, /) -> bool: ...
    @override
    def keys(self) -> PyoKeysView[_K]:
        """Return a view of the `Mapping` keys.

        Returns:
            PyoKeysView[_K]: A view of the dictionary's keys.

        Example:
            ```python
            from pyochain import Dict
            from pyochain.abc import PyoKeysView

            data = Dict(a=1, b=2)
            keys = data.keys()
            assert isinstance(keys, PyoKeysView)
            assert keys.pipe(tuple) == ("a", "b")
            assert repr(keys) == "PyoKeysView(Dict('a': 1, 'b': 2))"
            ```
        """

    @override
    def values(self) -> PyoValuesView[_V_co]:
        """Return a view of the `Mapping` values.

        Returns:
            PyoValuesView[_V_co]: A view of the dictionary's values.

        Example:
            ```python
            from pyochain import Dict
            from pyochain.abc import PyoValuesView

            data = Dict(a=1, b=2)
            values = data.values()
            assert isinstance(values, PyoValuesView)
            assert values.pipe(tuple) == (1, 2)
            assert repr(values) == "PyoValuesView(Dict('a': 1, 'b': 2))"
            ```
        """

    @override
    def items(self) -> PyoItemsView[_K, _V_co]:
        """Return a view of the `Mapping` items.

        Returns:
            PyoItemsView[_K, _V_co]: A view of the dictionary's (key, value) pairs.

        Example:
            ```python
            from pyochain import Dict
            from pyochain.abc import PyoItemsView

            data = Dict(a=1, b=2)
            items = data.items()
            assert isinstance(items, PyoItemsView)
            assert items.pipe(tuple) == (("a", 1), ("b", 2))
            assert repr(items) == "PyoItemsView(Dict('a': 1, 'b': 2))"
            ```
        """

    @overload
    def get(self, key: _K, /) -> _V_co | None: ...
    @overload
    # pyrefly: ignore [invalid-variance]
    def get(
        self,
        key: _K,
        default: _V_co,  # pyright: ignore[reportGeneralTypeIssues]
        /,
    ) -> _V_co: ...
    @overload
    def get[T](self, key: _K, default: T, /) -> _V_co | T: ...
    @override
    def get[T](self, key: _K, default: T | None = None, /) -> _V_co | T | None: ...
    def get_item(self, key: _K) -> Option[_V_co]:
        """Retrieve a value from the `MutableMapping`.

        Returns `Some(value)` if the **key** exists, or `Null` if it does not.

        Args:
            key (_K): The key to look up.

        Returns:
            Option[_V_co]: `Some(value)` that is associated with the **key**, or `Null` if not found.

        Example:
            ```python
            from pyochain import Dict, Some

            data = Dict(a=1)
            item = data.get_item("a")
            assert item == Some(1)
            assert data.get_item("x").unwrap_or("Not Found") == "Not Found"
            ```
        """