omdev 0.0.0.dev294__py3-none-any.whl → 0.0.0.dev295__py3-none-any.whl

omdev/ptk/markdown/tags.py

@@ -0,0 +1,298 @@
+import typing as ta
+
+from ... import ptk
+from .border import DoubleBorder
+from .border import SquareBorder
+from .utils import FormattedTextAlign
+from .utils import add_border
+from .utils import align
+from .utils import apply_style
+from .utils import indent
+from .utils import lex
+from .utils import strip
+from .utils import wrap
+
+
+if ta.TYPE_CHECKING:
+    from markdown_it.token import Token
+
+
+TagRule: ta.TypeAlias = ta.Callable[
+    [
+        ptk.StyleAndTextTuples,
+        int,
+        int,
+        'Token',
+    ],
+    ptk.StyleAndTextTuples,
+]
+
+
+##
+
+
+def h1(
+        ft: ptk.StyleAndTextTuples,
+        width: int,
+        left: int,
+        token: 'Token',
+) -> ptk.StyleAndTextTuples:
+    """Format a top-level heading wrapped and centered with a full width double border."""
+
+    ft = wrap(ft, width - 4)
+    ft = align(FormattedTextAlign.CENTER, ft, width=width - 4)
+    ft = add_border(ft, width, style='class:md.h1.border', border=DoubleBorder)
+    ft.append(('', '\n\n'))
+    return ft
+
+
+def h2(
+        ft: ptk.StyleAndTextTuples,
+        width: int,
+        left: int,
+        token: 'Token',
+) -> ptk.StyleAndTextTuples:
+    """Format a 2nd-level headding wrapped and centered with a double border."""
+
+    ft = wrap(ft, width=width - 4)
+    ft = align(FormattedTextAlign.CENTER, ft)
+    ft = add_border(ft, style='class:md.h2.border', border=SquareBorder)
+    ft = align(FormattedTextAlign.CENTER, ft, width=width)
+    ft.append(('', '\n\n'))
+    return ft
+
+
+def h(
+        ft: ptk.StyleAndTextTuples,
+        width: int,
+        left: int,
+        token: 'Token',
+) -> ptk.StyleAndTextTuples:
+    """Format headings wrapped and centeredr."""
+
+    ft = wrap(ft, width)
+    ft = align(FormattedTextAlign.CENTER, ft, width=width)
+    ft.append(('', '\n\n'))
+    return ft
+
+
+def p(
+        ft: ptk.StyleAndTextTuples,
+        width: int,
+        left: int,
+        token: 'Token',
+) -> ptk.StyleAndTextTuples:
+    """Format paragraphs wrapped."""
+
+    ft = wrap(ft, width)
+    ft.append(('', '\n' if token.hidden else '\n\n'))
+    return ft
+
+
+def ul(
+        ft: ptk.StyleAndTextTuples,
+        width: int,
+        left: int,
+        token: 'Token',
+) -> ptk.StyleAndTextTuples:
+    """Format unordered lists."""
+
+    ft.append(('', '\n'))
+    return ft
+
+
+def ol(
+        ft: ptk.StyleAndTextTuples,
+        width: int,
+        left: int,
+        token: 'Token',
+) -> ptk.StyleAndTextTuples:
+    """Formats ordered lists."""
+
+    ft.append(('', '\n'))
+    return ft
+
+
+def li(
+        ft: ptk.StyleAndTextTuples,
+        width: int,
+        left: int,
+        token: 'Token',
+) -> ptk.StyleAndTextTuples:
+    """Formats list items."""
+
+    ft = strip(ft)
+
+    # Determine if this is an ordered or unordered list
+    if token.attrs.get('data-list-type') == 'ol':
+        margin_style = 'class:md.ol.margin'
+    else:
+        margin_style = 'class:md.ul.margin'
+
+    # Get the margin (potentially contains aligned item numbers)
+    margin = str(token.attrs.get('data-margin', '•'))
+
+    # We put a speace each side of the margin
+    ft = indent(ft, margin=' ' * (len(margin) + 2), style=margin_style)
+    ft[0] = (ft[0][0], f' {margin} ')
+
+    ft.append(('', '\n'))
+    return ft
+
+
+def hr(
+        ft: ptk.StyleAndTextTuples,
+        width: int,
+        left: int,
+        token: 'Token',
+) -> ptk.StyleAndTextTuples:
+    """Format horizontal rules."""
+
+    ft = [
+        ('class:md.hr', '─' * width),
+        ('', '\n\n'),
+    ]
+    return ft
+
+
+def br(
+        ft: ptk.StyleAndTextTuples,
+        width: int,
+        left: int,
+        token: 'Token',
+) -> ptk.StyleAndTextTuples:
+    """Format line breaks."""
+
+    return [('', '\n')]
+
+
+def blockquote(
+        ft: ptk.StyleAndTextTuples,
+        width: int,
+        left: int,
+        token: 'Token',
+) -> ptk.StyleAndTextTuples:
+    """Format blockquotes with a solid left margin."""
+
+    ft = strip(ft)
+    ft = indent(ft, margin='▌ ', style='class:md.blockquote.margin')
+    ft.append(('', '\n\n'))
+    return ft
+
+
+def code(
+        ft: ptk.StyleAndTextTuples,
+        width: int,
+        left: int,
+        token: 'Token',
+) -> ptk.StyleAndTextTuples:
+    """Format inline code, and lexes and formats code blocks with a border."""
+
+    if token.block:
+        ft = strip(ft, left=False, right=True, char='\n')
+        ft = lex(ft, lexer_name=token.info)
+        ft = align(FormattedTextAlign.LEFT, ft, width - 4)
+        ft = add_border(ft, width, style='class:md.code.border', border=SquareBorder)
+        ft.append(('', '\n\n'))
+    else:
+        ft = apply_style(ft, style='class:md.code.inline')
+
+    return ft
+
+
+def math(
+        ft: ptk.StyleAndTextTuples,
+        width: int,
+        left: int,
+        token: 'Token',
+) -> ptk.StyleAndTextTuples:
+    """Format inline maths, and quotes math blocks."""
+
+    if token.block:
+        return blockquote(ft, width - 2, left, token)
+    else:
+        return ft
+
+
+def a(
+        ft: ptk.StyleAndTextTuples,
+        width: int,
+        left: int,
+        token: 'Token',
+) -> ptk.StyleAndTextTuples:
+    """Format hyperlinks and adds link escape sequences."""
+
+    result: ptk.StyleAndTextTuples = []
+    href = token.attrs.get('href')
+    if href:
+        result.append(('[ZeroWidthEscape]', f'\x1b]8;;{href}\x1b\\'))
+    result += ft
+    if href:
+        result.append(('[ZeroWidthEscape]', '\x1b]8;;\x1b\\'))
+    return result
+
+
+def img(
+        ft: ptk.StyleAndTextTuples,
+        width: int,
+        left: int,
+        token: 'Token',
+) -> ptk.StyleAndTextTuples:
+    """Format image titles."""
+
+    bounds = ('', '')
+    if not ptk.to_plain_text(ft):
+        # Add fallback text if there is no image title
+        title = str(token.attrs.get('alt'))
+
+        # Try getting the filename
+        src = str(token.attrs.get('src', ''))
+        if not title and not src.startswith('data:'):
+            title = src.rsplit('/', 1)[-1]
+        if not title:
+            title = 'Image'
+        ft = [('class:md.img', title)]
+
+    # Add the sunrise emoji to represent an image. I would use :framed_picture:, but it requires multiple code-points
+    # and causes breakage in many terminals
+    result = [('class:md.img', '🌄 '), *ft]
+    result = apply_style(result, style='class:md.img')
+    result = [
+        ('class:md.img.border', f'{bounds[0]}'),
+        *result,
+        ('class:md.img.border', f'{bounds[1]}'),
+    ]
+    return result
+
+
+##
+
+
+# Maps HTML tag names to formatting functions. Functionality can be extended by modifying this dictionary
+TAG_RULES: ta.Mapping[str, TagRule] = {
+    'h1': h1,
+    'h2': h2,
+    'h3': h,
+    'h4': h,
+    'h5': h,
+    'h6': h,
+    'p': p,
+    'ul': ul,
+    'ol': ol,
+    'li': li,
+    'hr': hr,
+    'br': br,
+    'blockquote': blockquote,
+    'code': code,
+    'math': math,
+    'a': a,
+    'img': img,
+}
+
+
+# Mapping showing how much width the formatting of block elements used. This is used to reduce the available width when
+# rendering child elements
+TAG_INSETS = {
+    'li': 3,
+    'blockquote': 2,
+}

omdev/ptk/markdown/utils.py

@@ -0,0 +1,365 @@
+import enum
+import typing as ta
+
+from pygments.lexers import get_lexer_by_name
+from pygments.util import ClassNotFound
+
+from ... import ptk
+from .border import Border
+from .border import SquareBorder
+
+
+##
+
+
+class FormattedTextAlign(enum.Enum):
+    """Alignment of formatted text."""
+
+    LEFT = 'LEFT'
+    RIGHT = 'RIGHT'
+    CENTER = 'CENTER'
+
+
+def last_line_length(ft: ptk.StyleAndTextTuples) -> int:
+    """Calculate the length of the last line in formatted text."""
+
+    line: ptk.StyleAndTextTuples = []
+    for style, text, *_ in ft[::-1]:
+        index = text.find('\n')
+        line.append((style, text[index + 1:]))
+        if index > -1:
+            break
+
+    return ptk.fragment_list_width(line)
+
+
+def max_line_width(ft: ptk.StyleAndTextTuples) -> int:
+    """Calculate the length of the longest line in formatted text."""
+
+    return max(ptk.fragment_list_width(line) for line in ptk.split_lines(ft))
+
+
+def fragment_list_to_words(fragments: ptk.StyleAndTextTuples) -> ta.Iterable[ptk.OneStyleAndTextTuple]:
+    """Split formatted text into word fragments."""
+
+    for style, string, *mouse_handler in fragments:
+        parts = string.split(' ')
+        for part in parts[:-1]:
+            yield ta.cast('ptk.OneStyleAndTextTuple', (style, part, *mouse_handler))
+            yield ta.cast('ptk.OneStyleAndTextTuple', (style, ' ', *mouse_handler))
+
+        yield ta.cast('ptk.OneStyleAndTextTuple', (style, parts[-1], *mouse_handler))
+
+
+def apply_style(ft: ptk.StyleAndTextTuples, style: str) -> ptk.StyleAndTextTuples:
+    """Apply a style to formatted text."""
+
+    return [
+        (
+            f'{fragment_style} {style}'
+            if '[ZeroWidthEscape]' not in fragment_style else fragment_style,
+            text,
+        )
+        for (fragment_style, text, *_) in ft
+    ]
+
+
+def strip(
+    ft: ptk.StyleAndTextTuples,
+    left: bool = True,
+    right: bool = True,
+    char: str | None = None,
+) -> ptk.StyleAndTextTuples:
+    """
+    Strip whitespace (or a given character) from the ends of formatted text.
+
+    Args:
+        ft: The formatted text to strip
+        left: If :py:const:`True`, strip from the left side of the input
+        right: If :py:const:`True`, strip from the right side of the input
+        char: The character to strip. If :py:const:`None`, strips whitespace
+    Returns:
+        The stripped formatted text
+    """
+
+    result = ft[:]
+    for toggle, index, strip_func in [
+        (left, 0, str.lstrip),
+        (right, -1, str.rstrip),
+    ]:
+        if result and toggle:
+            text = strip_func(result[index][1], char)
+
+            while result and not text:
+                del result[index]
+                if not result:
+                    break
+
+                text = strip_func(result[index][1], char)
+
+            if result and '[ZeroWidthEscape]' not in result[index][0]:
+                result[index] = (result[index][0], text)
+
+    return result
+
+
+def truncate(
+    ft: ptk.StyleAndTextTuples,
+    width: int,
+    style: str = '',
+    placeholder: str = '…',
+) -> ptk.StyleAndTextTuples:
+    """
+    Truncates all lines at a given length.
+
+    Args:
+        ft: The formatted text to truncate
+        width: The width at which to truncate the text
+        style: The style to apply to the truncation placeholder. The style of the truncated text will be used if not
+            provided
+        placeholder: The string that will appear at the end of a truncated line
+    Returns:
+        The truncated formatted text
+    """
+
+    result: ptk.StyleAndTextTuples = []
+    phw = sum(ptk.get_cwidth(c) for c in placeholder)
+    for line in ptk.split_lines(ft):
+        used_width = 0
+        for item in line:
+            fragment_width = sum(
+                ptk.get_cwidth(c)
+                for c in item[1]
+                if '[ZeroWidthEscape]' not in item[0]
+            )
+
+            if used_width + fragment_width > width - phw:
+                remaining_width = width - used_width - fragment_width - phw
+                result.append((item[0], item[1][:remaining_width]))
+                result.append((style or item[0], placeholder))
+                break
+
+            result.append(item)
+            used_width += fragment_width
+
+        result.append(('', '\n'))
+
+    result.pop()
+    return result
+
+
+def wrap(
+    ft: ptk.StyleAndTextTuples,
+    width: int,
+    style: str = '',
+    placeholder: str = '…',
+) -> ptk.StyleAndTextTuples:
+    """
+    Wraps formatted text at a given width. If words are longer than the given line they will be truncated
+
+    Args:
+        ft: The formatted text to wrap
+        width: The width at which to wrap the text
+        style: The style to apply to the truncation placeholder
+        placeholder: The string that will appear at the end of a truncated line
+    Returns:
+        The wrapped formatted text
+    """
+
+    result: ptk.StyleAndTextTuples = []
+    lines = list(ptk.split_lines(ft))
+    for i, line in enumerate(lines):
+        if ptk.fragment_list_width(line) <= width:
+            result += line
+            if i < len(lines) - 1:
+                result.append(('', '\n'))
+            continue
+
+        used_width = 0
+        for item in fragment_list_to_words(line):
+            fragment_width = sum(
+                ptk.get_cwidth(c)
+                for c in item[1]
+                if '[ZeroWidthEscape]' not in item[0]
+            )
+
+            # Start a new line we are at the end
+            if used_width + fragment_width > width and used_width > 0:
+                # Remove trailing whitespace
+                result = strip(result, left=False)
+                result.append(('', '\n'))
+                used_width = 0
+
+            # Truncate words longer than a line
+            if fragment_width > width and used_width == 0:
+                result += truncate([item], width, style, placeholder)
+                used_width += fragment_width
+
+            # Left-strip words at the start of a line
+            elif used_width == 0:
+                result += strip([item], right=False)
+                used_width += fragment_width
+
+            # Otherwise just add the word to the line
+            else:
+                result.append(item)
+                used_width += fragment_width
+
+    return result
+
+
+def align(
+    how: FormattedTextAlign,
+    ft: ptk.StyleAndTextTuples,
+    width: int | None = None,
+    style: str = '',
+    placeholder: str = '…',
+) -> ptk.StyleAndTextTuples:
+    """
+    Align formatted text at a given width.
+
+    Args:
+        how: The alignment direction
+        ft: The formatted text to strip
+        width: The width to which the output should be padded. If :py:const:`None`, the length of the longest line is
+            used
+        style: The style to apply to the padding
+        placeholder: The string that will appear at the end of a truncated line
+    Returns:
+        The aligned formatted text
+    """
+
+    lines = ptk.split_lines(ft)
+    if width is None:
+        lines = [strip(line) for line in ptk.split_lines(ft)]
+        width = max(ptk.fragment_list_width(line) for line in lines)
+
+    result: ptk.StyleAndTextTuples = []
+    for line in lines:
+        line_width = ptk.fragment_list_width(line)
+
+        # Truncate the line if it is too long
+        if line_width > width:
+            result += truncate(line, width, style, placeholder)
+
+        else:
+            pad_left = pad_right = 0
+
+            if how == FormattedTextAlign.CENTER:
+                pad_left = (width - line_width) // 2
+                pad_right = width - line_width - pad_left
+
+            elif how == FormattedTextAlign.LEFT:
+                pad_right = width - line_width
+
+            elif how == FormattedTextAlign.RIGHT:
+                pad_left = width - line_width
+
+            if pad_left:
+                result.append((style, ' ' * pad_left))
+
+            result += line
+
+            if pad_right:
+                result.append((style, ' ' * pad_right))
+
+        result.append((style, '\n'))
+
+    result.pop()
+    return result
+
+
+def indent(
+    ft: ptk.StyleAndTextTuples,
+    margin: str = ' ',
+    style: str = '',
+    skip_first: bool = False,
+) -> ptk.StyleAndTextTuples:
+    """
+    Indents formatted text with a given margin.
+
+    Args:
+        ft: The formatted text to strip
+        margin: The margin string to add
+        style: The style to apply to the margin
+        skip_first: If :py:const:`True`, the first line is skipped
+    Returns:
+        The indented formatted text
+    """
+
+    result: ptk.StyleAndTextTuples = []
+    for i, line in enumerate(ptk.split_lines(ft)):
+        if not (i == 0 and skip_first):
+            result.append((style, margin))
+        result += line
+        result.append(('', '\n'))
+
+    result.pop()
+    return result
+
+
+def add_border(
+    ft: ptk.StyleAndTextTuples,
+    width: int | None = None,
+    style: str = '',
+    border: type[Border] = SquareBorder,
+) -> ptk.StyleAndTextTuples:
+    """
+    Adds a border around formatted text.
+
+    Args:
+        ft: The formatted text to enclose with a border
+        width: The target width of the output including the border
+        style: The style to apply to the border
+        border: The border to apply
+    Returns:
+        The indented formatted text
+    """
+
+    # if border is None:
+    # See mypy issue #4236
+    # border = cast("Type[Border]", Border)
+    if width is None:
+        width = max_line_width(ft) + 4
+
+    # ft = align(FormattedTextAlign.LEFT, ft, width - 4)
+    result: ptk.StyleAndTextTuples = []
+
+    result.append((
+        style,
+        border.TOP_LEFT + border.HORIZONTAL * (width - 2) + border.TOP_RIGHT + '\n',
+    ))
+
+    for line in ptk.split_lines(ft):
+        result += [
+            (style, border.VERTICAL),
+            ('', ' '),
+            *line,
+            ('', ' '),
+            (style, border.VERTICAL + '\n'),
+        ]
+
+    result.append((
+        style,
+        border.BOTTOM_LEFT + border.HORIZONTAL * (width - 2) + border.BOTTOM_RIGHT,
+    ))
+
+    return result
+
+
+def lex(ft: ptk.StyleAndTextTuples, lexer_name: str) -> ptk.StyleAndTextTuples:
+    """Format formatted text using a named :py:mod:`pygments` lexer."""
+
+    from prompt_toolkit.lexers.pygments import _token_cache  # noqa
+
+    text = ptk.fragment_list_to_text(ft)
+
+    try:
+        lexer = get_lexer_by_name(lexer_name)
+    except ClassNotFound:
+        return ft
+    else:
+        return [
+            (_token_cache[t], v)
+            for _, t, v in lexer.get_tokens_unprocessed(text)
+        ]

omdev/tools/doc.py

@@ -25,6 +25,9 @@ else:
     markdown_it = lang.proxy_import('markdown_it')
 
 
+##
+
+
 def rst2html(rst, report_level=None):
     kwargs = {
         'writer_name': 'html',

{omdev-0.0.0.dev294.dist-info → omdev-0.0.0.dev295.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: omdev
-Version: 0.0.0.dev294
+Version: 0.0.0.dev295
 Summary: omdev
 Author: wrmsr
 License: BSD-3-Clause
@@ -12,13 +12,14 @@ Classifier: Operating System :: OS Independent
 Classifier: Operating System :: POSIX
 Requires-Python: >=3.12
 License-File: LICENSE
-Requires-Dist: omlish==0.0.0.dev294
+Requires-Dist: omlish==0.0.0.dev295
 Provides-Extra: all
 Requires-Dist: black~=25.1; extra == "all"
 Requires-Dist: pycparser~=2.22; extra == "all"
 Requires-Dist: pcpp~=1.30; extra == "all"
 Requires-Dist: docutils~=0.21; extra == "all"
 Requires-Dist: markdown-it-py~=3.0; extra == "all"
+Requires-Dist: mdit-py-plugins~=0.4; extra == "all"
 Requires-Dist: mypy~=1.15; extra == "all"
 Requires-Dist: gprof2dot~=2025.4; extra == "all"
 Requires-Dist: prompt-toolkit~=3.0; extra == "all"
@@ -31,6 +32,7 @@ Requires-Dist: pcpp~=1.30; extra == "c"
 Provides-Extra: doc
 Requires-Dist: docutils~=0.21; extra == "doc"
 Requires-Dist: markdown-it-py~=3.0; extra == "doc"
+Requires-Dist: mdit-py-plugins~=0.4; extra == "doc"
 Provides-Extra: mypy
 Requires-Dist: mypy~=1.15; extra == "mypy"
 Provides-Extra: prof