marktip 0.3.0__tar.gz → 0.4.0__tar.gz

{marktip-0.3.0 → marktip-0.4.0}/CMakeLists.txt

@@ -7,7 +7,7 @@ set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS OFF)
 
 if(NOT DEFINED SKBUILD_PROJECT_VERSION)
-  set(SKBUILD_PROJECT_VERSION "0.3.0")
+  set(SKBUILD_PROJECT_VERSION "0.4.0")
 endif()
 
 set(PYBIND11_FINDPYTHON ON)

marktip-0.4.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: marktip
+Version: 0.4.0
+Summary: Fast C++/MD4C Markdown parser and canonical Markdown serializer for Tiptap-style JSON
+Keywords: markdown,tiptap,md4c,parser
+Author: Saneaven (Minjae Kyung)
+License-Expression: MIT
+License-File: LICENSE
+License-File: third_party/md4c/LICENSE.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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 :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.9
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Description-Content-Type: text/markdown
+
+# marktip
+
+Fast C++/MD4C Markdown conversion for Tiptap-style JSON.
+
+## Installation
+
+```bash
+python -m pip install marktip
+```
+
+Release wheels are built for common CPython versions on Linux, macOS, and Windows.
+If a wheel is not available for a platform, pip can build from the source distribution with a C++17 compiler and standard Python build tooling.
+
+## Usage
+
+```python
+import marktip as tm
+
+doc = tm.from_markdown("# Hello")
+ast = doc.to_dict()
+markdown = doc.to_markdown()
+
+doc = tm.from_dict(ast)
+```
+
+`from_markdown` follows GFM/CommonMark by default.
+Pass `cjk_friendly=True` to relax the emphasis and strikethrough rules so delimiters next to CJK text still open and close (e.g. `**볼드**은` parses as bold), a non-standard extension that is off by default:
+
+```python
+doc = tm.from_markdown("**볼드**은 강조", cjk_friendly=True)
+```
+
+Strikethrough follows the GFM reference implementations (cmark-gfm/micromark): intra-word `~~` strikes (`a~~b~~c`), including next to CJK letters (`~~삭제~~은`).
+`cjk_friendly` still matters for `*`/`_`, and for `~` in punctuation-adjacent cases such as `~~"인용"~~라고`.
+
+Pass `html=False` to parse raw HTML as literal text instead of `htmlBlock`/`htmlInline` nodes.
+Content is preserved (the serializer escapes it), and `<br>` inside table cells still maps to `hardBreak` so marktip's own table output round-trips:
+
+```python
+doc = tm.from_markdown("a <u>x</u> b", html=False)
+# paragraph with the literal text "a <u>x</u> b"
+```
+
+marktip targets GFM core syntax and canonical Markdown output rather than byte-identical source preservation.
+
+## Errors
+
+Every rejection marktip raises derives from `marktip.MarktipError`, so "the input is malformed" is a single `except` — no need to catch a bare `ValueError` wide enough to swallow an unrelated bug:
+
+```python
+try:
+    tm.from_dict(payload).to_markdown()
+except tm.MarktipError as e:
+    return 422, {"code": e.code, "path": e.path, "detail": e.detail}
+```
+
+```
+Exception
+└─ MarktipError              .code, .path, .detail
+   ├─ UnknownTypeError       + .type, .kind    — type outside the closed schema
+   ├─ InvalidNodeError       + .field          — violates the node grammar
+   └─ ParseError                               — markdown could not be parsed
+```
+
+`.path` is a breadcrumb into the input, e.g. `content[1].content[0].marks[0]`; it is `""` when the failure is at the root or has no location.
+`.detail` is the same string as `str(e)`.
+`.code` is a stable machine key:
+
+| `.code` | Class | Raised when |
+| --- | --- | --- |
+| `unknown_node_type` | `UnknownTypeError` | node `type` is outside the closed schema |
+| `unknown_mark_type` | `UnknownTypeError` | mark `type` is outside the closed schema |
+| `missing_type` | `InvalidNodeError` | a node or mark has no `type` key |
+| `invalid_root` | `InvalidNodeError` | the root node's type is not `doc` |
+| `wrong_type` | `InvalidNodeError` | `attrs`/`content`/`marks`/a child has the wrong Python type |
+| `max_depth` | `InvalidNodeError` | dict nesting exceeds 2048 |
+| `markdown_max_depth` | `ParseError` | markdown nesting exceeds 2048 |
+| `parse_failed` | `ParseError` | MD4C could not parse the input |
+
+`from_markdown` still raises a plain `TypeError` when the argument is not `str`/`bytes` — that is a caller bug, not a malformed document.
+
+> **Changed in 0.4.0** — these were previously `ValueError` (`from_dict`) and `RuntimeError` (`from_markdown`).
+> `MarktipError` derives from `Exception` directly, so `except ValueError` no longer catches them.
+
+## What `from_dict` validates
+
+The Tiptap-side schema is closed: every node/mark type must have a markdown mapping.
+`from_dict` is the single enforcement point and rejects unknown types instead of silently dropping content.
+It guarantees, for the whole tree:
+
+- **Closed schema.**
+  Node types are `doc`, `paragraph`, `text`, `hardBreak`, `heading`, `blockquote`, `codeBlock`, `horizontalRule`, `bulletList`, `orderedList`, `listItem`, `taskList`, `taskItem`, `table`, `tableRow`, `tableHeader`, `tableCell`, `image`, `htmlBlock`, `htmlInline`.
+  Marks are `bold`, `italic`, `strike`, `code`, `link`.
+  Anything else → `UnknownTypeError`.
+- **`type` is required** on every node and mark.
+- **The root is a `doc`.**
+- **Shapes**: `attrs` is a dict, `content` and `marks` are lists, and every entry of `content`/`marks` is a dict.
+- **Depth** is at most 2048 levels.
+
+A document that survives `from_dict` always serializes; callers do not need to re-check any of the above.
+
+It deliberately does **not** validate:
+
+- **`attrs` value types.**
+  Keys are free-form.
+  `str`, `int`, and `bool` round-trip unchanged; anything else is coerced to a string (`[1, 2]` → `"[1, 2]"`, `1.5` → `"1.5"`, `None` → `""`), so `to_dict()` will not always give back what you passed in.
+- **Per-node required attrs.**
+  A `heading` without `level`, an `image` without `src`, or a `link` mark without `href` is accepted; the serializer substitutes a default rather than failing.
+- **Content models.**
+  Which node may contain which is not checked — a `text` node directly under `doc` is accepted and serialized.
+
+Structural violations report where they happened:
+
+```python
+try:
+    tm.from_dict({"type": "doc", "content": [{"content": []}]})
+except tm.InvalidNodeError as e:
+    e.code    # "missing_type"
+    e.field   # "type"
+    e.path    # "content[0]"
+    e.detail  # "node is missing required key 'type'"
+```
+
+## Defined normalizations
+
+Markdown cannot represent every Tiptap document exactly.
+Rather than emitting markdown that reparses into a different structure, marktip applies these deterministic (and idempotent) normalizations at serialization time:
+
+- **Hard breaks in headings** — ATX headings are single-line, so a `hardBreak` (or a literal newline carried over from setext input) inside a heading serializes as a single space: `heading("a", hardBreak, "b")` → `# a b`.
+- **Multi-block table cells** — blocks inside a cell are joined with `<br>` and the cell is flattened to one line; two paragraphs in a cell reparse as one paragraph containing a `hardBreak`.
+- **Headerless tables** — GFM tables require a header row, so the first row is always emitted as the header; a leading `tableCell` row reparses as `tableHeader`.
+- **Heading levels** — clamped to 1–6 at serialization (`0` → `#`, `7` → `######`).
+- **Emphasis boundary whitespace** — whitespace touching an emphasis delimiter has no valid markdown form and is expelled outside the marks (`bold("굵게 ")` → `**굵게** `), cf. prosemirror-markdown's `expelEnclosingWhitespace`.
+- **Adjacent same-family lists** — consecutive lists of the same family alternate markers (`-`/`*`, `1.`/`1)`) so they stay separate lists on reparse instead of merging (which would renumber ordered items or spread task checkboxes).
+
+## Development
+
+```bash
+python -m pip install .[test]
+python -m pytest
+```
+
+For a direct local CMake build:
+
+```bash
+cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release \
+  -Dpybind11_DIR="$(python -m pybind11 --cmakedir)"
+cmake --build build
+PYTHONPATH=python python -m pytest
+PYTHONPATH=python python scripts/benchmark.py
+```

marktip-0.4.0/README.md

@@ -0,0 +1,151 @@
+# marktip
+
+Fast C++/MD4C Markdown conversion for Tiptap-style JSON.
+
+## Installation
+
+```bash
+python -m pip install marktip
+```
+
+Release wheels are built for common CPython versions on Linux, macOS, and Windows.
+If a wheel is not available for a platform, pip can build from the source distribution with a C++17 compiler and standard Python build tooling.
+
+## Usage
+
+```python
+import marktip as tm
+
+doc = tm.from_markdown("# Hello")
+ast = doc.to_dict()
+markdown = doc.to_markdown()
+
+doc = tm.from_dict(ast)
+```
+
+`from_markdown` follows GFM/CommonMark by default.
+Pass `cjk_friendly=True` to relax the emphasis and strikethrough rules so delimiters next to CJK text still open and close (e.g. `**볼드**은` parses as bold), a non-standard extension that is off by default:
+
+```python
+doc = tm.from_markdown("**볼드**은 강조", cjk_friendly=True)
+```
+
+Strikethrough follows the GFM reference implementations (cmark-gfm/micromark): intra-word `~~` strikes (`a~~b~~c`), including next to CJK letters (`~~삭제~~은`).
+`cjk_friendly` still matters for `*`/`_`, and for `~` in punctuation-adjacent cases such as `~~"인용"~~라고`.
+
+Pass `html=False` to parse raw HTML as literal text instead of `htmlBlock`/`htmlInline` nodes.
+Content is preserved (the serializer escapes it), and `<br>` inside table cells still maps to `hardBreak` so marktip's own table output round-trips:
+
+```python
+doc = tm.from_markdown("a <u>x</u> b", html=False)
+# paragraph with the literal text "a <u>x</u> b"
+```
+
+marktip targets GFM core syntax and canonical Markdown output rather than byte-identical source preservation.
+
+## Errors
+
+Every rejection marktip raises derives from `marktip.MarktipError`, so "the input is malformed" is a single `except` — no need to catch a bare `ValueError` wide enough to swallow an unrelated bug:
+
+```python
+try:
+    tm.from_dict(payload).to_markdown()
+except tm.MarktipError as e:
+    return 422, {"code": e.code, "path": e.path, "detail": e.detail}
+```
+
+```
+Exception
+└─ MarktipError              .code, .path, .detail
+   ├─ UnknownTypeError       + .type, .kind    — type outside the closed schema
+   ├─ InvalidNodeError       + .field          — violates the node grammar
+   └─ ParseError                               — markdown could not be parsed
+```
+
+`.path` is a breadcrumb into the input, e.g. `content[1].content[0].marks[0]`; it is `""` when the failure is at the root or has no location.
+`.detail` is the same string as `str(e)`.
+`.code` is a stable machine key:
+
+| `.code` | Class | Raised when |
+| --- | --- | --- |
+| `unknown_node_type` | `UnknownTypeError` | node `type` is outside the closed schema |
+| `unknown_mark_type` | `UnknownTypeError` | mark `type` is outside the closed schema |
+| `missing_type` | `InvalidNodeError` | a node or mark has no `type` key |
+| `invalid_root` | `InvalidNodeError` | the root node's type is not `doc` |
+| `wrong_type` | `InvalidNodeError` | `attrs`/`content`/`marks`/a child has the wrong Python type |
+| `max_depth` | `InvalidNodeError` | dict nesting exceeds 2048 |
+| `markdown_max_depth` | `ParseError` | markdown nesting exceeds 2048 |
+| `parse_failed` | `ParseError` | MD4C could not parse the input |
+
+`from_markdown` still raises a plain `TypeError` when the argument is not `str`/`bytes` — that is a caller bug, not a malformed document.
+
+> **Changed in 0.4.0** — these were previously `ValueError` (`from_dict`) and `RuntimeError` (`from_markdown`).
+> `MarktipError` derives from `Exception` directly, so `except ValueError` no longer catches them.
+
+## What `from_dict` validates
+
+The Tiptap-side schema is closed: every node/mark type must have a markdown mapping.
+`from_dict` is the single enforcement point and rejects unknown types instead of silently dropping content.
+It guarantees, for the whole tree:
+
+- **Closed schema.**
+  Node types are `doc`, `paragraph`, `text`, `hardBreak`, `heading`, `blockquote`, `codeBlock`, `horizontalRule`, `bulletList`, `orderedList`, `listItem`, `taskList`, `taskItem`, `table`, `tableRow`, `tableHeader`, `tableCell`, `image`, `htmlBlock`, `htmlInline`.
+  Marks are `bold`, `italic`, `strike`, `code`, `link`.
+  Anything else → `UnknownTypeError`.
+- **`type` is required** on every node and mark.
+- **The root is a `doc`.**
+- **Shapes**: `attrs` is a dict, `content` and `marks` are lists, and every entry of `content`/`marks` is a dict.
+- **Depth** is at most 2048 levels.
+
+A document that survives `from_dict` always serializes; callers do not need to re-check any of the above.
+
+It deliberately does **not** validate:
+
+- **`attrs` value types.**
+  Keys are free-form.
+  `str`, `int`, and `bool` round-trip unchanged; anything else is coerced to a string (`[1, 2]` → `"[1, 2]"`, `1.5` → `"1.5"`, `None` → `""`), so `to_dict()` will not always give back what you passed in.
+- **Per-node required attrs.**
+  A `heading` without `level`, an `image` without `src`, or a `link` mark without `href` is accepted; the serializer substitutes a default rather than failing.
+- **Content models.**
+  Which node may contain which is not checked — a `text` node directly under `doc` is accepted and serialized.
+
+Structural violations report where they happened:
+
+```python
+try:
+    tm.from_dict({"type": "doc", "content": [{"content": []}]})
+except tm.InvalidNodeError as e:
+    e.code    # "missing_type"
+    e.field   # "type"
+    e.path    # "content[0]"
+    e.detail  # "node is missing required key 'type'"
+```
+
+## Defined normalizations
+
+Markdown cannot represent every Tiptap document exactly.
+Rather than emitting markdown that reparses into a different structure, marktip applies these deterministic (and idempotent) normalizations at serialization time:
+
+- **Hard breaks in headings** — ATX headings are single-line, so a `hardBreak` (or a literal newline carried over from setext input) inside a heading serializes as a single space: `heading("a", hardBreak, "b")` → `# a b`.
+- **Multi-block table cells** — blocks inside a cell are joined with `<br>` and the cell is flattened to one line; two paragraphs in a cell reparse as one paragraph containing a `hardBreak`.
+- **Headerless tables** — GFM tables require a header row, so the first row is always emitted as the header; a leading `tableCell` row reparses as `tableHeader`.
+- **Heading levels** — clamped to 1–6 at serialization (`0` → `#`, `7` → `######`).
+- **Emphasis boundary whitespace** — whitespace touching an emphasis delimiter has no valid markdown form and is expelled outside the marks (`bold("굵게 ")` → `**굵게** `), cf. prosemirror-markdown's `expelEnclosingWhitespace`.
+- **Adjacent same-family lists** — consecutive lists of the same family alternate markers (`-`/`*`, `1.`/`1)`) so they stay separate lists on reparse instead of merging (which would renumber ordered items or spread task checkboxes).
+
+## Development
+
+```bash
+python -m pip install .[test]
+python -m pytest
+```
+
+For a direct local CMake build:
+
+```bash
+cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release \
+  -Dpybind11_DIR="$(python -m pybind11 --cmakedir)"
+cmake --build build
+PYTHONPATH=python python -m pytest
+PYTHONPATH=python python scripts/benchmark.py
+```

{marktip-0.3.0 → marktip-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "marktip"
-version = "0.3.0"
+version = "0.4.0"
 description = "Fast C++/MD4C Markdown parser and canonical Markdown serializer for Tiptap-style JSON"
 readme = "README.md"
 requires-python = ">=3.9"

{marktip-0.3.0 → marktip-0.4.0}/python/marktip/__init__.py

@@ -1,7 +1,16 @@
 """Fast Markdown conversion for Tiptap-style JSON."""
 
 try:
-    from ._core import Document, UnknownTypeError, __version__, from_dict, from_markdown
+    from ._core import (
+        Document,
+        InvalidNodeError,
+        MarktipError,
+        ParseError,
+        UnknownTypeError,
+        __version__,
+        from_dict,
+        from_markdown,
+    )
 except ImportError:  # pragma: no cover - development-only CMake build fallback
     import importlib.util
     import pathlib
@@ -21,8 +30,20 @@ except ImportError:  # pragma: no cover - development-only CMake build fallback
 
     __version__ = _module.__version__
     Document = _module.Document
+    MarktipError = _module.MarktipError
     UnknownTypeError = _module.UnknownTypeError
+    InvalidNodeError = _module.InvalidNodeError
+    ParseError = _module.ParseError
     from_dict = _module.from_dict
     from_markdown = _module.from_markdown
 
-__all__ = ["__version__", "Document", "UnknownTypeError", "from_markdown", "from_dict"]
+__all__ = [
+    "__version__",
+    "Document",
+    "MarktipError",
+    "UnknownTypeError",
+    "InvalidNodeError",
+    "ParseError",
+    "from_markdown",
+    "from_dict",
+]

{marktip-0.3.0 → marktip-0.4.0}/src/ast.cpp

@@ -2,7 +2,6 @@
 
 #include <algorithm>
 #include <iterator>
-#include <stdexcept>
 
 namespace py = pybind11;
 
@@ -64,16 +63,16 @@ py::object dict_get(py::dict dict, const char* key) {
     return dict[py::str(key)];
 }
 
-py::dict expect_dict(py::handle value, std::string_view context) {
+py::dict expect_dict(py::handle value, std::string_view context, const char* field, const PathStack& path) {
     if (!py::isinstance<py::dict>(value)) {
-        throw std::invalid_argument(std::string(context) + " must be a dict");
+        throw InvalidNodeError("wrong_type", field, std::string(context) + " must be a dict", format_path(path));
     }
     return py::reinterpret_borrow<py::dict>(value);
 }
 
-py::list expect_list(py::handle value, std::string_view context) {
+py::list expect_list(py::handle value, std::string_view context, const char* field, const PathStack& path) {
     if (!py::isinstance<py::list>(value)) {
-        throw std::invalid_argument(std::string(context) + " must be a list");
+        throw InvalidNodeError("wrong_type", field, std::string(context) + " must be a list", format_path(path));
     }
     return py::reinterpret_borrow<py::list>(value);
 }
@@ -85,10 +84,11 @@ std::string py_to_string(py::handle value) {
     return py::cast<std::string>(py::str(value));
 }
 
-std::string required_type(py::dict value, std::string_view context) {
+std::string required_type(py::dict value, std::string_view context, const PathStack& path) {
     py::object type = dict_get(value, "type");
     if (type.is_none()) {
-        throw std::invalid_argument(std::string(context) + " is missing required key 'type'");
+        throw InvalidNodeError("missing_type", "type", std::string(context) + " is missing required key 'type'",
+                               format_path(path));
     }
     return py_to_string(type);
 }
@@ -172,14 +172,14 @@ py::dict node_to_py(const Document& document, std::size_t index) {
 
 Mark mark_from_py(py::dict mark_dict, const PathStack& path) {
     Mark mark;
-    mark.type = required_type(mark_dict, "mark");
+    mark.type = required_type(mark_dict, "mark", path);
     if (!is_known_mark_type(mark.type)) {
         throw UnknownTypeError("mark", mark.type, format_path(path));
     }
 
     py::object attrs = dict_get(mark_dict, "attrs");
     if (!attrs.is_none()) {
-        mark.attrs = attrs_from_py(expect_dict(attrs, "mark attrs"));
+        mark.attrs = attrs_from_py(expect_dict(attrs, "mark attrs", "attrs", path));
     }
 
     return mark;
@@ -188,11 +188,12 @@ Mark mark_from_py(py::dict mark_dict, const PathStack& path) {
 void fill_node_from_py(Document& document, std::size_t index, py::dict node_dict, std::string_view context,
                        std::size_t depth, PathStack& path) {
     if (depth > kMaxNodeDepth) {
-        throw std::invalid_argument("node content nesting exceeds maximum depth");
+        throw InvalidNodeError("max_depth", "content", "node content nesting exceeds maximum depth",
+                               format_path(path));
     }
 
     Node node;
-    node.type = required_type(node_dict, context);
+    node.type = required_type(node_dict, context, path);
     if (!is_known_node_type(node.type)) {
         throw UnknownTypeError("node", node.type, format_path(path));
     }
@@ -203,16 +204,16 @@ void fill_node_from_py(Document& document, std::size_t index, py::dict node_dict
 
     py::object attrs = dict_get(node_dict, "attrs");
     if (!attrs.is_none()) {
-        node.attrs = attrs_from_py(expect_dict(attrs, "node attrs"));
+        node.attrs = attrs_from_py(expect_dict(attrs, "node attrs", "attrs", path));
     }
 
     py::object marks = dict_get(node_dict, "marks");
     if (!marks.is_none()) {
-        py::list mark_list = expect_list(marks, "node marks");
+        py::list mark_list = expect_list(marks, "node marks", "marks", path);
         std::size_t mark_index = 0;
         for (py::handle mark_handle : mark_list) {
             path.push_back({"marks", mark_index});
-            node.marks.push_back(mark_from_py(expect_dict(mark_handle, "mark"), path));
+            node.marks.push_back(mark_from_py(expect_dict(mark_handle, "mark", "marks", path), path));
             path.pop_back();
             ++mark_index;
         }
@@ -225,12 +226,13 @@ void fill_node_from_py(Document& document, std::size_t index, py::dict node_dict
         return;
     }
 
-    py::list content_list = expect_list(content, "node content");
+    py::list content_list = expect_list(content, "node content", "content", path);
     std::size_t child_pos = 0;
     for (py::handle child_handle : content_list) {
         std::size_t child_index = document.append_child(index, Node{});
         path.push_back({"content", child_pos});
-        fill_node_from_py(document, child_index, expect_dict(child_handle, "content child"), "node", depth + 1, path);
+        fill_node_from_py(document, child_index, expect_dict(child_handle, "content child", "content", path), "node",
+                          depth + 1, path);
         path.pop_back();
         ++child_pos;
     }
@@ -390,14 +392,15 @@ py::dict Document::to_dict() const {
 }
 
 Document from_dict_py(py::dict root) {
-    std::string type = required_type(root, "root node");
+    PathStack path;
+    path.reserve(32);
+
+    std::string type = required_type(root, "root node", path);
     if (type != "doc") {
-        throw std::invalid_argument("root node must have type 'doc'");
+        throw InvalidNodeError("invalid_root", "type", "root node must have type 'doc'", format_path(path));
     }
 
     Document document;
-    PathStack path;
-    path.reserve(32);
     fill_node_from_py(document, 0, root, "root node", 0, path);
     return document;
 }

{marktip-0.3.0 → marktip-0.4.0}/src/ast.h

@@ -3,12 +3,13 @@
 #include <pybind11/pybind11.h>
 
 #include <cstddef>
-#include <stdexcept>
 #include <string>
 #include <string_view>
 #include <utility>
 #include <vector>
 
+#include "errors.h"
+
 namespace marktip {
 
 // Deep documents are traversed recursively (to_dict, to_markdown); cap nesting
@@ -47,27 +48,6 @@ struct Node {
     std::vector<std::size_t> content;
 };
 
-// Raised by from_dict when a node or mark type is outside the closed schema.
-// Subclasses std::invalid_argument so it surfaces as (a subclass of) ValueError.
-class UnknownTypeError : public std::invalid_argument {
-public:
-    UnknownTypeError(std::string kind, std::string type_name, std::string path)
-        : std::invalid_argument("unknown " + kind + " type '" + type_name + "' at " +
-                                (path.empty() ? std::string("root") : path)),
-          kind_(std::move(kind)),
-          type_name_(std::move(type_name)),
-          path_(std::move(path)) {}
-
-    const std::string& kind() const noexcept { return kind_; }
-    const std::string& type_name() const noexcept { return type_name_; }
-    const std::string& path() const noexcept { return path_; }
-
-private:
-    std::string kind_;       // "node" | "mark"
-    std::string type_name_;
-    std::string path_;       // "content[0].marks[1]"; empty = root
-};
-
 void set_attr(AttrList& attrs, std::string key, AttrValue value);
 const AttrValue* find_attr(const AttrList& attrs, std::string_view key);
 std::string attr_string(const AttrList& attrs, std::string_view key, std::string fallback = {});

marktip-0.4.0/src/errors.h

@@ -0,0 +1,70 @@
+#pragma once
+
+#include <exception>
+#include <string>
+#include <utility>
+
+namespace marktip {
+
+// Every error marktip raises for bad input derives from MarktipError,
+// so a caller can express "the document is malformed" as a single except clause.
+//
+// These types are thrown from parse_to_document() while the GIL is released,
+// so they must never hold pybind11 objects — std::string members only.
+class MarktipError : public std::exception {
+public:
+    MarktipError(std::string code, std::string message, std::string path = {})
+        : code_(std::move(code)), message_(std::move(message)), path_(std::move(path)) {}
+
+    const char* what() const noexcept override { return message_.c_str(); }
+
+    const std::string& code() const noexcept { return code_; }
+    const std::string& path() const noexcept { return path_; }
+
+private:
+    std::string code_;     // stable machine key, e.g. "wrong_type"
+    std::string message_;
+    std::string path_;     // "content[0].marks[1]"; empty = root / not applicable
+};
+
+// Raised by from_dict when a node or mark type is outside the closed schema.
+class UnknownTypeError : public MarktipError {
+public:
+    UnknownTypeError(std::string kind, std::string type_name, std::string path)
+        // path is passed by copy, not moved: argument evaluation order is unspecified,
+        // and the message argument above reads it.
+        : MarktipError("unknown_" + kind + "_type",
+                       "unknown " + kind + " type '" + type_name + "' at " +
+                           (path.empty() ? std::string("root") : path),
+                       path),
+          kind_(std::move(kind)),
+          type_name_(std::move(type_name)) {}
+
+    const std::string& kind() const noexcept { return kind_; }
+    const std::string& type_name() const noexcept { return type_name_; }
+
+private:
+    std::string kind_;  // "node" | "mark"
+    std::string type_name_;
+};
+
+// Raised when the input violates the node grammar itself: a missing 'type', a non-dict attrs,
+// a non-list content, a root that is not a doc.
+class InvalidNodeError : public MarktipError {
+public:
+    InvalidNodeError(std::string code, std::string field, std::string message, std::string path)
+        : MarktipError(std::move(code), std::move(message), std::move(path)), field_(std::move(field)) {}
+
+    const std::string& field() const noexcept { return field_; }
+
+private:
+    std::string field_;  // "type" | "attrs" | "marks" | "content"
+};
+
+// Raised by from_markdown when the markdown itself cannot be parsed.
+class ParseError : public MarktipError {
+public:
+    ParseError(std::string code, std::string message) : MarktipError(std::move(code), std::move(message)) {}
+};
+
+}  // namespace marktip