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,452 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Reading and writing GitHub through its REST API.
|
|
3
|
+
|
|
4
|
+
The reading and the writing halves are declared separately, so a caller that must not
|
|
5
|
+
write can be handed a reader and provably cannot.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import itertools
|
|
11
|
+
import json
|
|
12
|
+
import shutil
|
|
13
|
+
import subprocess
|
|
14
|
+
import time
|
|
15
|
+
import urllib.parse
|
|
16
|
+
import urllib.request
|
|
17
|
+
from abc import ABC, abstractmethod
|
|
18
|
+
from collections.abc import Mapping
|
|
19
|
+
from dataclasses import dataclass, field, replace
|
|
20
|
+
from datetime import timedelta
|
|
21
|
+
from enum import StrEnum
|
|
22
|
+
from functools import cached_property
|
|
23
|
+
from http import HTTPStatus
|
|
24
|
+
from http.client import HTTPResponse
|
|
25
|
+
from typing import Any
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
from basstler.class_property import classproperty
|
|
29
|
+
from basstler.environment import GitHubCredentialVariable
|
|
30
|
+
from basstler.github.constants import GitHubExecutable
|
|
31
|
+
from basstler.github.credential import CredentialProvider, GitHubCredential
|
|
32
|
+
from basstler.github.exceptions import (
|
|
33
|
+
GitHubCallFailed,
|
|
34
|
+
GitHubCredentialUnavailableError,
|
|
35
|
+
GitHubRequestFailed,
|
|
36
|
+
GitHubUnreachableError,
|
|
37
|
+
)
|
|
38
|
+
from basstler.github.repository import GitHubAddress, HasRepository
|
|
39
|
+
from basstler.json_model import ValidatedJSONModel
|
|
40
|
+
|
|
41
|
+
# %% the interface
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class HttpMethod(StrEnum):
|
|
45
|
+
"""
|
|
46
|
+
The HTTP methods the API is called with.
|
|
47
|
+
"""
|
|
48
|
+
|
|
49
|
+
GET = "GET"
|
|
50
|
+
POST = "POST"
|
|
51
|
+
PUT = "PUT"
|
|
52
|
+
PATCH = "PATCH"
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
class GitHubReader(ABC):
|
|
56
|
+
"""
|
|
57
|
+
Reading REST resources.
|
|
58
|
+
|
|
59
|
+
A path is relative to the API root, query included, e.g.
|
|
60
|
+
``repos/<owner>/<name>/pulls?state=open``.
|
|
61
|
+
"""
|
|
62
|
+
|
|
63
|
+
@abstractmethod
|
|
64
|
+
def get(self, path: str) -> Any:
|
|
65
|
+
"""
|
|
66
|
+
:param path: The resource's path.
|
|
67
|
+
:return: The parsed response.
|
|
68
|
+
"""
|
|
69
|
+
|
|
70
|
+
@abstractmethod
|
|
71
|
+
def get_pages(self, path: str) -> list[Any]:
|
|
72
|
+
"""
|
|
73
|
+
:param path: The listing's path, without a page number.
|
|
74
|
+
:return: Each page's parsed response, first page first.
|
|
75
|
+
"""
|
|
76
|
+
|
|
77
|
+
def get_entries(self, path: str) -> list[dict[str, Any]]:
|
|
78
|
+
"""
|
|
79
|
+
:param path: The path of a listing whose pages are lists.
|
|
80
|
+
:return: Every entry of every page, first page first.
|
|
81
|
+
"""
|
|
82
|
+
return [entry for page in self.get_pages(path) for entry in page]
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
class GitHubAttemptReader(ABC):
|
|
86
|
+
"""
|
|
87
|
+
Reading a REST resource that may be refused, such as one that may not exist.
|
|
88
|
+
"""
|
|
89
|
+
|
|
90
|
+
@abstractmethod
|
|
91
|
+
def attempt_get(self, path: str) -> GitHubResponse:
|
|
92
|
+
"""
|
|
93
|
+
Like :meth:`GitHubReader.get`, but a refusal or a call that got no answer is
|
|
94
|
+
returned on the answer instead of raised.
|
|
95
|
+
"""
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
class GitHubWrite(ValidatedJSONModel, ABC):
|
|
99
|
+
"""
|
|
100
|
+
A change sent to the REST API, carrying the resource it changes.
|
|
101
|
+
|
|
102
|
+
Its body is its fields, except those that only name the resource.
|
|
103
|
+
"""
|
|
104
|
+
|
|
105
|
+
@classproperty
|
|
106
|
+
@abstractmethod
|
|
107
|
+
def method(cls) -> HttpMethod:
|
|
108
|
+
"""
|
|
109
|
+
How the resource is written.
|
|
110
|
+
"""
|
|
111
|
+
|
|
112
|
+
@property
|
|
113
|
+
@abstractmethod
|
|
114
|
+
def path(self) -> str:
|
|
115
|
+
"""
|
|
116
|
+
The resource's path.
|
|
117
|
+
"""
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
class RepositoryWrite(GitHubWrite, HasRepository, ABC):
|
|
121
|
+
"""
|
|
122
|
+
A change to a resource of one repository.
|
|
123
|
+
"""
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
class GitHubWriter(ABC):
|
|
127
|
+
"""
|
|
128
|
+
Writing REST resources.
|
|
129
|
+
"""
|
|
130
|
+
|
|
131
|
+
@abstractmethod
|
|
132
|
+
def attempt_send(self, write: GitHubWrite) -> GitHubResponse:
|
|
133
|
+
"""
|
|
134
|
+
Like :meth:`send`, but a refusal or a call that got no answer is returned on the
|
|
135
|
+
answer instead of raised.
|
|
136
|
+
"""
|
|
137
|
+
|
|
138
|
+
def send(self, write: GitHubWrite) -> Any:
|
|
139
|
+
"""
|
|
140
|
+
:param write: The change to send.
|
|
141
|
+
:return: The parsed response, ``None`` when it has no body.
|
|
142
|
+
:raises GitHubRequestFailed: If the API refuses the write.
|
|
143
|
+
:raises GitHubUnreachableError: If the write gets no answer.
|
|
144
|
+
"""
|
|
145
|
+
return self.attempt_send(write).raise_if_failed()
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
class GitHubAttemptClient(GitHubAttemptReader, GitHubWriter, ABC):
|
|
149
|
+
"""
|
|
150
|
+
Reading and writing REST resources, with a refusal returned on the answer.
|
|
151
|
+
"""
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
class GitHubClient(GitHubReader, GitHubWriter, ABC):
|
|
155
|
+
"""
|
|
156
|
+
Reading and writing REST resources.
|
|
157
|
+
"""
|
|
158
|
+
|
|
159
|
+
|
|
160
|
+
class GitHubFullClient(GitHubClient, GitHubAttemptClient, ABC):
|
|
161
|
+
"""
|
|
162
|
+
Reading and writing REST resources, with a refusal raised or returned on the answer
|
|
163
|
+
as the caller chooses.
|
|
164
|
+
"""
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
# %% the implementation
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
class PageParameter(StrEnum):
|
|
171
|
+
"""
|
|
172
|
+
The query parameter a page of a listing is asked for by.
|
|
173
|
+
"""
|
|
174
|
+
|
|
175
|
+
PAGE = "page"
|
|
176
|
+
"""
|
|
177
|
+
Which page to read, counting from one.
|
|
178
|
+
"""
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
class ResponseHeader(StrEnum):
|
|
182
|
+
"""
|
|
183
|
+
The response headers the client reads.
|
|
184
|
+
"""
|
|
185
|
+
|
|
186
|
+
LINK = "Link"
|
|
187
|
+
"""
|
|
188
|
+
The links to the listing's other pages.
|
|
189
|
+
"""
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
NEXT_PAGE_RELATION = 'rel="next"'
|
|
193
|
+
"""
|
|
194
|
+
What a ``Link`` header carries when the listing has a page after this one.
|
|
195
|
+
"""
|
|
196
|
+
|
|
197
|
+
|
|
198
|
+
class ErrorResponsePassThrough(urllib.request.HTTPErrorProcessor):
|
|
199
|
+
"""
|
|
200
|
+
Hands a response with an error status back like any other, so the client decides
|
|
201
|
+
what a refusal means instead of :mod:`urllib` raising.
|
|
202
|
+
"""
|
|
203
|
+
|
|
204
|
+
def http_response(
|
|
205
|
+
self, request: urllib.request.Request, response: HTTPResponse
|
|
206
|
+
) -> HTTPResponse:
|
|
207
|
+
return response
|
|
208
|
+
|
|
209
|
+
https_response = http_response
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
SERVER_ERROR_STATUSES = range(HTTPStatus.INTERNAL_SERVER_ERROR, 600)
|
|
213
|
+
"""
|
|
214
|
+
Every status of the 5xx class, including those past the ones :class:`HTTPStatus` names.
|
|
215
|
+
"""
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
@dataclass(frozen=True)
|
|
219
|
+
class RetryPolicy:
|
|
220
|
+
"""
|
|
221
|
+
How often, and after how long, a read that GitHub answered with a server error is
|
|
222
|
+
asked again.
|
|
223
|
+
"""
|
|
224
|
+
|
|
225
|
+
retries: int = 3
|
|
226
|
+
"""
|
|
227
|
+
How many times a read is asked again after the first attempt.
|
|
228
|
+
"""
|
|
229
|
+
|
|
230
|
+
first_delay: timedelta = timedelta(seconds=1)
|
|
231
|
+
"""
|
|
232
|
+
The wait before the first retry.
|
|
233
|
+
"""
|
|
234
|
+
|
|
235
|
+
delay_factor: float = 2.0
|
|
236
|
+
"""
|
|
237
|
+
What each wait is multiplied by to give the next one.
|
|
238
|
+
"""
|
|
239
|
+
|
|
240
|
+
def delays(self) -> list[timedelta]:
|
|
241
|
+
"""
|
|
242
|
+
:return: The wait before each retry, first retry first.
|
|
243
|
+
"""
|
|
244
|
+
return [
|
|
245
|
+
self.first_delay * self.delay_factor**retry for retry in range(self.retries)
|
|
246
|
+
]
|
|
247
|
+
|
|
248
|
+
|
|
249
|
+
@dataclass(frozen=True)
|
|
250
|
+
class GitHubResponse:
|
|
251
|
+
"""
|
|
252
|
+
One answer from the API.
|
|
253
|
+
"""
|
|
254
|
+
|
|
255
|
+
body: Any
|
|
256
|
+
"""
|
|
257
|
+
The parsed JSON body, ``None`` when it has none.
|
|
258
|
+
"""
|
|
259
|
+
|
|
260
|
+
has_next_page: bool = False
|
|
261
|
+
"""
|
|
262
|
+
Whether the answer is a page of a listing with a page after it.
|
|
263
|
+
"""
|
|
264
|
+
|
|
265
|
+
failure: GitHubCallFailed | None = None
|
|
266
|
+
"""
|
|
267
|
+
Why the call failed, ``None`` when it succeeded.
|
|
268
|
+
"""
|
|
269
|
+
|
|
270
|
+
waits: tuple[timedelta, ...] = ()
|
|
271
|
+
"""
|
|
272
|
+
The wait before each time the call was asked again, first first.
|
|
273
|
+
"""
|
|
274
|
+
|
|
275
|
+
@property
|
|
276
|
+
def is_server_error(self) -> bool:
|
|
277
|
+
"""
|
|
278
|
+
:return: Whether GitHub answered with a 5xx status, which asking again may clear.
|
|
279
|
+
"""
|
|
280
|
+
return (
|
|
281
|
+
isinstance(self.failure, GitHubRequestFailed)
|
|
282
|
+
and self.failure.status in SERVER_ERROR_STATUSES
|
|
283
|
+
)
|
|
284
|
+
|
|
285
|
+
@property
|
|
286
|
+
def is_not_found(self) -> bool:
|
|
287
|
+
"""
|
|
288
|
+
:return: Whether GitHub answered 404: no such resource, or none this credential
|
|
289
|
+
may see.
|
|
290
|
+
"""
|
|
291
|
+
return (
|
|
292
|
+
isinstance(self.failure, GitHubRequestFailed)
|
|
293
|
+
and self.failure.status == HTTPStatus.NOT_FOUND
|
|
294
|
+
)
|
|
295
|
+
|
|
296
|
+
def raise_if_failed(self) -> Any:
|
|
297
|
+
"""
|
|
298
|
+
:return: :attr:`body`.
|
|
299
|
+
:raises GitHubCallFailed: If the call did not succeed.
|
|
300
|
+
"""
|
|
301
|
+
if self.failure is not None:
|
|
302
|
+
raise self.failure
|
|
303
|
+
return self.body
|
|
304
|
+
|
|
305
|
+
|
|
306
|
+
@dataclass(frozen=True)
|
|
307
|
+
class GitHubRestClient(GitHubFullClient):
|
|
308
|
+
"""
|
|
309
|
+
Plain authenticated HTTPS requests, through the proxy the environment names.
|
|
310
|
+
|
|
311
|
+
A listing is read page by page with the ``page`` parameter on the path it was asked
|
|
312
|
+
for. The URL a ``Link`` header names is never followed: GitHub writes it as a
|
|
313
|
+
``repositories/<id>/`` path, which the cloud session proxy refuses.
|
|
314
|
+
"""
|
|
315
|
+
|
|
316
|
+
token: str | None = None
|
|
317
|
+
"""
|
|
318
|
+
The credential the requests authenticate with; ``None`` reads it, at the first
|
|
319
|
+
request, from the first token variable set, else from ``gh``'s login.
|
|
320
|
+
"""
|
|
321
|
+
|
|
322
|
+
api_root: str = GitHubAddress.API
|
|
323
|
+
"""
|
|
324
|
+
The URL every path is relative to.
|
|
325
|
+
"""
|
|
326
|
+
|
|
327
|
+
retry_policy: RetryPolicy = field(default_factory=RetryPolicy)
|
|
328
|
+
"""
|
|
329
|
+
When a read answered with a server error is asked again.
|
|
330
|
+
|
|
331
|
+
A write is never sent again, since GitHub may have applied it.
|
|
332
|
+
"""
|
|
333
|
+
|
|
334
|
+
@cached_property
|
|
335
|
+
def credential(self) -> GitHubCredential:
|
|
336
|
+
"""
|
|
337
|
+
:return: The token the requests authenticate with, and where it came from.
|
|
338
|
+
:raises GitHubCredentialUnavailableError: If no token was given and neither the
|
|
339
|
+
environment nor ``gh`` has one.
|
|
340
|
+
"""
|
|
341
|
+
if self.token:
|
|
342
|
+
return GitHubCredential(self.token, CredentialProvider.CALLER)
|
|
343
|
+
variable = GitHubCredentialVariable.first_set()
|
|
344
|
+
if variable is not None:
|
|
345
|
+
return GitHubCredential(variable.read(), variable)
|
|
346
|
+
executable = shutil.which(GitHubExecutable.COMMAND_LINE)
|
|
347
|
+
if executable is None:
|
|
348
|
+
raise GitHubCredentialUnavailableError(tuple(GitHubCredentialVariable))
|
|
349
|
+
login = subprocess.run(
|
|
350
|
+
[executable, "auth", "token"], capture_output=True, encoding="utf-8"
|
|
351
|
+
)
|
|
352
|
+
if login.returncode != 0 or not login.stdout.strip():
|
|
353
|
+
raise GitHubCredentialUnavailableError(tuple(GitHubCredentialVariable))
|
|
354
|
+
return GitHubCredential(login.stdout.strip(), CredentialProvider.GH_LOGIN)
|
|
355
|
+
|
|
356
|
+
def get(self, path: str) -> Any:
|
|
357
|
+
return self.attempt_get(path).raise_if_failed()
|
|
358
|
+
|
|
359
|
+
def attempt_get(self, path: str) -> GitHubResponse:
|
|
360
|
+
return self._read(path)
|
|
361
|
+
|
|
362
|
+
def get_pages(self, path: str) -> list[Any]:
|
|
363
|
+
pages: list[Any] = []
|
|
364
|
+
for page_number in itertools.count(1):
|
|
365
|
+
response = self._read(self._page_path(path, page_number))
|
|
366
|
+
pages.append(response.raise_if_failed())
|
|
367
|
+
if not response.has_next_page:
|
|
368
|
+
break
|
|
369
|
+
return pages
|
|
370
|
+
|
|
371
|
+
def attempt_send(self, write: GitHubWrite) -> GitHubResponse:
|
|
372
|
+
return self._exchange(write.method, write.path, write.to_json())
|
|
373
|
+
|
|
374
|
+
@staticmethod
|
|
375
|
+
def _page_path(path: str, page_number: int) -> str:
|
|
376
|
+
"""
|
|
377
|
+
:param path: A listing's path.
|
|
378
|
+
:param page_number: The page to ask for, counting from one.
|
|
379
|
+
:return: The path asking for that page.
|
|
380
|
+
"""
|
|
381
|
+
parts = urllib.parse.urlsplit(path)
|
|
382
|
+
query = urllib.parse.parse_qsl(parts.query, keep_blank_values=True)
|
|
383
|
+
query.append((PageParameter.PAGE, str(page_number)))
|
|
384
|
+
return urllib.parse.urlunsplit(
|
|
385
|
+
parts._replace(query=urllib.parse.urlencode(query, safe=":"))
|
|
386
|
+
)
|
|
387
|
+
|
|
388
|
+
def _read(self, path: str) -> GitHubResponse:
|
|
389
|
+
"""
|
|
390
|
+
Read a resource, asking again as :attr:`retry_policy` says while GitHub answers
|
|
391
|
+
with a server error.
|
|
392
|
+
|
|
393
|
+
:param path: The path below :attr:`api_root`.
|
|
394
|
+
:return: The last answer, with the waits made before it.
|
|
395
|
+
"""
|
|
396
|
+
response = self._exchange(HttpMethod.GET, path, None)
|
|
397
|
+
waits: list[timedelta] = []
|
|
398
|
+
for delay in self.retry_policy.delays():
|
|
399
|
+
if not response.is_server_error:
|
|
400
|
+
break
|
|
401
|
+
time.sleep(delay.total_seconds())
|
|
402
|
+
waits.append(delay)
|
|
403
|
+
response = self._exchange(HttpMethod.GET, path, None)
|
|
404
|
+
return replace(response, waits=tuple(waits))
|
|
405
|
+
|
|
406
|
+
def _exchange(
|
|
407
|
+
self, method: HttpMethod, path: str, payload: Mapping[str, Any] | None
|
|
408
|
+
) -> GitHubResponse:
|
|
409
|
+
"""
|
|
410
|
+
Make one authenticated call.
|
|
411
|
+
|
|
412
|
+
:param method: The HTTP method.
|
|
413
|
+
:param path: The path below :attr:`api_root`.
|
|
414
|
+
:param payload: The JSON body, ``None`` for a read.
|
|
415
|
+
:return: The answer, carrying the failure when the API answers with an error
|
|
416
|
+
status or does not answer.
|
|
417
|
+
:raises GitHubCredentialUnavailableError: If no token is available.
|
|
418
|
+
"""
|
|
419
|
+
request = urllib.request.Request(
|
|
420
|
+
f"{self.api_root}/{path.removeprefix('/')}",
|
|
421
|
+
method=method,
|
|
422
|
+
data=None if payload is None else json.dumps(payload).encode(),
|
|
423
|
+
headers={
|
|
424
|
+
"Authorization": f"Bearer {self.credential.token}",
|
|
425
|
+
"Accept": "application/vnd.github+json",
|
|
426
|
+
"Content-Type": "application/json",
|
|
427
|
+
},
|
|
428
|
+
)
|
|
429
|
+
opener = urllib.request.build_opener(ErrorResponsePassThrough)
|
|
430
|
+
try:
|
|
431
|
+
with opener.open(request) as response:
|
|
432
|
+
status = response.status
|
|
433
|
+
raw_body = response.read()
|
|
434
|
+
links = response.headers.get(ResponseHeader.LINK) or ""
|
|
435
|
+
except OSError as error:
|
|
436
|
+
return GitHubResponse(
|
|
437
|
+
None, failure=GitHubUnreachableError(method, path, str(error))
|
|
438
|
+
)
|
|
439
|
+
if status >= HTTPStatus.MULTIPLE_CHOICES:
|
|
440
|
+
return GitHubResponse(
|
|
441
|
+
None,
|
|
442
|
+
failure=GitHubRequestFailed.for_status(
|
|
443
|
+
status=status,
|
|
444
|
+
detail=raw_body.decode(errors="replace"),
|
|
445
|
+
method=method,
|
|
446
|
+
path=path,
|
|
447
|
+
credential_origin=self.credential.origin,
|
|
448
|
+
),
|
|
449
|
+
)
|
|
450
|
+
return GitHubResponse(
|
|
451
|
+
json.loads(raw_body) if raw_body else None, NEXT_PAGE_RELATION in links
|
|
452
|
+
)
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
"""
|
|
2
|
+
How one commit relates to another, as GitHub's comparison of two refs reports it.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
from enum import StrEnum
|
|
8
|
+
|
|
9
|
+
from basstler.json_model import ValidatedJSONModel
|
|
10
|
+
|
|
11
|
+
# %% a comparison
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class ComparisonStatus(StrEnum):
|
|
15
|
+
"""
|
|
16
|
+
How the head of a comparison relates to its base.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
IDENTICAL = "identical"
|
|
20
|
+
"""
|
|
21
|
+
They are the same commit.
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
AHEAD = "ahead"
|
|
25
|
+
"""
|
|
26
|
+
The head has commits the base lacks and the base has none the head lacks.
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
BEHIND = "behind"
|
|
30
|
+
"""
|
|
31
|
+
The base has commits the head lacks and the head has none the base lacks.
|
|
32
|
+
"""
|
|
33
|
+
|
|
34
|
+
DIVERGED = "diverged"
|
|
35
|
+
"""
|
|
36
|
+
Each has commits the other lacks.
|
|
37
|
+
"""
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class Comparison(ValidatedJSONModel):
|
|
41
|
+
"""
|
|
42
|
+
GitHub's comparison of a head with a base.
|
|
43
|
+
"""
|
|
44
|
+
|
|
45
|
+
status: ComparisonStatus
|
|
46
|
+
"""
|
|
47
|
+
How the head relates to the base.
|
|
48
|
+
"""
|
|
49
|
+
|
|
50
|
+
ahead_by: int
|
|
51
|
+
"""
|
|
52
|
+
How many commits the head has that the base lacks.
|
|
53
|
+
"""
|
|
54
|
+
|
|
55
|
+
@property
|
|
56
|
+
def head_is_contained_in_base(self) -> bool:
|
|
57
|
+
"""
|
|
58
|
+
:return: Whether every commit of the head is already in the base.
|
|
59
|
+
"""
|
|
60
|
+
return self.status in {ComparisonStatus.IDENTICAL, ComparisonStatus.BEHIND}
|
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
"""
|
|
2
|
+
The maintenance executor's hand-maintained values.
|
|
3
|
+
|
|
4
|
+
Everything here is a decision somebody made and may change again - the heading a promotion
|
|
5
|
+
link is written under, the label marking it sent. They are gathered in one module, each
|
|
6
|
+
in the enum of the values it is one of, so changing one is an edit rather than a search
|
|
7
|
+
through whichever module happens to read it.
|
|
8
|
+
|
|
9
|
+
Values a program derives for itself belong beside the code that derives them, not here.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import re
|
|
15
|
+
from enum import Enum, StrEnum
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class GitHubExecutable(StrEnum):
|
|
19
|
+
"""
|
|
20
|
+
The executables the tooling reaches the GitHub API through, each named as it is on
|
|
21
|
+
``PATH``.
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
COMMAND_LINE = "gh"
|
|
25
|
+
"""
|
|
26
|
+
GitHub's own command-line client, preferred where it is installed.
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
CURL = "curl"
|
|
30
|
+
"""
|
|
31
|
+
The plain HTTP client the shell hooks fall back to, with a token, where there is no
|
|
32
|
+
``gh``.
|
|
33
|
+
"""
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class DescriptionPattern(Enum):
|
|
37
|
+
"""
|
|
38
|
+
What the tooling looks for in a pull request description.
|
|
39
|
+
"""
|
|
40
|
+
|
|
41
|
+
SESSION_LINK = re.compile(r"https://claude\.ai/code/session_[A-Za-z0-9_-]+")
|
|
42
|
+
"""
|
|
43
|
+
The session link a pull request description carries, which is the only channel for
|
|
44
|
+
telling a branch's owner that their branch needs them.
|
|
45
|
+
"""
|
|
46
|
+
|
|
47
|
+
HEADING = re.compile(r"^#{1,6} ", re.MULTILINE)
|
|
48
|
+
"""
|
|
49
|
+
The start of a Markdown heading line, which ends the section before it.
|
|
50
|
+
"""
|
|
51
|
+
|
|
52
|
+
LINK_TARGET = re.compile(r"(?<=\]\()[^)\s]+(?=\))")
|
|
53
|
+
"""
|
|
54
|
+
The URL a Markdown hyperlink points at.
|
|
55
|
+
"""
|
|
56
|
+
|
|
57
|
+
def first_in(self, text: str | None) -> str | None:
|
|
58
|
+
"""
|
|
59
|
+
:param text: The text to search, which may be absent.
|
|
60
|
+
:return: The first match, or ``None`` if the text holds none.
|
|
61
|
+
"""
|
|
62
|
+
if not text:
|
|
63
|
+
return None
|
|
64
|
+
found = self.value.search(text)
|
|
65
|
+
return found.group(0) if found else None
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
class MaintenanceText(StrEnum):
|
|
69
|
+
"""
|
|
70
|
+
Text a maintenance pass writes onto GitHub, and later finds again by.
|
|
71
|
+
"""
|
|
72
|
+
|
|
73
|
+
CONFLICT_COMMENT_PREFIX = "🔴 MAINTENANCE - NEEDS RESOLUTION:"
|
|
74
|
+
"""
|
|
75
|
+
Opens the comment a conflict is reported in, so the branch's owner can find every one
|
|
76
|
+
of them at a glance.
|
|
77
|
+
"""
|
|
78
|
+
|
|
79
|
+
MERGE_RESOLUTION = (
|
|
80
|
+
"Merge `{parent}` into this branch, resolve the conflicts in the merge commit "
|
|
81
|
+
"and push. A plain push publishes it; the pass never force-pushes a merged branch."
|
|
82
|
+
)
|
|
83
|
+
"""
|
|
84
|
+
How the owner of a conflicting branch resolves it when the pass merges its parent,
|
|
85
|
+
with the parent's name to fill in.
|
|
86
|
+
"""
|
|
87
|
+
|
|
88
|
+
REBASE_RESOLUTION = (
|
|
89
|
+
"Rebase this branch onto `{parent}`, resolve the conflicts and push with "
|
|
90
|
+
"`--force-with-lease`. Its `rebase` label is what allows the rewrite."
|
|
91
|
+
)
|
|
92
|
+
"""
|
|
93
|
+
How the owner of a conflicting branch resolves it when the pass rebases it onto its
|
|
94
|
+
parent, with the parent's name to fill in.
|
|
95
|
+
"""
|
|
96
|
+
|
|
97
|
+
LANDED_COMMENT = (
|
|
98
|
+
"Closed by a maintenance pass: every commit of `{branch}` is in `{base}`, so "
|
|
99
|
+
"its work has landed. GitHub records no merge for a pull request that is not "
|
|
100
|
+
"based on the branch it landed in, so it stayed open."
|
|
101
|
+
)
|
|
102
|
+
"""
|
|
103
|
+
What a pull request is told when it is closed because its work landed, with its
|
|
104
|
+
branch and the upstream base to fill in.
|
|
105
|
+
"""
|
|
106
|
+
|
|
107
|
+
PROMOTION_HEADING = "## Promote"
|
|
108
|
+
"""
|
|
109
|
+
Heading the compare-and-create link is written under, in the fork pull request's own
|
|
110
|
+
description - the summary that carried it is delivered once and then gone, and the
|
|
111
|
+
description is still there a week later.
|
|
112
|
+
"""
|
|
113
|
+
|
|
114
|
+
UPSTREAM_PULL_REQUEST_HEADING = "## Upstream pull request"
|
|
115
|
+
"""
|
|
116
|
+
Heading the link to the open upstream pull request opened from the branch is written
|
|
117
|
+
under, in the fork pull request's own description.
|
|
118
|
+
"""
|
|
119
|
+
|
|
120
|
+
FULL_DETAIL = "Full detail:"
|
|
121
|
+
"""
|
|
122
|
+
Opens the line an upstream pull request's description ends with, linking back to the
|
|
123
|
+
fork pull request it was promoted from.
|
|
124
|
+
"""
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
class MaintenanceNotice(StrEnum):
|
|
128
|
+
"""
|
|
129
|
+
What a maintenance command tells its caller on stderr about how it ran.
|
|
130
|
+
"""
|
|
131
|
+
|
|
132
|
+
NO_UPSTREAM = (
|
|
133
|
+
"no upstream is named, so the clone's own remote is the base: no upstream pull "
|
|
134
|
+
"request is read and no branch is promoted"
|
|
135
|
+
)
|
|
136
|
+
"""
|
|
137
|
+
The project is not a fork, so the pass leaves out every step that needs an upstream.
|
|
138
|
+
"""
|
|
139
|
+
|
|
140
|
+
LANDED_BRANCH_UNREADABLE = (
|
|
141
|
+
"`{branch}` is in the upstream base but its commits cannot be counted, because "
|
|
142
|
+
"`{base}` or `{head}` is not in this clone: its pull request was not closed. "
|
|
143
|
+
"Fetch the fork and run the pass again."
|
|
144
|
+
)
|
|
145
|
+
"""
|
|
146
|
+
A landed branch was left open because the fork's copy of it or of its base is
|
|
147
|
+
missing, with the branch and the two references to fill in.
|
|
148
|
+
"""
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
class MergeableState(StrEnum):
|
|
152
|
+
"""
|
|
153
|
+
The values GitHub reports as a pull request's ``mergeable_state``.
|
|
154
|
+
|
|
155
|
+
Only :attr:`DIRTY` means a branch genuinely conflicts with its base; every other one
|
|
156
|
+
means there are no conflicts, whatever else may be true of it.
|
|
157
|
+
"""
|
|
158
|
+
|
|
159
|
+
DIRTY = "dirty"
|
|
160
|
+
"""
|
|
161
|
+
The branch conflicts with its base.
|
|
162
|
+
"""
|
|
163
|
+
|
|
164
|
+
CLEAN = "clean"
|
|
165
|
+
"""
|
|
166
|
+
Mergeable, with every required check passing.
|
|
167
|
+
"""
|
|
168
|
+
|
|
169
|
+
UNSTABLE = "unstable"
|
|
170
|
+
"""
|
|
171
|
+
Mergeable, with a check that is not required failing.
|
|
172
|
+
"""
|
|
173
|
+
|
|
174
|
+
BLOCKED = "blocked"
|
|
175
|
+
"""
|
|
176
|
+
Mergeable once a required review or check passes.
|
|
177
|
+
"""
|
|
178
|
+
|
|
179
|
+
BEHIND = "behind"
|
|
180
|
+
"""
|
|
181
|
+
Mergeable once brought up to date with its base.
|
|
182
|
+
"""
|
|
183
|
+
|
|
184
|
+
HAS_HOOKS = "has_hooks"
|
|
185
|
+
"""
|
|
186
|
+
Mergeable, with pre-receive hooks configured.
|
|
187
|
+
"""
|
|
188
|
+
|
|
189
|
+
DRAFT = "draft"
|
|
190
|
+
"""
|
|
191
|
+
A draft, which cannot be merged until it is marked ready.
|
|
192
|
+
"""
|
|
193
|
+
|
|
194
|
+
UNKNOWN = "unknown"
|
|
195
|
+
"""
|
|
196
|
+
Not yet computed by GitHub.
|
|
197
|
+
"""
|