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,360 @@
|
|
|
1
|
+
"""
|
|
2
|
+
GitHub's form for a new fine-grained personal access token, filled in from its address.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
from abc import ABC
|
|
8
|
+
from collections.abc import Mapping
|
|
9
|
+
from dataclasses import dataclass, field
|
|
10
|
+
|
|
11
|
+
from basstler.class_property import classproperty
|
|
12
|
+
from basstler.github.actions_secret import ActionsSecret
|
|
13
|
+
from basstler.github.permission_level import PermissionLevel
|
|
14
|
+
from basstler.github.repository import HasRepository, NewTokenPage, Repository
|
|
15
|
+
from basstler.github.user_steps import UserStep
|
|
16
|
+
from basstler.github.web_form import PrefilledForm, UrlQueryParameter
|
|
17
|
+
from basstler.locations import GitHubTemplate
|
|
18
|
+
from basstler.render_common import TemplatePage
|
|
19
|
+
|
|
20
|
+
# %% the form's parameters
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
class TokenFormParameter(UrlQueryParameter):
|
|
24
|
+
"""
|
|
25
|
+
The query parameters GitHub fills the form's fields from, other than permissions.
|
|
26
|
+
"""
|
|
27
|
+
|
|
28
|
+
NAME = "name"
|
|
29
|
+
"""
|
|
30
|
+
The token's name, at most 40 characters.
|
|
31
|
+
"""
|
|
32
|
+
|
|
33
|
+
DESCRIPTION = "description"
|
|
34
|
+
"""
|
|
35
|
+
The token's description.
|
|
36
|
+
"""
|
|
37
|
+
|
|
38
|
+
RESOURCE_OWNER = "target_name"
|
|
39
|
+
"""
|
|
40
|
+
The user or organisation whose repositories the token reaches.
|
|
41
|
+
"""
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class RepositoryPermission(UrlQueryParameter):
|
|
45
|
+
"""
|
|
46
|
+
The repository permissions the form takes as query parameters.
|
|
47
|
+
"""
|
|
48
|
+
|
|
49
|
+
ACTIONS = "actions"
|
|
50
|
+
"""
|
|
51
|
+
The repository's workflows and their runs.
|
|
52
|
+
"""
|
|
53
|
+
|
|
54
|
+
CONTENTS = "contents"
|
|
55
|
+
"""
|
|
56
|
+
The repository's files and commits.
|
|
57
|
+
"""
|
|
58
|
+
|
|
59
|
+
PULL_REQUESTS = "pull_requests"
|
|
60
|
+
"""
|
|
61
|
+
The repository's pull requests, their reviews and their files' viewed state.
|
|
62
|
+
"""
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
# %% the filled-in form
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
@dataclass(frozen=True)
|
|
69
|
+
class FineGrainedTokenForm(PrefilledForm):
|
|
70
|
+
"""
|
|
71
|
+
The form with a token's name, description, owner and permissions filled in; the
|
|
72
|
+
repositories it reaches the form cannot be given.
|
|
73
|
+
"""
|
|
74
|
+
|
|
75
|
+
name: str
|
|
76
|
+
"""
|
|
77
|
+
The token's name, at most 40 characters.
|
|
78
|
+
"""
|
|
79
|
+
|
|
80
|
+
description: str
|
|
81
|
+
"""
|
|
82
|
+
What the token is for.
|
|
83
|
+
"""
|
|
84
|
+
|
|
85
|
+
resource_owner: str
|
|
86
|
+
"""
|
|
87
|
+
The user or organisation whose repositories the token reaches.
|
|
88
|
+
"""
|
|
89
|
+
|
|
90
|
+
permissions: dict[RepositoryPermission, PermissionLevel] = field(
|
|
91
|
+
default_factory=dict
|
|
92
|
+
)
|
|
93
|
+
"""
|
|
94
|
+
The access granted on each permission; any other is left without access.
|
|
95
|
+
"""
|
|
96
|
+
|
|
97
|
+
@property
|
|
98
|
+
def page_url(self) -> str:
|
|
99
|
+
return NewTokenPage.FINE_GRAINED.url
|
|
100
|
+
|
|
101
|
+
@property
|
|
102
|
+
def filled_fields(self) -> Mapping[UrlQueryParameter, str]:
|
|
103
|
+
return {
|
|
104
|
+
TokenFormParameter.NAME: self.name,
|
|
105
|
+
TokenFormParameter.DESCRIPTION: self.description,
|
|
106
|
+
TokenFormParameter.RESOURCE_OWNER: self.resource_owner,
|
|
107
|
+
**self.permissions,
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
# %% one token for several jobs
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
@dataclass(frozen=True)
|
|
115
|
+
class TokenUse:
|
|
116
|
+
"""
|
|
117
|
+
One job a person's fine-grained token does, and the secret it is stored as.
|
|
118
|
+
"""
|
|
119
|
+
|
|
120
|
+
purpose: str
|
|
121
|
+
"""
|
|
122
|
+
What the token does for this job, as a phrase completing "it ...".
|
|
123
|
+
"""
|
|
124
|
+
|
|
125
|
+
repositories: tuple[Repository, ...]
|
|
126
|
+
"""
|
|
127
|
+
The repositories the job reaches, all of one owner.
|
|
128
|
+
"""
|
|
129
|
+
|
|
130
|
+
permissions: dict[RepositoryPermission, PermissionLevel]
|
|
131
|
+
"""
|
|
132
|
+
The access the job needs on each permission.
|
|
133
|
+
"""
|
|
134
|
+
|
|
135
|
+
secret: ActionsSecret
|
|
136
|
+
"""
|
|
137
|
+
The Actions secret the job's workflows read the token from.
|
|
138
|
+
"""
|
|
139
|
+
|
|
140
|
+
stored_on: tuple[Repository, ...]
|
|
141
|
+
"""
|
|
142
|
+
The repositories whose Actions read :attr:`secret`.
|
|
143
|
+
"""
|
|
144
|
+
|
|
145
|
+
@property
|
|
146
|
+
def resource_owner(self) -> str:
|
|
147
|
+
"""
|
|
148
|
+
The user or organisation whose repositories the job reaches.
|
|
149
|
+
"""
|
|
150
|
+
return self.repositories[0].owner
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
@dataclass(frozen=True)
|
|
154
|
+
class StoredSecret(HasRepository):
|
|
155
|
+
"""
|
|
156
|
+
One Actions secret a token is stored as, on one repository.
|
|
157
|
+
"""
|
|
158
|
+
|
|
159
|
+
secret: ActionsSecret
|
|
160
|
+
"""
|
|
161
|
+
The secret's name.
|
|
162
|
+
"""
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
@dataclass(frozen=True)
|
|
166
|
+
class SharedToken(TemplatePage):
|
|
167
|
+
"""
|
|
168
|
+
One fine-grained token doing several jobs on one owner's repositories.
|
|
169
|
+
"""
|
|
170
|
+
|
|
171
|
+
name: str
|
|
172
|
+
"""
|
|
173
|
+
The token's name, at most 40 characters.
|
|
174
|
+
"""
|
|
175
|
+
|
|
176
|
+
uses: tuple[TokenUse, ...]
|
|
177
|
+
"""
|
|
178
|
+
The jobs, all reaching one owner's repositories; the first is the one asked for.
|
|
179
|
+
"""
|
|
180
|
+
|
|
181
|
+
@classmethod
|
|
182
|
+
def from_requested_use(
|
|
183
|
+
cls,
|
|
184
|
+
name: str,
|
|
185
|
+
requested_use: TokenUse,
|
|
186
|
+
candidate_uses: tuple[TokenUse, ...] = (),
|
|
187
|
+
) -> SharedToken:
|
|
188
|
+
"""
|
|
189
|
+
:param name: The token's name.
|
|
190
|
+
:param requested_use: The job the token is asked for.
|
|
191
|
+
:param candidate_uses: Further jobs, joined where they reach the same owner.
|
|
192
|
+
:return: The token doing *requested_use* and every candidate one token can do
|
|
193
|
+
with it.
|
|
194
|
+
"""
|
|
195
|
+
return cls(
|
|
196
|
+
name,
|
|
197
|
+
(
|
|
198
|
+
requested_use,
|
|
199
|
+
*(
|
|
200
|
+
use
|
|
201
|
+
for use in candidate_uses
|
|
202
|
+
if use.resource_owner == requested_use.resource_owner
|
|
203
|
+
),
|
|
204
|
+
),
|
|
205
|
+
)
|
|
206
|
+
|
|
207
|
+
@classproperty
|
|
208
|
+
def template(cls) -> str:
|
|
209
|
+
return GitHubTemplate.SHARED_TOKEN_STORE_COMMAND.name
|
|
210
|
+
|
|
211
|
+
@property
|
|
212
|
+
def form(self) -> FineGrainedTokenForm:
|
|
213
|
+
"""
|
|
214
|
+
The form creating the token, granting each permission the broadest level a job
|
|
215
|
+
needs.
|
|
216
|
+
"""
|
|
217
|
+
permissions = {
|
|
218
|
+
permission: PermissionLevel.broadest(
|
|
219
|
+
[
|
|
220
|
+
use.permissions[permission]
|
|
221
|
+
for use in self.uses
|
|
222
|
+
if permission in use.permissions
|
|
223
|
+
]
|
|
224
|
+
)
|
|
225
|
+
for use in self.uses
|
|
226
|
+
for permission in use.permissions
|
|
227
|
+
}
|
|
228
|
+
return FineGrainedTokenForm(
|
|
229
|
+
self.name,
|
|
230
|
+
self.description,
|
|
231
|
+
self.uses[0].resource_owner,
|
|
232
|
+
permissions,
|
|
233
|
+
)
|
|
234
|
+
|
|
235
|
+
@property
|
|
236
|
+
def description(self) -> str:
|
|
237
|
+
"""
|
|
238
|
+
What the token does, every job's purpose in turn.
|
|
239
|
+
"""
|
|
240
|
+
purposes = "; ".join(use.purpose for use in self.uses)
|
|
241
|
+
return f"{purposes[0].upper()}{purposes[1:]}"
|
|
242
|
+
|
|
243
|
+
@property
|
|
244
|
+
def selection(self) -> str:
|
|
245
|
+
"""
|
|
246
|
+
The repositories to select under the form's repository access, as a phrase.
|
|
247
|
+
"""
|
|
248
|
+
names = [repository.full_name for repository in self.repositories]
|
|
249
|
+
if len(names) == 1:
|
|
250
|
+
return names[0]
|
|
251
|
+
return f"{', '.join(names[:-1])} and {names[-1]}"
|
|
252
|
+
|
|
253
|
+
@property
|
|
254
|
+
def repositories(self) -> list[Repository]:
|
|
255
|
+
"""
|
|
256
|
+
Every repository a job reaches, each once, in the order the jobs name them.
|
|
257
|
+
"""
|
|
258
|
+
return list(
|
|
259
|
+
dict.fromkeys(
|
|
260
|
+
repository for use in self.uses for repository in use.repositories
|
|
261
|
+
)
|
|
262
|
+
)
|
|
263
|
+
|
|
264
|
+
@property
|
|
265
|
+
def secrets(self) -> list[StoredSecret]:
|
|
266
|
+
"""
|
|
267
|
+
Each secret the token is stored as.
|
|
268
|
+
"""
|
|
269
|
+
return [
|
|
270
|
+
StoredSecret(repository=repository, secret=use.secret)
|
|
271
|
+
for use in self.uses
|
|
272
|
+
for repository in use.stored_on
|
|
273
|
+
]
|
|
274
|
+
|
|
275
|
+
@property
|
|
276
|
+
def store_command(self) -> str:
|
|
277
|
+
"""
|
|
278
|
+
The command storing the token as every secret in :attr:`secrets`, asking for it
|
|
279
|
+
once.
|
|
280
|
+
"""
|
|
281
|
+
if len(self.secrets) == 1:
|
|
282
|
+
(stored,) = self.secrets
|
|
283
|
+
return f"gh secret set {stored.secret} --repo {stored.repository.full_name}"
|
|
284
|
+
return self.render_template(secrets=self.secrets).strip()
|
|
285
|
+
|
|
286
|
+
|
|
287
|
+
# %% the steps only the user can take
|
|
288
|
+
|
|
289
|
+
|
|
290
|
+
@dataclass(frozen=True)
|
|
291
|
+
class TokenStep(UserStep, ABC):
|
|
292
|
+
"""
|
|
293
|
+
A step of creating or storing a shared token, which may have been taken before.
|
|
294
|
+
"""
|
|
295
|
+
|
|
296
|
+
token: SharedToken
|
|
297
|
+
"""
|
|
298
|
+
The token.
|
|
299
|
+
"""
|
|
300
|
+
|
|
301
|
+
may_be_done: bool = False
|
|
302
|
+
"""
|
|
303
|
+
Whether the step may have been taken already, as when its secret could not be read.
|
|
304
|
+
"""
|
|
305
|
+
|
|
306
|
+
@property
|
|
307
|
+
def condition(self) -> str:
|
|
308
|
+
"""
|
|
309
|
+
The clause leading :attr:`description`, empty when the step is known to be left.
|
|
310
|
+
"""
|
|
311
|
+
return "unless it is stored already, " if self.may_be_done else ""
|
|
312
|
+
|
|
313
|
+
|
|
314
|
+
@dataclass(frozen=True)
|
|
315
|
+
class CreateToken(TokenStep):
|
|
316
|
+
"""
|
|
317
|
+
Creating the token from its filled-in form.
|
|
318
|
+
"""
|
|
319
|
+
|
|
320
|
+
@property
|
|
321
|
+
def description(self) -> str:
|
|
322
|
+
purposes = " and ".join(use.purpose for use in self.token.uses)
|
|
323
|
+
return f"{self.condition}create one token that {purposes}"
|
|
324
|
+
|
|
325
|
+
@property
|
|
326
|
+
def browser_steps(self) -> tuple[str, ...]:
|
|
327
|
+
return (
|
|
328
|
+
f"Open {self.token.form.url} - its name, owner and permissions are filled "
|
|
329
|
+
"in.",
|
|
330
|
+
"Under Repository access, choose Only select repositories and select "
|
|
331
|
+
f"{self.token.selection} alone.",
|
|
332
|
+
"Give it an expiry, click Generate token and copy it; GitHub shows it once.",
|
|
333
|
+
)
|
|
334
|
+
|
|
335
|
+
|
|
336
|
+
@dataclass(frozen=True)
|
|
337
|
+
class StoreToken(TokenStep):
|
|
338
|
+
"""
|
|
339
|
+
Storing the token as every secret its jobs read.
|
|
340
|
+
"""
|
|
341
|
+
|
|
342
|
+
@property
|
|
343
|
+
def description(self) -> str:
|
|
344
|
+
stored = " and ".join(
|
|
345
|
+
f"{entry.secret} on {entry.repository.full_name}"
|
|
346
|
+
for entry in self.token.secrets
|
|
347
|
+
)
|
|
348
|
+
return f"{self.condition}store the token as {stored}"
|
|
349
|
+
|
|
350
|
+
@property
|
|
351
|
+
def browser_steps(self) -> tuple[str, ...]:
|
|
352
|
+
return tuple(
|
|
353
|
+
f"Open {entry.repository.new_actions_secret_url}, set the name to "
|
|
354
|
+
f"{entry.secret}, paste the token, then click Add secret."
|
|
355
|
+
for entry in self.token.secrets
|
|
356
|
+
)
|
|
357
|
+
|
|
358
|
+
@property
|
|
359
|
+
def command(self) -> str | None:
|
|
360
|
+
return self.token.store_command
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
"""
|
|
2
|
+
The GitHub labels this tooling reads or applies, in one table.
|
|
3
|
+
|
|
4
|
+
The plan site reads some of them, a maintenance pass writes one, and setup creates all
|
|
5
|
+
of them on a fork. One enum names them all, so a label one part recognizes cannot be
|
|
6
|
+
missing from the set setup creates.
|
|
7
|
+
|
|
8
|
+
Kept free of third-party imports, so the setup script can read it before the plan site's
|
|
9
|
+
dependencies are installed.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
from enum import StrEnum
|
|
15
|
+
|
|
16
|
+
from basstler.github.repository import Repository
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
class GitHubLabel(StrEnum):
|
|
20
|
+
"""
|
|
21
|
+
Every label this tooling reads or applies, and therefore every one a fork must
|
|
22
|
+
carry, each with the description it is created with.
|
|
23
|
+
|
|
24
|
+
A member is its own label name, so it compares equal to the label as GitHub returns
|
|
25
|
+
it.
|
|
26
|
+
"""
|
|
27
|
+
|
|
28
|
+
purpose: str
|
|
29
|
+
"""
|
|
30
|
+
What the label means, used as its description when it is created.
|
|
31
|
+
"""
|
|
32
|
+
|
|
33
|
+
def __new__(cls, label: str, purpose: str) -> GitHubLabel:
|
|
34
|
+
"""
|
|
35
|
+
Make a member that is its own label name and carries what the label means.
|
|
36
|
+
|
|
37
|
+
:param label: The label's name, as GitHub stores it.
|
|
38
|
+
:param purpose: What it means, used as the description when it is created.
|
|
39
|
+
:return: The member.
|
|
40
|
+
"""
|
|
41
|
+
member = str.__new__(cls, label)
|
|
42
|
+
member._value_ = label
|
|
43
|
+
member.purpose = purpose
|
|
44
|
+
return member
|
|
45
|
+
|
|
46
|
+
MERGED = ("merged", "The changes landed even though GitHub never recorded a merge")
|
|
47
|
+
"""
|
|
48
|
+
Read by the plan site, which treats the label exactly like a real merge.
|
|
49
|
+
"""
|
|
50
|
+
IN_REVIEW = ("in-review", "Under review")
|
|
51
|
+
"""
|
|
52
|
+
Kept in step by a maintenance pass with the open upstream pull request opened from
|
|
53
|
+
the branch.
|
|
54
|
+
"""
|
|
55
|
+
BUG = ("bug", "A bug fix")
|
|
56
|
+
"""
|
|
57
|
+
Applied by a session opening a bug-fix pull request.
|
|
58
|
+
"""
|
|
59
|
+
MAIN_RED = ("main-red", "The tests on the default branch are failing")
|
|
60
|
+
"""
|
|
61
|
+
Applied by the test workflow to the one issue open while the default branch's tests
|
|
62
|
+
fail, and read back to find it.
|
|
63
|
+
"""
|
|
64
|
+
PROMOTION_LINK_SENT = (
|
|
65
|
+
"promotion-link-sent",
|
|
66
|
+
"A maintenance pass has written this branch's upstream create-link",
|
|
67
|
+
)
|
|
68
|
+
"""
|
|
69
|
+
Applied by a maintenance pass to a fork pull request whose link it has built, so a
|
|
70
|
+
later pass does not rebuild it.
|
|
71
|
+
"""
|
|
72
|
+
|
|
73
|
+
def creation_command(self, repository: Repository) -> str:
|
|
74
|
+
"""
|
|
75
|
+
The ``gh`` command that creates this label.
|
|
76
|
+
|
|
77
|
+
:param repository: The repository to create it in.
|
|
78
|
+
:return: The command, ready to paste.
|
|
79
|
+
"""
|
|
80
|
+
return (
|
|
81
|
+
f"gh label create {self.value} --repo {repository.full_name} "
|
|
82
|
+
f'--description "{self.purpose}"'
|
|
83
|
+
)
|
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
"""
|
|
2
|
+
The steps on GitHub only the user can take, each with the browser steps and, where
|
|
3
|
+
GitHub offers one, the command that takes it.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
from abc import ABC, abstractmethod
|
|
9
|
+
from dataclasses import dataclass
|
|
10
|
+
|
|
11
|
+
from basstler.github.workflows import RepositoryWorkflow
|
|
12
|
+
from basstler.github.repository import Repository, HasRepository
|
|
13
|
+
|
|
14
|
+
# %% a step
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class UserStep(ABC):
|
|
18
|
+
"""
|
|
19
|
+
One step only the user can take.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
@property
|
|
23
|
+
@abstractmethod
|
|
24
|
+
def description(self) -> str:
|
|
25
|
+
"""
|
|
26
|
+
What the step does, as a phrase.
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
@property
|
|
30
|
+
@abstractmethod
|
|
31
|
+
def browser_steps(self) -> tuple[str, ...]:
|
|
32
|
+
"""
|
|
33
|
+
The step taken on github.com, one click or entry each, in order.
|
|
34
|
+
"""
|
|
35
|
+
|
|
36
|
+
@property
|
|
37
|
+
def command(self) -> str | None:
|
|
38
|
+
"""
|
|
39
|
+
The command that takes it, ``None`` when GitHub offers none.
|
|
40
|
+
"""
|
|
41
|
+
return None
|
|
42
|
+
|
|
43
|
+
@property
|
|
44
|
+
def text(self) -> str | None:
|
|
45
|
+
"""
|
|
46
|
+
A file the step writes, shown in full, ``None`` when it writes none.
|
|
47
|
+
"""
|
|
48
|
+
return None
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
# %% repository settings
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
@dataclass(frozen=True)
|
|
55
|
+
class AllowActions(HasRepository, UserStep):
|
|
56
|
+
"""
|
|
57
|
+
Allowing a repository to run Actions.
|
|
58
|
+
"""
|
|
59
|
+
|
|
60
|
+
known_off: bool
|
|
61
|
+
"""
|
|
62
|
+
Whether Actions are known to be off there, rather than unread.
|
|
63
|
+
"""
|
|
64
|
+
|
|
65
|
+
@property
|
|
66
|
+
def description(self) -> str:
|
|
67
|
+
if self.known_off:
|
|
68
|
+
return f"allow Actions on {self.repository.full_name}"
|
|
69
|
+
return f"check that {self.repository.full_name} allows Actions"
|
|
70
|
+
|
|
71
|
+
@property
|
|
72
|
+
def browser_steps(self) -> tuple[str, ...]:
|
|
73
|
+
allow = "Allow all actions and reusable workflows, then click Save."
|
|
74
|
+
return (
|
|
75
|
+
f"Open {self.repository.actions_settings_url}.",
|
|
76
|
+
f"Choose {allow}"
|
|
77
|
+
if self.known_off
|
|
78
|
+
else f"If Actions are disabled there: choose {allow}",
|
|
79
|
+
)
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
@dataclass(frozen=True)
|
|
83
|
+
class EnableWorkflow(RepositoryWorkflow, HasRepository, UserStep):
|
|
84
|
+
"""
|
|
85
|
+
Enabling one disabled workflow of a repository.
|
|
86
|
+
"""
|
|
87
|
+
|
|
88
|
+
@property
|
|
89
|
+
def description(self) -> str:
|
|
90
|
+
return f"enable the {self.workflow_path.name} workflow"
|
|
91
|
+
|
|
92
|
+
@property
|
|
93
|
+
def browser_steps(self) -> tuple[str, ...]:
|
|
94
|
+
return (
|
|
95
|
+
f"Open {self.repository.workflow_page_url(self.workflow_path)}.",
|
|
96
|
+
"Click Enable workflow.",
|
|
97
|
+
)
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
# %% pull requests
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
@dataclass(frozen=True)
|
|
104
|
+
class MergePullRequest(UserStep):
|
|
105
|
+
"""
|
|
106
|
+
Reviewing and merging an open pull request.
|
|
107
|
+
"""
|
|
108
|
+
|
|
109
|
+
page_url: str
|
|
110
|
+
"""
|
|
111
|
+
The pull request's page.
|
|
112
|
+
"""
|
|
113
|
+
|
|
114
|
+
change: str
|
|
115
|
+
"""
|
|
116
|
+
What the pull request does, as a phrase completing "the pull request ...".
|
|
117
|
+
"""
|
|
118
|
+
|
|
119
|
+
@property
|
|
120
|
+
def description(self) -> str:
|
|
121
|
+
return f"merge the pull request {self.change}"
|
|
122
|
+
|
|
123
|
+
@property
|
|
124
|
+
def browser_steps(self) -> tuple[str, ...]:
|
|
125
|
+
return (f"Open {self.page_url}.", "Review it, then merge it.")
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
@dataclass(frozen=True)
|
|
129
|
+
class OpenPullRequestFromForm(MergePullRequest):
|
|
130
|
+
"""
|
|
131
|
+
Opening a pull request from its filled-in form, then merging it.
|
|
132
|
+
"""
|
|
133
|
+
|
|
134
|
+
@property
|
|
135
|
+
def description(self) -> str:
|
|
136
|
+
return f"open and {super().description}"
|
|
137
|
+
|
|
138
|
+
@property
|
|
139
|
+
def browser_steps(self) -> tuple[str, ...]:
|
|
140
|
+
return (
|
|
141
|
+
f"Open {self.page_url} - its title and description are filled in.",
|
|
142
|
+
"Click Create pull request, review it, then merge it.",
|
|
143
|
+
)
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
# %% forks
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
@dataclass(frozen=True)
|
|
150
|
+
class SyncFork(UserStep):
|
|
151
|
+
"""
|
|
152
|
+
Bringing a fork's default branch up to date with its parent's.
|
|
153
|
+
"""
|
|
154
|
+
|
|
155
|
+
fork: Repository
|
|
156
|
+
"""
|
|
157
|
+
The fork.
|
|
158
|
+
"""
|
|
159
|
+
|
|
160
|
+
@property
|
|
161
|
+
def description(self) -> str:
|
|
162
|
+
return f"sync {self.fork.full_name}'s default branch with its parent's"
|
|
163
|
+
|
|
164
|
+
@property
|
|
165
|
+
def browser_steps(self) -> tuple[str, ...]:
|
|
166
|
+
return (f"Open {self.fork.url}.", "Click Sync fork, then Update branch.")
|
|
167
|
+
|
|
168
|
+
@property
|
|
169
|
+
def command(self) -> str | None:
|
|
170
|
+
return f"gh repo sync {self.fork.full_name}"
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
"""
|
|
2
|
+
A GitHub page whose fields its address fills in.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
from abc import ABC, abstractmethod
|
|
8
|
+
from collections.abc import Mapping
|
|
9
|
+
from enum import StrEnum
|
|
10
|
+
from urllib.parse import quote, urlencode
|
|
11
|
+
|
|
12
|
+
# %% the fields
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class UrlQueryParameter(StrEnum):
|
|
16
|
+
"""
|
|
17
|
+
A query parameter a GitHub page fills one of its fields from; each form declares its
|
|
18
|
+
own as members of a subclass.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
# %% the form
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
class PrefilledForm(ABC):
|
|
26
|
+
"""
|
|
27
|
+
A GitHub page opened with its fields filled in from its address.
|
|
28
|
+
"""
|
|
29
|
+
|
|
30
|
+
@property
|
|
31
|
+
@abstractmethod
|
|
32
|
+
def page_url(self) -> str:
|
|
33
|
+
"""
|
|
34
|
+
The page's address without any field filled in.
|
|
35
|
+
"""
|
|
36
|
+
|
|
37
|
+
@property
|
|
38
|
+
@abstractmethod
|
|
39
|
+
def filled_fields(self) -> Mapping[UrlQueryParameter, str]:
|
|
40
|
+
"""
|
|
41
|
+
Each field the address fills in, with its value.
|
|
42
|
+
"""
|
|
43
|
+
|
|
44
|
+
@property
|
|
45
|
+
def url(self) -> str:
|
|
46
|
+
"""
|
|
47
|
+
The page's address with every field of :attr:`filled_fields` filled in.
|
|
48
|
+
"""
|
|
49
|
+
return self.url_filling(self.filled_fields)
|
|
50
|
+
|
|
51
|
+
def url_filling(self, fields: Mapping[UrlQueryParameter, str]) -> str:
|
|
52
|
+
"""
|
|
53
|
+
:param fields: The fields to fill in, with their values.
|
|
54
|
+
:return: The page's address filling them in, each value percent-encoded.
|
|
55
|
+
"""
|
|
56
|
+
return f"{self.page_url}?{urlencode(fields, quote_via=quote)}"
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
"""
|
|
2
|
+
A REST resource's own page on GitHub, and links GitHub may report as null.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
from typing import Annotated
|
|
8
|
+
|
|
9
|
+
from pydantic import Field
|
|
10
|
+
|
|
11
|
+
from basstler.json_model import RawValueReader, ValidatedJSONModel
|
|
12
|
+
|
|
13
|
+
# %% links
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class AbsentAsEmpty(RawValueReader):
|
|
17
|
+
"""
|
|
18
|
+
Reads a text GitHub reports as null as empty text.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
def read(self, value: str | None) -> str:
|
|
22
|
+
return value or ""
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
class WebPage(ValidatedJSONModel):
|
|
26
|
+
"""
|
|
27
|
+
A REST resource that has a page of its own on github.com.
|
|
28
|
+
"""
|
|
29
|
+
|
|
30
|
+
page_url: Annotated[str, Field(alias="html_url")]
|
|
31
|
+
"""
|
|
32
|
+
The address of its own page on GitHub.
|
|
33
|
+
"""
|