flowmark 0.3.3__tar.gz → 0.4.1__tar.gz

{flowmark-0.3.3 → flowmark-0.4.1}/.copier-answers.yml

@@ -1,5 +1,5 @@
 # Changes here will be overwritten by Copier. Do not edit manually.
-_commit: v0.2.0
+_commit: v0.2.7
 _src_path: gh:jlevy/simple-modern-uv
 package_author_email: joshua@cal.berkeley.edu
 package_author_name: Joshua Levy

{flowmark-0.3.3 → flowmark-0.4.1}/.github/workflows/ci.yml

@@ -40,7 +40,8 @@ jobs:
       - name: Install uv (official Astral action)
         uses: astral-sh/setup-uv@v5
         with:
-          version: "0.6.5"
+          # Update this as needed:
+          version: "0.6.14"
           enable-cache: true
           python-version: ${{ matrix.python-version }}
 

{flowmark-0.3.3 → flowmark-0.4.1}/.github/workflows/publish.yml

@@ -21,7 +21,7 @@ jobs:
       - name: Install uv (official Astral action)
         uses: astral-sh/setup-uv@v5
         with:
-          version: "0.6.5"
+          version: "0.6.14"
           enable-cache: true
           python-version: "3.12"
 

{flowmark-0.3.3 → flowmark-0.4.1}/Makefile

@@ -1,5 +1,6 @@
 # Makefile for easy development workflows.
-# GitHub Actions call uv directly.
+# See development.md for docs.
+# Note GitHub Actions call uv directly, not this Makefile.
 
 .DEFAULT_GOAL := default
 

{flowmark-0.3.3 → flowmark-0.4.1}/PKG-INFO

@@ -1,11 +1,20 @@
 Metadata-Version: 2.4
 Name: flowmark
-Version: 0.3.3
+Version: 0.4.1
 Summary: Better line wrapping and formatting for plaintext and Markdown
 Project-URL: Repository, https://github.com/jlevy/flowmark
 Author-email: Joshua Levy <joshua@cal.berkeley.edu>
 License-Expression: MIT
 License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
 Requires-Python: <4.0,>=3.10
 Requires-Dist: marko>=2.1.2
 Requires-Dist: regex>=2024.11.6
@@ -169,7 +178,6 @@ Markdown content. It can:
 
 - Optionally break lines at sentence boundaries for better diff readability
 
-
 - Process plaintext with HTML-aware word splitting
 
 It is both a library and a command-line tool.
@@ -195,6 +203,12 @@ Command-line usage examples:
 For more details, see: https://github.com/jlevy/flowmark
 ```
 
+## Project Docs
+
+For how to install uv and Python, see [installation.md](installation.md).
+
+For development workflows, see [development.md](development.md).
+
 For instructions on publishing to PyPI, see [publishing.md](publishing.md).
 
 * * *

{flowmark-0.3.3 → flowmark-0.4.1}/README.md

@@ -154,7 +154,6 @@ Markdown content. It can:
 
 - Optionally break lines at sentence boundaries for better diff readability
 
-
 - Process plaintext with HTML-aware word splitting
 
 It is both a library and a command-line tool.
@@ -180,6 +179,12 @@ Command-line usage examples:
 For more details, see: https://github.com/jlevy/flowmark
 ```
 
+## Project Docs
+
+For how to install uv and Python, see [installation.md](installation.md).
+
+For development workflows, see [development.md](development.md).
+
 For instructions on publishing to PyPI, see [publishing.md](publishing.md).
 
 * * *

{flowmark-0.3.3 → flowmark-0.4.1}/devtools/lint.py

@@ -1,6 +1,7 @@
 import subprocess
 
 from funlog import log_calls
+from rich import get_console, reconfigure
 from rich import print as rprint
 
 # Update as needed.
@@ -8,6 +9,9 @@ SRC_PATHS = ["src", "tests", "devtools"]
 DOC_PATHS = ["README.md"]
 
 
+reconfigure(emoji=not get_console().options.legacy_windows)  # No emojis on legacy windows.
+
+
 def main():
     rprint()
 
@@ -20,9 +24,9 @@ def main():
     rprint()
 
     if errcount != 0:
-        rprint(f"[bold red]✗ Lint failed with {errcount} errors.[/bold red]")
+        rprint(f"[bold red]:x: Lint failed with {errcount} errors.[/bold red]")
     else:
-        rprint("[bold green]✔️ Lint passed![/bold green]")
+        rprint("[bold green]:white_check_mark: Lint passed![/bold green]")
     rprint()
 
     return errcount
@@ -31,7 +35,7 @@ def main():
 @log_calls(level="warning", show_timing_only=True)
 def run(cmd: list[str]) -> int:
     rprint()
-    rprint(f"[bold green]❯ {' '.join(cmd)}[/bold green]")
+    rprint(f"[bold green]:arrow_forward: {' '.join(cmd)}[/bold green]")
     errcount = 0
     try:
         subprocess.run(cmd, text=True, check=True)

flowmark-0.4.1/installation.md

@@ -0,0 +1,27 @@
+## Installing uv and Python
+
+This project is set up to use [**uv**](https://docs.astral.sh/uv/), the new package
+manager for Python. `uv` replaces traditional use of `pyenv`, `pipx`, `poetry`, `pip`,
+etc. This is a quick cheat sheet on that:
+
+On macOS or Linux, if you don't have `uv` installed, a quick way to install it:
+
+```shell
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+For macOS, you prefer [brew](https://brew.sh/) you can install or upgrade uv with:
+
+```shell
+brew update
+brew install uv
+```
+
+See [uv's docs](https://docs.astral.sh/uv/getting-started/installation/) for more
+installation methods and platforms.
+
+Now you can use uv to install a current Python environment:
+
+```shell
+uv python install 3.13 # Or pick another version.
+```

{flowmark-0.3.3 → flowmark-0.4.1}/pyproject.toml

@@ -3,6 +3,7 @@
 [project.urls]
 Repository = "https://github.com/jlevy/flowmark"
 # Homepage = "https://..."
+# Documentation = "https://..."
 
 [project]
 name = "flowmark"
@@ -15,6 +16,24 @@ license = "MIT"
 requires-python = ">=3.10,<4.0"
 dynamic = ["version"]
 
+# https://pypi.org/classifiers/
+# Adjust as needed:
+classifiers = [
+    # Adjust as needed:
+    "Development Status :: 4 - Beta",
+    # "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+    # Include this to avoid accidentally publishing to PyPI:
+    # "Private :: Do Not Upload",
+]
+
 dependencies = [
     "marko>=2.1.2",
     "regex>=2024.11.6",
@@ -22,6 +41,7 @@ dependencies = [
     "typing-extensions>=4.12.2",
 ]
 
+
 [dependency-groups]
 dev = [
     "pytest>=8.3.5",
@@ -38,6 +58,7 @@ dev = [
 flowmark = "flowmark.cli:main"
 
 
+
 # ---- Build system ----
 
 # Dynamic versioning from:
@@ -58,6 +79,11 @@ vcs = "git"
 style = "pep440"
 bump = "true"
 
+[tool.hatch.build.targets.wheel]
+# The source location for the package.
+packages = ["src/flowmark"]
+
+
 # ---- Settings ----
 
 [tool.ruff]
@@ -65,8 +91,8 @@ bump = "true"
 line-length = 100
 
 [tool.ruff.lint]
-# See: https://docs.astral.sh/ruff/rules/
 select = [
+    # See: https://docs.astral.sh/ruff/rules/
     # Basic list from: https://docs.astral.sh/ruff/linter/#rule-selection
     "E", # https://docs.astral.sh/ruff/rules/#error-e
     "F", # https://docs.astral.sh/ruff/rules/#pyflakes-f
@@ -81,6 +107,7 @@ select = [
 
 ]
 ignore = [
+    # Disable some rules that are overly pedantic. Add/remove as desired:
     "E501", # https://docs.astral.sh/ruff/rules/line-too-long/
     "E402", # https://docs.astral.sh/ruff/rules/module-import-not-at-top-of-file/
     "E731", # https://docs.astral.sh/ruff/rules/lambda-assignment/
@@ -101,28 +128,38 @@ ignore = [
     "ISC002", # https://docs.astral.sh/ruff/rules/multi-line-implicit-string-concatenation/
 ]
 
+[tool.basedpyright]
 # BasedPyright currently seems like the best type checker option, much faster
 # than mypy and with a good extension for VSCode/Cursor.
 # https://marketplace.visualstudio.com/items?itemName=detachhead.basedpyright
 # https://docs.basedpyright.com/latest/configuration/config-files/#sample-pyprojecttoml-file
-[tool.basedpyright]
 include = ["src", "tests", "devtools"]
-# Make ignoring easier:
+
+# By default BasedPyright is very strict, so you almost certainly want to disable
+# some of the rules.
+# First, these turn off warnings about (yes) how you ignore warnings:
 reportIgnoreCommentWithoutRule = false
 reportUnnecessaryTypeIgnoreComment = false
-# Typically noisy warnings, comment/uncomment as desired:
+# A few typically noisy warnings are next.
+# How many you enable is up to you. The first few are off by default, but you can
+# comment/uncomment these as desired:
 reportMissingTypeStubs = false
 reportUnusedCallResult = false
+reportAny = false
+reportExplicitAny = false
+reportImplicitStringConcatenation = false
+# reportUnreachable = false
+# reportUnusedParameter = false
+# reportPrivateImportUsage = false
+# reportPrivateLocalImportUsage = false
 # reportMissingImports = false
 # reportUnnecessaryIsInstance = false
 # reportUnreachable = false
-reportAny = false
-reportExplicitAny = false
-reportUnusedParameter = false
 # reportUnknownVariableType = false
 # reportUnknownArgumentType = false
 
 [tool.codespell]
+# Add here as needed:
 # ignore-words-list = "foo,bar"
 skip = "tests/testdocs/*.md"
 

flowmark-0.4.1/src/flowmark/cleanups.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from marko import block, inline
+from marko.block import Document
+from marko.element import Element
+
+ContainerElement = (
+    block.Document,
+    block.Quote,
+    block.List,
+    block.ListItem,
+    block.Paragraph,  # Paragraphs contain inline elements
+    block.Heading,  # Already handled, but include for completeness if structure changes
+    inline.Emphasis,
+    inline.StrongEmphasis,
+    inline.Link,
+)
+
+
+def transform_tree(element: Element, transformer: Callable[[Element], None]) -> None:
+    """
+    Recursively traverse the element tree and apply a transformer function to each node.
+    """
+    transformer(element)
+
+    # Recursively process children for known container types
+    if isinstance(element, ContainerElement):
+        # Now we know element has a .children attribute that's a Sequence[Element] or str
+        # We only care about processing Element children
+        if isinstance(element.children, list):
+            # Create a copy for safe iteration if modification occurs
+            current_children = list(element.children)
+            for child in current_children:
+                transform_tree(child, transformer)
+
+
+def _unbold_heading_transformer(element: Element) -> None:
+    """
+    Transformer function to unbold headings where the entire text is bold.
+    """
+    if isinstance(element, block.Heading):
+        # Check if the heading consists *only* of a single StrongEmphasis element
+        if len(element.children) == 1 and isinstance(element.children[0], inline.StrongEmphasis):
+            # Replace the heading's children with the children of the StrongEmphasis element
+            strong_emphasis_node = element.children[0]
+            # Type checker struggles here, but StrongEmphasis children should be Elements.
+            element.children = strong_emphasis_node.children  # pyright: ignore
+
+        # Handle the case where the heading is bold and italic (StrongEmphasis inside Emphasis or vice versa)
+        # ***text***  -> *text*
+        elif len(element.children) == 1 and isinstance(element.children[0], inline.Emphasis):
+            emphasis_node = element.children[0]
+            if len(emphasis_node.children) == 1 and isinstance(
+                emphasis_node.children[0], inline.StrongEmphasis
+            ):
+                strong_node = emphasis_node.children[0]
+                emphasis_node.children = strong_node.children
+
+
+def unbold_headings(doc: Document) -> None:
+    """
+    Find headings where the entire text is bold and remove the bold.
+
+    Modifies the Marko document tree in place using a general transformer.
+    Example: `## **My Heading**` -> `## My Heading`
+    """
+    transform_tree(doc, _unbold_heading_transformer)
+
+
+def doc_cleanups(doc: Document):
+    """
+    Apply (ideally quite safe) cleanups to the document.
+    """
+    unbold_headings(doc)

{flowmark-0.3.3 → flowmark-0.4.1}/src/flowmark/cli.py

@@ -55,6 +55,7 @@ class Options:
     width: int
     plaintext: bool
     semantic: bool
+    cleanups: bool
     inplace: bool
     nobackup: bool
     version: bool
@@ -98,6 +99,13 @@ def _parse_args(args: list[str] | None = None) -> Options:
         default=False,
         help="Enable semantic (sentence-based) line breaks (only applies to Markdown mode)",
     )
+    parser.add_argument(
+        "-c",
+        "--cleanups",
+        action="store_true",
+        default=False,
+        help="Enable (safe) cleanups for common issues (only applies to Markdown mode)",
+    )
     parser.add_argument(
         "-i", "--inplace", action="store_true", help="Edit the file in place (ignores --output)"
     )
@@ -129,6 +137,7 @@ def _parse_args(args: list[str] | None = None) -> Options:
         width=opts.width,
         plaintext=opts.plaintext,
         semantic=opts.semantic,
+        cleanups=opts.cleanups,
         inplace=opts.inplace,
         nobackup=opts.nobackup,
         version=opts.version,
@@ -177,6 +186,7 @@ def main(args: list[str] | None = None) -> int:
             text,
             width=options.width,
             semantic=options.semantic,
+            cleanups=options.cleanups,
             dedent_input=True,
         )
 

flowmark-0.3.3/src/flowmark/markdown_filling.py → flowmark-0.4.1/src/flowmark/custom_marko.py

@@ -1,78 +1,19 @@
-"""
-Auto-formatting of Markdown text.
-
-This is similar to what is offered by
-[markdownfmt](https://github.com/shurcooL/markdownfmt) but with a few adaptations,
-including more aggressive normalization and support for wrapping of lines
-semi-semantically (e.g. on sentence boundaries when appropriate).
-(See [here](https://github.com/shurcooL/markdownfmt/issues/17) for some old
-discussion on why line wrapping this way is convenient.)
-"""
-
 from __future__ import annotations
 
 import re
-from collections.abc import Callable, Generator
+from collections.abc import Generator
 from contextlib import contextmanager
-from textwrap import dedent
 from typing import Any, cast
 
-from marko import block, inline
+from marko import Markdown, Renderer, block, inline
 from marko.block import HTMLBlock
+from marko.ext.gfm import GFM
+from marko.ext.gfm import elements as gfm_elements
 from marko.parser import Parser
-from marko.renderer import Renderer
 from marko.source import Source
 from typing_extensions import override
 
-from flowmark.frontmatter import split_frontmatter
-from flowmark.line_wrappers import LineWrapper, line_wrap_by_sentence, line_wrap_to_width
-from flowmark.sentence_split_regex import split_sentences_regex
-from flowmark.text_filling import DEFAULT_WRAP_WIDTH
-
-
-def _normalize_html_comments(text: str, break_str: str = "\n\n") -> str:
-    """
-    Put HTML comments as standalone paragraphs.
-    """
-
-    # Small hack to avoid changing frontmatter format, for the rare corner
-    # case where Markdown contains HTML-style frontmatter.
-    def not_frontmatter(text: str) -> bool:
-        return "<!---" not in text
-
-    # TODO: Probably want do this for <div>s too.
-    return _ensure_surrounding_breaks(
-        text, [("<!--", "-->")], break_str=break_str, filter=not_frontmatter
-    )
-
-
-def _ensure_surrounding_breaks(
-    html: str,
-    tag_pairs: list[tuple[str, str]],
-    filter: Callable[[str], bool] = lambda _: True,
-    break_str: str = "\n\n",
-) -> str:
-    html_len = len(html)
-    for start_tag, end_tag in tag_pairs:
-        pattern = re.compile(rf"(\s*{re.escape(start_tag)}.*?{re.escape(end_tag)}\s*)", re.DOTALL)
-
-        def replacer(match: re.Match[str]) -> str:
-            if not filter(match.group(0)):
-                return match.group(0)
-
-            content = match.group(1).strip()
-            before = after = break_str
-
-            if match.start() == 0:
-                before = ""
-            if match.end() == html_len:
-                after = ""
-
-            return f"{before}{content}{after}"
-
-        html = re.sub(pattern, replacer, html)
-
-    return html
+from flowmark.line_wrappers import LineWrapper
 
 
 # XXX Turn off Marko's parsing of block HTML.
@@ -94,11 +35,16 @@ class CustomParser(Parser):
         self.block_elements["HTMLBlock"] = CustomHTMLBlock
 
 
-class _MarkdownNormalizer(Renderer):
+class MarkdownNormalizer(Renderer):
     """
-    Render Markdown in normalized form. This is the internal implementation.
+    Render Markdown in normalized form. This is the internal implementation
+    which overrides most of `MarkdownRenderer`.
+
     You likely want to use `normalize_markdown()` instead.
-    Based on: https://github.com/frostming/marko/blob/master/marko/md_renderer.py
+
+    Based on:
+    https://github.com/frostming/marko/blob/master/marko/md_renderer.py
+    https://github.com/frostming/marko/blob/master/marko/ext/gfm/renderer.py
     """
 
     def __init__(self, line_wrapper: LineWrapper) -> None:
@@ -109,7 +55,7 @@ class _MarkdownNormalizer(Renderer):
         self._line_wrapper: LineWrapper = line_wrapper
 
     @override
-    def __enter__(self) -> _MarkdownNormalizer:
+    def __enter__(self) -> MarkdownNormalizer:
         self._prefix = ""
         self._second_prefix = ""
         return super().__enter__()
@@ -126,7 +72,14 @@ class _MarkdownNormalizer(Renderer):
         # Suppress item breaks on list items following a top-level paragraph.
         if not self._prefix:
             self._suppress_item_break = True
+
         children: Any = self.render_children(element)
+
+        # GFM checkbox support.
+        if hasattr(element, "checked"):
+            children = f"[{'x' if element.checked else ' '}] {children}"  # pyright: ignore
+
+        # Wrap the text.
         wrapped_text = self._line_wrapper(
             children,
             self._prefix,
@@ -211,7 +164,7 @@ class _MarkdownNormalizer(Renderer):
         self._prefix = self._second_prefix
         return result
 
-    def render_thematic_break(self, element: block.ThematicBreak) -> str:
+    def render_thematic_break(self, _element: block.ThematicBreak) -> str:
         result = f"{self._prefix}* * *\n"
         self._prefix = self._second_prefix
         return result
@@ -224,7 +177,7 @@ class _MarkdownNormalizer(Renderer):
     def render_setext_heading(self, element: block.SetextHeading) -> str:
         return self.render_heading(cast(block.Heading, element))  # pyright: ignore
 
-    def render_blank_line(self, element: block.BlankLine) -> str:
+    def render_blank_line(self, _element: block.BlankLine) -> str:
         if self._prefix.strip():
             result = f"{self._prefix}\n"
         else:
@@ -288,63 +241,62 @@ class _MarkdownNormalizer(Renderer):
             return f"`` {text} ``"
         return f"`{element.children}`"
 
+    # --- GFM Renderer Methods ---
 
-def split_sentences_no_min_length(text: str) -> list[str]:
-    return split_sentences_regex(text, min_length=0)
+    def render_strikethrough(self, element: gfm_elements.Strikethrough) -> str:
+        return f"~~{self.render_children(element)}~~"
 
+    def render_table(self, element: gfm_elements.Table) -> str:
+        """Render a GFM table."""
+        lines: list[str] = []
+        head, *body = element.children
+        lines.append(self.render(head))
+        lines.append(f"| {' | '.join(element.delimiters)} |\n")
+        for row in body:
+            lines.append(self.render(row))
+        return "".join(lines)
 
-def fill_markdown(
-    markdown_text: str,
-    dedent_input: bool = True,
-    width: int = DEFAULT_WRAP_WIDTH,
-    semantic: bool = False,
-    line_wrapper: LineWrapper | None = None,
-) -> str:
-    """
-    Normalize and wrap Markdown text filling paragraphs to the full width.
-
-    Wraps lines and adds line breaks within paragraphs and on
-    best-guess estimations of sentences, to make diffs more readable.
+    def render_table_row(self, element: gfm_elements.TableRow) -> str:
+        """Render a row within a GFM table."""
+        return f"| {' | '.join(self.render(cell) for cell in element.children)} |\n"
 
-    Also enforces that all list items have two newlines between them, so
-    that items are separate paragraphs when viewed as plaintext.
+    def render_table_cell(self, element: gfm_elements.TableCell) -> str:
+        """Render a cell within a GFM table row."""
+        return self.render_children(element).replace("|", "\\|")
 
-    Optionally also dedents and strips the input, so it can be used
-    on docstrings.
+    def render_url(self, element: gfm_elements.Url) -> str:
+        """For GFM autolink URLs, just output the URL directly."""
+        return element.dest
 
-    With `semantic` enabled, the line breaks are wrapped approximately
-    by sentence boundaries, to make diffs more readable.
 
-    Preserves YAML frontmatter (delimited by --- lines) if present at the
-    beginning of the document.
+def custom_marko(line_wrapper: LineWrapper) -> Markdown:
+    """
+    Marko Markdown setup for GFM with minor customizations and a
+    renderer that normalizes Markdown.
     """
-    if line_wrapper is None:
-        line_wrapper = (
-            line_wrap_by_sentence(width=width) if semantic else line_wrap_to_width(width=width)
-        )
-
-    # Extract frontmatter before any processing
-    frontmatter, content = split_frontmatter(markdown_text)
-
-    # Only format the content part if there's frontmatter
-    if frontmatter:
-        markdown_text = content
 
-    if dedent_input:
-        markdown_text = dedent(markdown_text).strip()
+    class CustomRenderer(MarkdownNormalizer):
+        def __init__(self) -> None:
+            super().__init__(line_wrapper)
 
-    markdown_text = markdown_text.strip() + "\n"
+    class CustomMarkdown(Markdown):
+        def __init__(self) -> None:  # pyright: ignore[reportMissingSuperCall]
+            pass
 
-    # If we want to normalize HTML blocks or comments.
-    markdown_text = _normalize_html_comments(markdown_text)
+        @override
+        def _setup_extensions(self) -> None:
+            # Using Marko's full extension system is tricky with our customizations so simpler
+            # to do this manually.
+            custom_parser = CustomParser()
+            for e in GFM.elements:
+                assert (
+                    e not in custom_parser.block_elements and e not in custom_parser.inline_elements
+                )
+                custom_parser.add_element(e)
 
-    # Normalize the markdown and wrap lines.
-    parser = CustomParser()
-    parsed = parser.parse(markdown_text)
-    result = _MarkdownNormalizer(line_wrapper).render(parsed)
+            self.parser: Parser = custom_parser
+            self.renderer: Renderer = CustomRenderer()
 
-    # Reattach frontmatter if it was present
-    if frontmatter:
-        result = frontmatter + result
+            self._setup_done: bool = True
 
-    return result
+    return CustomMarkdown()