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,440 @@
1
+ """
2
+ Writing one file of a repository, directly or proposed for a default branch through a
3
+ pull request.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from dataclasses import dataclass
9
+ from typing import Annotated
10
+
11
+ from pydantic import Field
12
+
13
+ from basstler.class_property import classproperty
14
+ from basstler.git.branch import Branch
15
+ from basstler.github.client import (
16
+ GitHubAttemptClient,
17
+ GitHubCallFailed,
18
+ GitHubResponse,
19
+ HttpMethod,
20
+ RepositoryWrite,
21
+ )
22
+ from basstler.github.git_objects import EncodedContent, GitObject
23
+ from basstler.github.pull_request import NewPullRequest
24
+ from basstler.github.pull_request_form import PullRequestForm
25
+ from basstler.github.wire_form import BranchFullReference, BranchName
26
+ from basstler.github.repository import Repository
27
+ from basstler.github.repository_access import PullRequestListState
28
+ from basstler.github.repository_resources import RepositoryRead, ResourceWrite
29
+ from basstler.github.rest_models import PullRequestPage, RestPullRequestSummary
30
+ from basstler.json_model import ValidatedJSONModel
31
+
32
+ # %% the contents API
33
+
34
+
35
+ class RepositoryFile(GitObject, EncodedContent):
36
+ """
37
+ One file of a repository, as the contents API returns it, standing for the blob it
38
+ holds.
39
+ """
40
+
41
+
42
+ @dataclass(frozen=True)
43
+ class FileRead(RepositoryRead[RepositoryFile]):
44
+ """
45
+ Reads one file of a repository at one revision.
46
+ """
47
+
48
+ file_path_from_repository_root: str
49
+ """
50
+ The file's path from the repository's root.
51
+ """
52
+
53
+ revision: str
54
+ """
55
+ The branch or commit to read it at.
56
+ """
57
+
58
+ @property
59
+ def path(self) -> str:
60
+ return self.repository.contents_path(
61
+ self.file_path_from_repository_root, self.revision
62
+ )
63
+
64
+
65
+ class FileWrite(ResourceWrite[RepositoryFile], EncodedContent):
66
+ """
67
+ Commits one file to a branch of a repository: creates it, or replaces the blob it
68
+ holds.
69
+ """
70
+
71
+ file_path_from_repository_root: Annotated[str, Field(exclude=True)]
72
+ """
73
+ The file's path from the repository's root.
74
+ """
75
+
76
+ message: str
77
+ """
78
+ The commit's message.
79
+ """
80
+
81
+ branch: Annotated[Branch[Repository], BranchName()]
82
+ """
83
+ The branch the commit is made on.
84
+ """
85
+
86
+ replaced_object_hash: Annotated[
87
+ str | None, Field(alias="sha", exclude_if=lambda value: value is None)
88
+ ] = None
89
+ """
90
+ The blob the file holds now, which the API requires to replace it; ``None`` when
91
+ the file is created.
92
+ """
93
+
94
+ @classproperty
95
+ def method(cls) -> HttpMethod:
96
+ return HttpMethod.PUT
97
+
98
+ @property
99
+ def path(self) -> str:
100
+ return self.repository.contents_path(self.file_path_from_repository_root)
101
+
102
+
103
+ @dataclass(frozen=True)
104
+ class FileCommit:
105
+ """
106
+ One file's whole content, committed to a branch of a repository.
107
+ """
108
+
109
+ branch: Branch[Repository]
110
+ """
111
+ The branch holding the file.
112
+ """
113
+
114
+ file_path_from_repository_root: str
115
+ """
116
+ The file's path from the repository's root.
117
+ """
118
+
119
+ text: str
120
+ """
121
+ The file's whole content.
122
+ """
123
+
124
+ message: str
125
+ """
126
+ The commit's message.
127
+ """
128
+
129
+ def read_at(self, revision: str) -> FileRead:
130
+ """
131
+ :param revision: The branch or commit to read the file at.
132
+ :return: The read of the file there.
133
+ """
134
+ return FileRead(
135
+ self.branch.repository, self.file_path_from_repository_root, revision
136
+ )
137
+
138
+ def write_replacing(self, current: RepositoryFile | None) -> FileWrite:
139
+ """
140
+ :param current: The file on :attr:`branch` now, ``None`` when there is none.
141
+ :return: The write making the file hold :attr:`text`.
142
+ """
143
+ return FileWrite(
144
+ repository=self.branch.repository,
145
+ file_path_from_repository_root=self.file_path_from_repository_root,
146
+ message=self.message,
147
+ content=EncodedContent.encode(self.text),
148
+ branch=self.branch,
149
+ replaced_object_hash=None if current is None else current.object_hash,
150
+ )
151
+
152
+
153
+ # %% branches and pull requests
154
+
155
+
156
+ class BranchReference(ValidatedJSONModel):
157
+ """
158
+ A git reference naming one branch, as the git references API reads and writes it.
159
+ """
160
+
161
+ branch: Annotated[Branch[Repository], Field(alias="ref"), BranchFullReference()]
162
+ """
163
+ The branch the reference names.
164
+ """
165
+
166
+
167
+ class ExistingBranch(BranchReference):
168
+ """
169
+ A branch of a repository, as the git references API returns it.
170
+ """
171
+
172
+ target: Annotated[GitObject, Field(alias="object")]
173
+ """
174
+ The commit the branch points at.
175
+ """
176
+
177
+
178
+ @dataclass(frozen=True)
179
+ class BranchReferenceRead(RepositoryRead[ExistingBranch]):
180
+ """
181
+ Reads where one branch of a repository points.
182
+ """
183
+
184
+ branch: Branch[Repository]
185
+ """
186
+ The branch.
187
+ """
188
+
189
+ @property
190
+ def path(self) -> str:
191
+ return self.repository.branch_reference_path(self.branch)
192
+
193
+
194
+ class NewBranch(RepositoryWrite, BranchReference):
195
+ """
196
+ A branch that does not exist yet, starting at one commit.
197
+ """
198
+
199
+ start_commit: Annotated[str, Field(alias="sha")]
200
+ """
201
+ The hash of the commit the branch starts at.
202
+ """
203
+
204
+ @classproperty
205
+ def method(cls) -> HttpMethod:
206
+ return HttpMethod.POST
207
+
208
+ @property
209
+ def path(self) -> str:
210
+ return self.repository.git_references_path
211
+
212
+
213
+ # %% proposing the file
214
+
215
+
216
+ @dataclass(frozen=True)
217
+ class ProposalOutcome:
218
+ """
219
+ What proposing a file came to.
220
+ """
221
+
222
+ pull_request: PullRequestPage | None = None
223
+ """
224
+ The pull request proposing the file, ``None`` when none could be opened.
225
+ """
226
+
227
+ opened_now: bool = False
228
+ """
229
+ Whether this proposal opened it, rather than finding it open.
230
+ """
231
+
232
+ failure: GitHubCallFailed | None = None
233
+ """
234
+ Why no pull request could be opened, ``None`` otherwise.
235
+ """
236
+
237
+ form_url: str = ""
238
+ """
239
+ GitHub's form opening the pull request with everything filled in, when the branch
240
+ holds the file but the pull request could not be opened; empty otherwise.
241
+ """
242
+
243
+ merges_into: Branch[Repository] | None = None
244
+ """
245
+ The branch the pull request merges into, when it is another than the base; ``None``
246
+ otherwise.
247
+ """
248
+
249
+
250
+ @dataclass(frozen=True)
251
+ class FileProposal:
252
+ """
253
+ One file proposed for a repository's default branch: committed to a branch of its
254
+ own, on that repository or on a fork of it, and opened as a pull request a reviewer
255
+ merges.
256
+ """
257
+
258
+ commit: FileCommit
259
+ """
260
+ The file, committed to the branch that carries it; its message is the pull
261
+ request's title.
262
+ """
263
+
264
+ base: Branch[Repository]
265
+ """
266
+ The default branch the file is proposed for, on the repository the pull request is
267
+ opened on.
268
+ """
269
+
270
+ description: str
271
+ """
272
+ The pull request's description, in Markdown.
273
+ """
274
+
275
+ @property
276
+ def opening(self) -> NewPullRequest:
277
+ """
278
+ The pull request proposing the file, titled with the commit's message and
279
+ opened ready to merge.
280
+ """
281
+ return NewPullRequest(
282
+ self.base,
283
+ self.commit.branch,
284
+ self.commit.message,
285
+ self.description,
286
+ draft=False,
287
+ )
288
+
289
+ @property
290
+ def form(self) -> PullRequestForm:
291
+ """
292
+ The form opening :attr:`opening`, with its title and description filled in.
293
+ """
294
+ opening = self.opening
295
+ return PullRequestForm(opening.base, opening.head, opening.title, opening.body)
296
+
297
+ @property
298
+ def open_pull_requests_path(self) -> str:
299
+ """
300
+ The REST path listing every open pull request on the base's repository.
301
+ """
302
+ return PullRequestListState.OPEN.path_on(self.base.repository)
303
+
304
+ @property
305
+ def open_from_branch_path(self) -> str:
306
+ """
307
+ The REST path listing the open pull requests from the commit's branch into
308
+ :attr:`base`.
309
+ """
310
+ return PullRequestListState.OPEN.path_between(self.opening)
311
+
312
+ def propose(self, client: GitHubAttemptClient) -> ProposalOutcome:
313
+ """
314
+ Find an open pull request carrying the file, else put the file on the commit's
315
+ branch and open a pull request for it, unless one is open already.
316
+
317
+ :param client: Reads and writes both repositories.
318
+ :return: The pull request, or why none could be opened.
319
+ """
320
+ carrying = self._pull_request_carrying(client)
321
+ if carrying is not None:
322
+ merges_into = carrying.base
323
+ return ProposalOutcome(
324
+ carrying,
325
+ merges_into=None if merges_into.name == self.base.name else merges_into,
326
+ )
327
+ from_branch = client.attempt_get(self.open_from_branch_path)
328
+ failed = (
329
+ from_branch if from_branch.failure is not None else None
330
+ ) or self._put_on_branch(client)
331
+ if failed is not None:
332
+ return ProposalOutcome(failure=failed.failure)
333
+ if from_branch.body:
334
+ return ProposalOutcome(PullRequestPage.from_json(from_branch.body[0]))
335
+ return self._open_pull_request(client)
336
+
337
+ def _pull_request_carrying(
338
+ self, client: GitHubAttemptClient
339
+ ) -> RestPullRequestSummary | None:
340
+ """
341
+ :param client: Reads the repository.
342
+ :return: The open pull request from another branch than the commit's whose
343
+ head holds the file with this content and which is not stacked on another
344
+ such pull request, ``None`` when none does or they cannot be read.
345
+ """
346
+ listed = client.attempt_get(self.open_pull_requests_path)
347
+ if listed.failure is not None:
348
+ return None
349
+ carrying = [
350
+ pull_request
351
+ for pull_request in map(RestPullRequestSummary.from_json, listed.body)
352
+ if pull_request.head.name != self.commit.branch.name
353
+ and self._held_by(client, pull_request)
354
+ ]
355
+ heads = {pull_request.head.name for pull_request in carrying}
356
+ lowest = [
357
+ pull_request
358
+ for pull_request in carrying
359
+ if pull_request.base.name not in heads
360
+ ]
361
+ return lowest[0] if lowest else None
362
+
363
+ def _held_by(
364
+ self, client: GitHubAttemptClient, pull_request: RestPullRequestSummary
365
+ ) -> bool:
366
+ """
367
+ :param client: Reads the repository.
368
+ :param pull_request: An open pull request.
369
+ :return: Whether its head holds the file with this content.
370
+ """
371
+ held = FileRead(
372
+ self.base.repository,
373
+ self.commit.file_path_from_repository_root,
374
+ pull_request.head.commit,
375
+ ).attempt(client)
376
+ return held.resource is not None and held.resource.text == self.commit.text
377
+
378
+ def _put_on_branch(self, client: GitHubAttemptClient) -> GitHubResponse | None:
379
+ """
380
+ Start the commit's branch when it does not exist, then commit the file to it.
381
+
382
+ :param client: Reads and writes the repository carrying the branch.
383
+ :return: The answer that failed, ``None`` once the branch holds the file.
384
+ """
385
+ return self._create_branch(client) or self._write_file(client)
386
+
387
+ def _create_branch(self, client: GitHubAttemptClient) -> GitHubResponse | None:
388
+ """
389
+ Start the commit's branch at :attr:`base`'s head when it does not exist.
390
+
391
+ :param client: Reads and writes the repository carrying the branch.
392
+ :return: The answer that failed, ``None`` when the branch exists now.
393
+ """
394
+ carrier = self.commit.branch.repository
395
+ existing = BranchReferenceRead(carrier, self.commit.branch).attempt(client)
396
+ if existing.resource is not None:
397
+ return None
398
+ if not existing.response.is_not_found:
399
+ return existing.response
400
+ base = BranchReferenceRead(self.base.repository, self.base).attempt(client)
401
+ if base.resource is None:
402
+ return base.response
403
+ created = client.attempt_send(
404
+ NewBranch(
405
+ repository=carrier,
406
+ branch=self.commit.branch,
407
+ start_commit=base.resource.target.object_hash,
408
+ )
409
+ )
410
+ return created if created.failure is not None else None
411
+
412
+ def _write_file(self, client: GitHubAttemptClient) -> GitHubResponse | None:
413
+ """
414
+ Commit the file to the commit's branch unless it holds this content already.
415
+
416
+ :param client: Reads and writes the repository carrying the branch.
417
+ :return: The answer that failed, ``None`` when the branch holds the file now.
418
+ """
419
+ existing = self.commit.read_at(self.commit.branch.name).attempt(client)
420
+ if existing.resource is None and not existing.response.is_not_found:
421
+ return existing.response
422
+ if existing.resource is not None and existing.resource.text == self.commit.text:
423
+ return None
424
+ written = client.attempt_send(self.commit.write_replacing(existing.resource))
425
+ return written if written.failure is not None else None
426
+
427
+ def _open_pull_request(self, client: GitHubAttemptClient) -> ProposalOutcome:
428
+ """
429
+ :param client: Opens pull requests on the base's repository.
430
+ :return: The pull request opened, or the form that opens it when GitHub
431
+ refuses.
432
+ """
433
+ opened = client.attempt_send(self.opening)
434
+ if opened.failure is not None:
435
+ link = self.form.link
436
+ return ProposalOutcome(
437
+ failure=opened.failure,
438
+ form_url="" if link is None else link.url,
439
+ )
440
+ return ProposalOutcome(PullRequestPage.from_json(opened.body), opened_now=True)
@@ -0,0 +1,44 @@
1
+ """
2
+ Bringing a fork's branch up to date with its parent's by moving it forward.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from typing import Annotated
8
+
9
+ from pydantic import Field
10
+
11
+ from basstler.class_property import classproperty
12
+ from basstler.git.branch import Branch
13
+ from basstler.github.client import HttpMethod
14
+ from basstler.github.file_proposal import ExistingBranch
15
+ from basstler.github.git_objects import GitObject
16
+ from basstler.github.repository import Repository
17
+ from basstler.github.repository_resources import SettingWrite
18
+ from basstler.github.user_steps import SyncFork, UserStep
19
+
20
+ # %% moving a fork's branch forward
21
+
22
+
23
+ class ForkFastForward(SettingWrite[ExistingBranch], GitObject):
24
+ """
25
+ Moves a fork's branch forward to a commit of its parent's, the object it stands for;
26
+ GitHub refuses it unless the branch's commit is an ancestor of that commit.
27
+ """
28
+
29
+ branch: Annotated[Branch[Repository], Field(exclude=True)]
30
+ """
31
+ The fork's branch.
32
+ """
33
+
34
+ @classproperty
35
+ def method(cls) -> HttpMethod:
36
+ return HttpMethod.PATCH
37
+
38
+ @property
39
+ def path(self) -> str:
40
+ return self.repository.branch_update_path(self.branch)
41
+
42
+ @property
43
+ def manual_step(self) -> UserStep:
44
+ return SyncFork(self.repository)
@@ -0,0 +1,57 @@
1
+ """
2
+ The git objects GitHub's REST resources name by their hash, and the file content they
3
+ carry encoded.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import base64
9
+ from typing import Annotated
10
+
11
+ from pydantic import Field
12
+
13
+ from basstler.json_model import ValidatedJSONModel
14
+
15
+ # %% objects
16
+
17
+
18
+ class GitObject(ValidatedJSONModel):
19
+ """
20
+ A resource standing for one git object - a commit, a blob - which GitHub names by
21
+ its hash.
22
+ """
23
+
24
+ object_hash: Annotated[str, Field(alias="sha")]
25
+ """
26
+ The git object's hash.
27
+ """
28
+
29
+
30
+ # %% content
31
+
32
+
33
+ class EncodedContent(ValidatedJSONModel):
34
+ """
35
+ A resource carrying a file's content, base64-encoded as the contents API reads and
36
+ writes it.
37
+ """
38
+
39
+ content: str
40
+ """
41
+ The file's content, base64-encoded, with line breaks where GitHub returns it.
42
+ """
43
+
44
+ @property
45
+ def text(self) -> str:
46
+ """
47
+ The file's content, decoded.
48
+ """
49
+ return base64.b64decode(self.content).decode()
50
+
51
+ @staticmethod
52
+ def encode(text: str) -> str:
53
+ """
54
+ :param text: A file's whole content.
55
+ :return: *text*, base64-encoded as the contents API takes it.
56
+ """
57
+ return base64.b64encode(text.encode()).decode()
@@ -0,0 +1,101 @@
1
+ """
2
+ The shapes of GitHub's GraphQL API: the lists it returns, the requests sent to it and
3
+ its answers to them.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from typing import Annotated, Any, TypeVar
9
+
10
+ from basstler.class_property import classproperty
11
+ from basstler.github.client import GitHubWrite, HttpMethod
12
+ from basstler.github.exceptions import GraphQLErrorsReturned
13
+ from basstler.json_model import RawValueReader, ValidatedJSONModel
14
+
15
+ # %% connections
16
+
17
+
18
+ class GraphQLNodes(RawValueReader):
19
+ """
20
+ Reads a GraphQL connection, which holds a list-valued field's entries under
21
+ ``nodes``, as those entries.
22
+ """
23
+
24
+ def read(self, value: dict[str, Any] | list[Any]) -> list[Any]:
25
+ if isinstance(value, list):
26
+ return value
27
+ return value["nodes"]
28
+
29
+
30
+ Node = TypeVar("Node")
31
+ """
32
+ Whatever model the entries of a connection are parsed into.
33
+ """
34
+
35
+ GraphQLConnection = Annotated[list[Node], GraphQLNodes()]
36
+ """
37
+ A list-valued GraphQL field, which GitHub returns as a connection.
38
+ """
39
+
40
+
41
+ # %% requests and their answers
42
+
43
+
44
+ class GraphQLRequest(GitHubWrite):
45
+ """
46
+ One GraphQL document, a query or a mutation, sent to GitHub's GraphQL endpoint.
47
+ """
48
+
49
+ query: str
50
+ """
51
+ The GraphQL document.
52
+ """
53
+
54
+ variables: dict[str, Any]
55
+ """
56
+ The document's variables.
57
+ """
58
+
59
+ @classproperty
60
+ def method(cls) -> HttpMethod:
61
+ return HttpMethod.POST
62
+
63
+ @property
64
+ def path(self) -> str:
65
+ return "graphql"
66
+
67
+
68
+ class GraphQLError(ValidatedJSONModel):
69
+ """
70
+ One error GitHub reports for a GraphQL request.
71
+ """
72
+
73
+ message: str
74
+ """
75
+ What went wrong.
76
+ """
77
+
78
+
79
+ class GraphQLResponse(ValidatedJSONModel):
80
+ """
81
+ GitHub's answer to a GraphQL request.
82
+ """
83
+
84
+ data: dict[str, Any] | None = None
85
+ """
86
+ The request's result, absent when it failed outright.
87
+ """
88
+
89
+ errors: tuple[GraphQLError, ...] = ()
90
+ """
91
+ The errors reported, none when the request succeeded.
92
+ """
93
+
94
+ def result(self) -> dict[str, Any]:
95
+ """
96
+ :return: The request's result.
97
+ :raises GraphQLErrorsReturned: If GitHub reported errors instead.
98
+ """
99
+ if self.errors:
100
+ raise GraphQLErrorsReturned(tuple(error.message for error in self.errors))
101
+ return self.data or {}