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