basstler-notes 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/document_references.py +296 -0
- basstler/personal_notes/__init__.py +0 -0
- basstler/personal_notes/access.py +141 -0
- basstler/personal_notes/branch.py +289 -0
- basstler/personal_notes/git_identity.py +134 -0
- basstler/personal_notes/progress_notes.py +400 -0
- basstler/setup/__init__.py +0 -0
- basstler/setup/dependencies.py +433 -0
- basstler/setup/exceptions.py +154 -0
- basstler/setup/gate.py +283 -0
- basstler/setup/personal_notes.py +474 -0
- basstler/setup/report.py +346 -0
- basstler/setup/steps.py +790 -0
- basstler_notes-4.2.0.dist-info/METADATA +17 -0
- basstler_notes-4.2.0.dist-info/RECORD +18 -0
- basstler_notes-4.2.0.dist-info/WHEEL +4 -0
- basstler_notes-4.2.0.dist-info/licenses/LICENSE +202 -0
- basstler_notes-4.2.0.dist-info/licenses/NOTICE +13 -0
|
@@ -0,0 +1,289 @@
|
|
|
1
|
+
"""
|
|
2
|
+
The personal-notes branch: where it lives, fetching it, and writing files onto it.
|
|
3
|
+
|
|
4
|
+
Every write goes through a scratch worktree of the fetched branch, so the checkout a
|
|
5
|
+
session works in is never switched or touched.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import tempfile
|
|
11
|
+
from abc import ABC, abstractmethod
|
|
12
|
+
from collections.abc import Mapping
|
|
13
|
+
from dataclasses import dataclass, field
|
|
14
|
+
from enum import StrEnum
|
|
15
|
+
from pathlib import Path, PurePosixPath
|
|
16
|
+
from types import TracebackType
|
|
17
|
+
|
|
18
|
+
from basstler.directory_tree import DirectoryTree
|
|
19
|
+
from basstler.exceptions import (
|
|
20
|
+
NotesBranchMissingError,
|
|
21
|
+
NotesPushRejectedError,
|
|
22
|
+
UnsafeNotesPathError,
|
|
23
|
+
)
|
|
24
|
+
from basstler.git.commands import GitCommandRunner
|
|
25
|
+
from basstler.setup.steps import PersonalNotesSetting
|
|
26
|
+
from basstler.shell_configuration import FetchedBranchReference
|
|
27
|
+
from basstler.text_file import TextFile
|
|
28
|
+
|
|
29
|
+
NO_HOOKS_DIRECTORY = "/dev/null"
|
|
30
|
+
"""
|
|
31
|
+
A hooks directory holding no hooks, so git runs none.
|
|
32
|
+
"""
|
|
33
|
+
|
|
34
|
+
# %% where the notes live
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
@dataclass(frozen=True)
|
|
38
|
+
class PersonalNotesLocation:
|
|
39
|
+
"""
|
|
40
|
+
Where a clone's personal notes are kept.
|
|
41
|
+
"""
|
|
42
|
+
|
|
43
|
+
remote: str
|
|
44
|
+
"""
|
|
45
|
+
The remote the notes branch is fetched from and pushed to: a name or a URL.
|
|
46
|
+
"""
|
|
47
|
+
|
|
48
|
+
branch: str
|
|
49
|
+
"""
|
|
50
|
+
The branch holding the notes.
|
|
51
|
+
"""
|
|
52
|
+
|
|
53
|
+
notes_path: str
|
|
54
|
+
"""
|
|
55
|
+
The personal-notes file, relative to the branch's root.
|
|
56
|
+
"""
|
|
57
|
+
|
|
58
|
+
@classmethod
|
|
59
|
+
def resolve(
|
|
60
|
+
cls, project_root: Path, environment: Mapping[str, str]
|
|
61
|
+
) -> PersonalNotesLocation:
|
|
62
|
+
"""
|
|
63
|
+
:param project_root: The clone whose git config to read.
|
|
64
|
+
:param environment: The environment to read the settings' variables from.
|
|
65
|
+
:return: The location the hooks resolve for that clone.
|
|
66
|
+
"""
|
|
67
|
+
return cls(
|
|
68
|
+
remote=PersonalNotesSetting.REMOTE.resolve(project_root, environment),
|
|
69
|
+
branch=PersonalNotesSetting.BRANCH.resolve(project_root, environment),
|
|
70
|
+
notes_path=PersonalNotesSetting.PATH.resolve(project_root, environment),
|
|
71
|
+
)
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
# %% fetching
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
@dataclass(frozen=True)
|
|
78
|
+
class PersonalNotesBranch:
|
|
79
|
+
"""
|
|
80
|
+
The personal-notes branch, as one clone reaches it.
|
|
81
|
+
"""
|
|
82
|
+
|
|
83
|
+
location: PersonalNotesLocation
|
|
84
|
+
"""
|
|
85
|
+
Where the notes are kept.
|
|
86
|
+
"""
|
|
87
|
+
|
|
88
|
+
git: GitCommandRunner
|
|
89
|
+
"""
|
|
90
|
+
The clone that fetches the branch.
|
|
91
|
+
"""
|
|
92
|
+
|
|
93
|
+
def candidate_remotes(self) -> list[str]:
|
|
94
|
+
"""
|
|
95
|
+
:return: The configured remote, then the current branch's upstream remote when
|
|
96
|
+
that is a different one.
|
|
97
|
+
"""
|
|
98
|
+
remotes = [self.location.remote]
|
|
99
|
+
upstream = self.git.attempt(
|
|
100
|
+
"rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"
|
|
101
|
+
)
|
|
102
|
+
upstream_remote = upstream.output.split("/", 1)[0] if upstream.succeeded else ""
|
|
103
|
+
if upstream_remote and upstream_remote not in remotes:
|
|
104
|
+
remotes.append(upstream_remote)
|
|
105
|
+
return remotes
|
|
106
|
+
|
|
107
|
+
def fetch(self) -> str:
|
|
108
|
+
"""
|
|
109
|
+
Fetch the branch into :attr:`FetchedBranchReference.PERSONAL_NOTES` from the
|
|
110
|
+
first remote that has it.
|
|
111
|
+
|
|
112
|
+
:return: That remote.
|
|
113
|
+
:raises NotesBranchMissingError: If no candidate remote has the branch.
|
|
114
|
+
"""
|
|
115
|
+
remotes = self.candidate_remotes()
|
|
116
|
+
for remote in remotes:
|
|
117
|
+
if self.git.attempt(
|
|
118
|
+
"fetch",
|
|
119
|
+
"--quiet",
|
|
120
|
+
"--no-write-fetch-head",
|
|
121
|
+
remote,
|
|
122
|
+
f"+refs/heads/{self.location.branch}:"
|
|
123
|
+
f"{FetchedBranchReference.PERSONAL_NOTES}",
|
|
124
|
+
).succeeded:
|
|
125
|
+
return remote
|
|
126
|
+
raise NotesBranchMissingError(self.location.branch, tuple(remotes))
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
# %% writing
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
class NotesWriteOutcome(StrEnum):
|
|
133
|
+
"""
|
|
134
|
+
What a write did to the notes branch.
|
|
135
|
+
"""
|
|
136
|
+
|
|
137
|
+
PUSHED = "pushed"
|
|
138
|
+
"""
|
|
139
|
+
The changes were committed and pushed.
|
|
140
|
+
"""
|
|
141
|
+
|
|
142
|
+
UNCHANGED = "unchanged"
|
|
143
|
+
"""
|
|
144
|
+
The branch already held every change, so nothing was committed.
|
|
145
|
+
"""
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
@dataclass
|
|
149
|
+
class ScratchWorktree:
|
|
150
|
+
"""
|
|
151
|
+
A detached worktree of :attr:`FetchedBranchReference.PERSONAL_NOTES` in a temporary
|
|
152
|
+
directory, removed on exit.
|
|
153
|
+
"""
|
|
154
|
+
|
|
155
|
+
git: GitCommandRunner
|
|
156
|
+
"""
|
|
157
|
+
The clone the worktree belongs to.
|
|
158
|
+
"""
|
|
159
|
+
|
|
160
|
+
directory: Path = field(init=False)
|
|
161
|
+
"""
|
|
162
|
+
The worktree's root, once entered.
|
|
163
|
+
"""
|
|
164
|
+
|
|
165
|
+
def __enter__(self) -> GitCommandRunner:
|
|
166
|
+
"""
|
|
167
|
+
:return: A runner for the new worktree.
|
|
168
|
+
"""
|
|
169
|
+
self.directory = Path(tempfile.mkdtemp())
|
|
170
|
+
self.git.run(
|
|
171
|
+
"worktree",
|
|
172
|
+
"add",
|
|
173
|
+
"--detach",
|
|
174
|
+
"--quiet",
|
|
175
|
+
str(self.directory),
|
|
176
|
+
FetchedBranchReference.PERSONAL_NOTES,
|
|
177
|
+
)
|
|
178
|
+
return GitCommandRunner(self.directory)
|
|
179
|
+
|
|
180
|
+
def __exit__(
|
|
181
|
+
self,
|
|
182
|
+
exception_type: type[BaseException] | None,
|
|
183
|
+
exception: BaseException | None,
|
|
184
|
+
traceback: TracebackType | None,
|
|
185
|
+
) -> None:
|
|
186
|
+
"""
|
|
187
|
+
Remove the worktree, whether or not the write succeeded.
|
|
188
|
+
"""
|
|
189
|
+
self.git.attempt("worktree", "remove", "--force", str(self.directory))
|
|
190
|
+
DirectoryTree(self.directory).remove()
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
class NotesEdit(ABC):
|
|
194
|
+
"""
|
|
195
|
+
A change made to a checkout of the notes branch, which a writer commits and pushes.
|
|
196
|
+
"""
|
|
197
|
+
|
|
198
|
+
@abstractmethod
|
|
199
|
+
def apply(self, root: Path) -> None:
|
|
200
|
+
"""
|
|
201
|
+
Make the change.
|
|
202
|
+
|
|
203
|
+
:param root: The root of a checkout of the latest notes branch.
|
|
204
|
+
"""
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
@dataclass(frozen=True)
|
|
208
|
+
class NotesFileChanges(NotesEdit):
|
|
209
|
+
"""
|
|
210
|
+
New contents for files on the notes branch.
|
|
211
|
+
"""
|
|
212
|
+
|
|
213
|
+
changes: Mapping[PurePosixPath, str | None]
|
|
214
|
+
"""
|
|
215
|
+
Each path relative to the branch's root, with its new content, or ``None`` to remove
|
|
216
|
+
the file or directory there.
|
|
217
|
+
"""
|
|
218
|
+
|
|
219
|
+
def __post_init__(self) -> None:
|
|
220
|
+
"""
|
|
221
|
+
:raises UnsafeNotesPathError: If a path is absolute or contains ``..``.
|
|
222
|
+
"""
|
|
223
|
+
for path in self.changes:
|
|
224
|
+
if path.is_absolute() or ".." in path.parts:
|
|
225
|
+
raise UnsafeNotesPathError(path)
|
|
226
|
+
|
|
227
|
+
def apply(self, root: Path) -> None:
|
|
228
|
+
for path, content in self.changes.items():
|
|
229
|
+
target = root / path
|
|
230
|
+
if content is None and target.is_dir():
|
|
231
|
+
DirectoryTree(target).remove()
|
|
232
|
+
continue
|
|
233
|
+
if content is None:
|
|
234
|
+
target.unlink(missing_ok=True)
|
|
235
|
+
continue
|
|
236
|
+
target.parent.mkdir(parents=True, exist_ok=True)
|
|
237
|
+
TextFile(target).write(content)
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
@dataclass(frozen=True)
|
|
241
|
+
class NotesBranchWriter:
|
|
242
|
+
"""
|
|
243
|
+
Commits edits onto the personal-notes branch and pushes them.
|
|
244
|
+
"""
|
|
245
|
+
|
|
246
|
+
branch: PersonalNotesBranch
|
|
247
|
+
"""
|
|
248
|
+
The branch written to.
|
|
249
|
+
"""
|
|
250
|
+
|
|
251
|
+
push_attempts: int = 1
|
|
252
|
+
"""
|
|
253
|
+
How many times an edit is applied to the latest branch and pushed before a push the
|
|
254
|
+
remote keeps rejecting is given up on.
|
|
255
|
+
"""
|
|
256
|
+
|
|
257
|
+
def write(self, edit: NotesEdit, message: str) -> NotesWriteOutcome:
|
|
258
|
+
"""
|
|
259
|
+
Apply *edit* to the latest notes branch in one commit, and push it to the remote
|
|
260
|
+
it was fetched from; a rejected push is retried from a fresh fetch. The
|
|
261
|
+
project's commit hooks do not run: the notes branch carries none of the
|
|
262
|
+
project's files they check.
|
|
263
|
+
|
|
264
|
+
:param edit: The change to make.
|
|
265
|
+
:param message: The commit message.
|
|
266
|
+
:raises NotesBranchMissingError: If no remote has the branch.
|
|
267
|
+
:raises NotesPushRejectedError: If every push attempt was rejected.
|
|
268
|
+
:return: Whether anything was pushed.
|
|
269
|
+
"""
|
|
270
|
+
for _ in range(self.push_attempts):
|
|
271
|
+
remote = self.branch.fetch()
|
|
272
|
+
with ScratchWorktree(self.branch.git) as worktree:
|
|
273
|
+
edit.apply(worktree.working_directory)
|
|
274
|
+
worktree.run("add", "--all")
|
|
275
|
+
if worktree.attempt("diff", "--cached", "--quiet").succeeded:
|
|
276
|
+
return NotesWriteOutcome.UNCHANGED
|
|
277
|
+
worktree.run(
|
|
278
|
+
"-c",
|
|
279
|
+
f"core.hooksPath={NO_HOOKS_DIRECTORY}",
|
|
280
|
+
"commit",
|
|
281
|
+
"--quiet",
|
|
282
|
+
"-m",
|
|
283
|
+
message,
|
|
284
|
+
)
|
|
285
|
+
if worktree.attempt(
|
|
286
|
+
"push", "--quiet", remote, f"HEAD:{self.branch.location.branch}"
|
|
287
|
+
).succeeded:
|
|
288
|
+
return NotesWriteOutcome.PUSHED
|
|
289
|
+
raise NotesPushRejectedError(self.branch.location.branch, self.push_attempts)
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Print where on the personal-notes branch this session's git identity is recorded.
|
|
3
|
+
|
|
4
|
+
The notes repository's owner keeps the identity at :attr:`ProjectLocation.GIT_IDENTITY`.
|
|
5
|
+
Everyone else who shares the notes branch, a collaborator of a team repository, keeps
|
|
6
|
+
one of their own below :attr:`ProjectLocation.CONTRIBUTOR_GIT_IDENTITIES`, named after
|
|
7
|
+
their GitHub login, so each authors their commits as themselves.
|
|
8
|
+
|
|
9
|
+
Usage:
|
|
10
|
+
"${BASSTLER_PYTHON}" -m basstler.personal_notes.git_identity
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
import os
|
|
16
|
+
from collections.abc import Mapping
|
|
17
|
+
from dataclasses import dataclass
|
|
18
|
+
from pathlib import Path, PurePosixPath
|
|
19
|
+
|
|
20
|
+
from cyclopts import App
|
|
21
|
+
|
|
22
|
+
from basstler.exit_codes import StackExitCode
|
|
23
|
+
from basstler.git.commands import GitCommandRunner
|
|
24
|
+
from basstler.github.client import GitHubAttemptClient, GitHubRestClient
|
|
25
|
+
from basstler.github.pull_request_record import AccountField
|
|
26
|
+
from basstler.github.repository import Repository
|
|
27
|
+
from basstler.github.repository_access import GitHubPath
|
|
28
|
+
from basstler.locations import ClaudeCodeVariable, ProjectLocation
|
|
29
|
+
from basstler.personal_notes.branch import PersonalNotesLocation
|
|
30
|
+
from basstler.standard_streams import StandardStreamHandler
|
|
31
|
+
|
|
32
|
+
logger = StandardStreamHandler.logger_for(__name__)
|
|
33
|
+
"""
|
|
34
|
+
This module's logger, which is also what its command prints through.
|
|
35
|
+
"""
|
|
36
|
+
|
|
37
|
+
# %% whose identity applies
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
@dataclass(frozen=True, kw_only=True)
|
|
41
|
+
class GitIdentityRecord:
|
|
42
|
+
"""
|
|
43
|
+
Which identity file on the notes branch belongs to the account a session works as.
|
|
44
|
+
"""
|
|
45
|
+
|
|
46
|
+
notes_repository: Repository | None
|
|
47
|
+
"""
|
|
48
|
+
The repository holding the notes branch, ``None`` when its remote names no GitHub
|
|
49
|
+
repository.
|
|
50
|
+
"""
|
|
51
|
+
|
|
52
|
+
login: str | None
|
|
53
|
+
"""
|
|
54
|
+
The GitHub login the session's credential belongs to, ``None`` when it is unknown.
|
|
55
|
+
"""
|
|
56
|
+
|
|
57
|
+
@classmethod
|
|
58
|
+
def of_session(
|
|
59
|
+
cls,
|
|
60
|
+
*,
|
|
61
|
+
project_root: Path,
|
|
62
|
+
environment: Mapping[str, str],
|
|
63
|
+
client: GitHubAttemptClient,
|
|
64
|
+
) -> GitIdentityRecord:
|
|
65
|
+
"""
|
|
66
|
+
:param project_root: The clone whose notes settings are read.
|
|
67
|
+
:param environment: The environment the notes settings are read from.
|
|
68
|
+
:param client: Asks GitHub whose credential the session holds.
|
|
69
|
+
:return: The record for the account the session works as.
|
|
70
|
+
"""
|
|
71
|
+
git = GitCommandRunner(project_root)
|
|
72
|
+
notes_remote = PersonalNotesLocation.resolve(project_root, environment).remote
|
|
73
|
+
notes_url = git.configured_remote_url(notes_remote) or notes_remote
|
|
74
|
+
notes_repository = (
|
|
75
|
+
Repository.from_remote_url(notes_url)
|
|
76
|
+
if Repository.names_a_repository(notes_url)
|
|
77
|
+
else None
|
|
78
|
+
)
|
|
79
|
+
account = client.attempt_get(str(GitHubPath.AUTHENTICATED_USER))
|
|
80
|
+
login = (
|
|
81
|
+
None if account.failure is not None else account.body[AccountField.LOGIN]
|
|
82
|
+
)
|
|
83
|
+
return cls(notes_repository=notes_repository, login=login)
|
|
84
|
+
|
|
85
|
+
@property
|
|
86
|
+
def is_owner(self) -> bool:
|
|
87
|
+
"""
|
|
88
|
+
Whether the session works as the notes repository's owner.
|
|
89
|
+
|
|
90
|
+
Also true when either side is unknown, so a notes branch nothing can attribute
|
|
91
|
+
keeps the one identity it always had.
|
|
92
|
+
"""
|
|
93
|
+
if self.notes_repository is None or self.login is None:
|
|
94
|
+
return True
|
|
95
|
+
return self.notes_repository.owner.casefold() == self.login.casefold()
|
|
96
|
+
|
|
97
|
+
@property
|
|
98
|
+
def path(self) -> PurePosixPath:
|
|
99
|
+
"""
|
|
100
|
+
The identity file's path on the notes branch, ``/``-separated on every platform.
|
|
101
|
+
"""
|
|
102
|
+
if self.is_owner:
|
|
103
|
+
return PurePosixPath(ProjectLocation.GIT_IDENTITY)
|
|
104
|
+
return PurePosixPath(ProjectLocation.CONTRIBUTOR_GIT_IDENTITIES) / self.login
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
# %% the command line
|
|
108
|
+
|
|
109
|
+
app = App(help=__doc__)
|
|
110
|
+
"""
|
|
111
|
+
The command, which takes no arguments.
|
|
112
|
+
"""
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
@app.default
|
|
116
|
+
def print_git_identity_path() -> StackExitCode:
|
|
117
|
+
"""
|
|
118
|
+
Print the path of the identity file that belongs to this session's account.
|
|
119
|
+
|
|
120
|
+
:return: :attr:`StackExitCode.SUCCESS`, also when GitHub does not say who the
|
|
121
|
+
session is: the owner's path is the answer then.
|
|
122
|
+
"""
|
|
123
|
+
project_root = Path(
|
|
124
|
+
os.environ.get(ClaudeCodeVariable.PROJECT_DIRECTORY, Path.cwd())
|
|
125
|
+
)
|
|
126
|
+
record = GitIdentityRecord.of_session(
|
|
127
|
+
project_root=project_root, environment=os.environ, client=GitHubRestClient()
|
|
128
|
+
)
|
|
129
|
+
logger.info(str(record.path))
|
|
130
|
+
return StackExitCode.SUCCESS
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
if __name__ == "__main__":
|
|
134
|
+
app()
|