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,85 @@
|
|
|
1
|
+
"""
|
|
2
|
+
The token the GitHub REST client authenticates with, and where it came from.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
from dataclasses import dataclass, field
|
|
8
|
+
from enum import StrEnum
|
|
9
|
+
|
|
10
|
+
from basstler.credential_origin import CredentialOrigin
|
|
11
|
+
|
|
12
|
+
# %% the commands that give access
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class GitHubCommand(StrEnum):
|
|
16
|
+
"""
|
|
17
|
+
The ``gh`` command lines a user is told to run to give this package or git access to
|
|
18
|
+
GitHub.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
LOG_IN = "gh auth login"
|
|
22
|
+
"""
|
|
23
|
+
Logs ``gh`` in, which gives this package its credential.
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
REFRESH_WORKFLOW_SCOPE = "gh auth refresh -s workflow"
|
|
27
|
+
"""
|
|
28
|
+
Adds the ``workflow`` scope to ``gh``'s login, which pushing a workflow file needs.
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
# %% where a token comes from
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class CredentialProvider(CredentialOrigin, StrEnum):
|
|
36
|
+
"""
|
|
37
|
+
The origins of a token not read from a
|
|
38
|
+
:class:`basstler.environment.GitHubCredentialVariable`.
|
|
39
|
+
"""
|
|
40
|
+
|
|
41
|
+
CALLER = "the token the client was given"
|
|
42
|
+
"""
|
|
43
|
+
The caller handed the client its token.
|
|
44
|
+
"""
|
|
45
|
+
|
|
46
|
+
GH_LOGIN = "gh's login"
|
|
47
|
+
"""
|
|
48
|
+
``gh auth token`` printed it.
|
|
49
|
+
"""
|
|
50
|
+
|
|
51
|
+
def describe_credential(self) -> str:
|
|
52
|
+
"""
|
|
53
|
+
:return: :meth:`CredentialOrigin.describe_credential`: this provider's value.
|
|
54
|
+
"""
|
|
55
|
+
return self.value
|
|
56
|
+
|
|
57
|
+
def suggest_renewal(self) -> str:
|
|
58
|
+
"""
|
|
59
|
+
:return: :meth:`CredentialOrigin.suggest_renewal` for this provider.
|
|
60
|
+
"""
|
|
61
|
+
match self:
|
|
62
|
+
case CredentialProvider.CALLER:
|
|
63
|
+
return "Give the client a valid token."
|
|
64
|
+
case CredentialProvider.GH_LOGIN:
|
|
65
|
+
return "Log in again with `gh auth login`."
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
# %% the token
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
@dataclass(frozen=True)
|
|
72
|
+
class GitHubCredential:
|
|
73
|
+
"""
|
|
74
|
+
A token the client authenticates with, and where it came from.
|
|
75
|
+
"""
|
|
76
|
+
|
|
77
|
+
token: str = field(repr=False)
|
|
78
|
+
"""
|
|
79
|
+
The token, kept out of the representation so it never reaches a log.
|
|
80
|
+
"""
|
|
81
|
+
|
|
82
|
+
origin: CredentialOrigin
|
|
83
|
+
"""
|
|
84
|
+
Where the token came from.
|
|
85
|
+
"""
|
|
@@ -0,0 +1,264 @@
|
|
|
1
|
+
"""
|
|
2
|
+
The failures of a call to the GitHub REST API.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
from abc import ABC
|
|
8
|
+
from dataclasses import dataclass
|
|
9
|
+
from http import HTTPStatus
|
|
10
|
+
|
|
11
|
+
from basstler.class_property import classproperty
|
|
12
|
+
from basstler.credential_origin import CredentialOrigin
|
|
13
|
+
from basstler.exceptions import DataclassException, ExternalCallFailed
|
|
14
|
+
from basstler.exit_codes import CommandFailure, StackExitCode
|
|
15
|
+
|
|
16
|
+
REDIRECTION_STATUSES = range(HTTPStatus.MULTIPLE_CHOICES, HTTPStatus.BAD_REQUEST)
|
|
17
|
+
"""
|
|
18
|
+
Every status of the 3xx class, with which the API answers a path naming a moved resource.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
@dataclass
|
|
23
|
+
class GitHubCredentialUnavailableError(CommandFailure, RuntimeError):
|
|
24
|
+
"""
|
|
25
|
+
Raised when no token is available to authenticate the API calls with.
|
|
26
|
+
"""
|
|
27
|
+
|
|
28
|
+
@classproperty
|
|
29
|
+
def exit_code(cls) -> StackExitCode:
|
|
30
|
+
""":return: The status this kind of error ends a command with."""
|
|
31
|
+
return StackExitCode.CREDENTIAL_UNAVAILABLE
|
|
32
|
+
|
|
33
|
+
variables: tuple[str, ...]
|
|
34
|
+
"""
|
|
35
|
+
The environment variables that were consulted.
|
|
36
|
+
"""
|
|
37
|
+
|
|
38
|
+
def __str__(self) -> str:
|
|
39
|
+
""":return: What was looked for, so the caller can supply it."""
|
|
40
|
+
return (
|
|
41
|
+
f"no GitHub token: set one of {', '.join(self.variables)}, log in with "
|
|
42
|
+
f"`gh auth login`, or run this with a caller that has one"
|
|
43
|
+
)
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
@dataclass
|
|
47
|
+
class GitHubCallFailed(CommandFailure, DataclassException):
|
|
48
|
+
"""
|
|
49
|
+
Base for a call to the API that did not succeed.
|
|
50
|
+
"""
|
|
51
|
+
|
|
52
|
+
@classproperty
|
|
53
|
+
def exit_code(cls) -> StackExitCode:
|
|
54
|
+
""":return: The status this kind of error ends a command with."""
|
|
55
|
+
return StackExitCode.GITHUB_REQUEST_FAILED
|
|
56
|
+
|
|
57
|
+
method: str
|
|
58
|
+
"""
|
|
59
|
+
The HTTP method used.
|
|
60
|
+
"""
|
|
61
|
+
path: str
|
|
62
|
+
"""
|
|
63
|
+
The API path called, without the host.
|
|
64
|
+
"""
|
|
65
|
+
|
|
66
|
+
@property
|
|
67
|
+
def call(self) -> str:
|
|
68
|
+
""":return: The request line, as issued."""
|
|
69
|
+
return f"{self.method} {self.path}"
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
@dataclass
|
|
73
|
+
class GitHubRequestFailed(GitHubCallFailed, ExternalCallFailed):
|
|
74
|
+
"""
|
|
75
|
+
Raised when the API refuses a call.
|
|
76
|
+
"""
|
|
77
|
+
|
|
78
|
+
credential_origin: CredentialOrigin
|
|
79
|
+
"""
|
|
80
|
+
Where the token the call authenticated with came from.
|
|
81
|
+
"""
|
|
82
|
+
|
|
83
|
+
@classmethod
|
|
84
|
+
def for_status(
|
|
85
|
+
cls,
|
|
86
|
+
status: int,
|
|
87
|
+
detail: str,
|
|
88
|
+
method: str,
|
|
89
|
+
path: str,
|
|
90
|
+
credential_origin: CredentialOrigin,
|
|
91
|
+
) -> GitHubRequestFailed:
|
|
92
|
+
"""
|
|
93
|
+
:return: The refusal, a :class:`GitHubCredentialRejected` for a 401 and a
|
|
94
|
+
:class:`GitHubRepositoryMoved` for a redirection.
|
|
95
|
+
"""
|
|
96
|
+
refusal = cls
|
|
97
|
+
if status == HTTPStatus.UNAUTHORIZED:
|
|
98
|
+
refusal = GitHubCredentialRejected
|
|
99
|
+
if status in REDIRECTION_STATUSES:
|
|
100
|
+
refusal = GitHubRepositoryMoved
|
|
101
|
+
return refusal(
|
|
102
|
+
status=status,
|
|
103
|
+
detail=detail,
|
|
104
|
+
method=method,
|
|
105
|
+
path=path,
|
|
106
|
+
credential_origin=credential_origin,
|
|
107
|
+
)
|
|
108
|
+
|
|
109
|
+
def error_message(self) -> str:
|
|
110
|
+
"""
|
|
111
|
+
:return: :meth:`ExternalCallFailed.error_message`, naming the credential.
|
|
112
|
+
"""
|
|
113
|
+
return (
|
|
114
|
+
f"{self.call} failed with {self.status} using "
|
|
115
|
+
f"{self.credential_origin.describe_credential()}: "
|
|
116
|
+
f"{self.detail}"
|
|
117
|
+
)
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
@dataclass
|
|
121
|
+
class GitHubCredentialRejected(GitHubRequestFailed):
|
|
122
|
+
"""
|
|
123
|
+
Raised when the API rejects the call's token as invalid or expired.
|
|
124
|
+
"""
|
|
125
|
+
|
|
126
|
+
def error_message(self) -> str:
|
|
127
|
+
"""
|
|
128
|
+
:return: That GitHub rejects the credential, unlike
|
|
129
|
+
:meth:`GitHubRequestFailed.error_message`.
|
|
130
|
+
"""
|
|
131
|
+
return (
|
|
132
|
+
f"GitHub rejects {self.credential_origin.describe_credential()} as "
|
|
133
|
+
f"invalid or expired: {self.call} failed with {self.status}"
|
|
134
|
+
)
|
|
135
|
+
|
|
136
|
+
def suggest_correction(self) -> str:
|
|
137
|
+
"""
|
|
138
|
+
:return: How to renew the credential, where
|
|
139
|
+
:meth:`ExternalCallFailed.suggest_correction` has no advice.
|
|
140
|
+
"""
|
|
141
|
+
return self.credential_origin.suggest_renewal()
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
@dataclass
|
|
145
|
+
class GitHubRepositoryMoved(GitHubRequestFailed):
|
|
146
|
+
"""
|
|
147
|
+
Raised when the API redirects the call because the repository it names was renamed
|
|
148
|
+
or transferred.
|
|
149
|
+
"""
|
|
150
|
+
|
|
151
|
+
def error_message(self) -> str:
|
|
152
|
+
return (
|
|
153
|
+
f"{self.call} names a repository that moved: GitHub answered "
|
|
154
|
+
f"{self.status} with {self.detail}"
|
|
155
|
+
)
|
|
156
|
+
|
|
157
|
+
def suggest_correction(self) -> str:
|
|
158
|
+
return (
|
|
159
|
+
"Look up the repository's new owner and name on github.com, then point the "
|
|
160
|
+
"git remote, configuration or plan that named the old one at it."
|
|
161
|
+
)
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
@dataclass
|
|
165
|
+
class GitHubUnreachableError(GitHubCallFailed, ConnectionError):
|
|
166
|
+
"""
|
|
167
|
+
Raised when a call gets no answer from the API, such as when the network is down.
|
|
168
|
+
"""
|
|
169
|
+
|
|
170
|
+
reason: str
|
|
171
|
+
"""
|
|
172
|
+
What stopped the call.
|
|
173
|
+
"""
|
|
174
|
+
|
|
175
|
+
def error_message(self) -> str:
|
|
176
|
+
return f"{self.call} got no answer from GitHub: {self.reason}"
|
|
177
|
+
|
|
178
|
+
def suggest_correction(self) -> str:
|
|
179
|
+
return "Check the network connection to GitHub, then run the command again."
|
|
180
|
+
|
|
181
|
+
|
|
182
|
+
@dataclass
|
|
183
|
+
class GraphQLErrorsReturned(DataclassException):
|
|
184
|
+
"""
|
|
185
|
+
Raised when GitHub answers a GraphQL request with errors.
|
|
186
|
+
"""
|
|
187
|
+
|
|
188
|
+
messages: tuple[str, ...]
|
|
189
|
+
"""
|
|
190
|
+
Every message GitHub reported.
|
|
191
|
+
"""
|
|
192
|
+
|
|
193
|
+
def error_message(self) -> str:
|
|
194
|
+
return "GitHub answered with errors: " + "; ".join(self.messages)
|
|
195
|
+
|
|
196
|
+
def suggest_correction(self) -> str:
|
|
197
|
+
return (
|
|
198
|
+
"Check that what the request names exists and that the account gh is "
|
|
199
|
+
"logged in as may read or change it: gh auth status"
|
|
200
|
+
)
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
@dataclass
|
|
204
|
+
class BasstlerSourceUnknown(DataclassException):
|
|
205
|
+
"""
|
|
206
|
+
Raised when the installed package's metadata names no source repository.
|
|
207
|
+
"""
|
|
208
|
+
|
|
209
|
+
distribution: str
|
|
210
|
+
"""
|
|
211
|
+
The distribution whose metadata was read.
|
|
212
|
+
"""
|
|
213
|
+
|
|
214
|
+
project_urls: tuple[str, ...]
|
|
215
|
+
"""
|
|
216
|
+
Every ``Project-URL`` entry it declares.
|
|
217
|
+
"""
|
|
218
|
+
|
|
219
|
+
def error_message(self) -> str:
|
|
220
|
+
return (
|
|
221
|
+
f"the {self.distribution} package's metadata names no Source among its "
|
|
222
|
+
f"project URLs ({', '.join(self.project_urls) or 'none'})"
|
|
223
|
+
)
|
|
224
|
+
|
|
225
|
+
def suggest_correction(self) -> str:
|
|
226
|
+
return (
|
|
227
|
+
f"Reinstall {self.distribution} from its published release or repository, "
|
|
228
|
+
"whose pyproject.toml declares its Source URL"
|
|
229
|
+
)
|
|
230
|
+
|
|
231
|
+
|
|
232
|
+
# %% reading what a repository owns out of a payload
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
@dataclass
|
|
236
|
+
class RepositoryUnknown(DataclassException, ValueError):
|
|
237
|
+
"""
|
|
238
|
+
Raised when a payload names a branch or a pull request but nothing says which
|
|
239
|
+
repository it is of.
|
|
240
|
+
"""
|
|
241
|
+
|
|
242
|
+
owned_text: str
|
|
243
|
+
"""
|
|
244
|
+
The branch or pull request as the payload writes it.
|
|
245
|
+
"""
|
|
246
|
+
|
|
247
|
+
def error_message(self) -> str:
|
|
248
|
+
return f"no repository is known for {self.owned_text!r}"
|
|
249
|
+
|
|
250
|
+
def suggest_correction(self) -> str:
|
|
251
|
+
return (
|
|
252
|
+
"Parse the payload through the read that was served it, so what it names "
|
|
253
|
+
"takes that read's repository; a pull request whose head fork was deleted "
|
|
254
|
+
"names no repository for its head and cannot be read"
|
|
255
|
+
)
|
|
256
|
+
|
|
257
|
+
|
|
258
|
+
# %% reading an upstream pull request
|
|
259
|
+
|
|
260
|
+
|
|
261
|
+
class UpstreamReadError(DataclassException, ABC):
|
|
262
|
+
"""
|
|
263
|
+
Base class for every failure reading an upstream pull request.
|
|
264
|
+
"""
|