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,74 @@
1
+ """
2
+ The requests GitHub's pull request endpoints read.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from basstler.git.branch import Branch
8
+ from basstler.class_property import classproperty
9
+ from pydantic import field_serializer
10
+
11
+ from basstler.github.client import GitHubWrite, HttpMethod
12
+ from basstler.github.issue import IssueWrite
13
+ from basstler.github.pull_request_ends import PullRequestOpening
14
+ from basstler.github.repository import Repository
15
+
16
+ # %% opening a pull request
17
+
18
+
19
+ class NewPullRequest(GitHubWrite, PullRequestOpening):
20
+ """
21
+ A pull request that does not exist yet, opened on its base's repository.
22
+ """
23
+
24
+ draft: bool = True
25
+ """
26
+ Whether it opens as a draft, which a pull request stays until its author has
27
+ reviewed it themselves.
28
+ """
29
+
30
+ @classproperty
31
+ def method(cls) -> HttpMethod:
32
+ return HttpMethod.POST
33
+
34
+ @property
35
+ def path(self) -> str:
36
+ return self.base.repository.pull_requests_path
37
+
38
+ @field_serializer("base")
39
+ def _base_name(self, base: Branch[Repository]) -> str:
40
+ """
41
+ :param base: :attr:`base`.
42
+ :return: Its name, as the endpoint takes it.
43
+ """
44
+ return base.name
45
+
46
+ @field_serializer("head")
47
+ def _head_name(self, head: Branch[Repository]) -> str:
48
+ """
49
+ :param head: :attr:`head`.
50
+ :return: Its name as the base's repository names it.
51
+ """
52
+ return self.base.repository.head_name(head)
53
+
54
+
55
+ # %% editing a pull request
56
+
57
+
58
+ class PullRequestDescription(IssueWrite):
59
+ """
60
+ A pull request's new description, leaving everything else about it unchanged.
61
+ """
62
+
63
+ body: str
64
+ """
65
+ The description, in Markdown.
66
+ """
67
+
68
+ @classproperty
69
+ def method(cls) -> HttpMethod:
70
+ return HttpMethod.PATCH
71
+
72
+ @property
73
+ def path(self) -> str:
74
+ return self.repository.pull_request_path(self.number)
@@ -0,0 +1,141 @@
1
+ """
2
+ A pull request as GitHub's REST API describes it, and the files it changes, as git reads
3
+ them.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from dataclasses import dataclass
9
+ from typing import Annotated
10
+
11
+ from pydantic import Field
12
+
13
+ from basstler.git.commands import GitCommandRunner
14
+ from basstler.git.commit_range import CommitRange, FileVersions
15
+ from basstler.github.client import GitHubReader
16
+ from basstler.github.repository import Repository
17
+ from basstler.github.web_page import AbsentAsEmpty
18
+ from basstler.json_model import ValidatedJSONModel
19
+
20
+ # %% the pull request
21
+
22
+
23
+ class BranchTip(ValidatedJSONModel):
24
+ """
25
+ One end of a pull request: a branch and the commit it points at.
26
+ """
27
+
28
+ commit: Annotated[str, Field(alias="sha")]
29
+ """
30
+ The commit the branch points at.
31
+ """
32
+
33
+ branch: Annotated[str, Field(alias="ref")]
34
+ """
35
+ The branch's name.
36
+ """
37
+
38
+
39
+ class RestPullRequest(ValidatedJSONModel):
40
+ """
41
+ One pull request as REST describes it, read for its description and its two ends.
42
+ """
43
+
44
+ number: int
45
+ """
46
+ Its number in its repository.
47
+ """
48
+
49
+ node_identifier: Annotated[str, Field(alias="node_id")]
50
+ """
51
+ What GitHub's GraphQL API identifies it by.
52
+ """
53
+
54
+ description: Annotated[str, AbsentAsEmpty(), Field(alias="body")]
55
+ """
56
+ Its description, in Markdown; empty when it has none.
57
+ """
58
+
59
+ base: BranchTip
60
+ """
61
+ The branch it merges into.
62
+ """
63
+
64
+ head: BranchTip
65
+ """
66
+ The branch carrying its changes.
67
+ """
68
+
69
+ @property
70
+ def head_reference(self) -> str:
71
+ """
72
+ The ref the base repository keeps the pull request's head commit under.
73
+ """
74
+ return f"refs/pull/{self.number}/head"
75
+
76
+
77
+ # %% the pull request with its changes
78
+
79
+
80
+ @dataclass(frozen=True)
81
+ class PullRequestChanges:
82
+ """
83
+ A pull request and the files it changes.
84
+ """
85
+
86
+ pull_request: RestPullRequest
87
+ """
88
+ The pull request.
89
+ """
90
+
91
+ commits: CommitRange
92
+ """
93
+ The commits its change runs between, from its merge base to its head commit.
94
+ """
95
+
96
+ files: tuple[FileVersions, ...]
97
+ """
98
+ Every file it changes.
99
+ """
100
+
101
+
102
+ @dataclass(frozen=True)
103
+ class PullRequestChangesReader:
104
+ """
105
+ Reads pull requests of GitHub and their changes in one checkout.
106
+ """
107
+
108
+ git: GitCommandRunner
109
+ """
110
+ The checkout the changes are read in.
111
+ """
112
+
113
+ github: GitHubReader
114
+ """
115
+ Where the pull request is read from.
116
+ """
117
+
118
+ def read(self, repository: Repository, number: int) -> PullRequestChanges:
119
+ """
120
+ :param repository: The repository the pull request is opened on.
121
+ :param number: The pull request's number.
122
+ :return: The pull request and its changes, its commits fetched first when the
123
+ checkout lacks either end.
124
+ """
125
+ pull_request = RestPullRequest.from_json(
126
+ self.github.get(repository.pull_request_path(number))
127
+ )
128
+ if None in (
129
+ self.git.commit_or_none(f"{pull_request.base.commit}^{{commit}}"),
130
+ self.git.commit_or_none(f"{pull_request.head.commit}^{{commit}}"),
131
+ ):
132
+ self.git.fetch(
133
+ repository.clone_url,
134
+ pull_request.head_reference,
135
+ pull_request.base.branch,
136
+ )
137
+ merge_base = self.git.merge_base(
138
+ pull_request.base.commit, pull_request.head.commit
139
+ )
140
+ commits = CommitRange(self.git, merge_base, pull_request.head.commit)
141
+ return PullRequestChanges(pull_request, commits, commits.file_versions())
@@ -0,0 +1,145 @@
1
+ """
2
+ A fork pull request's description: what a pass reads out of it and writes into it.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ import re
8
+ from dataclasses import dataclass
9
+
10
+ from basstler.github.constants import DescriptionPattern, MaintenanceText
11
+ from basstler.github.repository import HasRepository
12
+
13
+ # %% the upstream pull request a description links to
14
+
15
+
16
+ @dataclass(frozen=True)
17
+ class UpstreamPullRequestLink(HasRepository):
18
+ """
19
+ A hyperlink to one upstream pull request.
20
+ """
21
+
22
+ number: int
23
+ """
24
+ The upstream pull request's number.
25
+ """
26
+
27
+ @property
28
+ def url(self) -> str:
29
+ """
30
+ The upstream pull request's page on GitHub.
31
+ """
32
+ return self.repository.pull_request_url(self.number)
33
+
34
+ @property
35
+ def markdown(self) -> str:
36
+ """
37
+ The Markdown hyperlink to it, titled with its ``owner/repo#number`` reference.
38
+ """
39
+ return f"[{self.repository.full_name}#{self.number}]({self.url})"
40
+
41
+
42
+ # %% the description
43
+
44
+
45
+ @dataclass(frozen=True)
46
+ class PullRequestDescription:
47
+ """
48
+ A pull request's description, with the session link a pass reads out of it and the
49
+ promotion section it records in it.
50
+ """
51
+
52
+ text: str
53
+ """
54
+ The description as written, empty when the pull request has none.
55
+ """
56
+
57
+ @property
58
+ def session_link(self) -> str | None:
59
+ """
60
+ The first session link the description names, or ``None`` when it names none.
61
+ """
62
+ return DescriptionPattern.SESSION_LINK.first_in(self.text)
63
+
64
+ @property
65
+ def prose(self) -> str:
66
+ """
67
+ The description as its author wrote it, without the sections a pass writes.
68
+ """
69
+ sections = (
70
+ MaintenanceText.PROMOTION_HEADING,
71
+ MaintenanceText.UPSTREAM_PULL_REQUEST_HEADING,
72
+ )
73
+ prose = self.text
74
+ for heading in sections:
75
+ prose = PullRequestDescription(prose).with_section(heading, None)
76
+ return prose.strip()
77
+
78
+ def with_promotion_link(self, url: str) -> str:
79
+ """
80
+ :param url: The link to record.
81
+ :return: The description with *url* as its promotion section, replacing any
82
+ section already there.
83
+ """
84
+ return self.with_section(MaintenanceText.PROMOTION_HEADING, url)
85
+
86
+ @property
87
+ def upstream_link(self) -> str | None:
88
+ """
89
+ The URL of the upstream pull request a pass linked under the upstream pull
90
+ request heading, or ``None`` when the description has no such section.
91
+ """
92
+ return DescriptionPattern.LINK_TARGET.first_in(
93
+ self.section(MaintenanceText.UPSTREAM_PULL_REQUEST_HEADING)
94
+ )
95
+
96
+ def with_upstream_link(self, link: UpstreamPullRequestLink | None) -> str:
97
+ """
98
+ :param link: The upstream pull request to link, ``None`` when there is none.
99
+ :return: The description with *link* as its upstream pull request section,
100
+ replacing any section already there, or without that section when *link*
101
+ is ``None``.
102
+ """
103
+ return self.with_section(
104
+ MaintenanceText.UPSTREAM_PULL_REQUEST_HEADING,
105
+ None if link is None else link.markdown,
106
+ )
107
+
108
+ def section(self, heading: MaintenanceText) -> str | None:
109
+ """
110
+ :param heading: The heading the section opens with.
111
+ :return: The text between *heading* and the next heading, ``None`` when the
112
+ description has no such heading.
113
+ """
114
+ _, content, _ = self._partition(heading)
115
+ return content
116
+
117
+ def with_section(self, heading: MaintenanceText, content: str | None) -> str:
118
+ """
119
+ :param heading: The heading the section opens with.
120
+ :param content: What the section holds, ``None`` to drop the section.
121
+ :return: The description with that section written last, replacing any section
122
+ under *heading* already there.
123
+ """
124
+ before, _, after = self._partition(heading)
125
+ kept = "\n\n".join(part for part in (before.rstrip(), after.strip()) if part)
126
+ if content is None:
127
+ return f"{kept}\n"
128
+ return f"{kept}\n\n{heading}\n\n{content}\n"
129
+
130
+ def _partition(self, heading: MaintenanceText) -> tuple[str, str | None, str]:
131
+ """
132
+ :param heading: The heading the section opens with, matched only as a whole
133
+ line.
134
+ :return: The text before the section, the section's content (``None`` when the
135
+ description has no such heading), and the text after it.
136
+ """
137
+ found = re.search(
138
+ rf"^{re.escape(heading)}[ \t]*$", self.text, flags=re.MULTILINE
139
+ )
140
+ if found is None:
141
+ return self.text, None, ""
142
+ before, rest = self.text[: found.start()], self.text[found.end() :]
143
+ following = DescriptionPattern.HEADING.value.search(rest)
144
+ end = len(rest) if following is None else following.start()
145
+ return before, rest[:end].strip(), rest[end:]
@@ -0,0 +1,58 @@
1
+ """
2
+ The two branches a pull request joins: the one it merges into and the one it proposes.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from dataclasses import dataclass
8
+
9
+ from basstler.git.branch import Branch
10
+ from basstler.github.repository import Repository
11
+
12
+ # %% the ends
13
+
14
+
15
+ @dataclass(frozen=True)
16
+ class PullRequestEnds:
17
+ """
18
+ The branch a pull request merges into and the branch it proposes.
19
+ """
20
+
21
+ base: Branch[Repository]
22
+ """
23
+ The branch it merges into, on the repository the pull request is opened on.
24
+ """
25
+
26
+ head: Branch[Repository]
27
+ """
28
+ The branch it proposes, on that repository or on a fork of it.
29
+ """
30
+
31
+ @property
32
+ def compare_url(self) -> str:
33
+ """
34
+ The page comparing :attr:`head` with :attr:`base`, from which the pull request
35
+ is opened.
36
+ """
37
+ return self.base.repository.compare_url(self.base, self.head)
38
+
39
+
40
+ # %% what a pull request is opened with
41
+
42
+
43
+ @dataclass(frozen=True)
44
+ class PullRequestOpening(PullRequestEnds):
45
+ """
46
+ What a pull request is opened with: the branches it joins, its title and its
47
+ description.
48
+ """
49
+
50
+ title: str
51
+ """
52
+ The pull request's title.
53
+ """
54
+
55
+ body: str = ""
56
+ """
57
+ The pull request's description, in Markdown.
58
+ """
@@ -0,0 +1,136 @@
1
+ """
2
+ GitHub's form opening a pull request, with its title and description filled in from its
3
+ address.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from bisect import bisect_right
9
+ from collections.abc import Mapping
10
+ from dataclasses import dataclass
11
+ from itertools import accumulate
12
+ from urllib.parse import quote
13
+
14
+ from basstler.class_property import classproperty
15
+ from basstler.github.pull_request_ends import PullRequestOpening
16
+ from basstler.github.web_form import PrefilledForm, UrlQueryParameter
17
+
18
+ # %% the form's parameters
19
+
20
+
21
+ class PullRequestFormParameter(UrlQueryParameter):
22
+ """
23
+ The query parameters of a compare-and-create link.
24
+ """
25
+
26
+ EXPAND = "expand"
27
+ """
28
+ Opens the pull request form rather than only the comparison.
29
+ """
30
+
31
+ TITLE = "title"
32
+ """
33
+ The title to prefill.
34
+ """
35
+
36
+ BODY = "body"
37
+ """
38
+ The description to prefill.
39
+ """
40
+
41
+
42
+ # %% the filled-in form
43
+
44
+
45
+ @dataclass(frozen=True)
46
+ class PrefilledPullRequestLink:
47
+ """
48
+ A link opening the pull request form with its title and description filled in.
49
+ """
50
+
51
+ url: str
52
+ """
53
+ The compare-and-create URL, ready to open.
54
+ """
55
+
56
+ body_was_truncated: bool
57
+ """
58
+ Whether the description had to be shortened to fit the URL.
59
+ """
60
+
61
+
62
+ @dataclass(frozen=True)
63
+ class PullRequestForm(PrefilledForm, PullRequestOpening):
64
+ """
65
+ The pull request form joining two branches, filled in from its address.
66
+
67
+ The prefill travels in the query string, so an unencoded character truncates it and
68
+ an oversized one is discarded whole by the server - both silently, so
69
+ :attr:`link` shortens :attr:`body` to fit.
70
+ """
71
+
72
+ @classproperty
73
+ def url_character_limit(cls) -> int:
74
+ """
75
+ Longest URL to build, the conventional 8 KiB request-line limit servers accept.
76
+ """
77
+ return 8192
78
+
79
+ @classproperty
80
+ def truncation_marker(cls) -> str:
81
+ """
82
+ Appended to a body that had to be shortened, so the cut is visible in the
83
+ prefill.
84
+ """
85
+ return "..."
86
+
87
+ @property
88
+ def page_url(self) -> str:
89
+ return self.compare_url
90
+
91
+ @property
92
+ def filled_fields(self) -> Mapping[UrlQueryParameter, str]:
93
+ return self._fields_with_description(self.body)
94
+
95
+ @property
96
+ def url_without_description(self) -> str:
97
+ """
98
+ The form's address with the title alone filled in, the shortest it can be.
99
+ """
100
+ return self.url_filling(self._fields_with_description(""))
101
+
102
+ @property
103
+ def link(self) -> PrefilledPullRequestLink | None:
104
+ """
105
+ The link with :attr:`body` filled in, shortened to fit
106
+ :attr:`url_character_limit`; ``None`` when even the title does not fit.
107
+ """
108
+ if len(self.url) <= self.url_character_limit:
109
+ return PrefilledPullRequestLink(self.url, body_was_truncated=False)
110
+ marked = self.url_filling(self._fields_with_description(self.truncation_marker))
111
+ room = self.url_character_limit - len(marked)
112
+ if room < 0:
113
+ return None
114
+ encoded_lengths = accumulate(
115
+ len(quote(character, safe="")) for character in self.body
116
+ )
117
+ kept = bisect_right(list(encoded_lengths), room)
118
+ return PrefilledPullRequestLink(
119
+ self.url_filling(
120
+ self._fields_with_description(self.body[:kept] + self.truncation_marker)
121
+ ),
122
+ body_was_truncated=True,
123
+ )
124
+
125
+ def _fields_with_description(
126
+ self, description: str
127
+ ) -> dict[UrlQueryParameter, str]:
128
+ """
129
+ :param description: The description to prefill.
130
+ :return: The fields filling in :attr:`title` and *description*.
131
+ """
132
+ return {
133
+ PullRequestFormParameter.EXPAND: "1",
134
+ PullRequestFormParameter.TITLE: self.title,
135
+ PullRequestFormParameter.BODY: description,
136
+ }