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,297 @@
1
+ """
2
+ The Actions usage monitor: how many runs and jobs each workflow took in the last 24
3
+ hours, compared with the daily ceilings of the repository's budget.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import argparse
9
+ import sys
10
+ from dataclasses import dataclass
11
+ from datetime import UTC, datetime, timedelta
12
+ from enum import StrEnum
13
+ from pathlib import PurePosixPath
14
+ from urllib.parse import quote
15
+
16
+ from basstler.environment import GitHubActionsVariable
17
+ from basstler.github.actions_budget import ActionsBudget, WorkflowLimits
18
+ from basstler.github.client import GitHubReader, GitHubRestClient
19
+ from basstler.github.repository import Repository
20
+
21
+ # %% vocabulary
22
+
23
+ RUNS_PER_PAGE = 100
24
+ """
25
+ The most runs GitHub returns in one page.
26
+ """
27
+
28
+ WINDOW = timedelta(days=1)
29
+ """
30
+ How far back runs are counted: the period the daily ceilings are for.
31
+ """
32
+
33
+
34
+ class UsageLevel(StrEnum):
35
+ """
36
+ How near a workflow's usage is to its ceilings, from the lowest to the highest.
37
+ """
38
+
39
+ WITHIN_BUDGET = "within budget"
40
+ APPROACHING_CEILING = "approaching its ceiling"
41
+ OVER_CEILING = "over its ceiling"
42
+
43
+ @property
44
+ def severity(self) -> int:
45
+ """
46
+ The position among the levels, which orders them.
47
+ """
48
+ return list(type(self)).index(self)
49
+
50
+
51
+ class UsageOutputKey(StrEnum):
52
+ """
53
+ The ``$GITHUB_OUTPUT`` keys the report sets.
54
+ """
55
+
56
+ OVER_BUDGET = "over_budget"
57
+ """
58
+ ``true`` when any workflow is over a ceiling.
59
+ """
60
+
61
+
62
+ class WorkflowCommand(StrEnum):
63
+ """
64
+ The workflow commands the report prints.
65
+ """
66
+
67
+ WARNING = "::warning::"
68
+
69
+
70
+ # %% what one workflow used
71
+
72
+
73
+ @dataclass(frozen=True)
74
+ class WorkflowUsage:
75
+ """
76
+ One workflow's runs and jobs in the window, with the limits they are compared with.
77
+ """
78
+
79
+ workflow: str
80
+ """
81
+ The workflow's file name.
82
+ """
83
+
84
+ runs: int
85
+ """
86
+ The runs created in the window.
87
+ """
88
+
89
+ jobs: int
90
+ """
91
+ The jobs of those runs.
92
+ """
93
+
94
+ limits: WorkflowLimits
95
+ """
96
+ The limits the workflow is held to.
97
+ """
98
+
99
+ warning_fraction: float = 0.8
100
+ """
101
+ The share of a ceiling at which usage is flagged as approaching it.
102
+ """
103
+
104
+ @property
105
+ def level(self) -> UsageLevel:
106
+ """
107
+ The highest level either count reaches against its ceiling; counts with no
108
+ ceiling are within budget.
109
+ """
110
+ return max(
111
+ (
112
+ self._level_of(self.runs, self.limits.runs_per_day),
113
+ self._level_of(self.jobs, self.limits.jobs_per_day),
114
+ ),
115
+ key=lambda level: level.severity,
116
+ )
117
+
118
+ def _level_of(self, count: int, ceiling: int | None) -> UsageLevel:
119
+ """
120
+ :param count: A count in the window.
121
+ :param ceiling: Its daily ceiling, or ``None`` for no ceiling.
122
+ :return: How near the count is to the ceiling.
123
+ """
124
+ if ceiling is None or count < ceiling * self.warning_fraction:
125
+ return UsageLevel.WITHIN_BUDGET
126
+ if count < ceiling:
127
+ return UsageLevel.APPROACHING_CEILING
128
+ return UsageLevel.OVER_CEILING
129
+
130
+ def summary(self) -> str:
131
+ """
132
+ :return: One line naming the workflow, its level and its counts against the
133
+ ceilings.
134
+ """
135
+ runs = self._counted(self.runs, self.limits.runs_per_day, "runs")
136
+ jobs = self._counted(self.jobs, self.limits.jobs_per_day, "jobs")
137
+ return f"{self.workflow}: {self.level}: {runs} and {jobs} in the last 24 hours"
138
+
139
+ def annotation(self) -> str:
140
+ """
141
+ :return: The summary, as a workflow warning when the workflow is approaching or
142
+ over a ceiling.
143
+ """
144
+ if self.level == UsageLevel.WITHIN_BUDGET:
145
+ return self.summary()
146
+ return f"{WorkflowCommand.WARNING}{self.summary()}"
147
+
148
+ @staticmethod
149
+ def _counted(count: int, ceiling: int | None, noun: str) -> str:
150
+ """
151
+ :param count: A count in the window.
152
+ :param ceiling: Its daily ceiling, or ``None`` for no ceiling.
153
+ :param noun: What is counted.
154
+ :return: The count, with its ceiling when it has one.
155
+ """
156
+ if ceiling is None:
157
+ return f"{count} {noun}"
158
+ return f"{count} of {ceiling} {noun}"
159
+
160
+
161
+ # %% the report
162
+
163
+
164
+ @dataclass(frozen=True)
165
+ class UsageReport:
166
+ """
167
+ Every workflow's usage in the window.
168
+ """
169
+
170
+ usages: tuple[WorkflowUsage, ...]
171
+ """
172
+ The usage of each workflow that ran, in the order its first run was listed.
173
+ """
174
+
175
+ @classmethod
176
+ def measure(
177
+ cls,
178
+ client: GitHubReader,
179
+ repository: Repository,
180
+ budget: ActionsBudget,
181
+ now: datetime,
182
+ ) -> UsageReport:
183
+ """
184
+ :param client: Where the runs and jobs are read from.
185
+ :param repository: The repository whose runs are counted.
186
+ :param budget: The budget whose ceilings the counts are compared with.
187
+ :param now: The end of the window.
188
+ :return: The usage of every workflow that ran in the window.
189
+ """
190
+ since = (now - WINDOW).astimezone(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
191
+ query = quote(f">={since}", safe="")
192
+ pages = client.get_pages(
193
+ f"{repository.api_path}/actions/runs"
194
+ f"?created={query}&per_page={RUNS_PER_PAGE}"
195
+ )
196
+ runs_by_workflow: dict[str, int] = {}
197
+ jobs_by_workflow: dict[str, int] = {}
198
+ for page in pages:
199
+ for run in page["workflow_runs"]:
200
+ workflow = PurePosixPath(run["path"].split("@")[0]).name
201
+ job_count = client.get(
202
+ f"{repository.api_path}/actions/runs/{run['id']}/jobs?per_page=1"
203
+ )["total_count"]
204
+ runs_by_workflow[workflow] = runs_by_workflow.get(workflow, 0) + 1
205
+ jobs_by_workflow[workflow] = (
206
+ jobs_by_workflow.get(workflow, 0) + job_count
207
+ )
208
+ return cls(
209
+ usages=tuple(
210
+ WorkflowUsage(
211
+ workflow=workflow,
212
+ runs=runs,
213
+ jobs=jobs_by_workflow[workflow],
214
+ limits=budget.limits_of(workflow),
215
+ )
216
+ for workflow, runs in runs_by_workflow.items()
217
+ )
218
+ )
219
+
220
+ @property
221
+ def flagged(self) -> tuple[WorkflowUsage, ...]:
222
+ """
223
+ The workflows approaching or over a ceiling.
224
+ """
225
+ return tuple(
226
+ usage for usage in self.usages if usage.level != UsageLevel.WITHIN_BUDGET
227
+ )
228
+
229
+ @property
230
+ def is_over_budget(self) -> bool:
231
+ """
232
+ Whether any workflow is over a ceiling.
233
+ """
234
+ return any(usage.level == UsageLevel.OVER_CEILING for usage in self.usages)
235
+
236
+ def markdown(self) -> str:
237
+ """
238
+ :return: The report as a Markdown table, for a job summary.
239
+ """
240
+ rows = "\n".join(
241
+ f"| {usage.workflow} | {usage.runs} | {usage.jobs} | {usage.level} |"
242
+ for usage in self.usages
243
+ )
244
+ return (
245
+ f"| Workflow | Runs | Jobs | Level |\n| --- | --- | --- | --- |\n{rows}\n"
246
+ )
247
+
248
+
249
+ # %% the command
250
+
251
+
252
+ def main() -> None:
253
+ """
254
+ Print the last 24 hours of Actions usage against the repository's budget.
255
+ """
256
+ parser = argparse.ArgumentParser(description=main.__doc__)
257
+ parser.add_argument("--repository", required=True, type=Repository.parse)
258
+ parser.add_argument(
259
+ "--flagged-only",
260
+ action="store_true",
261
+ help="Print only the workflows approaching or over a ceiling.",
262
+ )
263
+ parser.add_argument(
264
+ "--github-actions",
265
+ action="store_true",
266
+ help="Annotate the flagged workflows, write the job summary and the output.",
267
+ )
268
+ arguments = parser.parse_args()
269
+ budget = ActionsBudget.load()
270
+ if not budget.has_daily_ceilings:
271
+ return
272
+ report = UsageReport.measure(
273
+ GitHubRestClient(),
274
+ arguments.repository,
275
+ budget,
276
+ datetime.now(UTC),
277
+ )
278
+ for usage in report.flagged if arguments.flagged_only else report.usages:
279
+ sys.stdout.write(
280
+ f"{usage.annotation() if arguments.github_actions else usage.summary()}\n"
281
+ )
282
+ if not arguments.github_actions:
283
+ return
284
+ summary_path = GitHubActionsVariable.STEP_SUMMARY.read()
285
+ if summary_path:
286
+ with open(summary_path, "a", encoding="utf-8") as summary:
287
+ summary.write(report.markdown())
288
+ output_path = GitHubActionsVariable.OUTPUT.read()
289
+ if output_path:
290
+ with open(output_path, "a", encoding="utf-8") as output:
291
+ output.write(
292
+ f"{UsageOutputKey.OVER_BUDGET}={str(report.is_over_budget).lower()}\n"
293
+ )
294
+
295
+
296
+ if __name__ == "__main__":
297
+ main()
@@ -0,0 +1,75 @@
1
+ """
2
+ basstler's own project, as the workflows, links and tokens it sets up name it.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ import functools
8
+ import importlib.metadata
9
+ from enum import StrEnum
10
+
11
+ from basstler.class_property import classproperty
12
+ from basstler.git.branch import Branch
13
+ from basstler.github.exceptions import BasstlerSourceUnknown
14
+ from basstler.github.repository import Repository
15
+ from basstler.locations import PackageLocation
16
+ from basstler.package_map import Distribution
17
+
18
+ # %% the package metadata
19
+
20
+
21
+ class ProjectUrlLabel(StrEnum):
22
+ """
23
+ The labels of the ``Project-URL`` entries ``pyproject.toml`` declares.
24
+ """
25
+
26
+ SOURCE = "Source"
27
+ """
28
+ The repository basstler is developed in.
29
+ """
30
+
31
+
32
+ # %% the project
33
+
34
+
35
+ class BasstlerProject:
36
+ """
37
+ Where basstler is developed and released.
38
+ """
39
+
40
+ @classproperty
41
+ def name(cls) -> str:
42
+ """
43
+ The package's name, which also names the tokens and commands it sets up.
44
+ """
45
+ return PackageLocation.DIRECTORY.name
46
+
47
+ @classproperty
48
+ def repository(cls) -> Repository:
49
+ """
50
+ The repository basstler is developed in, whose reusable workflows users' callers
51
+ run.
52
+ """
53
+ return cls._source_repository(Distribution.GITHUB)
54
+
55
+ @classproperty
56
+ def default_branch(cls) -> Branch[Repository]:
57
+ """
58
+ The branch of :attr:`repository` that holds what is developed next.
59
+ """
60
+ return Branch(cls.repository, "main")
61
+
62
+ @staticmethod
63
+ @functools.cache
64
+ def _source_repository(distribution: Distribution) -> Repository:
65
+ """
66
+ :param distribution: The installed distribution whose metadata is read.
67
+ :return: The repository its ``Project-URL`` labels as the source.
68
+ :raises BasstlerSourceUnknown: If the metadata names no source.
69
+ """
70
+ entries = importlib.metadata.metadata(distribution).get_all("Project-URL", [])
71
+ for entry in entries:
72
+ label, _, url = entry.partition(", ")
73
+ if label == ProjectUrlLabel.SOURCE:
74
+ return Repository.from_remote_url(url)
75
+ raise BasstlerSourceUnknown(distribution, tuple(entries))
@@ -0,0 +1,24 @@
1
+ """
2
+ The pair every record about one fork pull request names: its branch and its number.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from dataclasses import dataclass
8
+
9
+
10
+ @dataclass(frozen=True)
11
+ class BranchPullRequest:
12
+ """
13
+ A fork pull request, named by its head branch and its number.
14
+ """
15
+
16
+ branch: str
17
+ """
18
+ The pull request's head branch.
19
+ """
20
+
21
+ pull_request_number: int
22
+ """
23
+ The fork pull request.
24
+ """