feat: Allow defining IDs on code blocks (for warnings)

If the ID is missing/empty,
the title is used instead.

The ID/title is shown in warnings
when there was an error running the code.

If both the ID and titles are missing
or empty, nothing is shown in the warning.

src/markdown_exec/__init__.py

@@ -59,12 +59,13 @@ def validator(
     exec_value = _to_bool(inputs.pop("exec", "no"))
     if language != "tree" and not exec_value:
         return False
+    id_value = inputs.pop("id", "")
     html_value = _to_bool(inputs.pop("html", "no"))
     source_value = inputs.pop("source", "")
     result_value = inputs.pop("result", "")
     tabs_value = inputs.pop("tabs", "Source|Result")
     tabs = tuple(_tabs_re.split(tabs_value, maxsplit=1))
-    options["exec"] = exec_value
+    options["id"] = id_value
     options["html"] = html_value
     options["source"] = source_value
     options["result"] = result_value

src/markdown_exec/formatters/base.py

@@ -23,6 +23,7 @@ def base_format(  # noqa: WPS231
     source: str,
     result: str,
     tabs: tuple[str, str],
+    id: str,  # noqa: A002,VNE003
     transform_source: Callable[[str], tuple[str, str]] | None = None,
     **options: Any,
 ) -> Markup:
@@ -37,6 +38,7 @@ def base_format(  # noqa: WPS231
         source: Whether to show source as well, and where.
         result: If provided, use as language to format result in a code block.
         tabs: Titles of tabs (if used).
+        id: An optional ID for the code block (useful when warning about errors).
         transform_source: An optional callable that returns transformed versions of the source.
             The input source is the one that is ran, the output source is the one that is
             rendered (when the source option is enabled).
@@ -57,7 +59,9 @@ def base_format(  # noqa: WPS231
     try:
         output = run(source_input, **extra)
     except RuntimeError as error:
-        logger.warning(f"Execution of {language} code block exited with non-zero status")
+        identifier = id or extra.get("title", "")
+        identifier = identifier and f"'{identifier}' "
+        logger.warning(f"Execution of {language} code block {identifier}exited with non-zero status")
         return markdown.convert(str(error))
 
     if html:

tests/test_base_formatter.py

@@ -13,7 +13,7 @@ def test_no_p_around_html(md: Markdown) -> None:
         md: A Markdown instance (fixture).
     """
     code = "<pre><code>hello</code></pre>"
-    html = base_format("whatever", lambda _: _, code, md, html=True, source="", result="", tabs=("", ""))
+    html = base_format("whatever", lambda _: _, code, md, id="", html=True, source="", result="", tabs=("", ""))
     assert html == code
 
 
@@ -25,5 +25,5 @@ def test_render_source(md: Markdown, html: bool) -> None:
         md: A Markdown instance (fixture).
         html: Whether output is HTML or not.
     """
-    markup = base_format("python", lambda _: _, "hello", md, html, "tabbed-left", "", ("Source", "Output"))
+    markup = base_format("python", lambda _: _, "hello", md, html, "tabbed-left", "", ("Source", "Output"), id="")
     assert "Source" in markup