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,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
+ """