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,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
+ """