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,437 @@
1
+ """
2
+ A pull request's live GitHub state, as ``pr_data.json`` records it, and the state an
3
+ item is classified into from it.
4
+
5
+ pr_data.json shape: {"<owner>/<repo>": {"<pr_number>": {"state": "open"| "closed",
6
+ "draft": bool, "merged_at": str|null, "labels": [str, ...], "body": str|null}}} - one entry per pull
7
+ request number referenced by any item. A closed entry must carry merged_at explicitly,
8
+ null included; omitting it is rejected rather than read as unmerged. See pr-data-
9
+ fetching.md for how a session should gather it.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import dataclasses
15
+ from dataclasses import dataclass, field
16
+ from datetime import datetime
17
+ from enum import StrEnum
18
+ from typing import Any
19
+
20
+ from basstler.github.constants import MergeableState
21
+ from basstler.github.exceptions import GitHubRequestFailed
22
+ from basstler.github.pull_request_description import PullRequestDescription
23
+ from basstler.github.pull_request_record import (
24
+ PullRequestField,
25
+ PullRequestHead,
26
+ )
27
+ from basstler.github.pull_request_record import (
28
+ PullRequestRecord as PullRequestAPIRecord,
29
+ )
30
+ from basstler.github.repository import Repository
31
+ from basstler.github.states import CombinedCheckState
32
+ from basstler.github.tooling_labels import GitHubLabel
33
+
34
+ # %% classified state
35
+
36
+
37
+ class LiveState(StrEnum):
38
+ """
39
+ An item's live GitHub pull request state, classified fresh on every run.
40
+
41
+ :attr:`NO_PULL_REQUEST` is a real member, not represented as ``None``: "this item
42
+ has no pull request yet" is itself a meaningful, displayable state (with its own
43
+ label and CSS class) rather than an absence value every caller would otherwise have
44
+ to special-case around the enum.
45
+ """
46
+
47
+ NO_PULL_REQUEST = "none"
48
+ MERGED = "merged"
49
+ OPEN_DRAFT = "open_draft"
50
+ OPEN_READY = "open_ready"
51
+ CLOSED_UNMERGED = "closed_unmerged"
52
+ NOT_FOUND = "not_found"
53
+ REPOSITORY_UNREADABLE = "repository_unreadable"
54
+
55
+ @property
56
+ def display_label(self) -> str:
57
+ """
58
+ The human-readable label shown on the plan site for this state.
59
+ """
60
+ match self:
61
+ case LiveState.NO_PULL_REQUEST:
62
+ return "No pull request yet"
63
+ case LiveState.MERGED:
64
+ return "Merged"
65
+ case LiveState.OPEN_DRAFT:
66
+ return "Open · Draft"
67
+ case LiveState.OPEN_READY:
68
+ return "Open · Ready"
69
+ case LiveState.CLOSED_UNMERGED:
70
+ return "Closed (unmerged)"
71
+ case LiveState.NOT_FOUND:
72
+ return "Not found on GitHub"
73
+ case LiveState.REPOSITORY_UNREADABLE:
74
+ return "Repository unreadable"
75
+
76
+ @classmethod
77
+ def classify(
78
+ cls,
79
+ pull_request_number: int | None,
80
+ repository: str,
81
+ live_pull_requests: LivePullRequests,
82
+ ) -> LiveState:
83
+ """
84
+ Classify one item's live GitHub state from its pull request number and
85
+ repository.
86
+
87
+ :param pull_request_number: The item's tracked pull request number, or ``None``
88
+ if it has no pull request yet.
89
+ :param repository: The ``"owner/repo"`` to look the pull request up under.
90
+ :param live_pull_requests: What was read of every repository referenced by the
91
+ plan's items.
92
+ :return: The classified state.
93
+ """
94
+ if pull_request_number is None:
95
+ return LiveState.NO_PULL_REQUEST
96
+ if Repository.parse(repository) in live_pull_requests.read_failures:
97
+ return LiveState.REPOSITORY_UNREADABLE
98
+ repository_pull_requests = live_pull_requests.pull_requests_by_repository.get(
99
+ repository, {}
100
+ )
101
+ pull_request = repository_pull_requests.get(str(pull_request_number))
102
+ if pull_request is None:
103
+ return LiveState.NOT_FOUND
104
+ if pull_request.was_merged:
105
+ return LiveState.MERGED
106
+ if pull_request.state is PullRequestState.CLOSED:
107
+ return LiveState.CLOSED_UNMERGED
108
+ if pull_request.draft:
109
+ return LiveState.OPEN_DRAFT
110
+ return LiveState.OPEN_READY
111
+
112
+
113
+ class PullRequestState(StrEnum):
114
+ """
115
+ GitHub's own coarse-grained pull request state, as returned by its API.
116
+ """
117
+
118
+ OPEN = "open"
119
+ CLOSED = "closed"
120
+
121
+
122
+ # %% pr_data.json records
123
+
124
+
125
+ class MissingMergeTimestampError(ValueError):
126
+ """
127
+ Raised when a closed pull request's ``pr_data.json`` entry omits the ``merged_at``
128
+ key altogether, which leaves no way to tell a merged pull request from one closed
129
+ unmerged.
130
+ """
131
+
132
+
133
+ @dataclass
134
+ class PullRequestRecord:
135
+ """
136
+ The live GitHub state of one pull request, as gathered by the skill.
137
+ """
138
+
139
+ state: PullRequestState
140
+ """
141
+ GitHub's own coarse-grained state.
142
+ """
143
+
144
+ draft: bool = False
145
+ """
146
+ Whether the pull request is currently a draft.
147
+ """
148
+
149
+ merged_at: datetime | None = None
150
+ """
151
+ The pull request's merge timestamp, or ``None`` if GitHub never recorded a merge
152
+ through its own merge API.
153
+ """
154
+
155
+ labels: list[str] = field(default_factory=list)
156
+ """
157
+ The pull request's raw GitHub labels, exactly as GitHub reports them.
158
+
159
+ Kept as ``list[str]`` rather than ``list[GitHubLabel]``: a real pull request can carry
160
+ labels this codebase has no reason to know about (other.
161
+
162
+ automation's own labels, GitHub's defaults), so this field must tolerate
163
+ anything - see :attr:`identified_labels` for the subset this codebase
164
+ actually recognizes. Needed because :attr:`merged_at` alone misses a real
165
+ case in this repo's history: a pull request merged out-of-band (its
166
+ branch pushed directly, then the pull request closed by hand rather than
167
+ through GitHub's merge button) never gets ``merged_at`` set, so the
168
+ closer manually adds the :attr:`GitHubLabel.MERGED` label to record
169
+ what actually happened - see :meth:`was_merged`.
170
+ """
171
+
172
+ upstream_link: str | None = None
173
+ """
174
+ The URL of the upstream pull request a maintenance pass linked in the pull request's
175
+ description, ``None`` while none is linked.
176
+ """
177
+
178
+ head_commit: str | None = None
179
+ """
180
+ The commit the pull request's head branch points at, ``None`` when the source it was
181
+ read from does not say.
182
+ """
183
+
184
+ assignees: list[str] = field(default_factory=list)
185
+ """
186
+ The logins of the accounts the pull request is assigned to.
187
+ """
188
+
189
+ base: str | None = None
190
+ """
191
+ The branch the pull request merges into, ``None`` when the source it was read from
192
+ does not say.
193
+ """
194
+
195
+ title: str | None = None
196
+ """
197
+ The pull request's title, ``None`` when the source it was read from does not say.
198
+ """
199
+
200
+ check_state: CombinedCheckState | None = None
201
+ """
202
+ The verdict over the checks reported on :attr:`head_commit`, ``None`` while they
203
+ were not read.
204
+ """
205
+
206
+ landed_upstream: bool | None = None
207
+ """
208
+ Whether GitHub's comparison shows every commit of the head in the upstream's default
209
+ branch and some commit beyond the pull request's own base; ``None`` while it was not
210
+ read.
211
+ """
212
+
213
+ mergeable_state: MergeableState | None = None
214
+ """
215
+ GitHub's verdict on whether the pull request conflicts with its base, ``None`` while
216
+ it was not read.
217
+ """
218
+
219
+ @property
220
+ def identified_labels(self) -> frozenset[GitHubLabel]:
221
+ """The subset of :attr:`labels` that match a known
222
+ :class:`GitHubLabel` - any other raw label this pull request
223
+ happens to carry is silently excluded, not an error, since
224
+ :attr:`labels` is deliberately not limited to labels this codebase
225
+ recognizes."""
226
+ known_values = {member.value for member in GitHubLabel}
227
+ return frozenset(
228
+ GitHubLabel(label) for label in self.labels if label in known_values
229
+ )
230
+
231
+ @classmethod
232
+ def from_mapping(cls, data: dict[str, Any]) -> PullRequestRecord:
233
+ """
234
+ Build a record from one entry of ``pr_data.json``.
235
+
236
+ A closed entry must carry ``merged_at`` explicitly, ``null`` included: a
237
+ gatherer that never requested the field would otherwise be indistinguishable
238
+ from GitHub reporting no merge, silently turning every merged pull request into
239
+ a closed-unmerged one.
240
+
241
+ :raises MissingMergeTimestampError: If a closed entry omits ``merged_at``.
242
+ """
243
+ state = PullRequestState(data[PullRequestField.STATE.key])
244
+ if (
245
+ state is PullRequestState.CLOSED
246
+ and PullRequestField.MERGED_AT.key not in data
247
+ ):
248
+ raise MissingMergeTimestampError(
249
+ "a closed pull request entry must carry merged_at (null included)"
250
+ )
251
+ merged_at = data.get(PullRequestField.MERGED_AT.key)
252
+ return cls(
253
+ state=state,
254
+ draft=data.get(PullRequestField.DRAFT.key, False),
255
+ merged_at=datetime.fromisoformat(merged_at) if merged_at else None,
256
+ labels=list(data.get(PullRequestField.LABELS.key) or []),
257
+ upstream_link=PullRequestDescription(
258
+ data.get(PullRequestField.BODY.key) or ""
259
+ ).upstream_link,
260
+ )
261
+
262
+ @classmethod
263
+ def from_api(cls, api_record: PullRequestAPIRecord) -> PullRequestRecord:
264
+ """
265
+ Read one pull request object as the REST pulls API answers it.
266
+
267
+ :param api_record: The pull request, as the API describes it.
268
+ :return: The fields the plan site classifies it by.
269
+ """
270
+ number = PullRequestField.NUMBER.read(api_record)
271
+ record = cls.from_mapping(
272
+ {
273
+ pull_request_field.key: pull_request_field.read(api_record, number)
274
+ for pull_request_field in (
275
+ PullRequestField.STATE,
276
+ PullRequestField.DRAFT,
277
+ PullRequestField.MERGED_AT,
278
+ PullRequestField.LABELS,
279
+ PullRequestField.BODY,
280
+ )
281
+ }
282
+ )
283
+ mergeable_state = PullRequestField.MERGEABLE_STATE.read(api_record, number)
284
+ return dataclasses.replace(
285
+ record,
286
+ mergeable_state=(
287
+ None if mergeable_state is None else MergeableState(mergeable_state)
288
+ ),
289
+ head_commit=PullRequestHead.commit_in(api_record),
290
+ assignees=PullRequestField.ASSIGNEES.read(api_record, number) or [],
291
+ base=PullRequestField.BASE.read(api_record, number),
292
+ title=PullRequestField.TITLE.read(api_record, number),
293
+ )
294
+
295
+ @property
296
+ def has_unread_checks(self) -> bool:
297
+ """
298
+ Whether the pull request is open at a known commit whose checks were not read.
299
+ """
300
+ return (
301
+ self.state is PullRequestState.OPEN
302
+ and self.head_commit is not None
303
+ and self.check_state is None
304
+ )
305
+
306
+ @property
307
+ def has_unread_mergeable_state(self) -> bool:
308
+ """
309
+ Whether the pull request is open and out of draft with its mergeable state not
310
+ read.
311
+ """
312
+ return (
313
+ self.state is PullRequestState.OPEN
314
+ and not self.draft
315
+ and self.mergeable_state is None
316
+ )
317
+
318
+ @property
319
+ def was_merged(self) -> bool:
320
+ """Whether this pull request's changes actually landed - GitHub's own
321
+ :attr:`merged_at`, its commits found in the upstream by
322
+ :attr:`landed_upstream`, or (for an out-of-band merge GitHub never
323
+ recorded) the manually-applied :attr:`GitHubLabel.MERGED`
324
+ label."""
325
+ return (
326
+ self.merged_at is not None
327
+ or self.landed_upstream is True
328
+ or GitHubLabel.MERGED in self.identified_labels
329
+ )
330
+
331
+ @classmethod
332
+ def parse_by_repository(
333
+ cls,
334
+ raw_pull_request_data: dict[str, Any],
335
+ ) -> PullRequestsByRepository:
336
+ """
337
+ Parse ``pr_data.json``'s raw JSON into :class:`PullRequestRecord`\\ s.
338
+
339
+ :param raw_pull_request_data: The parsed JSON, keyed by ``"owner/repo"``
340
+ then by pull request number as a string - see the module docstring for the
341
+ exact shape.
342
+ :raises MalformedPullRequestDataError: If the data is not keyed by repository
343
+ then by number, or any entry can't be parsed into a
344
+ :class:`PullRequestRecord`.
345
+ :return: The same structure, with each leaf mapping parsed into a
346
+ :class:`PullRequestRecord`.
347
+ """
348
+ pull_requests_by_repository: PullRequestsByRepository = {}
349
+ for repository, pull_requests in raw_pull_request_data.items():
350
+ if not Repository.is_full_name(repository) or not isinstance(
351
+ pull_requests, dict
352
+ ):
353
+ raise MalformedPullRequestDataError(
354
+ f"top-level key {repository!r} does not map an 'owner/repo' to its "
355
+ 'pull requests: pr_data.json is {"<owner>/<repo>": '
356
+ '{"<pr_number>": {...}}}'
357
+ )
358
+ pull_requests_by_repository[repository] = {}
359
+ for pull_request_number, record in pull_requests.items():
360
+ if not isinstance(record, dict):
361
+ raise MalformedPullRequestDataError(
362
+ f"{repository}#{pull_request_number}: expected the pull "
363
+ f"request's fields, got {record!r}"
364
+ )
365
+ try:
366
+ pull_requests_by_repository[repository][pull_request_number] = (
367
+ PullRequestRecord.from_mapping(record)
368
+ )
369
+ except (KeyError, ValueError) as error:
370
+ raise MalformedPullRequestDataError(
371
+ f"{repository}#{pull_request_number}: {error}"
372
+ ) from error
373
+ return pull_requests_by_repository
374
+
375
+
376
+ class MalformedPullRequestDataError(ValueError):
377
+ """Raised when one entry of ``pr_data.json`` cannot be parsed into a
378
+ :class:`PullRequestRecord` - a missing or invalid ``state`` field, or an
379
+ unparsable ``merged_at`` timestamp."""
380
+
381
+
382
+ PullRequestsByRepository = dict[str, dict[str, PullRequestRecord]]
383
+
384
+
385
+ # %% what was read of a plan's repositories
386
+
387
+
388
+ @dataclass(frozen=True)
389
+ class ForkLineage:
390
+ """
391
+ The repository a fork was forked from, and the default branch of each.
392
+ """
393
+
394
+ upstream_repository: Repository
395
+ """
396
+ The repository the fork was forked from.
397
+ """
398
+
399
+ upstream_default_branch: str
400
+ """
401
+ The upstream's default branch.
402
+ """
403
+
404
+ fork_default_branch: str
405
+ """
406
+ The fork's own default branch.
407
+ """
408
+
409
+
410
+ @dataclass
411
+ class LivePullRequests:
412
+ """
413
+ The live state of a plan's pull requests, and the refusal of each repository holding
414
+ them that the token is not granted.
415
+ """
416
+
417
+ pull_requests_by_repository: PullRequestsByRepository = field(default_factory=dict)
418
+ """
419
+ Live pull request state for every repository that could be read.
420
+ """
421
+
422
+ read_failures: dict[Repository, GitHubRequestFailed] = field(default_factory=dict)
423
+ """
424
+ The refusal of the token's access to each repository whose pull requests could not
425
+ be read.
426
+ """
427
+
428
+ fork_lineages: dict[str, ForkLineage] = field(default_factory=dict)
429
+ """
430
+ The upstream of each readable repository that is a fork, by ``"owner/repo"``.
431
+ """
432
+
433
+ upstream_pull_requests: dict[str, dict[str, int]] = field(default_factory=dict)
434
+ """
435
+ The number of the open upstream pull request opened from each branch, by the
436
+ ``"owner/repo"`` of the fork the branch is in.
437
+ """
@@ -0,0 +1,17 @@
1
+ query PullRequestForBranch($owner: String!, $name: String!, $headRefName: String!) {
2
+ repository(owner: $owner, name: $name) {
3
+ pullRequests(
4
+ headRefName: $headRefName
5
+ first: 20
6
+ orderBy: { field: CREATED_AT, direction: DESC }
7
+ ) {
8
+ nodes {
9
+ number
10
+ state
11
+ headRepositoryOwner {
12
+ login
13
+ }
14
+ }
15
+ }
16
+ }
17
+ }
@@ -0,0 +1,72 @@
1
+ query ReviewThreadsPage(
2
+ $owner: String!
3
+ $name: String!
4
+ $number: Int!
5
+ $threadCursor: String
6
+ ) {
7
+ repository(owner: $owner, name: $name) {
8
+ pullRequest(number: $number) {
9
+ number
10
+ title
11
+ url
12
+ commits(last: 1) {
13
+ nodes {
14
+ commit {
15
+ statusCheckRollup {
16
+ state
17
+ contexts(first: 100) {
18
+ nodes {
19
+ __typename
20
+ ... on CheckRun {
21
+ name
22
+ conclusion
23
+ detailsUrl
24
+ }
25
+ ... on StatusContext {
26
+ context
27
+ state
28
+ targetUrl
29
+ }
30
+ }
31
+ }
32
+ }
33
+ }
34
+ }
35
+ }
36
+ reviews(first: 100) {
37
+ nodes {
38
+ author {
39
+ login
40
+ }
41
+ state
42
+ body
43
+ submittedAt
44
+ }
45
+ }
46
+ reviewThreads(first: 100, after: $threadCursor) {
47
+ pageInfo {
48
+ hasNextPage
49
+ endCursor
50
+ }
51
+ nodes {
52
+ id
53
+ isResolved
54
+ isOutdated
55
+ path
56
+ line
57
+ comments(first: 100) {
58
+ nodes {
59
+ databaseId
60
+ author {
61
+ login
62
+ }
63
+ body
64
+ createdAt
65
+ url
66
+ }
67
+ }
68
+ }
69
+ }
70
+ }
71
+ }
72
+ }
@@ -0,0 +1,37 @@
1
+ """
2
+ The GraphQL documents the upstream reviews are read with, and their variables.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from enum import StrEnum
8
+
9
+ from basstler.locations import PackageLocation
10
+ from basstler.text_file import TextFile
11
+
12
+ # %% the query documents
13
+
14
+
15
+ class QueryVariable(StrEnum):
16
+ """
17
+ The variables the query documents declare.
18
+ """
19
+
20
+ OWNER = "owner"
21
+ NAME = "name"
22
+ HEAD_REF_NAME = "headRefName"
23
+ NUMBER = "number"
24
+ THREAD_CURSOR = "threadCursor"
25
+
26
+
27
+ class GraphQLDocument(StrEnum):
28
+ """
29
+ The query documents, stored as ``.graphql`` files beside this script.
30
+ """
31
+
32
+ PULL_REQUEST_FOR_BRANCH = "pull_request_for_branch"
33
+ REVIEW_THREADS_PAGE = "review_threads_page"
34
+
35
+ def read(self) -> str:
36
+ """:return: The document's text."""
37
+ return TextFile(PackageLocation.QUERIES / f"{self}.graphql").read()