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,148 @@
|
|
|
1
|
+
"""
|
|
2
|
+
The workflow runs a repository's branch has had, read from GitHub.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
from datetime import datetime
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
from typing import Annotated
|
|
10
|
+
from urllib.parse import urlencode
|
|
11
|
+
|
|
12
|
+
from pydantic import Field
|
|
13
|
+
|
|
14
|
+
from basstler.github.client import (
|
|
15
|
+
GitHubReader,
|
|
16
|
+
)
|
|
17
|
+
from basstler.github.repository import Repository
|
|
18
|
+
from basstler.github.states import CheckOutcome
|
|
19
|
+
from basstler.github.web_page import WebPage
|
|
20
|
+
from basstler.github.workflow_run import WorkflowRun
|
|
21
|
+
from basstler.json_model import ValidatedJSONModel
|
|
22
|
+
from basstler.locations import WorkflowLocation
|
|
23
|
+
from basstler.standard_streams import StandardStreamHandler
|
|
24
|
+
|
|
25
|
+
logger = StandardStreamHandler.logger_for(__name__)
|
|
26
|
+
"""
|
|
27
|
+
This module's logger, which is also what its command prints through.
|
|
28
|
+
"""
|
|
29
|
+
|
|
30
|
+
MAXIMUM_RUNS_PER_PAGE = 100
|
|
31
|
+
"""
|
|
32
|
+
The most runs GitHub lists on one page.
|
|
33
|
+
"""
|
|
34
|
+
|
|
35
|
+
# %% the runs that confirm a step
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
class ListedRun(WorkflowRun, WebPage):
|
|
39
|
+
"""
|
|
40
|
+
One run, as a repository's run listing describes it.
|
|
41
|
+
"""
|
|
42
|
+
|
|
43
|
+
workflow_file_path: Annotated[Path, Field(alias="path")]
|
|
44
|
+
"""
|
|
45
|
+
The workflow file it ran, relative to its repository's root.
|
|
46
|
+
"""
|
|
47
|
+
|
|
48
|
+
created_at: datetime
|
|
49
|
+
"""
|
|
50
|
+
When it was started.
|
|
51
|
+
"""
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
class RunListing(ValidatedJSONModel):
|
|
55
|
+
"""
|
|
56
|
+
The latest runs on one branch of a repository, newest first.
|
|
57
|
+
"""
|
|
58
|
+
|
|
59
|
+
workflow_runs: list[ListedRun]
|
|
60
|
+
"""
|
|
61
|
+
The runs.
|
|
62
|
+
"""
|
|
63
|
+
|
|
64
|
+
@staticmethod
|
|
65
|
+
def path(
|
|
66
|
+
repository: Repository, branch: str, runs_per_page: int = MAXIMUM_RUNS_PER_PAGE
|
|
67
|
+
) -> str:
|
|
68
|
+
"""
|
|
69
|
+
:param repository: The repository.
|
|
70
|
+
:param branch: The branch the runs ran on.
|
|
71
|
+
:param runs_per_page: How many of the latest runs to list.
|
|
72
|
+
:return: The REST path listing them.
|
|
73
|
+
"""
|
|
74
|
+
query = urlencode(
|
|
75
|
+
{
|
|
76
|
+
"branch": branch,
|
|
77
|
+
"per_page": runs_per_page,
|
|
78
|
+
}
|
|
79
|
+
)
|
|
80
|
+
return f"{repository.api_path}/actions/runs?{query}"
|
|
81
|
+
|
|
82
|
+
@classmethod
|
|
83
|
+
def read(
|
|
84
|
+
cls, client: GitHubReader, repository: Repository, branch: str
|
|
85
|
+
) -> RunListing:
|
|
86
|
+
"""
|
|
87
|
+
:param client: What reads the listing.
|
|
88
|
+
:param repository: The repository.
|
|
89
|
+
:param branch: The branch the runs ran on.
|
|
90
|
+
:return: The listing.
|
|
91
|
+
"""
|
|
92
|
+
return cls.from_json(client.get(cls.path(repository, branch)))
|
|
93
|
+
|
|
94
|
+
def run_for_commit(self, commit: str) -> ListedRun | None:
|
|
95
|
+
"""
|
|
96
|
+
:param commit: The commit a run was started for.
|
|
97
|
+
:return: The latest run started for it, ``None`` when none was.
|
|
98
|
+
"""
|
|
99
|
+
return next((run for run in self.workflow_runs if run.commit == commit), None)
|
|
100
|
+
|
|
101
|
+
def select(self, workflow: WorkflowLocation) -> RunListing:
|
|
102
|
+
"""
|
|
103
|
+
:param workflow: The workflow.
|
|
104
|
+
:return: The listing of its runs alone.
|
|
105
|
+
"""
|
|
106
|
+
return RunListing(
|
|
107
|
+
[run for run in self.workflow_runs if run.workflow_file_path == workflow]
|
|
108
|
+
)
|
|
109
|
+
|
|
110
|
+
def count(self, outcome: CheckOutcome) -> int:
|
|
111
|
+
"""
|
|
112
|
+
:param outcome: How a run ended.
|
|
113
|
+
:return: How many listed runs ended so.
|
|
114
|
+
"""
|
|
115
|
+
return sum(run.outcome is outcome for run in self.workflow_runs)
|
|
116
|
+
|
|
117
|
+
def latest(self, workflow: WorkflowLocation) -> ListedRun | None:
|
|
118
|
+
"""
|
|
119
|
+
:param workflow: The workflow.
|
|
120
|
+
:return: Its latest run, ``None`` when the listing holds none.
|
|
121
|
+
"""
|
|
122
|
+
return next(
|
|
123
|
+
(run for run in self.workflow_runs if run.workflow_file_path == workflow),
|
|
124
|
+
None,
|
|
125
|
+
)
|
|
126
|
+
|
|
127
|
+
def latest_success(self, workflow: WorkflowLocation) -> ListedRun | None:
|
|
128
|
+
"""
|
|
129
|
+
:param workflow: The workflow.
|
|
130
|
+
:return: Its latest run that succeeded, ``None`` when the listing holds none.
|
|
131
|
+
"""
|
|
132
|
+
return next(
|
|
133
|
+
(
|
|
134
|
+
run
|
|
135
|
+
for run in self.workflow_runs
|
|
136
|
+
if run.workflow_file_path == workflow
|
|
137
|
+
and run.outcome is CheckOutcome.SUCCESS
|
|
138
|
+
),
|
|
139
|
+
None,
|
|
140
|
+
)
|
|
141
|
+
|
|
142
|
+
def succeeded(self, workflow: WorkflowLocation) -> bool:
|
|
143
|
+
"""
|
|
144
|
+
:param workflow: The workflow.
|
|
145
|
+
:return: Whether its latest run succeeded.
|
|
146
|
+
"""
|
|
147
|
+
latest = self.latest(workflow)
|
|
148
|
+
return latest is not None and latest.outcome is CheckOutcome.SUCCESS
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
"""
|
|
2
|
+
The stack configuration a project commits, layered over the defaults the package ships.
|
|
3
|
+
|
|
4
|
+
The shipped ``stack.toml`` holds what is the same for every project - label names, the
|
|
5
|
+
base branch - and names nobody's repository. A project names its own upstream in
|
|
6
|
+
``.claude/basstler/stack.toml``, committed beside its code, so every contributor and every
|
|
7
|
+
Actions runner checking the project out reads the same answer. The per-user layer on the
|
|
8
|
+
personal-notes branch goes on top of both, and is :mod:`basstler.stack`'s to read, since
|
|
9
|
+
a runner never fetches that branch.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import tomllib
|
|
15
|
+
from dataclasses import dataclass, field
|
|
16
|
+
from enum import StrEnum
|
|
17
|
+
from pathlib import Path
|
|
18
|
+
from typing import Any
|
|
19
|
+
|
|
20
|
+
from basstler.class_property import classproperty
|
|
21
|
+
from basstler.exit_codes import CommandFailure, StackExitCode
|
|
22
|
+
from basstler.github.repository import Repository
|
|
23
|
+
from basstler.locations import PackageLocation, ProjectLocation
|
|
24
|
+
from basstler.text_file import TextFile
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class StackSetting(StrEnum):
|
|
28
|
+
"""
|
|
29
|
+
The keys of a ``stack.toml``.
|
|
30
|
+
"""
|
|
31
|
+
|
|
32
|
+
IN_REVIEW_LABEL = "in_review_label"
|
|
33
|
+
"""
|
|
34
|
+
The fork pull request label marking a branch promoted to the upstream.
|
|
35
|
+
"""
|
|
36
|
+
|
|
37
|
+
REBASE_LABEL = "rebase_label"
|
|
38
|
+
"""
|
|
39
|
+
The label opting a branch into rebasing instead of merging.
|
|
40
|
+
"""
|
|
41
|
+
|
|
42
|
+
NEEDS_RESOLUTION_LABEL = "needs_resolution_label"
|
|
43
|
+
"""
|
|
44
|
+
The label withholding a branch from promotion until a conflict is resolved.
|
|
45
|
+
"""
|
|
46
|
+
|
|
47
|
+
FORK_REPOSITORY = "fork_repository"
|
|
48
|
+
"""
|
|
49
|
+
The fork, for a checkout whose fork remote is ambiguous.
|
|
50
|
+
"""
|
|
51
|
+
|
|
52
|
+
FORK_REMOTE = "fork_remote"
|
|
53
|
+
"""
|
|
54
|
+
The git remote of the fork.
|
|
55
|
+
"""
|
|
56
|
+
|
|
57
|
+
UPSTREAM_REPOSITORY = "upstream_repository"
|
|
58
|
+
"""
|
|
59
|
+
The repository every fork is forked from and reviewed on.
|
|
60
|
+
"""
|
|
61
|
+
|
|
62
|
+
UPSTREAM_REMOTE = "upstream_remote"
|
|
63
|
+
"""
|
|
64
|
+
The name the upstream's tracking references are kept under when no remote points at
|
|
65
|
+
it.
|
|
66
|
+
"""
|
|
67
|
+
|
|
68
|
+
UPSTREAM_BASE = "upstream_base"
|
|
69
|
+
"""
|
|
70
|
+
The upstream branch every stack ultimately targets.
|
|
71
|
+
"""
|
|
72
|
+
|
|
73
|
+
UPSTREAM_LOCATION = "upstream_location"
|
|
74
|
+
"""
|
|
75
|
+
What the upstream is fetched from: its remote's name, or its URL when the checkout
|
|
76
|
+
has none. Resolved from the checkout rather than read from a ``stack.toml``.
|
|
77
|
+
"""
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
@dataclass
|
|
81
|
+
class MissingUpstreamRepositoryError(CommandFailure, LookupError):
|
|
82
|
+
"""
|
|
83
|
+
Raised when neither the project nor anything above it names the upstream repository.
|
|
84
|
+
"""
|
|
85
|
+
|
|
86
|
+
@classproperty
|
|
87
|
+
def exit_code(cls) -> StackExitCode:
|
|
88
|
+
""":return: The status this kind of error ends a command with."""
|
|
89
|
+
return StackExitCode.UPSTREAM_UNCONFIGURED
|
|
90
|
+
|
|
91
|
+
project_file: Path
|
|
92
|
+
"""
|
|
93
|
+
The file the project names its upstream in.
|
|
94
|
+
"""
|
|
95
|
+
|
|
96
|
+
personal_file: Path | None = None
|
|
97
|
+
"""
|
|
98
|
+
The personal-notes file that can name it instead, for a caller that reads that layer.
|
|
99
|
+
"""
|
|
100
|
+
|
|
101
|
+
def __str__(self) -> str:
|
|
102
|
+
""":return: Where to name the upstream, and how."""
|
|
103
|
+
alternative = (
|
|
104
|
+
f", or to {self.personal_file} on your personal-notes branch"
|
|
105
|
+
if self.personal_file
|
|
106
|
+
else ""
|
|
107
|
+
)
|
|
108
|
+
return (
|
|
109
|
+
f"no {StackSetting.UPSTREAM_REPOSITORY} is configured - add "
|
|
110
|
+
f'{StackSetting.UPSTREAM_REPOSITORY} = "<owner>/<name>" to {self.project_file}'
|
|
111
|
+
f"{alternative}"
|
|
112
|
+
)
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
@dataclass(frozen=True)
|
|
116
|
+
class CommittedStackConfiguration:
|
|
117
|
+
"""
|
|
118
|
+
The shipped defaults with a project's own committed settings layered on top.
|
|
119
|
+
"""
|
|
120
|
+
|
|
121
|
+
shipped: Path = PackageLocation.STACK_CONFIGURATION.value
|
|
122
|
+
"""
|
|
123
|
+
The defaults the package ships.
|
|
124
|
+
"""
|
|
125
|
+
|
|
126
|
+
project_root: Path = field(default_factory=Path.cwd)
|
|
127
|
+
"""
|
|
128
|
+
The project whose committed settings outrank them.
|
|
129
|
+
"""
|
|
130
|
+
|
|
131
|
+
@property
|
|
132
|
+
def project_file(self) -> Path:
|
|
133
|
+
"""
|
|
134
|
+
The project's own settings file, which may not exist.
|
|
135
|
+
"""
|
|
136
|
+
return self.project_root / ProjectLocation.PROJECT_STACK_CONFIGURATION
|
|
137
|
+
|
|
138
|
+
def values(self) -> dict[str, Any]:
|
|
139
|
+
"""
|
|
140
|
+
:return: The shipped values, with every key the project sets replaced by its own.
|
|
141
|
+
"""
|
|
142
|
+
values = tomllib.loads(TextFile(self.shipped).read())
|
|
143
|
+
if self.project_file.is_file():
|
|
144
|
+
values.update(tomllib.loads(TextFile(self.project_file).read()))
|
|
145
|
+
return values
|
|
146
|
+
|
|
147
|
+
def upstream_repository(self) -> Repository:
|
|
148
|
+
"""
|
|
149
|
+
:return: The repository the project's pull requests are reviewed on.
|
|
150
|
+
:raises MissingUpstreamRepositoryError: If the project names none.
|
|
151
|
+
"""
|
|
152
|
+
return self.upstream_repository_in(self.values())
|
|
153
|
+
|
|
154
|
+
def upstream_repository_in(
|
|
155
|
+
self, values: dict[str, Any], personal_file: Path | None = None
|
|
156
|
+
) -> Repository:
|
|
157
|
+
"""
|
|
158
|
+
:param values: Layered stack settings, of which this project's are a layer.
|
|
159
|
+
:param personal_file: Where the user could name the upstream instead, when
|
|
160
|
+
*values* include the personal-notes layer.
|
|
161
|
+
:return: The upstream repository the settings name.
|
|
162
|
+
:raises MissingUpstreamRepositoryError: If they name none.
|
|
163
|
+
"""
|
|
164
|
+
upstream_repository = self.named_upstream_repository(values)
|
|
165
|
+
if upstream_repository is None:
|
|
166
|
+
raise MissingUpstreamRepositoryError(self.project_file, personal_file)
|
|
167
|
+
return upstream_repository
|
|
168
|
+
|
|
169
|
+
@staticmethod
|
|
170
|
+
def named_upstream_repository(values: dict[str, Any]) -> Repository | None:
|
|
171
|
+
"""
|
|
172
|
+
:param values: Layered stack settings.
|
|
173
|
+
:return: The upstream repository they name, or ``None`` for a project that is
|
|
174
|
+
not a fork.
|
|
175
|
+
"""
|
|
176
|
+
if StackSetting.UPSTREAM_REPOSITORY not in values:
|
|
177
|
+
return None
|
|
178
|
+
return Repository.parse(values[StackSetting.UPSTREAM_REPOSITORY])
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
"""
|
|
2
|
+
The fixed values GitHub reports reviews, pull requests and checks in.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
from enum import StrEnum
|
|
8
|
+
from typing import Annotated, Any, Self
|
|
9
|
+
|
|
10
|
+
from pydantic import GetCoreSchemaHandler
|
|
11
|
+
from pydantic_core import core_schema
|
|
12
|
+
|
|
13
|
+
from basstler.json_model import RawValueReader
|
|
14
|
+
|
|
15
|
+
# %% values named as GitHub spells them
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class NamedAsGitHub(StrEnum):
|
|
19
|
+
"""
|
|
20
|
+
An enum whose members are named as GitHub spells its values, in any letter case,
|
|
21
|
+
while each member's value is how it reads in the report.
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
@classmethod
|
|
25
|
+
def from_github_name(cls, spelling: str) -> Self:
|
|
26
|
+
"""
|
|
27
|
+
:param spelling: A value as GitHub spells it, or a member already.
|
|
28
|
+
:return: The member it names.
|
|
29
|
+
:raises KeyError: If no member has that name.
|
|
30
|
+
"""
|
|
31
|
+
if isinstance(spelling, cls):
|
|
32
|
+
return spelling
|
|
33
|
+
return cls[spelling.upper()]
|
|
34
|
+
|
|
35
|
+
@classmethod
|
|
36
|
+
def __get_pydantic_core_schema__(
|
|
37
|
+
cls, source: type[Any], handler: GetCoreSchemaHandler
|
|
38
|
+
) -> core_schema.CoreSchema:
|
|
39
|
+
"""
|
|
40
|
+
:param source: The enum.
|
|
41
|
+
:param handler: Builds pydantic's own schema for a type, unused since the enum
|
|
42
|
+
replaces it.
|
|
43
|
+
:return: How pydantic reads a field of this enum: by :meth:`from_github_name`.
|
|
44
|
+
"""
|
|
45
|
+
return core_schema.no_info_plain_validator_function(
|
|
46
|
+
cls.from_github_name, json_schema_input_schema=core_schema.str_schema()
|
|
47
|
+
)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
class ReviewState(NamedAsGitHub):
|
|
51
|
+
"""
|
|
52
|
+
The verdict a reviewer submitted with a review.
|
|
53
|
+
"""
|
|
54
|
+
|
|
55
|
+
APPROVED = "approved"
|
|
56
|
+
"""
|
|
57
|
+
The reviewer approved the changes.
|
|
58
|
+
"""
|
|
59
|
+
|
|
60
|
+
CHANGES_REQUESTED = "changes requested"
|
|
61
|
+
"""
|
|
62
|
+
The reviewer asked for changes before the pull request can merge.
|
|
63
|
+
"""
|
|
64
|
+
|
|
65
|
+
COMMENTED = "commented"
|
|
66
|
+
"""
|
|
67
|
+
The reviewer left comments without a verdict.
|
|
68
|
+
"""
|
|
69
|
+
|
|
70
|
+
DISMISSED = "dismissed"
|
|
71
|
+
"""
|
|
72
|
+
The review was dismissed and no longer counts towards the verdict.
|
|
73
|
+
"""
|
|
74
|
+
|
|
75
|
+
PENDING = "pending"
|
|
76
|
+
"""
|
|
77
|
+
The review was started but not yet submitted.
|
|
78
|
+
"""
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
class PullRequestState(StrEnum):
|
|
82
|
+
"""
|
|
83
|
+
The lifecycle state GitHub reports for a pull request.
|
|
84
|
+
"""
|
|
85
|
+
|
|
86
|
+
OPEN = "OPEN"
|
|
87
|
+
CLOSED = "CLOSED"
|
|
88
|
+
MERGED = "MERGED"
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
# %% checks
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
class Conclusion(RawValueReader):
|
|
95
|
+
"""
|
|
96
|
+
Reads the conclusion GitHub gives a check run or workflow run, null while it runs,
|
|
97
|
+
as its :class:`CheckOutcome`.
|
|
98
|
+
"""
|
|
99
|
+
|
|
100
|
+
def read(self, value: str | None) -> CheckOutcome:
|
|
101
|
+
return CheckOutcome.from_conclusion(value)
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
class CheckOutcome(NamedAsGitHub):
|
|
105
|
+
"""
|
|
106
|
+
Where one check stands, over check runs and commit statuses alike.
|
|
107
|
+
|
|
108
|
+
A check run that has not finished reports no conclusion at all, which reads here as
|
|
109
|
+
:attr:`PENDING` so an unfinished check is never mistaken for a passing one.
|
|
110
|
+
"""
|
|
111
|
+
|
|
112
|
+
SUCCESS = "success"
|
|
113
|
+
"""
|
|
114
|
+
The check passed.
|
|
115
|
+
"""
|
|
116
|
+
|
|
117
|
+
FAILURE = "failure"
|
|
118
|
+
"""
|
|
119
|
+
The check failed.
|
|
120
|
+
"""
|
|
121
|
+
|
|
122
|
+
ERROR = "error"
|
|
123
|
+
"""
|
|
124
|
+
The commit status reported an error.
|
|
125
|
+
"""
|
|
126
|
+
|
|
127
|
+
CANCELLED = "cancelled"
|
|
128
|
+
"""
|
|
129
|
+
The check run was cancelled before it finished.
|
|
130
|
+
"""
|
|
131
|
+
|
|
132
|
+
TIMED_OUT = "timed out"
|
|
133
|
+
"""
|
|
134
|
+
The check run exceeded its time limit.
|
|
135
|
+
"""
|
|
136
|
+
|
|
137
|
+
ACTION_REQUIRED = "action required"
|
|
138
|
+
"""
|
|
139
|
+
The check run needs someone to act before it can conclude.
|
|
140
|
+
"""
|
|
141
|
+
|
|
142
|
+
NEUTRAL = "neutral"
|
|
143
|
+
"""
|
|
144
|
+
The check run finished without passing or failing.
|
|
145
|
+
"""
|
|
146
|
+
|
|
147
|
+
SKIPPED = "skipped"
|
|
148
|
+
"""
|
|
149
|
+
The check run was skipped.
|
|
150
|
+
"""
|
|
151
|
+
|
|
152
|
+
STALE = "stale"
|
|
153
|
+
"""
|
|
154
|
+
GitHub marked the check run stale after it went too long without finishing.
|
|
155
|
+
"""
|
|
156
|
+
|
|
157
|
+
@classmethod
|
|
158
|
+
def from_conclusion(cls, conclusion: str | None) -> CheckOutcome:
|
|
159
|
+
"""
|
|
160
|
+
:param conclusion: A check run's or workflow run's conclusion as GitHub spells
|
|
161
|
+
it, ``None`` while it runs.
|
|
162
|
+
:return: The outcome it reads as.
|
|
163
|
+
"""
|
|
164
|
+
return cls.from_github_name(conclusion) if conclusion else cls.PENDING
|
|
165
|
+
|
|
166
|
+
STARTUP_FAILURE = "startup failure"
|
|
167
|
+
"""
|
|
168
|
+
The check run failed before it could start.
|
|
169
|
+
"""
|
|
170
|
+
PENDING = "pending"
|
|
171
|
+
"""
|
|
172
|
+
The check has not finished yet.
|
|
173
|
+
"""
|
|
174
|
+
EXPECTED = "expected"
|
|
175
|
+
"""
|
|
176
|
+
A required commit status that has not been reported yet.
|
|
177
|
+
"""
|
|
178
|
+
|
|
179
|
+
@property
|
|
180
|
+
def combined_state(self) -> CombinedCheckState:
|
|
181
|
+
"""
|
|
182
|
+
:return: The verdict this outcome alone would give the combined state, the way
|
|
183
|
+
GitHub counts it: a neutral or skipped check does not hold a pull request
|
|
184
|
+
back, and everything that ended without passing fails it.
|
|
185
|
+
"""
|
|
186
|
+
if self in {CheckOutcome.SUCCESS, CheckOutcome.NEUTRAL, CheckOutcome.SKIPPED}:
|
|
187
|
+
return CombinedCheckState.SUCCESS
|
|
188
|
+
if self in {CheckOutcome.ERROR, CheckOutcome.PENDING, CheckOutcome.EXPECTED}:
|
|
189
|
+
return CombinedCheckState[self.name]
|
|
190
|
+
return CombinedCheckState.FAILURE
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
ConclusionOutcome = Annotated[CheckOutcome, Conclusion()]
|
|
194
|
+
"""
|
|
195
|
+
A check's outcome, read from the conclusion GitHub gives a check run or workflow run.
|
|
196
|
+
"""
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
class CombinedCheckState(NamedAsGitHub):
|
|
200
|
+
"""
|
|
201
|
+
The verdict GitHub itself computes over all of a pull request's checks, or that
|
|
202
|
+
nothing has reported one yet.
|
|
203
|
+
"""
|
|
204
|
+
|
|
205
|
+
SUCCESS = "success"
|
|
206
|
+
"""
|
|
207
|
+
Every check passed.
|
|
208
|
+
"""
|
|
209
|
+
|
|
210
|
+
FAILURE = "failure"
|
|
211
|
+
"""
|
|
212
|
+
At least one check failed.
|
|
213
|
+
"""
|
|
214
|
+
|
|
215
|
+
ERROR = "error"
|
|
216
|
+
"""
|
|
217
|
+
At least one commit status reported an error.
|
|
218
|
+
"""
|
|
219
|
+
|
|
220
|
+
PENDING = "pending"
|
|
221
|
+
"""
|
|
222
|
+
At least one check has not finished yet.
|
|
223
|
+
"""
|
|
224
|
+
|
|
225
|
+
EXPECTED = "expected"
|
|
226
|
+
"""
|
|
227
|
+
At least one required commit status has not been reported yet.
|
|
228
|
+
"""
|
|
229
|
+
|
|
230
|
+
NOT_REPORTED = "not reported"
|
|
231
|
+
"""
|
|
232
|
+
No check run or commit status has been reported at all.
|
|
233
|
+
"""
|
|
234
|
+
|
|
235
|
+
@property
|
|
236
|
+
def failed(self) -> bool:
|
|
237
|
+
""":return: Whether at least one check failed or reported an error."""
|
|
238
|
+
return self in {CombinedCheckState.FAILURE, CombinedCheckState.ERROR}
|
|
239
|
+
|
|
240
|
+
@classmethod
|
|
241
|
+
def over(cls, outcomes: list[CheckOutcome]) -> CombinedCheckState:
|
|
242
|
+
"""
|
|
243
|
+
Compute the verdict GitHub would over a set of checks, for a source that does
|
|
244
|
+
not report one: the worst any single check would give.
|
|
245
|
+
|
|
246
|
+
:param outcomes: Every check's outcome, at least one.
|
|
247
|
+
:return: The verdict.
|
|
248
|
+
"""
|
|
249
|
+
reached = {outcome.combined_state for outcome in outcomes}
|
|
250
|
+
return next(state for state in cls.severity_order() if state in reached)
|
|
251
|
+
|
|
252
|
+
@classmethod
|
|
253
|
+
def severity_order(cls) -> list[CombinedCheckState]:
|
|
254
|
+
"""
|
|
255
|
+
:return: Every verdict a reported check can give, worst first.
|
|
256
|
+
"""
|
|
257
|
+
return [cls.FAILURE, cls.ERROR, cls.PENDING, cls.EXPECTED, cls.SUCCESS]
|