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,532 @@
1
+ """
2
+ A GitHub repository, identified the way GitHub itself writes it, and read out of the
3
+ references and git remote URLs the tooling is handed.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from dataclasses import dataclass
9
+ from enum import StrEnum
10
+ from pathlib import Path
11
+ from typing import Annotated
12
+ from urllib.parse import urlencode, urlsplit
13
+
14
+ from pydantic import Field
15
+
16
+ from basstler.git.branch import Branch
17
+ from basstler.git.commands import GitCommandRunner
18
+ from basstler.git.repository import GitRepository
19
+
20
+
21
+ class GitHubAddress(StrEnum):
22
+ """
23
+ The GitHub URLs this package builds addresses on or points the user to.
24
+ """
25
+
26
+ WEB = "https://github.com"
27
+ """
28
+ The root of every web URL and of every clone URL reached over HTTPS.
29
+ """
30
+
31
+ API = "https://api.github.com"
32
+ """
33
+ The root of every REST call.
34
+ """
35
+
36
+ SSH = "ssh://git@github.com"
37
+ """
38
+ The root of every clone URL reached over SSH.
39
+ """
40
+
41
+ STATUS = "https://www.githubstatus.com"
42
+ """
43
+ The page where GitHub reports its incidents.
44
+ """
45
+
46
+ @classmethod
47
+ def clone_root_for(cls, remote_url: str) -> GitHubAddress:
48
+ """
49
+ :param remote_url: A git remote URL.
50
+ :return: The root other repositories are reached under over the same transport:
51
+ :attr:`SSH` for an SSH remote, :attr:`WEB` for any other.
52
+ """
53
+ before_path, colon, _ = remote_url.partition(":")
54
+ is_short_ssh_form = (
55
+ bool(colon) and "/" not in before_path and "@" in before_path
56
+ )
57
+ if is_short_ssh_form or urlsplit(remote_url).scheme == urlsplit(cls.SSH).scheme:
58
+ return cls.SSH
59
+ return cls.WEB
60
+
61
+
62
+ class NewTokenPage(StrEnum):
63
+ """
64
+ The signed-in account's forms creating a personal access token, below
65
+ :attr:`GitHubAddress.WEB`.
66
+ """
67
+
68
+ FINE_GRAINED = "settings/personal-access-tokens/new"
69
+ """
70
+ The form creating a fine-grained token.
71
+ """
72
+
73
+ CLASSIC = "settings/tokens/new"
74
+ """
75
+ The form creating a classic token.
76
+ """
77
+
78
+ @property
79
+ def url(self) -> str:
80
+ """
81
+ The form's address.
82
+ """
83
+ return f"{GitHubAddress.WEB}/{self}"
84
+
85
+
86
+ @dataclass
87
+ class MalformedRepositoryError(ValueError):
88
+ """
89
+ Raised when a repository reference is not in ``owner/name`` form.
90
+ """
91
+
92
+ text: str
93
+ """
94
+ The value that could not be parsed.
95
+ """
96
+
97
+ def __str__(self) -> str:
98
+ """:return: What was expected and what arrived instead."""
99
+ return f"expected a repository as 'owner/name', got {self.text!r}"
100
+
101
+
102
+ @dataclass(frozen=True)
103
+ class Repository(GitRepository):
104
+ """
105
+ A GitHub repository, identified the way GitHub itself writes it.
106
+ """
107
+
108
+ owner: str
109
+ """
110
+ The user or organization the repository belongs to.
111
+ """
112
+
113
+ name: str
114
+ """
115
+ The repository's own name.
116
+ """
117
+
118
+ @classmethod
119
+ def parse(cls, text: str) -> Repository:
120
+ """
121
+ Parse an ``owner/name`` repository reference.
122
+
123
+ :param text: The reference to parse.
124
+ :return: The parsed repository.
125
+ :raises MalformedRepositoryError: If *text* is not ``owner/name``.
126
+ """
127
+ if not cls.is_full_name(text):
128
+ raise MalformedRepositoryError(text)
129
+ owner, _, name = text.partition("/")
130
+ return cls(owner, name)
131
+
132
+ @classmethod
133
+ def from_name_or_remote(
134
+ cls, name: str | None, git: GitCommandRunner, remote: str = "origin"
135
+ ) -> Repository:
136
+ """
137
+ :param name: A repository as ``owner/name``, or ``None``.
138
+ :param git: The current checkout.
139
+ :param remote: The remote whose repository is meant when no name is given.
140
+ :return: The repository named, else the one *remote* points at.
141
+ :raises MalformedRepositoryError: If *name* is not ``owner/name``.
142
+ """
143
+ if name:
144
+ return cls.parse(name)
145
+ return cls.from_remote_url(git.run("remote", "get-url", remote))
146
+
147
+ @classmethod
148
+ def from_configured_remote(
149
+ cls, git: GitCommandRunner, remote: str = "origin"
150
+ ) -> Repository:
151
+ """
152
+ :param git: A checkout.
153
+ :param remote: One of its remotes.
154
+ :return: The repository the URL the checkout configures for *remote* names, not
155
+ git's rewrite of that URL.
156
+ """
157
+ return cls.from_remote_url(git.run("config", "--get", f"remote.{remote}.url"))
158
+
159
+ @staticmethod
160
+ def is_full_name(text: str) -> bool:
161
+ """
162
+ :param text: A value that may name a repository.
163
+ :return: Whether *text* is an ``owner/name`` repository reference.
164
+ """
165
+ owner, separator, name = text.partition("/")
166
+ return bool(owner and separator and name)
167
+
168
+ @staticmethod
169
+ def _remote_url_segments(url: str) -> list[str]:
170
+ """
171
+ Split a remote URL into its path segments, discarding scheme and host.
172
+
173
+ :param url: The remote URL to split.
174
+ :return: The path segments, which name a repository when there are two or more.
175
+ """
176
+ reference = url.removesuffix(".git").rstrip("/")
177
+ if "://" in reference:
178
+ _, _, host_and_path = reference.partition("://")
179
+ _, _, path = host_and_path.partition("/")
180
+ elif ":" in reference:
181
+ _, _, path = reference.rpartition(":")
182
+ else:
183
+ return []
184
+ return [segment for segment in path.split("/") if segment]
185
+
186
+ @classmethod
187
+ def names_a_repository(cls, url: str) -> bool:
188
+ """
189
+ Test whether a remote URL points at a repository at all.
190
+
191
+ :param url: The remote URL to test.
192
+ :return: Whether it names an ``owner/name`` pair.
193
+ """
194
+ return len(cls._remote_url_segments(url)) >= 2
195
+
196
+ @classmethod
197
+ def from_remote_url(cls, url: str) -> Repository:
198
+ """
199
+ Read the repository a git remote URL points at.
200
+
201
+ Accepts every form a fork remote takes - HTTPS, SSH, and the local proxy a cloud
202
+ session is given - by discarding the host and taking the last two path segments.
203
+
204
+ :param url: The remote URL to read.
205
+ :return: The repository it names.
206
+ :raises MalformedRepositoryError: If *url* names no ``owner/name`` pair.
207
+ """
208
+ segments = cls._remote_url_segments(url)
209
+ if len(segments) < 2:
210
+ raise MalformedRepositoryError(url)
211
+ return cls.parse("/".join(segments[-2:]))
212
+
213
+ @property
214
+ def full_name(self) -> str:
215
+ """
216
+ The ``owner/name`` form GitHub's own interface and the ``gh`` CLI use.
217
+ """
218
+ return f"{self.owner}/{self.name}"
219
+
220
+ @property
221
+ def url(self) -> str:
222
+ """
223
+ The repository's page on GitHub, which is also the base of every page within it.
224
+ """
225
+ return f"{GitHubAddress.WEB}/{self.full_name}"
226
+
227
+ @property
228
+ def clone_url(self) -> str:
229
+ """
230
+ The HTTPS URL git clones and fetches the repository from.
231
+ """
232
+ return self.clone_url_under()
233
+
234
+ def clone_url_under(self, root: str = GitHubAddress.WEB) -> str:
235
+ """
236
+ :param root: Where repositories are kept as ``<root>/owner/name.git``: GitHub
237
+ itself, or a directory of bare repositories standing in for it.
238
+ :return: The URL git clones and fetches this repository from there.
239
+ """
240
+ return f"{root}/{self.full_name}.git"
241
+
242
+ @property
243
+ def settings_url(self) -> str:
244
+ """
245
+ The repository's settings page, where its visibility is changed.
246
+ """
247
+ return f"{self.url}/settings"
248
+
249
+ def pull_request_url(self, number: int) -> str:
250
+ """
251
+ :param number: The pull request's number.
252
+ :return: The pull request's page on GitHub.
253
+ """
254
+ return f"{self.url}/pull/{number}"
255
+
256
+ def issue_url(self, number: int) -> str:
257
+ """
258
+ :param number: The issue's number.
259
+ :return: The issue's page on GitHub.
260
+ """
261
+ return f"{self.url}/issues/{number}"
262
+
263
+ def workflow_run_url(self, run: int) -> str:
264
+ """
265
+ :param run: The Actions workflow run's own number.
266
+ :return: The run's page on GitHub.
267
+ """
268
+ return f"{self.url}/actions/runs/{run}"
269
+
270
+ @property
271
+ def actions_settings_url(self) -> str:
272
+ """
273
+ The settings page that allows or forbids Actions in the repository.
274
+ """
275
+ return f"{self.settings_url}/actions"
276
+
277
+ def workflow_page_url(self, workflow: Path) -> str:
278
+ """
279
+ :param workflow: The workflow's file in the repository.
280
+ :return: The page listing the workflow's runs, where it is also enabled.
281
+ """
282
+ return f"{self.url}/actions/workflows/{workflow.name}"
283
+
284
+ def file_url(self, branch: Branch, file_path: str) -> str:
285
+ """
286
+ :param branch: The branch holding the file.
287
+ :param file_path: The file's path from the repository's root.
288
+ :return: The file's page, rendered.
289
+ """
290
+ return f"{self.url}/blob/{branch.name}/{file_path}"
291
+
292
+ def compare_url(self, base: Branch[Repository], head: Branch[Repository]) -> str:
293
+ """
294
+ :param base: A branch of this repository.
295
+ :param head: A branch of this repository or of a fork of it.
296
+ :return: The page comparing *head* with *base*.
297
+ """
298
+ return f"{self.url}/compare/{base.name}...{self.head_name(head)}"
299
+
300
+ def head_name(self, head: Branch[Repository]) -> str:
301
+ """
302
+ :param head: A branch of this repository or of a fork of it.
303
+ :return: The branch as a pull request opened on this repository names its
304
+ head: its name on this repository, else its :meth:`branch_label`.
305
+ """
306
+ if head.repository == self:
307
+ return head.name
308
+ return head.repository.branch_label(head)
309
+
310
+ def branch_label(self, branch: Branch[Repository]) -> str:
311
+ """
312
+ :param branch: A branch of this repository.
313
+ :return: The ``owner:branch`` label naming it among the repository and its
314
+ forks.
315
+ """
316
+ return f"{self.owner}:{branch.name}"
317
+
318
+ @property
319
+ def new_actions_secret_url(self) -> str:
320
+ """
321
+ The form on GitHub that adds an Actions secret to the repository.
322
+ """
323
+ return f"{self.settings_url}/secrets/actions/new"
324
+
325
+ @property
326
+ def api_path(self) -> str:
327
+ """
328
+ The repository's REST path, relative to :attr:`GitHubAddress.API`, which is also
329
+ the base of every REST path within it and what ``gh api`` takes.
330
+ """
331
+ return f"repos/{self.full_name}"
332
+
333
+ @property
334
+ def issues_path(self) -> str:
335
+ """
336
+ The REST path of the repository's issues, which lists and opens them.
337
+ """
338
+ return f"{self.api_path}/issues"
339
+
340
+ def issue_path(self, number: int) -> str:
341
+ """
342
+ :param number: The issue's number.
343
+ :return: The REST path of that issue.
344
+ """
345
+ return f"{self.issues_path}/{number}"
346
+
347
+ def issue_labels_path(self, number: int) -> str:
348
+ """
349
+ :param number: The issue's or pull request's number.
350
+ :return: The REST path that sets that issue's labels.
351
+ """
352
+ return f"{self.issue_path(number)}/labels"
353
+
354
+ def issue_comments_path(self, number: int) -> str:
355
+ """
356
+ :param number: The issue's number.
357
+ :return: The REST path that lists and posts that issue's comments.
358
+ """
359
+ return f"{self.issue_path(number)}/comments"
360
+
361
+ @property
362
+ def labels_path(self) -> str:
363
+ """
364
+ The REST path of the labels defined on the repository, which lists and creates
365
+ them.
366
+ """
367
+ return f"{self.api_path}/labels"
368
+
369
+ @property
370
+ def pull_requests_path(self) -> str:
371
+ """
372
+ The REST path of the repository's pull requests, which lists and opens them.
373
+ """
374
+ return f"{self.api_path}/pulls"
375
+
376
+ def pull_request_path(self, number: int) -> str:
377
+ """
378
+ :param number: The pull request's number.
379
+ :return: The REST path of that pull request.
380
+ """
381
+ return f"{self.pull_requests_path}/{number}"
382
+
383
+ def open_pull_requests_from_branch_path(self, branch: str) -> str:
384
+ """
385
+ :param branch: A branch of this repository itself.
386
+ :return: The REST path listing the open pull requests opened from that branch.
387
+ """
388
+ query = urlencode({"head": f"{self.owner}:{branch}", "state": "open"}, safe=":")
389
+ return f"{self.pull_requests_path}?{query}"
390
+
391
+ def compare_path(self, base: str) -> str:
392
+ """
393
+ :param base: What the head is compared with: a branch, or ``owner:branch`` for
394
+ one in another repository of the same network.
395
+ :return: The REST path of the comparison, which the head follows after ``...``.
396
+ """
397
+ return f"{self.api_path}/compare/{base}"
398
+
399
+ def workflow_run_path(self, run: int) -> str:
400
+ """
401
+ :param run: The Actions workflow run's own number.
402
+ :return: The REST path of that run.
403
+ """
404
+ return f"{self.api_path}/actions/runs/{run}"
405
+
406
+ def job_log_path(self, job: int) -> str:
407
+ """
408
+ :param job: The Actions job's own number.
409
+ :return: The REST path of that job's whole recorded log.
410
+ """
411
+ return f"{self.api_path}/actions/jobs/{job}/logs"
412
+
413
+ def workflow_resource_path(self, workflow: Path) -> str:
414
+ """
415
+ :param workflow: The workflow's file in the repository.
416
+ :return: The REST path of that workflow, which reads its state.
417
+ """
418
+ return f"{self.api_path}/actions/workflows/{workflow.name}"
419
+
420
+ def workflow_dispatch_path(self, workflow: Path) -> str:
421
+ """
422
+ :param workflow: The workflow's file in the repository.
423
+ :return: The REST path that starts a run of that workflow.
424
+ """
425
+ return f"{self.workflow_resource_path(workflow)}/dispatches"
426
+
427
+ @property
428
+ def actions_permissions_path(self) -> str:
429
+ """
430
+ The REST path of whether Actions may run in the repository.
431
+ """
432
+ return f"{self.api_path}/actions/permissions"
433
+
434
+ def actions_secret_path(self, secret: str) -> str:
435
+ """
436
+ :param secret: The Actions secret's name.
437
+ :return: The REST path of its metadata; GitHub never serves its value.
438
+ """
439
+ return f"{self.api_path}/actions/secrets/{secret}"
440
+
441
+ def contents_path(self, file_path: str, revision: str | None = None) -> str:
442
+ """
443
+ :param file_path: The file's path from the repository's root.
444
+ :param revision: The branch or commit to read it at, ``None`` to write it.
445
+ :return: The REST path of the file's contents.
446
+ """
447
+ path = f"{self.api_path}/contents/{file_path}"
448
+ return path if revision is None else f"{path}?ref={revision}"
449
+
450
+ @property
451
+ def git_references_path(self) -> str:
452
+ """
453
+ The REST path that creates git references, such as a new branch.
454
+ """
455
+ return f"{self.api_path}/git/refs"
456
+
457
+ def branch_reference_path(self, branch: Branch) -> str:
458
+ """
459
+ :param branch: A branch of the repository.
460
+ :return: The REST path of its git reference.
461
+ """
462
+ return f"{self.api_path}/git/ref/{branch.reference.removeprefix('refs/')}"
463
+
464
+ def branch_update_path(self, branch: Branch) -> str:
465
+ """
466
+ :param branch: A branch of the repository.
467
+ :return: The REST path that moves its git reference.
468
+ """
469
+ return f"{self.git_references_path}/{branch.reference.removeprefix('refs/')}"
470
+
471
+ def git_requirement(self, distribution: str, reference: str) -> str:
472
+ """
473
+ A pip requirement installing a distribution straight from this repository.
474
+
475
+ :param distribution: The distribution the repository builds.
476
+ :param reference: The tag, branch or commit to install it at.
477
+ :return: The requirement, as ``pip install`` takes it.
478
+ """
479
+ return f"{distribution} @ git+{self.url}@{reference}"
480
+
481
+ def __str__(self) -> str:
482
+ """:return: :attr:`full_name`."""
483
+ return self.full_name
484
+
485
+
486
+ @dataclass(frozen=True)
487
+ class HasRepository:
488
+ """
489
+ Something that belongs to one GitHub repository.
490
+ """
491
+
492
+ repository: Annotated[Repository, Field(exclude=True)]
493
+ """
494
+ The repository it belongs to, which a payload written for it leaves out.
495
+ """
496
+
497
+
498
+ @dataclass(frozen=True)
499
+ class PullRequestReference(HasRepository):
500
+ """
501
+ One pull request, named by the repository it is opened on and its number.
502
+
503
+ Identity only: what a pull request currently *is* - open, merged, labelled - is read
504
+ into a record of its own by whichever caller needs it.
505
+ """
506
+
507
+ number: int
508
+ """
509
+ The pull request's number.
510
+ """
511
+
512
+ @property
513
+ def url(self) -> str:
514
+ """
515
+ The pull request's page on GitHub.
516
+ """
517
+ return self.repository.pull_request_url(self.number)
518
+
519
+ @property
520
+ def api_url(self) -> str:
521
+ """
522
+ The pull request's address in GitHub's REST pulls API.
523
+ """
524
+ return f"{GitHubAddress.API}/{self.repository.pull_request_path(self.number)}"
525
+
526
+ @property
527
+ def head_reference(self) -> str:
528
+ """
529
+ The ref the repository keeps the pull request's head commit under, whichever
530
+ repository its branch is on.
531
+ """
532
+ return f"refs/pull/{self.number}/head"