kash-shell 0.3.10__py3-none-any.whl → 0.3.12__py3-none-any.whl

kash/text_handling/markdown_utils.py

@@ -1,5 +1,6 @@
 import re
-from typing import Any
+from textwrap import dedent
+from typing import Any, TypeAlias
 
 import marko
 import regex
@@ -11,6 +12,8 @@ from kash.utils.common.url import Url
 
 log = get_logger(__name__)
 
+HTag: TypeAlias = str
+
 # Characters that commonly need escaping in Markdown inline text.
 MARKDOWN_ESCAPE_CHARS = r"([\\`*_{}\[\]()#+.!-])"
 MARKDOWN_ESCAPE_RE = re.compile(MARKDOWN_ESCAPE_CHARS)
@@ -83,6 +86,19 @@ def extract_links(file_path: str, include_internal=False) -> list[str]:
         return _tree_links(document, include_internal)
 
 
+def extract_first_header(content: str) -> str | None:
+    """
+    Extract the first header from markdown content if present.
+    Also drops any formatting, so the result can be used as a document title.
+    """
+    document = marko.parse(content)
+
+    if document.children and isinstance(document.children[0], Heading):
+        return _extract_text(document.children[0]).strip()
+
+    return None
+
+
 def _extract_text(element: Any) -> str:
     if isinstance(element, str):
         return element
@@ -115,7 +131,7 @@ def extract_bullet_points(content: str) -> list[str]:
     return _tree_bullet_points(document)
 
 
-def _type_from_heading(heading: Heading) -> str:
+def _type_from_heading(heading: Heading) -> HTag:
     if heading.level in [1, 2, 3, 4, 5, 6]:
         return f"h{heading.level}"
     else:
@@ -161,6 +177,43 @@ def find_markdown_text(
         pos = match.end()
 
 
+def extract_headings(text: str) -> list[tuple[HTag, str]]:
+    """
+    Extract all Markdown headings from the given content.
+    Returns a list of (tag, text) tuples:
+    [("h1", "Main Title"), ("h2", "Subtitle")]
+    where `#` corresponds to `h1`, `##` to `h2`, etc.
+    """
+    document = marko.parse(text)
+    headings_list: list[tuple[HTag, str]] = []
+
+    def _collect_headings_recursive(element: Any) -> None:
+        if isinstance(element, Heading):
+            tag = _type_from_heading(element)
+            content = _extract_text(element).strip()
+            headings_list.append((tag, content))
+
+        if hasattr(element, "children"):
+            for child in element.children:
+                _collect_headings_recursive(child)
+
+    _collect_headings_recursive(document)
+
+    return headings_list
+
+
+def first_heading(text: str, *, allowed_tags: tuple[HTag, ...] = ("h1", "h2")) -> str | None:
+    """
+    Find the text of the first heading. Returns first h1 if present, otherwise first h2, etc.
+    """
+    headings = extract_headings(text)
+    for goal_tag in allowed_tags:
+        for h_tag, h_text in headings:
+            if h_tag == goal_tag:
+                return h_text
+    return None
+
+
 ## Tests
 
 
@@ -182,6 +235,15 @@ def test_escape_markdown() -> None:
     )
 
 
+def test_extract_first_header() -> None:
+    assert extract_first_header("# Header 1") == "Header 1"
+    assert extract_first_header("Not a header\n# Header later") is None
+    assert extract_first_header("") is None
+    assert (
+        extract_first_header("## *Formatted* _Header_ [link](#anchor)") == "Formatted Header link"
+    )
+
+
 def test_find_markdown_text() -> None:  # pragma: no cover
     # Match is returned when the term is not inside a link.
     text = "Foo bar baz"
@@ -202,3 +264,44 @@ def test_find_markdown_text() -> None:  # pragma: no cover
     pattern = re.compile("bar", re.IGNORECASE)
     match = find_markdown_text(pattern, text)
     assert match is None
+
+
+def test_extract_headings_and_first_header() -> None:
+    markdown_content = dedent("""
+        # Title 1
+        Some text.
+        ## Subtitle 1.1
+        More text.
+        ### Sub-subtitle 1.1.1
+        Even more text.
+        # Title 2 *with formatting*
+        And final text.
+        ## Subtitle 2.1
+        """)
+    expected_headings = [
+        ("h1", "Title 1"),
+        ("h2", "Subtitle 1.1"),
+        ("h3", "Sub-subtitle 1.1.1"),
+        ("h1", "Title 2 with formatting"),
+        ("h2", "Subtitle 2.1"),
+    ]
+    assert extract_headings(markdown_content) == expected_headings
+
+    assert first_heading(markdown_content) == "Title 1"
+    assert first_heading(markdown_content) == "Title 1"
+    assert first_heading(markdown_content, allowed_tags=("h2",)) == "Subtitle 1.1"
+    assert first_heading(markdown_content, allowed_tags=("h3",)) == "Sub-subtitle 1.1.1"
+    assert first_heading(markdown_content, allowed_tags=("h4",)) is None
+
+    assert extract_headings("") == []
+    assert first_heading("") is None
+    assert first_heading("Just text, no headers.") is None
+
+    markdown_h2_only = "## Only H2 Here"
+    assert extract_headings(markdown_h2_only) == [("h2", "Only H2 Here")]
+    assert first_heading(markdown_h2_only) == "Only H2 Here"
+    assert first_heading(markdown_h2_only, allowed_tags=("h2",)) == "Only H2 Here"
+
+    formatted_header_md = "## *Formatted* _Header_ [link](#anchor)"
+    assert extract_headings(formatted_header_md) == [("h2", "Formatted Header link")]
+    assert first_heading(formatted_header_md, allowed_tags=("h2",)) == "Formatted Header link"

kash/utils/common/format_utils.py

@@ -2,10 +2,9 @@ import html
 import re
 from pathlib import Path
 
-from inflect import engine
 from prettyfmt import fmt_path
 
-from kash.utils.common.lazyobject import lazyobject
+from kash.utils.common.inflection import plural
 from kash.utils.common.url import Locator, is_url
 
 
@@ -45,16 +44,11 @@ def fmt_loc(locator: str | Locator, resolve: bool = True) -> str:
         return fmt_path(locator, resolve=resolve)
 
 
-@lazyobject
-def inflect():
-    return engine()
-
-
 def fmt_count_items(count: int, name: str = "item") -> str:
     """
     Format a count and a name as a pluralized phrase, e.g. "1 item" or "2 items".
     """
-    return f"{count} {inflect.plural(name, count)}"  # pyright: ignore
+    return f"{count} {plural(name, count)}"  # pyright: ignore
 
 
 ## Tests