pyodide-mkdocs-theme 5.1.8__tar.gz → 5.4.3__tar.gz

{pyodide_mkdocs_theme-5.1.8 → pyodide_mkdocs_theme-5.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pyodide-mkdocs-theme
-Version: 5.1.8
+Version: 5.4.3
 Summary: Package embedding the necessary tools to host pyodide, ACE editors, jQuery terminals in mkdocs documentations
 License: GPL-3.0-or-later
 Keywords: mkdocs,mkdocs-plugin,pyodide,IDE,terminal
@@ -23,9 +23,11 @@ Classifier: Programming Language :: JavaScript
 Classifier: Topic :: Documentation
 Classifier: Topic :: Software Development :: Documentation
 Classifier: Topic :: Text Processing :: Markup :: HTML
+Requires-Dist: click (<=8.2.1)
 Requires-Dist: mkdocs (>=1.6)
-Requires-Dist: mkdocs-macros-plugin (>=1.2.0)
+Requires-Dist: mkdocs-macros-plugin (>=1.4)
 Requires-Dist: mkdocs-material (>=9.5)
+Requires-Dist: pymdown-extensions (>=10.11)
 Project-URL: Bug Tracker, https://gitlab.com/frederic-zinelli/pyodide-mkdocs-theme/-/issues
 Project-URL: Documentation, http://frederic-zinelli.gitlab.io/pyodide-mkdocs-theme/
 Project-URL: Homepage, http://frederic-zinelli.gitlab.io/pyodide-mkdocs-theme/

{pyodide_mkdocs_theme-5.1.8 → pyodide_mkdocs_theme-5.4.3}/pyodide_mkdocs_theme/PMT_tools/p5/__init__.py

@@ -4,7 +4,7 @@ p5.js wrapper for Pyodide-MkDocs-Theme, by Frédéric Zinelli.
 Basic use:
 
 1. Import p5 as a namespace (no wildcard imports!):
-2. Define the setup and draw callbacks, using calls to the original p6 JS functions,
+2. Define the setup and draw callbacks, using calls to the original p5 JS functions,
    using`p5.functionName()` syntax.
 3. Call `p5.run(setup, draw, preload, target="div_id")` at the end of the code (`preload`
    is optional / `target` is also optional and defaults to the current PMT option value

{pyodide_mkdocs_theme-5.1.8 → pyodide_mkdocs_theme-5.4.3}/pyodide_mkdocs_theme/__main__.py

@@ -27,11 +27,18 @@ from contextlib import redirect_stdout
 from .__version__ import __version__
 from .basthon_p5_to_pmt import update_basthon_p5_code
 
-
 PMT_SCRIPTS = 'scripts'
 
 MIMES = "https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types"
-LANGS = ('de', 'en', 'fr')
+
+
+# WARNING: do not import PMT python packages from here, otherwise troubles in devops scripts.
+MESSAGES_DIR = Path(__file__).parent / 'pyodide_macros' / 'messages'
+LANG_FILE_SUFFIX = "_lang.py"
+N_END = len(LANG_FILE_SUFFIX)
+LANGS = tuple(
+    p.name[:-N_END] for p in MESSAGES_DIR.iterdir() if p.name.endswith(LANG_FILE_SUFFIX)
+)
 
 
 
@@ -60,9 +67,10 @@ parser.add_argument(
 parser.add_argument(
     '--lang', action='extend', nargs='*', choices=LANGS, default=[],
     help=f'Optional. Choices: { ", ".join(LANGS) }. '
-         'Print the base python code to customize some messages. '
-         'Can also be used with other arguments to get the information in languages other '
-         'than "fr", when relevant.'
+         'Can be used with other arguments to get the information/files in languages other '
+         'than "fr", when relevant. '
+         '([DEPRECATED]: Print the base python code to customize some messages. From PMT 5.3.0, '
+         "use the plugin's configuration to change PMT messages.)"
 )
 parser.add_argument(    # Effect strictly equivalent to --lang, but present for semantic
     '-M', '--macros', action='store_true',
@@ -240,8 +248,7 @@ def main():
         'plot':     'pyodide_plot.py',
         'py':       'docs/exo.py',
         'toolbox':  'toolbox.py',
-        'yml':      'mkdocs.yml',
-        'lang':     'main.py' ,
+        'yml':      'mkdocs.yml'
     }
 
     if args.basthonP5:
@@ -275,7 +282,10 @@ def main():
 
     if not did_some and args.lang:
         did_some = True
-        handle_one_file(args, 'lang')
+        print(
+            "From PMT 5.3.0, you should update Lang messages directly through the plugin's configuration. "
+            "The old `env.lang.overload` way is still supported, but it should not be used anymore."
+        )
 
 
     if raise_toolbox:

pyodide_mkdocs_theme-5.4.3/pyodide_mkdocs_theme/__version__.py

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

{pyodide_mkdocs_theme-5.1.8 → pyodide_mkdocs_theme-5.4.3}/pyodide_mkdocs_theme/pyodide_macros/__init__.py

@@ -19,8 +19,8 @@ If not, see <https://www.gnu.org/licenses/>.
 
 
 from .plugin.pyodide_macros_plugin import PyodideMacrosPlugin
-from .plugin.config.dumpers import *
-from .plugin.tools.macros_data import (
+from .plugin_config.dumpers import *
+from .plugin_tools.macros_data import (
     MacroData,
     MacroDataIDE,
     MacroDataTerminal,

{pyodide_mkdocs_theme-5.1.8 → pyodide_mkdocs_theme-5.4.3}/pyodide_mkdocs_theme/pyodide_macros/exceptions.py

@@ -103,7 +103,8 @@ class PmtInvalidSyntaxError(PmtIndentParserError):
 
 class PmtIndentedMacroError(PmtIndentParserError):
     """
-    A macro with indent has been called while text is found on its left.
+    A macro with indent has been called while text is found on its left, or a user defined
+    macro with indent has been used and it didn't call the methods managing the indentation.
     """
 
 class PmtTabulationError(PmtIndentParserError):
@@ -162,11 +163,11 @@ class PmtMacrosInvalidArgumentError(PmtMacrosError):
 
 class PmtMultiRemSourcesError(PmtMacrosError):
     """
-    REMs contents set both with a md file and through a PYODIDE:section.
+    REMs contents set both with a md file and through a PMT:section.
     """
 
 
-class PmtMacrosInvalidPyFileError(PmtMacrosError):
+class PmtMacrosInvalidPmtFileError(PmtMacrosError):
     """
     File missing or with invalid content.
     """
@@ -176,12 +177,12 @@ class PmtMacrosComposerError(PmtMacrosError):
     Invalid composition instruction.
     """
 
-class PmtMacrosInvalidSectionError(PmtMacrosInvalidPyFileError):
+class PmtMacrosInvalidSectionError(PmtMacrosInvalidPmtFileError):
     """
-    Invalid PYODIDE section name.
+    Invalid PMT section name.
     """
 
-class PmtPythonPyInclusionError(PmtMacrosInvalidPyFileError):
+class PmtPythonPyInclusionError(PmtMacrosInvalidPmtFileError):
     """
     Error found while resolving python files inclusions instructions
     (`## {{ py_name:section }}`)
@@ -210,3 +211,4 @@ PyodideMacrosParsingError = PmtInvalidSyntaxError
 PyodideMacrosIndentError = PmtIndentParserError
 PyodideMacrosTabulationError = PmtTabulationError
 PyodideMacrosMetaError = PmtMetadataError
+PmtMacrosInvalidPyFileError = PmtMacrosInvalidPmtFileError

{pyodide_mkdocs_theme-5.1.8/pyodide_mkdocs_theme/pyodide_macros/macros/ide_files_data → pyodide_mkdocs_theme-5.4.3/pyodide_mkdocs_theme/pyodide_macros/files_extractors}/__init__.py

@@ -17,5 +17,9 @@ along with this program.
 If not, see <https://www.gnu.org/licenses/>.
 """
 
-from .common_extractors import IdeFilesExtractor, SnippetsExtractor, SourceFilesExtractor
-from .composite_file_data import CompositeFilesDataExtractor
+from .concrete_extractors import (
+    FileExtractor,
+    PythonExtractor,
+    PythonSnippetsExtractor,
+    SqlExtractor,
+)

pyodide_mkdocs_theme-5.4.3/pyodide_mkdocs_theme/pyodide_macros/files_extractors/_inclusions_tools.py

@@ -0,0 +1,288 @@
+"""
+pyodide-mkdocs-theme
+Copyleft GNU GPLv3 🄯 2024 Frédéric Zinelli
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.
+If not, see <https://www.gnu.org/licenses/>.
+"""
+# pylint: disable=multiple-statements, missing-function-docstring
+
+
+import re
+from pathlib import Path
+from dataclasses import dataclass
+from typing import ClassVar, Dict, List, Literal, Tuple, TYPE_CHECKING, Union
+
+
+from ..exceptions import PmtMacrosInvalidPmtFileError
+from ..tools_and_constants import ScriptData
+from ..parsing import add_indent
+from ..indent_parser import IndentParser
+
+
+if TYPE_CHECKING:
+    from .concrete_extractors import FileExtractor
+
+
+CWD = Path.cwd()
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+class InclusionParser(IndentParser):
+    """
+    Parser dedicated to analyze the sections and replacements instructions for inclusions (it does
+    not handle the full instruction!).
+    """
+
+    _CACHE: ClassVar[Dict[str,List]] = {}
+
+    LOOKING_FOR: ClassVar[str] = "python inclusions informations"
+
+    targets: List[ScriptData]
+    replacements: List[Tuple[str,str]]
+
+
+    def gathered_data_as_str(self):
+        replacements = ''.join(
+            f"\n               {src!r} -> {repl!r}" for src,repl in self.replacements
+        ) or "\n               ()"
+        return f"""\
+Content parsed:     {self.content!r}
+Targeted sections:
+               { ', '.join(self.targets) or () }
+Replacements:{ replacements }"""
+
+
+    def start_parsing(self):
+        self.targets = []
+        self.replacements = []
+
+        while self.is_(':'):
+            self.eat_section()
+
+        if '*' in self.targets and len(self.targets) > 1:
+            self.fatal("Cannot use '*' in combination with other section names.")
+
+        while self.is_('[|]'):
+            self.eat_replacement()
+
+        if self.tokens_left():
+            got_repl = bool(self.replacements)
+            self.eat('[|]'if got_repl else '[:|]')
+
+        return self.targets, self.replacements
+
+
+    def eat_section(self):
+        self.eat()
+        is_all  = self.is_('[*]')
+        section = self.eat() if is_all else self.eat_id()
+        self.targets.append(section)
+
+    def eat_replacement(self):
+        self.eat()
+        src = self.eat_repl_segment()
+        self.eat_arrow()
+        repl = self.eat_repl_segment()
+        self.replacements.append((src,repl))
+
+    def eat_arrow(self):
+        i = self.i
+        arrow = ''.join( self.tokens[i:i+2] )
+        if arrow != "->":
+            show = repr(arrow) if arrow else 'EOF'
+            self.fatal(
+                f"Expected an arrow `->` to specify the replacement to use, but found { show }"
+            )
+        self.eat()
+        self.eat()
+
+    def eat_repl_segment(self):
+        if self.is_string():
+            return self.eat_string()
+        else:
+            return self.eat_id()
+
+
+    def eat_id(self):
+        return self.eat(r'\w+')
+
+    def eat_string(self):
+        i = self.i
+        self.err_stack_opening()
+        self._eat_until_paired()
+        self.err_stack_closing()
+        j = self.i
+        str_repr = ''.join(self.tokens[i:j])
+        return eval(str_repr)           # Using eval to automatically handle escaped chars
+
+
+INCLUSION_PARSER = InclusionParser()
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+@dataclass
+class InclusionConfig:
+    """ Regroup the data for one inclusion instruction """
+
+    ALL_SECTIONS: ClassVar[List[str]] = ['*']
+
+    parent: 'FileExtractor' = None
+
+    inclusion_instruction: str = None
+    """
+    Full inclusion instruction as string (with leading indent). Used to make the strings substitutions.
+    """
+
+    indent: str = ""
+    """ Leading indentation level, as string. """
+
+    redirection: str = ""
+    """ Redirection instruction (may be empty string) """
+
+    rel_path: str = ""
+    """ Relative path to the file targeted to resolved this inclusion. """
+
+    targets: List[Union[ScriptData, Literal['*']]] = None
+    """
+    List of children sections name to insert (in order). May be '*' if all sections of the target file
+    must be included (using default sections ordering).
+    """
+
+    replacements: Dict[str,str] = None
+    """ Replacements to apply after resolving the inclusions. """
+
+
+
+
+    @classmethod
+    def build_for(cls, parent:'FileExtractor', m:re.Match):
+        """
+        Build the InclusionConfig instance for the given parent Extractor, with the given match object.
+        """
+        indent, src, rel_path, targets_str = m['indent'], m['src'], m['rel_path'], m['targets']
+
+        targets, replacements = INCLUSION_PARSER.parse(targets_str.strip(), parent.exo_file)
+
+        return cls(parent, m[0], indent, src, rel_path, targets, replacements)
+
+
+
+    def get_child_target_sections(self, child:'FileExtractor'):
+        """
+        No validation at this step, just produce the list of expected sections to include.
+        Resolve the `*` case on the way.
+        """
+        if self.targets == self.ALL_SECTIONS:
+            return [
+                section for section in self.parent.env.allowed_pmt_sections_in_order
+                        if section in child.contents
+            ]
+        return self.targets
+
+
+    def apply(self, content:str):
+
+        child   = self.get_child()
+        targets = self.get_child_target_sections(child)
+
+        sub_content = "\n\n".join(
+            child.resolve_section_inclusions(child_section) for child_section in targets
+        )
+
+        for src,repl in self.replacements:
+            sub_content = sub_content.replace(src,repl)
+
+        indented = add_indent(sub_content, self.indent, leading=True)
+        content  = content.replace(self.inclusion_instruction, indented)
+        return content
+
+
+
+    def get_child(self):
+        """
+        Extract the correct target/child file for the current inclusion/page/macro.
+
+        Raise PmtMacrosInvalidPmtFileError if:
+        - `rel_path` is not given (unless the redirection is `[py]`).
+        - or if no target file can be found (whatever the way it is sought for: "by exercice" or
+          "by chapter" modes).
+        """
+        redirect = self.redirection
+        rel_path = self.rel_path
+
+        if not redirect and not rel_path:        # Include a section from the current file
+            return self.parent
+
+        elif redirect=='[md]':
+            source = self.parent.get_current_md()
+
+        elif redirect in ('[py]', '[src]'):
+            source = self.parent.get_src_file()
+            if not rel_path:
+                rel_path = source.stem
+
+        elif redirect=='[cwd]':
+            md = self.parent.get_current_md()
+            source = CWD / md.stem
+
+        else:
+            source = self.parent.exo_file
+
+
+        if not rel_path:
+            raise PmtMacrosInvalidPmtFileError(
+                "Inclusions using `[md]` or `[cwd]` require to specify a relative path information "
+                f"(aka, `py_name`).\nOccurred in:\n{ self.parent.env.log() }"
+            )
+
+        as_path = Path(rel_path)
+        tail    = as_path.suffix or self.parent.EXTENSION
+        if as_path.suffix and rel_path.endswith(tail):
+            rel_path = rel_path[:-len(tail)]
+
+        runner_file = self.parent.env._get_sibling(source, rel_path, tail=tail)
+
+        if not runner_file:
+            raise PmtMacrosInvalidPmtFileError(
+                f"No file matching {(redirect or '')+rel_path!r} could be found, starting from "
+                f"the { source.parent } directory."
+            )
+
+        _, child = self.parent.get_file_extractor_for(
+            self.parent.env, rel_path, runner_file=runner_file, allow_snippets_py=True
+        )
+        return child