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,148 @@
1
+ """
2
+ The workflow runs a repository's branch has had, read from GitHub.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from datetime import datetime
8
+ from pathlib import Path
9
+ from typing import Annotated
10
+ from urllib.parse import urlencode
11
+
12
+ from pydantic import Field
13
+
14
+ from basstler.github.client import (
15
+ GitHubReader,
16
+ )
17
+ from basstler.github.repository import Repository
18
+ from basstler.github.states import CheckOutcome
19
+ from basstler.github.web_page import WebPage
20
+ from basstler.github.workflow_run import WorkflowRun
21
+ from basstler.json_model import ValidatedJSONModel
22
+ from basstler.locations import WorkflowLocation
23
+ from basstler.standard_streams import StandardStreamHandler
24
+
25
+ logger = StandardStreamHandler.logger_for(__name__)
26
+ """
27
+ This module's logger, which is also what its command prints through.
28
+ """
29
+
30
+ MAXIMUM_RUNS_PER_PAGE = 100
31
+ """
32
+ The most runs GitHub lists on one page.
33
+ """
34
+
35
+ # %% the runs that confirm a step
36
+
37
+
38
+ class ListedRun(WorkflowRun, WebPage):
39
+ """
40
+ One run, as a repository's run listing describes it.
41
+ """
42
+
43
+ workflow_file_path: Annotated[Path, Field(alias="path")]
44
+ """
45
+ The workflow file it ran, relative to its repository's root.
46
+ """
47
+
48
+ created_at: datetime
49
+ """
50
+ When it was started.
51
+ """
52
+
53
+
54
+ class RunListing(ValidatedJSONModel):
55
+ """
56
+ The latest runs on one branch of a repository, newest first.
57
+ """
58
+
59
+ workflow_runs: list[ListedRun]
60
+ """
61
+ The runs.
62
+ """
63
+
64
+ @staticmethod
65
+ def path(
66
+ repository: Repository, branch: str, runs_per_page: int = MAXIMUM_RUNS_PER_PAGE
67
+ ) -> str:
68
+ """
69
+ :param repository: The repository.
70
+ :param branch: The branch the runs ran on.
71
+ :param runs_per_page: How many of the latest runs to list.
72
+ :return: The REST path listing them.
73
+ """
74
+ query = urlencode(
75
+ {
76
+ "branch": branch,
77
+ "per_page": runs_per_page,
78
+ }
79
+ )
80
+ return f"{repository.api_path}/actions/runs?{query}"
81
+
82
+ @classmethod
83
+ def read(
84
+ cls, client: GitHubReader, repository: Repository, branch: str
85
+ ) -> RunListing:
86
+ """
87
+ :param client: What reads the listing.
88
+ :param repository: The repository.
89
+ :param branch: The branch the runs ran on.
90
+ :return: The listing.
91
+ """
92
+ return cls.from_json(client.get(cls.path(repository, branch)))
93
+
94
+ def run_for_commit(self, commit: str) -> ListedRun | None:
95
+ """
96
+ :param commit: The commit a run was started for.
97
+ :return: The latest run started for it, ``None`` when none was.
98
+ """
99
+ return next((run for run in self.workflow_runs if run.commit == commit), None)
100
+
101
+ def select(self, workflow: WorkflowLocation) -> RunListing:
102
+ """
103
+ :param workflow: The workflow.
104
+ :return: The listing of its runs alone.
105
+ """
106
+ return RunListing(
107
+ [run for run in self.workflow_runs if run.workflow_file_path == workflow]
108
+ )
109
+
110
+ def count(self, outcome: CheckOutcome) -> int:
111
+ """
112
+ :param outcome: How a run ended.
113
+ :return: How many listed runs ended so.
114
+ """
115
+ return sum(run.outcome is outcome for run in self.workflow_runs)
116
+
117
+ def latest(self, workflow: WorkflowLocation) -> ListedRun | None:
118
+ """
119
+ :param workflow: The workflow.
120
+ :return: Its latest run, ``None`` when the listing holds none.
121
+ """
122
+ return next(
123
+ (run for run in self.workflow_runs if run.workflow_file_path == workflow),
124
+ None,
125
+ )
126
+
127
+ def latest_success(self, workflow: WorkflowLocation) -> ListedRun | None:
128
+ """
129
+ :param workflow: The workflow.
130
+ :return: Its latest run that succeeded, ``None`` when the listing holds none.
131
+ """
132
+ return next(
133
+ (
134
+ run
135
+ for run in self.workflow_runs
136
+ if run.workflow_file_path == workflow
137
+ and run.outcome is CheckOutcome.SUCCESS
138
+ ),
139
+ None,
140
+ )
141
+
142
+ def succeeded(self, workflow: WorkflowLocation) -> bool:
143
+ """
144
+ :param workflow: The workflow.
145
+ :return: Whether its latest run succeeded.
146
+ """
147
+ latest = self.latest(workflow)
148
+ return latest is not None and latest.outcome is CheckOutcome.SUCCESS
@@ -0,0 +1,178 @@
1
+ """
2
+ The stack configuration a project commits, layered over the defaults the package ships.
3
+
4
+ The shipped ``stack.toml`` holds what is the same for every project - label names, the
5
+ base branch - and names nobody's repository. A project names its own upstream in
6
+ ``.claude/basstler/stack.toml``, committed beside its code, so every contributor and every
7
+ Actions runner checking the project out reads the same answer. The per-user layer on the
8
+ personal-notes branch goes on top of both, and is :mod:`basstler.stack`'s to read, since
9
+ a runner never fetches that branch.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import tomllib
15
+ from dataclasses import dataclass, field
16
+ from enum import StrEnum
17
+ from pathlib import Path
18
+ from typing import Any
19
+
20
+ from basstler.class_property import classproperty
21
+ from basstler.exit_codes import CommandFailure, StackExitCode
22
+ from basstler.github.repository import Repository
23
+ from basstler.locations import PackageLocation, ProjectLocation
24
+ from basstler.text_file import TextFile
25
+
26
+
27
+ class StackSetting(StrEnum):
28
+ """
29
+ The keys of a ``stack.toml``.
30
+ """
31
+
32
+ IN_REVIEW_LABEL = "in_review_label"
33
+ """
34
+ The fork pull request label marking a branch promoted to the upstream.
35
+ """
36
+
37
+ REBASE_LABEL = "rebase_label"
38
+ """
39
+ The label opting a branch into rebasing instead of merging.
40
+ """
41
+
42
+ NEEDS_RESOLUTION_LABEL = "needs_resolution_label"
43
+ """
44
+ The label withholding a branch from promotion until a conflict is resolved.
45
+ """
46
+
47
+ FORK_REPOSITORY = "fork_repository"
48
+ """
49
+ The fork, for a checkout whose fork remote is ambiguous.
50
+ """
51
+
52
+ FORK_REMOTE = "fork_remote"
53
+ """
54
+ The git remote of the fork.
55
+ """
56
+
57
+ UPSTREAM_REPOSITORY = "upstream_repository"
58
+ """
59
+ The repository every fork is forked from and reviewed on.
60
+ """
61
+
62
+ UPSTREAM_REMOTE = "upstream_remote"
63
+ """
64
+ The name the upstream's tracking references are kept under when no remote points at
65
+ it.
66
+ """
67
+
68
+ UPSTREAM_BASE = "upstream_base"
69
+ """
70
+ The upstream branch every stack ultimately targets.
71
+ """
72
+
73
+ UPSTREAM_LOCATION = "upstream_location"
74
+ """
75
+ What the upstream is fetched from: its remote's name, or its URL when the checkout
76
+ has none. Resolved from the checkout rather than read from a ``stack.toml``.
77
+ """
78
+
79
+
80
+ @dataclass
81
+ class MissingUpstreamRepositoryError(CommandFailure, LookupError):
82
+ """
83
+ Raised when neither the project nor anything above it names the upstream repository.
84
+ """
85
+
86
+ @classproperty
87
+ def exit_code(cls) -> StackExitCode:
88
+ """:return: The status this kind of error ends a command with."""
89
+ return StackExitCode.UPSTREAM_UNCONFIGURED
90
+
91
+ project_file: Path
92
+ """
93
+ The file the project names its upstream in.
94
+ """
95
+
96
+ personal_file: Path | None = None
97
+ """
98
+ The personal-notes file that can name it instead, for a caller that reads that layer.
99
+ """
100
+
101
+ def __str__(self) -> str:
102
+ """:return: Where to name the upstream, and how."""
103
+ alternative = (
104
+ f", or to {self.personal_file} on your personal-notes branch"
105
+ if self.personal_file
106
+ else ""
107
+ )
108
+ return (
109
+ f"no {StackSetting.UPSTREAM_REPOSITORY} is configured - add "
110
+ f'{StackSetting.UPSTREAM_REPOSITORY} = "<owner>/<name>" to {self.project_file}'
111
+ f"{alternative}"
112
+ )
113
+
114
+
115
+ @dataclass(frozen=True)
116
+ class CommittedStackConfiguration:
117
+ """
118
+ The shipped defaults with a project's own committed settings layered on top.
119
+ """
120
+
121
+ shipped: Path = PackageLocation.STACK_CONFIGURATION.value
122
+ """
123
+ The defaults the package ships.
124
+ """
125
+
126
+ project_root: Path = field(default_factory=Path.cwd)
127
+ """
128
+ The project whose committed settings outrank them.
129
+ """
130
+
131
+ @property
132
+ def project_file(self) -> Path:
133
+ """
134
+ The project's own settings file, which may not exist.
135
+ """
136
+ return self.project_root / ProjectLocation.PROJECT_STACK_CONFIGURATION
137
+
138
+ def values(self) -> dict[str, Any]:
139
+ """
140
+ :return: The shipped values, with every key the project sets replaced by its own.
141
+ """
142
+ values = tomllib.loads(TextFile(self.shipped).read())
143
+ if self.project_file.is_file():
144
+ values.update(tomllib.loads(TextFile(self.project_file).read()))
145
+ return values
146
+
147
+ def upstream_repository(self) -> Repository:
148
+ """
149
+ :return: The repository the project's pull requests are reviewed on.
150
+ :raises MissingUpstreamRepositoryError: If the project names none.
151
+ """
152
+ return self.upstream_repository_in(self.values())
153
+
154
+ def upstream_repository_in(
155
+ self, values: dict[str, Any], personal_file: Path | None = None
156
+ ) -> Repository:
157
+ """
158
+ :param values: Layered stack settings, of which this project's are a layer.
159
+ :param personal_file: Where the user could name the upstream instead, when
160
+ *values* include the personal-notes layer.
161
+ :return: The upstream repository the settings name.
162
+ :raises MissingUpstreamRepositoryError: If they name none.
163
+ """
164
+ upstream_repository = self.named_upstream_repository(values)
165
+ if upstream_repository is None:
166
+ raise MissingUpstreamRepositoryError(self.project_file, personal_file)
167
+ return upstream_repository
168
+
169
+ @staticmethod
170
+ def named_upstream_repository(values: dict[str, Any]) -> Repository | None:
171
+ """
172
+ :param values: Layered stack settings.
173
+ :return: The upstream repository they name, or ``None`` for a project that is
174
+ not a fork.
175
+ """
176
+ if StackSetting.UPSTREAM_REPOSITORY not in values:
177
+ return None
178
+ return Repository.parse(values[StackSetting.UPSTREAM_REPOSITORY])
@@ -0,0 +1,257 @@
1
+ """
2
+ The fixed values GitHub reports reviews, pull requests and checks in.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from enum import StrEnum
8
+ from typing import Annotated, Any, Self
9
+
10
+ from pydantic import GetCoreSchemaHandler
11
+ from pydantic_core import core_schema
12
+
13
+ from basstler.json_model import RawValueReader
14
+
15
+ # %% values named as GitHub spells them
16
+
17
+
18
+ class NamedAsGitHub(StrEnum):
19
+ """
20
+ An enum whose members are named as GitHub spells its values, in any letter case,
21
+ while each member's value is how it reads in the report.
22
+ """
23
+
24
+ @classmethod
25
+ def from_github_name(cls, spelling: str) -> Self:
26
+ """
27
+ :param spelling: A value as GitHub spells it, or a member already.
28
+ :return: The member it names.
29
+ :raises KeyError: If no member has that name.
30
+ """
31
+ if isinstance(spelling, cls):
32
+ return spelling
33
+ return cls[spelling.upper()]
34
+
35
+ @classmethod
36
+ def __get_pydantic_core_schema__(
37
+ cls, source: type[Any], handler: GetCoreSchemaHandler
38
+ ) -> core_schema.CoreSchema:
39
+ """
40
+ :param source: The enum.
41
+ :param handler: Builds pydantic's own schema for a type, unused since the enum
42
+ replaces it.
43
+ :return: How pydantic reads a field of this enum: by :meth:`from_github_name`.
44
+ """
45
+ return core_schema.no_info_plain_validator_function(
46
+ cls.from_github_name, json_schema_input_schema=core_schema.str_schema()
47
+ )
48
+
49
+
50
+ class ReviewState(NamedAsGitHub):
51
+ """
52
+ The verdict a reviewer submitted with a review.
53
+ """
54
+
55
+ APPROVED = "approved"
56
+ """
57
+ The reviewer approved the changes.
58
+ """
59
+
60
+ CHANGES_REQUESTED = "changes requested"
61
+ """
62
+ The reviewer asked for changes before the pull request can merge.
63
+ """
64
+
65
+ COMMENTED = "commented"
66
+ """
67
+ The reviewer left comments without a verdict.
68
+ """
69
+
70
+ DISMISSED = "dismissed"
71
+ """
72
+ The review was dismissed and no longer counts towards the verdict.
73
+ """
74
+
75
+ PENDING = "pending"
76
+ """
77
+ The review was started but not yet submitted.
78
+ """
79
+
80
+
81
+ class PullRequestState(StrEnum):
82
+ """
83
+ The lifecycle state GitHub reports for a pull request.
84
+ """
85
+
86
+ OPEN = "OPEN"
87
+ CLOSED = "CLOSED"
88
+ MERGED = "MERGED"
89
+
90
+
91
+ # %% checks
92
+
93
+
94
+ class Conclusion(RawValueReader):
95
+ """
96
+ Reads the conclusion GitHub gives a check run or workflow run, null while it runs,
97
+ as its :class:`CheckOutcome`.
98
+ """
99
+
100
+ def read(self, value: str | None) -> CheckOutcome:
101
+ return CheckOutcome.from_conclusion(value)
102
+
103
+
104
+ class CheckOutcome(NamedAsGitHub):
105
+ """
106
+ Where one check stands, over check runs and commit statuses alike.
107
+
108
+ A check run that has not finished reports no conclusion at all, which reads here as
109
+ :attr:`PENDING` so an unfinished check is never mistaken for a passing one.
110
+ """
111
+
112
+ SUCCESS = "success"
113
+ """
114
+ The check passed.
115
+ """
116
+
117
+ FAILURE = "failure"
118
+ """
119
+ The check failed.
120
+ """
121
+
122
+ ERROR = "error"
123
+ """
124
+ The commit status reported an error.
125
+ """
126
+
127
+ CANCELLED = "cancelled"
128
+ """
129
+ The check run was cancelled before it finished.
130
+ """
131
+
132
+ TIMED_OUT = "timed out"
133
+ """
134
+ The check run exceeded its time limit.
135
+ """
136
+
137
+ ACTION_REQUIRED = "action required"
138
+ """
139
+ The check run needs someone to act before it can conclude.
140
+ """
141
+
142
+ NEUTRAL = "neutral"
143
+ """
144
+ The check run finished without passing or failing.
145
+ """
146
+
147
+ SKIPPED = "skipped"
148
+ """
149
+ The check run was skipped.
150
+ """
151
+
152
+ STALE = "stale"
153
+ """
154
+ GitHub marked the check run stale after it went too long without finishing.
155
+ """
156
+
157
+ @classmethod
158
+ def from_conclusion(cls, conclusion: str | None) -> CheckOutcome:
159
+ """
160
+ :param conclusion: A check run's or workflow run's conclusion as GitHub spells
161
+ it, ``None`` while it runs.
162
+ :return: The outcome it reads as.
163
+ """
164
+ return cls.from_github_name(conclusion) if conclusion else cls.PENDING
165
+
166
+ STARTUP_FAILURE = "startup failure"
167
+ """
168
+ The check run failed before it could start.
169
+ """
170
+ PENDING = "pending"
171
+ """
172
+ The check has not finished yet.
173
+ """
174
+ EXPECTED = "expected"
175
+ """
176
+ A required commit status that has not been reported yet.
177
+ """
178
+
179
+ @property
180
+ def combined_state(self) -> CombinedCheckState:
181
+ """
182
+ :return: The verdict this outcome alone would give the combined state, the way
183
+ GitHub counts it: a neutral or skipped check does not hold a pull request
184
+ back, and everything that ended without passing fails it.
185
+ """
186
+ if self in {CheckOutcome.SUCCESS, CheckOutcome.NEUTRAL, CheckOutcome.SKIPPED}:
187
+ return CombinedCheckState.SUCCESS
188
+ if self in {CheckOutcome.ERROR, CheckOutcome.PENDING, CheckOutcome.EXPECTED}:
189
+ return CombinedCheckState[self.name]
190
+ return CombinedCheckState.FAILURE
191
+
192
+
193
+ ConclusionOutcome = Annotated[CheckOutcome, Conclusion()]
194
+ """
195
+ A check's outcome, read from the conclusion GitHub gives a check run or workflow run.
196
+ """
197
+
198
+
199
+ class CombinedCheckState(NamedAsGitHub):
200
+ """
201
+ The verdict GitHub itself computes over all of a pull request's checks, or that
202
+ nothing has reported one yet.
203
+ """
204
+
205
+ SUCCESS = "success"
206
+ """
207
+ Every check passed.
208
+ """
209
+
210
+ FAILURE = "failure"
211
+ """
212
+ At least one check failed.
213
+ """
214
+
215
+ ERROR = "error"
216
+ """
217
+ At least one commit status reported an error.
218
+ """
219
+
220
+ PENDING = "pending"
221
+ """
222
+ At least one check has not finished yet.
223
+ """
224
+
225
+ EXPECTED = "expected"
226
+ """
227
+ At least one required commit status has not been reported yet.
228
+ """
229
+
230
+ NOT_REPORTED = "not reported"
231
+ """
232
+ No check run or commit status has been reported at all.
233
+ """
234
+
235
+ @property
236
+ def failed(self) -> bool:
237
+ """:return: Whether at least one check failed or reported an error."""
238
+ return self in {CombinedCheckState.FAILURE, CombinedCheckState.ERROR}
239
+
240
+ @classmethod
241
+ def over(cls, outcomes: list[CheckOutcome]) -> CombinedCheckState:
242
+ """
243
+ Compute the verdict GitHub would over a set of checks, for a source that does
244
+ not report one: the worst any single check would give.
245
+
246
+ :param outcomes: Every check's outcome, at least one.
247
+ :return: The verdict.
248
+ """
249
+ reached = {outcome.combined_state for outcome in outcomes}
250
+ return next(state for state in cls.severity_order() if state in reached)
251
+
252
+ @classmethod
253
+ def severity_order(cls) -> list[CombinedCheckState]:
254
+ """
255
+ :return: Every verdict a reported check can give, worst first.
256
+ """
257
+ return [cls.FAILURE, cls.ERROR, cls.PENDING, cls.EXPECTED, cls.SUCCESS]