docs/mkdocs/scripts/figures/exception_map.py - third_party/json - Git at Google


            
            """Draws the exception id map of home/exceptions.md as an inline SVG into docs/images/exception_map.svg.


            The SVG is not an image: the page includes its text with `--8<-- "images/exception_map.svg"`, so it picks up the

            
            colours and fonts of the page (see the `nj-fig` rules in docs/css/brand.css and the `nj-exceptions-*` rules in

            
            docs/css/fig-exceptions.css). The file holds two drawings of the same map, a wide one and a narrow one for phones;

            
            the CSS shows one of them. Every id chip is a link to the `###` section of that id on the page, every family box a

            
            link to the family's `##` section.


            Run `python3 scripts/figures/exception_map.py` from docs/mkdocs after changing the drawing or after adding an

            
            exception section to home/exceptions.md (the ids are read from the page), and commit the generated file. In SVG text

            
            write the word JSON as `J&#8203;SON`, otherwise the abbreviation extension wraps it in an <abbr> and the text

            
            disappears.

            
            """

            
            import html

            
            import re

            
            from pathlib import Path


            OUT = Path(__file__).resolve().parents[2] / "docs" / "images"

            
            PAGE = Path(__file__).resolve().parents[2] / "docs" / "home" / "exceptions.md"

            
            P = "nj-exceptions-"


            # family name, id range label, anchor of the family section, extra member

            
            FAMILIES = [

            
                ("parse_error", "1xx", "parse-errors", "byte"),

            
                ("invalid_iterator", "2xx", "iterator-errors", None),

            
                ("type_error", "3xx", "type-errors", None),

            
                ("out_of_range", "4xx", "out-of-range", None),

            
                ("other_error", "5xx", "further-exceptions", None),

            
            ]


            # the chips show the id only; naming just some of them was confusing

            
            LABELS = {}


            GLOSSARY = Path(__file__).resolve().parents[2] / "includes" / "glossary.md"

            
            ABBRS = sorted(re.findall(r"^\*\[([^\]]+)\]:", GLOSSARY.read_text(), re.M), key=len, reverse=True)


            def noabbr(s):

            
                """Breaks every glossary abbreviation with a zero-width space, so the abbr extension leaves SVG text alone."""

            
                for a in ABBRS:

            
                    s = re.sub(r"(?<![\w&#])%s(?!\w)" % re.escape(a), a[0] + "&#8203;" + a[1:], s)

            
                return s


            def ids_on_page():

            
                found = {}

            
                for m in re.finditer(r"^### json\.exception\.(\w+)\.(\d+)\s*$", PAGE.read_text(), re.M):

            
                    found.setdefault(m.group(1), []).append(int(m.group(2)))

            
                return found


            def text_w(s, size):

            
                """Rough advance width of Inter at the given size (good enough to size chips)."""

            
                w = 0.0

            
                for c in s:

            
                    if c in "il.,:;'|![]()":

            
                        w += 0.28

            
                    elif c in " ft":

            
                        w += 0.32

            
                    elif c in "mwMW":

            
                        w += 0.85

            
                    elif c.isupper() or c.isdigit():

            
                        w += 0.64

            
                    else:

            
                        w += 0.55

            
                return w * size


            def esc(s):

            
                return html.escape(s, quote=True).replace("[", "&#91;").replace("]", "&#93;")


            MONO = 7.9    # JetBrains Mono advance at 13px

            
            CH = 28       # chip height

            
            GAP = 6


            def chip(x, y, fam, num):

            
                label = LABELS.get(num)

            
                w = 3 * MONO + 18 + (text_w(label, 12.5) + 10 if label else 0)

            
                anchor = "jsonexception%s%d" % (fam, num)

            
                aria = "json.exception.%s.%d%s" % (fam, num, (": " + label) if label else "")

            
                s = ['<a class="%schip%s" xlink:href="#%s" aria-label="%s">' % (P, " %schip--named" % P if label else "", anchor, esc(aria)),

            
                     '<rect x="%g" y="%g" width="%g" height="%d" rx="6"/>' % (x, y, w, CH),

            
                     '<text class="%sid" x="%g" y="%g">%d</text>' % (P, x + 9, y + CH / 2 + 4.5, num)]

            
                if label:

            
                    s.append('<text class="%slabel" x="%g" y="%g">%s</text>' % (P, x + 9 + 3 * MONO + 9, y + CH / 2 + 4.5, noabbr(esc(label))))

            
                s.append('</a>')

            
                return w, "".join(s)


            def flow(fam, nums, x0, x1, y0):

            
                """Places the chips of one family left to right, wrapping at x1. Returns (svg parts, bottom y)."""

            
                parts, x, y = [], x0, y0

            
                for n in nums:

            
                    w, _ = chip(0, 0, fam, n)

            
                    if x > x0 and x + w > x1:

            
                        x, y = x0, y + CH + GAP

            
                    _, s = chip(x, y, fam, n)

            
                    parts.append(s)

            
                    x += w + GAP

            
                return parts, y + CH


            def box(x, y, w, h, title, sub, href=None, cls=""):

            
                s = []

            
                if href:

            
                    s.append('<a class="%sfam" xlink:href="#%s" aria-label="%s">' % (P, href, esc(title + ", " + sub)))

            
                s.append('<rect class="%sbox%s" x="%g" y="%g" width="%g" height="%g" rx="7"/>' % (P, cls, x, y, w, h))

            
                s.append('<text class="%sname" x="%g" y="%g">%s</text>' % (P, x + 12, y + 22, noabbr(esc(title))))

            
                s.append('<text class="%ssub" x="%g" y="%g">%s</text>' % (P, x + 12, y + 41, noabbr(esc(sub))))

            
                if href:

            
                    s.append('</a>')

            
                return "".join(s)


            def drawing(W, narrow, suffix):

            
                global CH

            
                CH = 34 if narrow else 28   # larger touch targets on phones

            
                ids = ids_on_page()

            
                mid = "nj-exc-tri-" + suffix

            
                body = []

            
                trunk = 34

            
                # std::exception and json::exception

            
                body.append(box(12, 12, 190 if narrow else 200, 52, "std::exception", "C++ standard library base"))

            
                body.append('<line class="%sedge" x1="%d" y1="%d" x2="%d" y2="%d" marker-end="url(#%s)"/>' % (P, trunk, 104, trunk, 66, mid))

            
                body.append(box(12, 104, 250 if narrow else 300, 52, "json::exception", "id, what() \u00b7 catch-all"))

            
                y = 196

            
                last_branch = y

            
                fam_w = W - 64 - 12 if narrow else 214

            
                for fam, rng, href, member in FAMILIES:

            
                    nums = ids[fam]

            
                    sub = "%s \u00b7 %d ids" % (rng, len(nums)) + (" \u00b7 adds member %s" % member if member else "")

            
                    body.append('<line class="%sedge" x1="%d" y1="%d" x2="%d" y2="%d"/>' % (P, trunk, y + 26, 64, y + 26))

            
                    last_branch = y + 26

            
                    body.append(box(64, y, fam_w, 52, "json::" + fam, sub, href, " %sbox--fam" % P))

            
                    if narrow:

            
                        parts, bottom = flow(fam, nums, 64, W - 12, y + 52 + 10)

            
                    else:

            
                        parts, bottom = flow(fam, nums, 64 + fam_w + 16, W - 12, y + 12)

            
                    body += parts

            
                    y = max(bottom, y + 52) + 26

            
                # trunk from json::exception down to the last family, with the inheritance triangle at the top

            
                body.insert(0, '<line class="%sedge" x1="%d" y1="%d" x2="%d" y2="%d" marker-end="url(#%s)"/>' % (P, trunk, last_branch, trunk, 158, mid))

            
                H = y - 14

            
                defs = ('<defs><marker id="%s" viewBox="0 0 12 12" refX="11" refY="6" markerWidth="11" markerHeight="11" orient="auto">'

            
                        '<path class="%stri" d="M1 1 L11 6 L1 11 z"/></marker></defs>' % (mid, P))

            
                tid, did = "nj-exc-map-title-" + suffix, "nj-exc-map-desc-" + suffix

            
                total = sum(len(v) for v in ids.values())

            
                desc = ("Class tree: std::exception is the base of json::exception, which is the base of the five exception "

            
                        "families parse_error (ids 1xx), invalid_iterator (2xx), type_error (3xx), out_of_range (4xx) and "

            
                        "other_error (5xx). Each family lists the ids documented on this page, %d in total; every id links to "

            
                        "its section." % total)

            
                s = ['<svg class="nj-fig %smap %smap--%s" viewBox="0 0 %d %d" aria-labelledby="%s %s" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">'

            
                     % (P, P, "narrow" if narrow else "wide", W, H, tid, did),

            
                     '<title id="%s">Exception id map</title>' % tid,

            
                     '<desc id="%s">%s</desc>' % (did, noabbr(esc(desc))),

            
                     defs] + body + ['</svg>']

            
                return "\n".join(s)


            def main():

            
                out = drawing(760, False, "w") + "\n" + drawing(360, True, "n") + "\n"

            
                (OUT / "exception_map.svg").write_text(out)


            main()
	"""Draws the exception id map of home/exceptions.md as an inline SVG into docs/images/exception_map.svg.

	The SVG is not an image: the page includes its text with `--8<-- "images/exception_map.svg"`, so it picks up the
	colours and fonts of the page (see the `nj-fig` rules in docs/css/brand.css and the `nj-exceptions-*` rules in
	docs/css/fig-exceptions.css). The file holds two drawings of the same map, a wide one and a narrow one for phones;
	the CSS shows one of them. Every id chip is a link to the `###` section of that id on the page, every family box a
	link to the family's `##` section.

	Run `python3 scripts/figures/exception_map.py` from docs/mkdocs after changing the drawing or after adding an
	exception section to home/exceptions.md (the ids are read from the page), and commit the generated file. In SVG text
	write the word JSON as `JSON`, otherwise the abbreviation extension wraps it in an <abbr> and the text
	disappears.
	"""
	import html
	import re
	from pathlib import Path

	OUT = Path(__file__).resolve().parents[2] / "docs" / "images"
	PAGE = Path(__file__).resolve().parents[2] / "docs" / "home" / "exceptions.md"
	P = "nj-exceptions-"

	# family name, id range label, anchor of the family section, extra member
	FAMILIES = [
	("parse_error", "1xx", "parse-errors", "byte"),
	("invalid_iterator", "2xx", "iterator-errors", None),
	("type_error", "3xx", "type-errors", None),
	("out_of_range", "4xx", "out-of-range", None),
	("other_error", "5xx", "further-exceptions", None),
	]

	# the chips show the id only; naming just some of them was confusing
	LABELS = {}


	GLOSSARY = Path(__file__).resolve().parents[2] / "includes" / "glossary.md"
	ABBRS = sorted(re.findall(r"^\*\[([^\]]+)\]:", GLOSSARY.read_text(), re.M), key=len, reverse=True)


	def noabbr(s):
	"""Breaks every glossary abbreviation with a zero-width space, so the abbr extension leaves SVG text alone."""
	for a in ABBRS:
	s = re.sub(r"(?<![\w&#])%s(?!\w)" % re.escape(a), a[0] + "" + a[1:], s)
	return s


	def ids_on_page():
	found = {}
	for m in re.finditer(r"^### json\.exception\.(\w+)\.(\d+)\s*$", PAGE.read_text(), re.M):
	found.setdefault(m.group(1), []).append(int(m.group(2)))
	return found


	def text_w(s, size):
	"""Rough advance width of Inter at the given size (good enough to size chips)."""
	w = 0.0
	for c in s:
	if c in "il.,:;'\|![]()":
	w += 0.28
	elif c in " ft":
	w += 0.32
	elif c in "mwMW":
	w += 0.85
	elif c.isupper() or c.isdigit():
	w += 0.64
	else:
	w += 0.55
	return w * size


	def esc(s):
	return html.escape(s, quote=True).replace("[", "[").replace("]", "]")


	MONO = 7.9 # JetBrains Mono advance at 13px
	CH = 28 # chip height
	GAP = 6


	def chip(x, y, fam, num):
	label = LABELS.get(num)
	w = 3 * MONO + 18 + (text_w(label, 12.5) + 10 if label else 0)
	anchor = "jsonexception%s%d" % (fam, num)
	aria = "json.exception.%s.%d%s" % (fam, num, (": " + label) if label else "")
	s = ['<a class="%schip%s" xlink:href="#%s" aria-label="%s">' % (P, " %schip--named" % P if label else "", anchor, esc(aria)),
	'<rect x="%g" y="%g" width="%g" height="%d" rx="6"/>' % (x, y, w, CH),
	'<text class="%sid" x="%g" y="%g">%d</text>' % (P, x + 9, y + CH / 2 + 4.5, num)]
	if label:
	s.append('<text class="%slabel" x="%g" y="%g">%s</text>' % (P, x + 9 + 3 * MONO + 9, y + CH / 2 + 4.5, noabbr(esc(label))))
	s.append('</a>')
	return w, "".join(s)


	def flow(fam, nums, x0, x1, y0):
	"""Places the chips of one family left to right, wrapping at x1. Returns (svg parts, bottom y)."""
	parts, x, y = [], x0, y0
	for n in nums:
	w, _ = chip(0, 0, fam, n)
	if x > x0 and x + w > x1:
	x, y = x0, y + CH + GAP
	_, s = chip(x, y, fam, n)
	parts.append(s)
	x += w + GAP
	return parts, y + CH


	def box(x, y, w, h, title, sub, href=None, cls=""):
	s = []
	if href:
	s.append('<a class="%sfam" xlink:href="#%s" aria-label="%s">' % (P, href, esc(title + ", " + sub)))
	s.append('<rect class="%sbox%s" x="%g" y="%g" width="%g" height="%g" rx="7"/>' % (P, cls, x, y, w, h))
	s.append('<text class="%sname" x="%g" y="%g">%s</text>' % (P, x + 12, y + 22, noabbr(esc(title))))
	s.append('<text class="%ssub" x="%g" y="%g">%s</text>' % (P, x + 12, y + 41, noabbr(esc(sub))))
	if href:
	s.append('</a>')
	return "".join(s)


	def drawing(W, narrow, suffix):
	global CH
	CH = 34 if narrow else 28 # larger touch targets on phones
	ids = ids_on_page()
	mid = "nj-exc-tri-" + suffix
	body = []
	trunk = 34
	# std::exception and json::exception
	body.append(box(12, 12, 190 if narrow else 200, 52, "std::exception", "C++ standard library base"))
	body.append('<line class="%sedge" x1="%d" y1="%d" x2="%d" y2="%d" marker-end="url(#%s)"/>' % (P, trunk, 104, trunk, 66, mid))
	body.append(box(12, 104, 250 if narrow else 300, 52, "json::exception", "id, what() \u00b7 catch-all"))
	y = 196
	last_branch = y
	fam_w = W - 64 - 12 if narrow else 214
	for fam, rng, href, member in FAMILIES:
	nums = ids[fam]
	sub = "%s \u00b7 %d ids" % (rng, len(nums)) + (" \u00b7 adds member %s" % member if member else "")
	body.append('<line class="%sedge" x1="%d" y1="%d" x2="%d" y2="%d"/>' % (P, trunk, y + 26, 64, y + 26))
	last_branch = y + 26
	body.append(box(64, y, fam_w, 52, "json::" + fam, sub, href, " %sbox--fam" % P))
	if narrow:
	parts, bottom = flow(fam, nums, 64, W - 12, y + 52 + 10)
	else:
	parts, bottom = flow(fam, nums, 64 + fam_w + 16, W - 12, y + 12)
	body += parts
	y = max(bottom, y + 52) + 26
	# trunk from json::exception down to the last family, with the inheritance triangle at the top
	body.insert(0, '<line class="%sedge" x1="%d" y1="%d" x2="%d" y2="%d" marker-end="url(#%s)"/>' % (P, trunk, last_branch, trunk, 158, mid))
	H = y - 14
	defs = ('<defs><marker id="%s" viewBox="0 0 12 12" refX="11" refY="6" markerWidth="11" markerHeight="11" orient="auto">'
	'<path class="%stri" d="M1 1 L11 6 L1 11 z"/></marker></defs>' % (mid, P))
	tid, did = "nj-exc-map-title-" + suffix, "nj-exc-map-desc-" + suffix
	total = sum(len(v) for v in ids.values())
	desc = ("Class tree: std::exception is the base of json::exception, which is the base of the five exception "
	"families parse_error (ids 1xx), invalid_iterator (2xx), type_error (3xx), out_of_range (4xx) and "
	"other_error (5xx). Each family lists the ids documented on this page, %d in total; every id links to "
	"its section." % total)
	s = ['<svg class="nj-fig %smap %smap--%s" viewBox="0 0 %d %d" aria-labelledby="%s %s" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">'
	% (P, P, "narrow" if narrow else "wide", W, H, tid, did),
	'<title id="%s">Exception id map</title>' % tid,
	'<desc id="%s">%s</desc>' % (did, noabbr(esc(desc))),
	defs] + body + ['</svg>']
	return "\n".join(s)


	def main():
	out = drawing(760, False, "w") + "\n" + drawing(360, True, "n") + "\n"
	(OUT / "exception_map.svg").write_text(out)


	main()