line-markdown-parser 0.1.2__py3-none-any.whl

line_markdown_parser/converter.py

@@ -0,0 +1,260 @@
+"""Public conversion API and size-aware splitting.
+
+All results are fresh JSON-compatible dictionaries. No input is logged, cached
+across calls, sent over the network, or written to disk.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable
+from typing import Any
+
+from ._renderer import _iter_links
+from ._renderer import build_flex_contents as _render_contents
+
+DEFAULT_MAX_FLEX_PAYLOAD_BYTES = 28_000
+_MAX_BUBBLE_BYTES = 30_000
+_MAX_ALT_TEXT_UNITS = 1_500
+_MAX_INPUT_BYTES = 200_000
+# Keep fence recognition aligned with the renderer's supported Markdown subset.
+_CODE_FENCE_RE = re.compile(r"(```[\s\S]*?```)")
+
+
+def _require_text(text: str) -> str:
+    if not isinstance(text, str):
+        raise TypeError("text must be a string")
+    if any(0xD800 <= ord(char) <= 0xDFFF for char in text):
+        raise ValueError("text must contain valid Unicode scalar values")
+    if len(text.encode("utf-8")) > _MAX_INPUT_BYTES:
+        raise ValueError("text exceeds the 200,000-byte UTF-8 input limit")
+    return text
+
+
+def build_flex_contents(text: str) -> list[dict[str, Any]]:
+    """Build body components without a bubble, footer, or delivery metadata.
+
+    This low-level function does not split or enforce the bubble byte limit.
+    """
+    _require_text(text)
+    if not text.strip():
+        return []
+    contents = _render_contents(text)
+    # Separators alone can be removed by the renderer. A bubble cannot be empty.
+    return contents or [{"type": "text", "text": text.strip(), "wrap": True}]
+
+
+def _bubble(text: str) -> dict[str, Any]:
+    return {
+        "type": "bubble",
+        "size": "giga",
+        "body": {
+            "type": "box",
+            "layout": "vertical",
+            "contents": build_flex_contents(text),
+            "paddingAll": "16px",
+            "backgroundColor": "#FFFFFF",
+        },
+    }
+
+
+def _json_size(value: dict[str, Any]) -> int:
+    return len(
+        json.dumps(value, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+    )
+
+
+def estimate_flex_payload_size(text: str) -> int:
+    """Return compact UTF-8 JSON bytes of the bubble (not the HTTP envelope).
+
+    Use the same JSON serialization for delivery. The default split budget
+    reserves 2,000 bytes below LINE's 30 KB bubble limit.
+    """
+    return _json_size(_bubble(_require_text(text)))
+
+
+def _alt_text(text: str) -> str:
+    text = _require_text(text).strip()
+    if not text:
+        raise ValueError("alt_text must not be empty")
+    units = 0
+    end = 0
+    for end, char in enumerate(text, start=1):
+        units += 2 if ord(char) > 0xFFFF else 1
+        if units > _MAX_ALT_TEXT_UNITS:
+            # The truncation marker itself consumes one UTF-16 code unit.
+            prefix = text[: end - 1]
+            while len(prefix.encode("utf-16-le")) // 2 >= _MAX_ALT_TEXT_UNITS:
+                prefix = prefix[:-1]
+            return prefix + "…"
+    return text
+
+
+def build_flex_message(text: str, *, alt_text: str | None = None) -> dict[str, Any]:
+    """Build one standalone Flex message; raise ValueError if it exceeds 30 KB.
+
+    Use convert_markdown_to_line_messages for automatic splitting. alt_text
+    defaults to the source text and is bounded to 1,500 UTF-16 code units.
+    """
+    _require_text(text)
+    if not text.strip():
+        raise ValueError("text must not be empty")
+    bubble = _bubble(text)
+    if _json_size(bubble) > _MAX_BUBBLE_BYTES:
+        raise ValueError(
+            "bubble exceeds 30,000 bytes; use convert_markdown_to_line_messages"
+        )
+    return {
+        "type": "flex",
+        "altText": _alt_text(text if alt_text is None else alt_text),
+        "contents": bubble,
+    }
+
+
+def _validate_limits(max_length: int, max_payload_bytes: int) -> None:
+    if (
+        isinstance(max_length, bool)
+        or not isinstance(max_length, int)
+        or max_length < 1
+    ):
+        raise ValueError("max_length must be a positive integer")
+    if (
+        isinstance(max_payload_bytes, bool)
+        or not isinstance(max_payload_bytes, int)
+        or not 1 <= max_payload_bytes <= _MAX_BUBBLE_BYTES
+    ):
+        raise ValueError("max_payload_bytes must be an integer between 1 and 30,000")
+
+
+def split_long_text(
+    text: str,
+    max_length: int = 1600,
+    max_payload_bytes: int = DEFAULT_MAX_FLEX_PAYLOAD_BYTES,
+) -> list[str]:
+    """Split Markdown into pieces that fit both source length and rendered bytes.
+
+    Prefer paragraph/line/word boundaries. Closed triple-backtick code fences
+    are repeated around each code fragment, including a single oversized line.
+    Other inline syntax may become plain text when split. Impossible budgets
+    raise ValueError; no over-budget fragment is returned.
+    """
+    _require_text(text)
+    _validate_limits(max_length, max_payload_bytes)
+    if not text.strip():
+        return []
+
+    def fits(candidate: str) -> bool:
+        return (
+            len(candidate) <= max_length
+            and estimate_flex_payload_size(candidate) <= max_payload_bytes
+        )
+
+    def split_unit(
+        body: str, wrap: Callable[[str], str], *, preserve_links: bool = False
+    ) -> list[str]:
+        if fits(wrap(body)):
+            return [wrap(body)]
+        pieces: list[str] = []
+        start = 0
+        overhead = len(wrap(""))
+        link_ranges = (
+            [(link.start, link.end) for link in _iter_links(body)]
+            if preserve_links
+            else []
+        )
+
+        def safe_boundary(end: int) -> int:
+            for link_start, link_end in link_ranges:
+                if link_start < end < link_end:
+                    return link_start
+            return end
+
+        while start < len(body):
+            end = safe_boundary(min(len(body), start + max_length - overhead))
+            while end > start and not fits(wrap(body[start:end])):
+                end = safe_boundary(start + (end - start) * 3 // 4)
+            if end <= start:
+                # Shrinking is conservative, and can jump past a whole link.
+                # Try that atomic token before declaring the budget impossible.
+                for link_start, link_end in link_ranges:
+                    if link_start == start and fits(wrap(body[start:link_end])):
+                        end = link_end
+                        break
+            if end <= start:
+                raise ValueError(
+                    "limits are too small for a rendered fragment or intact link"
+                )
+            if end < len(body):
+                # Keep at least half the fitting candidate to avoid tiny chunks.
+                for separator in ("\n\n", "\n", " "):
+                    boundary = body.rfind(separator, start + (end - start) // 2, end)
+                    if boundary >= 0:
+                        preferred_end = safe_boundary(boundary + len(separator))
+                        if preferred_end > start and fits(
+                            wrap(body[start:preferred_end])
+                        ):
+                            end = preferred_end
+                            break
+            pieces.append(wrap(body[start:end]))
+            start = end
+        if not pieces:
+            raise ValueError("limits are too small for an empty fenced block")
+        return pieces
+
+    if fits(text):
+        return [text]
+
+    chunks: list[str] = []
+    for segment in _CODE_FENCE_RE.split(text):
+        if not segment:
+            continue
+        if _CODE_FENCE_RE.fullmatch(segment) and "\n" in segment:
+            header, body = segment[:-3].split("\n", 1)
+            if body.endswith("\n"):
+                body = body[:-1]
+
+            def wrap_code(piece: str, opening: str = header) -> str:
+                return opening + "\n" + piece + "\n```"
+
+            chunks.extend(split_unit(body, wrap_code))
+        else:
+            chunks.extend(split_unit(segment, lambda piece: piece, preserve_links=True))
+
+    parts: list[str] = []
+    current = ""
+    for chunk in chunks:
+        candidate = current + chunk
+        if not current or fits(candidate):
+            current = candidate
+        else:
+            if current.strip():
+                parts.append(current)
+            current = chunk
+    if current.strip():
+        parts.append(current)
+    # Validate rendered output after every boundary decision; Markdown size is
+    # not monotonic with source length (a closing delimiter can change layout).
+    if any(not fits(part) for part in parts):
+        raise ValueError("unable to split text within the requested limits")
+    return parts
+
+
+def convert_markdown_to_line_messages(
+    text: str,
+    *,
+    alt_text: str | None = None,
+    max_length: int = 1600,
+    max_payload_bytes: int = DEFAULT_MAX_FLEX_PAYLOAD_BYTES,
+) -> list[dict[str, Any]]:
+    """Convert Markdown to ordered standalone Flex messages, without sending.
+
+    Empty input returns []. The caller manages LINE's five-message request
+    limit and delivery. This function never truncates the message list.
+    """
+    if alt_text is not None:
+        _alt_text(alt_text)
+    return [
+        build_flex_message(part, alt_text=alt_text)
+        for part in split_long_text(text, max_length, max_payload_bytes)
+    ]

line_markdown_parser-0.1.2.dist-info/METADATA

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: line-markdown-parser
+Version: 0.1.2
+Summary: Convert LLM Markdown into readable LINE Flex Messages without runtime dependencies.
+Author: line-markdown-parser contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/darkgaldragon/line-markdown-parser
+Project-URL: Source, https://github.com/darkgaldragon/line-markdown-parser
+Project-URL: Issues, https://github.com/darkgaldragon/line-markdown-parser/issues
+Keywords: line,markdown,flex-message,llm,chatbot
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.11; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# line-markdown-parser
+
+Convert LLM Markdown into readable LINE Flex Message dictionaries with no runtime dependencies.
+
+[日本語](README-ja.md)
+
+Headings, paragraphs, lists, quotes, code, and links receive a chat-friendly layout. Long output is split into separate messages. Sending remains the responsibility of your application.
+
+## Installation
+
+Requires Python 3.10 or later.
+
+```bash
+python -m pip install line-markdown-parser
+```
+
+## Quick start
+
+```python
+import json
+
+from line_markdown_parser import convert_markdown_to_line_messages
+
+markdown = """# Project update
+
+The **first draft** is ready.
+
+- Review the examples
+- Read the [guide](https://example.com/guide)
+"""
+
+messages = convert_markdown_to_line_messages(markdown)
+print(json.dumps(messages, ensure_ascii=False, indent=2))
+```
+
+Each item has `type: "flex"`, `altText`, and one `bubble` in `contents`. Pass these dictionaries to your LINE API integration. The library makes no network requests and does not require the LINE SDK.
+
+The converter returns all generated messages. LINE accepts up to five message objects per [reply](https://developers.line.biz/en/reference/messaging-api/#send-reply-message) or [push](https://developers.line.biz/en/reference/messaging-api/#send-push-message) request, so your application must handle longer results and reply-token restrictions.
+
+## API
+
+All functions are exported from `line_markdown_parser`.
+
+| Function | Purpose |
+| --- | --- |
+| `convert_markdown_to_line_messages` | Split Markdown and return a `list[dict]` of Flex Messages. |
+| `build_flex_message` | Build one message without splitting; reject oversized input. |
+| `build_flex_contents` | Build body components for a custom bubble, without a bubble size check. |
+| `split_long_text` | Return Markdown chunks as a `list[str]`. |
+| `estimate_flex_payload_size` | Measure the rendered bubble's compact UTF-8 JSON size. |
+
+The converter defaults to 1,600 source characters and 28,000 rendered bytes per chunk. See the [API specification](docs/spec.md) for signatures, limits, alternative text, and error behavior.
+
+## Limitations
+
+- Markdown tables use code-style text boxes; column alignment varies by client font.
+- Images appear as labels and links, without fetching or embedding images.
+- Only `http` and `https` links receive URI actions; destinations are not verified.
+- Full CommonMark support, arbitrary nesting, and every code-fence style are outside the scope.
+- This is an alpha release with automated tests. Live LINE delivery and client appearance have not been verified. Check integration with the [Flex Message Simulator](https://developers.line.biz/flex-simulator/) and your target LINE clients.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and checks, [SECURITY.md](SECURITY.md) for vulnerability reporting, and [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## License
+
+[MIT](LICENSE). This independent project is not an official LINE product.

line_markdown_parser-0.1.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+line_markdown_parser/__init__.py,sha256=JVWtYjb8ESOB3MpiR8YXmA0W7uI_LrDM0Sl-NdFMQYQ,506
+line_markdown_parser/_renderer.py,sha256=JluqobiP9iBtXhUYAr9bwrY9uDo4zYxh2cKtOToSm28,58959
+line_markdown_parser/converter.py,sha256=lH-k66ckNNNG8X6CZdPAI2b_Cy0EDAtGHWiQai8Gezk,9199
+line_markdown_parser/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+line_markdown_parser-0.1.2.dist-info/licenses/LICENSE,sha256=u5FUkJhpVNaUIe78mhEt0qPwcjgkSIMlhIwaA8xQaLY,1090
+line_markdown_parser-0.1.2.dist-info/METADATA,sha256=1tHxGGIDHRAecD7RODV9vFm7owVQXH2K2EQ4n5hZX0k,4224
+line_markdown_parser-0.1.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+line_markdown_parser-0.1.2.dist-info/top_level.txt,sha256=TdLst9mUdFc2XS5t3t-Gg-xIJh3BLmzaHigypJ2qqZ8,21
+line_markdown_parser-0.1.2.dist-info/RECORD,,

line_markdown_parser-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

line_markdown_parser-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 line-markdown-parser contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

line_markdown_parser-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+line_markdown_parser