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,459 @@
1
+ """
2
+ Reading and writing a repository's pull requests and labels.
3
+
4
+ The reading and the writing halves are declared separately, so a caller that must not
5
+ write - the board export - can be handed a reader and provably cannot. Every write here
6
+ was probed against the live API first: a pull request's *base branch* is the one the
7
+ credential a session carries is refused, which is why retargeting is reported for a
8
+ caller to perform rather than performed.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import urllib.parse
14
+ from abc import ABC, abstractmethod
15
+ from collections.abc import Mapping, Sequence
16
+ from dataclasses import dataclass
17
+ from enum import Enum, StrEnum
18
+ from typing import Any
19
+
20
+ from basstler.github.client import GitHubClient, GitHubRestClient
21
+ from basstler.github.issue import ClosingReason, IssueClosing, IssueComment
22
+ from basstler.github.label import LabelReplacement, NewLabel, RepositoryLabel
23
+ from basstler.github.pull_request import PullRequestDescription
24
+ from basstler.github.pull_request_ends import PullRequestEnds
25
+ from basstler.github.pull_request_models import CheckStatus
26
+ from basstler.github.pull_request_record import (
27
+ AccountField,
28
+ CommitChecks,
29
+ PullRequestRecord,
30
+ )
31
+ from basstler.github.pull_request_state import PullRequestState
32
+ from basstler.github.repository import HasRepository, Repository
33
+ from basstler.github.rest_models import (
34
+ RestCheckRunPage,
35
+ RestCombinedStatusPage,
36
+ )
37
+ from basstler.github.states import CombinedCheckState
38
+ from basstler.github.tooling_labels import GitHubLabel
39
+ from basstler.github.web_page import WebPage
40
+
41
+ # %% what a pass reads and writes
42
+
43
+
44
+ @dataclass(frozen=True)
45
+ class PullRequestReader(ABC):
46
+ """
47
+ Reading the pull-request state a pass derives from.
48
+
49
+ Implementations inherit rather than merely match the shape, so one that omits a read
50
+ is refused when it is constructed rather than when the missing call is first made.
51
+ """
52
+
53
+ @abstractmethod
54
+ def open_pull_requests(self) -> list[PullRequestRecord]:
55
+ """:return: Every open pull request on the fork."""
56
+
57
+ @abstractmethod
58
+ def pull_request(self, number: int) -> PullRequestRecord:
59
+ """:param number: The pull request to read.
60
+ :return: That pull request."""
61
+
62
+
63
+ @dataclass(frozen=True)
64
+ class PullRequestWriter(ABC):
65
+ """
66
+ The writes a pass makes, each one probed against the live API first.
67
+
68
+ Every one of them is available to the credential a session carries; a pull request's
69
+ *base branch* is the single write that is not, which is why reparenting is the
70
+ caller's job and none of this is.
71
+ """
72
+
73
+ @abstractmethod
74
+ def replace_labels(self, number: int, labels: Sequence[str]) -> None:
75
+ """:param number: The pull request to write.
76
+ :param labels: The complete label set it must end up with."""
77
+
78
+ @abstractmethod
79
+ def add_comment(self, number: int, body: str) -> str:
80
+ """:param number: The pull request to comment on.
81
+ :param body: The comment.
82
+ :return: The comment's URL."""
83
+
84
+ @abstractmethod
85
+ def set_description(self, number: int, body: str) -> None:
86
+ """:param number: The pull request to write.
87
+ :param body: The new description."""
88
+
89
+ @abstractmethod
90
+ def close_pull_request(self, number: int) -> None:
91
+ """:param number: The pull request to close, as completed."""
92
+
93
+
94
+ @dataclass(frozen=True)
95
+ class ForkPullRequests(PullRequestReader, PullRequestWriter, ABC):
96
+ """
97
+ Everything a pass does to the fork's pull requests.
98
+
99
+ A pass reads state and writes back to the same fork, so the two halves are named
100
+ together wherever both are needed; the board export takes the reading half alone,
101
+ which is what keeps an export from being able to write.
102
+ """
103
+
104
+
105
+ @dataclass(frozen=True)
106
+ class RepositoryLabels(ABC):
107
+ """
108
+ The labels a repository carries, and adding one it lacks.
109
+ """
110
+
111
+ @abstractmethod
112
+ def labels(self) -> set[str]:
113
+ """:return: The name of every label the repository carries."""
114
+
115
+ @abstractmethod
116
+ def create_label(self, label: GitHubLabel) -> None:
117
+ """:param label: The label to add, described by its purpose."""
118
+
119
+
120
+ @dataclass(frozen=True)
121
+ class CredentialHolder(ABC):
122
+ """
123
+ Telling whose credential a client calls GitHub with.
124
+ """
125
+
126
+ @abstractmethod
127
+ def authenticated_login(self) -> str:
128
+ """:return: The login of the account the credential belongs to."""
129
+
130
+
131
+ class GitHubPath(StrEnum):
132
+ """
133
+ The API routes that are not below a repository, ``/``-separated on every platform.
134
+ """
135
+
136
+ AUTHENTICATED_USER = "/user"
137
+ """
138
+ The account the request's credential belongs to.
139
+ """
140
+
141
+
142
+ class GitHubRepositoryPath(StrEnum):
143
+ """
144
+ The API routes below a repository, ``/``-separated on every platform.
145
+ """
146
+
147
+ PULL_REQUESTS = "/pulls"
148
+ """
149
+ The repository's pull requests.
150
+ """
151
+
152
+ LABELS = "/labels"
153
+ """
154
+ The labels defined on the repository.
155
+ """
156
+
157
+ COMMITS = "/commits"
158
+ """
159
+ The repository's commits.
160
+ """
161
+
162
+
163
+ class CommitReport(StrEnum):
164
+ """
165
+ The listings reported against one commit, below :attr:`GitHubRepositoryPath.COMMITS`.
166
+ """
167
+
168
+ CHECK_RUNS = "check-runs"
169
+ """
170
+ The check runs reported against it.
171
+ """
172
+
173
+ STATUS = "status"
174
+ """
175
+ The commit statuses posted against it.
176
+ """
177
+
178
+
179
+ MAXIMUM_PULL_REQUESTS_PER_PAGE = 100
180
+ """
181
+ The most pull requests one page of GitHub's pull request listing holds.
182
+ """
183
+
184
+
185
+ class ListingParameter(StrEnum):
186
+ """
187
+ The query parameters a paged listing takes.
188
+ """
189
+
190
+ STATE = "state"
191
+ """
192
+ Which pull requests to list, by state.
193
+ """
194
+
195
+ PAGE_SIZE = "per_page"
196
+ """
197
+ How many entries one page holds.
198
+ """
199
+
200
+ HEAD = "head"
201
+ """
202
+ The branch the pull requests are opened from, as ``owner:branch``.
203
+ """
204
+
205
+ BASE = "base"
206
+ """
207
+ The branch the pull requests merge into.
208
+ """
209
+
210
+
211
+ @dataclass(frozen=True)
212
+ class PullRequestListingSpecification:
213
+ """
214
+ One filter the pull request list API takes: what it is asked for by, and which
215
+ :class:`PullRequestState` values it lets through.
216
+ """
217
+
218
+ query: str
219
+ """
220
+ The value the list API's ``state`` parameter takes for this filter.
221
+ """
222
+
223
+ states: tuple[PullRequestState, ...]
224
+ """
225
+ The pull request states this filter lets through.
226
+ """
227
+
228
+ def path_on(self, repository: Repository) -> str:
229
+ """
230
+ :param repository: The repository the pull requests are opened on.
231
+ :return: The REST path listing the first page of its pull requests this filter
232
+ lets through.
233
+ """
234
+ return self._path(repository, {})
235
+
236
+ def path_between(self, ends: PullRequestEnds) -> str:
237
+ """
238
+ :param ends: The branches the pull requests join.
239
+ :return: The REST path listing the pull requests from *ends*' head into its base
240
+ this filter lets through.
241
+ """
242
+ return self._path(
243
+ ends.base.repository,
244
+ {
245
+ ListingParameter.HEAD: ends.head.repository.branch_label(ends.head),
246
+ ListingParameter.BASE: ends.base.name,
247
+ },
248
+ )
249
+
250
+ def _path(
251
+ self, repository: Repository, filters: Mapping[ListingParameter, str]
252
+ ) -> str:
253
+ """
254
+ :param repository: The repository the pull requests are opened on.
255
+ :param filters: Further filters of the listing.
256
+ :return: The REST path listing a full first page of them.
257
+ """
258
+ query = urllib.parse.urlencode(
259
+ {
260
+ ListingParameter.STATE: self.query,
261
+ ListingParameter.PAGE_SIZE: MAXIMUM_PULL_REQUESTS_PER_PAGE,
262
+ **filters,
263
+ },
264
+ safe=":",
265
+ )
266
+ return f"{repository.pull_requests_path}?{query}"
267
+
268
+
269
+ class PullRequestListState(PullRequestListingSpecification, Enum):
270
+ """
271
+ The pull request states the list API filters on: each :class:`PullRequestState` a
272
+ pull request reports, plus every state at once.
273
+
274
+ Each member *is* a :class:`PullRequestListingSpecification`, written as its fields
275
+ in declaration order - ``query``, then ``states`` - which the enum passes straight to
276
+ the dataclass.
277
+ """
278
+
279
+ OPEN = PullRequestState.OPEN.value, (PullRequestState.OPEN,)
280
+ """
281
+ Pull requests whose state is :attr:`PullRequestState.OPEN`: drafts and those ready
282
+ for review alike.
283
+ """
284
+
285
+ CLOSED = PullRequestState.CLOSED.value, (PullRequestState.CLOSED,)
286
+ """
287
+ Pull requests whose state is :attr:`PullRequestState.CLOSED`: merged and closed
288
+ unmerged alike.
289
+ """
290
+
291
+ ALL = "all", tuple(PullRequestState)
292
+ """
293
+ Every pull request, whatever its :class:`PullRequestState`.
294
+ """
295
+
296
+
297
+ # %% the client that makes the calls
298
+
299
+
300
+ @dataclass(frozen=True)
301
+ class GitHubRepository(
302
+ HasRepository, ForkPullRequests, CommitChecks, RepositoryLabels, CredentialHolder
303
+ ):
304
+ """
305
+ Every pull-request and label call this tooling makes, against one repository.
306
+ """
307
+
308
+ client: GitHubClient
309
+ """
310
+ How the calls reach GitHub.
311
+ """
312
+
313
+ page_size: int = 100
314
+ """
315
+ How many pull requests, labels or checks to ask for per page.
316
+ """
317
+
318
+ @classmethod
319
+ def from_environment(cls, repository: Repository) -> GitHubRepository:
320
+ """
321
+ Build a client from whichever credential the environment carries.
322
+
323
+ :param repository: The repository to read and write.
324
+ :return: The client.
325
+ """
326
+ return cls(repository, GitHubRestClient())
327
+
328
+ def open_pull_requests(self) -> list[PullRequestRecord]:
329
+ """:return: Every open pull request on the repository, oldest page first."""
330
+ return self._pull_requests_in_state(PullRequestListState.OPEN)
331
+
332
+ def all_pull_requests(self) -> list[PullRequestRecord]:
333
+ """:return: Every pull request on the repository, open or closed."""
334
+ return self._pull_requests_in_state(PullRequestListState.ALL)
335
+
336
+ def issue(self, number: int) -> Mapping[str, Any]:
337
+ """:param number: The issue or pull request to read.
338
+ :return: It, as the issues API describes it."""
339
+ return self.client.get(self._path(f"/issues/{number}"))
340
+
341
+ def _pull_requests_in_state(
342
+ self, state: PullRequestListState
343
+ ) -> list[PullRequestRecord]:
344
+ """
345
+ Read every page of pull requests in one state.
346
+
347
+ :param state: Which pull requests to list.
348
+ :return: Them, oldest page first.
349
+ """
350
+ return self._every_entry(
351
+ GitHubRepositoryPath.PULL_REQUESTS, {ListingParameter.STATE: state.query}
352
+ )
353
+
354
+ def labels(self) -> set[str]:
355
+ return {
356
+ RepositoryLabel.from_json(label).name
357
+ for label in self._every_entry(GitHubRepositoryPath.LABELS, {})
358
+ }
359
+
360
+ def create_label(self, label: GitHubLabel) -> None:
361
+ self.client.send(
362
+ NewLabel(self.repository, RepositoryLabel(label, label.purpose))
363
+ )
364
+
365
+ def check_state(self, commit: str) -> CombinedCheckState:
366
+ runs = [
367
+ run
368
+ for page in self.client.get_pages(
369
+ self._listing(self._commit_report(commit, CommitReport.CHECK_RUNS), {})
370
+ )
371
+ for run in RestCheckRunPage.from_json(page).check_runs
372
+ ]
373
+ statuses = [
374
+ status
375
+ for page in self.client.get_pages(
376
+ self._listing(self._commit_report(commit, CommitReport.STATUS), {})
377
+ )
378
+ for status in RestCombinedStatusPage.from_json(page).statuses
379
+ ]
380
+ checks = CheckStatus.over(runs + statuses)
381
+ return CombinedCheckState.NOT_REPORTED if checks is None else checks.state
382
+
383
+ @staticmethod
384
+ def _commit_report(commit: str, report: CommitReport) -> str:
385
+ """:param commit: The commit reported against.
386
+ :param report: Which of its listings to read.
387
+ :return: The listing's path below the repository."""
388
+ return f"{GitHubRepositoryPath.COMMITS}/{commit}/{report}"
389
+
390
+ def authenticated_login(self) -> str:
391
+ account = self.client.get(str(GitHubPath.AUTHENTICATED_USER))
392
+ return str(account[AccountField.LOGIN])
393
+
394
+ def _every_entry(
395
+ self, path: GitHubRepositoryPath, filters: Mapping[ListingParameter, str]
396
+ ) -> list[dict[str, Any]]:
397
+ """
398
+ Read a listing below the repository whose pages are lists, to its end.
399
+
400
+ :param path: The listing's path below the repository.
401
+ :param filters: The query parameters narrowing the listing.
402
+ :return: Every entry, first page first.
403
+ """
404
+ return self.client.get_entries(self._listing(str(path), filters))
405
+
406
+ def _listing(self, path: str, filters: Mapping[ListingParameter, str]) -> str:
407
+ """
408
+ :param path: A listing's path below the repository.
409
+ :param filters: The query parameters narrowing it.
410
+ :return: Its path below the API root, asking for full pages.
411
+ """
412
+ query = urllib.parse.urlencode(
413
+ {**filters, ListingParameter.PAGE_SIZE: self.page_size}
414
+ )
415
+ return self._path(f"{path}?{query}")
416
+
417
+ def _path(self, path: str) -> str:
418
+ """
419
+ :param path: A path below the repository, starting with a slash.
420
+ :return: It below the API root.
421
+ """
422
+ return f"/{self.repository.api_path}{path}"
423
+
424
+ def pull_request(self, number: int) -> PullRequestRecord:
425
+ """:param number: The pull request to read.
426
+ :return: That pull request."""
427
+ return self.client.get(
428
+ self._path(f"{GitHubRepositoryPath.PULL_REQUESTS}/{number}")
429
+ )
430
+
431
+ def replace_labels(self, number: int, labels: Sequence[str]) -> None:
432
+ """
433
+ Write a pull request's complete label set.
434
+
435
+ :param number: The pull request to write.
436
+ :param labels: The complete set it must end up with, computed by
437
+ :meth:`stack.LabelWrite.replacing` - this call replaces rather than adds.
438
+ """
439
+ self.client.send(LabelReplacement(self.repository, number, list(labels)))
440
+
441
+ def add_comment(self, number: int, body: str) -> str:
442
+ """:param number: The pull request to comment on.
443
+ :param body: The comment.
444
+ :return: The comment's URL."""
445
+ created = self.client.send(IssueComment(self.repository, number, body))
446
+ return WebPage.from_json(created).page_url
447
+
448
+ def set_description(self, number: int, body: str) -> None:
449
+ """
450
+ Rewrite a pull request's description and nothing else.
451
+
452
+ :param number: The pull request to write.
453
+ :param body: The new description.
454
+ """
455
+ self.client.send(PullRequestDescription(self.repository, number, body))
456
+
457
+ def close_pull_request(self, number: int) -> None:
458
+ """:param number: The pull request to close, as completed."""
459
+ self.client.send(IssueClosing(self.repository, number, ClosingReason.COMPLETED))
@@ -0,0 +1,95 @@
1
+ """
2
+ Telling a Claude Code cloud session to attach a repository it cannot reach, and to ask the
3
+ user when the attach is refused.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from dataclasses import dataclass
9
+ from enum import StrEnum
10
+
11
+ from basstler.github.repository import HasRepository
12
+
13
+ # %% the session's tools
14
+
15
+
16
+ class SessionTool(StrEnum):
17
+ """
18
+ The Claude Code tools a session calls.
19
+ """
20
+
21
+ ATTACH_REPOSITORY = "mcp__claude-code-remote__add_repo"
22
+ """
23
+ Attaches a repository to a cloud session, which lets its proxy answer that
24
+ repository's git and API requests.
25
+ """
26
+
27
+ REGISTER_REPOSITORY_ROOT = "mcp__claude-code-remote__register_repo_root"
28
+ """
29
+ Loads the instructions of an attached repository's local clone into the session.
30
+ """
31
+
32
+ ASK_USER = "AskUserQuestion"
33
+ """
34
+ Asks the user to choose between options.
35
+ """
36
+
37
+ RUN_SHELL_COMMAND = "Bash"
38
+ """
39
+ Runs a command in the session's shell.
40
+ """
41
+
42
+
43
+ class SessionProxyAnswer(StrEnum):
44
+ """
45
+ What a cloud session's proxy answers a GitHub request with, in GitHub's place.
46
+ """
47
+
48
+ REPOSITORY_NOT_ATTACHED = (
49
+ "GitHub access to this repository is not enabled for this session"
50
+ )
51
+ """
52
+ The repository is not attached to the session, whether or not it exists.
53
+ """
54
+
55
+
56
+ # %% the instruction
57
+
58
+
59
+ @dataclass(frozen=True)
60
+ class RepositoryAttachment(HasRepository):
61
+ """
62
+ How a cloud session gets :attr:`repository` attached, and what it then runs.
63
+ """
64
+
65
+ retry_command: str
66
+ """
67
+ The command that does what failed, once the repository is attached.
68
+ """
69
+
70
+ benefit: str
71
+ """
72
+ What attaching the repository gives the user, said when asking them to allow it.
73
+ """
74
+
75
+ recommended_option: str = "Attach it (Recommended)"
76
+ """
77
+ The first option the user is offered when the attach is refused.
78
+ """
79
+
80
+ def instruction(self) -> str:
81
+ """
82
+ :return: The tool call that attaches :attr:`repository`, the command to run
83
+ then without a local clone, and the question to put to the user when the
84
+ attach is refused.
85
+ """
86
+ return (
87
+ f"Attach {self.repository.full_name} to this session: call "
88
+ f"{SessionTool.ATTACH_REPOSITORY} with owner {self.repository.owner}, repo "
89
+ f"{self.repository.name} and access push, then run {self.retry_command}. "
90
+ f"Only the attachment's credential is needed: skip the clone and the "
91
+ f"{SessionTool.REGISTER_REPOSITORY_ROOT} call the attach answer asks for. If "
92
+ f"the attach is refused, ask the user with {SessionTool.ASK_USER} to allow "
93
+ f'it, with "{self.recommended_option}" as the first option: '
94
+ f"{self.benefit}."
95
+ )
@@ -0,0 +1,98 @@
1
+ """
2
+ What GitHub's repository resource says about a repository.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from dataclasses import dataclass
8
+ from typing import Annotated
9
+
10
+ from pydantic import Field
11
+
12
+ from basstler.git.branch import Branch
13
+ from basstler.github.permission_level import PermissionLevel
14
+ from basstler.github.pull_request_state import ForkLineage
15
+ from basstler.github.repository import Repository
16
+ from basstler.github.repository_resources import RepositoryRead
17
+ from basstler.github.wire_form import BranchName, RepositoryDefaultBranch
18
+ from basstler.json_model import RawValueReader, ValidatedJSONModel
19
+
20
+ # %% the repository resource
21
+
22
+
23
+ class ContentsAccess(RawValueReader):
24
+ """
25
+ Reads the requesting account's role in a repository, as its resource gives it, as
26
+ the :class:`PermissionLevel` it has on the repository's contents.
27
+ """
28
+
29
+ def read(self, value: dict[str, bool]) -> PermissionLevel | None:
30
+ if value.get("push"):
31
+ return PermissionLevel.WRITE
32
+ if value.get("pull"):
33
+ return PermissionLevel.READ
34
+ return None
35
+
36
+
37
+ class RepositoryDetails(ValidatedJSONModel):
38
+ """
39
+ One repository, as its REST resource describes it.
40
+ """
41
+
42
+ default_branch: Annotated[Branch[Repository], BranchName()]
43
+ """
44
+ The branch pull requests target unless told otherwise.
45
+ """
46
+
47
+ is_fork: Annotated[bool, Field(alias="fork")]
48
+ """
49
+ Whether it is a fork, whose default branch follows its upstream's.
50
+ """
51
+
52
+ is_private: Annotated[bool, Field(alias="private")]
53
+ """
54
+ Whether only the people and tokens granted access can read it.
55
+ """
56
+
57
+ parent_default_branch: Annotated[
58
+ Branch[Repository] | None, Field(alias="parent"), RepositoryDefaultBranch()
59
+ ] = None
60
+ """
61
+ The default branch of the repository it was forked from, ``None`` when it is no
62
+ fork.
63
+ """
64
+
65
+ contents_access: Annotated[
66
+ PermissionLevel | None, Field(alias="permissions"), ContentsAccess()
67
+ ] = None
68
+ """
69
+ What the requesting account may do with the repository's files and branches,
70
+ ``None`` when it may do neither or the request was anonymous.
71
+ """
72
+
73
+ @property
74
+ def lineage(self) -> ForkLineage | None:
75
+ """
76
+ What the repository was forked from, ``None`` unless it is a fork.
77
+ """
78
+ if self.parent_default_branch is None:
79
+ return None
80
+ return ForkLineage(
81
+ upstream_repository=self.parent_default_branch.repository,
82
+ upstream_default_branch=self.parent_default_branch.name,
83
+ fork_default_branch=self.default_branch.name,
84
+ )
85
+
86
+
87
+ # %% reading it
88
+
89
+
90
+ @dataclass(frozen=True)
91
+ class RepositoryDetailsRead(RepositoryRead[RepositoryDetails]):
92
+ """
93
+ Reads a repository's own resource.
94
+ """
95
+
96
+ @property
97
+ def path(self) -> str:
98
+ return self.repository.api_path
@@ -0,0 +1,43 @@
1
+ """
2
+ A GitHub repository given on the command line as ``owner/name``.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from typing import Annotated
8
+
9
+ from cyclopts import Parameter, Token
10
+
11
+ from basstler.github.repository import Repository
12
+
13
+ # %% converting the value
14
+
15
+
16
+ def parse_repository(_: type, tokens: tuple[Token, ...]) -> Repository:
17
+ """
18
+ Convert a command-line ``owner/name`` value.
19
+
20
+ :param tokens: The one token given for the option.
21
+ :return: The repository it names.
22
+ :raises MalformedRepositoryError: If the value is not ``owner/name``.
23
+ """
24
+ return Repository.parse(tokens[0].value)
25
+
26
+
27
+ # %% the parameters
28
+
29
+ RepositoryArgument = Annotated[
30
+ Repository,
31
+ Parameter(converter=parse_repository, n_tokens=1, accepts_keys=False),
32
+ ]
33
+ """
34
+ An ``owner/name`` repository given on the command line.
35
+ """
36
+
37
+ RepositoryOption = Annotated[
38
+ Repository | None,
39
+ Parameter(converter=parse_repository, n_tokens=1, accepts_keys=False),
40
+ ]
41
+ """
42
+ An optional ``owner/name`` repository given on the command line.
43
+ """