fairshare-cli 0.1.1__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.
fairshare/hub.py ADDED
@@ -0,0 +1,272 @@
1
+ """The hub: one folder that makes several accounts one assistant. Provider-neutral; a provider
2
+ says only which items are shared (`Provider.shared`, a name ending in "/" is a folder).
3
+
4
+ <hub>/shared/ the shared items
5
+ <hub>/accounts/<id>/ one config folder per account: its own login and state, and a RELATIVE
6
+ link for every shared item (projects -> ../../shared/projects), so the
7
+ whole hub can be moved
8
+ <hub>/backups/ whatever fairshare moves aside. fairshare never deletes.
9
+
10
+ Nothing here writes outside the hub except `seed`, which only reads the user's folder."""
11
+ from __future__ import annotations
12
+
13
+ import difflib
14
+ import filecmp
15
+ import os
16
+ import shutil
17
+ import tempfile
18
+ import time
19
+ from pathlib import Path
20
+
21
+ from . import store
22
+
23
+
24
+ def shared_dir(hub: Path) -> Path:
25
+ return hub / "shared"
26
+
27
+
28
+ def accounts_dir(hub: Path) -> Path:
29
+ return hub / "accounts"
30
+
31
+
32
+ def account_dir(hub: Path, account_id: str) -> Path:
33
+ return accounts_dir(hub) / account_id
34
+
35
+
36
+ def present(hub: Path, account_id: str | None = None) -> bool:
37
+ """Whether a hub is at `hub` (its shared/ and accounts/ folders, and the account's folder
38
+ when one is named). A launch never builds a hub: after a move it would silently start an
39
+ empty one at the old path."""
40
+ return shared_dir(hub).is_dir() and accounts_dir(hub).is_dir() and (
41
+ account_id is None or account_dir(hub, account_id).is_dir())
42
+
43
+
44
+ def lock(hub: Path):
45
+ """Held while the hub's links or shared items change: two launches must not repair at once."""
46
+ return store.locked(hub / ".lock")
47
+
48
+
49
+ def backup_dir(hub: Path, label: str) -> Path:
50
+ """A new folder name under backups/ for what one run moves aside (created when used)."""
51
+ return store.free_name(hub / "backups" / f"{time.strftime('%Y%m%d-%H%M%S')}-{label}")
52
+
53
+
54
+ def _items(prov) -> list[tuple[str, bool]]:
55
+ return [(i.rstrip("/"), i.endswith("/")) for i in prov.shared]
56
+
57
+
58
+ def _same(a: Path, b: Path) -> bool:
59
+ if a.is_symlink() or b.is_symlink():
60
+ return a.is_symlink() and b.is_symlink() and os.readlink(a) == os.readlink(b)
61
+ return a.is_file() and b.is_file() and filecmp.cmp(a, b, shallow=False)
62
+
63
+
64
+ def _suffixed(p: Path, label: str, n: int) -> Path:
65
+ tag = f"from-{label}" + (f"-{n}" if n > 1 else "")
66
+ return p.with_name(f"{p.stem}.{tag}{p.suffix}")
67
+
68
+
69
+ def _place(src: Path, dest: Path, label: str, move: bool) -> bool:
70
+ """Put the file (or link) `src` at `dest` in shared/. A clash keeps both: the incoming one
71
+ takes a name naming `label`. An identical file is not placed twice. True when placed."""
72
+ target, n = dest, 1
73
+ while os.path.lexists(target):
74
+ if _same(src, target):
75
+ return False
76
+ target, n = _suffixed(dest, label, n), n + 1
77
+ target.parent.mkdir(parents=True, exist_ok=True)
78
+ if move:
79
+ os.rename(src, target)
80
+ elif src.is_symlink():
81
+ os.symlink(os.readlink(src), target)
82
+ else: # a copy keeps the times: sessions sort by them
83
+ fd, tmp = tempfile.mkstemp(dir=target.parent)
84
+ os.close(fd)
85
+ shutil.copy2(src, tmp)
86
+ os.replace(tmp, target)
87
+ return True
88
+
89
+
90
+ def _merge_tree(src: Path, dest: Path, label: str, move: bool) -> int:
91
+ """Every file under `src` into `dest` by `_place`; returns how many were placed."""
92
+ placed = 0
93
+ for root, dirs, files in os.walk(src):
94
+ here = Path(root)
95
+ links = [d for d in dirs if (here / d).is_symlink()] # a linked folder is an entry
96
+ dirs[:] = [d for d in dirs if d not in links]
97
+ for name in sorted(files + links):
98
+ placed += _place(here / name, dest / here.relative_to(src) / name, label, move)
99
+ return placed
100
+
101
+
102
+ def _append_missing(src: Path, dest: Path) -> int:
103
+ """Append to `dest` the lines of `src` it lacks, in their order; returns how many."""
104
+ have = dest.read_bytes() if dest.exists() else b""
105
+ seen, add = set(have.splitlines()), []
106
+ for line in src.read_bytes().splitlines():
107
+ if line and line not in seen:
108
+ seen.add(line)
109
+ add.append(line)
110
+ if add:
111
+ with open(dest, "ab") as f:
112
+ f.write((b"\n" if have and not have.endswith(b"\n") else b"") + b"\n".join(add) + b"\n")
113
+ return len(add)
114
+
115
+
116
+ def _write_bytes(dest: Path, data: bytes, mode_from: Path | None = None) -> None:
117
+ """Write a new file atomically (through a symlink, never over it)."""
118
+ if dest.is_symlink():
119
+ dest = dest.resolve()
120
+ dest.parent.mkdir(parents=True, exist_ok=True)
121
+ fd, tmp = tempfile.mkstemp(dir=dest.parent)
122
+ with os.fdopen(fd, "wb") as f:
123
+ f.write(data)
124
+ if mode_from is not None:
125
+ os.chmod(tmp, mode_from.stat().st_mode & 0o777)
126
+ os.replace(tmp, dest)
127
+
128
+
129
+ def diff(prov, item: str, ours: bytes, theirs: bytes, theirs_name: str) -> str:
130
+ """The differences the user is shown, values that may be secrets hidden by the provider."""
131
+ try:
132
+ a = prov.masked(item, ours.decode("utf-8"))
133
+ b = prov.masked(item, theirs.decode("utf-8"))
134
+ except UnicodeDecodeError:
135
+ return " (not text: no diff shown)\n"
136
+ return "".join(difflib.unified_diff(a.splitlines(True), b.splitlines(True),
137
+ f"shared/{item}", theirs_name))
138
+
139
+
140
+ def check(hub: Path, account_id: str, prov) -> list[str]:
141
+ """The start check, run before every launch: make the account's links right, never losing
142
+ content. Returns one line per item it changed (a diff follows the line where one is due).
143
+ - missing link: created (all new links of one run are reported in one line);
144
+ - a real folder: its files are merged into shared/ (a clash keeps both, the incoming one
145
+ named after the account), then the emptied folder goes to backups/ and the link is made;
146
+ - a real `.jsonl` file: shared/ gets the lines it lacks, in order; the file goes to backups/;
147
+ - another real file: moved into shared/ when shared/ has none; else, identical or not, it
148
+ goes to backups/ and shared/'s is kept (a difference is shown);
149
+ - a link pointing anywhere else (absolute links included): the link goes to backups/.
150
+ Raises OSError when the hub cannot be changed; nothing is lost when it does."""
151
+ shared, acct = shared_dir(hub), account_dir(hub, account_id)
152
+ notes, linked, aside = [], [], None
153
+
154
+ def put_aside(p: Path) -> Path:
155
+ nonlocal aside
156
+ aside = aside or backup_dir(hub, account_id)
157
+ aside.mkdir(parents=True, exist_ok=True)
158
+ dest = store.free_name(aside / p.name)
159
+ os.rename(p, dest)
160
+ return dest
161
+
162
+ with lock(hub):
163
+ acct.mkdir(parents=True, exist_ok=True)
164
+ for name, is_dir in _items(prov):
165
+ if is_dir:
166
+ (shared / name).mkdir(parents=True, exist_ok=True)
167
+ for name, is_dir in _items(prov):
168
+ link, want, ours = acct / name, f"../../shared/{name}", shared / name
169
+ what = f"{account_id}: {name}{'/' if is_dir else ''}"
170
+ if link.is_symlink():
171
+ if os.readlink(link) == want:
172
+ continue
173
+ target = os.readlink(link)
174
+ notes.append(f"{what} pointed to {target}; that link is now in "
175
+ f"{put_aside(link)}")
176
+ elif not os.path.lexists(link):
177
+ linked.append(name)
178
+ elif is_dir != link.is_dir():
179
+ notes.append(f"{what} was a {'file' if is_dir else 'folder'}; moved to "
180
+ f"{put_aside(link)}")
181
+ elif is_dir:
182
+ n = _merge_tree(link, ours, account_id, move=True)
183
+ notes.append(f"{what} was a real folder: {n} file{'s' * (n != 1)} merged into "
184
+ f"the shared one; the rest is in {put_aside(link)}")
185
+ elif name.endswith(".jsonl"):
186
+ n = _append_missing(link, ours)
187
+ notes.append(f"{what} was a real file: {n} line{'s' * (n != 1)} added to the "
188
+ f"shared one; the file is in {put_aside(link)}")
189
+ elif not os.path.lexists(ours):
190
+ os.rename(link, ours)
191
+ notes.append(f"{what} was a real file and the hub had none: it is now the "
192
+ "shared one")
193
+ elif _same(link, ours):
194
+ notes.append(f"{what} was a real copy of the shared one; moved to "
195
+ f"{put_aside(link)}")
196
+ else:
197
+ shown = diff(prov, name, ours.read_bytes(), link.read_bytes(),
198
+ f"{account_id}'s {name} (set aside)")
199
+ notes.append(f"{what} differed from the shared one, which is kept; this "
200
+ f"account's copy is in {put_aside(link)}:\n{shown}".rstrip("\n"))
201
+ os.symlink(want, link)
202
+ if linked:
203
+ notes.insert(0, f"{account_id}: linked {', '.join(linked)}")
204
+ return notes
205
+
206
+
207
+ def seed(hub: Path, source: Path, account_id: str, prov,
208
+ prepare: dict[str, object] | None = None) -> list[str]:
209
+ """Copy the shared items of the user's folder `source` into shared/, never writing `source`.
210
+ Folders merge as in `check` (a clash keeps both); `.jsonl` files add the lines shared/ lacks;
211
+ another file is copied when shared/ has none (`prepare[name]`, when given, turns its text into
212
+ what is stored and raises ValueError for one it cannot use; a shared file equal to what it
213
+ makes of an empty text holds nothing of the user's and counts as none), and otherwise the
214
+ first seed wins and a difference is shown, not applied. Returns one line per item."""
215
+ shared, notes, prepare = shared_dir(hub), [], prepare or {}
216
+ skip = {i.rstrip("/") for i in prov.not_copied}
217
+ with lock(hub):
218
+ for name, is_dir in _items(prov):
219
+ src, ours = source / name, shared / name
220
+ if name in skip or not src.exists():
221
+ continue
222
+ if is_dir != src.is_dir():
223
+ notes.append(f"{name}: not a {'folder' if is_dir else 'file'} in {source}; "
224
+ "not copied")
225
+ elif is_dir:
226
+ if n := _merge_tree(src, ours, account_id, move=False):
227
+ notes.append(f"{name}/: copied {n} file{'s' * (n != 1)}")
228
+ elif name.endswith(".jsonl"):
229
+ if n := _append_missing(src, ours):
230
+ notes.append(f"{name}: added {n} line{'s' * (n != 1)}")
231
+ else:
232
+ data = src.read_bytes()
233
+ if name in prepare:
234
+ try:
235
+ data = prepare[name](data.decode("utf-8")).encode("utf-8")
236
+ except (UnicodeDecodeError, ValueError) as e:
237
+ notes.append(f"{name}: cannot be read in {source} ({e}); not copied")
238
+ continue
239
+ if not ours.exists():
240
+ _write_bytes(ours, data, src)
241
+ notes.append(f"{name}: copied")
242
+ elif name in prepare and ours.read_bytes() == prepare[name]("").encode("utf-8"):
243
+ store.write_with_backup(ours, data.decode("utf-8"),
244
+ backup_dir(hub, f"seed-{account_id}"))
245
+ notes.append(f"{name}: copied (the hub's held only what fairshare adds)")
246
+ elif ours.read_bytes() != data:
247
+ shown = diff(prov, name, ours.read_bytes(), data, f"{source}/{name}")
248
+ keep = ", keeping fairshare's own entries" if name in prepare else ""
249
+ notes.append(f"{name}: differs from the hub's, which is kept (the first "
250
+ f"folder copied wins); not applied:\n{shown}".rstrip("\n")
251
+ + f"\nto adopt {source}/{name} instead, edit {ours}{keep}")
252
+ return notes
253
+
254
+
255
+ def edit_shared(hub: Path, path: Path, change, label: str) -> str | None:
256
+ """Apply `change` (current text or None -> new text or None for no change; may raise
257
+ ValueError) to the shared file `path`, under the hub's lock: read, change, back up into
258
+ backups/, write atomically, read back. Returns what happened, or None when nothing changed.
259
+ A file that cannot be read or decoded is refused, never taken for absent."""
260
+ with lock(hub):
261
+ try:
262
+ text = path.read_text(encoding="utf-8") if path.exists() else None
263
+ except (OSError, UnicodeDecodeError) as e:
264
+ return f"{path} cannot be read ({e}); left as it is"
265
+ try:
266
+ new = change(text)
267
+ except ValueError as e:
268
+ return f"{path}: {e}; left as it is"
269
+ if new is None:
270
+ return None
271
+ backup = store.write_with_backup(path, new, backup_dir(hub, label))
272
+ return f"updated {path}" + (f" (backup: {backup})" if backup else "")
fairshare/model.py ADDED
@@ -0,0 +1,411 @@
1
+ """Provider-neutral data model. Nothing here knows about any one provider."""
2
+ from __future__ import annotations
3
+
4
+ import json
5
+ import math
6
+ import re
7
+ import shlex
8
+ import tomllib
9
+ from dataclasses import dataclass, field
10
+ from importlib import resources
11
+ from pathlib import Path
12
+
13
+ from . import browser
14
+
15
+
16
+ @dataclass(frozen=True)
17
+ class Window:
18
+ """One usage window as the provider reports it."""
19
+ used_pct: float # 0-100
20
+ resets_at: float # unix seconds
21
+
22
+
23
+ @dataclass(frozen=True)
24
+ class Plan:
25
+ name: str
26
+ provider: str
27
+ capacity: float # relative budget size; Pro = 1.0
28
+ long_name: str # provider's name for the long window
29
+ long_hours: float # its length: the fallback for an unknown reset
30
+ short_name: str | None = None # provider's name for the short window; None: the plan has none
31
+ short_hours: float | None = None # its length, when the plan file gives it
32
+
33
+
34
+ @dataclass(frozen=True)
35
+ class Account:
36
+ id: str
37
+ provider: str
38
+ plan: Plan | None # None: the configured plan has no plan file (see plan_error)
39
+ config_dir: Path
40
+ status_args: tuple[str, ...] | None = None # overrides the provider's sign-in check command
41
+ usage_args: tuple[str, ...] | None = None # overrides its usage probe; () turns it off
42
+ capacity: float | None = None # the account's own override; it survives plan detection
43
+ plan_error: str | None = None # why `plan` is None: the account is left out of ranking
44
+ browser: str | None = None # how its sign-in link opens (`browser.parse`); None: default
45
+
46
+
47
+ @dataclass(frozen=True)
48
+ class AccountStatus:
49
+ """What the provider says about one account's sign-in. Held in memory only."""
50
+ logged_in: bool
51
+ usable: bool # a subscription login (the provider's own kind), not an API key
52
+ identity: str | None = None # opaque: equal identities share one quota
53
+ plan: str | None = None # a fairshare plan name, None when the provider's maps to none
54
+ expires_at: float | None = None # when the sign-in ends (unix seconds), when the provider says
55
+
56
+
57
+ # Why a usage probe read nothing: short and value-free. A provider may add a detail after
58
+ # USAGE_NO_ANSWER only (`no answer: timed out`); the CLI tells USAGE_MODEL_TURN apart (it spends
59
+ # usage, so it is said loudly).
60
+ USAGE_NO_ANSWER = "no answer"
61
+ USAGE_SIGNED_OUT = "not signed in"
62
+ USAGE_NOT_UNDERSTOOD = "not understood"
63
+ USAGE_MODEL_TURN = "ran as a model turn"
64
+
65
+ MODEL_WINDOW_SEP = ":"
66
+
67
+
68
+ def model_window(long_name: str, model: str) -> str:
69
+ """The snapshot key of a per-model week (`seven_day:Fable`): kept beside the plan's windows,
70
+ never read by the policy."""
71
+ return f"{long_name}{MODEL_WINDOW_SEP}{model}"
72
+
73
+
74
+ def window_model(key: str) -> str | None:
75
+ """The model a snapshot key names a week for, else None (a plan window)."""
76
+ return key.partition(MODEL_WINDOW_SEP)[2] or None
77
+
78
+
79
+ @dataclass(frozen=True)
80
+ class Candidate:
81
+ """An account found on disk, before the user confirms it."""
82
+ id: str
83
+ provider: str
84
+ config_dir: Path
85
+ found: str # where it was found, shown to the user
86
+
87
+
88
+ @dataclass(frozen=True)
89
+ class Capture:
90
+ """A usage hook the provider calls, as found in its settings: which fairshare command it
91
+ runs (`runner`, the argv before `capture`) and the user's own command it wraps, if any."""
92
+ runner: tuple[str, ...]
93
+ then: str | None
94
+
95
+
96
+ EFFORT_NONE = "none" # the model takes no effort level: no effort argument is passed
97
+
98
+
99
+ @dataclass(frozen=True)
100
+ class SessionSeen:
101
+ """A running session as the provider describes it to a usage hook or a hook: its id, and its
102
+ folder and transcript when given. The usage hook's payload also names the model (and its
103
+ effort level, EFFORT_NONE when the model takes none); None: not said, keep what is known."""
104
+ id: str
105
+ cwd: str | None = None
106
+ transcript: str | None = None
107
+ model: str | None = None # the provider's model id
108
+ model_name: str | None = None # its display name
109
+ effort: str | None = None
110
+ cost: float | None = None # the session's running cost so far, in the payload's unit
111
+
112
+
113
+ @dataclass(frozen=True)
114
+ class SessionRecord:
115
+ """What fairshare keeps of one session (`store.note_session`)."""
116
+ id: str
117
+ account: str
118
+ cwd: str | None
119
+ transcript: str | None
120
+ seen: float # when a usage hook or a hook last saw it
121
+ stranded_at: float | None = None # when its account's limit stopped it, if it did
122
+ role: str | None = None # ROLE_WORKER for a worker; None: a main session
123
+ parent: str | None = None # a worker's main session (its id)
124
+ checkpoint_requested: float | None = None # when its main session asked for a checkpoint
125
+ request_said: float | None = None # the request a hook last passed on (its time)
126
+ warned: dict = field(default_factory=dict) # plan window -> [its reset, level warned]
127
+ reported: dict = field(default_factory=dict) # what `watch` already said: key -> value
128
+ model: str | None = None # the latest model id a usage hook saw
129
+ model_name: str | None = None # its display name
130
+ effort: str | None = None # the latest effort level (EFFORT_NONE: the model takes none)
131
+ waiting_until: float | None = None # stranded, left for the provider's own resume at this reset
132
+ costs: list = field(default_factory=list) # the running cost seen: series (a new one each
133
+ # time it fell) of [time, cost], see store.add_cost
134
+ continues: str | None = None # the session this one continues under a new id
135
+ moved_to: str | None = None # the session that continues this one (store.link_session)
136
+ drawn: dict = field(default_factory=dict) # the windows its usage hook last drew:
137
+ # {account: {key: [used_pct, resets_at]}}
138
+
139
+
140
+ ROLE_WORKER = "worker"
141
+
142
+
143
+ @dataclass(frozen=True)
144
+ class Worker:
145
+ """A background session a main session started (`fairshare worker`). Its session id is
146
+ known once joined: the provider lists sessions by name."""
147
+ name: str
148
+ parent: str # the main session's id
149
+ account: str
150
+ cwd: str
151
+ started: float
152
+ session: str | None = None
153
+ model: str | None = None # what the main session chose for it
154
+ effort: str | None = None
155
+ cost: float | None = None # its measured cost when it ended or went still (unread yet)
156
+ duration: float | None = None # seconds from its start to its last cost movement
157
+
158
+
159
+ @dataclass(frozen=True)
160
+ class Request:
161
+ """What a command asks the launcher to do with its child's session (`kind`), with the
162
+ user's flags: a model, an effort, an account. `manual`: asked by the user (no check that the
163
+ account is out); `pid`: the session's own process, when known."""
164
+ session: str
165
+ manual: bool
166
+ pid: int | None = None
167
+ kind: str = "pickup"
168
+ model: str | None = None
169
+ effort: str | None = None
170
+ account: str | None = None
171
+
172
+
173
+ @dataclass(frozen=True)
174
+ class LiveSession:
175
+ """A running session as the provider lists it."""
176
+ id: str
177
+ name: str | None
178
+ busy: bool | None # None: the provider did not say
179
+
180
+
181
+ NOTE_THINKING, NOTE_WRITING = "thinking", "writing"
182
+
183
+
184
+ @dataclass(frozen=True)
185
+ class NoteEvent:
186
+ """One line of the handoff note turn's output, as the provider reads it: the model is
187
+ thinking (NOTE_THINKING) or writing its answer (NOTE_WRITING, with the text that arrived)."""
188
+ kind: str
189
+ text: str = ""
190
+
191
+
192
+ @dataclass(frozen=True)
193
+ class Snapshot:
194
+ captured_at: float
195
+ windows: dict[str, Window] = field(default_factory=dict)
196
+
197
+
198
+ @dataclass(frozen=True)
199
+ class Tuning:
200
+ short_hot_pct: float = 85.0 # a short window this full counts as "hot"
201
+ long_exhausted_pct: float = 98.0 # a long window this full cannot take work
202
+ grace_hours: float = 1.0 # a hot account resetting this soon is still usable
203
+ min_hours: float = 1.0 # floor on time-to-reset, so a near reset stays finite
204
+ refresh_minutes: float = 5.0 # usage this old is asked for again (the usage probe)
205
+ launch_pause: float = 3.0 # seconds a launch with a close choice waits; 0: never
206
+ resume_wait_minutes: float = 30.0 # a limit resetting this soon is waited for, not picked up
207
+
208
+
209
+ def _plan_data(name: str) -> dict:
210
+ return tomllib.loads((resources.files("fairshare.plans") / f"{name}.toml").read_text())
211
+
212
+
213
+ def plan_for(provider: str, native: str | None) -> str | None:
214
+ """The plan whose `names` list the provider's own name for it, else None."""
215
+ for name in plan_names():
216
+ d = _plan_data(name)
217
+ if d["provider"] == provider and native in d.get("names", []):
218
+ return d["name"]
219
+ return None
220
+
221
+
222
+ def window_names(provider: str) -> set[str]:
223
+ """Every window name the plan files give for `provider`: what its usage payload may carry."""
224
+ return {w["name"] for n in plan_names() if (d := _plan_data(n))["provider"] == provider
225
+ for w in d["windows"].values()}
226
+
227
+
228
+ def load_plan(name: str, capacity: float | None = None) -> Plan:
229
+ d = _plan_data(name)
230
+ w = d["windows"]
231
+ cap = float(d["capacity"]) if capacity is None else float(capacity)
232
+ if cap <= 0:
233
+ raise ValueError(f"capacity must be positive (got {cap}) for plan {name}")
234
+ short = w.get("short", {})
235
+ return Plan(d["name"], d["provider"], cap, w["long"]["name"], float(w["long"]["hours"]),
236
+ short.get("name"), float(short["hours"]) if "hours" in short else None)
237
+
238
+
239
+ DEFAULT_HUB = "~/.local/share/fairshare/hub" # where setup proposes the hub
240
+ ACCOUNT_ID = re.compile(r"\w[\w.-]*") # an id is also a folder name in the hub
241
+
242
+
243
+ class ConfigError(ValueError):
244
+ """accounts.toml cannot be used. The message says what is wrong and where; callers add the
245
+ file's name."""
246
+
247
+
248
+ def _sole_provider() -> str | None:
249
+ """The one provider the plan files serve, or None when there are several."""
250
+ found = {_plan_data(n)["provider"] for n in plan_names()}
251
+ return found.pop() if len(found) == 1 else None
252
+
253
+
254
+ def _account(a: dict, hub: Path) -> Account:
255
+ if "config_dir" in a:
256
+ raise ValueError("config_dir is no longer used: each account lives in the hub, at "
257
+ "<hub>/accounts/<id>; move this file aside, then run `fairshare setup`")
258
+ if not isinstance(a["id"], str) or not ACCOUNT_ID.fullmatch(a["id"]):
259
+ raise ValueError(f"id {a['id']!r}: use letters, digits, '.', '-' or '_'")
260
+ capacity = None if a.get("capacity") is None else float(a["capacity"])
261
+ try:
262
+ plan, error = load_plan(a["plan"], capacity), None
263
+ except FileNotFoundError: # a renamed or removed plan file must not take the rest down
264
+ plan, error = None, f"plan {a['plan']} not found; known: {', '.join(plan_names())}"
265
+ provider = a.get("provider") or (plan.provider if plan else _sole_provider())
266
+ if not provider:
267
+ raise ValueError(f"{error}, and no provider is named")
268
+ args, usage = _args(a, "status_args"), _args(a, "usage_args")
269
+ if (spec := a.get("browser")) is not None:
270
+ browser.parse(spec) # raises ValueError saying what is accepted
271
+ return Account(a["id"], provider, plan, hub / "accounts" / a["id"], args or None, usage,
272
+ capacity, error, spec)
273
+
274
+
275
+ def _args(a: dict, key: str) -> tuple[str, ...] | None:
276
+ """An account's command override `key`: a string (split as a shell would) or a list of
277
+ strings; None when absent."""
278
+ v = a.get(key)
279
+ if v is None:
280
+ return None
281
+ if isinstance(v, str):
282
+ return tuple(shlex.split(v))
283
+ if isinstance(v, list) and all(isinstance(x, str) for x in v):
284
+ return tuple(v)
285
+ raise ValueError(f"{key} of {a['id']} must be a string or a list of strings")
286
+
287
+
288
+ def load_accounts(path: Path) -> tuple[list[Account], Tuning, Path]:
289
+ """The accounts, the tuning and the hub folder. Raises ConfigError, never anything else, for
290
+ a file that cannot be used. An account whose plan has no plan file loads with `plan` None and
291
+ `plan_error` set."""
292
+ try:
293
+ d = tomllib.loads(path.read_text())
294
+ except tomllib.TOMLDecodeError as e:
295
+ raise ConfigError(str(e)) from None
296
+ except (OSError, UnicodeDecodeError):
297
+ raise ConfigError("cannot be read as text") from None
298
+ if not isinstance(d.get("account", []), list):
299
+ raise ConfigError("account must be a list of [[account]] tables")
300
+ if not isinstance(d.get("hub", DEFAULT_HUB), str):
301
+ raise ConfigError("hub must be a folder path in quotes")
302
+ hub = Path(d.get("hub", DEFAULT_HUB)).expanduser()
303
+ accounts = []
304
+ for i, a in enumerate(d.get("account", []), 1):
305
+ try:
306
+ accounts.append(_account(a, hub))
307
+ except KeyError as e:
308
+ raise ConfigError(f"account {i}: missing {e}") from None
309
+ except (TypeError, ValueError, AttributeError) as e:
310
+ raise ConfigError(f"account {i}: {e}") from None
311
+ if [x.id for x in accounts].count(accounts[-1].id) > 1:
312
+ raise ConfigError(f"account {i}: id {accounts[-1].id!r} is used twice")
313
+ policy, valid = d.get("policy", {}), ", ".join(Tuning.__dataclass_fields__)
314
+ if not isinstance(policy, dict):
315
+ raise ConfigError("[policy] must be a table")
316
+ for k, v in policy.items():
317
+ if k not in Tuning.__dataclass_fields__:
318
+ raise ConfigError(f"[policy] unknown key {k!r}; valid keys: {valid}")
319
+ if isinstance(v, bool) or not isinstance(v, (int, float)) or not math.isfinite(v):
320
+ raise ConfigError(f"[policy] {k} must be a number (not nan or inf)")
321
+ if policy.get("refresh_minutes", 1) < 1:
322
+ raise ConfigError("[policy] refresh_minutes must be at least 1")
323
+ if policy.get("launch_pause", 0) < 0:
324
+ raise ConfigError("[policy] launch_pause must be 0 (off) or more")
325
+ if policy.get("resume_wait_minutes", 0) < 0:
326
+ raise ConfigError("[policy] resume_wait_minutes must be 0 (always pick up) or more")
327
+ return accounts, Tuning(**policy), hub
328
+
329
+
330
+ def plan_names() -> list[str]:
331
+ return sorted(f.name[:-5] for f in resources.files("fairshare.plans").iterdir()
332
+ if f.name.endswith(".toml"))
333
+
334
+
335
+ # accounts.toml is edited as text: a change touches only its own lines, so the user's comments and
336
+ # layout survive, and every result is parsed again before it is returned.
337
+
338
+ _TABLE = re.compile(r"^\s*\[")
339
+ _HUB_LINE = re.compile(r"^\s*hub\s*=")
340
+ _ACCOUNT_TABLE = re.compile(r"^\s*\[\[\s*account\s*\]\]")
341
+
342
+
343
+ def account_table(entry: dict) -> str:
344
+ """One [[account]] table. Refuses what would not load."""
345
+ if not ACCOUNT_ID.fullmatch(entry["id"]):
346
+ raise ValueError(f"account id {entry['id']!r}: use letters, digits, '.', '-' or '_'")
347
+ if entry["plan"] not in plan_names():
348
+ raise ValueError(f"unknown plan {entry['plan']!r} (known: {', '.join(plan_names())})")
349
+ load_plan(entry["plan"], entry.get("capacity"))
350
+ return "\n".join(["[[account]]", *(f"{k} = {_toml(v)}" for k, v in entry.items())]) + "\n"
351
+
352
+
353
+ def with_hub(text: str, hub: str) -> str:
354
+ """`text` whose top-level `hub` key is `hub`: its one line replaced, or added at the top."""
355
+ old = tomllib.loads(text)
356
+ if old.get("hub") == hub:
357
+ return text
358
+ new = f"hub = {_toml(hub)}\n" + ("\n" + text if text.strip() else "")
359
+ if "hub" in old:
360
+ lines = text.splitlines(keepends=True)
361
+ at = next((i for i, line in enumerate(lines) if _HUB_LINE.match(line)
362
+ and not any(_TABLE.match(x) for x in lines[:i])), None)
363
+ if at is None:
364
+ raise ValueError("could not find the hub line in accounts.toml")
365
+ new = "".join(lines[:at] + [f"hub = {_toml(hub)}\n"] + lines[at + 1:])
366
+ if tomllib.loads(new) != {**old, "hub": hub}:
367
+ raise ValueError("could not set the hub in accounts.toml")
368
+ return new
369
+
370
+
371
+ def with_account(text: str, entry: dict) -> str:
372
+ """`text` with one more [[account]] table at its end."""
373
+ old = tomllib.loads(text).get("account", [])
374
+ if any(a.get("id") == entry["id"] for a in old):
375
+ raise ValueError(f"account id {entry['id']!r} is already configured")
376
+ body = text if not text or text.endswith("\n") else text + "\n"
377
+ new = body + ("\n" if body.strip() else "") + account_table(entry)
378
+ if tomllib.loads(new).get("account", []) != [*old, entry]:
379
+ raise ValueError("could not add the account to accounts.toml")
380
+ return new
381
+
382
+
383
+ def without_account(text: str, account_id: str) -> str:
384
+ """`text` without the [[account]] table whose id is `account_id`: its lines, from its header
385
+ to the next table, are removed and nothing else."""
386
+ lines = text.splitlines(keepends=True)
387
+ starts = [i for i, line in enumerate(lines) if _TABLE.match(line)] + [len(lines)]
388
+ for i, end in zip(starts, starts[1:]):
389
+ if _ACCOUNT_TABLE.match(lines[i]):
390
+ try:
391
+ found = tomllib.loads("".join(lines[i:end]))["account"][0].get("id")
392
+ except (tomllib.TOMLDecodeError, KeyError, IndexError):
393
+ continue
394
+ if found == account_id:
395
+ new = "".join(lines[:i] + lines[end:])
396
+ old = tomllib.loads(text).get("account", [])
397
+ if tomllib.loads(new).get("account", []) != [a for a in old
398
+ if a.get("id") != account_id]:
399
+ raise ValueError("could not remove the account from accounts.toml")
400
+ return new
401
+ raise ValueError(f"no account {account_id!r} in accounts.toml")
402
+
403
+
404
+ def _toml(v) -> str:
405
+ if isinstance(v, bool):
406
+ return str(v).lower()
407
+ if isinstance(v, (int, float)):
408
+ return repr(v)
409
+ if isinstance(v, str):
410
+ return json.dumps(v, ensure_ascii=False)
411
+ raise ValueError(f"cannot write {v!r} to accounts.toml")
File without changes