basstler-github 4.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- basstler/github/__init__.py +0 -0
- basstler/github/actions_budget.py +428 -0
- basstler/github/actions_secret.py +25 -0
- basstler/github/actions_settings.py +162 -0
- basstler/github/actions_usage.py +297 -0
- basstler/github/basstler_project.py +75 -0
- basstler/github/branch_pull_request.py +24 -0
- basstler/github/client.py +452 -0
- basstler/github/comparison.py +60 -0
- basstler/github/constants.py +197 -0
- basstler/github/credential.py +85 -0
- basstler/github/exceptions.py +264 -0
- basstler/github/file_proposal.py +440 -0
- basstler/github/fork_sync.py +44 -0
- basstler/github/git_objects.py +57 -0
- basstler/github/graphql.py +101 -0
- basstler/github/issue.py +221 -0
- basstler/github/label.py +78 -0
- basstler/github/login_lending.py +46 -0
- basstler/github/main_failure.py +289 -0
- basstler/github/permission_level.py +33 -0
- basstler/github/pull_request.py +74 -0
- basstler/github/pull_request_changes.py +141 -0
- basstler/github/pull_request_description.py +145 -0
- basstler/github/pull_request_ends.py +58 -0
- basstler/github/pull_request_form.py +136 -0
- basstler/github/pull_request_models.py +321 -0
- basstler/github/pull_request_record.py +369 -0
- basstler/github/pull_request_source.py +395 -0
- basstler/github/pull_request_state.py +437 -0
- basstler/github/queries/pull_request_for_branch.graphql +17 -0
- basstler/github/queries/review_threads_page.graphql +72 -0
- basstler/github/query_documents.py +37 -0
- basstler/github/release_version.py +565 -0
- basstler/github/remote.py +36 -0
- basstler/github/repository.py +532 -0
- basstler/github/repository_access.py +459 -0
- basstler/github/repository_attachment.py +95 -0
- basstler/github/repository_details.py +98 -0
- basstler/github/repository_option.py +43 -0
- basstler/github/repository_resources.py +133 -0
- basstler/github/rest_models.py +353 -0
- basstler/github/review_models.py +223 -0
- basstler/github/run_listing.py +148 -0
- basstler/github/stack_configuration.py +178 -0
- basstler/github/states.py +257 -0
- basstler/github/token_form.py +360 -0
- basstler/github/tooling_labels.py +83 -0
- basstler/github/user_steps.py +170 -0
- basstler/github/web_form.py +56 -0
- basstler/github/web_page.py +33 -0
- basstler/github/wire_form.py +159 -0
- basstler/github/workflow_run.py +126 -0
- basstler/github/workflows.py +561 -0
- basstler/templates/actions_budget.py.jinja +26 -0
- basstler_github-4.2.0.dist-info/METADATA +16 -0
- basstler_github-4.2.0.dist-info/RECORD +60 -0
- basstler_github-4.2.0.dist-info/WHEEL +4 -0
- basstler_github-4.2.0.dist-info/licenses/LICENSE +202 -0
- basstler_github-4.2.0.dist-info/licenses/NOTICE +13 -0
|
@@ -0,0 +1,459 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Reading and writing a repository's pull requests and labels.
|
|
3
|
+
|
|
4
|
+
The reading and the writing halves are declared separately, so a caller that must not
|
|
5
|
+
write - the board export - can be handed a reader and provably cannot. Every write here
|
|
6
|
+
was probed against the live API first: a pull request's *base branch* is the one the
|
|
7
|
+
credential a session carries is refused, which is why retargeting is reported for a
|
|
8
|
+
caller to perform rather than performed.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import urllib.parse
|
|
14
|
+
from abc import ABC, abstractmethod
|
|
15
|
+
from collections.abc import Mapping, Sequence
|
|
16
|
+
from dataclasses import dataclass
|
|
17
|
+
from enum import Enum, StrEnum
|
|
18
|
+
from typing import Any
|
|
19
|
+
|
|
20
|
+
from basstler.github.client import GitHubClient, GitHubRestClient
|
|
21
|
+
from basstler.github.issue import ClosingReason, IssueClosing, IssueComment
|
|
22
|
+
from basstler.github.label import LabelReplacement, NewLabel, RepositoryLabel
|
|
23
|
+
from basstler.github.pull_request import PullRequestDescription
|
|
24
|
+
from basstler.github.pull_request_ends import PullRequestEnds
|
|
25
|
+
from basstler.github.pull_request_models import CheckStatus
|
|
26
|
+
from basstler.github.pull_request_record import (
|
|
27
|
+
AccountField,
|
|
28
|
+
CommitChecks,
|
|
29
|
+
PullRequestRecord,
|
|
30
|
+
)
|
|
31
|
+
from basstler.github.pull_request_state import PullRequestState
|
|
32
|
+
from basstler.github.repository import HasRepository, Repository
|
|
33
|
+
from basstler.github.rest_models import (
|
|
34
|
+
RestCheckRunPage,
|
|
35
|
+
RestCombinedStatusPage,
|
|
36
|
+
)
|
|
37
|
+
from basstler.github.states import CombinedCheckState
|
|
38
|
+
from basstler.github.tooling_labels import GitHubLabel
|
|
39
|
+
from basstler.github.web_page import WebPage
|
|
40
|
+
|
|
41
|
+
# %% what a pass reads and writes
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
@dataclass(frozen=True)
|
|
45
|
+
class PullRequestReader(ABC):
|
|
46
|
+
"""
|
|
47
|
+
Reading the pull-request state a pass derives from.
|
|
48
|
+
|
|
49
|
+
Implementations inherit rather than merely match the shape, so one that omits a read
|
|
50
|
+
is refused when it is constructed rather than when the missing call is first made.
|
|
51
|
+
"""
|
|
52
|
+
|
|
53
|
+
@abstractmethod
|
|
54
|
+
def open_pull_requests(self) -> list[PullRequestRecord]:
|
|
55
|
+
""":return: Every open pull request on the fork."""
|
|
56
|
+
|
|
57
|
+
@abstractmethod
|
|
58
|
+
def pull_request(self, number: int) -> PullRequestRecord:
|
|
59
|
+
""":param number: The pull request to read.
|
|
60
|
+
:return: That pull request."""
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
@dataclass(frozen=True)
|
|
64
|
+
class PullRequestWriter(ABC):
|
|
65
|
+
"""
|
|
66
|
+
The writes a pass makes, each one probed against the live API first.
|
|
67
|
+
|
|
68
|
+
Every one of them is available to the credential a session carries; a pull request's
|
|
69
|
+
*base branch* is the single write that is not, which is why reparenting is the
|
|
70
|
+
caller's job and none of this is.
|
|
71
|
+
"""
|
|
72
|
+
|
|
73
|
+
@abstractmethod
|
|
74
|
+
def replace_labels(self, number: int, labels: Sequence[str]) -> None:
|
|
75
|
+
""":param number: The pull request to write.
|
|
76
|
+
:param labels: The complete label set it must end up with."""
|
|
77
|
+
|
|
78
|
+
@abstractmethod
|
|
79
|
+
def add_comment(self, number: int, body: str) -> str:
|
|
80
|
+
""":param number: The pull request to comment on.
|
|
81
|
+
:param body: The comment.
|
|
82
|
+
:return: The comment's URL."""
|
|
83
|
+
|
|
84
|
+
@abstractmethod
|
|
85
|
+
def set_description(self, number: int, body: str) -> None:
|
|
86
|
+
""":param number: The pull request to write.
|
|
87
|
+
:param body: The new description."""
|
|
88
|
+
|
|
89
|
+
@abstractmethod
|
|
90
|
+
def close_pull_request(self, number: int) -> None:
|
|
91
|
+
""":param number: The pull request to close, as completed."""
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
@dataclass(frozen=True)
|
|
95
|
+
class ForkPullRequests(PullRequestReader, PullRequestWriter, ABC):
|
|
96
|
+
"""
|
|
97
|
+
Everything a pass does to the fork's pull requests.
|
|
98
|
+
|
|
99
|
+
A pass reads state and writes back to the same fork, so the two halves are named
|
|
100
|
+
together wherever both are needed; the board export takes the reading half alone,
|
|
101
|
+
which is what keeps an export from being able to write.
|
|
102
|
+
"""
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
@dataclass(frozen=True)
|
|
106
|
+
class RepositoryLabels(ABC):
|
|
107
|
+
"""
|
|
108
|
+
The labels a repository carries, and adding one it lacks.
|
|
109
|
+
"""
|
|
110
|
+
|
|
111
|
+
@abstractmethod
|
|
112
|
+
def labels(self) -> set[str]:
|
|
113
|
+
""":return: The name of every label the repository carries."""
|
|
114
|
+
|
|
115
|
+
@abstractmethod
|
|
116
|
+
def create_label(self, label: GitHubLabel) -> None:
|
|
117
|
+
""":param label: The label to add, described by its purpose."""
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
@dataclass(frozen=True)
|
|
121
|
+
class CredentialHolder(ABC):
|
|
122
|
+
"""
|
|
123
|
+
Telling whose credential a client calls GitHub with.
|
|
124
|
+
"""
|
|
125
|
+
|
|
126
|
+
@abstractmethod
|
|
127
|
+
def authenticated_login(self) -> str:
|
|
128
|
+
""":return: The login of the account the credential belongs to."""
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
class GitHubPath(StrEnum):
|
|
132
|
+
"""
|
|
133
|
+
The API routes that are not below a repository, ``/``-separated on every platform.
|
|
134
|
+
"""
|
|
135
|
+
|
|
136
|
+
AUTHENTICATED_USER = "/user"
|
|
137
|
+
"""
|
|
138
|
+
The account the request's credential belongs to.
|
|
139
|
+
"""
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
class GitHubRepositoryPath(StrEnum):
|
|
143
|
+
"""
|
|
144
|
+
The API routes below a repository, ``/``-separated on every platform.
|
|
145
|
+
"""
|
|
146
|
+
|
|
147
|
+
PULL_REQUESTS = "/pulls"
|
|
148
|
+
"""
|
|
149
|
+
The repository's pull requests.
|
|
150
|
+
"""
|
|
151
|
+
|
|
152
|
+
LABELS = "/labels"
|
|
153
|
+
"""
|
|
154
|
+
The labels defined on the repository.
|
|
155
|
+
"""
|
|
156
|
+
|
|
157
|
+
COMMITS = "/commits"
|
|
158
|
+
"""
|
|
159
|
+
The repository's commits.
|
|
160
|
+
"""
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
class CommitReport(StrEnum):
|
|
164
|
+
"""
|
|
165
|
+
The listings reported against one commit, below :attr:`GitHubRepositoryPath.COMMITS`.
|
|
166
|
+
"""
|
|
167
|
+
|
|
168
|
+
CHECK_RUNS = "check-runs"
|
|
169
|
+
"""
|
|
170
|
+
The check runs reported against it.
|
|
171
|
+
"""
|
|
172
|
+
|
|
173
|
+
STATUS = "status"
|
|
174
|
+
"""
|
|
175
|
+
The commit statuses posted against it.
|
|
176
|
+
"""
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
MAXIMUM_PULL_REQUESTS_PER_PAGE = 100
|
|
180
|
+
"""
|
|
181
|
+
The most pull requests one page of GitHub's pull request listing holds.
|
|
182
|
+
"""
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
class ListingParameter(StrEnum):
|
|
186
|
+
"""
|
|
187
|
+
The query parameters a paged listing takes.
|
|
188
|
+
"""
|
|
189
|
+
|
|
190
|
+
STATE = "state"
|
|
191
|
+
"""
|
|
192
|
+
Which pull requests to list, by state.
|
|
193
|
+
"""
|
|
194
|
+
|
|
195
|
+
PAGE_SIZE = "per_page"
|
|
196
|
+
"""
|
|
197
|
+
How many entries one page holds.
|
|
198
|
+
"""
|
|
199
|
+
|
|
200
|
+
HEAD = "head"
|
|
201
|
+
"""
|
|
202
|
+
The branch the pull requests are opened from, as ``owner:branch``.
|
|
203
|
+
"""
|
|
204
|
+
|
|
205
|
+
BASE = "base"
|
|
206
|
+
"""
|
|
207
|
+
The branch the pull requests merge into.
|
|
208
|
+
"""
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
@dataclass(frozen=True)
|
|
212
|
+
class PullRequestListingSpecification:
|
|
213
|
+
"""
|
|
214
|
+
One filter the pull request list API takes: what it is asked for by, and which
|
|
215
|
+
:class:`PullRequestState` values it lets through.
|
|
216
|
+
"""
|
|
217
|
+
|
|
218
|
+
query: str
|
|
219
|
+
"""
|
|
220
|
+
The value the list API's ``state`` parameter takes for this filter.
|
|
221
|
+
"""
|
|
222
|
+
|
|
223
|
+
states: tuple[PullRequestState, ...]
|
|
224
|
+
"""
|
|
225
|
+
The pull request states this filter lets through.
|
|
226
|
+
"""
|
|
227
|
+
|
|
228
|
+
def path_on(self, repository: Repository) -> str:
|
|
229
|
+
"""
|
|
230
|
+
:param repository: The repository the pull requests are opened on.
|
|
231
|
+
:return: The REST path listing the first page of its pull requests this filter
|
|
232
|
+
lets through.
|
|
233
|
+
"""
|
|
234
|
+
return self._path(repository, {})
|
|
235
|
+
|
|
236
|
+
def path_between(self, ends: PullRequestEnds) -> str:
|
|
237
|
+
"""
|
|
238
|
+
:param ends: The branches the pull requests join.
|
|
239
|
+
:return: The REST path listing the pull requests from *ends*' head into its base
|
|
240
|
+
this filter lets through.
|
|
241
|
+
"""
|
|
242
|
+
return self._path(
|
|
243
|
+
ends.base.repository,
|
|
244
|
+
{
|
|
245
|
+
ListingParameter.HEAD: ends.head.repository.branch_label(ends.head),
|
|
246
|
+
ListingParameter.BASE: ends.base.name,
|
|
247
|
+
},
|
|
248
|
+
)
|
|
249
|
+
|
|
250
|
+
def _path(
|
|
251
|
+
self, repository: Repository, filters: Mapping[ListingParameter, str]
|
|
252
|
+
) -> str:
|
|
253
|
+
"""
|
|
254
|
+
:param repository: The repository the pull requests are opened on.
|
|
255
|
+
:param filters: Further filters of the listing.
|
|
256
|
+
:return: The REST path listing a full first page of them.
|
|
257
|
+
"""
|
|
258
|
+
query = urllib.parse.urlencode(
|
|
259
|
+
{
|
|
260
|
+
ListingParameter.STATE: self.query,
|
|
261
|
+
ListingParameter.PAGE_SIZE: MAXIMUM_PULL_REQUESTS_PER_PAGE,
|
|
262
|
+
**filters,
|
|
263
|
+
},
|
|
264
|
+
safe=":",
|
|
265
|
+
)
|
|
266
|
+
return f"{repository.pull_requests_path}?{query}"
|
|
267
|
+
|
|
268
|
+
|
|
269
|
+
class PullRequestListState(PullRequestListingSpecification, Enum):
|
|
270
|
+
"""
|
|
271
|
+
The pull request states the list API filters on: each :class:`PullRequestState` a
|
|
272
|
+
pull request reports, plus every state at once.
|
|
273
|
+
|
|
274
|
+
Each member *is* a :class:`PullRequestListingSpecification`, written as its fields
|
|
275
|
+
in declaration order - ``query``, then ``states`` - which the enum passes straight to
|
|
276
|
+
the dataclass.
|
|
277
|
+
"""
|
|
278
|
+
|
|
279
|
+
OPEN = PullRequestState.OPEN.value, (PullRequestState.OPEN,)
|
|
280
|
+
"""
|
|
281
|
+
Pull requests whose state is :attr:`PullRequestState.OPEN`: drafts and those ready
|
|
282
|
+
for review alike.
|
|
283
|
+
"""
|
|
284
|
+
|
|
285
|
+
CLOSED = PullRequestState.CLOSED.value, (PullRequestState.CLOSED,)
|
|
286
|
+
"""
|
|
287
|
+
Pull requests whose state is :attr:`PullRequestState.CLOSED`: merged and closed
|
|
288
|
+
unmerged alike.
|
|
289
|
+
"""
|
|
290
|
+
|
|
291
|
+
ALL = "all", tuple(PullRequestState)
|
|
292
|
+
"""
|
|
293
|
+
Every pull request, whatever its :class:`PullRequestState`.
|
|
294
|
+
"""
|
|
295
|
+
|
|
296
|
+
|
|
297
|
+
# %% the client that makes the calls
|
|
298
|
+
|
|
299
|
+
|
|
300
|
+
@dataclass(frozen=True)
|
|
301
|
+
class GitHubRepository(
|
|
302
|
+
HasRepository, ForkPullRequests, CommitChecks, RepositoryLabels, CredentialHolder
|
|
303
|
+
):
|
|
304
|
+
"""
|
|
305
|
+
Every pull-request and label call this tooling makes, against one repository.
|
|
306
|
+
"""
|
|
307
|
+
|
|
308
|
+
client: GitHubClient
|
|
309
|
+
"""
|
|
310
|
+
How the calls reach GitHub.
|
|
311
|
+
"""
|
|
312
|
+
|
|
313
|
+
page_size: int = 100
|
|
314
|
+
"""
|
|
315
|
+
How many pull requests, labels or checks to ask for per page.
|
|
316
|
+
"""
|
|
317
|
+
|
|
318
|
+
@classmethod
|
|
319
|
+
def from_environment(cls, repository: Repository) -> GitHubRepository:
|
|
320
|
+
"""
|
|
321
|
+
Build a client from whichever credential the environment carries.
|
|
322
|
+
|
|
323
|
+
:param repository: The repository to read and write.
|
|
324
|
+
:return: The client.
|
|
325
|
+
"""
|
|
326
|
+
return cls(repository, GitHubRestClient())
|
|
327
|
+
|
|
328
|
+
def open_pull_requests(self) -> list[PullRequestRecord]:
|
|
329
|
+
""":return: Every open pull request on the repository, oldest page first."""
|
|
330
|
+
return self._pull_requests_in_state(PullRequestListState.OPEN)
|
|
331
|
+
|
|
332
|
+
def all_pull_requests(self) -> list[PullRequestRecord]:
|
|
333
|
+
""":return: Every pull request on the repository, open or closed."""
|
|
334
|
+
return self._pull_requests_in_state(PullRequestListState.ALL)
|
|
335
|
+
|
|
336
|
+
def issue(self, number: int) -> Mapping[str, Any]:
|
|
337
|
+
""":param number: The issue or pull request to read.
|
|
338
|
+
:return: It, as the issues API describes it."""
|
|
339
|
+
return self.client.get(self._path(f"/issues/{number}"))
|
|
340
|
+
|
|
341
|
+
def _pull_requests_in_state(
|
|
342
|
+
self, state: PullRequestListState
|
|
343
|
+
) -> list[PullRequestRecord]:
|
|
344
|
+
"""
|
|
345
|
+
Read every page of pull requests in one state.
|
|
346
|
+
|
|
347
|
+
:param state: Which pull requests to list.
|
|
348
|
+
:return: Them, oldest page first.
|
|
349
|
+
"""
|
|
350
|
+
return self._every_entry(
|
|
351
|
+
GitHubRepositoryPath.PULL_REQUESTS, {ListingParameter.STATE: state.query}
|
|
352
|
+
)
|
|
353
|
+
|
|
354
|
+
def labels(self) -> set[str]:
|
|
355
|
+
return {
|
|
356
|
+
RepositoryLabel.from_json(label).name
|
|
357
|
+
for label in self._every_entry(GitHubRepositoryPath.LABELS, {})
|
|
358
|
+
}
|
|
359
|
+
|
|
360
|
+
def create_label(self, label: GitHubLabel) -> None:
|
|
361
|
+
self.client.send(
|
|
362
|
+
NewLabel(self.repository, RepositoryLabel(label, label.purpose))
|
|
363
|
+
)
|
|
364
|
+
|
|
365
|
+
def check_state(self, commit: str) -> CombinedCheckState:
|
|
366
|
+
runs = [
|
|
367
|
+
run
|
|
368
|
+
for page in self.client.get_pages(
|
|
369
|
+
self._listing(self._commit_report(commit, CommitReport.CHECK_RUNS), {})
|
|
370
|
+
)
|
|
371
|
+
for run in RestCheckRunPage.from_json(page).check_runs
|
|
372
|
+
]
|
|
373
|
+
statuses = [
|
|
374
|
+
status
|
|
375
|
+
for page in self.client.get_pages(
|
|
376
|
+
self._listing(self._commit_report(commit, CommitReport.STATUS), {})
|
|
377
|
+
)
|
|
378
|
+
for status in RestCombinedStatusPage.from_json(page).statuses
|
|
379
|
+
]
|
|
380
|
+
checks = CheckStatus.over(runs + statuses)
|
|
381
|
+
return CombinedCheckState.NOT_REPORTED if checks is None else checks.state
|
|
382
|
+
|
|
383
|
+
@staticmethod
|
|
384
|
+
def _commit_report(commit: str, report: CommitReport) -> str:
|
|
385
|
+
""":param commit: The commit reported against.
|
|
386
|
+
:param report: Which of its listings to read.
|
|
387
|
+
:return: The listing's path below the repository."""
|
|
388
|
+
return f"{GitHubRepositoryPath.COMMITS}/{commit}/{report}"
|
|
389
|
+
|
|
390
|
+
def authenticated_login(self) -> str:
|
|
391
|
+
account = self.client.get(str(GitHubPath.AUTHENTICATED_USER))
|
|
392
|
+
return str(account[AccountField.LOGIN])
|
|
393
|
+
|
|
394
|
+
def _every_entry(
|
|
395
|
+
self, path: GitHubRepositoryPath, filters: Mapping[ListingParameter, str]
|
|
396
|
+
) -> list[dict[str, Any]]:
|
|
397
|
+
"""
|
|
398
|
+
Read a listing below the repository whose pages are lists, to its end.
|
|
399
|
+
|
|
400
|
+
:param path: The listing's path below the repository.
|
|
401
|
+
:param filters: The query parameters narrowing the listing.
|
|
402
|
+
:return: Every entry, first page first.
|
|
403
|
+
"""
|
|
404
|
+
return self.client.get_entries(self._listing(str(path), filters))
|
|
405
|
+
|
|
406
|
+
def _listing(self, path: str, filters: Mapping[ListingParameter, str]) -> str:
|
|
407
|
+
"""
|
|
408
|
+
:param path: A listing's path below the repository.
|
|
409
|
+
:param filters: The query parameters narrowing it.
|
|
410
|
+
:return: Its path below the API root, asking for full pages.
|
|
411
|
+
"""
|
|
412
|
+
query = urllib.parse.urlencode(
|
|
413
|
+
{**filters, ListingParameter.PAGE_SIZE: self.page_size}
|
|
414
|
+
)
|
|
415
|
+
return self._path(f"{path}?{query}")
|
|
416
|
+
|
|
417
|
+
def _path(self, path: str) -> str:
|
|
418
|
+
"""
|
|
419
|
+
:param path: A path below the repository, starting with a slash.
|
|
420
|
+
:return: It below the API root.
|
|
421
|
+
"""
|
|
422
|
+
return f"/{self.repository.api_path}{path}"
|
|
423
|
+
|
|
424
|
+
def pull_request(self, number: int) -> PullRequestRecord:
|
|
425
|
+
""":param number: The pull request to read.
|
|
426
|
+
:return: That pull request."""
|
|
427
|
+
return self.client.get(
|
|
428
|
+
self._path(f"{GitHubRepositoryPath.PULL_REQUESTS}/{number}")
|
|
429
|
+
)
|
|
430
|
+
|
|
431
|
+
def replace_labels(self, number: int, labels: Sequence[str]) -> None:
|
|
432
|
+
"""
|
|
433
|
+
Write a pull request's complete label set.
|
|
434
|
+
|
|
435
|
+
:param number: The pull request to write.
|
|
436
|
+
:param labels: The complete set it must end up with, computed by
|
|
437
|
+
:meth:`stack.LabelWrite.replacing` - this call replaces rather than adds.
|
|
438
|
+
"""
|
|
439
|
+
self.client.send(LabelReplacement(self.repository, number, list(labels)))
|
|
440
|
+
|
|
441
|
+
def add_comment(self, number: int, body: str) -> str:
|
|
442
|
+
""":param number: The pull request to comment on.
|
|
443
|
+
:param body: The comment.
|
|
444
|
+
:return: The comment's URL."""
|
|
445
|
+
created = self.client.send(IssueComment(self.repository, number, body))
|
|
446
|
+
return WebPage.from_json(created).page_url
|
|
447
|
+
|
|
448
|
+
def set_description(self, number: int, body: str) -> None:
|
|
449
|
+
"""
|
|
450
|
+
Rewrite a pull request's description and nothing else.
|
|
451
|
+
|
|
452
|
+
:param number: The pull request to write.
|
|
453
|
+
:param body: The new description.
|
|
454
|
+
"""
|
|
455
|
+
self.client.send(PullRequestDescription(self.repository, number, body))
|
|
456
|
+
|
|
457
|
+
def close_pull_request(self, number: int) -> None:
|
|
458
|
+
""":param number: The pull request to close, as completed."""
|
|
459
|
+
self.client.send(IssueClosing(self.repository, number, ClosingReason.COMPLETED))
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Telling a Claude Code cloud session to attach a repository it cannot reach, and to ask the
|
|
3
|
+
user when the attach is refused.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
from dataclasses import dataclass
|
|
9
|
+
from enum import StrEnum
|
|
10
|
+
|
|
11
|
+
from basstler.github.repository import HasRepository
|
|
12
|
+
|
|
13
|
+
# %% the session's tools
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class SessionTool(StrEnum):
|
|
17
|
+
"""
|
|
18
|
+
The Claude Code tools a session calls.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
ATTACH_REPOSITORY = "mcp__claude-code-remote__add_repo"
|
|
22
|
+
"""
|
|
23
|
+
Attaches a repository to a cloud session, which lets its proxy answer that
|
|
24
|
+
repository's git and API requests.
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
REGISTER_REPOSITORY_ROOT = "mcp__claude-code-remote__register_repo_root"
|
|
28
|
+
"""
|
|
29
|
+
Loads the instructions of an attached repository's local clone into the session.
|
|
30
|
+
"""
|
|
31
|
+
|
|
32
|
+
ASK_USER = "AskUserQuestion"
|
|
33
|
+
"""
|
|
34
|
+
Asks the user to choose between options.
|
|
35
|
+
"""
|
|
36
|
+
|
|
37
|
+
RUN_SHELL_COMMAND = "Bash"
|
|
38
|
+
"""
|
|
39
|
+
Runs a command in the session's shell.
|
|
40
|
+
"""
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class SessionProxyAnswer(StrEnum):
|
|
44
|
+
"""
|
|
45
|
+
What a cloud session's proxy answers a GitHub request with, in GitHub's place.
|
|
46
|
+
"""
|
|
47
|
+
|
|
48
|
+
REPOSITORY_NOT_ATTACHED = (
|
|
49
|
+
"GitHub access to this repository is not enabled for this session"
|
|
50
|
+
)
|
|
51
|
+
"""
|
|
52
|
+
The repository is not attached to the session, whether or not it exists.
|
|
53
|
+
"""
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
# %% the instruction
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
@dataclass(frozen=True)
|
|
60
|
+
class RepositoryAttachment(HasRepository):
|
|
61
|
+
"""
|
|
62
|
+
How a cloud session gets :attr:`repository` attached, and what it then runs.
|
|
63
|
+
"""
|
|
64
|
+
|
|
65
|
+
retry_command: str
|
|
66
|
+
"""
|
|
67
|
+
The command that does what failed, once the repository is attached.
|
|
68
|
+
"""
|
|
69
|
+
|
|
70
|
+
benefit: str
|
|
71
|
+
"""
|
|
72
|
+
What attaching the repository gives the user, said when asking them to allow it.
|
|
73
|
+
"""
|
|
74
|
+
|
|
75
|
+
recommended_option: str = "Attach it (Recommended)"
|
|
76
|
+
"""
|
|
77
|
+
The first option the user is offered when the attach is refused.
|
|
78
|
+
"""
|
|
79
|
+
|
|
80
|
+
def instruction(self) -> str:
|
|
81
|
+
"""
|
|
82
|
+
:return: The tool call that attaches :attr:`repository`, the command to run
|
|
83
|
+
then without a local clone, and the question to put to the user when the
|
|
84
|
+
attach is refused.
|
|
85
|
+
"""
|
|
86
|
+
return (
|
|
87
|
+
f"Attach {self.repository.full_name} to this session: call "
|
|
88
|
+
f"{SessionTool.ATTACH_REPOSITORY} with owner {self.repository.owner}, repo "
|
|
89
|
+
f"{self.repository.name} and access push, then run {self.retry_command}. "
|
|
90
|
+
f"Only the attachment's credential is needed: skip the clone and the "
|
|
91
|
+
f"{SessionTool.REGISTER_REPOSITORY_ROOT} call the attach answer asks for. If "
|
|
92
|
+
f"the attach is refused, ask the user with {SessionTool.ASK_USER} to allow "
|
|
93
|
+
f'it, with "{self.recommended_option}" as the first option: '
|
|
94
|
+
f"{self.benefit}."
|
|
95
|
+
)
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
"""
|
|
2
|
+
What GitHub's repository resource says about a repository.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
from dataclasses import dataclass
|
|
8
|
+
from typing import Annotated
|
|
9
|
+
|
|
10
|
+
from pydantic import Field
|
|
11
|
+
|
|
12
|
+
from basstler.git.branch import Branch
|
|
13
|
+
from basstler.github.permission_level import PermissionLevel
|
|
14
|
+
from basstler.github.pull_request_state import ForkLineage
|
|
15
|
+
from basstler.github.repository import Repository
|
|
16
|
+
from basstler.github.repository_resources import RepositoryRead
|
|
17
|
+
from basstler.github.wire_form import BranchName, RepositoryDefaultBranch
|
|
18
|
+
from basstler.json_model import RawValueReader, ValidatedJSONModel
|
|
19
|
+
|
|
20
|
+
# %% the repository resource
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
class ContentsAccess(RawValueReader):
|
|
24
|
+
"""
|
|
25
|
+
Reads the requesting account's role in a repository, as its resource gives it, as
|
|
26
|
+
the :class:`PermissionLevel` it has on the repository's contents.
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
def read(self, value: dict[str, bool]) -> PermissionLevel | None:
|
|
30
|
+
if value.get("push"):
|
|
31
|
+
return PermissionLevel.WRITE
|
|
32
|
+
if value.get("pull"):
|
|
33
|
+
return PermissionLevel.READ
|
|
34
|
+
return None
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
class RepositoryDetails(ValidatedJSONModel):
|
|
38
|
+
"""
|
|
39
|
+
One repository, as its REST resource describes it.
|
|
40
|
+
"""
|
|
41
|
+
|
|
42
|
+
default_branch: Annotated[Branch[Repository], BranchName()]
|
|
43
|
+
"""
|
|
44
|
+
The branch pull requests target unless told otherwise.
|
|
45
|
+
"""
|
|
46
|
+
|
|
47
|
+
is_fork: Annotated[bool, Field(alias="fork")]
|
|
48
|
+
"""
|
|
49
|
+
Whether it is a fork, whose default branch follows its upstream's.
|
|
50
|
+
"""
|
|
51
|
+
|
|
52
|
+
is_private: Annotated[bool, Field(alias="private")]
|
|
53
|
+
"""
|
|
54
|
+
Whether only the people and tokens granted access can read it.
|
|
55
|
+
"""
|
|
56
|
+
|
|
57
|
+
parent_default_branch: Annotated[
|
|
58
|
+
Branch[Repository] | None, Field(alias="parent"), RepositoryDefaultBranch()
|
|
59
|
+
] = None
|
|
60
|
+
"""
|
|
61
|
+
The default branch of the repository it was forked from, ``None`` when it is no
|
|
62
|
+
fork.
|
|
63
|
+
"""
|
|
64
|
+
|
|
65
|
+
contents_access: Annotated[
|
|
66
|
+
PermissionLevel | None, Field(alias="permissions"), ContentsAccess()
|
|
67
|
+
] = None
|
|
68
|
+
"""
|
|
69
|
+
What the requesting account may do with the repository's files and branches,
|
|
70
|
+
``None`` when it may do neither or the request was anonymous.
|
|
71
|
+
"""
|
|
72
|
+
|
|
73
|
+
@property
|
|
74
|
+
def lineage(self) -> ForkLineage | None:
|
|
75
|
+
"""
|
|
76
|
+
What the repository was forked from, ``None`` unless it is a fork.
|
|
77
|
+
"""
|
|
78
|
+
if self.parent_default_branch is None:
|
|
79
|
+
return None
|
|
80
|
+
return ForkLineage(
|
|
81
|
+
upstream_repository=self.parent_default_branch.repository,
|
|
82
|
+
upstream_default_branch=self.parent_default_branch.name,
|
|
83
|
+
fork_default_branch=self.default_branch.name,
|
|
84
|
+
)
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
# %% reading it
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
@dataclass(frozen=True)
|
|
91
|
+
class RepositoryDetailsRead(RepositoryRead[RepositoryDetails]):
|
|
92
|
+
"""
|
|
93
|
+
Reads a repository's own resource.
|
|
94
|
+
"""
|
|
95
|
+
|
|
96
|
+
@property
|
|
97
|
+
def path(self) -> str:
|
|
98
|
+
return self.repository.api_path
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
"""
|
|
2
|
+
A GitHub repository given on the command line as ``owner/name``.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
from typing import Annotated
|
|
8
|
+
|
|
9
|
+
from cyclopts import Parameter, Token
|
|
10
|
+
|
|
11
|
+
from basstler.github.repository import Repository
|
|
12
|
+
|
|
13
|
+
# %% converting the value
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def parse_repository(_: type, tokens: tuple[Token, ...]) -> Repository:
|
|
17
|
+
"""
|
|
18
|
+
Convert a command-line ``owner/name`` value.
|
|
19
|
+
|
|
20
|
+
:param tokens: The one token given for the option.
|
|
21
|
+
:return: The repository it names.
|
|
22
|
+
:raises MalformedRepositoryError: If the value is not ``owner/name``.
|
|
23
|
+
"""
|
|
24
|
+
return Repository.parse(tokens[0].value)
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
# %% the parameters
|
|
28
|
+
|
|
29
|
+
RepositoryArgument = Annotated[
|
|
30
|
+
Repository,
|
|
31
|
+
Parameter(converter=parse_repository, n_tokens=1, accepts_keys=False),
|
|
32
|
+
]
|
|
33
|
+
"""
|
|
34
|
+
An ``owner/name`` repository given on the command line.
|
|
35
|
+
"""
|
|
36
|
+
|
|
37
|
+
RepositoryOption = Annotated[
|
|
38
|
+
Repository | None,
|
|
39
|
+
Parameter(converter=parse_repository, n_tokens=1, accepts_keys=False),
|
|
40
|
+
]
|
|
41
|
+
"""
|
|
42
|
+
An optional ``owner/name`` repository given on the command line.
|
|
43
|
+
"""
|