run-radar-run 0.1__tar.gz

run_radar_run-0.1/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.3
+Name: run-radar-run
+Version: 0.1
+Summary: Run, Radar, Run - Running your own tech radar should be easy
+License: MIT
+Keywords: tech-radar
+Author: Alexei Znamensky
+Author-email: russoz@gmail.com
+Requires-Python: >=3.12,<4.0
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+Requires-Dist: blessed (>=1.20.0)
+Requires-Dist: docker (>=7.1.0)
+Requires-Dist: gitpython (>=3.1.44)
+Requires-Dist: pyyaml (>=5.4)
+Description-Content-Type: text/markdown
+
+Run, Radar, Run
+===============
+
+Using run-radar-run
+-------------------
+
+### Requirements
+
+* Python3.12+
+* Docker (for the TWBYOR radar)
+
+### Running the Radar
+
+Clone this repository and run:
+
+```bash
+$ ./run-radar-run
+```
+
+Or if you intend to see a specific radar directory, run:
+
+```bash
+$ ./run-radar-run -i tests/radar
+```
+
+### Publishers
+
+Publishers are the frameworks you can use to publish your tech radar.
+
+As of early 2025, the publishers available are:
+
+* Thoughtworks' Bring Your Own Radar
+* Zalando Tech Radar
+

run_radar_run-0.1/README.md

@@ -0,0 +1,33 @@
+Run, Radar, Run
+===============
+
+Using run-radar-run
+-------------------
+
+### Requirements
+
+* Python3.12+
+* Docker (for the TWBYOR radar)
+
+### Running the Radar
+
+Clone this repository and run:
+
+```bash
+$ ./run-radar-run
+```
+
+Or if you intend to see a specific radar directory, run:
+
+```bash
+$ ./run-radar-run -i tests/radar
+```
+
+### Publishers
+
+Publishers are the frameworks you can use to publish your tech radar.
+
+As of early 2025, the publishers available are:
+
+* Thoughtworks' Bring Your Own Radar
+* Zalando Tech Radar

run_radar_run-0.1/pyproject.toml

@@ -0,0 +1,45 @@
+[tool.poetry]
+name = "run-radar-run"
+version = "0.1"
+description = "Run, Radar, Run - Running your own tech radar should be easy"
+authors = ["Alexei Znamensky <russoz@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Information Technology",
+    "Operating System :: OS Independent",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Utilities"
+]
+keywords = [ "tech-radar" ]
+
+packages = [
+    { include = "runradarrun" }
+]
+
+[tool.poetry.scripts]
+run-radar-run = "runradarrun.main:main"
+
+[tool.poetry.dependencies]
+python = "^3.12"
+pyyaml = ">=5.4"
+docker = ">=7.1.0"
+blessed = ">=1.20.0"
+gitpython = ">=3.1.44"
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=7.3.1,<9.0.0"
+pytest-mock = "^3.10.0"
+pylint = ">=2.17.4,<4.0.0"
+flake8 = ">=6,<8"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

run_radar_run-0.1/runradarrun/ingest.py

@@ -0,0 +1,69 @@
+# -*- coding: utf-8 -*-
+# code: language=python tabSize=4
+#
+import argparse
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+from .model import Blip
+from .model import Quadrant
+from .model import Radar
+from .model import RadarException
+from .model import Ring
+from .output import Printer
+
+
+class Ingester:
+    def __init__(
+        self, path: Path, options: Optional[argparse.Namespace] = None
+    ) -> None:
+        self.radar_path = path
+        self.options = options
+        self.printer = Printer(options.quiet)
+
+    def parse_blip(self, quadrant: Quadrant, ring: Ring, path: Path) -> Blip:
+        with open(path) as blip_file:
+            blip_spec = yaml.safe_load(blip_file)
+
+            blip = Blip(
+                quadrant=quadrant.name,
+                ring=ring.name,
+                **{k: v for k, v in blip_spec["blip"].items() if k != "is_new"},
+            )
+            if "is_new" in blip_spec["blip"]:
+                blip.previous_ring = None if blip_spec["blip"]["is_new"] else blip.ring
+            else:
+                blip.previous_ring = blip.ring
+            return blip
+
+    def ingest(self) -> Radar:
+        if (self.radar_path / "specs.yml").exists():
+            file = self.radar_path / "specs.yml"
+        else:
+            file = self.radar_path / "specs.yaml"
+
+        with open(file) as f:
+            specs = yaml.safe_load(f)
+
+        rings = {pos: Ring(**r) for pos, r in specs["rings"].items()}
+        quadrants = {pos: Quadrant(**q) for pos, q in specs["quadrants"].items()}
+        radar = Radar(rings, quadrants)
+        count = 0
+
+        for ring in rings.values():
+            for quadrant in quadrants.values():
+                blips_dir: Path = self.radar_path / quadrant.id / ring.id
+                if not blips_dir.exists():
+                    continue
+                if not blips_dir.is_dir():
+                    raise RadarException(f"Path {blips_dir} must be a directory")
+
+                for path in blips_dir.iterdir():
+                    if path.as_posix().endswith((".yaml", ".yml")):
+                        blip = self.parse_blip(quadrant, ring, path)
+                        radar.add_blip(blip)
+                        count = count + 1
+
+        return radar

run_radar_run-0.1/runradarrun/main.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# code: language=python tabSize=4
+#
+import argparse
+import importlib
+import pathlib
+import pkgutil
+
+import runradarrun.publishers
+from runradarrun.ingest import Ingester
+from runradarrun.model import RadarException
+from runradarrun.output import Printer
+
+
+def iter_namespace(ns_pkg):
+    # Specifying the second argument (prefix) to iter_modules makes the
+    # returned name an absolute name instead of a relative one. This allows
+    # import_module to work without having to do additional modification to
+    # the name.
+    return pkgutil.iter_modules(ns_pkg.__path__, ns_pkg.__name__ + ".")
+
+
+def load_publishers():
+    return {
+        publisher.cli_id(): publisher
+        for finder, name, ispkg in iter_namespace(runradarrun.publishers)
+        for publisher in [getattr(importlib.import_module(name), "Publisher")]
+    }
+
+
+def main():
+    publishers = load_publishers()
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--publisher",
+        "-P",
+        default="twbyor",
+        choices=sorted(publishers.keys()),
+        help="publisher for the data radar",
+    )
+    parser.add_argument(
+        "--output",
+        "-o",
+        type=pathlib.Path,
+        help="output path for the radar data, depends on publisher",
+    )
+    parser.add_argument(
+        "--run",
+        "-r",
+        help="run the radar opens it in browser, depends on publisher",
+        action="store_true",
+    )
+    parser.add_argument(
+        "--run-only",
+        "-R",
+        help="only run the radar, depends on publisher",
+        action="store_true",
+    )
+    parser.add_argument(
+        "--quiet",
+        "-q",
+        help="do not print output",
+        action="store_true",
+    )
+    parser.add_argument(
+        "input",
+        type=pathlib.Path,
+        nargs="?",
+        default="./radar",
+        help="radar definition directory",
+    )
+
+    try:
+        args = parser.parse_args()
+        p = Printer(args.quiet)
+        ingester = Ingester(pathlib.Path(args.input), options=args)
+        radar = ingester.ingest()
+        p.print(
+            f"{p.align_item('Radar Path')}: {p.term.bold_yellow(str(ingester.radar_path.absolute()))}"
+        )
+        p.print(
+            f"{p.align_item('Rings')}: {', '.join(p.term.bold_green(r.name) for r in radar.rings_raw.values())}"
+        )
+        p.print(
+            f"{p.align_item('Quadrants')}: {', '.join(p.term.bold_green(q.name) for q in radar.quadrants_raw.values())}"
+        )
+        p.print(
+            f"{p.align_item('Processed')}: {p.term.bold_green}{len(radar.blips):2} blips{p.term.normal + p.term.clear_eol}"
+        )
+
+        if args.publisher:
+            publisher_class = publishers[args.publisher]
+            publisher = publisher_class(radar, options=args)
+
+            if args.output:
+                publisher.write(args.output)
+
+            if args.run or args.run_only:
+                try:
+                    p.print(
+                        f"{p.align_item('Radar URL')}: {p.term.bold_blue}{p.term.link(publisher.url, publisher.url)}{p.term.normal}"
+                    )
+                    publisher.run()
+                finally:
+                    publisher.cleanup()
+    except KeyboardInterrupt:
+        pass
+    except RadarException as e:
+        print(f"\n{p.term.bold_red}ERROR: {e}{p.term.normal}")
+
+
+if __name__ == "__main__":
+    main()

run_radar_run-0.1/runradarrun/model.py

@@ -0,0 +1,168 @@
+# -*- coding: utf-8 -*-
+# code: language=python tabSize=4
+#
+import argparse
+import webbrowser
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict
+from typing import List
+from typing import Optional
+from typing import Tuple
+from typing import Union
+
+
+OptionalStrOrListStr = Optional[Union[str, List[str]]]
+
+
+class RadarException(Exception):
+    pass
+
+
+@dataclass
+class Ring:
+    id: str
+    name: str
+
+
+@dataclass
+class Quadrant:
+    id: str
+    name: str
+
+
+class Blip:
+    def __init__(
+        self,
+        name: str,
+        ring: str,
+        quadrant: str,
+        previous_ring: Optional[str] = None,
+        description: OptionalStrOrListStr = None,
+        references: OptionalStrOrListStr = None,
+        tags: OptionalStrOrListStr = None,
+    ) -> None:
+        self.name = name
+        self.ring = ring
+        self.quadrant = quadrant
+        self.previous_ring = previous_ring
+        self.description = description or []
+        self.references = references or []
+        self.tags = tags or []
+
+    @property
+    def is_new(self) -> bool:
+        return self.previous_ring is None
+
+    def __str__(self) -> str:
+        return f"Blip({self.name}, r={self.ring}, q={self.quadrant}{' NEW' if self.is_new else ''})"
+
+    __repr__ = __str__
+
+
+class Radar:
+    MIN_NUM_RINGS = 3
+    MAX_NUM_RINGS = 4
+
+    Q_TL = "top_left"
+    Q_TR = "top_right"
+    Q_BL = "bottom_left"
+    Q_BR = "bottom_right"
+
+    QUADRANTS_CLOCKWISE = (Q_TL, Q_TR, Q_BR, Q_BL)
+    QUADRANTS_CTR_CLOCKWISE = (Q_TL, Q_BL, Q_BR, Q_TR)
+    QUADRANTS_TL_BL_TR_BR = (Q_TL, Q_BL, Q_TR, Q_BR)
+    QUADRANTS_TL_TR_BL_BR = (Q_TL, Q_TR, Q_BL, Q_BR)
+
+    def __init__(self, rings: Dict[str, Ring], quadrants: Dict[str, Quadrant]) -> None:
+        if Radar.MIN_NUM_RINGS <= len(rings) <= Radar.MAX_NUM_RINGS:
+            self._rings = rings
+        else:
+            raise RadarException(
+                f"Radar must have between {Radar.MIN_NUM_RINGS} and {Radar.MAX_NUM_RINGS}: {rings}"
+            )
+
+        if len(quadrants) != 4:
+            raise RadarException(f"Radar must have 4 quadrants: {quadrants}")
+        self._quadrants = quadrants
+        self._blips = []
+
+    def add_blip(self, blip: Blip) -> None:
+        self._blips.append(blip)
+
+    @property
+    def blips(self) -> Tuple[Blip]:
+        return tuple(self._blips)
+
+    @property
+    def rings_raw(self):
+        return self._rings
+
+    @property
+    def quadrants_raw(self):
+        return self._quadrants
+
+    def rings_outward(self) -> List[Ring]:
+        return [
+            self._rings[ring]
+            for ring in ["inner", "mid_inner", "mid_outer", "outer"]
+            if self._rings.get(ring)
+        ]
+
+    def rings_inward(self) -> List[Ring]:
+        return [
+            self._rings[ring]
+            for ring in ["outer", "mid_outer", "mid_inner", "inner"]
+            if self._rings.get(ring)
+        ]
+
+    def quadrants(self, order: Tuple) -> List[Quadrant]:
+        return [self._quadrants[q] for q in order]
+
+
+class AbstractPublisher:
+    publishing_url = None
+
+    def __init__(
+        self, radar: Radar, options: Optional[argparse.Namespace] = None
+    ) -> None:
+        self.radar = radar
+        self.options = options
+        self._output = None
+
+    def make_output(self) -> str:
+        raise NotImplementedError()
+
+    @classmethod
+    def cli_id(cls):
+        raise NotImplementedError()
+
+    @property
+    def output(self) -> str:
+        if self._output is None:
+            self._output = self.make_output()
+        return self._output
+
+    def run(self):
+        # optional implementation
+        pass
+
+    def cleanup(self):
+        # optional implementation
+        pass
+
+    @property
+    def url(self) -> str:
+        if self.publishing_url is None:
+            raise NotImplementedError()
+        return self.publishing_url
+
+    def write(self, output: Path) -> None:
+        with open(output, "w") as outputfile:
+            outputfile.write(self.output)
+
+    def open_url(self, url: Optional[str] = None) -> None:
+        if not url:
+            url = self.url
+        if not self.options.run_only:
+            webbrowser.open(url, new=1)

run_radar_run-0.1/runradarrun/output.py

@@ -0,0 +1,53 @@
+# -*- coding: utf-8 -*-
+# code: language=python tabSize=4
+#
+from blessed import Terminal
+
+
+class Printer:
+    def __init__(self, quiet) -> None:
+        self.quiet = quiet
+        self._term = None
+
+    @property
+    def term(self) -> Terminal:
+        if not self._term:
+            self._term = Terminal()
+        return self._term
+
+    def print(self, *args, **kwargs) -> None:
+        if not self.quiet:
+            print(*args, **kwargs)
+
+    def align_item(self, item: str) -> str:
+        return self.term.rjust(item, 12)
+
+    def logger(self, stream, log_height, trigger=None):
+        try:
+            self.print(
+                self.term.hide_cursor
+                + "\n" * (log_height + 1)
+                + self.term.move_up(log_height)
+                + self.term.grey,
+                end="",
+            )
+            start_row, _ = self.term.get_location()
+
+            log_lines = []
+            for line in stream:
+                line = line.decode("utf-8").strip()
+                for wrapped_line in self.term.wrap(line) or [""]:
+                    log_lines.append(wrapped_line)
+
+                log_lines = log_lines[-log_height:]
+                log_lines[-1] = log_lines[-1] + self.term.clear_eol + "\n"
+                with self.term.location(0, start_row):
+                    for log_line in log_lines:
+                        self.print(f"{log_line}", end="", flush=True)
+
+                if trigger:
+                    trigger(line)
+        finally:
+            print(
+                f"{self.term.normal}{self.term.normal_cursor}{self.term.move_up}{self.term.clear_eos}"
+            )

run_radar_run-0.1/runradarrun/publishers/twbyor.py

@@ -0,0 +1,88 @@
+# -*- coding: utf-8 -*-
+# code: language=python tabSize=4
+#
+import json
+import os
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+import docker
+
+from ..model import AbstractPublisher
+from ..output import Printer
+
+
+class Publisher(AbstractPublisher):
+    container_image = "wwwthoughtworks/build-your-own-radar:latest"
+    container = None
+    publishing_url = "http://localhost:8080/"
+    run_output_file = "run-radar-run.json"
+
+    @classmethod
+    def cli_id(cls):
+        return "twbyor"
+
+    def make_output(self):
+        results = []
+        for blip in self.radar.blips:
+            results.append(
+                dict(
+                    name=blip.name,
+                    ring=blip.ring,
+                    quadrant=blip.quadrant,
+                    isNew="TRUE" if blip.is_new else "FALSE",
+                    description=blip.description,
+                )
+            )
+
+        return json.dumps(results)
+
+    def run(self):
+        with TemporaryDirectory(dir=".", prefix=".runradarrun-") as temp_dir:
+            os.chmod(temp_dir, 0o755)
+            temp_output = Path(temp_dir) / self.run_output_file
+            self.write(temp_output)
+
+            rd = self.radar
+            client = docker.from_env()
+            self.container = client.containers.run(
+                self.container_image,
+                auto_remove=True,
+                ports={"80/tcp": 8080},
+                environment={
+                    "SERVER_NAMES": "localhost 127.0.0.1",
+                    "QUADRANTS": json.dumps(
+                        [q.name for q in rd.quadrants(rd.QUADRANTS_TL_BL_TR_BR)]
+                    ),
+                    "RINGS": json.dumps([r.name for r in rd.rings_outward()]),
+                },
+                volumes={
+                    temp_dir: {"bind": "/opt/build-your-own-radar/files", "mode": "rw"}
+                },
+                detach=True,
+                stream=True,
+            )
+
+            p = Printer(self.options.quiet)
+
+            def trigger_browser(line):
+                if "Starting nginx server..." in line:
+                    self.open_url()
+
+            p.logger(
+                stream=self.container.logs(stream=True),
+                log_height=10,
+                trigger=trigger_browser,
+            )
+
+    def cleanup(self):
+        if self.container:
+            self.container.stop()
+
+    @property
+    def url(self):
+        return (
+            f"{self.publishing_url}"
+            "?documentId=http%3A%2F%2Flocalhost%3A8080%2Ffiles%2F"
+            f"{self.run_output_file}"
+        )

run_radar_run-0.1/runradarrun/publishers/zalando.py

@@ -0,0 +1,161 @@
+# -*- coding: utf-8 -*-
+# code: language=python tabSize=4
+#
+import json
+import os
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+import docker
+from git import Repo
+
+from ..model import AbstractPublisher
+from ..output import Printer
+
+
+html_content = """\
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+<meta http-equiv="Content-type" content="text/html; charset=utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Zalando Tech Radar</title>
+<link rel="shortcut icon" href="https://www.zalando.de/favicon.ico">
+
+<script src="https://d3js.org/d3.v4.min.js"></script>
+<script src="radar.js"></script>
+
+<link rel="stylesheet" href="radar.css">
+</head>
+
+<body>
+
+<svg id="radar"></svg>
+
+<script>
+fetch('./config.json').then(function(response) {
+  return response.json();
+}).then(function(data) {
+  radar_visualization(data);
+}).catch(function(err) {
+  console.log('Error loading config.json', err);
+});
+</script>
+
+</body>
+</html>
+"""
+
+
+class Publisher(AbstractPublisher):
+    zalando_git_url = "https://github.com/zalando/tech-radar.git"
+    container_image = "gcriocloudbuilders/yarn"
+    container = None
+    publishing_url = "http://localhost:8080/"
+    ring_colors = ["#5ba300", "#009eb0", "#c7ba00", "#e09b96"]
+
+    @property
+    def quadrant_order(self):
+        rd = self.radar
+        return (rd.Q_BR, rd.Q_BL, rd.Q_TL, rd.Q_TR)
+
+    @classmethod
+    def cli_id(cls):
+        return "zalando"
+
+    def make_output(self):
+        q_names = [q.name for q in self.radar.quadrants(self.quadrant_order)]
+        r_names = [r.name for r in self.radar.rings_outward()]
+
+        entries = [
+            dict(
+                quadrant=q_names.index(blip.quadrant),
+                ring=r_names.index(blip.ring),
+                label=blip.name,
+                active=True,
+                moved=(blip.ring != blip.previous_ring),
+            )
+            for blip in self.radar.blips
+        ]
+
+        output = dict(
+            repo_url="https://github.com/zalando/tech-radar",
+            title="Zalando Tech Radar",
+            date="2025.01",  # kind of a version
+            quadrants=[
+                {"name": q.name} for q in self.radar.quadrants(self.quadrant_order)
+            ],
+            rings=[
+                dict(
+                    name=r.name.upper(),
+                    color=c,
+                )
+                for r, c in zip(self.radar.rings_outward(), self.ring_colors)
+            ],
+            entries=entries,
+        )
+        return json.dumps(output)
+
+    def run(self):
+        with TemporaryDirectory(dir=".", prefix=".runradarrun-") as temp_dir:
+            os.chmod(temp_dir, 0o755)
+
+            repo_dir = Path(temp_dir) / "zalando"
+            Repo.clone_from(self.zalando_git_url, repo_dir, depth=1)
+
+            temp_output = repo_dir / "docs" / "config.json"
+            self.write(temp_output)
+
+            with open(repo_dir / "docs" / "index.html", "w") as index:
+                index.write(html_content)
+
+            p = Printer(self.options.quiet)
+
+            client = docker.from_env()
+            # Run bare yarn to install packages
+            self.container = client.containers.run(
+                self.container_image,
+                auto_remove=True,
+                volumes={repo_dir.as_posix(): {"bind": "/app", "mode": "rw"}},
+                working_dir="/app",
+                detach=True,
+                stream=True,
+                user=os.getuid(),
+            )
+
+            p.logger(
+                stream=self.container.logs(stream=True),
+                log_height=10,
+            )
+
+            # Run radar
+            self.container = client.containers.run(
+                self.container_image,
+                auto_remove=True,
+                ports={"3000/tcp": 8080},
+                volumes={repo_dir.as_posix(): {"bind": "/app", "mode": "rw"}},
+                working_dir="/app",
+                detach=True,
+                stream=True,
+                command=["start", "--no-open"],
+                user=os.getuid(),
+            )
+
+            def trigger_browser(line):
+                if "Watching files..." in line:
+                    self.open_url()
+
+            p.logger(
+                stream=self.container.logs(stream=True),
+                log_height=10,
+                trigger=trigger_browser,
+            )
+
+    def cleanup(self):
+        if self.container:
+            self.container.stop()
+
+    @property
+    def url(self):
+        return self.publishing_url