k3kroki 0.1.0__tar.gz

k3kroki-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 张炎泼
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

k3kroki-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: k3kroki
+Version: 0.1.0
+Summary: Convert diagrams to images via the kroki.io API — zero local dependencies
+Author-email: Zhang Yanpo <drdr.xp@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/pykit3/k3kroki
+Project-URL: Documentation, https://k3kroki.readthedocs.io
+Keywords: diagram,kroki,graphviz,mermaid,plantuml,svg,png
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: resvg-py>=0.2
+Requires-Dist: Pillow>=10.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: numpy; extra == "dev"
+Requires-Dist: scikit-image; extra == "dev"
+Requires-Dist: Pillow; extra == "dev"
+Provides-Extra: publish
+Requires-Dist: build; extra == "publish"
+Requires-Dist: twine; extra == "publish"
+Requires-Dist: pk3; extra == "publish"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
+Dynamic: license-file
+
+# k3kroki
+
+[![Action-CI](https://github.com/pykit3/k3kroki/actions/workflows/python-package.yml/badge.svg)](https://github.com/pykit3/k3kroki/actions/workflows/python-package.yml)
+[![Documentation Status](https://readthedocs.org/projects/k3kroki/badge/?version=stable)](https://k3kroki.readthedocs.io/en/stable/?badge=stable)
+[![Package](https://img.shields.io/pypi/pyversions/k3kroki)](https://pypi.org/project/k3kroki)
+
+Convert diagrams to images via the kroki.io API — zero local dependencies
+
+k3kroki is a component of [pykit3] project: a python3 toolkit set.
+
+k3kroki converts diagrams to images via the free kroki.io HTTP API — no local tools needed.
+
+
+# Install
+
+```
+pip install k3kroki
+```
+
+# Synopsis
+
+```python
+import k3kroki
+
+# Render a Graphviz diagram to SVG bytes
+svg = k3kroki.convert("graphviz", "digraph { a -> b }")
+
+# Render a Mermaid diagram and save to file
+k3kroki.convert_to_file("mermaid", "graph TD\n  A --> B", "diagram.svg")
+
+# Render PlantUML to PNG
+png = k3kroki.convert("plantuml", "@startuml\nAlice -> Bob: hello\n@enduml", "png")
+```
+
+#   Author
+
+Zhang Yanpo (张炎泼) <drdr.xp@gmail.com>
+
+#   Copyright and License
+
+The MIT License (MIT)
+
+Copyright (c) 2015 Zhang Yanpo (张炎泼) <drdr.xp@gmail.com>
+
+
+[pykit3]: https://github.com/pykit3

k3kroki-0.1.0/README.md

@@ -0,0 +1,46 @@
+# k3kroki
+
+[![Action-CI](https://github.com/pykit3/k3kroki/actions/workflows/python-package.yml/badge.svg)](https://github.com/pykit3/k3kroki/actions/workflows/python-package.yml)
+[![Documentation Status](https://readthedocs.org/projects/k3kroki/badge/?version=stable)](https://k3kroki.readthedocs.io/en/stable/?badge=stable)
+[![Package](https://img.shields.io/pypi/pyversions/k3kroki)](https://pypi.org/project/k3kroki)
+
+Convert diagrams to images via the kroki.io API — zero local dependencies
+
+k3kroki is a component of [pykit3] project: a python3 toolkit set.
+
+k3kroki converts diagrams to images via the free kroki.io HTTP API — no local tools needed.
+
+
+# Install
+
+```
+pip install k3kroki
+```
+
+# Synopsis
+
+```python
+import k3kroki
+
+# Render a Graphviz diagram to SVG bytes
+svg = k3kroki.convert("graphviz", "digraph { a -> b }")
+
+# Render a Mermaid diagram and save to file
+k3kroki.convert_to_file("mermaid", "graph TD\n  A --> B", "diagram.svg")
+
+# Render PlantUML to PNG
+png = k3kroki.convert("plantuml", "@startuml\nAlice -> Bob: hello\n@enduml", "png")
+```
+
+#   Author
+
+Zhang Yanpo (张炎泼) <drdr.xp@gmail.com>
+
+#   Copyright and License
+
+The MIT License (MIT)
+
+Copyright (c) 2015 Zhang Yanpo (张炎泼) <drdr.xp@gmail.com>
+
+
+[pykit3]: https://github.com/pykit3

k3kroki-0.1.0/__init__.py

@@ -0,0 +1,32 @@
+"""k3kroki converts diagrams to images via the free kroki.io HTTP API — no local tools needed."""
+
+from importlib.metadata import version
+
+__version__ = version("k3kroki")
+__name__ = "k3kroki"
+
+from .kroki import (
+    DEFAULT_BASE_URL,
+    DIAGRAM_TYPES,
+    OUTPUT_FORMATS,
+    KrokiAPIError,
+    KrokiError,
+    KrokiNetworkError,
+    UnsupportedDiagramError,
+    UnsupportedFormatError,
+    convert,
+    convert_to_file,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "DIAGRAM_TYPES",
+    "OUTPUT_FORMATS",
+    "KrokiAPIError",
+    "KrokiError",
+    "KrokiNetworkError",
+    "UnsupportedDiagramError",
+    "UnsupportedFormatError",
+    "convert",
+    "convert_to_file",
+]

k3kroki-0.1.0/k3kroki.egg-info/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: k3kroki
+Version: 0.1.0
+Summary: Convert diagrams to images via the kroki.io API — zero local dependencies
+Author-email: Zhang Yanpo <drdr.xp@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/pykit3/k3kroki
+Project-URL: Documentation, https://k3kroki.readthedocs.io
+Keywords: diagram,kroki,graphviz,mermaid,plantuml,svg,png
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: resvg-py>=0.2
+Requires-Dist: Pillow>=10.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: numpy; extra == "dev"
+Requires-Dist: scikit-image; extra == "dev"
+Requires-Dist: Pillow; extra == "dev"
+Provides-Extra: publish
+Requires-Dist: build; extra == "publish"
+Requires-Dist: twine; extra == "publish"
+Requires-Dist: pk3; extra == "publish"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
+Dynamic: license-file
+
+# k3kroki
+
+[![Action-CI](https://github.com/pykit3/k3kroki/actions/workflows/python-package.yml/badge.svg)](https://github.com/pykit3/k3kroki/actions/workflows/python-package.yml)
+[![Documentation Status](https://readthedocs.org/projects/k3kroki/badge/?version=stable)](https://k3kroki.readthedocs.io/en/stable/?badge=stable)
+[![Package](https://img.shields.io/pypi/pyversions/k3kroki)](https://pypi.org/project/k3kroki)
+
+Convert diagrams to images via the kroki.io API — zero local dependencies
+
+k3kroki is a component of [pykit3] project: a python3 toolkit set.
+
+k3kroki converts diagrams to images via the free kroki.io HTTP API — no local tools needed.
+
+
+# Install
+
+```
+pip install k3kroki
+```
+
+# Synopsis
+
+```python
+import k3kroki
+
+# Render a Graphviz diagram to SVG bytes
+svg = k3kroki.convert("graphviz", "digraph { a -> b }")
+
+# Render a Mermaid diagram and save to file
+k3kroki.convert_to_file("mermaid", "graph TD\n  A --> B", "diagram.svg")
+
+# Render PlantUML to PNG
+png = k3kroki.convert("plantuml", "@startuml\nAlice -> Bob: hello\n@enduml", "png")
+```
+
+#   Author
+
+Zhang Yanpo (张炎泼) <drdr.xp@gmail.com>
+
+#   Copyright and License
+
+The MIT License (MIT)
+
+Copyright (c) 2015 Zhang Yanpo (张炎泼) <drdr.xp@gmail.com>
+
+
+[pykit3]: https://github.com/pykit3

k3kroki-0.1.0/k3kroki.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+__init__.py
+kroki.py
+pyproject.toml
+synopsis.py
+./__init__.py
+./kroki.py
+./synopsis.py
+k3kroki.egg-info/PKG-INFO
+k3kroki.egg-info/SOURCES.txt
+k3kroki.egg-info/dependency_links.txt
+k3kroki.egg-info/requires.txt
+k3kroki.egg-info/top_level.txt
+test/test_doctest.py
+test/test_kroki.py

k3kroki-0.1.0/k3kroki.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

k3kroki-0.1.0/k3kroki.egg-info/requires.txt

@@ -0,0 +1,20 @@
+resvg-py>=0.2
+Pillow>=10.0
+
+[dev]
+pytest>=7.0
+ruff
+coverage
+numpy
+scikit-image
+Pillow
+
+[docs]
+mkdocs>=1.5
+mkdocs-material>=9.0
+mkdocstrings[python]>=0.24
+
+[publish]
+build
+twine
+pk3

k3kroki-0.1.0/k3kroki.egg-info/top_level.txt

@@ -0,0 +1 @@
+k3kroki

k3kroki-0.1.0/kroki.py

@@ -0,0 +1,205 @@
+"""Convert diagrams to images via the kroki.io HTTP API with local SVG→bitmap fallback.
+
+Note:
+    Excalidraw is **not** supported. The kroki.io excalidraw backend is
+    unreliable (its internal renderer frequently refuses connections),
+    making it impossible to produce stable output.
+"""
+
+from __future__ import annotations
+
+import http.client
+import io
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+from PIL import Image
+from resvg_py import svg_to_bytes
+
+DEFAULT_BASE_URL = "https://kroki.io"
+
+DIAGRAM_TYPES: frozenset[str] = frozenset(
+    {
+        "actdiag",
+        "blockdiag",
+        "bpmn",
+        "bytefield",
+        "c4plantuml",
+        "d2",
+        "dbml",
+        "ditaa",
+        "erd",
+        "graphviz",
+        "mermaid",
+        "nomnoml",
+        "nwdiag",
+        "packetdiag",
+        "pikchr",
+        "plantuml",
+        "rackdiag",
+        "seqdiag",
+        "structurizr",
+        "svgbob",
+        "symbolator",
+        "tikz",
+        "umlet",
+        "vega",
+        "vegalite",
+        "wavedrom",
+        "wireviz",
+    }
+)
+
+OUTPUT_FORMATS: frozenset[str] = frozenset({"svg", "png", "jpeg", "pdf", "webp"})
+
+_EXT_TO_FORMAT: dict[str, str] = {
+    ".svg": "svg",
+    ".png": "png",
+    ".jpg": "jpeg",
+    ".jpeg": "jpeg",
+    ".pdf": "pdf",
+    ".webp": "webp",
+}
+
+_BITMAP_FORMATS: frozenset[str] = frozenset({"png", "jpeg", "webp"})
+
+
+def _fetch_kroki(base_url: str, diagram_type: str, output_format: str, data: bytes, timeout: float) -> bytes:
+    """Send a request to the kroki API and return response bytes."""
+    url = f"{base_url.rstrip('/')}/{diagram_type}/{output_format}"
+    headers = {
+        "Content-Type": "text/plain",
+        "User-Agent": "k3kroki/0.1",
+    }
+    req = urllib.request.Request(url, data=data, headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return resp.read()
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")
+        raise KrokiAPIError(exc.code, body) from exc
+    except urllib.error.URLError as exc:
+        raise KrokiNetworkError(str(exc.reason)) from exc
+    except (OSError, http.client.HTTPException) as exc:
+        # urllib wraps only the errors raised while sending the request; a
+        # timeout or reset while reading the response arrives unwrapped, and a
+        # truncated body raises `http.client.IncompleteRead`, not an OSError.
+        raise KrokiNetworkError(str(exc)) from exc
+
+
+def _svg_to_bitmap(svg_bytes: bytes, output_format: str) -> bytes:
+    """Render SVG bytes to a bitmap format using resvg (SVG→PNG) and Pillow (PNG→JPEG/WebP)."""
+    png_bytes = svg_to_bytes(svg_string=svg_bytes.decode("utf-8"), dpi=192)
+    if output_format == "png":
+        return png_bytes
+
+    img = Image.open(io.BytesIO(png_bytes))
+    buf = io.BytesIO()
+    if output_format == "jpeg":
+        img = img.convert("RGB")
+    img.save(buf, format=output_format.upper(), quality=90)
+    return buf.getvalue()
+
+
+class KrokiError(Exception):
+    """Base exception for k3kroki."""
+
+
+class UnsupportedDiagramError(KrokiError, ValueError):
+    """Raised when the diagram type is not supported."""
+
+
+class UnsupportedFormatError(KrokiError, ValueError):
+    """Raised when the output format is not supported."""
+
+
+class KrokiAPIError(KrokiError):
+    """Raised when the kroki API returns a non-2xx response."""
+
+    def __init__(self, status_code: int, body: str) -> None:
+        self.status_code = status_code
+        self.body = body
+        super().__init__(f"Kroki API error {status_code}: {body}")
+
+
+class KrokiNetworkError(KrokiError):
+    """Raised on network-level failures (DNS, timeout, connection refused)."""
+
+
+def convert(
+    diagram_type: str,
+    source: str,
+    output_format: str = "svg",
+    *,
+    base_url: str = DEFAULT_BASE_URL,
+    timeout: float = 30.0,
+) -> bytes:
+    """Send diagram source to kroki and return rendered image bytes.
+
+    Args:
+        diagram_type: Diagram language (e.g. ``"graphviz"``, ``"mermaid"``).
+        source: Diagram source text.
+        output_format: One of ``"svg"``, ``"png"``, ``"jpeg"``, ``"pdf"``, ``"webp"``.
+        base_url: Kroki server URL. Defaults to ``https://kroki.io``.
+        timeout: HTTP timeout in seconds.
+
+    Returns:
+        Raw bytes of the rendered image.
+
+    Raises:
+        UnsupportedDiagramError: If *diagram_type* is not recognised.
+        UnsupportedFormatError: If *output_format* is not recognised.
+        KrokiAPIError: If the server returns a non-2xx status.
+        KrokiNetworkError: On connection / DNS / timeout failures.
+    """
+    diagram_type = diagram_type.lower()
+    output_format = output_format.lower()
+
+    if diagram_type not in DIAGRAM_TYPES:
+        raise UnsupportedDiagramError(f"Unsupported diagram type: {diagram_type!r}")
+    if output_format not in OUTPUT_FORMATS:
+        raise UnsupportedFormatError(f"Unsupported output format: {output_format!r}")
+
+    data = source.encode("utf-8")
+
+    try:
+        return _fetch_kroki(base_url, diagram_type, output_format, data, timeout)
+    except KrokiAPIError as exc:
+        if output_format not in _BITMAP_FORMATS or "Unsupported output format" not in exc.body:
+            raise
+
+    svg_bytes = _fetch_kroki(base_url, diagram_type, "svg", data, timeout)
+    return _svg_to_bitmap(svg_bytes, output_format)
+
+
+def convert_to_file(
+    diagram_type: str,
+    source: str,
+    output_path: str,
+    output_format: str | None = None,
+    *,
+    base_url: str = DEFAULT_BASE_URL,
+    timeout: float = 30.0,
+) -> None:
+    """Render a diagram and write the result to *output_path*.
+
+    If *output_format* is ``None`` it is inferred from the file extension
+    (``.svg``, ``.png``, ``.jpg``/``.jpeg``, ``.pdf``).
+
+    Args:
+        diagram_type: Diagram language.
+        source: Diagram source text.
+        output_path: Destination file path.
+        output_format: Explicit format, or ``None`` to infer from extension.
+        base_url: Kroki server URL.
+        timeout: HTTP timeout in seconds.
+    """
+    if output_format is None:
+        ext = Path(output_path).suffix.lower()
+        output_format = _EXT_TO_FORMAT.get(ext)
+        if output_format is None:
+            raise UnsupportedFormatError(f"Cannot infer format from extension: {ext!r}")
+
+    data = convert(diagram_type, source, output_format, base_url=base_url, timeout=timeout)
+    Path(output_path).write_bytes(data)

k3kroki-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "k3kroki"
+version = "0.1.0"
+description = "Convert diagrams to images via the kroki.io API — zero local dependencies"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    { name = "Zhang Yanpo", email = "drdr.xp@gmail.com" }
+]
+keywords = ["diagram", "kroki", "graphviz", "mermaid", "plantuml", "svg", "png"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "resvg-py>=0.2",
+    "Pillow>=10.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/pykit3/k3kroki"
+Documentation = "https://k3kroki.readthedocs.io"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "ruff",
+    "coverage",
+    "numpy",
+    "scikit-image",
+    "Pillow",
+]
+publish = [
+    "build",
+    "twine",
+    "pk3",
+]
+docs = [
+    "mkdocs>=1.5",
+    "mkdocs-material>=9.0",
+    "mkdocstrings[python]>=0.24",
+]
+
+[tool.setuptools]
+packages = ["k3kroki"]
+
+[tool.setuptools.package-dir]
+k3kroki = "."
+
+[tool.ruff]
+line-length = 120

k3kroki-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

k3kroki-0.1.0/synopsis.py

@@ -0,0 +1,10 @@
+import k3kroki
+
+# Render a Graphviz diagram to SVG bytes
+svg = k3kroki.convert("graphviz", "digraph { a -> b }")
+
+# Render a Mermaid diagram and save to file
+k3kroki.convert_to_file("mermaid", "graph TD\n  A --> B", "diagram.svg")
+
+# Render PlantUML to PNG
+png = k3kroki.convert("plantuml", "@startuml\nAlice -> Bob: hello\n@enduml", "png")

k3kroki-0.1.0/test/test_doctest.py

@@ -0,0 +1,8 @@
+import doctest
+
+import k3kroki
+
+
+def load_tests(loader, tests, ignore):
+    tests.addTests(doctest.DocTestSuite(k3kroki))
+    return tests

k3kroki-0.1.0/test/test_kroki.py

@@ -0,0 +1,361 @@
+from __future__ import annotations
+
+import contextlib
+import http.client
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import numpy
+from skimage.metrics import structural_similarity as ssim
+
+import k3kroki
+from k3kroki.kroki import (
+    _EXT_TO_FORMAT,
+    DEFAULT_BASE_URL,
+    DIAGRAM_TYPES,
+    OUTPUT_FORMATS,
+    KrokiAPIError,
+    KrokiNetworkError,
+    UnsupportedDiagramError,
+    UnsupportedFormatError,
+    convert,
+    convert_to_file,
+)
+
+DATA_DIR = Path(__file__).parent / "data"
+
+
+def _mock_urlopen_response(response_data: bytes = b"<svg/>"):
+    mock_resp = MagicMock()
+    mock_resp.read.return_value = response_data
+    mock_resp.__enter__ = lambda s: s
+    mock_resp.__exit__ = MagicMock(return_value=False)
+    return mock_resp
+
+
+def _image_ssim(want_path: Path, got_path: Path) -> float:
+    from PIL import Image as PILImage
+
+    want_img = PILImage.open(want_path).convert("RGB")
+    got_img = PILImage.open(got_path).convert("RGB")
+
+    if want_img.size != got_img.size:
+        got_img = got_img.resize(want_img.size, PILImage.LANCZOS)
+
+    img1 = numpy.asarray(want_img)
+    img2 = numpy.asarray(got_img)
+    return ssim(img1, img2, channel_axis=2, data_range=255)
+
+
+class TestConstants(unittest.TestCase):
+    def test_diagram_types_is_frozenset(self):
+        self.assertIsInstance(DIAGRAM_TYPES, frozenset)
+
+    def test_well_known_types_present(self):
+        for t in ("graphviz", "mermaid", "plantuml", "d2", "ditaa", "erd"):
+            self.assertIn(t, DIAGRAM_TYPES)
+
+    def test_output_formats(self):
+        self.assertEqual(OUTPUT_FORMATS, frozenset({"svg", "png", "jpeg", "pdf", "webp"}))
+
+    def test_default_base_url(self):
+        self.assertEqual(DEFAULT_BASE_URL, "https://kroki.io")
+
+
+class TestValidation(unittest.TestCase):
+    def test_unsupported_diagram_type(self):
+        with self.assertRaises(UnsupportedDiagramError):
+            convert("not_a_real_type", "source")
+
+    def test_unsupported_output_format(self):
+        with self.assertRaises(UnsupportedFormatError):
+            convert("graphviz", "source", "gif")
+
+    def test_diagram_type_case_insensitive(self):
+        with patch("k3kroki.kroki.urllib.request.urlopen") as mock_urlopen:
+            mock_urlopen.return_value = _mock_urlopen_response()
+            convert("Graphviz", "digraph{a->b}", "SVG")
+
+            req = mock_urlopen.call_args[0][0]
+            self.assertIn("/graphviz/svg", req.full_url)
+
+
+class TestConvertMocked(unittest.TestCase):
+    @patch("k3kroki.kroki.urllib.request.urlopen")
+    def test_url_construction(self, mock_urlopen):
+        mock_urlopen.return_value = _mock_urlopen_response()
+        convert("mermaid", "graph TD; A-->B", "png")
+
+        req = mock_urlopen.call_args[0][0]
+        self.assertEqual(req.full_url, "https://kroki.io/mermaid/png")
+
+    @patch("k3kroki.kroki.urllib.request.urlopen")
+    def test_custom_base_url(self, mock_urlopen):
+        mock_urlopen.return_value = _mock_urlopen_response()
+        convert("graphviz", "digraph{}", "svg", base_url="http://localhost:8000")
+
+        req = mock_urlopen.call_args[0][0]
+        self.assertEqual(req.full_url, "http://localhost:8000/graphviz/svg")
+
+    @patch("k3kroki.kroki.urllib.request.urlopen")
+    def test_trailing_slash_stripped(self, mock_urlopen):
+        mock_urlopen.return_value = _mock_urlopen_response()
+        convert("graphviz", "digraph{}", "svg", base_url="https://kroki.io/")
+
+        req = mock_urlopen.call_args[0][0]
+        self.assertEqual(req.full_url, "https://kroki.io/graphviz/svg")
+
+    @patch("k3kroki.kroki.urllib.request.urlopen")
+    def test_content_type_header(self, mock_urlopen):
+        mock_urlopen.return_value = _mock_urlopen_response()
+        convert("graphviz", "digraph{a->b}", "svg")
+
+        req = mock_urlopen.call_args[0][0]
+        self.assertEqual(req.get_header("Content-type"), "text/plain")
+
+    @patch("k3kroki.kroki.urllib.request.urlopen")
+    def test_post_body_is_utf8_encoded(self, mock_urlopen):
+        mock_urlopen.return_value = _mock_urlopen_response()
+        source = 'digraph { label="日本語" }'
+        convert("graphviz", source, "svg")
+
+        req = mock_urlopen.call_args[0][0]
+        self.assertEqual(req.data, source.encode("utf-8"))
+
+    @patch("k3kroki.kroki.urllib.request.urlopen")
+    def test_returns_bytes(self, mock_urlopen):
+        mock_urlopen.return_value = _mock_urlopen_response(b"\x89PNG")
+        result = convert("graphviz", "digraph{}", "png")
+        self.assertEqual(result, b"\x89PNG")
+
+    @patch("k3kroki.kroki.urllib.request.urlopen")
+    def test_timeout_passed(self, mock_urlopen):
+        mock_urlopen.return_value = _mock_urlopen_response()
+        convert("graphviz", "digraph{}", "svg", timeout=5.0)
+        self.assertEqual(mock_urlopen.call_args[1]["timeout"], 5.0)
+
+
+class TestSvgFallbackMocked(unittest.TestCase):
+    """Test the SVG→bitmap fallback path using mocks."""
+
+    @patch("k3kroki.kroki._svg_to_bitmap")
+    @patch("k3kroki.kroki._fetch_kroki")
+    def test_fallback_on_unsupported_format(self, mock_fetch, mock_bitmap):
+        mock_fetch.side_effect = [
+            KrokiAPIError(400, "Unsupported output format: png"),
+            b"<svg>mock</svg>",
+        ]
+        mock_bitmap.return_value = b"\x89PNG-mock"
+
+        result = convert("d2", "x -> y", "png")
+
+        self.assertEqual(result, b"\x89PNG-mock")
+        self.assertEqual(mock_fetch.call_count, 2)
+        self.assertEqual(mock_fetch.call_args_list[1][0][2], "svg")
+        mock_bitmap.assert_called_once_with(b"<svg>mock</svg>", "png")
+
+    @patch("k3kroki.kroki._fetch_kroki")
+    def test_non_format_api_error_propagates(self, mock_fetch):
+        mock_fetch.side_effect = KrokiAPIError(400, "syntax error in diagram")
+
+        with self.assertRaises(KrokiAPIError) as ctx:
+            convert("graphviz", "bad", "png")
+
+        self.assertIn("syntax error", ctx.exception.body)
+
+    @patch("k3kroki.kroki._fetch_kroki")
+    def test_fallback_not_triggered_for_svg(self, mock_fetch):
+        mock_fetch.side_effect = KrokiAPIError(400, "Unsupported output format: svg")
+
+        with self.assertRaises(KrokiAPIError):
+            convert("d2", "x -> y", "svg")
+
+        mock_fetch.assert_called_once()
+
+
+class TestErrorWrapping(unittest.TestCase):
+    @patch("k3kroki.kroki.urllib.request.urlopen")
+    def test_http_error_becomes_api_error(self, mock_urlopen):
+        import urllib.error
+
+        exc = urllib.error.HTTPError("url", 400, "Bad Request", {}, MagicMock(read=lambda: b"syntax error"))
+        mock_urlopen.side_effect = exc
+
+        with self.assertRaises(KrokiAPIError) as ctx:
+            convert("graphviz", "bad source", "svg")
+
+        self.assertEqual(ctx.exception.status_code, 400)
+        self.assertIn("syntax error", ctx.exception.body)
+
+    @patch("k3kroki.kroki.urllib.request.urlopen")
+    def test_url_error_becomes_network_error(self, mock_urlopen):
+        import urllib.error
+
+        mock_urlopen.side_effect = urllib.error.URLError("Name or service not known")
+
+        with self.assertRaises(KrokiNetworkError):
+            convert("graphviz", "digraph{}", "svg")
+
+    @patch("k3kroki.kroki.urllib.request.urlopen")
+    def test_read_timeout_becomes_network_error(self, mock_urlopen):
+        timeout = TimeoutError("The read operation timed out")
+        mock_urlopen.side_effect = timeout
+
+        with self.assertRaises(KrokiNetworkError) as ctx:
+            convert("graphviz", "digraph{}", "svg")
+
+        self.assertEqual("The read operation timed out", str(ctx.exception))
+        self.assertIs(timeout, ctx.exception.__cause__)
+
+    @patch("k3kroki.kroki.urllib.request.urlopen")
+    def test_incomplete_read_becomes_network_error(self, mock_urlopen):
+        incomplete = http.client.IncompleteRead(b"<svg", 10)
+        resp = _mock_urlopen_response()
+        resp.read.side_effect = incomplete
+        mock_urlopen.return_value = resp
+
+        with self.assertRaises(KrokiNetworkError) as ctx:
+            convert("graphviz", "digraph{}", "svg")
+
+        self.assertEqual("IncompleteRead(4 bytes read, 10 more expected)", str(ctx.exception))
+        self.assertIs(incomplete, ctx.exception.__cause__)
+
+
+class TestConvertToFileMocked(unittest.TestCase):
+    @patch("k3kroki.kroki.convert")
+    def test_writes_bytes_to_file(self, mock_convert):
+        mock_convert.return_value = b"<svg>test</svg>"
+
+        with tempfile.TemporaryDirectory() as tdir:
+            path = str(Path(tdir) / "out.svg")
+            convert_to_file("graphviz", "digraph{}", path)
+
+            self.assertEqual(Path(path).read_bytes(), b"<svg>test</svg>")
+            mock_convert.assert_called_once_with(
+                "graphviz", "digraph{}", "svg", base_url=DEFAULT_BASE_URL, timeout=30.0
+            )
+
+    @patch("k3kroki.kroki.convert")
+    def test_infers_format_from_extension(self, mock_convert):
+        mock_convert.return_value = b"\x89PNG"
+
+        with tempfile.TemporaryDirectory() as tdir:
+            for ext, fmt in _EXT_TO_FORMAT.items():
+                path = str(Path(tdir) / f"out{ext}")
+                convert_to_file("graphviz", "digraph{}", path)
+                self.assertEqual(mock_convert.call_args[0][2], fmt)
+
+    @patch("k3kroki.kroki.convert")
+    def test_explicit_format_overrides_extension(self, mock_convert):
+        mock_convert.return_value = b"data"
+
+        with tempfile.TemporaryDirectory() as tdir:
+            path = str(Path(tdir) / "out.svg")
+            convert_to_file("graphviz", "digraph{}", path, output_format="png")
+            self.assertEqual(mock_convert.call_args[0][2], "png")
+
+    def test_unknown_extension_raises(self):
+        with self.assertRaises(UnsupportedFormatError):
+            convert_to_file("graphviz", "digraph{}", "/tmp/out.bmp")
+
+
+class TestExceptionHierarchy(unittest.TestCase):
+    def test_unsupported_diagram_is_value_error(self):
+        self.assertTrue(issubclass(UnsupportedDiagramError, ValueError))
+        self.assertTrue(issubclass(UnsupportedDiagramError, k3kroki.KrokiError))
+
+    def test_unsupported_format_is_value_error(self):
+        self.assertTrue(issubclass(UnsupportedFormatError, ValueError))
+        self.assertTrue(issubclass(UnsupportedFormatError, k3kroki.KrokiError))
+
+    def test_api_error_is_kroki_error(self):
+        self.assertTrue(issubclass(KrokiAPIError, k3kroki.KrokiError))
+
+    def test_network_error_is_kroki_error(self):
+        self.assertTrue(issubclass(KrokiNetworkError, k3kroki.KrokiError))
+
+
+class TestImageOutput(unittest.TestCase):
+    """Tests that hit kroki.io and compare rendered images against expected outputs."""
+
+    @contextlib.contextmanager
+    def _skip_if_kroki_down(self):
+        """Skip, instead of fail, when kroki.io itself times out or returns 5xx."""
+        try:
+            yield
+        except KrokiNetworkError as e:
+            self.skipTest(f"kroki.io unreachable: {e}")
+        except KrokiAPIError as e:
+            if e.status_code < 500:
+                raise
+            self.skipTest(f"kroki.io failed: {e}")
+
+    def _assert_bitmap(self, diagram_type: str, fmt: str) -> None:
+        source = (DATA_DIR / diagram_type / "input").read_text()
+        with self._skip_if_kroki_down():
+            got_bytes = convert(diagram_type, source, fmt)
+
+        got_path = DATA_DIR / diagram_type / f"got.{fmt}"
+        got_path.write_bytes(got_bytes)
+        try:
+            sim = _image_ssim(DATA_DIR / diagram_type / f"want.{fmt}", got_path)
+            self.assertGreater(sim, 0.75)
+        finally:
+            got_path.unlink(missing_ok=True)
+
+    def test_convert_png(self):
+        for t in ("graphviz", "mermaid", "plantuml", "d2", "svgbob"):
+            with self.subTest(diagram_type=t):
+                self._assert_bitmap(t, "png")
+
+    def test_convert_webp(self):
+        for t in ("d2", "svgbob", "graphviz"):
+            with self.subTest(diagram_type=t):
+                self._assert_bitmap(t, "webp")
+
+    def test_convert_svg(self):
+        for t in ("graphviz", "mermaid", "plantuml", "d2", "svgbob"):
+            want_path = DATA_DIR / t / "want.svg"
+            if not want_path.exists():
+                continue
+
+            with self.subTest(diagram_type=t):
+                source = (DATA_DIR / t / "input").read_text()
+                with self._skip_if_kroki_down():
+                    got = convert(t, source, "svg")
+                self.assertIn(b"<svg", want_path.read_bytes())
+                self.assertIn(b"<svg", got)
+
+    def test_convert_to_file(self):
+        cases = [
+            ("graphviz", "png"),
+            ("mermaid", "png"),
+            ("plantuml", "png"),
+            ("d2", "svg"),
+            ("d2", "png"),
+            ("d2", "webp"),
+            ("svgbob", "svg"),
+            ("svgbob", "png"),
+            ("svgbob", "webp"),
+        ]
+        for diagram_type, fmt in cases:
+            want_path = DATA_DIR / diagram_type / f"want.{fmt}"
+            if not want_path.exists():
+                continue
+
+            with self.subTest(diagram_type=diagram_type, fmt=fmt):
+                source = (DATA_DIR / diagram_type / "input").read_text()
+                got_path = DATA_DIR / diagram_type / f"got.{fmt}"
+
+                with self._skip_if_kroki_down():
+                    convert_to_file(diagram_type, source, str(got_path), fmt)
+                try:
+                    if fmt == "svg":
+                        self.assertIn(b"<svg", got_path.read_bytes())
+                    else:
+                        sim = _image_ssim(want_path, got_path)
+                        self.assertGreater(sim, 0.75)
+                finally:
+                    got_path.unlink(missing_ok=True)