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