mdformat-py-edu-fr 0.1.7__tar.gz

mdformat_py_edu_fr-0.1.7/LICENSE.txt

@@ -0,0 +1,27 @@
+Copyright (c) 2025, py-edu-fr developers and Pierre Augier
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

mdformat_py_edu_fr-0.1.7/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: mdformat-py-edu-fr
+Version: 0.1.7
+Summary: Tiny wrapper around mdformat for the py-edu-fr project
+Author-Email: Pierre Augier <pierre.augier@univ-grenoble-alpes.fr>
+License-Expression: BSD-3-Clause
+License-File: LICENSE.txt
+Requires-Python: >=3.13
+Requires-Dist: jupytext
+Requires-Dist: mdformat>=0.7.0
+Requires-Dist: mdit-py-plugins>=0.3.0
+Requires-Dist: mdformat-frontmatter>=0.3.2
+Requires-Dist: mdformat-footnote>=0.1.1
+Requires-Dist: mdformat-gfm>=1.0.0
+Requires-Dist: ruamel.yaml>=0.16.0
+Requires-Dist: ruff
+Description-Content-Type: text/markdown
+
+# Tiny wrapper around mdformat for the py-edu-fr project
+
+We needed a specific markdown formatter for the
+[py-edu-fr project](https://python-cnrs.netlify.app/edu).
+
+mdformat-py-edu-fr is based on mdformat, mdformat-myst and Jupytext.
+
+```
+$ mdformat-py-edu-fr -h
+usage: mdformat-py-edu-fr [-h] [--version] [--check] [--exclude PATTERN] [--verbose] [paths ...]
+
+Format Markdown files for py-edu-fr project
+
+positional arguments:
+  paths                 Files or directories to format (if omitted, reads from stdin)
+
+options:
+  -h, --help            show this help message and exit
+  --version             show program's version number and exit
+  --check               Check if files are formatted without modifying them (exit code 1 if changes needed)
+  --exclude PATTERN     Glob pattern to exclude files/directories (can be specified multiple times)
+  --verbose, -v         Print detailed information about processing
+```

mdformat_py_edu_fr-0.1.7/README.md

@@ -0,0 +1,23 @@
+# Tiny wrapper around mdformat for the py-edu-fr project
+
+We needed a specific markdown formatter for the
+[py-edu-fr project](https://python-cnrs.netlify.app/edu).
+
+mdformat-py-edu-fr is based on mdformat, mdformat-myst and Jupytext.
+
+```
+$ mdformat-py-edu-fr -h
+usage: mdformat-py-edu-fr [-h] [--version] [--check] [--exclude PATTERN] [--verbose] [paths ...]
+
+Format Markdown files for py-edu-fr project
+
+positional arguments:
+  paths                 Files or directories to format (if omitted, reads from stdin)
+
+options:
+  -h, --help            show this help message and exit
+  --version             show program's version number and exit
+  --check               Check if files are formatted without modifying them (exit code 1 if changes needed)
+  --exclude PATTERN     Glob pattern to exclude files/directories (can be specified multiple times)
+  --verbose, -v         Print detailed information about processing
+```

mdformat_py_edu_fr-0.1.7/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = [
+    "pdm-backend@git+https://github.com/paugier/pdm-backend",
+]
+build-backend = "pdm.backend"
+
+[project]
+name = "mdformat-py-edu-fr"
+description = "Tiny wrapper around mdformat for the py-edu-fr project"
+authors = [
+    { name = "Pierre Augier", email = "pierre.augier@univ-grenoble-alpes.fr" },
+]
+dependencies = [
+    "jupytext",
+    "mdformat >=0.7.0",
+    "mdit-py-plugins >=0.3.0",
+    "mdformat-frontmatter >=0.3.2",
+    "mdformat-footnote >=0.1.1",
+    "mdformat-gfm >=1.0.0",
+    "ruamel.yaml >=0.16.0",
+    "ruff",
+]
+requires-python = ">=3.13"
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = [
+    "LICENSE.txt",
+]
+dynamic = []
+version = "0.1.7"
+
+[project.scripts]
+mdformat-py-edu-fr = "mdformat_py_edu_fr.__main__:main"
+
+[project.entry-points."mdformat.parser_extension"]
+myst = "mdformat_myst_pef.plugin"
+
+[tool.pdm]
+distribution = true
+
+[tool.pdm.version]
+source = "scm"
+
+[tool.pdm.options]
+lock = [
+    "-G",
+    ":all",
+]
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+]
+addopts = "--pdbcls=IPython.terminal.debugger:TerminalPdb"
+
+[dependency-groups]
+format = [
+    "ruff",
+]
+test = [
+    "pytest",
+]
+dev = [
+    "mdformat-py-edu-fr[format]",
+    "mdformat-py-edu-fr[test]",
+    "ipython",
+    "ipdb",
+]

mdformat_py_edu_fr-0.1.7/src/mdformat_myst_pef/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Taneli Hukkinen
+
+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.

mdformat_py_edu_fr-0.1.7/src/mdformat_myst_pef/__init__.py

@@ -0,0 +1,3 @@
+"""Mdformat plugin for MyST compatibility."""
+
+__version__ = "0.2.2"

mdformat_py_edu_fr-0.1.7/src/mdformat_myst_pef/_directives.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, MutableMapping, Sequence
+import io
+
+from markdown_it import MarkdownIt
+from mdformat.renderer import LOGGER, RenderContext, RenderTreeNode
+import ruamel.yaml
+
+yaml = ruamel.yaml.YAML()
+yaml.indent(mapping=2, sequence=4, offset=2)
+
+
+def longest_consecutive_sequence(seq: str, char: str) -> int:
+    """Return length of the longest consecutive sequence of `char` characters
+    in string `seq`."""
+    assert len(char) == 1
+    longest = 0
+    current_streak = 0
+    for c in seq:
+        if c == char:
+            current_streak += 1
+        else:
+            current_streak = 0
+        if current_streak > longest:
+            longest = current_streak
+    return longest
+
+
+def fence(node: "RenderTreeNode", context: "RenderContext") -> str:
+    """Render fences (and directives).
+
+    Copied from upstream `mdformat` core and should be kept up-to-date
+    if upstream introduces changes. Note that only two lines are added
+    to the upstream implementation, i.e. the condition that calls
+    `format_directive_content` function.
+    """
+    info_str = node.info.strip()
+    lang = info_str.split(maxsplit=1)[0] if info_str else ""
+    code_block = node.content
+
+    # Info strings of backtick code fences can not contain backticks or tildes.
+    # If that is the case, we make a tilde code fence instead.
+    if "`" in info_str or "~" in info_str:
+        fence_char = "~"
+    else:
+        fence_char = "`"
+
+    # Format the code block using enabled codeformatter funcs
+    if lang in context.options.get("codeformatters", {}):
+        fmt_func = context.options["codeformatters"][lang]
+        try:
+            code_block = fmt_func(code_block, info_str)
+        except Exception:
+            # Swallow exceptions so that formatter errors (e.g. due to
+            # invalid code) do not crash mdformat.
+            assert node.map is not None, "A fence token must have `map` attribute set"
+            LOGGER.warning(
+                f"Failed formatting content of a {lang} code block "
+                f"(line {node.map[0] + 1} before formatting)"
+            )
+    # This "elif" is the *only* thing added to the upstream `fence` implementation!
+    elif lang.startswith("{") and lang.endswith("}"):
+        code_block = format_directive_content(code_block)
+
+    # The code block must not include as long or longer sequence of `fence_char`s
+    # as the fence string itself
+    fence_len = max(3, longest_consecutive_sequence(code_block, fence_char) + 1)
+    fence_str = fence_char * fence_len
+
+    return f"{fence_str}{info_str}\n{code_block}{fence_str}"
+
+
+def format_directive_content(raw_content: str) -> str:
+    parse_result = parse_opts_and_content(raw_content)
+    if not parse_result:
+        return raw_content
+    unformatted_yaml, content = parse_result
+    dump_stream = io.StringIO()
+    try:
+        parsed = yaml.load(unformatted_yaml)
+        yaml.dump(parsed, stream=dump_stream)
+    except ruamel.yaml.YAMLError:
+        LOGGER.warning("Invalid YAML in MyST directive options.")
+        return raw_content
+    formatted_yaml = dump_stream.getvalue()
+
+    # Remove the YAML closing tag if added by `ruamel.yaml`
+    if formatted_yaml.endswith("\n...\n"):
+        formatted_yaml = formatted_yaml[:-4]
+
+    # Convert empty YAML to most concise form
+    if formatted_yaml == "null\n":
+        formatted_yaml = ""
+
+    formatted = "---\n" + formatted_yaml + "---\n"
+    if content:
+        formatted += content + "\n"
+    return formatted
+
+
+def parse_opts_and_content(raw_content: str) -> tuple[str, str] | None:
+    if not raw_content:
+        return None
+    lines = raw_content.splitlines()
+    line = lines.pop(0)
+    yaml_lines = []
+    if all(c == "-" for c in line) and len(line) >= 3:
+        while lines:
+            line = lines.pop(0)
+            if all(c == "-" for c in line) and len(line) >= 3:
+                break
+            yaml_lines.append(line)
+    elif line.lstrip().startswith(":"):
+        yaml_lines.append(line.lstrip()[1:])
+        while lines:
+            if not lines[0].lstrip().startswith(":"):
+                break
+            line = lines.pop(0).lstrip()[1:]
+            yaml_lines.append(line)
+    else:
+        return None
+
+    first_line_is_empty_but_second_line_isnt = (
+        len(lines) >= 2 and not lines[0].strip() and lines[1].strip()
+    )
+    exactly_one_empty_line = len(lines) == 1 and not lines[0].strip()
+    if first_line_is_empty_but_second_line_isnt or exactly_one_empty_line:
+        lines.pop(0)
+
+    unformatted_yaml = "\n".join(yaml_lines)
+    content = "\n".join(lines)
+    return unformatted_yaml, content
+
+
+def render_fence_html(
+    self: MarkdownIt, tokens: Sequence, idx: int, options: Mapping, env: MutableMapping
+) -> str:
+    return ""

mdformat_py_edu_fr-0.1.7/src/mdformat_myst_pef/plugin.py

@@ -0,0 +1,251 @@
+from __future__ import annotations
+
+import re
+import textwrap
+
+from markdown_it import MarkdownIt
+import mdformat.plugins
+from mdformat.renderer import RenderContext, RenderTreeNode
+from mdit_py_plugins.dollarmath import dollarmath_plugin
+from mdit_py_plugins.myst_blocks import myst_block_plugin
+from mdit_py_plugins.myst_role import myst_role_plugin
+from mdit_py_plugins.container import container_plugin
+
+from mdformat_myst_pef._directives import fence, render_fence_html
+
+_TARGET_PATTERN = re.compile(r"^\s*\(.+\)=\s*$")
+_ROLE_NAME_PATTERN = re.compile(r"({[a-zA-Z0-9_\-+:]+})")
+_YAML_HEADER_PATTERN = re.compile(r"(?m)(^:\w+: .*$\n?)+|^---$\n(?s:.).*\n---\n")
+
+container_names = [
+    "admonition",
+    "attention",
+    "caution",
+    "danger",
+    "div",
+    "dropdown",
+    "embed",
+    "error",
+    "exercise",
+    "exercise-end",
+    "exercise-start",
+    "figure",
+    "glossary",
+    "grid",
+    "grid-item",
+    "grid-item-card",
+    "hint",
+    "image",
+    "important",
+    "include",
+    "index",
+    "literal-include",
+    "margin",
+    "math",
+    "note",
+    "prf:algorithm",
+    "prf:assumption",
+    "prf:axiom",
+    "prf:conjecture",
+    "prf:corollary",
+    "prf:criterion",
+    "prf:definition",
+    "prf:example",
+    "prf:lemma",
+    "prf:observation",
+    "prf:proof",
+    "prf:property",
+    "prf:proposition",
+    "prf:remark",
+    "prf:theorem",
+    "seealso",
+    "show-index",
+    "sidebar",
+    "solution",
+    "solution-end",
+    "solution-start",
+    "span",
+    "tab-item",
+    "tab-set",
+    "table",
+    "tip",
+    "todo",
+    "topics",
+    "warning",
+]
+
+
+def update_mdit(mdit: MarkdownIt) -> None:
+    # Enable mdformat-tables plugin
+    tables_plugin = mdformat.plugins.PARSER_EXTENSIONS["tables"]
+    if tables_plugin not in mdit.options["parser_extension"]:
+        mdit.options["parser_extension"].append(tables_plugin)
+        tables_plugin.update_mdit(mdit)
+
+    # Enable mdformat-frontmatter plugin
+    frontmatter_plugin = mdformat.plugins.PARSER_EXTENSIONS["frontmatter"]
+    if frontmatter_plugin not in mdit.options["parser_extension"]:
+        mdit.options["parser_extension"].append(frontmatter_plugin)
+        frontmatter_plugin.update_mdit(mdit)
+
+    # Enable mdformat-footnote plugin
+    footnote_plugin = mdformat.plugins.PARSER_EXTENSIONS["footnote"]
+    if footnote_plugin not in mdit.options["parser_extension"]:
+        mdit.options["parser_extension"].append(footnote_plugin)
+        footnote_plugin.update_mdit(mdit)
+
+    # Enable MyST role markdown-it extension
+    mdit.use(myst_role_plugin)
+
+    # Enable MyST block markdown-it extension (including "LineComment",
+    # "BlockBreak" and "Target" syntaxes)
+    mdit.use(myst_block_plugin)
+
+    # Enable dollarmath markdown-it extension
+    mdit.use(dollarmath_plugin)
+
+    # Trick `mdformat`s AST validation by removing HTML rendering of code
+    # blocks and fences. Directives are parsed as code fences and we
+    # modify them in ways that don't break MyST AST but do break
+    # CommonMark AST, so we need to do this to make validation pass.
+    mdit.add_render_rule("fence", render_fence_html)
+    mdit.add_render_rule("code_block", render_fence_html)
+
+    for name in container_names:
+        container_plugin(mdit, name="{" + name + "}", marker=":")
+
+
+def container_renderer(
+    node: RenderTreeNode, context: RenderContext, *args, **kwargs
+) -> str:
+    children = node.children
+    paragraphs = []
+    if children:
+        # Look at the tokens forming the first paragraph and see if
+        # they form a YAML header. This could be stricter: there
+        # should be exactly three tokens: paragraph open, YAML
+        # header, paragraph end.
+        tokens = children[0].to_tokens()
+        if all(
+            token.type in {"paragraph_open", "paragraph_close"}
+            or _YAML_HEADER_PATTERN.fullmatch(token.content)
+            for token in tokens
+        ):
+            paragraphs.append(
+                "\n".join(token.content.strip() for token in tokens if token.content)
+            )
+            # and skip that first paragraph
+            children = children[1:]
+
+    paragraphs.extend(child.render(context) for child in children)
+
+    return node.markup + node.info + "\n" + "\n\n".join(paragraphs) + "\n" + node.markup
+
+
+def _role_renderer(node: RenderTreeNode, context: RenderContext) -> str:
+    role_name = "{" + node.meta["name"] + "}"
+    role_content = f"`{node.content}`"
+    return role_name + role_content
+
+
+def _comment_renderer(node: RenderTreeNode, context: RenderContext) -> str:
+    return "%" + node.content.replace("\n", "\n%")
+
+
+def _blockbreak_renderer(node: RenderTreeNode, context: RenderContext) -> str:
+    text = "+++"
+    if node.content:
+        text += f" {node.content}"
+    return text
+
+
+def _target_renderer(node: RenderTreeNode, context: RenderContext) -> str:
+    return f"({node.content})="
+
+
+def _math_inline_renderer(node: RenderTreeNode, context: RenderContext) -> str:
+    return f"${node.content}$"
+
+
+def _math_block_renderer(node: RenderTreeNode, context: RenderContext) -> str:
+    indent_width = context.env.get("indent_width", 0)
+    if indent_width > 0:
+        return f"$${textwrap.dedent(node.content)}$$"
+    return f"$${node.content}$$"
+
+
+def _math_block_label_renderer(node: RenderTreeNode, context: RenderContext) -> str:
+    return f"{_math_block_renderer(node, context)} ({node.info})"
+
+
+def _math_block_safe_blockquote_renderer(
+    node: RenderTreeNode, context: RenderContext
+) -> str:
+    marker = "> "
+    with context.indented(len(marker)):
+        lines = []
+        for i, child in enumerate(node.children):
+            if child.type in ("math_block", "math_block_label"):
+                lines.append(child.render(context))
+            else:
+                lines.extend(child.render(context).splitlines())
+            if i < (len(node.children) - 1):
+                lines.append("")
+        if not lines:
+            return ">"
+        quoted_lines = (f"{marker}{line}" if line else ">" for line in lines)
+        quoted_str = "\n".join(quoted_lines)
+        return quoted_str
+
+
+def _render_children(node: RenderTreeNode, context: RenderContext) -> str:
+    return "\n\n".join(child.render(context) for child in node.children)
+
+
+def _escape_paragraph(text: str, node: RenderTreeNode, context: RenderContext) -> str:
+    lines = text.split("\n")
+
+    for i in range(len(lines)):
+        # Three or more "+" chars are interpreted as a block break. Escape them.
+        space_removed = lines[i].replace(" ", "")
+        if space_removed.startswith("+++"):
+            lines[i] = lines[i].replace("+", "\\+", 1)
+
+        # A line starting with "%" is a comment. Escape.
+        if lines[i].startswith("%"):
+            lines[i] = f"\\{lines[i]}"
+
+        # Escape lines that look like targets
+        if _TARGET_PATTERN.search(lines[i]):
+            lines[i] = lines[i].replace("(", "\\(", 1)
+
+    return "\n".join(lines)
+
+
+def _escape_text(text: str, node: RenderTreeNode, context: RenderContext) -> str:
+    # Escape MyST role names
+    text = _ROLE_NAME_PATTERN.sub(r"\\\1", text)
+
+    # Escape inline and block dollarmath
+    text = text.replace("$", "\\$")
+
+    return text
+
+
+RENDERERS = {
+    "blockquote": _math_block_safe_blockquote_renderer,
+    "myst_role": _role_renderer,
+    "myst_line_comment": _comment_renderer,
+    "myst_block_break": _blockbreak_renderer,
+    "myst_target": _target_renderer,
+    "math_inline": _math_inline_renderer,
+    "math_block_label": _math_block_label_renderer,
+    "math_block": _math_block_renderer,
+    "fence": fence,
+}
+
+
+for name in container_names:
+    RENDERERS["container_{" + name + "}"] = container_renderer
+
+POSTPROCESSORS = {"paragraph": _escape_paragraph, "text": _escape_text}

mdformat_py_edu_fr-0.1.7/src/mdformat_myst_pef/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561