idems-gitstore 0.1.0__py3-none-any.whl

gitstore/__init__.py

@@ -0,0 +1,91 @@
+"""gitstore: git as the store.
+
+Branches are units of work, pull requests are results, and history is the record.
+See docs/design.md.
+
+The operations live in their modules (`gitstore.git.clone`, `gitstore.refs.resolve_chain`,
+...); the names exported here are the types callers construct or catch.
+"""
+
+from gitstore.git import Backoff, Git, GitError, Identity
+from gitstore.guards import (
+    DefaultBranchError,
+    DestructiveChangeError,
+    Person,
+    Problem,
+    Problems,
+)
+from gitstore.lease import (
+    GitRefLeaseStore,
+    Heartbeat,
+    Lease,
+    LeaseError,
+    LeaseHeldError,
+    LeaseLostError,
+    LeaseStore,
+    LeaseUnavailableError,
+    MemoryLeaseStore,
+)
+from gitstore.provenance import Entry, Provenance, ProvenanceError
+from gitstore.provider import GitProvider, ProviderError, ProviderResolver
+from gitstore.refs import (
+    ChainCycleError,
+    ChainError,
+    ChainTooDeepError,
+    RepoRef,
+    ResolvedRef,
+    UnpinnedParentError,
+)
+from gitstore.run import Run, RunError
+from gitstore.work import (
+    OpenUnit,
+    UnitExistsError,
+    UnitNotFoundError,
+    WorkError,
+    Workspace,
+    WorkUnit,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Backoff",
+    "ChainCycleError",
+    "ChainError",
+    "ChainTooDeepError",
+    "DefaultBranchError",
+    "DestructiveChangeError",
+    "Entry",
+    "Git",
+    "GitError",
+    "GitProvider",
+    "GitRefLeaseStore",
+    "Heartbeat",
+    "Identity",
+    "Lease",
+    "LeaseError",
+    "LeaseHeldError",
+    "LeaseLostError",
+    "LeaseStore",
+    "LeaseUnavailableError",
+    "MemoryLeaseStore",
+    "OpenUnit",
+    "Person",
+    "Problem",
+    "Problems",
+    "Provenance",
+    "ProvenanceError",
+    "ProviderError",
+    "ProviderResolver",
+    "RepoRef",
+    "ResolvedRef",
+    "Run",
+    "RunError",
+    "UnitExistsError",
+    "UnitNotFoundError",
+    "UnpinnedParentError",
+    "WorkError",
+    "WorkUnit",
+    "Workspace",
+    "__version__",
+]

gitstore/aio.py

@@ -0,0 +1,317 @@
+"""Async wrappers over gitstore's synchronous core (decision #1).
+
+Each wrapper runs the synchronous call in a worker thread with ``asyncio.to_thread`` and
+adds nothing else: same arguments, same results, same exceptions. The logic stays in one
+place, and an async caller holds a thread for the length of one call. Callbacks, such as
+``resolve_chain``'s ``parent_of``, run in that thread too. ``retry_rejected_push`` is the
+exception: it takes a coroutine function, because the attempt it re-runs is the caller's own.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+from collections.abc import Awaitable, Callable, Sequence
+from datetime import timedelta
+from pathlib import Path
+from typing import TYPE_CHECKING, ParamSpec, TypeVar
+
+from gitstore import git, guards
+from gitstore import run as run_module
+from gitstore.lease import DEFAULT_TTL, Lease, LeaseStore
+from gitstore.provider.base import (
+    Capability,
+    GitProvider,
+    MergeMethod,
+    PullRequest,
+)
+
+if TYPE_CHECKING:
+    from gitstore.provenance import Actor
+    from gitstore.refs import ResolvedRef
+    from gitstore.run import Run
+    from gitstore.work import OpenUnit, Workspace, WorkUnit
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+# ─── Provider ───────────────────────────────────────────────────────────────────────────────
+
+
+class AsyncProvider:
+    """A ``GitProvider`` for async callers. ``sync`` is the provider it wraps.
+
+    ``kind`` and ``capabilities()`` are plain attributes of a provider already in hand, so
+    they stay synchronous. The draft operations exist whatever the wrapped provider
+    advertises; check ``capabilities()`` first, exactly as with the synchronous provider.
+    """
+
+    def __init__(self, sync: GitProvider) -> None:
+        self.sync = sync
+
+    @property
+    def kind(self) -> str:
+        return self.sync.kind
+
+    def capabilities(self) -> frozenset[Capability]:
+        return self.sync.capabilities()
+
+    async def get_pull_request(self, repo: str, number: int) -> PullRequest:
+        return await asyncio.to_thread(self.sync.get_pull_request, repo, number)
+
+    async def list_open_pull_requests(
+        self, repo: str, *, head_prefix: str = "", limit: int | None = None
+    ) -> list[PullRequest]:
+        return await asyncio.to_thread(
+            self.sync.list_open_pull_requests, repo, head_prefix=head_prefix, limit=limit
+        )
+
+    async def open_pull_request(
+        self, repo: str, *, head: str, base: str, title: str, body: str
+    ) -> PullRequest:
+        return await asyncio.to_thread(
+            self.sync.open_pull_request, repo, head=head, base=base, title=title, body=body
+        )
+
+    async def update_pull_request(
+        self,
+        repo: str,
+        number: int,
+        *,
+        title: str | None = None,
+        body: str | None = None,
+        base: str | None = None,
+    ) -> PullRequest:
+        return await asyncio.to_thread(
+            self.sync.update_pull_request, repo, number, title=title, body=body, base=base
+        )
+
+    async def close_pull_request(
+        self, repo: str, number: int, *, comment: str | None = None
+    ) -> PullRequest:
+        return await asyncio.to_thread(self.sync.close_pull_request, repo, number, comment=comment)
+
+    async def merge_pull_request(
+        self,
+        repo: str,
+        number: int,
+        *,
+        method: MergeMethod = "merge",
+        message: str | None = None,
+        expected_head: str | None = None,
+    ) -> PullRequest:
+        return await asyncio.to_thread(
+            self.sync.merge_pull_request,
+            repo,
+            number,
+            method=method,
+            message=message,
+            expected_head=expected_head,
+        )
+
+    async def open_draft_pull_request(
+        self, repo: str, *, head: str, base: str, title: str, body: str
+    ) -> PullRequest:
+        return await asyncio.to_thread(
+            self.sync.open_draft_pull_request,  # type: ignore[attr-defined]
+            repo,
+            head=head,
+            base=base,
+            title=title,
+            body=body,
+        )
+
+    async def mark_ready(self, repo: str, number: int) -> PullRequest:
+        return await asyncio.to_thread(self.sync.mark_ready, repo, number)  # type: ignore[attr-defined]
+
+    async def comment(self, repo: str, number: int, body: str) -> None:
+        await asyncio.to_thread(self.sync.comment, repo, number, body)
+
+    async def set_labels(self, repo: str, number: int, labels: Sequence[str]) -> tuple[str, ...]:
+        return await asyncio.to_thread(self.sync.set_labels, repo, number, labels)
+
+
+# ─── Git ────────────────────────────────────────────────────────────────────────────────────
+
+
+def _threaded(fn: Callable[P, T]) -> Callable[P, Awaitable[T]]:
+    @functools.wraps(fn)
+    async def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+        return await asyncio.to_thread(fn, *args, **kwargs)
+
+    return wrapper
+
+
+clone = _threaded(git.clone)
+fetch = _threaded(git.fetch)
+rev_parse = _threaded(git.rev_parse)
+head = _threaded(git.head)
+commit_exists = _threaded(git.commit_exists)
+merge_base = _threaded(git.merge_base)
+ls_remote = _threaded(git.ls_remote)
+worktree_list = _threaded(git.worktree_list)
+worktree_add = _threaded(git.worktree_add)
+worktree_remove = _threaded(git.worktree_remove)
+worktree_prune = _threaded(git.worktree_prune)
+commit = _threaded(git.commit)
+push = _threaded(git.push)
+resolve_ref = _threaded(git.resolve_ref)
+read_at = _threaded(git.read_at)
+resolve_chain = _threaded(git.resolve_chain)
+
+
+async def retry_rejected_push(attempt: Callable[[], Awaitable[T]]) -> T:
+    """As ``gitstore.git.retry_rejected_push``, for an attempt that is a coroutine function."""
+    try:
+        return await attempt()
+    except git.GitError as exc:
+        if not exc.rejected_push:
+            raise
+    return await attempt()
+
+
+# ─── Leases and work units ──────────────────────────────────────────────────────────────────
+
+
+class AsyncLeaseStore:
+    """A ``LeaseStore`` for async callers. ``sync`` is the store it wraps."""
+
+    def __init__(self, sync: LeaseStore) -> None:
+        self.sync = sync
+
+    async def holder(self, unit: str) -> Lease | None:
+        return await asyncio.to_thread(self.sync.holder, unit)
+
+    async def acquire(self, unit: str, holder: str, *, ttl: timedelta = DEFAULT_TTL) -> Lease:
+        return await asyncio.to_thread(self.sync.acquire, unit, holder, ttl=ttl)
+
+    async def renew(self, lease: Lease, *, ttl: timedelta = DEFAULT_TTL) -> Lease:
+        return await asyncio.to_thread(self.sync.renew, lease, ttl=ttl)
+
+    async def release(self, lease: Lease) -> None:
+        await asyncio.to_thread(self.sync.release, lease)
+
+
+class AsyncWorkspace:
+    """A ``Workspace`` for async callers. ``sync`` is the workspace it wraps.
+
+    ``heartbeat`` stays synchronous: it builds a ``Heartbeat``, which renews on a thread
+    of its own and whose ``check()`` does no I/O.
+    """
+
+    def __init__(self, sync: Workspace) -> None:
+        self.sync = sync
+
+    def heartbeat(self, unit: WorkUnit, **kwargs):
+        return self.sync.heartbeat(unit, **kwargs)
+
+    async def create(self, name: str, *, base: str | None = None, lease: bool = True) -> WorkUnit:
+        return await asyncio.to_thread(self.sync.create, name, base=base, lease=lease)
+
+    async def publish(
+        self, unit: WorkUnit, *, title: str, body: str, draft: bool = True
+    ) -> WorkUnit:
+        return await asyncio.to_thread(self.sync.publish, unit, title=title, body=body, draft=draft)
+
+    async def discover(self, *, limit: int | None = None) -> list[OpenUnit]:
+        return await asyncio.to_thread(self.sync.discover, limit=limit)
+
+    async def resume(self, name: str, *, lease: bool = True) -> WorkUnit:
+        return await asyncio.to_thread(self.sync.resume, name, lease=lease)
+
+    async def release(self, unit: WorkUnit) -> None:
+        await asyncio.to_thread(self.sync.release, unit)
+
+    async def prune(self) -> list[Path]:
+        return await asyncio.to_thread(self.sync.prune)
+
+    async def abandon(self, unit: WorkUnit, *, comment: str | None = None) -> None:
+        await asyncio.to_thread(self.sync.abandon, unit, comment=comment)
+
+
+# ─── Runs and guards ────────────────────────────────────────────────────────────────────────
+
+check_deletions = _threaded(guards.check_deletions)
+staged_deletions = _threaded(guards.staged_deletions)
+
+
+class AsyncRun:
+    """A ``Run`` for async callers. ``sync`` is the run it wraps.
+
+    Its state (``pull_request``, ``problems``, ``status``, the commits) is read from
+    ``sync``. As a context manager, a run that raises before it finishes fails itself and
+    re-raises, as the synchronous one does.
+    """
+
+    def __init__(self, sync: Run) -> None:
+        self.sync = sync
+
+    async def write(
+        self,
+        path: str,
+        content: str | bytes,
+        *,
+        actor: Actor,
+        producer: str,
+        sources: Sequence[ResolvedRef] = (),
+        edit: bool = False,
+        note: str | None = None,
+    ) -> Path:
+        return await asyncio.to_thread(
+            self.sync.write,
+            path,
+            content,
+            actor=actor,
+            producer=producer,
+            sources=sources,
+            edit=edit,
+            note=note,
+        )
+
+    async def record(
+        self,
+        path: str,
+        *,
+        actor: Actor,
+        producer: str,
+        sources: Sequence[ResolvedRef] = (),
+        edit: bool = False,
+        note: str | None = None,
+    ) -> None:
+        await asyncio.to_thread(
+            self.sync.record,
+            path,
+            actor=actor,
+            producer=producer,
+            sources=sources,
+            edit=edit,
+            note=note,
+        )
+
+    async def remove(self, path: str) -> None:
+        await asyncio.to_thread(self.sync.remove, path)
+
+    async def commit_state(self, subject: str, body: str | None = None, **kwargs) -> str:
+        return await asyncio.to_thread(self.sync.commit_state, subject, body, **kwargs)
+
+    async def succeed(self, subject: str, body: str | None = None, **kwargs) -> str | None:
+        return await asyncio.to_thread(self.sync.succeed, subject, body, **kwargs)
+
+    async def fail(self, reason: str) -> None:
+        await asyncio.to_thread(self.sync.fail, reason)
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await asyncio.to_thread(self.sync.__exit__, exc_type, exc, tb)
+
+
+async def start_run(workspace: Workspace, **kwargs) -> AsyncRun:
+    """As ``gitstore.run.start_run``, with the same keyword arguments."""
+    return AsyncRun(await asyncio.to_thread(run_module.start_run, workspace, **kwargs))
+
+
+async def resume_run(workspace: Workspace, run_id: str, **kwargs) -> AsyncRun:
+    """As ``gitstore.run.resume_run``, with the same keyword arguments."""
+    return AsyncRun(await asyncio.to_thread(run_module.resume_run, workspace, run_id, **kwargs))