gitd-client 0.14.0__py3-none-any.whl

gitd/models.py

@@ -0,0 +1,369 @@
+"""What gitd answers, as plain dataclasses, each built from the message gitd sends. The
+messages are made from the contract at run time, so their fields are typed here as Any."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+from . import messages
+from .publishing_settings import OpenedPullRequest, Provenance
+from .timestamps import Timestamp
+
+STRATEGY_PREFIX = "STRATEGY_"
+ACTION_PREFIX = "ACTION_"
+ACCESS_PREFIX = "ACCESS_"
+REASON_PREFIX = "REASON_"
+
+
+class Strategy(StrEnum):
+    """How a workspace is made: a layer on a shared template, a block clone, or every file written."""
+
+    OVERLAY = "overlay"
+    REFLINK = "reflink"
+    COPY = "copy"
+
+    @classmethod
+    def from_message(cls, number: int) -> Strategy:
+        name = messages.STRATEGY.name(number).removeprefix(STRATEGY_PREFIX).lower()
+        return cls(name) if name in {member.value for member in cls} else cls.COPY
+
+    @classmethod
+    def preference(cls, strategy: Strategy | None) -> int:
+        """The number a request carries: the strategy asked for, or none, for gitd to choose."""
+        name = strategy.value.upper() if strategy else "UNSPECIFIED"
+        return messages.STRATEGY.number(STRATEGY_PREFIX + name)
+
+
+class Access(StrEnum):
+    """Whether a repository can be read: by anyone, with a credential gitd keeps, or not at all."""
+
+    PUBLIC = "public"
+    REACHABLE = "reachable"
+    DENIED = "denied"
+
+    @classmethod
+    def from_message(cls, number: int) -> Access:
+        name = messages.ACCESS.name(number).removeprefix(ACCESS_PREFIX).lower()
+        return cls(name) if name in {member.value for member in cls} else cls.DENIED
+
+
+@dataclass(frozen=True)
+class Progress:
+    """How far a fetch or checkout has gone; repository is the submodule's URL, empty for the
+    workspace's own repository."""
+
+    phase: str
+    percent: int
+    repository: str
+
+    @classmethod
+    def from_message(cls, progress: Any) -> Progress:
+        return cls(phase=progress.phase, percent=progress.percent, repository=progress.repository)
+
+
+@dataclass(frozen=True)
+class Layers:
+    """An overlay workspace's template (lower), its own layer (upper, work), and the warm
+    layer between them, when it stands on one."""
+
+    lower: str
+    upper: str
+    work: str
+    warm: str = ""
+
+    @classmethod
+    def from_message(cls, layers: Any) -> Layers:
+        return cls(lower=layers.lower, upper=layers.upper, work=layers.work, warm=layers.warm)
+
+
+@dataclass(frozen=True)
+class PendingSubmodule:
+    """A submodule that could not be checked out, and what git said."""
+
+    path: str
+    url: str
+    reason: str
+
+    @classmethod
+    def from_message(cls, submodule: Any) -> PendingSubmodule:
+        return cls(path=submodule.path, url=submodule.url, reason=submodule.failure.git_said)
+
+
+@dataclass(frozen=True)
+class Workspace:
+    """Where a workspace ended up. branch is empty when it is detached at a commit;
+    lfs_patterns are the files the repository keeps in git LFS, which are pointers here, as
+    gitd does not download them."""
+
+    path: str
+    commit: str
+    branch: str
+    strategy: Strategy
+    layers: Layers | None = None
+    pending_submodules: list[PendingSubmodule] = field(default_factory=list)
+    lfs_patterns: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_message(cls, path: str, result: Any) -> Workspace:
+        return cls(
+            path=path,
+            commit=result.commit,
+            branch=result.branch,
+            strategy=Strategy.from_message(result.strategy),
+            layers=Layers.from_message(result.layers) if result.HasField("layers") else None,
+            pending_submodules=[
+                PendingSubmodule.from_message(pending) for pending in result.pending_submodules
+            ],
+            lfs_patterns=list(result.lfs_patterns),
+        )
+
+
+@dataclass(frozen=True)
+class Submodule:
+    path: str
+    url: str
+    commit: str
+    checked_out: bool
+
+    @classmethod
+    def from_message(cls, submodule: Any) -> Submodule:
+        return cls(
+            path=submodule.path,
+            url=submodule.url,
+            commit=submodule.commit,
+            checked_out=submodule.checked_out,
+        )
+
+
+@dataclass(frozen=True)
+class Description:
+    """What a workspace is on disk. modified says whether it has uncommitted changes;
+    lfs_patterns are the files kept in git LFS, which are pointers here."""
+
+    url: str
+    commit: str
+    branch: str
+    modified: bool
+    strategy: Strategy
+    submodules: list[Submodule] = field(default_factory=list)
+    lfs_patterns: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_message(cls, response: Any) -> Description:
+        return cls(
+            url=response.url,
+            commit=response.commit,
+            branch=response.branch,
+            modified=response.modified,
+            strategy=Strategy.from_message(response.strategy),
+            submodules=[Submodule.from_message(submodule) for submodule in response.submodules],
+            lfs_patterns=list(response.lfs_patterns),
+        )
+
+
+@dataclass(frozen=True)
+class PublishedRepository:
+    """A repository a publish pushed. path is the submodule's, empty for the workspace's own
+    repository; subjects are the new commits' subjects, newest first."""
+
+    url: str
+    path: str
+    commit: str
+    subjects: list[str]
+
+    @classmethod
+    def from_message(cls, repository: Any) -> PublishedRepository:
+        return cls(
+            url=repository.url,
+            path=repository.path,
+            commit=repository.commit,
+            subjects=list(repository.subjects),
+        )
+
+
+@dataclass(frozen=True)
+class Refusal:
+    """Why gitd refused a call: its reason (BRANCH_REFUSED, AUTH_REQUIRED, …) and what git said."""
+
+    reason: str
+    said: str
+
+    @classmethod
+    def from_message(cls, failure: Any) -> Refusal:
+        return cls(reason=cls.reason_of(failure), said=failure.git_said)
+
+    @staticmethod
+    def reason_of(failure: Any) -> str:
+        return messages.REASON.name(failure.reason).removeprefix(REASON_PREFIX)
+
+
+@dataclass(frozen=True)
+class SubmodulePullRequest:
+    """The pull request of one submodule, at path in the workspace and of the repository at
+    url, or why it could not be opened."""
+
+    path: str
+    url: str
+    pull_request: OpenedPullRequest | None = None
+    refused: Refusal | None = None
+
+    @classmethod
+    def from_message(cls, submodule: Any) -> SubmodulePullRequest:
+        return cls(
+            path=submodule.path,
+            url=submodule.url,
+            pull_request=(
+                OpenedPullRequest.from_message(submodule.pull_request)
+                if submodule.HasField("pull_request")
+                else None
+            ),
+            refused=Refusal.from_message(submodule.failure) if submodule.HasField("failure") else None,
+        )
+
+
+@dataclass(frozen=True)
+class Published:
+    """What a publish pushed: the workspace's repository first, then each submodule; the
+    pull request it opened or updated, or why it could not, the branch being published
+    either way; and each submodule's, when asked for. An update that brought nothing new
+    lists the workspace's repository with no subjects."""
+
+    branch: str
+    repositories: list[PublishedRepository]
+    pull_request: OpenedPullRequest | None = None
+    pull_request_refused: Refusal | None = None
+    submodule_pull_requests: list[SubmodulePullRequest] = field(default_factory=list)
+
+    @classmethod
+    def from_message(cls, response: Any) -> Published:
+        pushed = [response.repository, *response.submodules] if response.HasField("repository") else []
+        return cls(
+            branch=response.branch,
+            repositories=[PublishedRepository.from_message(repository) for repository in pushed],
+            pull_request=(
+                OpenedPullRequest.from_message(response.pull_request)
+                if response.HasField("pull_request")
+                else None
+            ),
+            pull_request_refused=(
+                Refusal.from_message(response.pull_request_failure)
+                if response.HasField("pull_request_failure")
+                else None
+            ),
+            submodule_pull_requests=[
+                SubmodulePullRequest.from_message(submodule) for submodule in response.submodule_pull_requests
+            ],
+        )
+
+
+@dataclass(frozen=True)
+class Info:
+    """Which gitd answers, and how it makes workspaces on its machine and why."""
+
+    version: str
+    git_version: str
+    pools: int
+    pools_bytes: int
+    templates: int
+    templates_bytes: int
+    strategy: Strategy
+    strategy_reason: str
+
+    @classmethod
+    def from_message(cls, response: Any) -> Info:
+        return cls(
+            version=response.version,
+            git_version=response.git_version,
+            pools=response.pools,
+            pools_bytes=response.pools_bytes,
+            templates=response.templates,
+            templates_bytes=response.templates_bytes,
+            strategy=Strategy.from_message(response.strategy),
+            strategy_reason=response.strategy_reason,
+        )
+
+
+@dataclass(frozen=True)
+class Probe:
+    """Whether a repository can be read, its default branch, and each branch's commit.
+    denied says why it cannot be read, when it cannot."""
+
+    access: Access
+    default_branch: str
+    branches: dict[str, str]
+    denied: str | None = None
+
+    @classmethod
+    def from_message(cls, response: Any) -> Probe:
+        return cls(
+            access=Access.from_message(response.access),
+            default_branch=response.default_branch,
+            branches=dict(response.commits),
+            denied=response.failure.git_said if response.HasField("failure") else None,
+        )
+
+
+@dataclass(frozen=True)
+class ConfigurationChange:
+    """A change to the credentials or publishing settings: connection_added,
+    connection_removed, settings_set or settings_removed; subject is the credential's id or
+    the settings' prefix."""
+
+    action: str
+    subject: str
+    url_prefix: str
+
+    @classmethod
+    def from_message(cls, change: Any) -> ConfigurationChange:
+        action = messages.CHANGE_ACTION.name(change.action).removeprefix(ACTION_PREFIX).lower()
+        return cls(action=action, subject=change.subject, url_prefix=change.url_prefix)
+
+
+@dataclass(frozen=True)
+class AuditEntry:
+    """One publish, done or refused, or one change to credentials or settings, as the audit
+    log keeps it. url is the workspace's repository, empty when the workspace could not be
+    opened; repositories is what was pushed, the workspace's repository first, empty when
+    refused; requested_by and the pull request are as the publish said and did."""
+
+    time: datetime
+    workspace: str
+    url: str
+    branch: str
+    repositories: list[PublishedRepository] = field(default_factory=list)
+    refused: Refusal | None = None
+    requested_by: str = ""
+    pull_request: OpenedPullRequest | None = None
+    pull_request_refused: Refusal | None = None
+    change: ConfigurationChange | None = None
+    provenance: Provenance | None = None
+    submodule_pull_requests: list[SubmodulePullRequest] = field(default_factory=list)
+
+    @classmethod
+    def from_message(cls, entry: Any) -> AuditEntry:
+        pushed = [entry.repository, *entry.submodules] if entry.HasField("repository") else []
+        return cls(
+            time=Timestamp.to_datetime(entry.time),
+            workspace=entry.workspace,
+            url=entry.url,
+            branch=entry.branch,
+            repositories=[PublishedRepository.from_message(repository) for repository in pushed],
+            refused=Refusal.from_message(entry.refusal) if entry.HasField("refusal") else None,
+            requested_by=entry.requested_by,
+            pull_request=OpenedPullRequest.from_message(entry.pull_request)
+            if entry.HasField("pull_request")
+            else None,
+            pull_request_refused=(
+                Refusal.from_message(entry.pull_request_failure)
+                if entry.HasField("pull_request_failure")
+                else None
+            ),
+            change=ConfigurationChange.from_message(entry.change) if entry.HasField("change") else None,
+            provenance=Provenance.from_message(entry.provenance) if entry.HasField("provenance") else None,
+            submodule_pull_requests=[
+                SubmodulePullRequest.from_message(submodule) for submodule in entry.submodule_pull_requests
+            ],
+        )

gitd/publishing_calls.py

@@ -0,0 +1,47 @@
+"""The calls that read and set the rules publishing follows: for a platform's own pages,
+never for an agent."""
+
+from __future__ import annotations
+
+from . import messages, methods
+from .connection import Connection
+from .publishing_settings import Preset, PublishSettings
+
+
+class Publishing:
+    """The publishing settings, per repository prefix, as gitd.publishing.
+
+    gitd.publishing.set(PublishSettings(url_prefix="https://github.com/acme", preset="recommended",
+                                        branch_prefix="agents/"))
+    """
+
+    def __init__(self, connection: Connection) -> None:
+        self.connection = connection
+
+    def settings(self) -> list[PublishSettings]:
+        """Every setting, gitd.toml's included."""
+        response = self.connection.call(methods.GET_SETTINGS, messages.GetSettingsRequest())
+        return [PublishSettings.from_message(settings) for settings in response.settings]
+
+    def set(self, settings: PublishSettings) -> PublishSettings:
+        """Keeps the settings of a prefix, replacing those it had, as gitd checked them."""
+        request = messages.SetSettingsRequest(settings=settings.to_message())
+        return PublishSettings.from_message(self.connection.call(methods.SET_SETTINGS, request).settings)
+
+    def remove(self, url_prefix: str) -> None:
+        """Forgets the settings of a prefix set through the API."""
+        self.connection.call(methods.REMOVE_SETTINGS, messages.RemoveSettingsRequest(url_prefix=url_prefix))
+
+    def presets(self) -> list[Preset]:
+        """Every preset as it applies: gitd's own, gitd.toml's and those set through the API."""
+        response = self.connection.call(methods.LIST_PRESETS, messages.ListPresetsRequest())
+        return [Preset.from_message(preset) for preset in response.presets]
+
+    def set_preset(self, preset: Preset) -> Preset:
+        """Keeps a preset, replacing one of the same name; "recommended" replaces gitd's own."""
+        request = messages.SetPresetRequest(preset=preset.to_message())
+        return Preset.from_message(self.connection.call(methods.SET_PRESET, request).preset)
+
+    def remove_preset(self, name: str) -> None:
+        """Forgets a preset set through the API; refused while settings take it."""
+        self.connection.call(methods.REMOVE_PRESET, messages.RemovePresetRequest(name=name))

gitd/publishing_settings.py

@@ -0,0 +1,216 @@
+"""The rules publishing follows, and what a publish says of its pull request, as plain
+dataclasses that write the messages gitd takes and read those it answers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+from . import messages
+
+OPENING_PREFIX = "OPEN_"
+ORIGIN_PREFIX = "ORIGIN_"
+
+
+class Opening(StrEnum):
+    """When publishes open pull requests: only when a publish asks, or always."""
+
+    WHEN_ASKED = "when_asked"
+    ALWAYS = "always"
+
+    @classmethod
+    def from_message(cls, number: int) -> Opening:
+        name = messages.OPENING.name(number).removeprefix(OPENING_PREFIX).lower()
+        return cls(name) if name in {member.value for member in cls} else cls.WHEN_ASKED
+
+    def to_message(self) -> int:
+        return messages.OPENING.number(OPENING_PREFIX + self.value.upper())
+
+
+@dataclass(frozen=True)
+class PullRequestSettings:
+    """How publishes open pull requests: when, as drafts or not, with which labels, and
+    whether the person a publish names as requester is asked to review."""
+
+    opening: Opening = Opening.WHEN_ASKED
+    draft: bool = False
+    labels: list[str] = field(default_factory=list)
+    request_review_from_requester: bool = False
+
+    @classmethod
+    def from_message(cls, settings: Any) -> PullRequestSettings:
+        return cls(
+            opening=Opening.from_message(settings.open),
+            draft=settings.draft,
+            labels=list(settings.labels),
+            request_review_from_requester=settings.request_review_from_requester,
+        )
+
+    def to_message(self) -> Any:
+        return messages.PullRequestSettings(
+            open=self.opening.to_message(),
+            draft=self.draft,
+            labels=self.labels,
+            request_review_from_requester=self.request_review_from_requester,
+        )
+
+
+@dataclass(frozen=True)
+class PublishSettings:
+    """The rules of the repositories whose address starts with url_prefix (empty for every
+    repository): the name of a preset whose rules they take ("recommended" is gitd's own),
+    paths a publish may not change and paths it may not delete, as git's glob pathspecs,
+    paths those rules leave free, at most how many files it may change, the branch prefix,
+    and how pull requests are opened. from_file says gitd.toml declares them."""
+
+    url_prefix: str = ""
+    preset: str = ""
+    protected_paths: list[str] = field(default_factory=list)
+    kept_paths: list[str] = field(default_factory=list)
+    allowed_paths: list[str] = field(default_factory=list)
+    max_changed_files: int | None = None
+    branch_prefix: str = ""
+    pull_requests: PullRequestSettings | None = None
+    from_file: bool = False
+
+    @classmethod
+    def from_message(cls, settings: Any) -> PublishSettings:
+        return cls(
+            url_prefix=settings.url_prefix,
+            preset=settings.preset,
+            protected_paths=list(settings.protected_paths),
+            kept_paths=list(settings.kept_paths),
+            allowed_paths=list(settings.allowed_paths),
+            max_changed_files=settings.max_changed_files if settings.HasField("max_changed_files") else None,
+            branch_prefix=settings.branch_prefix,
+            pull_requests=(
+                PullRequestSettings.from_message(settings.pull_requests)
+                if settings.HasField("pull_requests")
+                else None
+            ),
+            from_file=settings.from_file,
+        )
+
+    def to_message(self) -> Any:
+        message: Any = messages.PublishSettings(
+            url_prefix=self.url_prefix,
+            preset=self.preset,
+            protected_paths=self.protected_paths,
+            kept_paths=self.kept_paths,
+            allowed_paths=self.allowed_paths,
+            branch_prefix=self.branch_prefix,
+        )
+        if self.max_changed_files is not None:
+            message.max_changed_files = self.max_changed_files
+        if self.pull_requests is not None:
+            message.pull_requests.CopyFrom(self.pull_requests.to_message())
+        return message
+
+
+class PresetOrigin(StrEnum):
+    """Where a preset comes from: gitd's own, gitd.toml, or the API."""
+
+    BUILT_IN = "built_in"
+    FILE = "file"
+    API = "api"
+
+    @classmethod
+    def from_message(cls, number: int) -> PresetOrigin:
+        name = messages.PRESET_ORIGIN.name(number).removeprefix(ORIGIN_PREFIX).lower()
+        return cls(name) if name in {member.value for member in cls} else cls.API
+
+
+@dataclass(frozen=True)
+class Preset:
+    """A named set of rules settings take: paths a publish may not change, paths it may not
+    delete, and at most how many files it may change. One named "recommended" replaces
+    gitd's own. origin is read from gitd, never sent."""
+
+    name: str
+    protected_paths: list[str] = field(default_factory=list)
+    kept_paths: list[str] = field(default_factory=list)
+    max_changed_files: int | None = None
+    origin: PresetOrigin = PresetOrigin.API
+
+    @classmethod
+    def from_message(cls, preset: Any) -> Preset:
+        return cls(
+            name=preset.name,
+            protected_paths=list(preset.protected_paths),
+            kept_paths=list(preset.kept_paths),
+            max_changed_files=preset.max_changed_files if preset.HasField("max_changed_files") else None,
+            origin=PresetOrigin.from_message(preset.origin),
+        )
+
+    def to_message(self) -> Any:
+        message: Any = messages.Preset(
+            name=self.name, protected_paths=self.protected_paths, kept_paths=self.kept_paths
+        )
+        if self.max_changed_files is not None:
+            message.max_changed_files = self.max_changed_files
+        return message
+
+
+@dataclass(frozen=True)
+class PullRequestOptions:
+    """A publish's own say on its pull request: open one even when the settings open them
+    only when asked, its title (the newest commit's subject when empty), the text before
+    what gitd checked, the branch it merges into, and whether it is a draft. submodules
+    opens one too in each submodule's repository, with the same title, into the branch
+    .gitmodules names for it or its default branch: to be merged first, with a merge commit."""
+
+    open: bool = False
+    title: str = ""
+    body: str = ""
+    base: str = ""
+    draft: bool | None = None
+    submodules: bool = False
+
+    def to_message(self) -> Any:
+        message: Any = messages.PullRequestOptions(
+            open=self.open, title=self.title, body=self.body, base=self.base, submodules=self.submodules
+        )
+        if self.draft is not None:
+            message.draft = self.draft
+        return message
+
+
+@dataclass(frozen=True)
+class Provenance:
+    """Where a publish's work came from, as the platform says: gitd records it as told and
+    never writes it into a commit. Each field is one line of at most 200 characters;
+    task_url is an https address."""
+
+    agent: str = ""
+    model: str = ""
+    session: str = ""
+    task_url: str = ""
+
+    @classmethod
+    def from_message(cls, provenance: Any) -> Provenance:
+        return cls(
+            agent=provenance.agent,
+            model=provenance.model,
+            session=provenance.session,
+            task_url=provenance.task_url,
+        )
+
+    def to_message(self) -> Any:
+        return messages.Provenance(
+            agent=self.agent, model=self.model, session=self.session, task_url=self.task_url
+        )
+
+
+@dataclass(frozen=True)
+class OpenedPullRequest:
+    """A pull request gitd opened; updated says it was already open from the branch, and
+    gitd updated its title and body."""
+
+    url: str
+    number: int
+    updated: bool = False
+
+    @classmethod
+    def from_message(cls, opened: Any) -> OpenedPullRequest:
+        return cls(url=opened.url, number=opened.number, updated=opened.updated)

gitd/timestamps.py

@@ -0,0 +1,22 @@
+"""Between the contract's google.protobuf.Timestamp and Python's datetime."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+NANOSECONDS_PER_SECOND = 1_000_000_000
+
+
+class Timestamp:
+    """A Timestamp message read as a datetime, or written from one, always in UTC."""
+
+    @staticmethod
+    def to_datetime(message: Any) -> datetime:
+        return datetime.fromtimestamp(message.seconds + message.nanos / NANOSECONDS_PER_SECOND, tz=UTC)
+
+    @staticmethod
+    def fill(message: Any, moment: datetime) -> None:
+        seconds = moment.timestamp()
+        message.seconds = int(seconds // 1)
+        message.nanos = int(round((seconds % 1) * NANOSECONDS_PER_SECOND))

gitd/warm_layers.py

@@ -0,0 +1,34 @@
+"""Warm layers: what installing a repository's dependencies wrote, sealed from one
+workspace for the next ones to stand on."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+
+@dataclass(frozen=True)
+class WarmLayer:
+    """A layer sealed from a workspace. Workspaces stand on it at commit only; changed_files
+    are the files it changes that git does not ignore, and users the workspaces on it now."""
+
+    url: str
+    name: str
+    commit: str
+    sealed_at: datetime
+    sealed_from: str
+    changed_files: int
+    users: int
+
+    @classmethod
+    def from_message(cls, warm: Any) -> WarmLayer:
+        return cls(
+            url=warm.url,
+            name=warm.name,
+            commit=warm.commit,
+            sealed_at=datetime.fromtimestamp(warm.sealed_at, tz=UTC),
+            sealed_from=warm.sealed_from,
+            changed_files=warm.changed_files,
+            users=warm.users,
+        )