pyodide-mkdocs-theme 5.6.7__tar.gz → 5.7.0__tar.gz

{pyodide_mkdocs_theme-5.6.7 → pyodide_mkdocs_theme-5.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pyodide-mkdocs-theme
-Version: 5.6.7
+Version: 5.7.0
 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

pyodide_mkdocs_theme-5.7.0/pyodide_mkdocs_theme/PMT_tools/MocodoPmt/__init__.py

@@ -0,0 +1,178 @@
+
+import js                                                   # type: ignore
+import io, sys, bs4, markdown, shutil, os
+from contextlib import redirect_stderr, redirect_stdout
+from pathlib import Path
+from itertools import chain
+from dataclasses import dataclass
+from typing import ClassVar
+
+
+# Hack IPython so that mocodo.magic can be used:
+import IPython as IP                                        # type: ignore
+from IPython.terminal.ipapp import TerminalIPythonApp       # type: ignore
+
+def start(self):
+    if self.subapp is not None:
+        return self.subapp.start()
+    self.shell.restore_term_title()
+    # self.shell.display = lambda *a, **kw: None      # NOT ENOUGH
+    if not self.shell.last_execution_succeeded:
+        sys.exit(1)
+TerminalIPythonApp.start = start
+
+
+# Dedicated PMT Mocodo tooling:
+@as_builtin                                                 # type: ignore
+@dataclass
+class Mocodo:
+    """
+    Classe permettant de :
+
+    1. Cibler une figure html dans la page.
+    2. Générer des fichiers de représentations de modèles SQL avec mocodo.api ou mocodo.magic.
+    3. Specifier quel type de fichiers insérer dans la page.
+    4. Nettoyer automatiquement l'environnement, en supprimant les fichiers générés.
+
+    Exemple: Ce code cible la figure d'id html `"figure1"`, génère les fichiers correspondant
+    à la magic commande `magic(...)`, et insère le fichier svg généré dans la cible.
+
+    ```python
+    from mocodo import Mocodo
+
+    Mocodo("figure1").magic('''
+    %%mocodo
+    CLIENT: Réf. client, Nom, Prénom, Adresse
+    PASSER, 0N CLIENT, 11 COMMANDE
+    COMMANDE: Num. commande, Date, Montant
+    INCLURE, 1N COMMANDE, 0N PRODUIT: Quantité
+    PRODUIT: Réf. produit, Libellé, Prix unitaire
+    ''').show('svg')
+    ```
+
+    Les fichiers text ou markdown sont systématiquement insérés dans des balises `<pre><code>`,
+    avec une coloration syntaxique pour SQL.
+    """
+
+    _html_id: str = None
+    cwd: str = "mocodo_notebook"
+
+    _has_sql: bool = False
+    _first_only: bool = False
+
+    _id_count: ClassVar[int] = 0
+
+    @property
+    def html_id(self):
+        return self._html_id or js.config().argsFigureDivId
+
+    @property
+    def mocodo_id(self):
+        return f"sql-mocodo-{ self._id_count }"
+
+    def target(self, html_id:str, cwd:str=None):
+        """
+        Permet de changer la figure cible avec @html_id, ou de changer le répertoire utilisés
+        pour créer les figures (à ne pas utiliser avec `mocodo.magic`).
+        """
+        self._html_id = html_id
+        self.cwd = cwd or self.cwd
+        return self
+
+    def api(self, *cmds:str):
+        """ Utilise mocodo.api.mocodo pour construire les fichiers """
+        from mocodo.api import mocodo
+        return self._run(mocodo, *cmds)
+
+    def magic(self, cmd:str):
+        """
+        Utilise mocodo.magic.mocodo pour construire les fichiers avec les syntaxes normalement
+        utilisées dans les notebooks.
+        """
+        from mocodo.magic import mocodo     # doesn't work if imported differently...
+        return self._run(mocodo, cmd)
+
+    def _run(self, func, *cmds:str):
+        p = Path(self.cwd)
+        if not p.exists():
+            p.mkdir()
+        os.chdir(p)
+        try:
+            with redirect_stderr(io.StringIO()) as buffer, redirect_stdout(io.StringIO()):
+                func(*cmds)
+                msg = buffer.getvalue()
+                if msg:
+                    raise ValueError(msg)
+        finally:
+            os.chdir('..')
+        return self
+
+    def show(self, *extensions:str, cwd:str=None, clear=True, first_only=True, list_files=False):
+        """
+        Extrait automatiquement parmi les fichiers générés ceux dont l'extension correspond à une
+        de celles passées en argument.
+
+        @*extensions: les types de fichiers à extraire (sans "point"), dans l'ordre dans lequel
+        ils doivent être traités.
+
+        @cwd:str=None: permet de modifier le répertoire utilisé pour gérer les fichiers (ne pas
+        modifier pour les commandes `magic`).
+
+        @clear=True: par défaut, les fichiers et le dossier de travail est supprimé une fois la
+        méthode exécutée. On peut passer cet argument à `False` si on souhaite insérer des fichiers
+        dans différentes figures (voir la méthode `target`).
+
+        @first_only=True: Par défaut, seul le premier fichier d'un type donné est extrait. En effet,
+        certains modes d'utilisation de mocodo peuvent générer plusieurs fichiers du même type.
+
+        @list_files=False: Passer à True pour afficher dans la console le contenu du dossier de travail.
+        """
+        self.cwd = cwd or self.cwd
+        self._has_sql = False
+        self._first_only = first_only
+
+        if list_files:
+            print(
+                "--------------------------",
+                "Files generated by mocodo:",
+                *Path(self.cwd).rglob('*'),
+                sep='\n'
+            )
+
+        content = '<br>'.join(chain.from_iterable(map(self._extract, extensions)))
+        soup = bs4.BeautifulSoup(content, "html.parser")
+        for script in soup.find_all("script"):
+            script.decompose()
+        no_scripts = str(soup)
+        js.document.getElementById(self.html_id).innerHTML = no_scripts
+
+        if self._has_sql:
+            js.highlightElement(self.mocodo_id)     # delayed further in time
+            Mocodo._id_count += 1
+        if clear:
+            shutil.rmtree(self.cwd)
+
+        return self
+
+    def _extract(self, extension:str):
+        extension = extension.strip('.')
+        for file in Path(self.cwd).glob(f'*.{ extension }'):
+            content = file.read_text(encoding='utf-8')
+            formatted = getattr(self, f'_format_{ extension }', lambda s:s)(content)
+            yield formatted
+            if self._first_only:
+                return
+
+    def _format_md(self, txt:str):
+        return f'<div style="text-align:left">{ markdown.markdown(txt) }</div>'
+
+    def _format_mcd(self, txt:str):
+        self._has_sql = True
+        return f'<pre style="text-align:left"><code id="{ self.mocodo_id }" class="language-sql">{ txt }</code></pre>'
+
+    _format_txt = _format_mcd
+    _format_sql = _format_mcd
+
+
+import mocodo
+mocodo.Mocodo = Mocodo

pyodide_mkdocs_theme-5.7.0/pyodide_mkdocs_theme/PMT_tools/MocodoPmt/cdns.json

@@ -0,0 +1,7 @@
+[{
+    "src": "https://cdn.jsdelivr.net/npm/@highlightjs/cdn-assets@11.12.0/highlight.min.js",
+    "integrity": "sha384-wjfDDhOPPdjtva8vWBhWeVprSpmxisEu5aYT3q1JyACqXpdKpo3PWZTMVq24MBix"
+},{
+    "href": "https://cdn.jsdelivr.net/npm/@highlightjs/cdn-assets@11.12.0/styles/default.min.css",
+    "integrity": "sha384-4Y0nObtF3CbKnh+lpzmAVdAMtQXl+ganWiiv73RcGVdRdfVIya8Cao1C8ZsVRRDz"
+}]

pyodide_mkdocs_theme-5.7.0/pyodide_mkdocs_theme/PMT_tools/PyodidePlotPmt/__init__.py

@@ -0,0 +1,156 @@
+
+import matplotlib
+import matplotlib.pyplot as plt
+from typing import Callable, Sequence
+
+
+
+class PyodidePlot:
+    """
+    Helper class, to draw figures from pyodide runtime, into a specified html element.
+    If no argument is provided, the default `div_id` is used (arguments configuration of
+    the plugin).
+
+    ```python
+    import matplotlib.pyplot as plt
+    plt.PyodidePlot().target()
+
+    plt.plot(xs, ys, ...)
+    plt.title("...")
+    plt.show()
+    ```
+
+    ---
+
+    In case you want to target more than one figure in the same page, pass the html id of the
+    div tag to target to the `PyodidePlot` constructor:
+
+    ```python
+    fig1 = plt.PyodidePlot("figure_id1")
+    fig2 = plt.PyodidePlot("figure_id2")
+
+    fig1.target()       # Draw in "figure_id1"
+    plt.plot(...)
+
+    fig2.target()       # Draw now in "figure_id2"
+    plt.plot(...)
+    ```
+
+    ---
+    """
+
+    def __init__(self, div_id:str=''):
+        self.div_id = div_id or js.config().argsFigureDivId
+
+    def __getattr__(self, prop:str):
+        return getattr(plt, prop)
+
+
+    def target(self, keep_fig=False):
+        """
+        Close any previously created figure, then setup the current run to draw in
+        the div tag targeted by the current instance.
+        If keep_fig is set to True, the automatic `Figure N` will be kept, above the
+        next drawn figure.
+        """
+        for _ in plt.get_fignums():
+            plt.close()
+        div = js.document.getElementById(self.div_id)
+        if not div:
+            raise ValueError("Couldn't find the target object: #"+self.div_id)
+        js.document.pyodideMplTarget = div
+        div.textContent = ""
+        if not keep_fig:
+            self.clear_current_figure_title()
+        return plt
+
+    refresh = target        # backward compatibility
+
+
+
+    def plot_func(
+        self,
+        func:Callable,
+        rng:Sequence,
+        fmt:str=None,
+        title:str=None,
+        *,
+        show:bool=True,
+        keep_figure_num: bool = False,
+        **kw
+    ):
+        """
+        Draw an automatic graph for the given function on the given range, then "show"
+        automatically the resulting graph in the correct figure element in the page.
+
+        Arguments:
+            func:  Callable, func(x) -> y
+            rng:   Sequence of xs
+            fmt:   Curve formatting (just like `pyplot.plot`)
+            title: If given, will be added as title of the graph.
+            show:  Call `pyplot.show()` only if `True`. This allows to customize the graph
+                   before applying show manually.
+            keep_figure_num: if False (by default), the `Figure N` above the drawing is
+                   automatically removed.
+
+        """
+        self.target(keep_figure_num)
+
+        xs = list(rng)
+        ys = [*map(func, rng)]
+        args = (xs,ys) if fmt is None else (xs,ys,fmt)
+        out = plt.plot(*args, **kw)
+
+        if title:
+            plt.title(title)
+        if show:
+            plt.show()
+        return out
+
+
+
+    def plot(self, *args, keep_figure_num:bool=False, **kw):
+        """
+        Generic interface, strictly equivalent to `pyplot.plot`, except the `PyodidePlot`
+        instance will automatically apply the drawing to the desired html element it is
+        related to.
+
+        _Use specifically this method to "plot"_ ! You then can rely on `pyplot` to finalize
+        the figure as you prefer.
+        """
+        self.target(keep_figure_num)
+        out = plt.plot(*args, **kw)
+        return out
+
+
+    @classmethod
+    def clear_current_figure_title(cls):
+        """ Remove the automatic title added through matplotlib.pyplot. """
+        plt.gcf().canvas.manager.set_window_title('')
+
+
+    @classmethod
+    def interactive_backend(cls):
+        """ Use interactive html5 backend to draw figures """
+        matplotlib.use("module://matplotlib_pyodide.html5_canvas_backend")
+
+    @classmethod
+    def wasm_backend(cls):
+        """ Use wasm backend rendering to draw static figures """
+        matplotlib.use("module://matplotlib_pyodide.wasm_backend")
+
+    @classmethod
+    def matplotlib_backend(cls):
+        """ Use interactive html5 backend to draw figures """
+        cls.interactive_backend()
+
+    @classmethod
+    def sympy_backend(cls):
+        """ Use wasm backend rendering to draw static figures """
+        cls.wasm_backend()
+
+
+import js
+PyodidePlot.matplotlib_backend()
+plt.PyodidePlot = matplotlib.PyodidePlot = PyodidePlot
+as_builtin(PyodidePlot)

pyodide_mkdocs_theme-5.7.0/pyodide_mkdocs_theme/PMT_tools/PyodidePlotPmt/cdns.json

@@ -0,0 +1,4 @@
+[{
+    "href": "https://cdn.jsdelivr.net/npm/fontawesome-4.7@4.7.0/css/font-awesome.min.css",
+    "integrity": "sha256-eZrrJcwDc/3uDhsdt61sL2oOBY362qM3lon1gyExkL0="
+}]

pyodide_mkdocs_theme-5.7.0/pyodide_mkdocs_theme/PMT_tools/foliumPmt/__init__.py

@@ -0,0 +1,10 @@
+
+import folium
+import js
+
+def show(carte, cible:str=None):
+    """Affiche la carte Folium dans la figure dont l'identifiant est `cible`."""
+    cible = cible or js.config().argsFigureDivId
+    js.document.getElementById(cible).innerHTML = carte._repr_html_()
+
+folium.show = show

pyodide_mkdocs_theme-5.7.0/pyodide_mkdocs_theme/__version__.py

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

{pyodide_mkdocs_theme-5.6.7 → pyodide_mkdocs_theme-5.7.0}/pyodide_mkdocs_theme/pyodide_macros/files_extractors/base0_extractors.py

@@ -45,7 +45,7 @@ Context/Contracts/Goals:
 * An Extractor instance is cached based on the absolute/resolved path to the targeted
  file (aka `self.exo_file`).
 
-* The file is automatically refreshed when a local file has been modified.
+* The extractor object is automatically refreshed when a local file has been modified.
 
 * The concrete contents of the files are stored in the instance, avoiding multiple HDD
 reads operations. Note that the content is stored "as is", meaning the inclusions are not
@@ -95,7 +95,6 @@ class BaseFilesExtractor:
     interface and contracts.
 
     - source file and `arg_name` argument
-    - cache management
     - file content extraction generic triggers
     - hash and/or equality definitions
     - abstract methods that must be implemented at some point in the hierarchy
@@ -256,7 +255,8 @@ class BaseExtractorWithCache(BaseFilesExtractor):
     @classmethod
     def get_dirty_pages(cls, *, all=False):
         """
-        Yields all registered Extractor instances that aren't considered up to date at the moment.
+        Return a list of all pages instances that should be considered dirty (because a file
+        Extractor involved in the page has been modified).
         """
         unique = {
             uri: page

{pyodide_mkdocs_theme-5.6.7 → pyodide_mkdocs_theme-5.7.0}/pyodide_mkdocs_theme/pyodide_macros/html_builder/_html_builder.py

@@ -55,16 +55,24 @@ def _build_html_attributes(
     if attrs.get('for_'):
         attrs['for'] = attrs.pop('for_')
 
+    # Merge style sources:
     style = attrs.get('style')
     if style and not isinstance(style, str):
         raise ValueError(
             f'The `style` argument should be given as a string, but was:\n{style!r}'
         )
 
+    # Merge dataset sources:
     if 'data' in attrs:
         data: Dict = attrs.pop('data')
         attrs.update({f'data-{ k }':v for k,v in data.items()})
 
+    # Escape html tags delimiters in data-tip-txt:
+    # (see https://github.com/Python-Markdown/markdown/issues/1647)
+    if 'data-tip-txt' in attrs:
+        attrs['data-tip-txt'] = attrs['data-tip-txt'].replace('<','&lt;').replace('>','&gt;')
+
+    # Handle "named only" properties
     suffix_attrs = ""
     for name in ('disabled', 'checked'):
         if name in attrs:
@@ -74,9 +82,8 @@ def _build_html_attributes(
     attributes = " ".join(
         f'{ name }="{ value }"'
         for name,value in attrs.items()
-    ) + suffix_attrs
-
-    return attributes
+    )
+    return attributes + suffix_attrs
 
 
 

{pyodide_mkdocs_theme-5.6.7 → pyodide_mkdocs_theme-5.7.0}/pyodide_mkdocs_theme/pyodide_macros/plugin/maestro_base.py

@@ -61,8 +61,8 @@ class BaseMaestro(BasePlugin[PyodideMacrosConfig]):
     It is also used as "sink" for the super calls of other classes that are not implemented
     on the MacrosPlugin class.
 
-    Note that, for the ConfigExtractor for to properly work, the class hierarchy has to
-    extend MacrosPlugin at some point.
+    Note that, for the ConfigExtractor to properly work, the class hierarchy has to extend 
+    MacrosPlugin at some point.
     """
     config: PyodideMacroConfig
 
@@ -341,7 +341,7 @@ class BaseMaestro(BasePlugin[PyodideMacrosConfig]):
 
     top_args_IDE_TEST: str = ''
     """
-    Store the value of self.args_IDE_TEST at the top level, to know whet the user configured
+    Store the value of self.args_IDE_TEST at the top level, to know what the user configured
     in the mkdocs.yml file.
     """
 

{pyodide_mkdocs_theme-5.6.7 → pyodide_mkdocs_theme-5.7.0}/pyodide_mkdocs_theme/pyodide_macros/plugin/maestro_files.py

@@ -210,7 +210,6 @@ class MaestroGeneratedPages(BaseMaestro):
                 files.append(file)
 
         # "Make dirty" all pages with file extractors that aren't up to date at the moment:
-        # (handle only sources)
         for page in FileExtractor.get_dirty_pages():
             src_path = Path(page.file.abs_src_path)
             target_path = Path(page.file.abs_dest_path)
@@ -245,7 +244,7 @@ class MaestroPyLibs(MaestroGeneratedPages):
 
     base_py_libs: Set[str] = None       # added on the fly
     """
-    Set of all the python_libs paths strings, as declared in the plugins config (meta or not).
+    Set of all the python_libs paths strings, as declared in the plugin's config (meta or not).
     """
 
     python_libs_in_pyodide: List[str] = None

{pyodide_mkdocs_theme-5.6.7 → pyodide_mkdocs_theme-5.7.0}/pyodide_mkdocs_theme/pyodide_macros/plugin_config/definitions/macros_configs.py

@@ -905,8 +905,8 @@ RUN_MACRO = MacroConfigSrc.with_default_docs(
             Chemin relatif vers le fichier python (sans extension) à exécuter au chargement de
             la page (sections `env`, `post` et `ignore` uniquement).
         """},
-        RUN_GROUP = {'docs': """
-            Seules les valeurs `#!py None` et `#!py "SKIP"` sont autorisées pour les macros `run`,
+        RUN_GROUP = {'docs': f"""
+            Seules les valeurs `#!py None` et `#!py "{ PmtCte.RUN_GROUP_SKIP }"` sont autorisées pour les macros `run`,
             du fait qu'il serait impossible de déterminer quand passer d'une version à l'autre
             sur le site construit.<br>
         """}

{pyodide_mkdocs_theme-5.6.7 → pyodide_mkdocs_theme-5.7.0}/pyodide_mkdocs_theme/pyodide_macros/plugin_tools/test_cases.py

@@ -298,6 +298,7 @@ class Case:
     - `stdKey`
     - `stdoutCutOff`
     - `twoCols`
+    - `useLocalStorage`
     - `userContent`
     - `whiteList`
     """

{pyodide_mkdocs_theme-5.6.7 → pyodide_mkdocs_theme-5.7.0}/pyodide_mkdocs_theme/templates/js-libs/functools.js

@@ -84,8 +84,8 @@ export const withPyodideAsyncLock = (()=>{
    *
    * @runnerManager=null: if given, this is the RUNNERS_MANAGER instance. See @runner argument.
    *
-   * @runner=null: if @runnerManager is given, this is the runner opbject currently "asking for
-   * permission" to run. The RUNNERS_MANAGER qill auhorize the execution or not, depending on
+   * @runner=null: if @runnerManager is given, this is the runner object currently "asking for
+   * permission" to run. The RUNNERS_MANAGER will authorize the execution or not, depending on
    * AUTO_RUNs being completed or not (and if AUTO_RUNs are going on, authorize the current
    * runner).
    * */
@@ -353,14 +353,27 @@ export const cdnLoader = _ressourceLoaderFactory('script', 'src',  'script')
 export const cssLoader = _ressourceLoaderFactory('link',   'href', 'css', {rel:'stylesheet'})
 
 
+/**@ressourcesArr: Array of json objects, with href or src alongside other values (integrity, ...).
+ * If an element is a simple string, assume it's a `src` value.
+ * */
 export const externalRessourcesLoaderFor = (name, ressourcesArr)=>{
   if(name) console.log(`Loading ${ name } utilities...`)
-  const done = Promise.all(ressourcesArr.map(o=>typeof(o)!='string' && ('href' in o) ? cssLoader(o):cdnLoader(o)))
+  const done = Promise.all( ressourcesArr.map(
+    o => typeof(o)!='string' && ('href' in o) ? cssLoader(o) : cdnLoader(o)
+  ))
   if(name) console.log(name, 'ready')
   return done
 }
 
 
+/**Used only with mocodo + mcd/sql display */
+export const highlightElement=(htmlId)=>{
+  setTimeout(()=>{
+    hljs.highlightElement(document.getElementById(htmlId))
+  })
+}
+
+
 export class RessourcesLoader {
 
   static RESSOURCES = []
@@ -710,9 +723,10 @@ globalThis.subscribeWhenReady = subscribeWhenReady
 LOGGER_CONFIG.ACTIVATE && console.log("async subscriber updated")
 
 // Access from pyodide + IdeZipManager logistic + backward compatibility:
-globalThis.config        = config
-globalThis.isDark        = isDark
-globalThis.downloader    = downloader
-globalThis.uploader      = uploader
-globalThis.uploaderAsync = uploaderAsync
+globalThis.config           = config
+globalThis.isDark           = isDark
+globalThis.downloader       = downloader
+globalThis.uploader         = uploader
+globalThis.uploaderAsync    = uploaderAsync
+globalThis.highlightElement = highlightElement
 // globalThis.fileContentToDom = fileContentToDom

{pyodide_mkdocs_theme-5.6.7 → pyodide_mkdocs_theme-5.7.0}/pyodide_mkdocs_theme/templates/js-libs/functoolsUi.js

@@ -332,11 +332,14 @@ export const handlePmtTooltips=(()=>{
   }
 
   const validTags = '<br> <kbd> <code> <i> <u> <b>'.split(' ')
+  const unescapeTags = {"&lt;":'<', "&gt;":'>', "\\<": '<'}
 
   const getValidHtml=(html)=>{
     // In admonitions, tags are escaped somehow (dunno where exactly), so restore them,
-    // if they are allowed:
-    html = html.replace(/\\</g, "<")
+    // if they are allowed + handle markdown 3.11:
+    html = html.replace(/&[lg]t;/g, s=>unescapeTags[s])
+               .replace(/\\</g, s=>unescapeTags[s])
+                        // as a separated step, making sure no mixed escaping is missed
 
     const tags = [...html.replace(/\//g,"").match(/<[^>]*>/g)||[]]
     const tagsOk = tags.every(s=>validTags.includes(s))