52def annotate_debug_info(page: Page, new_doc: pp.PdfDocument = None, index: int = 0) -> pp.PdfDocument:
 53    """
 54    Copies each page into a new or existing PDF document and overlays the internal information on top of the content.
 55    - Renders the bounding boxes in RED and origins in BLACK of all characters.
 56    - Renders the bounding boxes of web links in BLUE GREEN.
 57    - Renders the bounding boxes of object links in YELLOW GREEN.
 58    - Renders all graphics paths in BLUE.
 59    - Renders the bounding boxes of computed graphics clusters in CYAN.
 60
 61    :param page: The page to be annotated.
 62    :param new_doc: The PDF document to copy the page to. If not provided, a new document is created.
 63    :param index: The index of the page in the new document.
 64    :return: The new document with the annotated page added.
 65    """
 66    _, height = page.width, page.height
 67
 68    if new_doc is None:
 69        new_doc = pp.raw.FPDF_CreateNewDocument()
 70    # copy page over to new doc
 71    assert pp.raw.FPDF_ImportPages(new_doc, page.pdf, str(page.number).encode("ascii"), index)
 72    new_page = pp.raw.FPDF_LoadPage(new_doc, index)
 73    rotation = page.rotation
 74
 75    for path in page.paths:
 76        p0 = path.points[0]
 77        if rotation:
 78            obj = pp.raw.FPDFPageObj_CreateNewPath(height - p0.y, p0.x)
 79        else:
 80            obj = pp.raw.FPDFPageObj_CreateNewPath(p0.x, p0.y)
 81        assert pp.raw.FPDFPageObj_SetStrokeColor(obj, 0, 0, 0xFF, 0xC0)
 82        assert pp.raw.FPDFPageObj_SetStrokeWidth(obj, 0.25)
 83        assert pp.raw.FPDFPageObj_SetLineJoin(obj, pp.raw.FPDF_LINEJOIN_ROUND)
 84        assert pp.raw.FPDFPageObj_SetLineCap(obj, pp.raw.FPDF_LINECAP_ROUND)
 85        assert pp.raw.FPDFPath_SetDrawMode(obj, 0, True)
 86        for point in path.points[1:]:
 87            if point.type == path.Type.MOVE:
 88                if rotation:
 89                    assert pp.raw.FPDFPath_MoveTo(obj, height - point.y, point.x)
 90                else:
 91                    assert pp.raw.FPDFPath_MoveTo(obj, point.x, point.y)
 92            else:
 93                if rotation:
 94                    assert pp.raw.FPDFPath_LineTo(obj, height - point.y, point.x)
 95                else:
 96                    assert pp.raw.FPDFPath_LineTo(obj, point.x, point.y)
 97        pp.raw.FPDFPage_InsertObject(new_page, obj)
 98
 99    for bbox, _ in page.graphic_clusters():
100        _rect(new_page, rotation, bbox, width=2, stroke=0x00FFFF)
101
102    for link in page.objlinks:
103        _rect(new_page, rotation, link.bbox, width=0.75, stroke=0x9ACD32)
104
105    for link in page.weblinks:
106        for bbox in link.bboxes:
107            _rect(new_page, rotation, bbox, width=0.75, stroke=0x00FF00)
108
109    for char in page.chars:
110        color = 0x0000FF
111        if char.bbox.width:
112            _rect(new_page, rotation, char.bbox, width=0.5, stroke=0xFF0000)
113            _vline(
114                new_page,
115                rotation,
116                char.bbox.midpoint.x,
117                char.bbox.midpoint.y - 1,
118                char.bbox.midpoint.y + 1,
119                width=0.25,
120                stroke=0xFF0000,
121            )
122            _hline(
123                new_page,
124                rotation,
125                char.bbox.midpoint.y,
126                char.bbox.midpoint.x - 1,
127                char.bbox.midpoint.x + 1,
128                width=0.25,
129                stroke=0xFF0000,
130            )
131            color = 0x000000
132        _vline(new_page, rotation, char.origin.x, char.origin.y - 1, char.origin.y + 1, width=0.25, stroke=color)
133        _hline(new_page, rotation, char.origin.y, char.origin.x - 1, char.origin.x + 1, width=0.25, stroke=color)
134
135    assert pp.raw.FPDFPage_GenerateContent(new_page)
136    pp.raw.FPDF_ClosePage(new_page)
137    return new_doc

 31class Document(pp.PdfDocument):
 32    """
 33    The PDF document is the root of the entire data structure and provides
 34    access to PDF metadata, the table of contents, as well as individual
 35    pages.
 36
 37    You should extend from this class for a specific vendor to provide the
 38    correct page class from `page()` function.
 39
 40    This class is a convenience wrapper with caching around the high-level APIs
 41    of pypdfium.
 42    """
 43
 44    def __init__(self, path: Path, autoclose: bool = False):
 45        """
 46        :param path: Path to the PDF to open.
 47        """
 48        path = Path(path)
 49        self.name: str = path.stem
 50        """Stem of the document file name"""
 51        super().__init__(path, autoclose=autoclose)
 52        self._path = path
 53        self._bbox_cache = defaultdict(dict)
 54        _LOGGER.debug(f"Loading: {path}")
 55
 56    @cached_property
 57    def metadata(self) -> dict[str, str]:
 58        """The PDF metadata dictionary."""
 59        return self.get_metadata_dict()
 60
 61    @property
 62    def destinations(self) -> Iterator[tuple[int, str]]:
 63        """Yields (page 0-index, named destination) of the whole document."""
 64        for ii in range(pp.raw.FPDF_CountNamedDests(self)):
 65            length = pp.raw.FPDF_GetNamedDest(self, ii, 0, 0)
 66            clength = ctypes.c_long(length)
 67            cbuffer = ctypes.create_string_buffer(length * 2)
 68            dest = pp.raw.FPDF_GetNamedDest(self, ii, cbuffer, clength)
 69            name = cbuffer.raw[: clength.value * 2].decode("utf-16-le").rstrip("\x00")
 70            page = pp.raw.FPDFDest_GetDestPageIndex(self, dest)
 71            yield (page, name)
 72
 73    @cached_property
 74    def toc(self) -> list[pp.PdfOutlineItem]:
 75        """
 76        The table of content as a sorted list of outline items ensuring item has
 77        a page index by reusing the last one.
 78        """
 79        tocs = set()
 80        # Sometimes the TOC contains duplicates so we must use a set
 81        last_page_index = 0
 82        for toc in self.get_toc():
 83            outline = _OutlineItem(
 84                toc.level,
 85                toc.title,
 86                toc.is_closed,
 87                toc.n_kids,
 88                toc.page_index or last_page_index,
 89                toc.view_mode,
 90                toc.view_pos,
 91            )
 92            last_page_index = toc.page_index or last_page_index
 93            tocs.add(outline)
 94        return list(sorted(list(tocs), key=lambda o: (o.page_index, o.level, o.title)))
 95
 96    @cached_property
 97    def identifier_permanent(self) -> str:
 98        """The permanent file identifier."""
 99        return self.get_identifier(pp.raw.FILEIDTYPE_PERMANENT)
100
101    @cached_property
102    def identifier_changing(self) -> str:
103        """The changing file identifier."""
104        return self.get_identifier(pp.raw.FILEIDTYPE_CHANGING)
105
106    @cached_property
107    def page_count(self) -> int:
108        """The number of pages in the document."""
109        return pp.raw.FPDF_GetPageCount(self)
110
111    @cache
112    def page(self, index: int) -> Page:
113        """
114        :param index: 0-indexed page number.
115        :return: the page object for the index.
116        """
117        assert index < self.page_count
118        return Page(self, index)
119
120    def pages(self, numbers: Iterable[int] = None) -> Iterator[Page]:
121        """
122        :param numbers: an iterable range of page numbers (0-indexed!).
123                        If `None`, then the whole page range is used.
124        :return: yields each page in the range.
125        """
126        if numbers is None:
127            numbers = range(self.page_count)
128        for ii in numbers:
129            if 0 <= ii < self.page_count:
130                yield self.page(ii)
131
132    def __repr__(self) -> str:
133        return f"Doc({self.name})"

 24class Page(pp.PdfPage):
 25    """
 26    This class provides low-level access to graphics and characters of the page.
 27    It also fixes missing bounding boxes for rotates characters on page load,
 28    as well as allow searching for characters in an area instead of just text.
 29    """
 30
 31    def __init__(self, document: "modm_data.pdf.Document", index: int):  # noqa: F821
 32        """
 33        :param document: a PDF document.
 34        :param index: 0-index page number.
 35        """
 36        self.index = index
 37        """0-index page number."""
 38        self.number = index + 1
 39        """1-index page number."""
 40
 41        super().__init__(pp.raw.FPDF_LoadPage(document, index), document, document.formenv)
 42        self._links = None
 43        self._weblinks = None
 44        self._linked = False
 45
 46        _LOGGER.debug(f"Loading: {index}")
 47
 48        self._text = self.get_textpage()
 49        self._linkpage = pp.raw.FPDFLink_LoadWebLinks(self._text)
 50        self._structtree = pp.raw.FPDF_StructTree_GetForPage(self)
 51        # close them in reverse order
 52        weakref.finalize(self, pp.raw.FPDF_StructTree_Close, self._structtree)
 53        weakref.finalize(self, pp.raw.FPDFLink_CloseWebLinks, self._linkpage)
 54
 55        self._fix_bboxes()
 56
 57    @cached_property
 58    def label(self) -> str:
 59        """The page label."""
 60        return self.pdf.get_page_label(self.index)
 61
 62    @cached_property
 63    def width(self) -> float:
 64        """The page width."""
 65        return self.get_width()
 66
 67    @cached_property
 68    def height(self) -> float:
 69        """The page height."""
 70        return self.get_height()
 71
 72    @cached_property
 73    def rotation(self) -> int:
 74        """The page rotation in degrees."""
 75        return self.get_rotation()
 76
 77    @cached_property
 78    def bbox(self) -> Rectangle:
 79        """The page bounding box."""
 80        return Rectangle(*self.get_bbox())
 81
 82    @cached_property
 83    def char_count(self) -> int:
 84        """The total count of characters."""
 85        return self._text.count_chars()
 86
 87    @cache
 88    def char(self, index: int) -> Character:
 89        """:return: The character at the 0-index."""
 90        return Character(self, index)
 91
 92    @property
 93    def chars(self) -> Iterator[Character]:
 94        """Yields all characters."""
 95        for ii in range(self.char_count):
 96            yield self.char(ii)
 97
 98    @cached_property
 99    def objlinks(self) -> list[ObjLink]:
100        """All object links."""
101        links = []
102        pos = ctypes.c_int(0)
103        link = pp.raw.FPDF_LINK()
104        while pp.raw.FPDFLink_Enumerate(self, pos, link):
105            links.append(ObjLink(self, link))
106        return links
107
108    @cached_property
109    def weblinks(self) -> list[WebLink]:
110        """All web links."""
111        links = []
112        for ii in range(pp.raw.FPDFLink_CountWebLinks(self._linkpage)):
113            links.append(WebLink(self, ii))
114        return links
115
116    def chars_in_area(self, area: Rectangle) -> list[Character]:
117        """
118        :param area: area to search for character in.
119        :return: All characters found in the area.
120        """
121        found = []
122        # We perform binary searches of the lower and upper y-positions first
123        # lines are ordered by y-position
124        ypositions = list(self._charlines.keys())
125        y_bottom = bisect_left(ypositions, area.bottom)
126        y_top = bisect_right(ypositions, area.top, lo=y_bottom)
127
128        # Then for every line we do another binary search for left and right
129        for ypos in ypositions[y_bottom:y_top]:
130            chars = self._charlines[ypos]
131            x_left = bisect_left(chars, area.left, key=lambda c: c.bbox.midpoint.x)
132            x_right = bisect_right(chars, area.right, lo=x_left, key=lambda c: c.bbox.midpoint.x)
133            # Finally we add all these characters
134            found.extend(chars[x_left:x_right])
135        return found
136
137    def text_in_area(self, area: Rectangle) -> str:
138        """
139        :param area: area to search for text in.
140        :return: Only the text found in the area.
141        """
142        return self._text.get_text_bounded(area.left, area.bottom, area.right, area.top)
143
144    @property
145    def structures(self) -> Iterator[Structure]:
146        """The PDF/UA tags."""
147        count = pp.raw.FPDF_StructTree_CountChildren(self._structtree)
148        for ii in range(count):
149            child = pp.raw.FPDF_StructTree_GetChildAtIndex(self._structtree, ii)
150            yield Structure(self, child)
151
152    def find(self, string: str, case_sensitive: bool = True) -> Iterator[Character]:
153        """
154        Searches for a match string as whole, consecutive words and yields the
155        characters.
156
157        :param string: The search string.
158        :param case_sensitive: Ignore case if false.
159        :return: yields the characters found.
160        """
161        searcher = self._text.search(string, match_case=case_sensitive, match_whole_word=True, consecutive=True)
162        while idx := searcher.get_next():
163            chars = [self.char(ii) for ii in range(idx[0], idx[0] + idx[1])]
164            yield chars
165
166    @cached_property
167    def paths(self) -> list[Path]:
168        """All paths."""
169        return [Path(o) for o in self.get_objects([pp.raw.FPDF_PAGEOBJ_PATH])]
170
171    @cached_property
172    def images(self) -> list[Image]:
173        """All images."""
174        return [Image(o) for o in self.get_objects([pp.raw.FPDF_PAGEOBJ_IMAGE])]
175
176    def graphic_clusters(
177        self, predicate: Callable[[Path | Image], bool] = None, absolute_tolerance: float = None
178    ) -> list[tuple[Rectangle, list[Path]]]:
179        if absolute_tolerance is None:
180            absolute_tolerance = min(self.width, self.height) * 0.01
181
182        # First collect all vertical regions
183        filtered_paths = []
184        for path in self.paths:
185            if predicate is None or predicate(path):
186                filtered_paths.append(path)
187        for image in self.images:
188            if predicate is None or predicate(image):
189                filtered_paths.append(image)
190
191        regions = []
192        for path in sorted(filtered_paths, key=lambda path: path.bbox.y):
193            for reg in regions:
194                if reg.overlaps(path.bbox.bottom, path.bbox.top, absolute_tolerance):
195                    # They overlap, so merge them
196                    reg.v0 = min(reg.v0, path.bbox.bottom)
197                    reg.v1 = max(reg.v1, path.bbox.top)
198                    reg.objs.append(path)
199                    break
200            else:
201                regions.append(Region(path.bbox.bottom, path.bbox.top, path))
202
203        # Now collect horizontal region inside each vertical region
204        for yreg in regions:
205            for path in sorted(filtered_paths, key=lambda path: path.bbox.x):
206                # check if horizontal line is contained in vregion
207                if yreg.contains(path.bbox.y, absolute_tolerance):
208                    for xreg in yreg.subregions:
209                        if xreg.overlaps(path.bbox.left, path.bbox.right, absolute_tolerance):
210                            # They overlap so merge them
211                            xreg.v0 = min(xreg.v0, path.bbox.left)
212                            xreg.v1 = max(xreg.v1, path.bbox.right)
213                            xreg.objs.append(path)
214                            break
215                    else:
216                        yreg.subregions.append(Region(path.bbox.left, path.bbox.right, path))
217
218        clusters = []
219        for yreg in regions:
220            for xreg in yreg.subregions:
221                if len(yreg.subregions) > 1:
222                    # Strip down the height again for subregions
223                    y0, y1 = 1e9, 0
224                    for path in xreg.objs:
225                        y0 = min(y0, path.bbox.bottom)
226                        y1 = max(y1, path.bbox.top)
227                else:
228                    y0, y1 = yreg.v0, yreg.v1
229                bbox = Rectangle(xreg.v0, y0, xreg.v1, y1)
230                clusters.append((bbox, xreg.objs))
231
232        return sorted(clusters, key=lambda c: (-c[0].y, c[0].x))
233
234    def _link_characters(self):
235        if self._linked:
236            return
237        # The in-document links only gives us rectangles and we must find the
238        # linked chars ourselves
239        for link in self.objlinks:
240            for char in self.chars_in_area(link.bbox):
241                char.objlink = link
242        # The weblinks give you an explicit char range, very convenient
243        for link in self.weblinks:
244            for ii in range(*link.range):
245                self.char(ii).weblink = link
246        self._linked = True
247
248    @cached_property
249    def _charlines(self):
250        charlines = defaultdict(list)
251        for char in self.chars:
252            charlines[round(char.bbox.midpoint.y, 1)].append(char)
253
254        orderedchars = OrderedDict.fromkeys(sorted(charlines))
255        for ypos, chars in charlines.items():
256            orderedchars[ypos] = sorted(chars, key=lambda c: c.bbox.midpoint.x)
257
258        return orderedchars
259
260    def _fix_bboxes(self):
261        def _key(char):
262            height = round(char.tbbox.height, 1)
263            width = round(char.tbbox.width, 1)
264            return f"{char.font} {char.unicode} {height} {width}"
265
266        fix_chars = []
267        for char in self.chars:
268            if not char._bbox.width or not char._bbox.height:
269                if char._rotation:
270                    fix_chars.append(char)
271                elif char.unicode not in {0xA, 0xD}:
272                    fix_chars.append(char)
273            elif char.unicode not in {0xA, 0xD} and not char._rotation and _key(char) not in self.pdf._bbox_cache:
274                bbox = char._bbox.translated(-char.origin).rotated(self.rotation + char._rotation)
275                self.pdf._bbox_cache[_key(char)] = (char, bbox)
276                # print("->", _key(char), char.descr(), char.height, char.rotation, char._rotation, self.rotation)
277        for char in fix_chars:
278            bbox = self.pdf._bbox_cache.get(_key(char))
279            if bbox is not None:
280                # print("<-", char.descr(), char._rotation, char.rotation, char.height)
281                _, bbox = bbox
282                bbox = bbox.rotated(-self.rotation - char._rotation).translated(char.origin)
283                char._bbox = bbox
284            elif char.unicode not in {0x20, 0xA, 0xD}:
285                _LOGGER.debug(f"Unable to fix bbox for {char.descr()}!")

 13class Character:
 14    """
 15    Each character on the PDF page is represented by a character object,
 16    describing exactly where and how to render the associated glyph.
 17
 18    While there are font flags, PDF files typically use entirely different fonts
 19    to render normal, bold, and italic characters.
 20
 21    The character's loose bounding box may not always be available, since it
 22    must be explicitly provided by the font. The tight bounding box is only
 23    available as long as the glyph is renderable, so a space character may have
 24    a loose, but not a tight bounding box, or none at all.
 25    """
 26
 27    class RenderMode(Enum):
 28        """Tells the PDF viewer how to render this character glyph."""
 29
 30        UNKNOWN = -1
 31        FILL = 0
 32        STROKE = 1
 33        FILL_STROKE = 2
 34        INVISIBLE = 3
 35        FILL_CLIP = 4
 36        STROKE_CLIP = 5
 37        FILL_STROKE_CLIP = 6
 38        CLIP = 7
 39
 40    def __init__(self, page: "modm_data.pdf.page.Page", index: int):  # noqa: F821
 41        """
 42        :param page: The page containing the character.
 43        :param index: The index of the character.
 44        """
 45        self._page = page
 46        self._text = page._text
 47        self._index = index
 48        self._font = None
 49        self._rotation = int(math.degrees(pp.raw.FPDFText_GetCharAngle(self._text, self._index)))
 50
 51        self.unicode: int = pp.raw.FPDFText_GetUnicode(self._text, self._index)
 52        """The unicode value of the character."""
 53        self.objlink: "modm_data.pdf.link.ObjLink" = None  # noqa: F821
 54        """The object link of this character or `None`"""
 55        self.weblink: "modm_data.pdf.link.WebLink" = None  # noqa: F821
 56        """The web link of this character or `None`"""
 57
 58        bbox = Rectangle(*self._text.get_charbox(self._index, loose=True))
 59        if self._page.rotation:
 60            bbox = Rectangle(bbox.p0.y, self._page.height - bbox.p1.x, bbox.p1.y, self._page.height - bbox.p0.x)
 61        self._bbox = bbox
 62
 63    def _font_flags(self) -> tuple[str, int]:
 64        if self._font is None:
 65            font = ctypes.create_string_buffer(255)
 66            flags = ctypes.c_int()
 67            pp.raw.FPDFText_GetFontInfo(self._text, self._index, font, 255, flags)
 68            self._font = (font.value.decode("utf-8"), flags.value)
 69        return self._font
 70
 71    @property
 72    def char(self) -> str:
 73        """The printable string of the unicode value."""
 74        char = chr(self.unicode)
 75        return char if char.isprintable() else ""
 76
 77    @cached_property
 78    def origin(self) -> Point:
 79        """The origin of the character."""
 80        x, y = ctypes.c_double(), ctypes.c_double()
 81        assert pp.raw.FPDFText_GetCharOrigin(self._text, self._index, x, y)
 82        if self._page.rotation:
 83            return Point(y.value, self._page.height - x.value)
 84        return Point(x.value, y.value)
 85
 86    @cached_property
 87    def width(self) -> float:
 88        """The width of the character's bounding box."""
 89        if self.rotation:
 90            return self.bbox.height
 91        return self.bbox.width
 92
 93    @cached_property
 94    def height(self) -> float:
 95        """The height of the character's bounding box."""
 96        if self.rotation:
 97            return self.bbox.width
 98        return self.bbox.height
 99
100    @cached_property
101    def tbbox(self) -> Rectangle:
102        """The tight bounding box of the character."""
103        tbbox = Rectangle(*self._text.get_charbox(self._index))
104        if self._page.rotation:
105            tbbox = Rectangle(tbbox.p0.y, self._page.height - tbbox.p1.x, tbbox.p1.y, self._page.height - tbbox.p0.x)
106        return tbbox
107
108    @property
109    def bbox(self) -> Rectangle:
110        """
111        The loose bounding box of the character.
112        .. note::
113            If the loose bounding box is not available, the tight bounding box
114            is used instead.
115        """
116        if not self._bbox.width or not self._bbox.height:
117            return self.tbbox
118        return self._bbox
119
120    @cached_property
121    def twidth(self) -> float:
122        """The width of the character's tight bounding box."""
123        return self.tbbox.width
124
125    @cached_property
126    def theight(self) -> float:
127        """The height of the character's tight bounding box."""
128        return self.tbbox.height
129
130    @cached_property
131    def render_mode(self) -> RenderMode:
132        """The render mode of the character."""
133        return Character.RenderMode(pp.raw.FPDFText_GetTextRenderMode(self._text, self._index))
134
135    @cached_property
136    def rotation(self) -> int:
137        """The rotation of the character in degrees modulo 360."""
138        # Special case for vertical text in rotated pages
139        if self._page.rotation == 90 and self._rotation == 0 and self.unicode not in {0x20, 0xA, 0xD}:
140            return 90
141        if self._page.rotation and self._rotation:
142            return (self._page.rotation + self._rotation) % 360
143        return self._rotation
144
145    @cached_property
146    def size(self) -> float:
147        """The font size of the character."""
148        return pp.raw.FPDFText_GetFontSize(self._text, self._index)
149
150    @cached_property
151    def weight(self) -> int:
152        """The font weight of the character."""
153        return pp.raw.FPDFText_GetFontWeight(self._text, self._index)
154
155    @cached_property
156    def fill(self) -> int:
157        """The fill color of the character."""
158        r, g, b, a = ctypes.c_uint(), ctypes.c_uint(), ctypes.c_uint(), ctypes.c_uint()
159        pp.raw.FPDFText_GetFillColor(self._text, self._index, r, g, b, a)
160        return r.value << 24 | g.value << 16 | b.value << 8 | a.value
161
162    @cached_property
163    def stroke(self) -> int:
164        """The stroke color of the character."""
165        r, g, b, a = ctypes.c_uint(), ctypes.c_uint(), ctypes.c_uint(), ctypes.c_uint()
166        pp.raw.FPDFText_GetStrokeColor(self._text, self._index, r, g, b, a)
167        return r.value << 24 | g.value << 16 | b.value << 8 | a.value
168
169    @cached_property
170    def font(self) -> str:
171        """The font name of the character."""
172        return self._font_flags()[0]
173
174    @cached_property
175    def flags(self) -> int:
176        """The font flags of the character."""
177        return self._font_flags()[1]
178
179    def descr(self) -> str:
180        """Human-readable description of the character for debugging."""
181        char = chr(self.unicode)
182        if not char.isprintable():
183            char = hex(self.unicode)
184        return (
185            f"Chr({char}, {self.size}, {self.weight}, {self.rotation}, "
186            f"{self.render_mode}, {self.font}, {hex(self.flags)}, "
187            f"{self.fill}, {self.stroke}, {repr(self.bbox)})"
188        )
189
190    def __str__(self) -> str:
191        return self.char
192
193    def __repr__(self) -> str:
194        char = chr(self.unicode)
195        escape = {0xA: "\\n", 0xD: "\\r", 0x9: "\\t", 0x20: "␣"}
196        char = escape.get(self.unicode, char if char.isprintable() else hex(self.unicode))
197        return char