repopath 0.1.0__py3-none-any.whl

repopath/_kinds.py

@@ -0,0 +1,314 @@
+"""`RepoPath`, the family of repository trees on a hosting service, and the
+registry of the kinds that make it up."""
+
+from __future__ import annotations
+
+import inspect as _inspect
+import io as _io
+import re as _re
+import stat as _stat
+import threading as _threading
+import typing as _ty
+
+from pathapi import FileStat
+from pathapi.providers import TreePath
+
+if _ty.TYPE_CHECKING:
+    from ._backend import BaseRepoBackend
+
+_KINDS: "dict[str, type[RepoPath]]" = {}
+"""Kind name -> the class that registered it."""
+
+_DETECTED: "dict[str, type[RepoPath]]" = {}
+"""Instance (folded to lower case) -> the kind a call that names no `type`
+gets for it."""
+
+_LOCK = _threading.Lock()
+
+_NAME = _re.compile(r"[a-z][a-z0-9_-]*")
+
+
+class _Kinds(type(TreePath)):
+    """The metaclass that lets calling `RepoPath` itself return a path of one
+    of its kinds, chosen by `type=` or by the `instance=` it names."""
+
+    def __call__(cls, *args, **kwargs):
+        if cls is RepoPath:
+            kind = RepoPath._kind_for(
+                args, kwargs.pop("type", None), kwargs.get("instance")
+            )
+            return kind(*args, **kwargs)
+        return super().__call__(*args, **kwargs)
+
+    @property
+    def __signature__(cls) -> _inspect.Signature:
+        """What `inspect.signature()` reads: the constructor a call of the
+        class runs, not the `__call__` above."""
+        if cls is RepoPath:
+            parameter = _inspect.Parameter
+            return _inspect.Signature(
+                [
+                    parameter("segments", parameter.VAR_POSITIONAL),
+                    parameter("type", parameter.KEYWORD_ONLY, default=None),
+                    parameter("instance", parameter.KEYWORD_ONLY, default=None),
+                    parameter("options", parameter.VAR_KEYWORD),
+                ]
+            )
+        signature = _inspect.signature(cls.__init__)
+        return signature.replace(parameters=list(signature.parameters.values())[1:])
+
+
+def _same_definition(a: type, b: type) -> bool:
+    """Whether two classes come from one `class` statement run twice (a
+    reload, a function body called again): same module, same qualified name."""
+    return a.__module__ == b.__module__ and a.__qualname__ == b.__qualname__
+
+
+def _register(cls: type, name: object, instances: object, replace: bool) -> None:
+    if not isinstance(name, str) or not _NAME.fullmatch(name):
+        raise ValueError(
+            f"TYPE of {cls.__qualname__} must be a lower-case name "
+            f"(letters, digits, '_' and '-'), not {name!r}"
+        )
+    if isinstance(instances, str) or not all(isinstance(i, str) for i in instances):
+        raise TypeError(f"INSTANCES of {cls.__qualname__} must be a tuple of str")
+    folded = tuple(dict.fromkeys(i.lower() for i in instances))
+    with _LOCK:
+        held = _KINDS.get(name)
+        if held is not None and not (replace or _same_definition(held, cls)):
+            raise ValueError(
+                f"repository kind {name!r} is already registered by "
+                f"{held.__module__}.{held.__qualname__}; pass replace=True in "
+                f"the class statement of {cls.__qualname__} to replace it"
+            )
+        for instance in folded:
+            owner = _DETECTED.get(instance)
+            if (
+                owner is not None
+                and owner is not held
+                and not (replace or _same_definition(owner, cls))
+            ):
+                raise ValueError(
+                    f"instance {instance!r} is already detected as the "
+                    f"{owner.TYPE!r} kind; pass replace=True in the class "
+                    f"statement of {cls.__qualname__} to replace it"
+                )
+        if held is not None:
+            for instance in [k for k, v in _DETECTED.items() if v is held]:
+                del _DETECTED[instance]
+        _KINDS[name] = cls
+        for instance in folded:
+            _DETECTED[instance] = cls
+
+
+class RepoPath(TreePath, metaclass=_Kinds):
+    """A path in the repository tree of a hosting service, read-only, over the
+    service's REST API.
+
+    `RepoPath(*segments, instance=..., type=None, **options)` returns a path
+    of one *kind*: a `GitHubPath` or a `GitLabPath`. `type` names the kind
+    (`"github"`, `"gitlab"`); without it the kind is detected from `instance`
+    (`github.com` and `gitlab.com`), and any other instance is a `ValueError`
+    that asks for `type=`. The segments are the path inside the repository;
+    the options are those of the kind (`owner=`, `repo=`, `ref=`, `token=`,
+    `backend=`). Every kind is a subclass, so `isinstance(path, RepoPath)`
+    holds for all of them; `RepoPath.kinds()` lists the registered names.
+
+    A kind is a subclass whose class body sets `TYPE` (its name) and
+    `INSTANCES` (the instances it is detected for): defining the class
+    registers it. A name or an instance another class holds is a `ValueError`
+    unless the class statement passes `replace=True`.
+
+    A path holds the names below the root of the tree, the tree it is in (the
+    place) and the backend that reaches the service. Nothing connects when a
+    path is built. A path joined from another keeps its place and its
+    backend."""
+
+    __slots__ = ("_backend", "_place", "_hint")
+
+    #: The name of the kind, set in the class body of a kind.
+    TYPE: "str | None" = None
+    #: The instances (hosts) a call that names no `type` gets this kind for.
+    INSTANCES: "tuple[str, ...]" = ()
+
+    if _ty.TYPE_CHECKING:
+        _segments: "tuple[str, ...]"
+
+        def __init__(
+            self,
+            *segments: str | RepoPath,
+            type: str | None = None,
+            instance: str | None = None,
+            **options: _ty.Any,
+        ) -> None: ...
+
+    def __init_subclass__(cls, replace: bool = False, **kwargs):
+        super().__init_subclass__(**kwargs)
+        name = cls.__dict__.get("TYPE")
+        if name is not None:
+            _register(cls, name, cls.__dict__.get("INSTANCES", ()), replace)
+
+    @staticmethod
+    def kinds() -> "tuple[str, ...]":
+        """The names of the registered kinds, sorted."""
+        with _LOCK:
+            return tuple(sorted(_KINDS))
+
+    @staticmethod
+    def _kind_for(segments, name: object, instance: object) -> "type[RepoPath]":
+        """The kind a call to `RepoPath(...)` makes: the one `name` registers,
+        else the one `instance` is detected for, else the one of the first
+        segment that is a repository path."""
+        with _LOCK:
+            kinds = dict(_KINDS)
+            detected = dict(_DETECTED)
+        known = ", ".join(sorted(kinds)) or "none"
+        if name is not None:
+            if not isinstance(name, str):
+                raise TypeError(f"type= must be a str, not {type(name).__name__!r}")
+            try:
+                return kinds[name]
+            except KeyError:
+                raise ValueError(
+                    f"no repository kind {name!r}; the registered kinds are: {known}"
+                ) from None
+        if instance is not None:
+            if not isinstance(instance, str):
+                raise TypeError(
+                    f"instance= must be a str, not {type(instance).__name__!r}"
+                )
+            try:
+                return detected[instance.lower()]
+            except KeyError:
+                raise ValueError(
+                    f"cannot tell the kind of instance {instance!r}; pass type= "
+                    f"with one of: {known}"
+                ) from None
+        for segment in segments:
+            if isinstance(segment, RepoPath):
+                return segment._family()
+        raise TypeError(f"RepoPath needs type= or instance= (kinds: {known})")
+
+    @classmethod
+    def _family(cls) -> type:
+        """The kind `cls` is, or derives from: its instances can donate a
+        place and a backend to a join, and a path of another kind cannot."""
+        return next((c for c in cls.__mro__ if c.__dict__.get("TYPE")), RepoPath)
+
+    def _initialize(self, text: str, place: tuple, backend) -> None:
+        self._segments = self._parse(text)
+        self._place = place
+        self._backend = backend
+        self._hint = None
+
+    def _derived(self, segments: "tuple[str, ...]"):
+        """A path of this class, place and backend with the names `segments`."""
+        path = object.__new__(type(self))
+        path._segments = segments
+        path._place = self._place
+        path._backend = self._backend
+        path._hint = None
+        return path
+
+    def _rebuild(self, text: str):
+        return self._derived(self._parse(text))
+
+    def _keywords(self) -> dict:
+        """The constructor keywords that name the place of this path."""
+        raise NotImplementedError
+
+    def _place_key(self) -> tuple:
+        """What of the place `==`, `hash()` and ordering compare."""
+        return self._place
+
+    def _identity(self) -> tuple:
+        # Relative and rooted spellings name one node: the tree has no
+        # working directory.
+        return (self._place_key(), tuple(name for name in self._segments if name))
+
+    def __eq__(self, other: object):
+        if type(self) is not type(other):
+            return NotImplemented
+        return self._identity() == other._identity()
+
+    def __hash__(self) -> int:
+        return hash((type(self), self._identity()))
+
+    def _order_key(self):
+        return self._identity()
+
+    def __reduce__(self):
+        # The place and the names; a backend travels only when it says it can
+        # (its token is a credential), else the receiving process builds a
+        # backend of its own.
+        keywords = self._keywords()
+        if getattr(self._backend, "picklable", False) is True:
+            keywords["backend"] = self._backend
+        return _rebuild_path, (type(self), self._segments, keywords)
+
+    @property
+    def kind(self) -> str:
+        """The name of the kind of this path (`"github"`, `"gitlab"`)."""
+        return self._family().TYPE
+
+    @property
+    def backend(self) -> "BaseRepoBackend":
+        """The backend that sends the requests of this path."""
+        return self._backend
+
+    def is_local(self) -> bool:
+        """Whether the tree is on this machine: never. A repository is on a
+        hosting service, so nothing is resolved."""
+        return False
+
+    def _pop_stat_hint(self) -> "FileStat | None":
+        """The stat that the listing of the parent attached to this child,
+        once; the next call asks the service. A hint that knows the type and
+        not the size is consumed here and not returned: `stat()` has to give
+        a size."""
+        hint, self._hint = self._hint, None
+        if hint is not None and not hint.size_known:
+            return None
+        return hint
+
+    def _st_mode(self, *, follow_symlinks=True):
+        # The type questions are answered by a type-only hint, without a request.
+        hint = self._hint
+        if hint is not None and not hint.size_known:
+            self._hint = None
+            mode = hint.st_mode
+            if _stat.S_IFMT(mode):
+                return mode
+        return super()._st_mode(follow_symlinks=follow_symlinks)
+
+    def _make_child_relpath(self, name: str, stat_hint=None, **kwargs):
+        """The child called exactly `name`, with the stat its listing gave."""
+        segments = self._segments
+        names = ("", name) if segments == ("", "") else (*segments, name)
+        child = self._derived(names)
+        child._hint = stat_hint
+        return child
+
+    def iterdir(self):
+        for name, listed in self._scandir():
+            yield self._make_child_relpath(name, stat_hint=listed)
+
+    @staticmethod
+    def _check_read_mode(mode: str) -> None:
+        # `open()` hands `_open()` a canonical mode ("r", "r+", "w", ...);
+        # anything but plain "r" would write, and writes are unsupported.
+        if mode.replace("b", "").replace("t", "") != "r":
+            raise NotImplementedError(f"open(mode={mode!r}): a repository is read-only")
+
+    @staticmethod
+    def _reader(data: bytes) -> _ty.BinaryIO:
+        # Read-only like a local file opened "rb": a write raises
+        # io.UnsupportedOperation instead of landing in a detached buffer.
+        return _io.BufferedReader(_io.BytesIO(data))
+
+
+def _rebuild_path(cls, segments, keywords):
+    """Unpickles a path: `cls(**keywords)` with the names it had."""
+    path = cls(**keywords)
+    path._segments = segments
+    return path

repopath/_version.py

@@ -0,0 +1,11 @@
+"""The version of the installed distribution."""
+
+from __future__ import annotations
+
+from importlib import metadata as _metadata
+
+try:
+    __version__ = _metadata.version("repopath")
+except _metadata.PackageNotFoundError:
+    # Run from a source tree that was never installed.
+    __version__ = "0+unknown"

repopath/exceptions.py

@@ -0,0 +1,43 @@
+"""The exceptions and the warning `repopath` defines.
+
+A failure of a hosting service or of the connection to it is the `OSError` type
+that `pathlib` raises for the same condition (`FileNotFoundError`,
+`PermissionError`, `TimeoutError`, `ConnectionError`, ...); this module holds
+the two that name a cause no builtin does. An exception of the HTTP transport is
+never raised across the API. A bad argument is a plain `ValueError` or
+`TypeError`.
+"""
+
+from __future__ import annotations
+
+from pathapi import PathError
+
+__all__ = [
+    "BadReplyError",
+    "InsecureTransportWarning",
+    "RateLimitError",
+    "RepoPathError",
+]
+
+
+class RepoPathError(PathError):
+    """Base class of the exceptions `repopath` defines for a failure at run
+    time that no builtin describes."""
+
+
+class RateLimitError(RepoPathError, BlockingIOError):
+    """The service refused a request because the caller used up its rate limit
+    (errno `EAGAIN`): HTTP 403 or 429 with a `RateLimit-Remaining: 0` or a
+    `Retry-After` header. The message says when to try again."""
+
+
+class BadReplyError(RepoPathError, OSError):
+    """The service answered with something that is not the shape its API
+    documents (errno `EIO`): a page of a proxy or a captive portal, a gateway's
+    JSON, `null`, a truncated body, a size that is not a number."""
+
+
+class InsecureTransportWarning(UserWarning):
+    """A `RepoBackend` is about to send an `Authorization` header (its token,
+    or one given in `headers=`) over plain `http://` to a host that is not
+    this machine, where anyone on the route can read it."""

repopath/uri.py

@@ -0,0 +1,253 @@
+"""The `repo:`, `github:` and `gitlab:` schemes of `uripath`: `RepoURIPath`,
+`GitHubURIPath` and `GitLabURIPath`, URI paths that delegate to a `GitHubPath`
+or a `GitLabPath`.
+
+Importing this module needs `uripath`: `pip install "repopath[uri]"`. `uripath`
+loads it by itself, through the `uripath.schemes` entry points, the first time
+a path of one of the schemes is used.
+"""
+
+from __future__ import annotations
+
+try:
+    import uripath as _uripath  # noqa: F401
+except ImportError as _error:
+    raise ImportError(
+        'repopath.uri needs the uripath distribution: pip install "repopath[uri]"',
+        name="uripath",
+    ) from _error
+
+import contextlib as _contextlib
+import errno as _errno
+import typing as _ty
+
+from uripath import Source
+from uripath.exceptions import URISyntaxError
+from uripath.schemes import DelegatingURIPath
+from uripath.source import compose_host, fold_host
+
+from ._backend import RepoBackend
+from ._github import GitHubPath
+from ._gitlab import GitLabPath
+from ._hosted import HostedRepoPath
+from ._kinds import RepoPath
+
+__all__ = ["GitHubURIPath", "GitLabURIPath", "RepoURIPath"]
+
+
+class RepoURIPath(DelegatingURIPath):
+    """`repo:` scheme (`repo://instance/owner/repo/path?ref=REF`): read-only
+    access to a repository on a hosting service, done by the path of its kind
+    (a `GitHubPath` or a `GitLabPath`) on the backend of this path. The kind is
+    detected from the host: `github.com` and `gitlab.com` (and `www.`); any
+    other host is a `ValueError` that names `github://host/...` and
+    `gitlab://host/...`, which pin the kind on any host. `ref` (branch, tag or
+    commit) is optional and carried in the `?ref=` query; without one the
+    service's default branch is read.
+
+    Auth: a bearer token given as the user slot of the URI,
+    `repo://TOKEN@host/...`, or as its password slot,
+    `repo://x-access-token:TOKEN@host/...` (the `oauth2:TOKEN` of GitLab
+    too); the `backend` keyword wins if both are given. Because the user slot
+    can be the secret, `str()`, `repr()`, `as_posix()` and `as_uri(sanitize=True)`,
+    and so every message of an exception, drop the WHOLE userinfo for these
+    schemes; `as_uri()` still round-trips it. The tree is read-only."""
+
+    __SCHEMES = ("repo",)
+    __slots__ = ()
+    _DELEGATED = ("_scandir", "_listdir", "_open")
+
+    #: The kind this class pins, or None to detect it from the host.
+    _KIND: "type[HostedRepoPath] | None" = None
+
+    if _ty.TYPE_CHECKING:
+        backend: RepoBackend
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        # Settles the parts, so a host that no kind is detected for is refused
+        # when the path is built and not at its first request.
+        self.source
+
+    def _init(self, source: Source, path, query, fragment, /, **kwargs):
+        self._kind_of(source, path, query, fragment)
+        super()._init(source, path, query, fragment, **kwargs)
+
+    @classmethod
+    def _kind_of(
+        cls, source: Source, path: str = "", query="", fragment=""
+    ) -> "type[HostedRepoPath]":
+        """The kind of path that serves a URI at `source`: the one this class
+        pins, else the one its host is detected for."""
+        if cls._KIND is not None:
+            return cls._KIND
+        host = str(source.host or "").lower()
+        try:
+            kind = RepoPath._kind_for((), None, host or None)
+        except (TypeError, ValueError):
+            kind = None
+        if kind is None or not issubclass(kind, HostedRepoPath):
+            # Redacted like the paths: the userinfo can be a bare token.
+            shown = cls._format_parsed_parts(
+                source, path, query, fragment, sanitize=True
+            )
+            raise URISyntaxError(
+                f"repo: can only auto-detect github.com and gitlab.com; "
+                f"use github: or gitlab: for {shown!r}"
+            )
+        return kind
+
+    def as_posix(self) -> str:
+        # `user@host:path` would show the token when it is the user slot.
+        host = self.source.host
+        return f"{host}:{self.path}" if host else self.path
+
+    def _initbackend(self):
+        user, password = self.source.parsed_userinfo()
+        return RepoBackend(token=password or user or None)
+
+    def is_local(self) -> bool:
+        """Whether the tree is on this machine: never. The host of the URI is
+        a hosting service and is not resolved."""
+        return False
+
+    @property
+    def kind(self) -> str:
+        """The name of the kind of repository this path reads (`"github"`,
+        `"gitlab"`)."""
+        return self._kind_of(self.source).TYPE
+
+    @property
+    def instance(self) -> str:
+        """The host (and port) of the service, in the case a URL spells it."""
+        text = self._instance()
+        return text or self._kind_of(self.source).DEFAULT_INSTANCE
+
+    def _instance(self) -> "str | None":
+        """`host[:port]` of the URI with an IPv6 literal bracketed, or None
+        when the URI names no host (the kind's default instance then)."""
+        source = self.source
+        if not source.host:
+            return None
+        text = compose_host(fold_host(source.host))
+        return f"{text}:{source.port}" if source.port else text
+
+    def _split(self) -> "tuple[str, str, list[str]]":
+        """`(owner, repo, names)` of the path of this URI, the kind's way:
+        `("", "", [])` and the like when it has fewer parts than a
+        repository."""
+        parts = [part for part in self.segments if part]
+        split = self._kind_of(self.source)._from_uri_segments(parts)
+        if split is not None:
+            return split
+        return (parts[0] if parts else ""), "", []
+
+    @property
+    def repo_owner(self) -> str:
+        """The owner of the repository: the first segment (the group path of a
+        GitLab project in a subgroup, ended by `/-/`)."""
+        return self._split()[0]
+
+    @property
+    def repo(self) -> str:
+        """The name of the repository."""
+        return self._split()[1]
+
+    @property
+    def repo_path(self) -> str:
+        """The path inside the repository, with no leading or trailing `/`."""
+        return "/".join(self._split()[2])
+
+    @property
+    def ref(self) -> "str | None":
+        """The branch, tag or commit of the `?ref=` query, or None."""
+        return self.query.to_dict(single=True).get("ref") or None
+
+    def _make_core(self) -> HostedRepoPath:
+        kind = self._kind_of(self.source)
+        owner, repo, names = self._split()
+        if not (owner and repo):
+            raise FileNotFoundError(
+                _errno.ENOENT,
+                f"a {self.source.scheme}: path needs an owner and a repository",
+                str(self),
+            )
+        return kind(
+            *names,
+            owner=owner,
+            repo=repo,
+            ref=self.ref,
+            instance=self._instance(),
+            backend=self.backend,
+        )
+
+    @_contextlib.contextmanager
+    def _delegated(self, *extra: "tuple[str, str]"):
+        # The core path names itself by its own scheme (`github:` for a path
+        # of `repo:`), and in the middle of a message as well as alone: the
+        # name of this path replaces it wherever it is.
+        try:
+            with super()._delegated(*extra):
+                yield
+        except OSError as error:
+            core_path = self._core
+            if core_path is not None and str(core_path) != str(self):
+                core, mine = str(core_path), str(self)
+                error.args = tuple(
+                    arg.replace(core, mine) if isinstance(arg, str) else arg
+                    for arg in error.args
+                )
+                # `str(OSError)` reads these, not `args`.
+                for attribute in ("strerror", "filename", "filename2"):
+                    value = getattr(error, attribute)
+                    if isinstance(value, str) and core in value:
+                        setattr(error, attribute, value.replace(core, mine))
+            raise
+
+
+class GitHubURIPath(RepoURIPath):
+    """`github:` scheme (`github://[TOKEN@]host/owner/repo/path?ref=REF`):
+    read-only access to a GitHub repository tree via the REST contents API,
+    done by a `GitHubPath`. `host` defaults to `github.com` (API at
+    `api.github.com`); any other host is GitHub Enterprise (API at
+    `https://{host}/api/v3`). The kind is fixed whatever the host. See
+    `RepoURIPath` for the token and the ref."""
+
+    __SCHEMES = ("github",)
+    __slots__ = ()
+    _KIND = GitHubPath
+
+
+class GitLabURIPath(RepoURIPath):
+    """`gitlab:` scheme (`gitlab://[TOKEN@]host[:port]/owner/repo/path?ref=REF`):
+    read-only access to a GitLab project's repository tree via the REST API
+    v4, done by a `GitLabPath`. A project in a subgroup is addressed with
+    GitLab's own `/-/` separator, as in its web URLs:
+    `gitlab://host/group/subgroup/project/-/path/in/repo`; without the
+    separator the first two segments are owner and repository. `host` defaults
+    to `gitlab.com`; a self-hosted instance is just a different host (and
+    port), always at `https://{host}/api/v4`. See `RepoURIPath` for the token
+    and the ref."""
+
+    __SCHEMES = ("gitlab",)
+    __slots__ = ()
+    _KIND = GitLabPath
+
+    def _separator_index(self) -> "int | None":
+        # GitLab's `/-/` ends the project path; it needs at least
+        # `owner/repo` in front of it.
+        try:
+            return self.segments.index("-", 3)
+        except ValueError:
+            return None
+
+    def _make_child_relpath(self, name: str, **kwargs):
+        parent = self
+        if name == "-" and self._separator_index() is None and len(self.segments) > 2:
+            # A directory literally named "-" would read as the separator:
+            # spell the parent with `/-/` so the child stays that directory.
+            segments = self.segments[:3] + ("-",) + self.segments[3:]
+            parent = self._from_parsed_parts(
+                self.source, "/".join(segments), self.query, self.fragment
+            )
+        return super(GitLabURIPath, parent)._make_child_relpath(name, **kwargs)