# misc.py - Various Interface that did not deserve a dedicated module (yet)

#

# Copyright 2025 Octobus, contact@octobus.net

from __future__ import annotations

import abc

from typing import (

    Callable,

    Dict,

    Iterator,

    List,

    Optional,

    Protocol,

    Tuple,

)

class IHooks(Protocol):

    """A collection of hook functions that can be used to extend a

    function's behavior. Hooks are called in lexicographic order,

    based on the names of their sources."""

    @abc.abstractmethod

    def add(self, source: bytes, hook: Callable):

        ...

    @abc.abstractmethod

    def __call__(self, *args) -> List:

        ...

class IDirs(Protocol):

    '''a multiset of directory names from a set of file paths'''

    @abc.abstractmethod

    def addpath(self, path: bytes) -> None:

        ...

    @abc.abstractmethod

    def delpath(self, path: bytes) -> None:

        ...

    @abc.abstractmethod

    def __iter__(self) -> Iterator[bytes]:

        ...

    @abc.abstractmethod

    def __contains__(self, d: bytes) -> bool:

        ...

AuthInfoT = Tuple[

    bytes,

    Optional[

        Tuple[

            None,

            Tuple[bytes, bytes],

            bytes,

            bytes,

        ]

    ],

]

class IUrl(Protocol):

    r"""Reliable URL parser.

    This parses URLs and provides attributes for the following

    components:

    <scheme>://<user>:<passwd>@<host>:<port>/<path>?<query>#<fragment>

    Missing components are set to None. The only exception is

    fragment, which is set to '' if present but empty.

    If parsefragment is False, fragment is included in query. If

    parsequery is False, query is included in path. If both are

    False, both fragment and query are included in path.

    See http://www.ietf.org/rfc/rfc2396.txt for more information.

    """

    path: Optional[bytes]

    scheme: Optional[bytes]

    user: Optional[bytes]

    passwd: Optional[bytes]

    host: Optional[bytes]

    port: Optional[bytes]

    query: Optional[bytes]

    fragment: Optional[bytes]

    @abc.abstractmethod

    def copy(self) -> IUrl:

        ...

    @abc.abstractmethod

    def authinfo(self) -> AuthInfoT:

        ...

    @abc.abstractmethod

    def isabs(self) -> bool:

        ...

    @abc.abstractmethod

    def localpath(self) -> bytes:

        ...

    @abc.abstractmethod

    def islocal(self) -> bool:

        ...

class IPath(Protocol):

    """Represents an individual path and its configuration."""

    name: bytes

    main_path: Optional[IPath]

    url: IUrl

    raw_url: IUrl

    branch: bytes

    rawloc: bytes

    loc: bytes

    @abc.abstractmethod

    def copy(self, new_raw_location: Optional[bytes] = None) -> IPath:

        ...

    @property

    @abc.abstractmethod

    def is_push_variant(self) -> bool:

        """is this a path variant to be used for pushing"""

    @abc.abstractmethod

    def get_push_variant(self) -> IPath:

        """get a "copy" of the path, but suitable for pushing

        This means using the value of the `pushurl` option (if any) as the url.

        The original path is available in the `main_path` attribute.

        """

    @property

    @abc.abstractmethod

    def suboptions(self) -> Dict[bytes, bytes]:

        """Return sub-options and their values for this path.

        This is intended to be used for presentation purposes.

        """