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,159 @@
1
+ """
2
+ The forms GitHub's payloads write a thing a repository owns in - a branch, a pull
3
+ request - each read into the model of what it names and written back from it.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from abc import ABC, abstractmethod
9
+ from types import UnionType
10
+ from typing import Any, Union, get_args, get_origin
11
+
12
+ from pydantic import GetCoreSchemaHandler, ValidationInfo
13
+ from pydantic_core import core_schema
14
+
15
+ from basstler.git.branch import Branch
16
+ from basstler.github.exceptions import RepositoryUnknown
17
+ from basstler.github.repository import HasRepository, PullRequestReference, Repository
18
+ from basstler.json_model import ObjectReader
19
+
20
+ UNION_ORIGINS = (Union, UnionType)
21
+ """
22
+ What a union type, ``X | None`` included, reports as its origin.
23
+ """
24
+
25
+ # %% the form
26
+
27
+
28
+ class WireForm[ValueType](ABC):
29
+ """
30
+ A field annotation reading a thing a repository owns from the form a payload writes
31
+ it in, and writing it back in that form.
32
+ """
33
+
34
+ @abstractmethod
35
+ def read(self, value: Any, read: HasRepository | None) -> ValueType:
36
+ """
37
+ :param value: The thing as the payload writes it.
38
+ :param read: The read that was served the payload, ``None`` when there is none.
39
+ :return: The thing.
40
+ """
41
+
42
+ @abstractmethod
43
+ def write(self, owned: ValueType) -> Any:
44
+ """
45
+ :param owned: The thing.
46
+ :return: It, as the payload writes it.
47
+ """
48
+
49
+ def __get_pydantic_core_schema__(
50
+ self, source: type[Any], handler: GetCoreSchemaHandler
51
+ ) -> core_schema.CoreSchema:
52
+ """
53
+ :param source: The field's type.
54
+ :param handler: Builds pydantic's own schema for a type.
55
+ :return: How pydantic reads and writes the field: :meth:`read` and
56
+ :meth:`write`, a missing value left as ``None`` and a built one as it is.
57
+ """
58
+ alternatives = get_args(source) if get_origin(source) in UNION_ORIGINS else ()
59
+ value_types = tuple(
60
+ get_origin(alternative) or alternative
61
+ for alternative in alternatives or (source,)
62
+ )
63
+
64
+ def read_field(value: Any, information: ValidationInfo) -> ValueType | None:
65
+ if value is None or isinstance(value, value_types):
66
+ return value
67
+ return self.read(value, information.context)
68
+
69
+ return core_schema.with_info_plain_validator_function(
70
+ read_field,
71
+ serialization=core_schema.plain_serializer_function_ser_schema(
72
+ self.write, when_used="unless-none"
73
+ ),
74
+ )
75
+
76
+
77
+ # %% a branch of the repository read
78
+
79
+
80
+ class ReadRepositoryBranchForm(WireForm[Branch[Repository]], ABC):
81
+ """
82
+ A form naming a branch of the repository the payload was read from, by text alone.
83
+ """
84
+
85
+ @abstractmethod
86
+ def name_in(self, text: str) -> str:
87
+ """
88
+ :param text: The branch as the payload writes it.
89
+ :return: The branch's name.
90
+ """
91
+
92
+ def read(self, value: Any, read: HasRepository | None) -> Branch[Repository]:
93
+ name = self.name_in(value)
94
+ if read is None:
95
+ raise RepositoryUnknown(name)
96
+ return Branch(read.repository, name)
97
+
98
+
99
+ class BranchName(ReadRepositoryBranchForm):
100
+ """
101
+ A branch written as its bare name, ``main``.
102
+ """
103
+
104
+ def name_in(self, text: str) -> str:
105
+ return text
106
+
107
+ def write(self, owned: Branch[Repository]) -> str:
108
+ return owned.name
109
+
110
+
111
+ class BranchFullReference(ReadRepositoryBranchForm):
112
+ """
113
+ A branch written as the full reference it is kept under, ``refs/heads/main``.
114
+ """
115
+
116
+ def name_in(self, text: str) -> str:
117
+ return text.removeprefix(f"{Branch.namespace}/")
118
+
119
+ def write(self, owned: Branch[Repository]) -> str:
120
+ return owned.reference
121
+
122
+
123
+ # %% a branch of a repository the payload names
124
+
125
+
126
+ class RepositoryDefaultBranch(WireForm[Branch[Repository]], ObjectReader):
127
+ """
128
+ A repository's default branch, written as the repository resource that names it.
129
+ """
130
+
131
+ @property
132
+ def read_keys(self) -> frozenset[str]:
133
+ return frozenset({"full_name", "default_branch"})
134
+
135
+ def read(self, value: Any, read: HasRepository | None) -> Branch[Repository]:
136
+ return Branch(Repository.parse(value["full_name"]), value["default_branch"])
137
+
138
+ def write(self, owned: Branch[Repository]) -> dict[str, str]:
139
+ return {
140
+ "full_name": owned.repository.full_name,
141
+ "default_branch": owned.name,
142
+ }
143
+
144
+
145
+ # %% a pull request of the repository read
146
+
147
+
148
+ class PullRequestNumber(WireForm[PullRequestReference]):
149
+ """
150
+ A pull request of the repository the payload was read from, written as its number.
151
+ """
152
+
153
+ def read(self, value: Any, read: HasRepository | None) -> PullRequestReference:
154
+ if read is None:
155
+ raise RepositoryUnknown(f"#{value}")
156
+ return PullRequestReference(read.repository, value)
157
+
158
+ def write(self, owned: PullRequestReference) -> int:
159
+ return owned.number
@@ -0,0 +1,126 @@
1
+ """
2
+ One run of a GitHub Actions workflow, and the jobs it ran.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from dataclasses import dataclass
8
+ from typing import Annotated, Any
9
+
10
+ from pydantic import Field
11
+
12
+ from basstler.class_property import classproperty
13
+ from basstler.github.workflows import RepositoryWorkflow
14
+ from basstler.github.client import HttpMethod, RepositoryWrite
15
+ from basstler.github.repository import Repository
16
+ from basstler.github.states import CheckOutcome, ConclusionOutcome
17
+ from basstler.json_model import JSONModel, ValidatedJSONModel
18
+
19
+ # %% a run
20
+
21
+
22
+ class WorkflowRun(ValidatedJSONModel):
23
+ """
24
+ One run of a workflow.
25
+ """
26
+
27
+ identifier: Annotated[int, Field(alias="id")]
28
+ """
29
+ The run's own number, which its page is addressed by.
30
+ """
31
+
32
+ commit: Annotated[str, Field(alias="head_sha")]
33
+ """
34
+ The commit it ran on.
35
+ """
36
+
37
+ outcome: Annotated[ConclusionOutcome, Field(alias="conclusion")]
38
+ """
39
+ How it ended, :attr:`CheckOutcome.PENDING` while it runs.
40
+ """
41
+
42
+ @property
43
+ def failed(self) -> bool:
44
+ """:return: Whether it ended without succeeding."""
45
+ return self.outcome not in {CheckOutcome.SUCCESS, CheckOutcome.PENDING}
46
+
47
+
48
+ # %% the jobs it ran
49
+
50
+
51
+ @dataclass(frozen=True)
52
+ class RunJob(JSONModel):
53
+ """
54
+ One job of a workflow run.
55
+ """
56
+
57
+ name: str
58
+ """
59
+ The job's name, as the run lists it.
60
+ """
61
+
62
+ outcome: CheckOutcome
63
+ """
64
+ How it ended, :attr:`CheckOutcome.PENDING` while it runs.
65
+ """
66
+
67
+ @classmethod
68
+ def from_json(cls, data: dict[str, Any]) -> RunJob:
69
+ return cls(data["name"], CheckOutcome.from_conclusion(data["conclusion"]))
70
+
71
+
72
+ @dataclass(frozen=True)
73
+ class RunJobPage(JSONModel):
74
+ """
75
+ The jobs one workflow run lists, as many as one page holds.
76
+ """
77
+
78
+ jobs: list[RunJob]
79
+ """
80
+ The jobs, in the order the run lists them.
81
+ """
82
+
83
+ @classproperty
84
+ def maximum_jobs_per_page(cls) -> int:
85
+ """
86
+ The most jobs GitHub lists on one page.
87
+ """
88
+ return 100
89
+
90
+ @classmethod
91
+ def path(cls, repository: Repository, run: int) -> str:
92
+ """
93
+ :param repository: The repository the run ran in.
94
+ :param run: The run's own number.
95
+ :return: The REST path listing its jobs.
96
+ """
97
+ return (
98
+ f"{repository.workflow_run_path(run)}/jobs"
99
+ f"?per_page={cls.maximum_jobs_per_page}"
100
+ )
101
+
102
+ @classmethod
103
+ def from_json(cls, data: dict[str, Any]) -> RunJobPage:
104
+ return cls([RunJob.from_json(job) for job in data["jobs"]])
105
+
106
+
107
+ # %% starting a run
108
+
109
+
110
+ class WorkflowDispatch(RepositoryWorkflow, RepositoryWrite):
111
+ """
112
+ A request to run a workflow.
113
+ """
114
+
115
+ branch: Annotated[str, Field(alias="ref")]
116
+ """
117
+ The branch the workflow runs on.
118
+ """
119
+
120
+ @classproperty
121
+ def method(cls) -> HttpMethod:
122
+ return HttpMethod.POST
123
+
124
+ @property
125
+ def path(self) -> str:
126
+ return self.repository.workflow_dispatch_path(self.workflow_path)