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,395 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Where the live state of the pull requests a plan references is read from.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
from abc import ABC, abstractmethod
|
|
8
|
+
from collections.abc import Iterable, Mapping
|
|
9
|
+
from dataclasses import dataclass, field
|
|
10
|
+
from http import HTTPStatus
|
|
11
|
+
from typing import Any
|
|
12
|
+
|
|
13
|
+
from basstler.github.client import (
|
|
14
|
+
GitHubFullClient,
|
|
15
|
+
GitHubResponse,
|
|
16
|
+
GitHubRestClient,
|
|
17
|
+
)
|
|
18
|
+
from basstler.github.comparison import Comparison
|
|
19
|
+
from basstler.github.constants import MergeableState
|
|
20
|
+
from basstler.github.exceptions import GitHubRequestFailed
|
|
21
|
+
from basstler.github.pull_request_record import (
|
|
22
|
+
PullRequestField,
|
|
23
|
+
PullRequestHead,
|
|
24
|
+
)
|
|
25
|
+
from basstler.github.pull_request_state import (
|
|
26
|
+
ForkLineage,
|
|
27
|
+
LivePullRequests,
|
|
28
|
+
PullRequestRecord,
|
|
29
|
+
PullRequestState,
|
|
30
|
+
)
|
|
31
|
+
from basstler.github.repository import PullRequestReference, Repository
|
|
32
|
+
from basstler.github.repository_details import RepositoryDetailsRead
|
|
33
|
+
from basstler.github.repository_access import GitHubRepository
|
|
34
|
+
from basstler.standard_streams import StandardStreamHandler
|
|
35
|
+
|
|
36
|
+
logger = StandardStreamHandler.logger_for(__name__)
|
|
37
|
+
"""
|
|
38
|
+
This module's logger, which reports a repository that cannot be read.
|
|
39
|
+
"""
|
|
40
|
+
|
|
41
|
+
READ_ACCESS_STATUSES = frozenset({HTTPStatus.NOT_FOUND, HTTPStatus.FORBIDDEN})
|
|
42
|
+
"""
|
|
43
|
+
What GitHub answers a token that is not granted a repository.
|
|
44
|
+
"""
|
|
45
|
+
|
|
46
|
+
# %% live pull request state
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
class PullRequestSource(ABC):
|
|
50
|
+
"""
|
|
51
|
+
Where the live state of the pull requests a plan references comes from.
|
|
52
|
+
"""
|
|
53
|
+
|
|
54
|
+
@abstractmethod
|
|
55
|
+
def pull_request(self, reference: PullRequestReference) -> PullRequestRecord | None:
|
|
56
|
+
"""
|
|
57
|
+
:param reference: The pull request to look up.
|
|
58
|
+
:return: Its live state, or ``None`` if the repository has no such pull request.
|
|
59
|
+
"""
|
|
60
|
+
|
|
61
|
+
@abstractmethod
|
|
62
|
+
def issue_url(self, repository: Repository, number: int) -> str | None:
|
|
63
|
+
"""
|
|
64
|
+
:param repository: The repository the issue or pull request is opened on.
|
|
65
|
+
:param number: Its number.
|
|
66
|
+
:return: Its web page, or ``None`` if the repository has no such number.
|
|
67
|
+
"""
|
|
68
|
+
|
|
69
|
+
def read_failure_of(self, repository: Repository) -> GitHubRequestFailed | None:
|
|
70
|
+
"""
|
|
71
|
+
:param repository: A repository a plan's items name.
|
|
72
|
+
:return: The refusal of the token's access to it, or ``None`` if it can be read;
|
|
73
|
+
``None`` unless the source finds otherwise.
|
|
74
|
+
"""
|
|
75
|
+
return None
|
|
76
|
+
|
|
77
|
+
def fork_lineage_of(self, repository: Repository) -> ForkLineage | None:
|
|
78
|
+
"""
|
|
79
|
+
:param repository: A repository that can be read.
|
|
80
|
+
:return: What it was forked from, or ``None`` if it is not a fork, or the source
|
|
81
|
+
cannot tell.
|
|
82
|
+
"""
|
|
83
|
+
return None
|
|
84
|
+
|
|
85
|
+
def upstream_pull_requests_of(
|
|
86
|
+
self, fork: Repository, lineage: ForkLineage
|
|
87
|
+
) -> dict[str, int]:
|
|
88
|
+
"""
|
|
89
|
+
:param fork: A repository that can be read and is a fork.
|
|
90
|
+
:param lineage: What it was forked from.
|
|
91
|
+
:return: The number of the open upstream pull request opened from each of its
|
|
92
|
+
branches; none when the source cannot tell.
|
|
93
|
+
"""
|
|
94
|
+
return {}
|
|
95
|
+
|
|
96
|
+
def live_pull_requests_of(
|
|
97
|
+
self, references: Iterable[PullRequestReference]
|
|
98
|
+
) -> LivePullRequests:
|
|
99
|
+
"""
|
|
100
|
+
:param references: The pull requests to read.
|
|
101
|
+
:return: The live state of each of them, and why each repository that cannot be
|
|
102
|
+
read cannot be; a number the repository does not have is left out.
|
|
103
|
+
"""
|
|
104
|
+
live_pull_requests = LivePullRequests()
|
|
105
|
+
for reference in references:
|
|
106
|
+
failure = self.read_failure_of(reference.repository)
|
|
107
|
+
if failure is not None:
|
|
108
|
+
live_pull_requests.read_failures[reference.repository] = failure
|
|
109
|
+
continue
|
|
110
|
+
repository = str(reference.repository)
|
|
111
|
+
lineage = self.fork_lineage_of(reference.repository)
|
|
112
|
+
if (
|
|
113
|
+
lineage is not None
|
|
114
|
+
and repository not in live_pull_requests.fork_lineages
|
|
115
|
+
):
|
|
116
|
+
live_pull_requests.fork_lineages[repository] = lineage
|
|
117
|
+
live_pull_requests.upstream_pull_requests[repository] = (
|
|
118
|
+
self.upstream_pull_requests_of(reference.repository, lineage)
|
|
119
|
+
)
|
|
120
|
+
record = self.pull_request(reference)
|
|
121
|
+
if record is not None:
|
|
122
|
+
live_pull_requests.pull_requests_by_repository.setdefault(
|
|
123
|
+
str(reference.repository), {}
|
|
124
|
+
)[str(reference.number)] = record
|
|
125
|
+
return live_pull_requests
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
@dataclass
|
|
129
|
+
class GitHubPullRequestSource(PullRequestSource):
|
|
130
|
+
"""
|
|
131
|
+
Pull request state read from the GitHub REST API, once per repository.
|
|
132
|
+
|
|
133
|
+
A repository's pull requests are listed in bulk on first use and kept, so a site
|
|
134
|
+
covering many plans costs a handful of requests rather than one per item. A number
|
|
135
|
+
the listing missed is read on its own. A repository whose details cannot be read is
|
|
136
|
+
not listed.
|
|
137
|
+
"""
|
|
138
|
+
|
|
139
|
+
client: GitHubFullClient
|
|
140
|
+
"""
|
|
141
|
+
How the requests reach GitHub.
|
|
142
|
+
"""
|
|
143
|
+
|
|
144
|
+
repository_details: dict[Repository, GitHubResponse] = field(default_factory=dict)
|
|
145
|
+
"""
|
|
146
|
+
The answer to the read of each repository's details asked about so far.
|
|
147
|
+
"""
|
|
148
|
+
|
|
149
|
+
listed_repositories: set[Repository] = field(default_factory=set)
|
|
150
|
+
"""
|
|
151
|
+
Every repository whose pull requests have been listed into :attr:`pull_requests`.
|
|
152
|
+
"""
|
|
153
|
+
|
|
154
|
+
pull_requests: dict[PullRequestReference, PullRequestRecord] = field(
|
|
155
|
+
default_factory=dict
|
|
156
|
+
)
|
|
157
|
+
"""
|
|
158
|
+
Every pull request read so far, listed or read on its own.
|
|
159
|
+
"""
|
|
160
|
+
|
|
161
|
+
reads_check_states: bool = True
|
|
162
|
+
"""
|
|
163
|
+
Whether the check state of an open pull request is read; off, it stays unknown.
|
|
164
|
+
"""
|
|
165
|
+
|
|
166
|
+
reads_mergeable_states: bool = False
|
|
167
|
+
"""
|
|
168
|
+
Whether the mergeable state of an open pull request out of draft is read, which
|
|
169
|
+
takes a request of its own; off, it stays unknown.
|
|
170
|
+
"""
|
|
171
|
+
|
|
172
|
+
reads_upstream_pull_requests: bool = True
|
|
173
|
+
"""
|
|
174
|
+
Whether a fork's upstream is listed for the open pull requests opened from the
|
|
175
|
+
fork's branches; off, none are found and the upstream is never called.
|
|
176
|
+
"""
|
|
177
|
+
|
|
178
|
+
@classmethod
|
|
179
|
+
def from_environment(
|
|
180
|
+
cls,
|
|
181
|
+
reads_check_states: bool = True,
|
|
182
|
+
reads_mergeable_states: bool = False,
|
|
183
|
+
reads_upstream_pull_requests: bool = True,
|
|
184
|
+
) -> GitHubPullRequestSource:
|
|
185
|
+
"""
|
|
186
|
+
:param reads_check_states: Whether open pull requests' check states are read.
|
|
187
|
+
:param reads_mergeable_states: Whether open pull requests' mergeable states are
|
|
188
|
+
read.
|
|
189
|
+
:param reads_upstream_pull_requests: Whether a fork's upstream pull requests are
|
|
190
|
+
read.
|
|
191
|
+
:return: A source authenticating with whichever credential the environment
|
|
192
|
+
carries.
|
|
193
|
+
"""
|
|
194
|
+
return cls(
|
|
195
|
+
client=GitHubRestClient(),
|
|
196
|
+
reads_check_states=reads_check_states,
|
|
197
|
+
reads_mergeable_states=reads_mergeable_states,
|
|
198
|
+
reads_upstream_pull_requests=reads_upstream_pull_requests,
|
|
199
|
+
)
|
|
200
|
+
|
|
201
|
+
def client_for(self, repository: Repository) -> GitHubRepository:
|
|
202
|
+
"""
|
|
203
|
+
:param repository: The repository to call.
|
|
204
|
+
:return: A client for it.
|
|
205
|
+
"""
|
|
206
|
+
return GitHubRepository(repository, self.client)
|
|
207
|
+
|
|
208
|
+
def read_failure_of(self, repository: Repository) -> GitHubRequestFailed | None:
|
|
209
|
+
"""
|
|
210
|
+
See :meth:`PullRequestSource.read_failure_of`: the refusal of the repository's
|
|
211
|
+
details, asked once and reported when refused.
|
|
212
|
+
|
|
213
|
+
:raises GitHubCallFailed: If the read fails other than by a refused access.
|
|
214
|
+
"""
|
|
215
|
+
if repository in self.repository_details:
|
|
216
|
+
return self.repository_details[repository].failure
|
|
217
|
+
details = self.client.attempt_get(f"/{repository.api_path}")
|
|
218
|
+
failure = details.failure
|
|
219
|
+
if failure is not None and not (
|
|
220
|
+
isinstance(failure, GitHubRequestFailed)
|
|
221
|
+
and failure.status in READ_ACCESS_STATUSES
|
|
222
|
+
):
|
|
223
|
+
raise failure
|
|
224
|
+
self.repository_details[repository] = details
|
|
225
|
+
if failure is not None:
|
|
226
|
+
logger.warning(
|
|
227
|
+
f"cannot read {repository}, so its pull requests are left out: "
|
|
228
|
+
f"{failure.error_message()}"
|
|
229
|
+
)
|
|
230
|
+
return failure
|
|
231
|
+
|
|
232
|
+
def fork_lineage_of(self, repository: Repository) -> ForkLineage | None:
|
|
233
|
+
if self.read_failure_of(repository) is not None:
|
|
234
|
+
return None
|
|
235
|
+
return (
|
|
236
|
+
RepositoryDetailsRead(repository)
|
|
237
|
+
.parse(self.repository_details[repository].body)
|
|
238
|
+
.lineage
|
|
239
|
+
)
|
|
240
|
+
|
|
241
|
+
def upstream_pull_requests_of(
|
|
242
|
+
self, fork: Repository, lineage: ForkLineage
|
|
243
|
+
) -> dict[str, int]:
|
|
244
|
+
if not self.reads_upstream_pull_requests:
|
|
245
|
+
return {}
|
|
246
|
+
return PullRequestHead.numbers_by_branch(
|
|
247
|
+
self.client_for(lineage.upstream_repository).open_pull_requests(),
|
|
248
|
+
fork.full_name,
|
|
249
|
+
)
|
|
250
|
+
|
|
251
|
+
def pull_request(self, reference: PullRequestReference) -> PullRequestRecord | None:
|
|
252
|
+
record = self.listed_or_read(reference)
|
|
253
|
+
if record is None:
|
|
254
|
+
return None
|
|
255
|
+
if self.reads_check_states and record.has_unread_checks:
|
|
256
|
+
record.check_state = self.client_for(reference.repository).check_state(
|
|
257
|
+
record.head_commit
|
|
258
|
+
)
|
|
259
|
+
if self.reads_mergeable_states and record.has_unread_mergeable_state:
|
|
260
|
+
record.mergeable_state = self.mergeable_state(reference)
|
|
261
|
+
if record.landed_upstream is None:
|
|
262
|
+
record.landed_upstream = self.landed_upstream(reference.repository, record)
|
|
263
|
+
return record
|
|
264
|
+
|
|
265
|
+
def mergeable_state(self, reference: PullRequestReference) -> MergeableState | None:
|
|
266
|
+
"""
|
|
267
|
+
:param reference: An open pull request.
|
|
268
|
+
:return: What reading it on its own says about its conflicts - a listing leaves
|
|
269
|
+
that out - or ``None`` when it cannot be read or GitHub reports none.
|
|
270
|
+
"""
|
|
271
|
+
api_record = self.read_if_present(
|
|
272
|
+
f"/{reference.repository.pull_request_path(reference.number)}"
|
|
273
|
+
)
|
|
274
|
+
if api_record is None:
|
|
275
|
+
return None
|
|
276
|
+
return PullRequestRecord.from_api(api_record).mergeable_state
|
|
277
|
+
|
|
278
|
+
def landed_upstream(
|
|
279
|
+
self, repository: Repository, record: PullRequestRecord
|
|
280
|
+
) -> bool | None:
|
|
281
|
+
"""
|
|
282
|
+
Ask GitHub whether an open pull request's work is already in the upstream.
|
|
283
|
+
|
|
284
|
+
:param repository: The repository the pull request is opened on.
|
|
285
|
+
:param record: The pull request.
|
|
286
|
+
:return: Whether every commit of its head is in the upstream's default branch
|
|
287
|
+
and it has a commit beyond its own base, which a branch with nothing of its
|
|
288
|
+
own does not; ``None`` when that is not asked of it, or GitHub cannot say.
|
|
289
|
+
"""
|
|
290
|
+
lineage = self.fork_lineage_of(repository)
|
|
291
|
+
if (
|
|
292
|
+
lineage is None
|
|
293
|
+
or record.state is not PullRequestState.OPEN
|
|
294
|
+
or record.head_commit is None
|
|
295
|
+
or record.base is None
|
|
296
|
+
):
|
|
297
|
+
return None
|
|
298
|
+
in_upstream = self.comparison(
|
|
299
|
+
repository,
|
|
300
|
+
f"{lineage.upstream_repository.owner}:{lineage.upstream_default_branch}",
|
|
301
|
+
record.head_commit,
|
|
302
|
+
)
|
|
303
|
+
if in_upstream is None:
|
|
304
|
+
return None
|
|
305
|
+
if not in_upstream.head_is_contained_in_base:
|
|
306
|
+
return False
|
|
307
|
+
beyond_base = self.comparison(repository, record.base, record.head_commit)
|
|
308
|
+
if beyond_base is None:
|
|
309
|
+
return None
|
|
310
|
+
return beyond_base.ahead_by > 0
|
|
311
|
+
|
|
312
|
+
def comparison(
|
|
313
|
+
self, repository: Repository, base: str, head: str
|
|
314
|
+
) -> Comparison | None:
|
|
315
|
+
"""
|
|
316
|
+
:param repository: The repository holding the head.
|
|
317
|
+
:param base: What the head is compared with.
|
|
318
|
+
:param head: The commit compared.
|
|
319
|
+
:return: GitHub's comparison, ``None`` when it cannot be read, which is
|
|
320
|
+
reported.
|
|
321
|
+
"""
|
|
322
|
+
path = f"/{repository.compare_path(base)}...{head}"
|
|
323
|
+
answer = self.client.attempt_get(path)
|
|
324
|
+
if answer.failure is not None:
|
|
325
|
+
logger.warning(
|
|
326
|
+
f"cannot compare {head} with {base} in {repository} ({path}), so it "
|
|
327
|
+
f"is not known whether its pull request has landed: "
|
|
328
|
+
f"{answer.failure.error_message()}"
|
|
329
|
+
)
|
|
330
|
+
return None
|
|
331
|
+
return Comparison.from_json(answer.body)
|
|
332
|
+
|
|
333
|
+
def listed_or_read(
|
|
334
|
+
self, reference: PullRequestReference
|
|
335
|
+
) -> PullRequestRecord | None:
|
|
336
|
+
"""
|
|
337
|
+
:param reference: The pull request to look up.
|
|
338
|
+
:return: Its state as its repository's listing gave it, read on its own when the
|
|
339
|
+
listing missed it, or ``None`` if the repository has no such pull request or
|
|
340
|
+
cannot be read.
|
|
341
|
+
"""
|
|
342
|
+
if self.read_failure_of(reference.repository) is not None:
|
|
343
|
+
return None
|
|
344
|
+
self.list_pull_requests_of(reference.repository)
|
|
345
|
+
if reference not in self.pull_requests:
|
|
346
|
+
api_record = self.read_if_present(
|
|
347
|
+
f"/{reference.repository.pull_request_path(reference.number)}"
|
|
348
|
+
)
|
|
349
|
+
if api_record is None:
|
|
350
|
+
return None
|
|
351
|
+
self.pull_requests[reference] = PullRequestRecord.from_api(api_record)
|
|
352
|
+
return self.pull_requests[reference]
|
|
353
|
+
|
|
354
|
+
def issue_url(self, repository: Repository, number: int) -> str | None:
|
|
355
|
+
"""
|
|
356
|
+
See :meth:`PullRequestSource.issue_url`; ``None`` also when the repository
|
|
357
|
+
cannot be read.
|
|
358
|
+
"""
|
|
359
|
+
if self.read_failure_of(repository) is not None:
|
|
360
|
+
return None
|
|
361
|
+
api_record = self.read_if_present(f"/{repository.issue_path(number)}")
|
|
362
|
+
if api_record is None:
|
|
363
|
+
return None
|
|
364
|
+
return PullRequestField.HTML_URL.read(api_record, number)
|
|
365
|
+
|
|
366
|
+
def list_pull_requests_of(self, repository: Repository) -> None:
|
|
367
|
+
"""
|
|
368
|
+
Read every pull request on a repository into :attr:`pull_requests`, once.
|
|
369
|
+
|
|
370
|
+
:param repository: The repository to list.
|
|
371
|
+
"""
|
|
372
|
+
if repository in self.listed_repositories:
|
|
373
|
+
return
|
|
374
|
+
for api_record in self.client_for(repository).all_pull_requests():
|
|
375
|
+
number = PullRequestField.NUMBER.read(api_record)
|
|
376
|
+
self.pull_requests[PullRequestReference(repository, number)] = (
|
|
377
|
+
PullRequestRecord.from_api(api_record)
|
|
378
|
+
)
|
|
379
|
+
self.listed_repositories.add(repository)
|
|
380
|
+
|
|
381
|
+
def read_if_present(self, path: str) -> Mapping[str, Any] | None:
|
|
382
|
+
"""
|
|
383
|
+
Make one read, treating an absent resource as an answer rather than a failure.
|
|
384
|
+
|
|
385
|
+
:param path: The resource's REST path.
|
|
386
|
+
:return: The response, or ``None`` if the API answered that it does not exist.
|
|
387
|
+
:raises GitHubRequestFailed: If the API refused the read for any other reason.
|
|
388
|
+
"""
|
|
389
|
+
answer = self.client.attempt_get(path)
|
|
390
|
+
if (
|
|
391
|
+
isinstance(answer.failure, GitHubRequestFailed)
|
|
392
|
+
and answer.failure.status == HTTPStatus.NOT_FOUND
|
|
393
|
+
):
|
|
394
|
+
return None
|
|
395
|
+
return answer.raise_if_failed()
|