pygments_better_html 0.1.6__py3-none-any.whl

pygments_better_html/__init__.py

@@ -0,0 +1,261 @@
+# -*- coding: utf-8 -*-
+"""Better HTML formatter for Pygments.
+
+Copyright © 2020-2026, Chris Warrick.
+License: 3-clause BSD.
+Portions copyright © 2006-2022, the Pygments authors. (2-clause BSD).
+"""
+
+__all__ = ["BetterHtmlFormatter"]
+__version__ = "0.1.6"
+
+import enum
+import re
+import warnings
+
+from pygments.formatters.html import HtmlFormatter
+
+MANY_SPACES = re.compile("(  +)")
+
+
+def _sp_to_nbsp(m):
+    return " " * (m.end() - m.start())
+
+
+class BetterLinenos(enum.Enum):
+    TABLE = "table"
+    OL = "ol"
+
+
+class BetterHtmlFormatter(HtmlFormatter):
+    r"""
+    Format tokens as HTML 4 ``<span>`` tags, with alternate formatting styles.
+
+    * ``linenos = 'table'`` renders each line of code in a separate table row
+    * ``linenos = 'ol'`` renders each line in a <li> element (inside <ol>)
+
+    Both options allow word wrap and don't include line numbers when copying.
+    """
+
+    name = "HTML"
+    aliases = ["html"]
+    filenames = ["*.html", "*.htm"]
+
+    def __init__(self, **options):
+        """Initialize the formatter."""
+        super().__init__(**options)
+        self.linenos_name = self.options.get("linenos", "table")
+        if self.linenos_name is False:
+            self.linenos_val = False
+            self.linenos = 0
+        elif self.linenos_name is True:
+            self.linenos_name = "table"
+        if self.linenos_name is not False:
+            self.linenos_val = BetterLinenos(self.linenos_name)
+            self.linenos = 2 if self.linenos_val == BetterLinenos.OL else 1
+
+    def get_style_defs(self, arg=None, wrapper_classes=None):
+        """Generate CSS style definitions.
+
+        Return CSS style definitions for the classes produced by the current
+        highlighting style. ``arg`` can be a string or list of selectors to
+        insert before the token type classes. ``wrapper_classes`` are a list of
+        classes for the wrappers, defaults to the ``cssclass`` option.
+        """
+        base = super().get_style_defs(arg)
+        new_styles = (
+            ("{0} table, {0} tr, {0} td", "border-spacing: 0; border-collapse: separate; padding: 0"),
+            ("{0} pre", "white-space: pre-wrap; line-height: normal"),
+            (
+                "{0}table td.linenos",
+                "vertical-align: top; padding-left: 10px; padding-right: 10px; user-select: none; -webkit-user-select: none",
+            ),
+            (
+                "{0}table td.linenos .special",
+                "padding: 0",
+            ),
+            # Hack for Safari (user-select does not affect copy-paste)
+            ("{0}table td.linenos code:before", "content: attr(data-line-number)"),
+            ("{0}table td.code", "overflow-wrap: normal; border-collapse: collapse"),
+            (
+                "{0}table td.code code",
+                "overflow: unset; border: none; padding: 0; margin: 0; white-space: pre-wrap; line-height: unset; background: none",
+            ),
+            ("{0} .lineno.nonumber", "list-style: none"),
+        )
+        new_styles_code = []
+        if wrapper_classes is None:
+            wrapper_classes = ["." + self.cssclass]
+        for cls, rule in new_styles:
+            new_styles_code.append(", ".join(cls.format(c) for c in wrapper_classes) + " { " + rule + " }")
+        return base + "\n" + "\n".join(new_styles_code)
+
+    def _wrap_tablelinenos(self, inner):
+        lncount = 0
+        codelines = []
+        for t, line in inner:
+            if t:
+                lncount += 1
+            codelines.append(line)
+
+        fl = self.linenostart
+        mw = len(str(lncount + fl - 1))
+        sp = self.linenospecial
+        st = self.linenostep
+        la = self.lineanchors
+        aln = self.anchorlinenos
+        nocls = self.noclasses
+        if sp:
+            lines = []
+
+            for i in range(fl, fl + lncount):
+                line_before = ""
+                line_after = ""
+                if i % st == 0:
+                    if i % sp == 0:
+                        if aln:
+                            line_before = '<a href="#%s-%d" class="special">' % (la, i)
+                            line_after = "</a>"
+                        else:
+                            line_before = '<span class="special">'
+                            line_after = "</span>"
+                    elif aln:
+                        line_before = '<a href="#%s-%d">' % (la, i)
+                        line_after = "</a>"
+                    lines.append((line_before, "%*d" % (mw, i), line_after))
+                else:
+                    lines.append(("", "", ""))
+        else:
+            lines = []
+            for i in range(fl, fl + lncount):
+                line_before = ""
+                line_after = ""
+                if i % st == 0:
+                    if aln:
+                        line_before = '<a href="#%s-%d">' % (la, i)
+                        line_after = "</a>"
+                    lines.append((line_before, "%*d" % (mw, i), line_after))
+                else:
+                    lines.append(("", "", ""))
+
+        yield 0, '<div class="%s"><table class="%stable">' % (
+            self.cssclass,
+            self.cssclass,
+        )
+        for lndata, cl in zip(lines, codelines):
+            ln_b, ln, ln_a = lndata
+            cl = MANY_SPACES.sub(_sp_to_nbsp, cl)
+            if nocls:
+                yield 0, (
+                    '<tr><td class="linenos linenodiv" style="background-color: #f0f0f0; padding-right: 10px">'
+                    + ln_b
+                    + '<code data-line-number="'
+                    + ln
+                    + '"></code>'
+                    + ln_a
+                    + '</td><td class="code"><code>'
+                    + cl
+                    + "</code></td></tr>"
+                )
+            else:
+                yield 0, (
+                    '<tr><td class="linenos linenodiv">'
+                    + ln_b
+                    + '<code data-line-number="'
+                    + ln
+                    + '"></code>'
+                    + ln_a
+                    + '</td><td class="code"><code>'
+                    + cl
+                    + "</code></td></tr>"
+                )
+        yield 0, "</table></div>"
+
+    def _wrap_inlinelinenos(self, inner):
+        # Override with new method
+        return self._wrap_ollineos(self, inner)
+
+    def _wrap_ollinenos(self, inner):
+        lines = inner
+        sp = self.linenospecial
+        st = self.linenostep or 1
+        num = self.linenostart
+
+        if self.anchorlinenos:
+            warnings.warn("anchorlinenos is not supported for linenos='ol'.")
+
+        yield 0, "<ol>"
+        if self.noclasses:
+            if sp:
+                for t, line in lines:
+                    if num % sp == 0:
+                        style = "background-color: #ffffc0; padding: 0 5px 0 5px"
+                    else:
+                        style = "background-color: #f0f0f0; padding: 0 5px 0 5px"
+                    if num % st != 0:
+                        style += "; list-style: none"
+                    yield 1, '<li style="%s" value="%s">' % (style, num,) + line + "</li>"
+                    num += 1
+            else:
+                for t, line in lines:
+                    yield 1, (
+                        '<li style="background-color: #f0f0f0; padding: 0 5px 0 5px%s" value="%s">'
+                        % (("; list-style: none" if num % st != 0 else ""), num)
+                        + line
+                        + "</li>"
+                    )
+                    num += 1
+        elif sp:
+            for t, line in lines:
+                yield 1, '<li class="lineno%s%s" value="%s">' % (
+                    " special" if num % sp == 0 else "",
+                    " nonumber" if num % st != 0 else "",
+                    num,
+                ) + line + "</li>"
+                num += 1
+        else:
+            for t, line in lines:
+                yield 1, '<li class="lineno%s" value="%s">' % (
+                    "" if num % st != 0 else " nonumber",
+                    num,
+                ) + line + "</li>"
+                num += 1
+
+        yield 0, "</ol>"
+
+    def format_unencoded(self, tokensource, outfile):
+        """Format code and write to outfile.
+
+        The formatting process uses several nested generators; which of
+        them are used is determined by the user's options.
+
+        Each generator should take at least one argument, ``inner``,
+        and wrap the pieces of text generated by this.
+
+        Always yield 2-tuples: (code, text). If "code" is 1, the text
+        is part of the original tokensource being highlighted, if it's
+        0, the text is some piece of wrapping. This makes it possible to
+        use several different wrappers that process the original source
+        linewise, e.g. line number generators.
+        """
+        if self.linenos_val is False:
+            return super().format_unencoded(tokensource, outfile)
+        source = self._format_lines(tokensource)
+        if self.hl_lines:
+            source = self._highlight_lines(source)
+        if not self.nowrap:
+            if self.linenos_val == BetterLinenos.OL:
+                source = self._wrap_ollinenos(source)
+            if self.lineanchors:
+                source = self._wrap_lineanchors(source)
+            if self.linespans:
+                source = self._wrap_linespans(source)
+            if self.linenos_val == BetterLinenos.TABLE:
+                source = self._wrap_tablelinenos(source)
+            if self.linenos_val == BetterLinenos.OL:
+                source = self.wrap(source)
+            if self.full:
+                source = self._wrap_full(source, outfile)
+
+        for t, piece in source:
+            outfile.write(piece)

pygments_better_html-0.1.6.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: pygments_better_html
+Version: 0.1.6
+Summary: Better HTML formatter for Pygments.
+Keywords: pygments,html,code,highlighting
+Author-email: Chris Warrick <chris@chriswarrick.com>
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+License-File: LICENSE
+License-File: LICENSE.pygments
+Requires-Dist: Pygments>=2.15.1
+Project-URL: Homepage, https://github.com/Kwpolska/pygments_better_html
+
+# Better line numbers for Pygments HTML
+
+This library provides improved line numbers for the Pygments HTML formatter. The `BetterHtmlFormatter` supports two styles:
+
+* `linenos="table"` (the default) — every line of the code is a separate table row (a 2xN table, as opposed to Pygments’ standard 2x1 table) This improves the appearance if the code contains characters with unusual line-height, and allows for the code to be word-wrapped with the numbers kept in the right places.
+* `linenos="ol"` — lines are `<li>` elements in an `<ol>` list.
+
+Both styles allow for copy-pasting into a code editor. Directly copy-pasting into Microsoft Word (or similar) might produce something ugly. The first style is inspired by GitHub, and the second can be seen at pastebin.com.
+
+The `table` style is more flexible and looks better. The `ol` style is slightly more compatible with broken browsers and minifiers. Pick whichever one works best for you.
+
+## Usage
+
+In most cases, it’s a drop-in replacement for `HtmlFormatter`. Just add the import:
+
+```py
+from pygments_better_html import BetterHtmlFormatter
+```
+
+and when calling `highlight()`, instead of `HtmlFormatter`, pass the `BetterHtmlFormatter` class:
+
+```py
+BetterHtmlFormatter(linenos="table", ..., other options, ...)
+BetterHtmlFormatter(linenos="ol", ..., other options, ...)
+```
+
+You can see a simple demo in `demo.py`.
+
+### Required CSS
+
+To make this work, you will need to add the following CSS:
+
+```css
+.highlight table, .highlight tr, .highlight td { border-spacing: 0; border-collapse: separate; padding: 0 }
+.highlight pre { white-space: pre-wrap; line-height: normal }
+.highlighttable td.linenos { vertical-align: top; padding-left: 10px; padding-right: 10px; user-select: none; -webkit-user-select: none }
+.highlighttable td.linenos code:before { content: attr(data-line-number) }
+.highlighttable td.code { overflow-wrap: normal; border-collapse: collapse }
+.highlighttable td.code code { overflow: unset; border: none; padding: 0; margin: 0; white-space: pre-wrap; line-height: unset; background: none }
+.highlight .lineno.nonumber { list-style: none }
+```
+
+If you’re using ``get_style_defs``, those will be included for you.
+
+## Browser support
+
+All reasonably modern versions of reasonable browsers are supported. Internet Explorer is neither, so it isn’t supported. Firefox, Chrome and Safari are supported. Either mode works with these browsers, although I’ve seen Firefox add extra spaces to the front of lines randomly, and Safari requires an ugly hack for the table mode.
+
+## Known limitations
+
+1. The `anchorlinenos` option is not supported for `linenos="ol"`.
+2. Third-party minifier tools may destroy your indentation if you use tabs. Spaces use a work-around, described in the following point.
+3. Because of overly clever HTML minifiers, `&nbsp;` tags are used for indentation and sequences of whitespace longer than one character. This might break in the event web browsers decide to copy non-breaking spaces as non-breaking instead of regular spaces. Currently, browsers do the right thing on all platforms. It might also lead to degraded apperance in some edge cases (indentation longer than the code box width, or long runs of spaces inside the code).
+4. Some completely broken HTML minifiers will remove line numbers, because they are empty tags (that’s the only way to make Safari ignore them on copy-paste). Removing empty tags is just wrong, considering how many browser hacks were built on top of these throughout the years. I saw this issue with HTML Tidy, which is an antique tool detached from reality (even in the HTML5 fork).
+
+If you care about compatiblity with bad tools or unusual scenarios, and don’t mind losing `anchorlinenos`, consider using the `lineos="ol"` mode instead of `lineos="table"`.
+
+### Browsers vs code vs minifiers
+
+Limitations (3) and (4) might be considered bugs in my code and not the minifiers. But note that browsers don’t ignore whitespace when parsing, and although the default `white-space: normal` setting for most tags collapses them, you can use `white-space: pre` or `white-space: pre-wrap` to display them. Those minifiers don’t take the CSS into account, and assume the default behavior, collapsing spaces outside of `<pre>` tags. Which is wrong if you override `white-space` on other elements, and “wasteful” if you do `pre { white-space: normal }` for some unusual reason (yeah, don’t do that.)
+
+Collapsing whitespace could be worked around with a `<pre>` tag around each line of code, but Firefox will add extra newlines when copying (so the actual code is on every other line of the copied text). This is not avoidable and hard-coded (the plaintext conversion does not look at CSS either, and has a special case for `<pre>` since it makes sense for normal use of that tag. And you can’t wrap the entire table in a `<pre>` tag. If I added one, browsers would move it outside of the table to make the HTML valid. But if browsers do that, some of those clever minifiers might fix HTML syntax as well.
+
+I decided to use a different solution, and work around these tools, by using non-breaking spaces for longer runs of spaces. This depends on web browsers replacing those with regular spaces when copying. Luckily, all browsers do this, and considering a 2008 4chan meme (“can’t triforce”, search results might be NSFW), that’s been a thing since forever and is not likely to change.
+
+The selected solution of replacing runs of spaces with non-breaking spaces can lead to the code overflowing the box/adding a horizontal scrollbar. Those will happen only in very specific edge cases, i.e. very narrow windows + very large fonts + large indents + no regular (single) spaces close to the indent.
+
+I also decided not to apply it to tabs (\t, ^I, U+0009 HORIZONTAL TAB), because tab width can be random, and tabs move the caret to a place, not by a set amount (so in `"a\tb"` and `"aa\tb"`, the `"b"` appears in the same place on the line). Which is generally difficult to handle properly, and you should be using spaces to indent your code anyway.
+
+You should also note that GitHub uses both of these techniques, and BitBucket uses the first one. And that it’s easier for everyone to find a better tool if their current tool does stupid stuff.
+
+## License
+
+Copyright © 2020-2026, Chris Warrick. Licensed under the 3-clause BSD license.
+
+Many parts of the code are taken from Pygments’ original HTMLFormatter, which is copyright © 2006-2022 by the Pygments team, and is licensed under the 2-clause BSD license.
+

pygments_better_html-0.1.6.dist-info/RECORD

@@ -0,0 +1,6 @@
+pygments_better_html/__init__.py,sha256=_n0f-Jgje14aR5dCEm0L-ulDU_Zi2BbCJ1GFlK_AEW8,9705
+pygments_better_html-0.1.6.dist-info/licenses/LICENSE,sha256=GkQeIqf8-mNiwQK4LK5sZ14T2vLSw1Z3ZwbsKJ31CvM,1526
+pygments_better_html-0.1.6.dist-info/licenses/LICENSE.pygments,sha256=qdZvHVJt8C4p3Oc0NtNOVuhjL0bCdbvf_HBWnogvnxc,1331
+pygments_better_html-0.1.6.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+pygments_better_html-0.1.6.dist-info/METADATA,sha256=ryRWoWEUMOxqb1GSjhea0dDIJJwszuwc30Z0WZWtfDE,7173
+pygments_better_html-0.1.6.dist-info/RECORD,,

pygments_better_html-0.1.6.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: flit 3.12.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pygments_better_html-0.1.6.dist-info/licenses/LICENSE

@@ -0,0 +1,30 @@
+Copyright © 2020-2026, Chris Warrick.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions, and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions, and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the author of this software nor the names of
+   contributors to this software may be used to endorse or promote
+   products derived from this software without specific prior written
+   consent.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pygments_better_html-0.1.6.dist-info/licenses/LICENSE.pygments

@@ -0,0 +1,25 @@
+Copyright (c) 2006-2022 by the respective authors (see AUTHORS file).
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.