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,221 @@
1
+ """
2
+ A GitHub issue and its comments, and the requests that open, comment on, close and
3
+ list issues.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from abc import ABC
9
+ from dataclasses import asdict, dataclass
10
+ from enum import StrEnum
11
+ from typing import Annotated, Any, Literal
12
+ from urllib.parse import urlencode
13
+
14
+ from pydantic import Field
15
+
16
+ from basstler.class_property import classproperty
17
+ from basstler.github.client import HttpMethod, RepositoryWrite
18
+ from basstler.json_model import JSONModel
19
+
20
+ # %% the values an issue's state is written in
21
+
22
+
23
+ class IssueState(StrEnum):
24
+ """
25
+ The states an issue is listed or set in.
26
+ """
27
+
28
+ OPEN = "open"
29
+ CLOSED = "closed"
30
+
31
+
32
+ class ClosingReason(StrEnum):
33
+ """
34
+ Why an issue is closed.
35
+ """
36
+
37
+ COMPLETED = "completed"
38
+ """
39
+ What the issue asked for is done.
40
+ """
41
+
42
+
43
+ # %% an issue as GitHub returns it
44
+
45
+
46
+ @dataclass(frozen=True)
47
+ class Issue(JSONModel):
48
+ """
49
+ One issue of a repository.
50
+ """
51
+
52
+ number: int
53
+ """
54
+ Its number in the repository.
55
+ """
56
+
57
+ url: str
58
+ """
59
+ Its page on GitHub.
60
+ """
61
+
62
+ @classmethod
63
+ def from_json(cls, data: dict[str, Any]) -> Issue:
64
+ return cls(data["number"], data["html_url"])
65
+
66
+
67
+ # %% what is sent to GitHub
68
+
69
+
70
+ class NewIssue(RepositoryWrite):
71
+ """
72
+ An issue to open.
73
+ """
74
+
75
+ title: str
76
+ """
77
+ The issue's title.
78
+ """
79
+
80
+ body: str
81
+ """
82
+ The issue's description, in Markdown.
83
+ """
84
+
85
+ labels: list[str]
86
+ """
87
+ The names of the labels it is opened with.
88
+ """
89
+
90
+ @classproperty
91
+ def method(cls) -> HttpMethod:
92
+ return HttpMethod.POST
93
+
94
+ @property
95
+ def path(self) -> str:
96
+ return self.repository.issues_path
97
+
98
+
99
+ class IssueWrite(RepositoryWrite, ABC):
100
+ """
101
+ A change to one issue or pull request, which GitHub numbers alike.
102
+ """
103
+
104
+ number: Annotated[int, Field(exclude=True)]
105
+ """
106
+ The issue's or pull request's number in the repository.
107
+ """
108
+
109
+
110
+ class IssueComment(IssueWrite):
111
+ """
112
+ A comment on an issue or pull request, as it is posted.
113
+ """
114
+
115
+ body: str
116
+ """
117
+ The comment's Markdown.
118
+ """
119
+
120
+ @classproperty
121
+ def method(cls) -> HttpMethod:
122
+ return HttpMethod.POST
123
+
124
+ @property
125
+ def path(self) -> str:
126
+ return self.repository.issue_comments_path(self.number)
127
+
128
+
129
+ @dataclass(frozen=True)
130
+ class PostedIssueComment(JSONModel):
131
+ """
132
+ A comment GitHub has recorded, with who posted it and when.
133
+ """
134
+
135
+ body: str
136
+ """
137
+ The comment's Markdown.
138
+ """
139
+
140
+ author_login: str
141
+ """
142
+ The GitHub login of whoever posted the comment.
143
+ """
144
+
145
+ created_at: str
146
+ """
147
+ When the comment was posted, as GitHub's ISO 8601 timestamp.
148
+ """
149
+
150
+ @classmethod
151
+ def from_json(cls, data: dict[str, Any]) -> PostedIssueComment:
152
+ return cls(data["body"], data["user"]["login"], data["created_at"])
153
+
154
+ def to_json(self) -> dict[str, Any]:
155
+ """
156
+ :return: The comment in the shape GitHub's issue-comments API returns it.
157
+ """
158
+ return {
159
+ "body": self.body,
160
+ "user": {"login": self.author_login},
161
+ "created_at": self.created_at,
162
+ }
163
+
164
+ def formatted(self) -> str:
165
+ """
166
+ :return: The comment as a ``[<login> @ <created_at>]`` line, then its body.
167
+ """
168
+ return f"[{self.author_login} @ {self.created_at}]\n{self.body}"
169
+
170
+
171
+ class IssueClosing(IssueWrite):
172
+ """
173
+ The closing of an issue.
174
+ """
175
+
176
+ closing_reason: Annotated[ClosingReason | None, Field(alias="state_reason")] = None
177
+ """
178
+ Why it is closed, or ``None`` to leave the reason unset.
179
+ """
180
+
181
+ state: Literal[IssueState.CLOSED] = IssueState.CLOSED
182
+ """
183
+ The state the issue is set to.
184
+ """
185
+
186
+ @classproperty
187
+ def method(cls) -> HttpMethod:
188
+ return HttpMethod.PATCH
189
+
190
+ @property
191
+ def path(self) -> str:
192
+ return self.repository.issue_path(self.number)
193
+
194
+
195
+ @dataclass(frozen=True)
196
+ class IssueListing:
197
+ """
198
+ The query narrowing a listing of a repository's issues.
199
+ """
200
+
201
+ labels: str
202
+ """
203
+ The label every listed issue carries.
204
+ """
205
+
206
+ state: IssueState
207
+ """
208
+ The state every listed issue is in.
209
+ """
210
+
211
+ per_page: int
212
+ """
213
+ How many issues the listing holds.
214
+ """
215
+
216
+ @property
217
+ def query(self) -> str:
218
+ """
219
+ The listing's query string.
220
+ """
221
+ return urlencode(asdict(self))
@@ -0,0 +1,78 @@
1
+ """
2
+ A label of a repository, as GitHub's labels API lists and creates it, and the labels a
3
+ pull request is given.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from typing import Any
9
+
10
+ from basstler.class_property import classproperty
11
+ from basstler.github.client import HttpMethod, RepositoryWrite
12
+ from basstler.github.issue import IssueWrite
13
+ from basstler.json_model import ValidatedJSONModel
14
+
15
+ # %% a label
16
+
17
+
18
+ class RepositoryLabel(ValidatedJSONModel):
19
+ """
20
+ One label, whose fields are named as the labels API names them.
21
+ """
22
+
23
+ name: str
24
+ """
25
+ The label's name.
26
+ """
27
+
28
+ description: str | None = None
29
+ """
30
+ What the label means, ``None`` when it has no description.
31
+ """
32
+
33
+
34
+ class NewLabel(RepositoryWrite):
35
+ """
36
+ A label to define on the repository.
37
+ """
38
+
39
+ label: RepositoryLabel
40
+ """
41
+ The label.
42
+ """
43
+
44
+ @classproperty
45
+ def method(cls) -> HttpMethod:
46
+ return HttpMethod.POST
47
+
48
+ @property
49
+ def path(self) -> str:
50
+ return self.repository.labels_path
51
+
52
+ def to_json(self) -> dict[str, Any]:
53
+ """
54
+ :return: The label alone, as :meth:`ValidatedJSONModel.to_json` writes it.
55
+ """
56
+ return self.label.to_json()
57
+
58
+
59
+ # %% the labels of a pull request
60
+
61
+
62
+ class LabelReplacement(IssueWrite):
63
+ """
64
+ The complete set of labels an issue or pull request ends up with.
65
+ """
66
+
67
+ labels: list[str]
68
+ """
69
+ The names of the labels.
70
+ """
71
+
72
+ @classproperty
73
+ def method(cls) -> HttpMethod:
74
+ return HttpMethod.PUT
75
+
76
+ @property
77
+ def path(self) -> str:
78
+ return self.repository.issue_labels_path(self.number)
@@ -0,0 +1,46 @@
1
+ """
2
+ Running git with ``gh``'s login lent to it for GitHub.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ import os
8
+ from collections.abc import Mapping
9
+ from dataclasses import dataclass
10
+
11
+ from basstler.class_property import classproperty
12
+ from basstler.git.commands import (
13
+ GitCommandResult,
14
+ GitCommandRunner,
15
+ TransientGitSetting,
16
+ )
17
+ from basstler.github.repository import GitHubAddress
18
+
19
+ # %% the runner
20
+
21
+
22
+ @dataclass(frozen=True)
23
+ class GitHubLoginLendingRunner(GitCommandRunner):
24
+ """
25
+ Runs git in one checkout, answering its request for a GitHub credential over HTTPS
26
+ with ``gh``'s login, without changing any git configuration.
27
+ """
28
+
29
+ @classproperty
30
+ def credential_helper(cls) -> str:
31
+ """
32
+ The credential helper that answers with ``gh``'s login.
33
+ """
34
+ return "!gh auth git-credential"
35
+
36
+ def attempt(
37
+ self, *arguments: str, environment: Mapping[str, str] | None = None
38
+ ) -> GitCommandResult:
39
+ """
40
+ :meth:`GitCommandRunner.attempt`, with :attr:`credential_helper` consulted for
41
+ GitHub after every helper git is already configured with.
42
+ """
43
+ lent = TransientGitSetting(
44
+ f"credential.{GitHubAddress.WEB}.helper", self.credential_helper
45
+ ).variables(os.environ)
46
+ return super().attempt(*arguments, environment={**lent, **(environment or {})})
@@ -0,0 +1,289 @@
1
+ """
2
+ The one issue that stays open while the tests on the default branch fail.
3
+
4
+ Usage:
5
+ "${BASSTLER_PYTHON}" -m basstler.github.main_failure record --repository <owner/name>
6
+ --run <run id> --commit <sha> --conclusion <conclusion>
7
+ "${BASSTLER_PYTHON}" -m basstler.github.main_failure show --repository <owner/name>
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from dataclasses import dataclass
13
+ from enum import StrEnum
14
+
15
+ from cyclopts import App
16
+
17
+ from basstler.github.client import (
18
+ GitHubClient,
19
+ GitHubReader,
20
+ GitHubRestClient,
21
+ )
22
+ from basstler.github.issue import (
23
+ ClosingReason,
24
+ Issue,
25
+ IssueClosing,
26
+ IssueComment,
27
+ IssueListing,
28
+ IssueState,
29
+ NewIssue,
30
+ )
31
+ from basstler.github.repository import HasRepository, Repository
32
+ from basstler.github.states import CheckOutcome
33
+ from basstler.github.tooling_labels import GitHubLabel
34
+ from basstler.github.workflow_run import RunJobPage, WorkflowRun
35
+ from basstler.standard_streams import StandardStreamHandler
36
+
37
+ logger = StandardStreamHandler.logger_for(__name__)
38
+ """
39
+ This module's logger, which is also what its command prints through.
40
+ """
41
+
42
+ # %% what one run of the tests says about the default branch
43
+
44
+
45
+ class TestsRunVerdict(StrEnum):
46
+ """
47
+ What a finished run of the tests says about the default branch.
48
+ """
49
+
50
+ FAILING = "failing"
51
+ """
52
+ The run failed, so the tests on the default branch fail.
53
+ """
54
+
55
+ PASSING = "passing"
56
+ """
57
+ The run succeeded, so the tests on the default branch pass.
58
+ """
59
+
60
+ UNDECIDED = "undecided"
61
+ """
62
+ The run was cancelled, skipped or otherwise proves nothing.
63
+ """
64
+
65
+ @classmethod
66
+ def from_run_check(cls, outcome: CheckOutcome) -> TestsRunVerdict:
67
+ """
68
+ :param outcome: How a run or one of its jobs ended.
69
+ :return: What that says about the default branch.
70
+ """
71
+ if outcome in {
72
+ CheckOutcome.FAILURE,
73
+ CheckOutcome.TIMED_OUT,
74
+ CheckOutcome.STARTUP_FAILURE,
75
+ }:
76
+ return cls.FAILING
77
+ if outcome is CheckOutcome.SUCCESS:
78
+ return cls.PASSING
79
+ return cls.UNDECIDED
80
+
81
+
82
+ @dataclass(frozen=True)
83
+ class FinishedRun(HasRepository):
84
+ """
85
+ One finished run of the tests on the default branch, with the jobs that failed.
86
+ """
87
+
88
+ workflow_run: WorkflowRun
89
+ """
90
+ The run.
91
+ """
92
+
93
+ failed_jobs: tuple[str, ...] = ()
94
+ """
95
+ The names of the jobs that failed, as the run lists them.
96
+ """
97
+
98
+ @classmethod
99
+ def read(
100
+ cls, repository: Repository, workflow_run: WorkflowRun, github: GitHubReader
101
+ ) -> FinishedRun:
102
+ """
103
+ :param repository: The repository the run tested.
104
+ :param workflow_run: The finished run.
105
+ :param github: What reads a failed run's jobs.
106
+ :return: The run, with its failed jobs when it failed.
107
+ """
108
+ if (
109
+ TestsRunVerdict.from_run_check(workflow_run.outcome)
110
+ is not TestsRunVerdict.FAILING
111
+ ):
112
+ return cls(repository, workflow_run)
113
+ page = RunJobPage.from_json(
114
+ github.get(RunJobPage.path(repository, workflow_run.identifier))
115
+ )
116
+ failed = tuple(
117
+ job.name
118
+ for job in page.jobs
119
+ if TestsRunVerdict.from_run_check(job.outcome) is TestsRunVerdict.FAILING
120
+ )
121
+ return cls(repository, workflow_run, failed)
122
+
123
+ @property
124
+ def verdict(self) -> TestsRunVerdict:
125
+ """
126
+ What the run says about the default branch.
127
+ """
128
+ return TestsRunVerdict.from_run_check(self.workflow_run.outcome)
129
+
130
+ @property
131
+ def url(self) -> str:
132
+ """
133
+ The run's page on GitHub.
134
+ """
135
+ return self.repository.workflow_run_url(self.workflow_run.identifier)
136
+
137
+ def describe(self) -> str:
138
+ """
139
+ :return: The run, its commit and, when it failed, its failed jobs, as Markdown.
140
+ """
141
+ run = f"[This run]({self.url}) on {self.workflow_run.commit}"
142
+ if self.verdict is not TestsRunVerdict.FAILING:
143
+ return f"{run} passed."
144
+ jobs = ", ".join(f"`{job}`" for job in self.failed_jobs)
145
+ return f"{run} failed in {jobs}."
146
+
147
+
148
+ # %% the issue
149
+
150
+
151
+ @dataclass(frozen=True)
152
+ class MainFailureTracker(HasRepository):
153
+ """
154
+ Keeps exactly one issue open, labelled :attr:`GitHubLabel.MAIN_RED`, while the
155
+ default branch's tests fail.
156
+ """
157
+
158
+ title: str = "The tests on main are failing"
159
+ """
160
+ The title the issue is opened with.
161
+ """
162
+
163
+ @property
164
+ def open_issues_path(self) -> str:
165
+ """
166
+ The listing of the open issue, if there is one.
167
+ """
168
+ listing = IssueListing(GitHubLabel.MAIN_RED, IssueState.OPEN, per_page=1)
169
+ return f"{self.repository.issues_path}?{listing.query}"
170
+
171
+ def open_issue(self, github: GitHubReader) -> Issue | None:
172
+ """
173
+ :param github: What reads the issues.
174
+ :return: The open issue, or ``None`` while the tests pass.
175
+ """
176
+ listed = github.get(self.open_issues_path)
177
+ if not listed:
178
+ return None
179
+ return Issue.from_json(listed[0])
180
+
181
+ def record(self, run: FinishedRun, github: GitHubClient) -> Issue | None:
182
+ """
183
+ :param run: The run of the tests that just finished.
184
+ :param github: What reads and writes the issues.
185
+ :return: The issue the run opened, commented on or closed, or ``None`` when it
186
+ changed nothing.
187
+ """
188
+ if run.verdict is TestsRunVerdict.UNDECIDED:
189
+ return None
190
+ issue = self.open_issue(github)
191
+ if run.verdict is TestsRunVerdict.FAILING:
192
+ return self.report_failure(run, issue, github)
193
+ if issue is None:
194
+ return None
195
+ self.report_pass(run, issue, github)
196
+ return issue
197
+
198
+ def report_failure(
199
+ self, run: FinishedRun, issue: Issue | None, github: GitHubClient
200
+ ) -> Issue:
201
+ """
202
+ Comment on the open issue, or open one when none is.
203
+
204
+ :param run: The failed run.
205
+ :param issue: The issue already open, if there is one.
206
+ :param github: What writes the issues.
207
+ :return: The issue now reporting the failure.
208
+ """
209
+ if issue is not None:
210
+ self.comment(issue, run, github)
211
+ return issue
212
+ opened = github.send(
213
+ NewIssue(
214
+ self.repository,
215
+ self.title,
216
+ run.describe(),
217
+ [GitHubLabel.BUG, GitHubLabel.MAIN_RED],
218
+ )
219
+ )
220
+ return Issue.from_json(opened)
221
+
222
+ def report_pass(self, run: FinishedRun, issue: Issue, github: GitHubClient) -> None:
223
+ """
224
+ Comment the passing run on the open issue and close it as completed.
225
+
226
+ :param run: The run that passed.
227
+ :param issue: The open issue.
228
+ :param github: What writes the issues.
229
+ """
230
+ self.comment(issue, run, github)
231
+ github.send(
232
+ IssueClosing(self.repository, issue.number, ClosingReason.COMPLETED)
233
+ )
234
+
235
+ def comment(self, issue: Issue, run: FinishedRun, github: GitHubClient) -> None:
236
+ """
237
+ Post the run's description on the issue.
238
+
239
+ :param issue: The issue to comment on.
240
+ :param run: The run the comment describes.
241
+ :param github: What writes the comment.
242
+ """
243
+ github.send(IssueComment(self.repository, issue.number, run.describe()))
244
+
245
+
246
+ # %% the command line
247
+
248
+ app = App(help=__doc__)
249
+ """
250
+ The commands recording a run and showing the open issue.
251
+ """
252
+
253
+
254
+ @app.command
255
+ def record(repository: str, run: int, commit: str, conclusion: str) -> None:
256
+ """
257
+ Open, comment on or close the issue after a run of the tests on the default branch.
258
+
259
+ :param repository: The tested repository, as ``owner/name``.
260
+ :param run: The Actions run's own number.
261
+ :param commit: The commit the run tested.
262
+ :param conclusion: How the run ended, as Actions spells it.
263
+ """
264
+ tested = Repository.parse(repository)
265
+ github = GitHubRestClient()
266
+ workflow_run = WorkflowRun(run, commit, CheckOutcome.from_conclusion(conclusion))
267
+ issue = MainFailureTracker(tested).record(
268
+ FinishedRun.read(tested, workflow_run, github), github
269
+ )
270
+ if issue is not None:
271
+ logger.info(issue.url)
272
+
273
+
274
+ @app.command
275
+ def show(repository: str) -> None:
276
+ """
277
+ Print the open issue's page, or nothing while the tests pass.
278
+
279
+ :param repository: The repository, as ``owner/name``.
280
+ """
281
+ issue = MainFailureTracker(Repository.parse(repository)).open_issue(
282
+ GitHubRestClient()
283
+ )
284
+ if issue is not None:
285
+ logger.info(issue.url)
286
+
287
+
288
+ if __name__ == "__main__":
289
+ app()
@@ -0,0 +1,33 @@
1
+ """
2
+ How much of a repository's resource an account or a token may use.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from enum import StrEnum
8
+
9
+ # %% the level
10
+
11
+
12
+ class PermissionLevel(StrEnum):
13
+ """
14
+ The access a permission grants on one of a repository's resources.
15
+ """
16
+
17
+ READ = "read"
18
+ """
19
+ Read only.
20
+ """
21
+
22
+ WRITE = "write"
23
+ """
24
+ Read and write.
25
+ """
26
+
27
+ @classmethod
28
+ def broadest(cls, levels: list[PermissionLevel]) -> PermissionLevel:
29
+ """
30
+ :param levels: The levels several jobs need on one permission, at least one.
31
+ :return: The level that grants all of them.
32
+ """
33
+ return cls.WRITE if cls.WRITE in levels else cls.READ