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.
- basstler/github/__init__.py +0 -0
- basstler/github/actions_budget.py +428 -0
- basstler/github/actions_secret.py +25 -0
- basstler/github/actions_settings.py +162 -0
- basstler/github/actions_usage.py +297 -0
- basstler/github/basstler_project.py +75 -0
- basstler/github/branch_pull_request.py +24 -0
- basstler/github/client.py +452 -0
- basstler/github/comparison.py +60 -0
- basstler/github/constants.py +197 -0
- basstler/github/credential.py +85 -0
- basstler/github/exceptions.py +264 -0
- basstler/github/file_proposal.py +440 -0
- basstler/github/fork_sync.py +44 -0
- basstler/github/git_objects.py +57 -0
- basstler/github/graphql.py +101 -0
- basstler/github/issue.py +221 -0
- basstler/github/label.py +78 -0
- basstler/github/login_lending.py +46 -0
- basstler/github/main_failure.py +289 -0
- basstler/github/permission_level.py +33 -0
- basstler/github/pull_request.py +74 -0
- basstler/github/pull_request_changes.py +141 -0
- basstler/github/pull_request_description.py +145 -0
- basstler/github/pull_request_ends.py +58 -0
- basstler/github/pull_request_form.py +136 -0
- basstler/github/pull_request_models.py +321 -0
- basstler/github/pull_request_record.py +369 -0
- basstler/github/pull_request_source.py +395 -0
- basstler/github/pull_request_state.py +437 -0
- basstler/github/queries/pull_request_for_branch.graphql +17 -0
- basstler/github/queries/review_threads_page.graphql +72 -0
- basstler/github/query_documents.py +37 -0
- basstler/github/release_version.py +565 -0
- basstler/github/remote.py +36 -0
- basstler/github/repository.py +532 -0
- basstler/github/repository_access.py +459 -0
- basstler/github/repository_attachment.py +95 -0
- basstler/github/repository_details.py +98 -0
- basstler/github/repository_option.py +43 -0
- basstler/github/repository_resources.py +133 -0
- basstler/github/rest_models.py +353 -0
- basstler/github/review_models.py +223 -0
- basstler/github/run_listing.py +148 -0
- basstler/github/stack_configuration.py +178 -0
- basstler/github/states.py +257 -0
- basstler/github/token_form.py +360 -0
- basstler/github/tooling_labels.py +83 -0
- basstler/github/user_steps.py +170 -0
- basstler/github/web_form.py +56 -0
- basstler/github/web_page.py +33 -0
- basstler/github/wire_form.py +159 -0
- basstler/github/workflow_run.py +126 -0
- basstler/github/workflows.py +561 -0
- basstler/templates/actions_budget.py.jinja +26 -0
- basstler_github-4.2.0.dist-info/METADATA +16 -0
- basstler_github-4.2.0.dist-info/RECORD +60 -0
- basstler_github-4.2.0.dist-info/WHEEL +4 -0
- basstler_github-4.2.0.dist-info/licenses/LICENSE +202 -0
- 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
|
+
"""
|