1panel-toolkit 0.3.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 (47) hide show
  1. 1panel_toolkit-0.3.0.dist-info/METADATA +407 -0
  2. 1panel_toolkit-0.3.0.dist-info/RECORD +47 -0
  3. 1panel_toolkit-0.3.0.dist-info/WHEEL +4 -0
  4. 1panel_toolkit-0.3.0.dist-info/entry_points.txt +2 -0
  5. 1panel_toolkit-0.3.0.dist-info/licenses/LICENSE +21 -0
  6. p1toolkit/__init__.py +3 -0
  7. p1toolkit/checks/__init__.py +21 -0
  8. p1toolkit/checks/compose.py +188 -0
  9. p1toolkit/checks/forms.py +129 -0
  10. p1toolkit/checks/hygiene.py +73 -0
  11. p1toolkit/checks/i18n.py +140 -0
  12. p1toolkit/checks/lessons.py +111 -0
  13. p1toolkit/checks/structure.py +140 -0
  14. p1toolkit/checks/substance.py +55 -0
  15. p1toolkit/cli.py +890 -0
  16. p1toolkit/config.py +114 -0
  17. p1toolkit/dependencies.py +218 -0
  18. p1toolkit/deploy.py +302 -0
  19. p1toolkit/depth.py +414 -0
  20. p1toolkit/errors.py +18 -0
  21. p1toolkit/evidence.py +523 -0
  22. p1toolkit/fix.py +394 -0
  23. p1toolkit/gen.py +728 -0
  24. p1toolkit/lifecycle.py +143 -0
  25. p1toolkit/loader.py +110 -0
  26. p1toolkit/logo.py +174 -0
  27. p1toolkit/model.py +71 -0
  28. p1toolkit/net.py +81 -0
  29. p1toolkit/panel.py +154 -0
  30. p1toolkit/patterns/__init__.py +250 -0
  31. p1toolkit/patterns/catalog.py +271 -0
  32. p1toolkit/patterns/data/patterns.json +724 -0
  33. p1toolkit/patterns/extract.py +402 -0
  34. p1toolkit/remote.py +554 -0
  35. p1toolkit/report.py +96 -0
  36. p1toolkit/resolve/__init__.py +554 -0
  37. p1toolkit/resolve/analyze.py +329 -0
  38. p1toolkit/resolve/sources.py +306 -0
  39. p1toolkit/rules/__init__.py +99 -0
  40. p1toolkit/rules/data/decisions.yaml +132 -0
  41. p1toolkit/rules/data/dependencies.yaml +113 -0
  42. p1toolkit/rules/data/envkeys.yaml +19 -0
  43. p1toolkit/rules/data/form-design.yaml +59 -0
  44. p1toolkit/rules/data/i18n.yaml +354 -0
  45. p1toolkit/rules/data/lessons.yaml +84 -0
  46. p1toolkit/rules/data/store.yaml +171 -0
  47. p1toolkit/selftest.py +211 -0
p1toolkit/depth.py ADDED
@@ -0,0 +1,414 @@
1
+ """How much of a package is app-specific, and how much is template.
2
+
3
+ A generator that only fills a template produces packages that look alike, and
4
+ the parts it never thinks about are exactly the parts that break at runtime:
5
+ the container-side port, the mount target inside the image, the application's
6
+ own variable names, the extra runtime knobs upstream asks for.
7
+
8
+ This module measures which decisions actually vary across the official store,
9
+ then uses that to check whether a given package is shallow (a reskinned
10
+ template) or genuinely adapted.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import json
16
+ import re
17
+ from collections import Counter
18
+ from dataclasses import asdict, dataclass, field
19
+ from pathlib import Path
20
+ from typing import Any, Iterable
21
+
22
+ from .loader import find_version_dirs, load_version, LoadError, load_yaml
23
+
24
+ ENV_REF = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)([^}]*)\}")
25
+
26
+ # Keys every package needs; anything beyond this set is deliberate extra work.
27
+ COMMON_SERVICE_KEYS = {
28
+ "image",
29
+ "container_name",
30
+ "restart",
31
+ "networks",
32
+ "ports",
33
+ "volumes",
34
+ "environment",
35
+ "labels",
36
+ "depends_on",
37
+ "healthcheck",
38
+ "command",
39
+ }
40
+
41
+ # Runtime knobs that mean the packager actually read the upstream docs.
42
+ HIGH_SIGNAL_SERVICE_KEYS = {
43
+ "privileged",
44
+ "cap_add",
45
+ "devices",
46
+ "sysctls",
47
+ "ulimits",
48
+ "shm_size",
49
+ "user",
50
+ "group_add",
51
+ "pid",
52
+ "ipc",
53
+ "tmpfs",
54
+ "read_only",
55
+ "security_opt",
56
+ "network_mode",
57
+ "extra_hosts",
58
+ "dns",
59
+ "logging",
60
+ "deploy",
61
+ "entrypoint",
62
+ "stop_grace_period",
63
+ "stop_signal",
64
+ "hostname",
65
+ }
66
+
67
+
68
+ @dataclass
69
+ class Profile:
70
+ """The decisions baked into one app version."""
71
+
72
+ app: str
73
+ version: str
74
+ root: str = ""
75
+ images: list[str] = field(default_factory=list)
76
+ registries: list[str] = field(default_factory=list)
77
+ image_tags: list[str] = field(default_factory=list)
78
+ services: int = 0
79
+ port_pairs: list[str] = field(default_factory=list)
80
+ mount_targets: list[str] = field(default_factory=list)
81
+ mount_hosts: list[str] = field(default_factory=list)
82
+ app_env_keys: list[str] = field(default_factory=list)
83
+ form_env_keys: list[str] = field(default_factory=list)
84
+ field_types: list[str] = field(default_factory=list)
85
+ field_rules: list[str] = field(default_factory=list)
86
+ service_extra_keys: list[str] = field(default_factory=list)
87
+ high_signal_keys: list[str] = field(default_factory=list)
88
+ restart: str = ""
89
+ has_healthcheck: bool = False
90
+ scripts: list[str] = field(default_factory=list)
91
+ readme_sections: list[str] = field(default_factory=list)
92
+ env_sample_keys: int = 0
93
+
94
+ def features(self) -> set[str]:
95
+ """The app-specific fingerprint used for near-duplicate detection."""
96
+ out = {f"mount:{m}" for m in self.mount_targets}
97
+ out |= {f"port:{p}" for p in self.port_pairs}
98
+ out |= {f"env:{e}" for e in self.app_env_keys}
99
+ out |= {f"image:{i}" for i in self.images}
100
+ out |= {f"extra:{k}" for k in self.high_signal_keys}
101
+ return out
102
+
103
+
104
+ def _container_port(entry: str) -> str:
105
+ text = str(entry).split("/")[0]
106
+ if ":" in text:
107
+ return text.rsplit(":", 1)[1]
108
+ return text
109
+
110
+
111
+ def _split_volume(entry: str) -> tuple[str, str] | None:
112
+ parts = str(entry).split(":")
113
+ if len(parts) < 2:
114
+ return None
115
+ return parts[0].strip(), parts[1].strip()
116
+
117
+
118
+ def _image_parts(image: str | None) -> tuple[str, str, str]:
119
+ if not image:
120
+ return "", "", ""
121
+ text = str(image).strip('"').strip("'")
122
+ if "@" in text:
123
+ text = text.split("@", 1)[0]
124
+ tag = ""
125
+ name = text
126
+ if ":" in text.rsplit("/", 1)[-1]:
127
+ name, tag = text.rsplit(":", 1)
128
+ segments = name.split("/")
129
+ registry = segments[0] if len(segments) > 1 and ("." in segments[0] or ":" in segments[0]) else "docker.io"
130
+ return name, registry, tag
131
+
132
+
133
+ def _env_keys(service: dict[str, Any]) -> list[str]:
134
+ env = service.get("environment")
135
+ keys: list[str] = []
136
+ if isinstance(env, dict):
137
+ keys = [str(k) for k in env]
138
+ elif isinstance(env, list):
139
+ for item in env:
140
+ if isinstance(item, str) and "=" in item:
141
+ keys.append(item.split("=", 1)[0].strip())
142
+ elif isinstance(item, str):
143
+ keys.append(item.strip())
144
+ return [
145
+ k
146
+ for k in keys
147
+ if k and not k.startswith(("PANEL_", "TZ")) and "${PANEL_" not in k
148
+ ]
149
+
150
+
151
+ def profile_app(root: Path, version_name: str | None = None) -> Profile | None:
152
+ data_path = root / "data.yml"
153
+ if not data_path.exists():
154
+ return None
155
+ try:
156
+ app_data = load_yaml(data_path)
157
+ except LoadError:
158
+ return None
159
+ key = str((app_data.get("additionalProperties") or {}).get("key") or root.name)
160
+
161
+ directories = find_version_dirs(root)
162
+ if version_name:
163
+ directories = [d for d in directories if d.name == version_name]
164
+ if not directories:
165
+ return None
166
+ try:
167
+ version = load_version(directories[0])
168
+ except LoadError:
169
+ return None
170
+
171
+ profile = Profile(app=key, version=version.name, root=str(root))
172
+ profile.form_env_keys = sorted(
173
+ {
174
+ str(f["envKey"])
175
+ for f in version.form_fields
176
+ if f.get("envKey")
177
+ }
178
+ | {
179
+ str(f["child"]["envKey"])
180
+ for f in version.form_fields
181
+ if isinstance(f.get("child"), dict) and f["child"].get("envKey")
182
+ }
183
+ )
184
+ profile.field_types = sorted({str(f.get("type")) for f in version.form_fields if f.get("type")})
185
+ profile.field_rules = sorted({str(f.get("rule")) for f in version.form_fields if f.get("rule")})
186
+
187
+ services = {
188
+ name: svc
189
+ for name, svc in (version.compose.get("services") or {}).items()
190
+ if isinstance(svc, dict)
191
+ }
192
+ profile.services = len(services)
193
+ restarts: Counter[str] = Counter()
194
+ for service in services.values():
195
+ name, registry, tag = _image_parts(service.get("image"))
196
+ if name:
197
+ profile.images.append(name)
198
+ profile.registries.append(registry)
199
+ profile.image_tags.append(tag)
200
+ for mapping in service.get("ports") or []:
201
+ profile.port_pairs.append(_container_port(str(mapping)))
202
+ for volume in service.get("volumes") or []:
203
+ split = _split_volume(str(volume))
204
+ if split and split[1]:
205
+ profile.mount_hosts.append(split[0])
206
+ profile.mount_targets.append(split[1])
207
+ profile.app_env_keys.extend(_env_keys(service))
208
+ extra = sorted(set(service) - COMMON_SERVICE_KEYS)
209
+ profile.service_extra_keys.extend(extra)
210
+ profile.high_signal_keys.extend(sorted(set(service) & HIGH_SIGNAL_SERVICE_KEYS))
211
+ if service.get("healthcheck"):
212
+ profile.has_healthcheck = True
213
+ if service.get("restart"):
214
+ restarts[str(service["restart"])] += 1
215
+
216
+ profile.restart = restarts.most_common(1)[0][0] if restarts else ""
217
+ profile.scripts = sorted(
218
+ name.split("/")[-1]
219
+ for name in version.files
220
+ if name.startswith("scripts/") and name.endswith(".sh")
221
+ )
222
+ readme = root / "README.md"
223
+ if readme.exists():
224
+ text = readme.read_text(encoding="utf-8-sig", errors="replace")
225
+ profile.readme_sections = [
226
+ line.strip("# ").strip()
227
+ for line in text.splitlines()
228
+ if line.startswith("## ")
229
+ ]
230
+ profile.env_sample_keys = sum(
231
+ 1
232
+ for line in version.env_sample.splitlines()
233
+ if "=" in line and not line.lstrip().startswith("#")
234
+ )
235
+ profile.mount_targets = sorted(set(profile.mount_targets))
236
+ profile.mount_hosts = sorted(set(profile.mount_hosts))
237
+ profile.port_pairs = sorted(set(profile.port_pairs))
238
+ profile.app_env_keys = sorted(set(profile.app_env_keys))
239
+ profile.images = sorted(set(profile.images))
240
+ profile.registries = sorted(set(profile.registries))
241
+ profile.image_tags = sorted(set(profile.image_tags))
242
+ profile.service_extra_keys = sorted(set(profile.service_extra_keys))
243
+ profile.high_signal_keys = sorted(set(profile.high_signal_keys))
244
+ return profile
245
+
246
+
247
+ def iter_app_roots(corpus: Path) -> Iterable[Path]:
248
+ if (corpus / "data.yml").exists():
249
+ yield corpus
250
+ return
251
+ for base in (corpus / "apps", corpus):
252
+ if not base.is_dir():
253
+ continue
254
+ for child in sorted(base.iterdir()):
255
+ if child.is_dir() and (child / "data.yml").exists():
256
+ yield child
257
+
258
+
259
+ def scan(corpus_dirs: list[Path], limit: int | None = None) -> list[Profile]:
260
+ out: list[Profile] = []
261
+ for corpus in corpus_dirs:
262
+ for root in iter_app_roots(corpus):
263
+ profile = profile_app(root)
264
+ if profile:
265
+ out.append(profile)
266
+ if limit and len(out) >= limit:
267
+ return out
268
+ return out
269
+
270
+
271
+ # --------------------------------------------------------------------------
272
+ # diversity: which decisions actually differ between applications
273
+ # --------------------------------------------------------------------------
274
+
275
+
276
+ def _distinct(values: Iterable[str]) -> int:
277
+ return len({v for v in values if v})
278
+
279
+
280
+ def dimension_report(
281
+ profiles: list[Profile], top: int = 6, include_values: bool = False
282
+ ) -> dict[str, Any]:
283
+ """For each dimension: how many distinct values, and the most common ones.
284
+
285
+ A dimension with one dominant value is safe to template. A dimension with
286
+ hundreds of distinct values is a decision the generator must make per app.
287
+ """
288
+ apps = max(len(profiles), 1)
289
+ dimensions: list[dict[str, Any]] = []
290
+
291
+ def add(name: str, values: list[str], advice: str) -> None:
292
+ pool = [v for v in values if v]
293
+ counter = Counter(pool)
294
+ dimensions.append(
295
+ {
296
+ "dimension": name,
297
+ "samples": len(pool),
298
+ "distinct": len(counter),
299
+ "per_app": round(len(pool) / apps, 2),
300
+ "top": counter.most_common(top),
301
+ "advice": advice,
302
+ }
303
+ )
304
+
305
+ def flat(attr: str) -> list[str]:
306
+ out: list[str] = []
307
+ for profile in profiles:
308
+ out.extend(getattr(profile, attr) or [])
309
+ return out
310
+
311
+ add("容器内端口", flat("port_pairs"), "必须来自上游 EXPOSE / 官方 compose,不能套模板")
312
+ add("容器内挂载点", flat("mount_targets"), "必须来自上游 Dockerfile VOLUME / 官方文档")
313
+ add("挂载来源路径", flat("mount_hosts"), "决定数据落在哪里,影响升级与备份")
314
+ add("应用环境变量名", flat("app_env_keys"), "上游自己的变量名,不能通用化")
315
+ add("镜像仓库", flat("registries"), "官方镜像优先;第三方需要明确接受")
316
+ add("镜像标签风格", flat("image_tags"), "固定版本还是 latest,影响可升级性")
317
+ add("表单 envKey", flat("form_env_keys"), "面板约定变量 + 应用自有变量")
318
+ add("表单字段类型", flat("field_types"), "按语义选择,不是一律 text")
319
+ add("表单校验规则", flat("field_rules"), "paramPort / paramComplexity 等")
320
+ add("服务额外字段", flat("service_extra_keys"), "upstream 要求的运行时开关")
321
+ add("高风险运行时字段", flat("high_signal_keys"), "privileged/cap_add/devices 等按证据保留")
322
+ add("重启策略", [p.restart for p in profiles], "多为 always")
323
+ add("README 章节", flat("readme_sections"), "商店风格章节")
324
+ add("脚本组合", [",".join(p.scripts) for p in profiles], "init/upgrade/uninstall 是否必要")
325
+
326
+ report = {
327
+ "apps": len(profiles),
328
+ "dimensions": sorted(dimensions, key=lambda d: -d["distinct"]),
329
+ "service_counts": Counter(p.services for p in profiles).most_common(),
330
+ "healthcheck": sum(1 for p in profiles if p.has_healthcheck),
331
+ }
332
+ if include_values:
333
+ report["values"] = [asdict(p) for p in profiles]
334
+ return report
335
+
336
+
337
+ # --------------------------------------------------------------------------
338
+ # similarity: is this package a reskinned template?
339
+ # --------------------------------------------------------------------------
340
+
341
+
342
+ def similarity(left: Profile, right: Profile) -> tuple[float, list[str]]:
343
+ """Jaccard over app-specific features, plus the shared features."""
344
+ a, b = left.features(), right.features()
345
+ if not a or not b:
346
+ return 0.0, []
347
+ shared = sorted(a & b)
348
+ union = a | b
349
+ return len(shared) / len(union), shared
350
+
351
+
352
+ def nearest(profile: Profile, corpus: list[Profile], threshold: float = 0.2, limit: int = 5):
353
+ scored = []
354
+ for other in corpus:
355
+ if other.app == profile.app:
356
+ continue
357
+ score, shared = similarity(profile, other)
358
+ if score >= threshold:
359
+ scored.append((score, other, shared))
360
+ scored.sort(key=lambda item: -item[0])
361
+ return scored[:limit]
362
+
363
+
364
+ @dataclass
365
+ class Verdict:
366
+ status: str
367
+ score: float
368
+ reasons: list[str] = field(default_factory=list)
369
+ twin: str | None = None
370
+
371
+ @property
372
+ def shallow(self) -> bool:
373
+ return self.status != "adapted"
374
+
375
+
376
+ def assess(
377
+ profile: Profile, corpus: list[Profile], twin_threshold: float = 0.5
378
+ ) -> Verdict:
379
+ """Decide whether a package looks adapted or reskinned.
380
+
381
+ The dimensions that carry all the diversity in the store (container ports,
382
+ mount targets, application variable names) are exactly the ones a template
383
+ cannot answer. A package with thin values there, or one that is nearly
384
+ identical to an unrelated app, is probably a reskin.
385
+ """
386
+ reasons: list[str] = []
387
+ if not profile.images:
388
+ reasons.append("compose 里没有可识别的镜像")
389
+ if not profile.port_pairs:
390
+ reasons.append("没有对外端口映射")
391
+ if not profile.mount_targets:
392
+ reasons.append("没有持久化挂载点(除非这个应用真的无状态)")
393
+ if not profile.app_env_keys:
394
+ reasons.append("没有任何应用自有环境变量(多数应用都有配置项)")
395
+ twin = None
396
+ score = 0.0
397
+ found = nearest(profile, corpus, threshold=twin_threshold, limit=1)
398
+ if found:
399
+ score, other, shared = found[0]
400
+ twin = other.app
401
+ reasons.append(
402
+ f"与 {other.app} 有 {score:.0%} 的应用特有特征重合"
403
+ f"({', '.join(shared[:4])})"
404
+ )
405
+
406
+ if not reasons:
407
+ return Verdict(status="adapted", score=score)
408
+ if twin:
409
+ return Verdict(status="possibly-reskinned", score=score, reasons=reasons, twin=twin)
410
+ return Verdict(status="thin", score=score, reasons=reasons)
411
+
412
+
413
+ def to_json(data: dict[str, Any]) -> str:
414
+ return json.dumps(data, ensure_ascii=False, indent=2)
p1toolkit/errors.py ADDED
@@ -0,0 +1,18 @@
1
+ """Exceptions shared by the generator and the modules it delegates to.
2
+
3
+ ``SpecError`` used to live in ``gen.py``; it moved here so ``dependencies`` and
4
+ ``lifecycle`` can refuse a bad spec without importing the generator back.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+
10
+ class SpecError(Exception):
11
+ """The spec is missing something the generator refuses to invent."""
12
+
13
+
14
+ class DependencyError(SpecError):
15
+ """The spec asks for a panel dependency the toolkit cannot wire up."""
16
+
17
+
18
+ __all__ = ["DependencyError", "SpecError"]