Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

dbbasic-object-server/object_namespace.py
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

danq9 signup: the person chooses the password and name on the confirm page 83c7aa6 2 weeks, 5 days ago History
object_namespace.py · 9.8 KB · 304 lines
1"""Object source discovery and object ID resolution.
2
3This module is intentionally small and standalone while the public package
4layout is being decided. It is the shared namespace contract for the daemon,
5future HTTP server, tests, and companion tools.
6"""
7from __future__ import annotations
8
9import os
10import re
11from dataclasses import dataclass
12from pathlib import Path
13from typing import Iterable, Literal
14
15
16DEFAULT_OBJECTS_DIR = "objects"
17OBJECTS_DIR_ENV = "DBBASIC_OBJECTS_DIR"
18OVERRIDES_DIR_ENV = "DBBASIC_OVERRIDES_DIR"
19
20_OBJECT_ID_RE = re.compile(r"^[A-Za-z0-9_]{1,64}$")
21_USER_OBJECT_RE = re.compile(r"^u_(\d+)_([A-Za-z][A-Za-z0-9_]{0,49})$")
22
23
24@dataclass(frozen=True)
25class ObjectSource:
26 """A discovered object source file."""
27
28 object_id: str
29 path: Path
30 relative_path: Path
31 kind: Literal["system", "user", "override"]
32
33
34def get_base_object_roots() -> list[Path]:
35 """Return the package/system object roots (never the override root).
36
37 This is the root packages install into and reconcile against. It is
38 identical to the pre-override-support get_object_roots() body, so
39 install/baseline/reconcile logic always operates on the pristine,
40 upgradeable copy regardless of whether overrides are enabled.
41 """
42 configured = os.environ.get(OBJECTS_DIR_ENV)
43 if configured:
44 return [Path(configured)]
45 return [Path(DEFAULT_OBJECTS_DIR)]
46
47
48def get_override_root() -> Path | None:
49 """Return the override root when DBBASIC_OVERRIDES_DIR is set, else None.
50
51 Overrides are strictly opt-in: when the env var is unset or empty, this
52 returns None and every override-aware code path behaves exactly as it
53 did before overrides existed.
54 """
55 configured = os.environ.get(OVERRIDES_DIR_ENV)
56 if configured:
57 return Path(configured)
58 return None
59
60
61def get_object_roots() -> list[Path]:
62 """Return object source roots in lookup order (override first, then base).
63
64 When DBBASIC_OVERRIDES_DIR is unset this returns exactly
65 get_base_object_roots() — a single-element list identical to the
66 pre-override behavior of this function.
67 """
68 override = get_override_root()
69 return ([override] if override is not None else []) + get_base_object_roots()
70
71
72def validate_object_id(object_id: str) -> bool:
73 """Return True when an object ID is safe to resolve."""
74 if not isinstance(object_id, str):
75 return False
76 return bool(_OBJECT_ID_RE.fullmatch(object_id))
77
78
79def parse_user_object_id(object_id: str) -> tuple[int, str] | None:
80 """Parse `u_{user_id}_{name}` object IDs."""
81 if not validate_object_id(object_id):
82 return None
83
84 match = _USER_OBJECT_RE.fullmatch(object_id)
85 if not match:
86 return None
87 return int(match.group(1)), match.group(2)
88
89
90def is_user_object_id(object_id: str) -> bool:
91 """Return True when an object ID belongs to a user namespace."""
92 return parse_user_object_id(object_id) is not None
93
94
95def override_relative_path(object_id: str) -> Path | None:
96 """Return the canonical override-root-relative path for an object ID.
97
98 Mirrors the first candidate form used by _candidate_system_paths.
99 Overrides only exist for system/package objects; user object IDs (and
100 any other invalid ID) are not supported and return None.
101 """
102 if not validate_object_id(object_id) or is_user_object_id(object_id):
103 return None
104 if "_" in object_id:
105 category, name = object_id.split("_", 1)
106 return Path(category) / f"{name}.py"
107 return Path(f"{object_id}.py")
108
109
110def override_path(object_id: str) -> Path | None:
111 """Return the absolute override path for an object ID, or None.
112
113 None is returned when overrides are not enabled (no override root
114 configured) or when the object ID is not a valid override target.
115 """
116 root = get_override_root()
117 if root is None:
118 return None
119 relative = override_relative_path(object_id)
120 if relative is None:
121 return None
122 return root / relative
123
124
125def has_override(object_id: str) -> bool:
126 """Return True when an override file exists for this object ID."""
127 path = override_path(object_id)
128 return path is not None and path.is_file()
129
130
131def resolve_object_id(object_id: str, roots: Iterable[Path] | None = None) -> Path | None:
132 """Resolve an object ID to an existing source file."""
133 if not validate_object_id(object_id):
134 return None
135
136 search_roots = list(roots) if roots is not None else get_object_roots()
137
138 parsed_user = parse_user_object_id(object_id)
139 if parsed_user:
140 user_id, name = parsed_user
141 for root in search_roots:
142 candidate = root / "users" / str(user_id) / f"{name}.py"
143 if _is_allowed_source_file(candidate, root):
144 return candidate
145 return None
146
147 for candidate in _candidate_system_paths(object_id, search_roots):
148 root = _candidate_root(candidate, search_roots)
149 if root is not None and _is_allowed_source_file(candidate, root):
150 return candidate
151
152 for source in iter_object_sources(search_roots):
153 if source.object_id == object_id:
154 return source.path
155
156 return None
157
158
159def find_trigger_file(trigger_name: str, roots: Iterable[Path] | None = None) -> Path | None:
160 """Find a known trigger object file under `objects/triggers/`."""
161 if not _is_safe_source_stem(trigger_name):
162 return None
163
164 search_roots = list(roots) if roots is not None else get_object_roots()
165 for root in search_roots:
166 candidate = root / "triggers" / f"{trigger_name}.py"
167 if _is_allowed_source_file(candidate, root):
168 return candidate
169 return None
170
171
172def object_id_from_path(path: Path | str, root: Path | str) -> str:
173 """Return the object ID represented by a source path under a root."""
174 source_path = Path(path)
175 source_root = Path(root)
176 rel = _relative_to_root(source_path, source_root)
177
178 if not _is_public_source_relative_path(rel):
179 raise ValueError(f"Not a public object source: {source_path}")
180
181 parts = rel.parts
182 if parts[0] == "users":
183 if len(parts) != 3:
184 raise ValueError(f"Invalid user object source path: {source_path}")
185 user_id = parts[1]
186 name = Path(parts[2]).stem
187 object_id = f"u_{user_id}_{name}"
188 else:
189 path_without_suffix = rel.with_suffix("")
190 object_id = "_".join(path_without_suffix.parts)
191
192 if not validate_object_id(object_id):
193 raise ValueError(f"Invalid object ID derived from path: {object_id}")
194 return object_id
195
196
197def iter_object_sources(roots: Iterable[Path] | None = None) -> list[ObjectSource]:
198 """List object source files from configured roots in deterministic order."""
199 search_roots = list(roots) if roots is not None else get_object_roots()
200 override_root = get_override_root()
201 sources: list[ObjectSource] = []
202
203 for root in search_roots:
204 if not root.exists() or not root.is_dir():
205 continue
206
207 is_override_root = override_root is not None and _same_root(root, override_root)
208
209 for path in sorted(root.rglob("*.py"), key=lambda p: p.relative_to(root).as_posix()):
210 try:
211 rel = _relative_to_root(path, root)
212 object_id = object_id_from_path(path, root)
213 except ValueError:
214 continue
215
216 kind: Literal["system", "user", "override"]
217 if rel.parts[0] == "users":
218 kind = "user"
219 elif is_override_root:
220 kind = "override"
221 else:
222 kind = "system"
223 sources.append(
224 ObjectSource(
225 object_id=object_id,
226 path=path,
227 relative_path=rel,
228 kind=kind,
229 )
230 )
231
232 return sources
233
234
235def _same_root(a: Path, b: Path) -> bool:
236 return a.resolve(strict=False) == b.resolve(strict=False)
237
238
239def _candidate_system_paths(object_id: str, roots: Iterable[Path]) -> list[Path]:
240 candidates: list[Path] = []
241 for root in roots:
242 if "_" in object_id:
243 category, name = object_id.split("_", 1)
244 candidates.append(root / category / f"{name}.py")
245 candidates.append(root / f"{object_id}.py")
246 return candidates
247
248
249def _candidate_root(candidate: Path, roots: Iterable[Path]) -> Path | None:
250 for root in roots:
251 try:
252 _relative_to_root(candidate, root)
253 return root
254 except ValueError:
255 continue
256 return None
257
258
259def _relative_to_root(path: Path, root: Path) -> Path:
260 resolved_path = path.resolve(strict=False)
261 resolved_root = root.resolve(strict=False)
262
263 try:
264 return resolved_path.relative_to(resolved_root)
265 except ValueError as exc:
266 raise ValueError(f"Path escapes object root: {path}") from exc
267
268
269def _is_allowed_source_file(path: Path, root: Path) -> bool:
270 if not path.exists() or not path.is_file():
271 return False
272 try:
273 rel = _relative_to_root(path, root)
274 except ValueError:
275 return False
276 return _is_public_source_relative_path(rel)
277
278
279def _is_public_source_relative_path(rel: Path) -> bool:
280 parts = rel.parts
281 if not parts:
282 return False
283 if rel.suffix != ".py":
284 return False
285 if rel.name == "__init__.py":
286 return False
287 if "__pycache__" in parts:
288 return False
289 if any(part.startswith(".") or part.startswith("_") for part in parts):
290 return False
291 if any(part in {"", ".", ".."} for part in parts):
292 return False
293
294 if parts[0] == "users":
295 if len(parts) != 3:
296 return False
297 return parts[1].isdigit() and _is_safe_source_stem(Path(parts[2]).stem)
298
299 return all(_is_safe_source_stem(part if i < len(parts) - 1 else Path(part).stem)
300 for i, part in enumerate(parts))
301
302
303def _is_safe_source_stem(stem: str) -> bool:
304 return bool(re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_]{0,49}", stem))