MDit 0.0.0.dev0__tar.gz → 0.0.0.dev2__tar.gz

mdit-0.0.0.dev2/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.1
+Name: MDit
+Version: 0.0.0.dev2
+Requires-Python: >=3.10
+Requires-Dist: sphinx<8
+Requires-Dist: myst-parser<4,>3
+Requires-Dist: pydata-sphinx-theme
+Requires-Dist: sphinx-togglebutton
+Requires-Dist: sphinx-design
+Requires-Dist: markdown-it-py
+Requires-Dist: mdit-py-plugins
+Requires-Dist: linkify-it-py
+Requires-Dist: readme-renderer
+Requires-Dist: cmarkgfm
+Requires-Dist: zundler
+Requires-Dist: PkgData
+Requires-Dist: PySerials
+Requires-Dist: PyLinks
+Requires-Dist: PyBadger
+Requires-Dist: PyColorIt
+Requires-Dist: IPython
+Requires-Dist: jupyterlab_myst
+Requires-Dist: PyProtocol
+Requires-Dist: HTMP
+Requires-Dist: ansi-sgr
+Requires-Dist: pygments
+Requires-Dist: rich

{mdit-0.0.0.dev0 → mdit-0.0.0.dev2}/pyproject.toml

@@ -17,15 +17,31 @@ namespaces = true
 # ----------------------------------------- Project Metadata -------------------------------------
 #
 [project]
-version = "0.0.0.dev0"
+version = "0.0.0.dev2"
 name = "MDit"
 requires-python = ">=3.10"
 dependencies = [
-    "IPython",
-    "PyProtocol",
+    "sphinx < 8",
+    "myst-parser > 3, < 4",
+    "pydata-sphinx-theme",
+    "sphinx-togglebutton",
+    "sphinx-design",
     "markdown-it-py",
     "mdit-py-plugins",
     "linkify-it-py",
     "readme-renderer",
     "cmarkgfm",
+    "zundler",
+    "PkgData",
+    "PySerials",
+    "PyLinks",
+    "PyBadger",
+    "PyColorIt",
+    "IPython",
+    "jupyterlab_myst",
+    "PyProtocol",
+    "HTMP",
+    "ansi-sgr",
+    "pygments",
+    "rich",
 ]

mdit-0.0.0.dev2/src/MDit.egg-info/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.1
+Name: MDit
+Version: 0.0.0.dev2
+Requires-Python: >=3.10
+Requires-Dist: sphinx<8
+Requires-Dist: myst-parser<4,>3
+Requires-Dist: pydata-sphinx-theme
+Requires-Dist: sphinx-togglebutton
+Requires-Dist: sphinx-design
+Requires-Dist: markdown-it-py
+Requires-Dist: mdit-py-plugins
+Requires-Dist: linkify-it-py
+Requires-Dist: readme-renderer
+Requires-Dist: cmarkgfm
+Requires-Dist: zundler
+Requires-Dist: PkgData
+Requires-Dist: PySerials
+Requires-Dist: PyLinks
+Requires-Dist: PyBadger
+Requires-Dist: PyColorIt
+Requires-Dist: IPython
+Requires-Dist: jupyterlab_myst
+Requires-Dist: PyProtocol
+Requires-Dist: HTMP
+Requires-Dist: ansi-sgr
+Requires-Dist: pygments
+Requires-Dist: rich

{mdit-0.0.0.dev0 → mdit-0.0.0.dev2}/src/MDit.egg-info/SOURCES.txt

@@ -9,6 +9,17 @@ src/MDit.egg-info/top_level.txt
 src/mdit/__init__.py
 src/mdit/container.py
 src/mdit/display.py
+src/mdit/document.py
 src/mdit/element.py
+src/mdit/generate.py
 src/mdit/parse.py
-src/mdit/render.py
+src/mdit/protocol.py
+src/mdit/render.py
+src/mdit/renderable.py
+src/mdit/template.py
+src/mdit/data/__init__.py
+src/mdit/data/file.py
+src/mdit/data/schema.py
+src/mdit/target/__init__.py
+src/mdit/target/md.py
+src/mdit/target/rich.py

mdit-0.0.0.dev2/src/MDit.egg-info/requires.txt

@@ -0,0 +1,23 @@
+sphinx<8
+myst-parser<4,>3
+pydata-sphinx-theme
+sphinx-togglebutton
+sphinx-design
+markdown-it-py
+mdit-py-plugins
+linkify-it-py
+readme-renderer
+cmarkgfm
+zundler
+PkgData
+PySerials
+PyLinks
+PyBadger
+PyColorIt
+IPython
+jupyterlab_myst
+PyProtocol
+HTMP
+ansi-sgr
+pygments
+rich

mdit-0.0.0.dev2/src/mdit/__init__.py

@@ -0,0 +1,220 @@
+"""Generate and process Markdown content.
+
+References
+----------
+- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING as _TYPE_CHECKING
+
+from mdit import display
+from mdit.container import Container, MDContainer
+from mdit.document import Document
+from mdit.generate import DocumentGenerator
+from mdit import render, target, element, parse, protocol, template
+
+if _TYPE_CHECKING:
+    from typing import Callable
+    from mdit.protocol import ContainerContentType, ContainerContentInputType, ContainerContentSingleInputType, Stringable, TargetConfig, TargetConfigs, MDTargetConfig, RichTargetConfig, ContainerContentInputType
+
+
+def generate(config: dict | list):
+    return DocumentGenerator().generate(config)
+
+
+def document(
+    heading: element.Heading | MDContainer | ContainerContentInputType = None,
+    body: MDContainer | ContainerContentInputType = None,
+    section: Container | None = None,
+    footer: MDContainer | ContainerContentInputType = None,
+    frontmatter: dict | element.FrontMatter | None = None,
+    frontmatter_conditions: list[str] | None = None,
+    separate_sections: bool = False,
+    current_section_key: list[str | int] | None = None,
+    toctree_args: dict[str, str] | None = None,
+    toctree_dirhtml: bool = True,
+    target_configs_md: dict[str, MDTargetConfig | dict] | None = None,
+    target_configs_rich: dict[str, RichTargetConfig | dict] | None = None,
+    target_default: str = "sphinx",
+    deep_section_generator: Callable[[Document], str] | None = None,
+    content_separator_heading: str = "",
+):
+    # Process target configs
+    target_configs = {}
+    for key, config in (target_configs_md or {}).items():
+        config_obj = config if isinstance(config, protocol.MDTargetConfig) else target.md.Config(**config)
+        target_configs[key] = config_obj
+    for key, config in (target_configs_rich or {}).items():
+        config_obj = config if isinstance(config, protocol.RichTargetConfig) else target.rich.Config(**config)
+        if key in target_configs:
+            raise ValueError(f"Target config key '{key}' already exists.")
+        target_configs[key] = config_obj
+    # Process heading
+    if heading and not isinstance(heading, element.Heading):
+        heading = element.heading(
+            content=heading,
+            target_configs=target_configs,
+            target_default=target_default,
+        )
+    body = to_block_container(body)
+    if isinstance(section, Container):
+        pass
+    elif not section:
+        section = section_container()
+    elif isinstance(section, dict):
+        section = section_container(**section)
+    elif isinstance(section, (list, tuple)):
+        section = section_container(*section)
+    else:
+        section = section_container(section)
+    footer = to_block_container(footer)
+    if isinstance(frontmatter, dict):
+        frontmatter = element.frontmatter(frontmatter)
+    return Document(
+        heading=heading,
+        body=body,
+        section=section,
+        footer=footer,
+        frontmatter=frontmatter,
+        frontmatter_conditions=frontmatter_conditions,
+        separate_sections=separate_sections,
+        current_section_key=current_section_key,
+        toctree_args=toctree_args,
+        toctree_dirhtml=toctree_dirhtml,
+        target_configs=target_configs,
+        target_default=target_default,
+        deep_section_generator=deep_section_generator,
+    )
+
+def block_container(
+    *contents: ContainerContentInputType,
+    html_container: Stringable | None = None,
+    html_container_attrs: dict | None = None,
+    html_container_conditions: list[str] | None = None,
+    target_configs: TargetConfigs = None,
+    target_default: str = "sphinx",
+) -> MDContainer:
+    return container(
+        *contents,
+        content_separator="\n\n",
+        html_container=html_container,
+        html_container_attrs=html_container_attrs,
+        html_container_conditions=html_container_conditions,
+        target_configs=target_configs,
+        target_default=target_default,
+    )
+
+
+def inline_container(
+    *contents: ContainerContentInputType,
+    separator: str = "",
+    html_container: Stringable | None = None,
+    html_container_attrs: dict | None = None,
+    html_container_conditions: list[str] | None = None,
+    target_configs: TargetConfigs = None,
+    target_default: str = "sphinx",
+) -> MDContainer:
+    return container(
+        *contents,
+        content_separator=separator,
+        html_container=html_container,
+        html_container_attrs=html_container_attrs,
+        html_container_conditions=html_container_conditions,
+        target_configs=target_configs,
+        target_default=target_default,
+    )
+
+
+def container(
+    *contents: ContainerContentInputType,
+    content_separator: str,
+    html_container: Stringable | None = None,
+    html_container_attrs: dict | None = None,
+    html_container_conditions: list[str] | None = None,
+    target_configs: TargetConfigs = None,
+    target_default: str = "sphinx",
+) -> MDContainer:
+    container_ = MDContainer(
+        content_separator=content_separator,
+        html_container=html_container,
+        html_container_attrs=html_container_attrs,
+        html_container_conditions=html_container_conditions,
+        target_configs=target_configs,
+        target_default=target_default,
+    )
+    container_.extend(list(contents))
+    return container_
+
+
+def section_container(
+    *unlabeled_contents: ContainerContentInputType,
+    **labeled_contents: ContainerContentInputType,
+) -> Container:
+    container_ = Container()
+    container_.extend(*unlabeled_contents, **labeled_contents)
+    return container_
+
+
+def to_block_container(
+    content: MDContainer | ContainerContentInputType,
+    separator: str = "\n\n",
+    html_container: Stringable | None = None,
+    html_container_attrs: dict | None = None,
+    html_container_conditions: list[str] | None = None,
+    target_configs: TargetConfigs = None,
+    target_default: str = "sphinx",
+) -> MDContainer:
+    return to_md_container(
+        content,
+        content_separator=separator,
+        html_container=html_container,
+        html_container_attrs=html_container_attrs,
+        html_container_conditions=html_container_conditions,
+        target_configs=target_configs,
+        target_default=target_default,
+    )
+
+
+def to_inline_container(
+    content: MDContainer | ContainerContentInputType,
+    separator: str = "",
+    html_container: Stringable | None = None,
+    html_container_attrs: dict | None = None,
+    html_container_conditions: list[str] | None = None,
+    target_configs: TargetConfigs = None,
+    target_default: str = "sphinx",
+) -> MDContainer:
+    return to_md_container(
+        content,
+        content_separator=separator,
+        html_container=html_container,
+        html_container_attrs=html_container_attrs,
+        html_container_conditions=html_container_conditions,
+        target_configs=target_configs,
+        target_default=target_default,
+    )
+
+
+def to_md_container(
+    content: MDContainer | ContainerContentInputType,
+    content_separator: str,
+    html_container: Stringable | None = None,
+    html_container_attrs: dict | None = None,
+    html_container_conditions: list[str] | None = None,
+    target_configs: TargetConfigs = None,
+    target_default: str = "sphinx",
+) -> MDContainer:
+    if isinstance(content, MDContainer):
+        return content
+    container_ = MDContainer(
+        content_separator=content_separator,
+        html_container=html_container,
+        html_container_attrs=html_container_attrs,
+        html_container_conditions=html_container_conditions,
+        target_configs=target_configs,
+        target_default=target_default,
+    )
+    container_.extend(content)
+    return container_

mdit-0.0.0.dev2/src/mdit/container.py

@@ -0,0 +1,209 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING as _TYPE_CHECKING, NamedTuple as _NamedTuple
+
+import htmp as _htmp
+import rich
+import rich.text
+import rich.markdown
+
+from mdit.protocol import MDITRenderable as _MDCode
+from mdit.renderable import Renderable as _Renderable
+
+if _TYPE_CHECKING:
+    from rich.console import RenderableType
+    from mdit.protocol import ContainerContentType, ContainerContentConditionType, ContainerContentInputType, TargetConfigs, Stringable, MDTargetConfig, RichTargetConfig
+
+
+class ContainerContent(_NamedTuple):
+    content: ContainerContentType
+    conditions: list[str]
+
+
+class Container:
+
+    def __init__(
+        self,
+        data: dict[str | int, ContainerContent] | None = None,
+        *args,
+        **kwargs
+    ):
+        self._data = data or {}
+        super().__init__(*args, **kwargs)
+        return
+
+    def append(
+        self,
+        content: ContainerContentType,
+        conditions: ContainerContentConditionType = None,
+        key: str | int | None = None
+    ) -> str | int:
+        if not key:
+            key = max((key for key in self._data.keys() if isinstance(key, int)), default=-1) + 1
+        if key in self._data:
+            raise ValueError("Key already exists in content.")
+        if not conditions:
+            conditions = []
+        elif isinstance(conditions, str):
+            conditions = [conditions]
+        else:
+            conditions = list(conditions)
+        self._data[key] = ContainerContent(content=content, conditions=conditions)
+        return key
+
+    def extend(self, *unlabeled_contents: ContainerContentInputType, **labeled_contents: ContainerContentInputType) -> list[str | int]:
+
+        def resolve_value(input_values):
+            if not input_values:
+                return
+            if isinstance(input_values, list):
+                for input_value in input_values:
+                    yield from resolve_value(input_value)
+            elif isinstance(input_values, tuple):
+                val = input_values[0]
+                cond = input_values[1] if len(input_values) > 1 else None
+                key = input_values[2] if len(input_values) > 2 else None
+                yield val, cond, key
+            elif isinstance(input_values, dict):
+                for k, v in input_values.items():
+                    key = k
+                    if isinstance(v, (list, tuple)):
+                        val = v[0]
+                        cond = v[1] if len(v) > 1 else None
+                    else:
+                        val = v
+                        cond = None
+                    yield val, cond, key
+            else:
+                yield input_values, None, None
+
+        added_keys = []
+        if unlabeled_contents:
+            first_available_key = max(
+                (key for key in self._data.keys() if isinstance(key, int)), default=-1
+            ) + 1
+            for idx, value in enumerate(unlabeled_contents):
+                for content, conditions, key in resolve_value(value):
+                    added_keys.append(self.append(content, conditions, key or first_available_key + idx))
+        if labeled_contents:
+            for key, value in labeled_contents.items():
+                for content, conditions, sub_key in resolve_value(value):
+                    final_key = key if sub_key is None else f"{key}.{sub_key}"
+                    added_keys.append(self.append(content, conditions, final_key))
+        return added_keys
+
+    def elements(
+        self,
+        target: TargetConfigs | None = None,
+        filters: str | list[str] | None = None,
+        source: bool = False,
+    ) -> list:
+        elements = []
+        if isinstance(filters, str):
+            filters = [filters]
+        for content, conditions in self.values():
+            if not filters or not conditions or any(filter in conditions for filter in filters):
+                if not source:
+                    elements.append(content)
+                elif isinstance(content, _MDCode):
+                    elements.append(content.source(target=target, filters=filters))
+                else:
+                    elements.append(str(content))
+        return elements
+
+    def get(self, key: str | int, default=None):
+        return self._data.get(key, default)
+
+    def keys(self):
+        return self._data.keys()
+
+    def values(self):
+        return self._data.values()
+
+    def items(self):
+        return self._data.items()
+
+    def __getitem__(self, item):
+        return self._data[item]
+
+    def __setitem__(self, key, value):
+        self._data[key] = value
+        return
+
+    def __contains__(self, item):
+        return item in self._data
+
+    def __bool__(self):
+        return bool(self._data)
+
+    def __len__(self):
+        return len(self._data)
+
+
+class MDContainer(Container, _Renderable):
+    # Multiple inheritance: https://stackoverflow.com/questions/9575409/calling-parent-class-init-with-multiple-inheritance-whats-the-right-way
+    def __init__(
+        self,
+        content: dict[str | int, ContainerContent] | None = None,
+        content_separator: str = "\n\n",
+        html_container: Stringable | None = None,
+        html_container_attrs: dict | None = None,
+        html_container_conditions: list[str] | None = None,
+        target_configs: TargetConfigs = None,
+        target_default: str = "sphinx"
+    ):
+        super().__init__(
+            data=content,
+            target_configs=target_configs,
+            target_default=target_default
+        )
+        self.content_separator = content_separator
+        self.html_container = html_container
+        self.html_container_attrs = html_container_attrs or {}
+        self.html_container_conditions = html_container_conditions or []
+        return
+
+    @property
+    def code_fence_count(self) -> int:
+        return max(
+            (
+                content.code_fence_count if isinstance(content, _MDCode)
+                else self._count_code_fence(str(content))
+                for content, _ in self._data.values()
+            ),
+            default=0,
+        )
+
+    def _source_rich(self, target: RichTargetConfig, filters: str | list[str] | None = None) -> RenderableType:
+        block_container = "\n" in self.content_separator
+        elements = self.elements(target=target, filters=filters, source=True)
+        if not elements:
+            return ""
+        if block_container:
+            group = [
+                rich.markdown.Markdown(element) if isinstance(element, str) else element
+                for element in elements
+            ]
+            return rich.console.Group(*group) if len(group) > 1 else group[0]
+        text = rich.text.Text()
+        for element in elements[:-1]:
+            text.append(element)
+            text.append(self.content_separator)
+        text.append(elements[-1])
+        return text
+
+    def _source_md(self, target: MDTargetConfig, filters: str | list[str] | None = None) -> str:
+        elements = self.elements(target=target, filters=filters, source=True)
+        elements_str = self.content_separator.join(elements)
+        if self.html_container and self.html_container_attrs and (
+            not filters
+            or not self.html_container_conditions
+            or any(filter in self.html_container_conditions for filter in filters)
+        ):
+            container_func = getattr(_htmp.element, str(self.html_container))
+            return container_func(_htmp.elementor.markdown(elements_str), self.html_container_attrs).source(
+                indent=-1)
+        return elements_str
+
+    def __str__(self) -> str:
+        return self.source()

mdit-0.0.0.dev2/src/mdit/data/__init__.py

@@ -0,0 +1,3 @@
+"""Work with the package's data files and JSON schemas."""
+
+from mdit.data import file, schema

mdit-0.0.0.dev2/src/mdit/data/file.py

@@ -0,0 +1,75 @@
+"""Get package data files."""
+
+from pathlib import Path as _Path
+
+import pkgdata as _pkgdata
+import pyserials as _ps
+
+
+path = _pkgdata.get_package_path_from_caller(top_level=True) / "data"
+
+
+def template(group: str, name: str) -> str:
+    """Get the string content of a template."""
+    dir_path = path / "template" / group
+    for filepath in dir_path.iterdir():
+        if filepath.stem == name:
+            return filepath.read_text()
+
+
+def schema(schema_id: str | None = None, relative_uri: bool = True) -> dict:
+    """Get all JSON schemas as a dictionary of schema IDs to schema objects.
+
+    Parameters
+    ----------
+    schema_id : str, optional
+        If provided, return only the schema with the given ID, otherwise all schemas.
+        The schema ID can be either an absolute or relative URI, i.e., with or without
+        the "https://docsman.repodynamics.com/schema/" prefix.
+    relative_uri : bool, default: True
+        Only applies when `schema_id` is not provided:
+        If True, the schema IDs (i.e., the keys of the returned dictionary)
+        will be relative URIs instead of absolute URIs,
+        i.e., without the "https://docsman.repodynamics.com/schema/" prefix.
+
+    Returns
+    -------
+    dict
+        If `schema_id` is provided, the schema object is returned,
+        otherwise a dictionary of JSON schemas with their IDs as keys.
+        The schema IDs are relative URIs if `relative_uri` is True.
+    """
+    dir_path = path / "schema"
+    if schema_id:
+        filepath = dir_path / schema_id.removeprefix("https://docsman.repodynamics.com/schema/")
+        filepath_full = filepath.with_suffix(".yaml")
+        return _ps.read.yaml_from_file(path=filepath_full)
+    schemas = {}
+    for filepath in dir_path.glob("**/*.yaml"):
+        schema = _ps.read.yaml_from_file(path=filepath)
+        schema_id = schema["$id"].removeprefix(
+            "https://docsman.repodynamics.com/schema/" if relative_uri else ""
+        )
+        schemas[schema_id] = schema
+    return schemas
+
+
+def from_filepath(filepath: str | _Path) -> str | dict | list:
+    """Get a package data file from its relative path.
+
+    Parameters
+    ----------
+    filepath : str
+        Path of the data file relative to the package's `data` directory.
+
+    Returns
+    -------
+    file_content : str | dict | list
+        The content of the file.
+        If the file is a serialized data structure (e.g., JSON or YAML),
+        the content will be deserialized, otherwise a string is returned.
+    """
+    absolute_filepath = path / filepath
+    if absolute_filepath.suffix in (".json", ".yaml", ".yml", "toml"):
+        return _ps.read.from_file(path=absolute_filepath)
+    return absolute_filepath.read_text()

mdit-0.0.0.dev2/src/mdit/data/schema.py

@@ -0,0 +1,50 @@
+"""Work with JSON schemas defined by the package."""
+
+from typing import Callable as _Callable
+
+import referencing as _referencing
+from referencing import jsonschema as _ref_jsonschema
+import jsonschemata as _jsonschemata
+import pyserials as _ps
+
+from mdit.data import file as _file
+
+
+_REGISTRY = None
+_SCHEMATA = None
+
+
+def make_registry(
+    dynamic: bool = False,
+    crawl: bool = True,
+    add_resources: list[dict | _referencing.Resource | tuple[str, dict | _referencing.Resource]] | None = None,
+    add_resources_default_spec: _referencing.Specification = _ref_jsonschema.DRAFT202012,
+    retrieval_func: _Callable[[str], str | _referencing.Resource] = None,
+) -> tuple[_referencing.Registry, dict[str, dict]]:
+    schemata = _file.schema(relative_uri=False)
+    resources = add_resources or []
+    for schema in schemata.values():
+        _jsonschemata.edit.required_last(schema)
+        resources.append(schema)
+    registry = _jsonschemata.registry.make(
+        dynamic=dynamic,
+        crawl=crawl,
+        add_resources=resources,
+        add_resources_default_spec=add_resources_default_spec,
+        retrieval_func=retrieval_func,
+    )
+    return registry, schemata
+
+
+def validate(data: dict, schema_id: str):
+    global _REGISTRY, _SCHEMATA
+    if not _REGISTRY:
+        _REGISTRY, _SCHEMATA = make_registry()
+    _ps.validate.jsonschema(
+        data=data,
+        schema=_SCHEMATA[schema_id],
+        registry=_REGISTRY,
+        fill_defaults=True,
+    )
+    return
+