merrow 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.
Files changed (60) hide show
  1. merrow/__init__.py +1 -0
  2. merrow/apply.py +116 -0
  3. merrow/archive.py +79 -0
  4. merrow/browser.py +72 -0
  5. merrow/bundle.py +69 -0
  6. merrow/cli.py +418 -0
  7. merrow/compose.py +148 -0
  8. merrow/config.py +110 -0
  9. merrow/convert/__init__.py +11 -0
  10. merrow/convert/opc.py +42 -0
  11. merrow/convert/pdf.py +136 -0
  12. merrow/convert/pptx.py +201 -0
  13. merrow/convert/svg.py +285 -0
  14. merrow/convert/visio.py +556 -0
  15. merrow/defaults.yaml +171 -0
  16. merrow/graph.py +174 -0
  17. merrow/lint/__init__.py +1 -0
  18. merrow/lint/diagram_check.py +807 -0
  19. merrow/lint/icons.py +32 -0
  20. merrow/model.py +115 -0
  21. merrow/naming.py +79 -0
  22. merrow/npm/package-lock.json +1156 -0
  23. merrow/npm/package.json +7 -0
  24. merrow/objects.py +143 -0
  25. merrow/objects.yaml +54 -0
  26. merrow/packs/starter.LICENSE +201 -0
  27. merrow/packs/starter.json +1 -0
  28. merrow/patterns.py +119 -0
  29. merrow/patterns.yaml +32 -0
  30. merrow/post.py +115 -0
  31. merrow/proc.py +58 -0
  32. merrow/profile.py +348 -0
  33. merrow/profiles/aws-dark.tokens.json +8 -0
  34. merrow/profiles/aws.tokens.json +13 -0
  35. merrow/profiles/house-dark.tokens.json +6 -0
  36. merrow/profiles/house.tokens.json +51 -0
  37. merrow/profiles.yaml +219 -0
  38. merrow/read/__init__.py +27 -0
  39. merrow/read/dot.py +81 -0
  40. merrow/read/drawio.py +198 -0
  41. merrow/read/excalidraw.py +88 -0
  42. merrow/read/pdf.py +693 -0
  43. merrow/read/pptx.py +155 -0
  44. merrow/read/structurizr.py +78 -0
  45. merrow/read/visio.py +174 -0
  46. merrow/render.py +147 -0
  47. merrow/skill/SKILL.md +46 -0
  48. merrow/sources/__init__.py +1 -0
  49. merrow/sources/detect.py +169 -0
  50. merrow/sources/fetch.py +77 -0
  51. merrow/sources/lock.py +58 -0
  52. merrow/sources.lock.yaml +87 -0
  53. merrow/sources.yaml +432 -0
  54. merrow/spec.py +123 -0
  55. merrow/write.py +289 -0
  56. merrow-0.1.1.dist-info/METADATA +110 -0
  57. merrow-0.1.1.dist-info/RECORD +60 -0
  58. merrow-0.1.1.dist-info/WHEEL +4 -0
  59. merrow-0.1.1.dist-info/entry_points.txt +2 -0
  60. merrow-0.1.1.dist-info/licenses/LICENSE +73 -0
merrow/__init__.py ADDED
@@ -0,0 +1 @@
1
+ """merrow: diagram automation on Mermaid."""
merrow/apply.py ADDED
@@ -0,0 +1,116 @@
1
+ """Hand-written Mermaid in a profile's look: its two managed regions.
2
+
3
+ An author writes the body, naming an object as `id:::aws-msk` (the object id
4
+ with dots as hyphens). apply sets the frontmatter, expands a bare object node
5
+ into the profile's label form, and rewrites the class block between the
6
+ markers. Each `:::` stays, so re-running is a no-op and picks up object edits.
7
+ """
8
+
9
+ import re
10
+ from collections.abc import Mapping
11
+ from pathlib import Path
12
+
13
+ from merrow.graph import Node
14
+ from merrow.lint.diagram_check import diagram_type, split_front
15
+ from merrow.objects import L1Object
16
+ from merrow.profile import Profile
17
+ from merrow.render import FENCE
18
+ from merrow.write import misfits, profile_label
19
+
20
+ BEGIN = "%% merrow:begin"
21
+ END = "%% merrow:end"
22
+ _REF = re.compile(r"^(?P<id>[A-Za-z_]\w*)(?P<label>[\[(].*[\])])?:::(?P<ref>[\w-]+)$")
23
+ _SUBGRAPH = re.compile(r"^subgraph\s+([A-Za-z_]\w*)")
24
+ # Mermaid kinds that take the frontmatter alone: they can name no object.
25
+ _FRONT_ONLY = ("sequenceDiagram", "erDiagram", "classDiagram")
26
+
27
+
28
+ def _indent(line: str) -> str:
29
+ return line[: len(line) - len(line.lstrip())]
30
+
31
+
32
+ def apply(source: str, profile: Profile, by_ref: Mapping[str, L1Object]) -> str:
33
+ """Return one diagram with the profile's frontmatter and class block.
34
+
35
+ `by_ref` is `objects.by_class_name` of the object library.
36
+
37
+ Raises:
38
+ ValueError: An object styles as a class the profile doesn't define.
39
+ """
40
+ _, body = split_front(source)
41
+ flow = diagram_type(body)[0] in ("flowchart", "graph")
42
+ kept, managed = [], False
43
+ for line in body.splitlines():
44
+ if line.strip() in (BEGIN, END):
45
+ managed = line.strip() == BEGIN
46
+ elif not managed:
47
+ kept.append(line)
48
+ while kept and not kept[-1].strip():
49
+ kept.pop()
50
+
51
+ styles: dict[str, list[str]] = {}
52
+ subgraphs, out = [], []
53
+ for line in kept:
54
+ match = _REF.match(line.strip())
55
+ known = by_ref.get(match["ref"]) if match else None
56
+ if match and known is not None:
57
+ if problems := misfits(profile, known):
58
+ raise ValueError("; ".join(problems))
59
+ node = Node(match["id"], known.label, known.subtitle)
60
+ label = match["label"] or profile_label(profile, node, known.shape)
61
+ line = f"{_indent(line)}{match['id']}{label}:::{match['ref']}"
62
+ styles.setdefault(known.style, []).append(match["id"])
63
+ if found := _SUBGRAPH.match(line.strip()):
64
+ subgraphs.append(found.group(1))
65
+ out.append(line)
66
+
67
+ if flow:
68
+ indent = next((_indent(ln) for ln in out[1:] if ln.strip()), " ")
69
+ order = [ln.split()[1] for ln in profile.class_lines]
70
+ block = [
71
+ f"class {','.join(styles[name])} {name}"
72
+ for name in sorted(styles, key=order.index)
73
+ ]
74
+ block += [*profile.class_lines]
75
+ block += [f"style {name} {profile.boundary}" for name in subgraphs]
76
+ out += [f"{indent}{BEGIN}", *(indent + ln for ln in block), f"{indent}{END}"]
77
+ front = profile.fronts["flowchart" if flow else "other"]
78
+ return f"{front}\n" + "\n".join(out) + "\n"
79
+
80
+
81
+ def managed(source: str, by_ref: Mapping[str, L1Object]) -> bool:
82
+ """Return whether a diagram takes the profile.
83
+
84
+ It does when it names an object, carries the class block, or is a sequence,
85
+ ER or class diagram, which can name no object.
86
+ """
87
+ names = {m["ref"] for ln in source.splitlines() if (m := _REF.match(ln.strip()))}
88
+ front_only = diagram_type(split_front(source)[1])[0] in _FRONT_ONLY
89
+ return BEGIN in source or bool(names & set(by_ref)) or front_only
90
+
91
+
92
+ def apply_file(path: Path, profile: Profile, by_ref: Mapping[str, L1Object]) -> bool:
93
+ """Apply the profile to a `.mmd` file, or to each managed fence in Markdown.
94
+
95
+ A fence is managed once it names an object or carries the class block. A
96
+ sequence, ER or class diagram is always managed: it can name no object.
97
+ Returns whether the file changed.
98
+
99
+ Raises:
100
+ ValueError: An object styles as a class the profile doesn't define.
101
+ """
102
+ text = path.read_text(encoding="utf-8")
103
+ if path.suffix != ".md":
104
+ new = apply(text, profile, by_ref)
105
+ else:
106
+
107
+ def one(fence: re.Match[str]) -> str:
108
+ body = fence.group(1)
109
+ if not managed(body, by_ref):
110
+ return fence.group(0)
111
+ return fence.group(0).replace(body, apply(body, profile, by_ref), 1)
112
+
113
+ new = FENCE.sub(one, text)
114
+ if new != text:
115
+ path.write_text(new, encoding="utf-8", newline="\n")
116
+ return new != text
merrow/archive.py ADDED
@@ -0,0 +1,79 @@
1
+ """Read the files in a download, whatever it ships as: a directory, zip or tarball.
2
+
3
+ Every converter selects its files with a regex on the path inside the download,
4
+ so a new release that moves or renames folders is a config change, never code.
5
+ """
6
+
7
+ import re
8
+ import tarfile
9
+ import zipfile
10
+ from collections.abc import Iterator
11
+ from dataclasses import dataclass
12
+ from pathlib import Path
13
+
14
+
15
+ @dataclass(frozen=True, slots=True)
16
+ class Member:
17
+ """One file in a download.
18
+
19
+ Attributes:
20
+ path: The `/`-separated path inside the download.
21
+ data: The bytes, or None when the file is over the size cap and unread.
22
+ """
23
+
24
+ path: str
25
+ data: bytes | None
26
+
27
+
28
+ def members(
29
+ source: Path,
30
+ pattern: re.Pattern[str],
31
+ max_bytes: int,
32
+ ignore: re.Pattern[str] | None = None,
33
+ ) -> Iterator[Member]:
34
+ """Yield every file under `source` whose path matches `pattern`, sorted by path.
35
+
36
+ A plain file is one member, named by its file name.
37
+
38
+ A path matching `ignore` is left out, such as the `__MACOSX/` resource forks
39
+ a zip made on a Mac carries.
40
+
41
+ A file larger than `max_bytes` comes back with no data and is never read, so
42
+ a bad download can't fill memory.
43
+
44
+ Raises:
45
+ ValueError: `source` doesn't exist.
46
+ """
47
+ if not source.exists():
48
+ raise ValueError(f"{source} is not a file, directory, zip or tarball")
49
+ if source.is_dir():
50
+ for path in sorted(p for p in source.rglob("*") if p.is_file()):
51
+ name = path.relative_to(source).as_posix()
52
+ if _wanted(name, pattern, ignore):
53
+ small = path.stat().st_size <= max_bytes
54
+ yield Member(name, path.read_bytes() if small else None)
55
+ elif zipfile.is_zipfile(source):
56
+ with zipfile.ZipFile(source) as archive:
57
+ for info in sorted(archive.infolist(), key=lambda i: i.filename):
58
+ if not info.is_dir() and _wanted(info.filename, pattern, ignore):
59
+ small = info.file_size <= max_bytes
60
+ yield Member(info.filename, archive.read(info) if small else None)
61
+ elif tarfile.is_tarfile(source):
62
+ with tarfile.open(source) as archive:
63
+ files = sorted(
64
+ (m for m in archive.getmembers() if m.isfile()), key=lambda m: m.name
65
+ )
66
+ for info in files:
67
+ handle = archive.extractfile(info)
68
+ if handle and _wanted(info.name, pattern, ignore):
69
+ small = info.size <= max_bytes
70
+ yield Member(info.name, handle.read() if small else None)
71
+ elif _wanted(source.name, pattern, ignore):
72
+ small = source.stat().st_size <= max_bytes
73
+ yield Member(source.name, source.read_bytes() if small else None)
74
+
75
+
76
+ def _wanted(
77
+ path: str, pattern: re.Pattern[str], ignore: re.Pattern[str] | None
78
+ ) -> bool:
79
+ return bool(pattern.search(path)) and not (ignore and ignore.search(path))
merrow/browser.py ADDED
@@ -0,0 +1,72 @@
1
+ """The browser every laid-out page runs in: render, post-render and lint."""
2
+
3
+ import functools
4
+ import subprocess
5
+ import sys
6
+ from typing import Any
7
+
8
+ from merrow import config, proc
9
+
10
+
11
+ class BrowserError(RuntimeError):
12
+ """No browser could be installed or launched."""
13
+
14
+
15
+ @functools.cache
16
+ def _install(name: str, timeout: float) -> str:
17
+ """Return "" once playwright has `name`, else its error. A no-op when installed."""
18
+ result = proc.run(
19
+ [sys.executable, "-m", "playwright", "install", name], timeout=timeout
20
+ )
21
+ return "" if result.returncode == 0 else proc.tail(result)
22
+
23
+
24
+ def _system_libraries(name: str, timeout: float) -> str:
25
+ """Return "" once apt has the libraries `name` needs, else why not.
26
+
27
+ Runs on the terminal, so the sudo playwright starts can ask for a password.
28
+ """
29
+ argv = [sys.executable, "-m", "playwright", "install-deps", name]
30
+ try:
31
+ code = subprocess.run(argv, timeout=timeout, check=False).returncode # noqa: S603
32
+ except subprocess.TimeoutExpired:
33
+ return f"timed out after {timeout:g} s"
34
+ return "" if code == 0 else f"exit {code}"
35
+
36
+
37
+ def ensure(settings: Any, deps: bool = False) -> None:
38
+ """Install the browser build this playwright release pins, with its system libraries when `deps`.
39
+
40
+ Raises:
41
+ BrowserError: The install failed, for example offline or, with `deps`, without sudo.
42
+ """
43
+ timeout = config.limits(settings).install_timeout_seconds
44
+ name = str(settings.get("browser"))
45
+ failed = _install(name, timeout)
46
+ if not failed and deps:
47
+ failed = _system_libraries(name, timeout)
48
+ if failed:
49
+ raise BrowserError(f"playwright install {name}: {failed}")
50
+
51
+
52
+ def launch(driver: Any, settings: Any) -> Any:
53
+ """Return a launched browser: playwright's pinned build, else the host's Chrome.
54
+
55
+ The pinned build lays text out the same on every host, so it comes first.
56
+
57
+ Raises:
58
+ BrowserError: Neither starts.
59
+ """
60
+ # Imported here so the steps that need no page run without playwright.
61
+ from playwright.sync_api import Error
62
+
63
+ try:
64
+ ensure(settings)
65
+ return driver.chromium.launch()
66
+ except (BrowserError, Error) as pinned:
67
+ try:
68
+ return driver.chromium.launch(channel="chrome")
69
+ except Error as chrome:
70
+ raise BrowserError(
71
+ f"no browser to render with: {pinned}; Chrome: {chrome}"
72
+ ) from chrome
merrow/bundle.py ADDED
@@ -0,0 +1,69 @@
1
+ """The Mermaid bundle render and lint run in a browser page.
2
+
3
+ npm/package-lock.json pins it and Renovate keeps it current. merrow downloads
4
+ the tarball the lock names, checks it against the lock's sha512 integrity, and
5
+ caches the bundle file from it, so no Node.js install is needed.
6
+ """
7
+
8
+ import base64
9
+ import hashlib
10
+ import io
11
+ import json
12
+ import tarfile
13
+ from pathlib import Path
14
+ from typing import Any
15
+
16
+ from merrow import config
17
+ from merrow.sources.fetch import download, write_atomic
18
+
19
+ LOCKFILE = Path(__file__).parent / "npm" / "package-lock.json"
20
+
21
+
22
+ class BundleError(RuntimeError):
23
+ """The pinned bundle could not be fetched, or didn't match the lock."""
24
+
25
+
26
+ def _pin(package: str) -> dict[str, str]:
27
+ """Return the lock's `version`, `resolved` and `integrity` for a package."""
28
+ lock = json.loads(LOCKFILE.read_text(encoding="utf-8"))
29
+ return lock["packages"][f"node_modules/{package}"]
30
+
31
+
32
+ def version(settings: Any) -> str:
33
+ """Return the Mermaid version the lock pins."""
34
+ return _pin(settings.get("render")["bundle"]["package"])["version"]
35
+
36
+
37
+ def _integrity(data: bytes) -> str:
38
+ return "sha512-" + base64.b64encode(hashlib.sha512(data).digest()).decode("ascii")
39
+
40
+
41
+ def path(settings: Any) -> Path:
42
+ """Return the cached bundle file, downloading the pinned tarball when missing.
43
+
44
+ Raises:
45
+ BundleError: The tarball doesn't match the lock, or lacks the bundle file.
46
+ """
47
+ wanted = settings.get("render")["bundle"]
48
+ pin = _pin(wanted["package"])
49
+ member = str(wanted["file"])
50
+ target = (
51
+ config.cache_dir(settings)
52
+ / "bundle"
53
+ / f"{wanted['package']}-{pin['version']}"
54
+ / Path(member).name
55
+ )
56
+ if target.is_file():
57
+ return target
58
+ data = download(pin["resolved"], config.limits(settings))
59
+ if _integrity(data) != pin["integrity"]:
60
+ raise BundleError(f"{pin['resolved']} doesn't match the lock's integrity")
61
+ with tarfile.open(fileobj=io.BytesIO(data), mode="r:gz") as archive:
62
+ try:
63
+ handle = archive.extractfile(member)
64
+ except KeyError as missing:
65
+ raise BundleError(f"{pin['resolved']} has no {member}") from missing
66
+ if handle is None:
67
+ raise BundleError(f"{pin['resolved']}: {member} is not a file")
68
+ write_atomic(target, handle.read())
69
+ return target