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.
Files changed (60) hide show
  1. basstler/github/__init__.py +0 -0
  2. basstler/github/actions_budget.py +428 -0
  3. basstler/github/actions_secret.py +25 -0
  4. basstler/github/actions_settings.py +162 -0
  5. basstler/github/actions_usage.py +297 -0
  6. basstler/github/basstler_project.py +75 -0
  7. basstler/github/branch_pull_request.py +24 -0
  8. basstler/github/client.py +452 -0
  9. basstler/github/comparison.py +60 -0
  10. basstler/github/constants.py +197 -0
  11. basstler/github/credential.py +85 -0
  12. basstler/github/exceptions.py +264 -0
  13. basstler/github/file_proposal.py +440 -0
  14. basstler/github/fork_sync.py +44 -0
  15. basstler/github/git_objects.py +57 -0
  16. basstler/github/graphql.py +101 -0
  17. basstler/github/issue.py +221 -0
  18. basstler/github/label.py +78 -0
  19. basstler/github/login_lending.py +46 -0
  20. basstler/github/main_failure.py +289 -0
  21. basstler/github/permission_level.py +33 -0
  22. basstler/github/pull_request.py +74 -0
  23. basstler/github/pull_request_changes.py +141 -0
  24. basstler/github/pull_request_description.py +145 -0
  25. basstler/github/pull_request_ends.py +58 -0
  26. basstler/github/pull_request_form.py +136 -0
  27. basstler/github/pull_request_models.py +321 -0
  28. basstler/github/pull_request_record.py +369 -0
  29. basstler/github/pull_request_source.py +395 -0
  30. basstler/github/pull_request_state.py +437 -0
  31. basstler/github/queries/pull_request_for_branch.graphql +17 -0
  32. basstler/github/queries/review_threads_page.graphql +72 -0
  33. basstler/github/query_documents.py +37 -0
  34. basstler/github/release_version.py +565 -0
  35. basstler/github/remote.py +36 -0
  36. basstler/github/repository.py +532 -0
  37. basstler/github/repository_access.py +459 -0
  38. basstler/github/repository_attachment.py +95 -0
  39. basstler/github/repository_details.py +98 -0
  40. basstler/github/repository_option.py +43 -0
  41. basstler/github/repository_resources.py +133 -0
  42. basstler/github/rest_models.py +353 -0
  43. basstler/github/review_models.py +223 -0
  44. basstler/github/run_listing.py +148 -0
  45. basstler/github/stack_configuration.py +178 -0
  46. basstler/github/states.py +257 -0
  47. basstler/github/token_form.py +360 -0
  48. basstler/github/tooling_labels.py +83 -0
  49. basstler/github/user_steps.py +170 -0
  50. basstler/github/web_form.py +56 -0
  51. basstler/github/web_page.py +33 -0
  52. basstler/github/wire_form.py +159 -0
  53. basstler/github/workflow_run.py +126 -0
  54. basstler/github/workflows.py +561 -0
  55. basstler/templates/actions_budget.py.jinja +26 -0
  56. basstler_github-4.2.0.dist-info/METADATA +16 -0
  57. basstler_github-4.2.0.dist-info/RECORD +60 -0
  58. basstler_github-4.2.0.dist-info/WHEEL +4 -0
  59. basstler_github-4.2.0.dist-info/licenses/LICENSE +202 -0
  60. 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()