markdown-include-variants 0.0.1__py3-none-any.whl

markdown_include_variants/__init__.py

@@ -0,0 +1,4 @@
+from ._main import IncludeVariantsExtension as IncludeVariantsExtension
+from ._main import IncludeVariantsPreprocessor as IncludeVariantsPreprocessor
+from ._main import makeExtension as makeExtension
+from ._version import __version__ as __version__

markdown_include_variants/_main.py

@@ -0,0 +1,308 @@
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, Union
+
+from markdown import Extension, Markdown
+from markdown.preprocessors import Preprocessor
+
+
+@dataclass(frozen=True)
+class Variant:
+    path: Path
+    title: str
+    is_annotated: Union[bool, None]
+    version: Literal["py38", "py39", "py310"]
+
+
+def calculate_variants(base_path: Path) -> dict[tuple[str, Union[bool, None]], Variant]:
+    base_name = base_path.stem
+    base_dir = base_path.parent
+    variants: dict[tuple[str, Union[bool, None]], Variant] = {}
+    an = "_an"
+    py39 = "_py39"
+    py310 = "_py310"
+    an_p310_path = base_dir / f"{base_name}{an}{py310}.py"
+    an_p39_path = base_dir / f"{base_name}{an}{py39}.py"
+    an_path = base_dir / f"{base_name}{an}.py"
+    p310_path = base_dir / f"{base_name}{py310}.py"
+    p39_path = base_dir / f"{base_name}{py39}.py"
+    if an_p310_path.exists():
+        v = Variant(
+            path=an_p310_path, title="Python 3.10+", is_annotated=True, version="py310"
+        )
+        variants[(v.version, v.is_annotated)] = v
+        if p310_path.exists():
+            v = Variant(
+                path=p310_path,
+                title="Python 3.10+ - non-Annotated",
+                is_annotated=False,
+                version="py310",
+            )
+            variants[(v.version, v.is_annotated)] = v
+    elif p310_path.exists():
+        v = Variant(
+            path=p310_path, title="Python 3.10+", is_annotated=None, version="py310"
+        )
+        variants[(v.version, v.is_annotated)] = v
+    if an_p39_path.exists():
+        v = Variant(
+            path=an_p39_path, title="Python 3.9+", is_annotated=True, version="py39"
+        )
+        variants[(v.version, v.is_annotated)] = v
+        if p39_path.exists():
+            v = Variant(
+                path=p39_path,
+                title="Python 3.9+ - non-Annotated",
+                is_annotated=False,
+                version="py39",
+            )
+            variants[(v.version, v.is_annotated)] = v
+    elif p39_path.exists():
+        v = Variant(
+            path=p39_path, title="Python 3.9+", is_annotated=None, version="py39"
+        )
+        variants[(v.version, v.is_annotated)] = v
+    if an_path.exists():
+        v = Variant(
+            path=an_path, title="Python 3.8+", is_annotated=True, version="py38"
+        )
+        variants[(v.version, v.is_annotated)] = v
+        if base_path.exists():
+            v = Variant(
+                path=base_path,
+                title="Python 3.8+ - non-Annotated",
+                is_annotated=False,
+                version="py38",
+            )
+            variants[(v.version, v.is_annotated)] = v
+    elif base_path.exists():
+        v = Variant(
+            path=base_path, title="Python 3.8+", is_annotated=None, version="py38"
+        )
+        variants[(v.version, v.is_annotated)] = v
+    return variants
+
+
+def parse_lines_index(include_lines_config: str) -> list[tuple[int, int]]:
+    lines = []
+    for line in include_lines_config.strip().split(","):
+        clean_line = line.strip()
+        if ":" in clean_line:
+            start, end = clean_line.split(":")
+            lines.append((int(start), int(end)))
+        else:
+            lines.append((int(line), int(line)))
+    lines.sort()
+    return lines
+
+
+@dataclass
+class IncludeInfo:
+    start: int
+    end: int
+    offset: int
+    hl_lines: list[tuple[int, int]]
+
+    def computed_hl_lines(self) -> list[tuple[int, int]]:
+        return [
+            (
+                hl_line[0] - self.start + self.offset + 1,
+                hl_line[1] - self.start + self.offset + 1,
+            )
+            for hl_line in self.hl_lines
+        ]
+
+
+def calculate_includes(
+    lines_to_include: list[tuple[int, int]], hl_lines: list[tuple[int, int]]
+) -> dict[tuple[int, int], IncludeInfo]:
+    lines_groups: dict[tuple[int, int], IncludeInfo] = {}
+    offset = 0
+    for i, line_group in enumerate(lines_to_include):
+        if line_group[0] > 1:
+            if i == 0:
+                offset = 2
+            else:
+                offset += 3
+        info = IncludeInfo(
+            start=line_group[0],
+            end=line_group[1],
+            offset=offset,
+            hl_lines=[],
+        )
+        offset += line_group[1] - line_group[0] + 1
+        for hl_line in hl_lines:
+            if hl_line[0] >= line_group[0] and hl_line[1] <= line_group[1]:
+                info.hl_lines.append(hl_line)
+        lines_groups[line_group] = info
+    return lines_groups
+
+
+re_line = r"^\{\*\s*(\S+)\s*(.*)\*\}$"
+re_config = r"(\w+)\[([^\]]+)\]"
+
+
+class IncludeVariantsPreprocessor(Preprocessor):
+    def run(self, lines: list[str]) -> list[str]:
+        new_lines = []
+        for line in lines:
+            line_match = re.match(re_line, line)
+            if not line_match:
+                new_lines.append(line)
+                continue
+            block_lines = []
+            src_file_str = line_match.group(1)
+            base_path = Path(src_file_str)
+
+            configs_str = line_match.group(2).strip()
+            include_lines: list[tuple[int, int]] = []
+            highlight_lines: list[tuple[int, int]] = []
+            for config_match in re.finditer(re_config, configs_str):
+                if config_match:
+                    name = config_match.group(1)
+                    ranges_str = config_match.group(2)
+                    ranges = parse_lines_index(ranges_str)
+                    if name == "ln":
+                        include_lines.extend(ranges)
+                    elif name == "hl":
+                        highlight_lines.extend(ranges)
+            use_hl_lines: list[tuple[int, int]] = []
+            if highlight_lines:
+                if include_lines:
+                    include_infos = calculate_includes(include_lines, highlight_lines)
+                    for info in include_infos.values():
+                        use_hl_lines.extend(info.computed_hl_lines())
+                else:
+                    use_hl_lines = highlight_lines
+            use_hl_lines_strs: list[str] = []
+            for hl_line in use_hl_lines:
+                if hl_line[0] == hl_line[1]:
+                    use_hl_lines_strs.append(str(hl_line[0]))
+                else:
+                    use_hl_lines_strs.append(f"{hl_line[0]}-{hl_line[1]}")
+            use_hl_lines_str = " ".join(use_hl_lines_strs)
+
+            variants = calculate_variants(base_path)
+            if len(variants) == 0:
+                raise FileNotFoundError(f"Could not find any variants for {base_path}")
+            sorted_variants: list[Variant] = []
+            for an in [True, False, None]:
+                for version in ["py310", "py39", "py38"]:
+                    v = variants.get((version, an))
+                    if v:
+                        sorted_variants.append(v)
+            assert sorted_variants
+            preferred_variant = sorted_variants[0]
+            content_lines = preferred_variant.path.read_text().splitlines()
+
+            internal_block_lines: list[str] = []
+            if not include_lines:
+                internal_block_lines.append(
+                    f"{{!{preferred_variant.path}!}}",
+                )
+            for i, line_group in enumerate(include_lines):
+                if i == 0 and line_group[0] > 1:
+                    internal_block_lines.extend(
+                        [
+                            "# Code above omitted 👆",
+                            "",
+                        ]
+                    )
+                if i >= 1:
+                    internal_block_lines.extend(
+                        [
+                            "",
+                            "# Code here omitted 👈",
+                            "",
+                        ]
+                    )
+                internal_block_lines.append(
+                    f"{{!{preferred_variant.path}[ln:{line_group[0]}-{line_group[1]}]!}}"
+                )
+                if i == len(include_lines) - 1 and line_group[1] < len(content_lines):
+                    internal_block_lines.extend(
+                        [
+                            "",
+                            "# Code below omitted 👇",
+                        ]
+                    )
+            first_line = "```python"
+            if use_hl_lines:
+                first_line += f' hl_lines="{use_hl_lines_str}"'
+
+            block_lines.extend(
+                [
+                    f"//// tab | {preferred_variant.title}" "",
+                    first_line,
+                    *internal_block_lines,
+                    "```",
+                    "",
+                    "////",
+                    "",
+                ]
+            )
+            if include_lines:
+                block_lines.extend(
+                    [
+                        "//// details | 👀 Full file preview",
+                        "",
+                        "```python",
+                        f"{{!{preferred_variant.path}!}}",
+                        "```",
+                        "",
+                        "////",
+                        "",
+                    ]
+                )
+            if len(sorted_variants) > 1:
+                block_lines.extend(
+                    [
+                        "///// details | 🤓 Other versions and variants",
+                        "",
+                    ]
+                )
+
+                for variant in sorted_variants[1:]:
+                    block_lines.extend([f"//// tab | {variant.title}", ""])
+                    if variant.is_annotated is False:
+                        block_lines.extend(
+                            [
+                                "/// tip",
+                                "",
+                                "Prefer to use the `Annotated` version if possible.",
+                                "",
+                                "///",
+                                "",
+                            ]
+                        )
+
+                    block_lines.extend(
+                        [
+                            "```python",
+                            f"{{!{variant.path}!}}",
+                            "```",
+                            "////",
+                        ]
+                    )
+
+                block_lines.extend(
+                    [
+                        "",
+                        "/////",
+                        "",
+                    ]
+                )
+            new_lines.extend(block_lines)
+        return new_lines
+
+
+class IncludeVariantsExtension(Extension):
+    def extendMarkdown(self, md: Markdown) -> None:
+        md.preprocessors.register(
+            IncludeVariantsPreprocessor(md), "include_variants", 110
+        )
+
+
+def makeExtension(*args, **kwargs):  # pragma: no cover
+    return IncludeVariantsExtension(*args, **kwargs)

markdown_include_variants/_version.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

markdown_include_variants-0.0.1.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.3
+Name: markdown-include-variants
+Version: 0.0.1
+Summary: Markdown extension to expand directives to include source example files to also include their variants. Only useful to tiangolo's projets. Don't use it. 😅
+Project-URL: Homepage, https://github.com/tiangolo/markdown-include-variants
+Project-URL: Repository, https://github.com/tiangolo/markdown-include-variants
+Project-URL: Issues, https://github.com/tiangolo/markdown-include-variants/issues
+Project-URL: Changelog, https://github.com/tiangolo/markdown-include-variants/release-notes.md
+Author-email: Sebastián Ramírez <tiangolo@gmail.com>
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: markdown>=3.7
+Description-Content-Type: text/markdown
+
+# markdown-include-variants
+
+<a href="https://github.com/tiangolo/markdown-include-variants/actions?query=workflow%3ATest" target="_blank">
+    <img src="https://github.com/tiangolo/markdown-include-variants/workflows/Test/badge.svg" alt="Test">
+</a>
+<a href="https://github.com/tiangolo/markdown-include-variants/actions?query=workflow%3APublish" target="_blank">
+    <img src="https://github.com/tiangolo/markdown-include-variants/workflows/Publish/badge.svg" alt="Publish">
+</a>
+<a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/tiangolo/markdown-include-variants" target="_blank">
+    <img src="https://coverage-badge.samuelcolvin.workers.dev/tiangolo/markdown-include-variants.svg" alt="Coverage">
+<a href="https://pypi.org/project/markdown-include-variants" target="_blank">
+    <img src="https://img.shields.io/pypi/v/markdown-include-variants?color=%2334D058&label=pypi%20package" alt="Package version">
+</a>
+
+---
+
+## 🚨 Warning: Internal Project
+
+This is an internal project, it is mainly useful for the docs in [@tiangolo](https://github.com/tiangolo)'s projects (e.g. all the [FastAPI](https://github.com/fastapi) projects).
+
+It is probably **not useful** to you. You should probably not use it. 😅
+
+There are no guarantees about behavior, it is made to suit the needs of these projects, to simplify writing documentation.
+
+## How to Use
+
+If you're still here it's probably because you are getting involved in one of the projects that use it. 🤓
+
+Here's how it works:
+
+* You add a Python source example to the `docs_src` directory, with the minimum Python version supported by the project, and using the old format without `Annotated`, if that applies, it would be named something like `tutorial001.py`.
+* Copy the file and update it to use `Annotated` (if that applies), and name the file with a "tag" (a prefix) of `an`, like: `tutorial001_an.py`.
+* Run the internal script to generate the variants of the files for superior versions of Python, like `3.9`, `3.10`, etc. (this internal script is in the project itself). This would generate files like `tutorial001_py39.py`, `tutorial001_py310.py`, etc. and `tutorial001_an_py39.py`, `tutorial001_an_py310.py`, etc.
+* In the Markdown file, include the simplest version of the file, using this syntax:
+
+```markdown
+{* ./docs_src/first_steps/tutorial001.py *}
+```
+
+That will be automatically expanded with [mdx-include](https://github.com/neurobin/mdx_include) to include the recommended version of the file (the highest version of Python, using `Annotated`), and will include the variants below in a collapsed `details` box.
+
+### Include Lines
+
+To include specific line ranges, use the config `ln`:
+
+```markdown
+{* ./docs_src/first_steps/tutorial001.py ln[3:6,8,10:11] *}
+```
+
+That will include only:
+
+* lines 3 to 6
+* line 8
+* lines 10 to 11
+
+It will add blocks with comments in the middle like:
+
+```python
+# Code here omitted 👈️
+```
+
+If you include specific lines, it will also add another collapsed `details` box with the "Full file preview".
+
+### Highlight Lines
+
+You can highlight specific lines using the config `hl`:
+
+```markdown
+{* ./docs_src/first_steps/tutorial001.py hl[3,5:7,10] *}
+```
+
+That will highlight:
+
+* line 3
+* lines 5 to 7
+* line 10
+
+Have in mind that the file path points to the simplest version of the file, the one without the `_an` suffix. But the main file shown will be the highest (recommended) version, and the highlights will apply to that file.
+
+So, when deciding which lines to highlight, do that based on the highest version of the file.
+
+### Include Lines and Highlight
+
+You can combine both `ln` and `hl`:
+
+```markdown
+{* ./docs_src/first_steps/tutorial001.py ln[3:6,8,10:11] hl[3,5:6,10] *}
+```
+
+The highlighted lines refer to the source file (for the highest/recommended version), not the final rendered code block.
+
+This makes it easier to decide which lines to highlight just by opening the source file, without having to calculate the actual lines in the rendered block after included, the extra lines for comments when omitting lines, etc.
+
+### Include Lines and Highlight - Example
+
+For example, you could have a source file with:
+
+```python
+print("line 1")
+print("line 2")
+print("line 3")
+print("line 4")
+print("line 5")
+print("line 6")  # highlight this
+print("line 7")
+```
+
+Using a declaration like this:
+
+```markdown
+{* ./docs_src/first_steps/tutorial001.py ln[5:7] hl[6] *}
+```
+
+Could render something like:
+
+```python
+# Code above omitted 👈️
+
+print("line 5")
+print("line 6")  # highlight this
+print("line 7")
+```
+
+Notice that the comment above adds 2 extra lines, and only the desired lines are included, the result is that the actual highlighted line is the rendered line 4, but the source line 6, it's all calculated automatically. 🤓
+
+## License
+
+This project is licensed under the terms of the [MIT license](https://github.com/tiangolo/markdown-include-variants/blob/main/LICENSE).

markdown_include_variants-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+markdown_include_variants/__init__.py,sha256=RmaChbqZsW3M0uLEui5TuxIIRNyiDlAT5SZ3girx0Yg,249
+markdown_include_variants/_main.py,sha256=hgg1J_ai-YTiCdGAGz1rlZPx1a-jtGZP6oaMd1C_GQo,10805
+markdown_include_variants/_version.py,sha256=sXLh7g3KC4QCFxcZGBTpG2scR7hmmBsMjq6LqRptkRg,22
+markdown_include_variants/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+markdown_include_variants-0.0.1.dist-info/METADATA,sha256=LzaTfegkmZgbXlPEnQDd-PVvVyW31VSVeQ7ihpU_lTI,5791
+markdown_include_variants-0.0.1.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+markdown_include_variants-0.0.1.dist-info/licenses/LICENSE,sha256=FqD5B4VbXJnefprQseE0U8llL6FxojC-i8muZy7YmSU,1086
+markdown_include_variants-0.0.1.dist-info/RECORD,,

markdown_include_variants-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.25.0
+Root-Is-Purelib: true
+Tag: py3-none-any

markdown_include_variants-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Sebastián Ramírez
+
+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.