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.
@@ -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()