flowmark 0.1.0__tar.gz → 0.2.0__tar.gz

flowmark-0.2.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.3
+Name: flowmark
+Version: 0.2.0
+Summary: Better line wrapping and formatting for plaintext and Markdown
+License: MIT
+Author: Joshua Levy
+Author-email: joshua@cal.berkeley.edu
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: marko (>=2.1.2,<3.0.0)
+Requires-Dist: regex (>=2024.11.6,<2025.0.0)
+Requires-Dist: strif (>=2.0.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+# flowmark
+
+Flowmark is a new Python implementation of text line wrapping and filling.
+
+It simplifies and generalizes Python's
+[`textwrap`](https://docs.python.org/3/library/textwrap.html) with a few more
+capabilities:
+
+- Full customizability of initial and subsequent indentation strings
+
+- Control over when to split words, by default using a word splitter that won't break
+  lines within HTML tags
+
+In addition, it adds optional support for Markdown and offers Markdown auto-formatting,
+like [markdownfmt](https://github.com/shurcooL/markdownfmt), also with controllable line
+wrapping options.
+
+One key use case is to normalize Markdown in a standard, readable way that makes diffs
+easy to read and use on GitHub.
+This can be useful for documentation workflows and also to compare LLM outputs that are
+Markdown.
+
+Finally, it has options to use heuristics to split on sentences, which can make diffs
+much more readable. (For an example of this, look at the
+[Markdown source](https://github.com/jlevy/flowmark/blob/main/README.md?plain=1) of this
+readme file.)
+
+It aims to be small and simple and have only a few dependencies, currently only
+[`marko`](https://github.com/frostming/marko) and
+[`regex`](https://pypi.org/project/regex/).
+
+This is a new and simple package (previously I'd implemented something like this
+[for Atom](https://github.com/jlevy/atom-flowmark)) but I plan to add more support for
+command line usage and VSCode/Cursor auto-formatting in the future.
+
+## Installation
+
+The simplest way to use the tool is to use pipx:
+
+```shell
+pipx install flowmark
+```
+
+To use as a library, use pip or poetry to install `flowmark`.
+
+## Usage
+
+Flowmark can be used as a library or as a CLI.
+
+```
+$ flowmark --help
+usage: flowmark [-h] [-o OUTPUT] [-w WIDTH] [-p] [-s] [-i] [--nobackup] [file]
+
+Flowmark: Better line wrapping and formatting for plaintext and Markdown
+
+positional arguments:
+  file                 Input file (use '-' for stdin)
+
+options:
+  -h, --help           show this help message and exit
+  -o, --output OUTPUT  Output file (use '-' for stdout)
+  -w, --width WIDTH    Line width to wrap to
+  -p, --plaintext      Process as plaintext (no Markdown parsing)
+  -s, --sentences      Enable sentence-based line breaks (only applies to Markdown mode)
+  -i, --inplace        Edit the file in place (ignores --output)
+  --nobackup           Do not make a backup of the original file when using --inplace
+
+Flowmark provides enhanced text wrapping capabilities with special handling for
+Markdown content. It can:
+
+- Format Markdown with proper line wrapping while preserving structure
+  and normalizing Markdown formatting
+
+- 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.
+
+Command-line usage examples:
+
+  # Format a Markdown file to stdout
+  flowmark README.md
+
+  # Format a Markdown file and save to a new file
+  flowmark README.md -o README_formatted.md
+
+  # Edit a file in-place (with or without making a backup)
+  flowmark --inplace README.md
+  flowmark --inplace --nobackup README.md
+
+  # Process plaintext instead of Markdown
+  flowmark --plaintext text.txt
+
+  # Use sentences to guide line breaks (good for many purposes git history and diffs)
+  flowmark --sentences README.md
+
+For more details, see: https://github.com/jlevy/flowmark
+```
+
+* * *
+
+*This project was built from
+[simple-modern-poetry](https://github.com/jlevy/simple-modern-poetry).*
+

flowmark-0.2.0/README.md

@@ -0,0 +1,104 @@
+# flowmark
+
+Flowmark is a new Python implementation of text line wrapping and filling.
+
+It simplifies and generalizes Python's
+[`textwrap`](https://docs.python.org/3/library/textwrap.html) with a few more
+capabilities:
+
+- Full customizability of initial and subsequent indentation strings
+
+- Control over when to split words, by default using a word splitter that won't break
+  lines within HTML tags
+
+In addition, it adds optional support for Markdown and offers Markdown auto-formatting,
+like [markdownfmt](https://github.com/shurcooL/markdownfmt), also with controllable line
+wrapping options.
+
+One key use case is to normalize Markdown in a standard, readable way that makes diffs
+easy to read and use on GitHub.
+This can be useful for documentation workflows and also to compare LLM outputs that are
+Markdown.
+
+Finally, it has options to use heuristics to split on sentences, which can make diffs
+much more readable. (For an example of this, look at the
+[Markdown source](https://github.com/jlevy/flowmark/blob/main/README.md?plain=1) of this
+readme file.)
+
+It aims to be small and simple and have only a few dependencies, currently only
+[`marko`](https://github.com/frostming/marko) and
+[`regex`](https://pypi.org/project/regex/).
+
+This is a new and simple package (previously I'd implemented something like this
+[for Atom](https://github.com/jlevy/atom-flowmark)) but I plan to add more support for
+command line usage and VSCode/Cursor auto-formatting in the future.
+
+## Installation
+
+The simplest way to use the tool is to use pipx:
+
+```shell
+pipx install flowmark
+```
+
+To use as a library, use pip or poetry to install `flowmark`.
+
+## Usage
+
+Flowmark can be used as a library or as a CLI.
+
+```
+$ flowmark --help
+usage: flowmark [-h] [-o OUTPUT] [-w WIDTH] [-p] [-s] [-i] [--nobackup] [file]
+
+Flowmark: Better line wrapping and formatting for plaintext and Markdown
+
+positional arguments:
+  file                 Input file (use '-' for stdin)
+
+options:
+  -h, --help           show this help message and exit
+  -o, --output OUTPUT  Output file (use '-' for stdout)
+  -w, --width WIDTH    Line width to wrap to
+  -p, --plaintext      Process as plaintext (no Markdown parsing)
+  -s, --sentences      Enable sentence-based line breaks (only applies to Markdown mode)
+  -i, --inplace        Edit the file in place (ignores --output)
+  --nobackup           Do not make a backup of the original file when using --inplace
+
+Flowmark provides enhanced text wrapping capabilities with special handling for
+Markdown content. It can:
+
+- Format Markdown with proper line wrapping while preserving structure
+  and normalizing Markdown formatting
+
+- 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.
+
+Command-line usage examples:
+
+  # Format a Markdown file to stdout
+  flowmark README.md
+
+  # Format a Markdown file and save to a new file
+  flowmark README.md -o README_formatted.md
+
+  # Edit a file in-place (with or without making a backup)
+  flowmark --inplace README.md
+  flowmark --inplace --nobackup README.md
+
+  # Process plaintext instead of Markdown
+  flowmark --plaintext text.txt
+
+  # Use sentences to guide line breaks (good for many purposes git history and diffs)
+  flowmark --sentences README.md
+
+For more details, see: https://github.com/jlevy/flowmark
+```
+
+* * *
+
+*This project was built from
+[simple-modern-poetry](https://github.com/jlevy/simple-modern-poetry).*

{flowmark-0.1.0 → flowmark-0.2.0}/pyproject.toml

@@ -1,27 +1,43 @@
-[tool.poetry]
+[project]
 name = "flowmark"
-# Keep this a dev version, as the dynamic versioning plugin is used for actual release versions:
-version = "0.1.0"
 description = "Better line wrapping and formatting for plaintext and Markdown"
-authors = ["Joshua Levy <joshua@cal.berkeley.edu>"]
+authors = [
+    { name="Joshua Levy", email="joshua@cal.berkeley.edu" },
+]
 readme = "README.md"
 license = "MIT"
-repository = "https://github.com/jlevy/flowmark"
+requires-python = ">=3.10,<4.0"
+dynamic = [ "dependencies", ]
+version = "0.2.0"
+
+[tool.poetry]
 requires-poetry = ">=2.0"
+packages = [
+    { include = "flowmark", from = "src" },
+]
+# Keep this a dev version, as the dynamic versioning plugin is used for actual release versions:
+
+# See: https://github.com/mtkennerly/poetry-dynamic-versioning
+[build-system]
+requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning>=1.7.0,<2.0.0"]
+build-backend = "poetry_dynamic_versioning.backend"
 
-# Useful plugins:
+[project.scripts]
+# Add script entry points here.
+flowmark = "flowmark.cli:main"
+
+# See:
 # https://github.com/python-poetry/poetry-plugin-shell
-# https://github.com/mtkennerly/poetry-dynamic-versioning
 # https://github.com/MousaZeidBaker/poetry-plugin-up
 [tool.poetry.requires-plugins]
 poetry-plugin-shell = "^1.0.1"
-poetry-dynamic-versioning = "^1.7.0"
 poetry-plugin-up = "^0.9.0"
 
 [tool.poetry.dependencies]
-python = "^3.10"
+python = "^3.10,<4.0"
 marko = "^2.1.2"
 regex = "^2024.11.6"
+strif = "^2.0.0"
 
 [tool.poetry.group.dev.dependencies]
 black = "^24.10.0"
@@ -32,10 +48,6 @@ mypy = "^1.15.0"
 codespell = "^2.4.1"
 rich = "^13.9.4"
 
-[build-system]
-requires = ["poetry-core"]
-build-backend = "poetry.core.masonry.api"
-
 # Auto-generated version for builds based on git tag or commit.
 #
 # Preferred styles of versioning (PEP 440 compliant):
@@ -61,10 +73,10 @@ format-jinja = """{%- if distance == 0 -%}
     {%- endif -%}"""
 
 [tool.black]
-line-length = 88
+line-length = 100
 
 [tool.ruff]
-line-length = 88
+line-length = 100
 
 [tool.ruff.lint]
 ignore = ["E402", "E731", "E712"]

flowmark-0.2.0/src/flowmark/__init__.py

@@ -0,0 +1,14 @@
+__all__ = (
+    "fill_text",
+    "fill_markdown",
+    "html_md_word_splitter",
+    "line_wrap_by_sentence",
+    "line_wrap_to_width",
+    "wrap_paragraph",
+    "wrap_paragraph_lines",
+    "Wrap",
+)
+
+from .markdown_filling import fill_markdown, line_wrap_by_sentence, line_wrap_to_width
+from .text_filling import fill_text, Wrap
+from .text_wrapping import html_md_word_splitter, wrap_paragraph, wrap_paragraph_lines

flowmark-0.2.0/src/flowmark/cli.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""
+Flowmark: Better line wrapping and formatting for plaintext and Markdown
+
+Flowmark provides enhanced text wrapping capabilities with special handling for
+Markdown content. It can:
+
+- Format Markdown with proper line wrapping while preserving structure
+  and normalizing Markdown formatting
+
+- 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.
+
+Command-line usage examples:
+
+  # Format a Markdown file to stdout
+  flowmark README.md
+
+  # Format a Markdown file and save to a new file
+  flowmark README.md -o README_formatted.md
+
+  # Edit a file in-place (with or without making a backup)
+  flowmark --inplace README.md
+  flowmark --inplace --nobackup README.md
+
+  # Process plaintext instead of Markdown
+  flowmark --plaintext text.txt
+
+  # Use sentences to guide line breaks (good for many purposes git history and diffs)
+  flowmark --sentences README.md
+
+For more details, see: https://github.com/jlevy/flowmark
+"""
+
+import argparse
+import sys
+from dataclasses import dataclass
+from typing import List, Optional
+
+from strif import atomic_output_file
+
+from flowmark import fill_markdown, fill_text, html_md_word_splitter, Wrap
+
+
+@dataclass
+class Options:
+    """Command-line options for the flowmark tool."""
+
+    file: str
+    output: str
+    width: int
+    plaintext: bool
+    sentences: bool
+    inplace: bool
+    nobackup: bool
+
+
+def _parse_args(args: Optional[List[str]] = None) -> Options:
+    """Parse command-line arguments for the flowmark tool."""
+    # Use the module's docstring as the description
+    module_doc = __doc__ or ""
+    doc_parts = module_doc.split("\n\n")
+    description = doc_parts[0]
+    epilog = "\n\n".join(doc_parts[1:])
+
+    parser = argparse.ArgumentParser(
+        description=description,
+        epilog=epilog,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "file",
+        nargs="?",
+        type=str,
+        default="-",
+        help="Input file (use '-' for stdin)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=str,
+        default="-",
+        help="Output file (use '-' for stdout)",
+    )
+    parser.add_argument("-w", "--width", type=int, default=88, help="Line width to wrap to")
+    parser.add_argument(
+        "-p", "--plaintext", action="store_true", help="Process as plaintext (no Markdown parsing)"
+    )
+    parser.add_argument(
+        "-s",
+        "--sentences",
+        action="store_true",
+        default=True,
+        help="Enable sentence-based line breaks (only applies to Markdown mode)",
+    )
+    parser.add_argument(
+        "-i", "--inplace", action="store_true", help="Edit the file in place (ignores --output)"
+    )
+    parser.add_argument(
+        "--nobackup",
+        action="store_true",
+        help="Do not make a backup of the original file when using --inplace",
+    )
+    parsed_args = parser.parse_args(args)
+
+    return Options(
+        file=parsed_args.file,
+        output=parsed_args.output,
+        width=parsed_args.width,
+        plaintext=parsed_args.plaintext,
+        sentences=parsed_args.sentences,
+        inplace=parsed_args.inplace,
+        nobackup=parsed_args.nobackup,
+    )
+
+
+def main(args: Optional[List[str]] = None) -> int:
+    """
+    Main entry point for the flowmark CLI.
+
+    Args:
+        args: Command-line arguments (uses sys.argv if None)
+
+    Returns:
+        Exit code (0 for success, non-zero for errors)
+    """
+    options = _parse_args(args)
+
+    # Handle input.
+    if options.file == "-":
+        text = sys.stdin.read()
+    else:
+        with open(options.file, "r") as f:
+            text = f.read()
+
+    if options.plaintext:
+        # Plaintext mode
+        result = fill_text(
+            text,
+            text_wrap=Wrap.WRAP,
+            width=options.width,
+            word_splitter=html_md_word_splitter,  # Still use HTML/MD aware splitter by default
+        )
+    else:
+        # Markdown mode
+        result = fill_markdown(
+            text,
+            width=options.width,
+            by_sentence=options.sentences,
+            dedent_input=True,
+        )
+
+    # Handle output
+    if options.inplace:
+        if options.file == "-":
+            print("Error: Cannot use --inplace with stdin", file=sys.stderr)
+            return 1
+        backup_suffix = ".orig" if not options.nobackup else ""
+        with atomic_output_file(options.file, backup_suffix=backup_suffix) as tmp_path:
+            with open(tmp_path, "w") as f:
+                f.write(result)
+    else:
+        if options.output == "-":
+            sys.stdout.write(result)
+        else:
+            with open(options.output, "w") as f:
+                f.write(result)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

flowmark-0.2.0/src/flowmark/line_wrappers.py

@@ -0,0 +1,105 @@
+from typing import Callable, List, Protocol
+
+from flowmark.sentence_split_regex import split_sentences_regex
+from flowmark.text_filling import DEFAULT_WRAP_WIDTH
+from flowmark.text_wrapping import DEFAULT_LEN_FUNCTION, wrap_paragraph, wrap_paragraph_lines
+
+
+DEFAULT_MIN_LINE_LEN = 20
+"""Default minimum line length for sentence breaking."""
+
+
+class LineWrapper(Protocol):
+    """
+    Takes a text string and any indents to use, and returns the wrapped text.
+    """
+
+    def __call__(self, text: str, initial_indent: str, subsequent_indent: str) -> str: ...
+
+
+class SentenceSplitter(Protocol):
+    """Takes a text string and returns a list of sentences."""
+
+    def __call__(self, text: str) -> List[str]: ...
+
+
+def split_sentences_no_min_length(text: str) -> List[str]:
+    return split_sentences_regex(text, min_length=0)
+
+
+def line_wrap_to_width(
+    width: int = DEFAULT_WRAP_WIDTH,
+    len_fn: Callable[[str], int] = DEFAULT_LEN_FUNCTION,
+) -> LineWrapper:
+    """
+    Wrap lines of text to a given width.
+    """
+
+    def line_wrapper(text: str, initial_indent: str, subsequent_indent: str) -> str:
+        return wrap_paragraph(
+            text,
+            width=width,
+            initial_indent=initial_indent,
+            subsequent_indent=subsequent_indent,
+            len_fn=len_fn,
+        )
+
+    return line_wrapper
+
+
+def line_wrap_by_sentence(
+    split_sentences: SentenceSplitter = split_sentences_no_min_length,
+    width: int = DEFAULT_WRAP_WIDTH,
+    min_line_len: int = DEFAULT_MIN_LINE_LEN,
+    len_fn: Callable[[str], int] = DEFAULT_LEN_FUNCTION,
+) -> LineWrapper:
+    """
+    Wrap lines of text to a given width but also keep sentences on their own lines.
+    If the last line ends up shorter than `min_line_len`, it's combined with the
+    next sentence.
+    """
+
+    def line_wrapper(text: str, initial_indent: str, subsequent_indent: str) -> str:
+        text = text.replace("\n", " ")
+        lines: List[str] = []
+        first_line = True
+        length = len_fn
+        initial_indent_len = len_fn(initial_indent)
+        subsequent_indent_len = len_fn(subsequent_indent)
+
+        sentences = split_sentences(text)
+
+        for i, sentence in enumerate(sentences):
+            current_column = initial_indent_len if first_line else subsequent_indent_len
+            if len(lines) > 0 and length(lines[-1]) < min_line_len:
+                current_column += length(lines[-1])
+
+            wrapped = wrap_paragraph_lines(
+                sentence,
+                width=width,
+                initial_column=current_column,
+                subsequent_offset=subsequent_indent_len,
+            )
+            # If last line is shorter than min_line_len, combine with next line.
+            # Also handles if the first word doesn't fit.
+            if (
+                len(lines) > 0
+                and length(lines[-1]) < min_line_len
+                and length(lines[-1]) + 1 + length(wrapped[0]) <= width
+            ):
+                lines[-1] += " " + wrapped[0]
+                wrapped.pop(0)
+
+            lines.extend(wrapped)
+
+            first_line = False
+
+        # Now insert the indents and assemble the paragraph.
+        if initial_indent and len(lines) > 0:
+            lines[0] = initial_indent + lines[0]
+        if subsequent_indent and len(lines) > 1:
+            lines[1:] = [subsequent_indent + line for line in lines[1:]]
+
+        return "\n".join(lines)
+
+    return line_wrapper

{flowmark-0.1.0 → flowmark-0.2.0}/src/flowmark/markdown_filling.py

@@ -12,7 +12,7 @@ discussion on why line wrapping this way is convenient.)
 import re
 from contextlib import contextmanager
 from textwrap import dedent
-from typing import Callable, cast, Generator, List, Protocol, Tuple
+from typing import Callable, cast, Generator, List, Optional, Tuple
 
 from marko import block, inline
 from marko.block import HTMLBlock
@@ -20,34 +20,9 @@ from marko.parser import Parser
 from marko.renderer import Renderer
 from marko.source import Source
 
-from .sentence_split_regex import split_sentences_regex
-from .text_wrapping import DEFAULT_LEN_FUNCTION, wrap_paragraph, wrap_paragraph_lines
-
-
-DEFAULT_WRAP_WIDTH = 88
-"""
-Default wrap width for Markdown content. This is a compromise between traditional
-but sometimes impractically narrow 80-char console width and being too wide to
-read comfortably for text, markup, and code. 88 is the same as Black.
-"""
-
-
-DEFAULT_MIN_LINE_LEN = 20
-"""Default minimum line length for sentence breaking."""
-
-
-class LineWrapper(Protocol):
-    """Takes a text string and any indents to use, and returns the wrapped text."""
-
-    def __call__(
-        self, text: str, initial_indent: str, subsequent_indent: str
-    ) -> str: ...
-
-
-class SentenceSplitter(Protocol):
-    """Takes a text string and returns a list of sentences."""
-
-    def __call__(self, text: str) -> List[str]: ...
+from flowmark.line_wrappers import line_wrap_by_sentence, line_wrap_to_width, LineWrapper
+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:
@@ -73,9 +48,7 @@ def _ensure_surrounding_breaks(
     break_str: str = "\n\n",
 ) -> str:
     for start_tag, end_tag in tag_pairs:
-        pattern = re.compile(
-            rf"(\s*{re.escape(start_tag)}.*?{re.escape(end_tag)}\s*)", re.DOTALL
-        )
+        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)):
@@ -123,9 +96,7 @@ class _MarkdownNormalizer(Renderer):
 
     def __init__(self, line_wrapper: LineWrapper) -> None:
         super().__init__()
-        self._prefix: str = (
-            ""  # The prefix on the first line, with a bullet, such as `  - `.
-        )
+        self._prefix: str = ""  # The prefix on the first line, with a bullet, such as `  - `.
         self._second_prefix: str = ""  # The prefix on subsequent lines, such as `    `.
         self._suppress_item_break: bool = True
         self._line_wrapper = line_wrapper
@@ -136,9 +107,7 @@ class _MarkdownNormalizer(Renderer):
         return super().__enter__()
 
     @contextmanager
-    def container(
-        self, prefix: str, second_prefix: str = ""
-    ) -> Generator[None, None, None]:
+    def container(self, prefix: str, second_prefix: str = "") -> Generator[None, None, None]:
         old_prefix, old_second_prefix = self._prefix, self._second_prefix
         self._prefix += prefix
         self._second_prefix += second_prefix
@@ -199,9 +168,7 @@ class _MarkdownNormalizer(Renderer):
         extra_text = f" {extra}" if extra else ""
         lang_text = f"{lang}{extra_text}" if lang else ""
         lines = [f"{self._prefix}```{lang_text}"]
-        lines.extend(
-            f"{self._second_prefix}{line}" for line in code_content.splitlines()
-        )
+        lines.extend(f"{self._second_prefix}{line}" for line in code_content.splitlines())
         lines.append(f"{self._second_prefix}```")
         self._prefix = self._second_prefix
         return "\n".join(lines) + "\n"
@@ -224,9 +191,7 @@ class _MarkdownNormalizer(Renderer):
         return result
 
     def render_heading(self, element: block.Heading) -> str:
-        result = (
-            f"{self._prefix}{'#' * element.level} {self.render_children(element)}\n"
-        )
+        result = f"{self._prefix}{'#' * element.level} {self.render_children(element)}\n"
         self._prefix = self._second_prefix
         return result
 
@@ -259,16 +224,10 @@ class _MarkdownNormalizer(Renderer):
 
     def render_link(self, element: inline.Link) -> str:
         link_text = self.render_children(element)
-        link_title = (
-            '"{}"'.format(element.title.replace('"', '\\"')) if element.title else None
-        )
+        link_title = '"{}"'.format(element.title.replace('"', '\\"')) if element.title else None
         assert self.root_node
         label = next(
-            (
-                k
-                for k, v in self.root_node.link_ref_defs.items()
-                if v == (element.dest, link_title)
-            ),
+            (k for k, v in self.root_node.link_ref_defs.items() if v == (element.dest, link_title)),
             None,
         )
         if label is not None:
@@ -283,9 +242,7 @@ class _MarkdownNormalizer(Renderer):
 
     def render_image(self, element: inline.Image) -> str:
         template = "![{}]({}{})"
-        title = (
-            ' "{}"'.format(element.title.replace('"', '\\"')) if element.title else ""
-        )
+        title = ' "{}"'.format(element.title.replace('"', '\\"')) if element.title else ""
         return template.format(self.render_children(element), element.dest, title)
 
     def render_literal(self, element: inline.Literal) -> str:
@@ -310,89 +267,33 @@ def split_sentences_no_min_length(text: str) -> List[str]:
     return split_sentences_regex(text, min_length=0)
 
 
-def wrap_lines_to_width(
-    text: str,
-    initial_indent: str,
-    subsequent_indent: str,
+def fill_markdown(
+    markdown_text: str,
+    dedent_input: bool = True,
     width: int = DEFAULT_WRAP_WIDTH,
+    by_sentence: bool = False,
+    line_wrapper: Optional[LineWrapper] = None,
 ) -> str:
     """
-    Wrap lines of text to a given width.
-    """
-    return wrap_paragraph(
-        text,
-        width=width,
-        initial_indent=initial_indent,
-        subsequent_indent=subsequent_indent,
-    )
+    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 wrap_lines_using_sentences(
-    text: str,
-    initial_indent: str,
-    subsequent_indent: str,
-    split_sentences: SentenceSplitter = split_sentences_no_min_length,
-    width: int = DEFAULT_WRAP_WIDTH,
-    min_line_len: int = DEFAULT_MIN_LINE_LEN,
-    len_fn: Callable[[str], int] = DEFAULT_LEN_FUNCTION,
-) -> str:
-    """
-    Wrap lines of text to a given width but also keep sentences on their own lines.
-    If the last line ends up shorter than min_line_len, it's combined with the next sentence.
+    Also enforces that all list items have two newlines between them, so
+    that items are separate paragraphs when viewed as plaintext.
+
+    Optionally also dedents and strips the input, so it can be used
+    on docstrings.
     """
-    text = text.replace("\n", " ")
-    lines: List[str] = []
-    first_line = True
-    length = len_fn
-    initial_indent_len = len_fn(initial_indent)
-    subsequent_indent_len = len_fn(subsequent_indent)
-
-    sentences = split_sentences(text)
-
-    for i, sentence in enumerate(sentences):
-        current_column = initial_indent_len if first_line else subsequent_indent_len
-        if len(lines) > 0 and length(lines[-1]) < min_line_len:
-            current_column += length(lines[-1])
-
-        wrapped = wrap_paragraph_lines(
-            sentence,
-            width=width,
-            initial_column=current_column,
-            subsequent_offset=subsequent_indent_len,
+    if line_wrapper is None:
+        line_wrapper = (
+            line_wrap_by_sentence(width=width) if by_sentence else line_wrap_to_width(width=width)
         )
-        # If last line is shorter than min_line_len, combine with next line.
-        # Also handles if the first word doesn't fit.
-        if (
-            len(lines) > 0
-            and length(lines[-1]) < min_line_len
-            and length(lines[-1]) + 1 + length(wrapped[0]) <= width
-        ):
-            lines[-1] += " " + wrapped[0]
-            wrapped.pop(0)
-
-        lines.extend(wrapped)
-
-        first_line = False
-
-    # Now insert the indents and assemble the paragraph.
-    if initial_indent and len(lines) > 0:
-        lines[0] = initial_indent + lines[0]
-    if subsequent_indent and len(lines) > 1:
-        lines[1:] = [subsequent_indent + line for line in lines[1:]]
-
-    return "\n".join(lines)
 
+    if dedent_input:
+        markdown_text = dedent(markdown_text).strip()
 
-def normalize_markdown(
-    markdown_text: str, line_wrapper: LineWrapper = wrap_lines_using_sentences
-) -> str:
-    """
-    Normalize Markdown text. Wraps lines and adds line breaks within paragraphs and on
-    best-guess estimations of sentences, to make diffs more readable.
-
-    Also enforces that all list items have two newlines between them, so that items
-    are separate paragraphs when viewed as plaintext.
-    """
     markdown_text = markdown_text.strip() + "\n"
 
     # If we want to normalize HTML blocks or comments.
@@ -403,17 +304,3 @@ def normalize_markdown(
     parsed = parser.parse(markdown_text)
     result = _MarkdownNormalizer(line_wrapper).render(parsed)
     return result
-
-
-def fill_markdown(
-    markdown_text: str,
-    dedent_input: bool = True,
-    line_wrapper: LineWrapper = wrap_lines_to_width,
-) -> str:
-    """
-    Normalize and wrap Markdown text filling paragraphs to the full width.
-    Also dedents and strips the input, so it can be used on docstrings.
-    """
-    if dedent_input:
-        markdown_text = dedent(markdown_text).strip()
-    return normalize_markdown(markdown_text, line_wrapper=line_wrapper)

{flowmark-0.1.0 → flowmark-0.2.0}/src/flowmark/text_filling.py

@@ -2,7 +2,7 @@ import re
 from enum import Enum
 from typing import Callable, List
 
-from .text_wrapping import (
+from flowmark.text_wrapping import (
     DEFAULT_LEN_FUNCTION,
     html_md_word_splitter,
     WordSplitter,
@@ -10,6 +10,12 @@ from .text_wrapping import (
 )
 
 DEFAULT_WRAP_WIDTH = 88
+"""
+Default wrap width. This is a compromise between traditional but sometimes
+impractically narrow 80-char console width and being too wide to read comfortably
+for text, markup, and code. 88 is the same as Black.
+"""
+
 
 DEFAULT_INDENT = "    "
 
@@ -98,11 +104,7 @@ def fill_text(
     """
 
     if not text_wrap.should_wrap:
-        indent = (
-            extra_indent + DEFAULT_INDENT
-            if text_wrap == Wrap.INDENT_ONLY
-            else extra_indent
-        )
+        indent = extra_indent + DEFAULT_INDENT if text_wrap == Wrap.INDENT_ONLY else extra_indent
         lines = text.splitlines()
         if lines:
             return "\n".join(indent + line for line in lines)

flowmark-0.1.0/PKG-INFO

@@ -1,53 +0,0 @@
-Metadata-Version: 2.3
-Name: flowmark
-Version: 0.1.0
-Summary: Better line wrapping and formatting for plaintext and Markdown
-License: MIT
-Author: Joshua Levy
-Author-email: joshua@cal.berkeley.edu
-Requires-Python: >=3.10,<4.0
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: marko (>=2.1.2,<3.0.0)
-Requires-Dist: regex (>=2024.11.6,<2025.0.0)
-Project-URL: Repository, https://github.com/jlevy/flowmark
-Description-Content-Type: text/markdown
-
-# flowmark
-
-Flowmark is a new Python implementation of text line wrapping and filling.
-
-It can be used as a more flexible alternative to Python's
-[`textwrap`](https://docs.python.org/3/library/textwrap.html) with a few more features,
-such as full customizability of initial and subsequent indentation strings, and more
-control over when to split words, so it won't break lines within HTML tags.
-
-It also combines line wrapping with support for Markdown and offers Markdown
-auto-formatting, like [markdownfmt](https://github.com/shurcooL/markdownfmt), also with
-controllable line wrapping options.
-
-One key use case is to normalize Markdown in a standard, readable way that makes diffs
-easy to read and use on GitHub.
-This can be useful for documentation workflows and also to compare LLM outputs that are
-Markdown.
-
-Finally, it has options to use heuristics to split on sentences, which can make diffs
-much more readable. (For an example of this, look at the source to this readme file.)
-
-It aims to be small and simple and have only a few dependencies, currently only
-[`marko`](https://github.com/frostming/marko) and
-[`regex`](https://pypi.org/project/regex/).
-
-This is a new and simple package (previously I'd implemented something like this
-[for Atom](https://github.com/jlevy/atom-flowmark)) but I plan to add more support for
-command line usage and VSCode/Cursor auto-formatting in the future.
-
-* * *
-
-*This project was built from
-[simple-modern-poetry](https://github.com/jlevy/simple-modern-poetry).*
-

flowmark-0.1.0/README.md

@@ -1,33 +0,0 @@
-# flowmark
-
-Flowmark is a new Python implementation of text line wrapping and filling.
-
-It can be used as a more flexible alternative to Python's
-[`textwrap`](https://docs.python.org/3/library/textwrap.html) with a few more features,
-such as full customizability of initial and subsequent indentation strings, and more
-control over when to split words, so it won't break lines within HTML tags.
-
-It also combines line wrapping with support for Markdown and offers Markdown
-auto-formatting, like [markdownfmt](https://github.com/shurcooL/markdownfmt), also with
-controllable line wrapping options.
-
-One key use case is to normalize Markdown in a standard, readable way that makes diffs
-easy to read and use on GitHub.
-This can be useful for documentation workflows and also to compare LLM outputs that are
-Markdown.
-
-Finally, it has options to use heuristics to split on sentences, which can make diffs
-much more readable. (For an example of this, look at the source to this readme file.)
-
-It aims to be small and simple and have only a few dependencies, currently only
-[`marko`](https://github.com/frostming/marko) and
-[`regex`](https://pypi.org/project/regex/).
-
-This is a new and simple package (previously I'd implemented something like this
-[for Atom](https://github.com/jlevy/atom-flowmark)) but I plan to add more support for
-command line usage and VSCode/Cursor auto-formatting in the future.
-
-* * *
-
-*This project was built from
-[simple-modern-poetry](https://github.com/jlevy/simple-modern-poetry).*

flowmark-0.1.0/src/flowmark/__init__.py

@@ -1,19 +0,0 @@
-__all__ = (
-    "fill_text",
-    "fill_markdown",
-    "normalize_markdown",
-    "wrap_paragraph",
-    "wrap_paragraph_lines",
-    "wrap_lines_to_width",
-    "wrap_lines_using_sentences",
-    "Wrap",
-)
-
-from .markdown_filling import (
-    fill_markdown,
-    normalize_markdown,
-    wrap_lines_to_width,
-    wrap_lines_using_sentences,
-)
-from .text_filling import fill_text, Wrap
-from .text_wrapping import wrap_paragraph, wrap_paragraph_lines