marimo-logilab-helper 0.1.1__tar.gz

marimo_logilab_helper-0.1.1/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.3
+Name: marimo-logilab-helper
+Version: 0.1.1
+Summary: Logilab Marimo helpers contains various functions used in Logilab training exercises implemented in Marimo notebooks
+Keywords: marimo,notebook,education,logilab
+Author: Logilab
+Author-email: Logilab <contact@logilab.fr>
+License: GNU Lesser General Public License v2 or later (LGPLv2+)
+Classifier: Environment :: Web Environment
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Natural Language :: English
+Classifier: Natural Language :: French
+Classifier: Topic :: Education
+Requires-Dist: marimo>=0.14
+Requires-Python: >=3.12
+Project-URL: Repository, https://forge.extranet.logilab.fr/open-source/logilab-marimo-helpers
+Project-URL: Issues, https://forge.extranet.logilab.fr/open-source/logilab-marimo-helpers/-/boards#/
+Description-Content-Type: text/markdown
+
+This package contains several functions that are used inside the
+Marimo notebooks implementing Logilab training exercises. These
+functions include:
+
+- a function that can run a list of test functions and that displays
+  a table giving the result of each test function,
+- several check functions that can be used inside the test functions to
+  verify a result,
+- a function that can display, in a Markdown block, the solution stored
+  in a Python file,
+- a function that can indicate if the Marimo notebook is running in a Web
+  Component (WASM) or in a Marimo regular server.
+- a function that can mock the standard `open` function of Python when
+  the Marimo notebook is run in a Web Component (WASM); basically, instead
+  of opening a file on the disk (which is impossible from a program running
+  in the Web browser), it opens a file at an URL.

marimo_logilab_helper-0.1.1/README.md

@@ -0,0 +1,16 @@
+This package contains several functions that are used inside the
+Marimo notebooks implementing Logilab training exercises. These
+functions include:
+
+- a function that can run a list of test functions and that displays
+  a table giving the result of each test function,
+- several check functions that can be used inside the test functions to
+  verify a result,
+- a function that can display, in a Markdown block, the solution stored
+  in a Python file,
+- a function that can indicate if the Marimo notebook is running in a Web
+  Component (WASM) or in a Marimo regular server.
+- a function that can mock the standard `open` function of Python when
+  the Marimo notebook is run in a Web Component (WASM); basically, instead
+  of opening a file on the disk (which is impossible from a program running
+  in the Web browser), it opens a file at an URL.

marimo_logilab_helper-0.1.1/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "marimo-logilab-helper"
+version = "0.1.1"
+description = "Logilab Marimo helpers contains various functions used in Logilab training exercises implemented in Marimo notebooks"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["marimo>=0.14"]
+keywords = [
+    "marimo",
+    "notebook",
+    "education",
+    "logilab",
+]
+classifiers = [
+    "Environment :: Web Environment",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Natural Language :: English",
+    "Natural Language :: French",
+    "Topic :: Education",
+]
+
+[project.license]
+text = "GNU Lesser General Public License v2 or later (LGPLv2+)"
+
+[[project.authors]]
+name = "Logilab"
+email = "contact@logilab.fr"
+
+[project.urls]
+Repository = "https://forge.extranet.logilab.fr/open-source/logilab-marimo-helpers"
+Issues = "https://forge.extranet.logilab.fr/open-source/logilab-marimo-helpers/-/boards#/"
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "ruff",
+    "twine",
+]
+
+[tool.uv.build-backend]
+module-name = "mo_logilab_helpers"
+
+[tool.ruff]
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "E4",
+    "E7",
+    "E9",
+    "F",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"

marimo_logilab_helper-0.1.1/pyproject.toml.orig

@@ -0,0 +1,42 @@
+[project]
+name = "marimo-logilab-helper"
+version = "0.1.1"
+description = "Logilab Marimo helpers contains various functions used in Logilab training exercises implemented in Marimo notebooks"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "marimo>=0.14",
+]
+license = {text = "GNU Lesser General Public License v2 or later (LGPLv2+)"}
+authors = [
+    {name="Logilab", email="contact@logilab.fr"},
+]
+keywords = ["marimo", "notebook", "education", "logilab"]
+classifiers = [
+    "Environment :: Web Environment",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Natural Language :: English",
+    "Natural Language :: French",
+    "Topic :: Education",
+]
+
+[project.urls]
+Repository = "https://forge.extranet.logilab.fr/open-source/logilab-marimo-helpers"
+Issues = "https://forge.extranet.logilab.fr/open-source/logilab-marimo-helpers/-/boards#/"
+
+[dependency-groups]
+dev = ["pytest", "ruff", "twine"]
+
+[tool.uv.build-backend]
+module-name = "mo_logilab_helpers"
+
+[tool.ruff]
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F"]
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"

marimo_logilab_helper-0.1.1/src/mo_logilab_helpers/__init__.py

@@ -0,0 +1,47 @@
+"""
+Package defining several useful functions that are used inside the Marimo
+notebooks implementing Logilab training exercises.
+
+These functions are:
+
+``run_tests``
+    Run a list of test functions and display their result in the Marimo cell
+    output.
+``check_value``
+    Inside a test function, checks a result is equal to a given value.
+``check_type``
+    Inside a test function, checks a result has the given type.
+``check_raise_exception``
+    Inside a test function, checks a piece of code raises an exception of a
+    given type
+
+``display_solution``
+    Read the code of the solution stored inside a Python file and display it
+    in a Markdown block inside the Marimo cell output. The solution is only
+    displayed when a given switch is active.
+``runs_in_web_component``
+    Return True if the Marimo notebook is run in a Web Component inside the
+    Web browser (some behaviours change in such a case and the Marimo notebook
+    must adapt to provide the same functionalities to the end-user).
+``mock_open_function_when_running_in_web_component``
+    Dynamically change the standard `open` function (that reads a file on the
+    disk) with a custom function that emulates this function by reading a file
+    through an HTTP GET request. This change is necessary when the Marimo
+    notebook is run in a Web Component inside the Web browser because then the
+    standard `open` function can't work.
+"""
+
+from .tests import run_tests, check_value, check_type, check_raise_exception
+from .solutions import display_solution
+from .others import runs_in_web_component
+from .mocks import mock_open_function_when_running_in_web_component
+
+__all__ = [
+    "run_tests",
+    "check_value",
+    "check_type",
+    "check_raise_exception",
+    "display_solution",
+    "runs_in_web_component",
+    "mock_open_function_when_running_in_web_component",
+]

marimo_logilab_helper-0.1.1/src/mo_logilab_helpers/mocks.py

@@ -0,0 +1,62 @@
+"""
+Module containing functions to mock some standard Python functions when the
+Marimo notebook is run in a Web Component inside the Web browser.
+"""
+
+from typing import Any
+import marimo as mo
+from .utils import get_message
+
+
+def mock_open_function_when_running_in_web_component(
+    globals_dict: dict[str, Any], lang: str = "en"
+):
+    """
+    In a notebook run as a Web Component, replace the standard `open`
+    function with a custom function that emulates its behaviour but relies
+    on `urlopen` to read the data from an URL with an HTTP GET request.
+
+    This function replaces the standard `open` function in `globals()` with
+    our custom function. Note that the standard function is always available
+    in the `io` module. `globals_dict` parameter should be given `globals()`
+    object.
+
+    Be aware that our custom function can only emulate the reading of a file
+    with `open`. Writing a file can't be done through an HTTP GET request.
+
+    `lang` is only used to display a message in Marimo output.
+    """
+    from urllib.request import urlopen
+    from types import MethodType
+
+    # Define our mock function
+    def open(file, mode="r", encoding=None):
+        resp = urlopen(file)
+        # Redefine `readline` on the stream returned by urlopen because it
+        # doesn't decode the read text (contrary to the standard `io text
+        # stream).
+        resp._readline = resp.readline
+
+        def readline(self):
+            return self._readline().decode(encoding or "utf-8")
+
+        resp.readline = MethodType(readline, resp)
+        # Return the customised stream
+        return resp
+
+    # Change the standard `open` function in the globals dict.
+    globals_dict["__builtin__"]["open"] = open
+    # Display a message in the Marimo cell output.
+    mo.output.replace(
+        mo.vstack(
+            [
+                mo.icon("ant-design:warning-filled", size=50, color="red"),
+                mo.md(
+                    get_message("mock_open_1", lang=lang)
+                    + "\n\n"
+                    + get_message("mock_open_2", lang=lang)
+                ).callout(kind="danger"),
+            ],
+            align="start",
+        )
+    )

marimo_logilab_helper-0.1.1/src/mo_logilab_helpers/others.py

@@ -0,0 +1,14 @@
+"""
+Module containing various other useful functions
+"""
+
+
+def runs_in_web_component() -> bool:
+    """
+    Return True if the Marimo notebook is running in a Web Component inside
+    the Web browser (instead of running in the Marimo server onto a regular
+    operating system).
+    """
+    import sys
+
+    return sys.platform == "emscripten"

marimo_logilab_helper-0.1.1/src/mo_logilab_helpers/solutions.py

@@ -0,0 +1,60 @@
+"""
+Module defining the functions that can be used to display the solution
+(content of a Python file stored near the Marimo exercice notebook.
+"""
+
+from pathlib import Path
+import marimo as mo
+from .others import runs_in_web_component
+
+
+def display_solution(
+    switch_obj, sol_filename: str | Path, markdown: bool = False
+):
+    """
+    Display the Python code of the solution stored inside ``sol_filename`` in
+    the output of the Marimo cell.
+
+    The solution is only shown when the Marimo switch ``switch_obj`` is
+    active.
+
+    If ``markdown`` is ``True``, the content of the solution is directly
+    displayed, else it is inserted in a code block marker.
+    """
+    sol_code: list[str] = []
+    try:
+        if runs_in_web_component():
+            # We are running inside the Web browser and must use `urlopen` to
+            # read the file containing the solution.
+            from urllib.request import urlopen
+
+            with urlopen(str(sol_filename)) as stream:
+                sol_code = [
+                    line.decode("utf-8") for line in stream.readlines()
+                ]
+        else:
+            with open(sol_filename) as stream:
+                sol_code = stream.readlines()
+    except Exception as exc:
+        mode = "in file" if not runs_in_web_component() else "at URL"
+        sol_code = [
+            f"# Can't access the solution {mode}: {sol_filename}\n",
+            "\n",
+            f"# Encountered the error: {exc.__class__.__name__} {exc}\n",
+        ]
+
+    if switch_obj.value:
+        mo.output.replace(
+            mo.vstack(
+                [
+                    switch_obj,
+                    mo.md(
+                        "".join(sol_code)
+                        if markdown
+                        else f"```python3\n{"".join(sol_code)}\n```\n"
+                    ),
+                ]
+            )
+        )
+    else:
+        mo.output.replace(switch_obj)

marimo_logilab_helper-0.1.1/src/mo_logilab_helpers/tests.py

@@ -0,0 +1,247 @@
+"""
+Module defining the functions that can be used to run tests in the Marimo
+notebook and display their results in the Marimo cell output.
+"""
+
+from typing import Optional, Callable, Any, cast
+import types
+import numbers
+from traceback import format_exc
+from contextlib import contextmanager
+import marimo as mo
+from .utils import get_message
+
+
+class CheckError(Exception):
+    """
+    Custom exception raised by the check functions (see below).
+    """
+
+    pass
+
+
+def run_tests(
+    test_functions_list: list[Callable[..., None]], lang: str = "en"
+):
+    """
+    Run the functions in ``test_functions_list`` list and display their
+    result in a nice grid in the output of the Marimo cell. The potential
+    tracebacks are printed (in the printing zone of the Marimo cell).
+
+    Each function can use the check functions (also defined in this module)
+    to verify an expected result.
+    """
+    results_data = []
+    for test_function in test_functions_list:
+        doc_lines = [
+            lin.strip()
+            for lin in (test_function.__doc__ or "").strip().split("\n")
+        ]
+        doc_first_para = (
+            doc_lines[: doc_lines.index("")]
+            if "" in doc_lines
+            else doc_lines[:]
+        )
+        data_row: list[Optional[str]] = [
+            test_function.__name__,
+            " ".join(doc_first_para),
+        ]
+        results_data.append(data_row)
+        try:
+            test_function()
+            data_row.append(f"✅️  {get_message('ok', lang=lang)}")
+            data_row.append(None)
+        except CheckError:
+            data_row.append(f"⚠️  **{get_message('failed', lang=lang)}**")
+            data_row.append(format_exc())
+        except Exception:
+            data_row.append(f"❌️  **{get_message('error', lang=lang)}**")
+            data_row.append(format_exc())
+
+    output_rows = []
+    for name, desc, status, details in results_data:
+        output_rows.append(
+            mo.hstack(
+                [
+                    mo.vstack(
+                        [
+                            mo.md(f"**{name}**"),
+                            mo.md(desc),
+                        ],
+                        gap=0,
+                    ),
+                    mo.md(status),
+                ],
+                widths=[3, 1],
+            )
+        )
+        if details is not None:
+            print(f"*** {name}\n")
+            print(details)
+
+    mo.output.replace(mo.vstack(output_rows, heights="equal"))
+
+
+def check_value(
+    result: Any,
+    expected_value: Any,
+    precision: int = 6,
+    message: Optional[str] = None,
+    **context: dict[str, Any],
+):
+    """
+    Check ``result`` is equal to the ``expected_value``.
+
+    If ``result`` is a number, the equality is tested with the specified
+    ``precision`` (difference less than 10^-<precision>). It is possible to
+    set ``precision`` to ``None`` to avoid this behaviour and check for a
+    strict equality.
+
+    ``message`` is the text written at the beginning of the error message.
+
+    Additional arguments with their values can be provided to describe the
+    context of the test (e.g. values used to run the function that produced
+    ``result``).
+    """
+    if isinstance(result, numbers.Number) and precision is not None:
+        power = -precision
+        check_test = abs(result - expected_value) < 10**power
+    else:
+        check_test = result == expected_value
+    if not check_test:
+        str_context = (
+            (
+                "\nContext: "
+                + " ; ".join(
+                    f"{key}={repr(val)}" for key, val in context.items()
+                )
+            )
+            if context
+            else ""
+        )
+        msg = (
+            message
+            if message
+            else "The result is different from the expected value:"
+        )
+        raise CheckError(
+            f"{msg}\n  {repr(result)}\nis different from\n"
+            f"  {repr(expected_value)}{str_context}\n"
+        )
+
+
+def check_type(
+    result: Any,
+    expected_type: type | tuple[type, ...] | types.UnionType,
+    message: Optional[str] = None,
+    **context: dict[str, Any],
+):
+    """
+    Check ``result`` has the ``expected_type`` type.
+
+    ``expected_type`` can be a single type, a tuple of types or an union of
+    types (see documentation of the standard ``isinstance`` function).
+
+    ``message`` is the text written at the beginning of the error message.
+
+     Additional arguments with their values can be provided to describe the
+    context of the test (e.g. values used to run the function that produced
+    ``result``).
+    """
+    exp_types = expected_type
+    if not isinstance(expected_type, (tuple, types.UnionType)):
+        exp_types = (expected_type,)
+    if not isinstance(result, exp_types):
+        str_types = (
+            str(exp_types)
+            if isinstance(exp_types, types.UnionType)
+            else " | ".join(
+                (f"{typ.__module__}." if typ.__module__ != "builtins" else "")
+                + typ.__name__
+                for typ in cast(tuple[type, ...], exp_types)
+            )
+        )
+        str_context = (
+            (
+                "\nContext: "
+                + " ; ".join(
+                    f"{key}={repr(val)}" for key, val in context.items()
+                )
+            )
+            if context
+            else ""
+        )
+        msg = (
+            message
+            if message
+            else "The result doesn't have the expected type:"
+        )
+        raise CheckError(
+            f"{msg}\n  {repr(result)}\nhas not a type in\n  {str_types}"
+            f"{str_context}\n"
+        )
+
+
+@contextmanager
+def check_raise_exception(
+    exception_type,
+    message: Optional[str] = None,
+    **context: dict[str, Any],
+):
+    """
+    Context manager that verifies the code it contains raises an exception of
+    ``expected_type`` type.
+
+    ``expected_type`` can be a single type, a tuple of types or an union of
+    types (see documentation of the standard ``isinstance`` function).
+
+    ``message`` is the text written at the beginning of the error message.
+
+    Additional arguments with their values can be provided to describe the
+    context of the test (e.g. values used to run the function that raised the
+    exception).
+    """
+    exc_types = exception_type
+    if not isinstance(exception_type, (tuple, types.UnionType)):
+        exc_types = (exception_type,)
+    error = False
+    exc_obj: Optional[Exception] = None
+    try:
+        yield
+        error = True
+    except Exception as exc:
+        if not isinstance(exc, exc_types):
+            error = True
+            exc_obj = exc
+    finally:
+        if error:
+            str_exc_types = (
+                str(exc_types)
+                if isinstance(exc_types, types.UnionType)
+                else " | ".join(excp.__name__ for excp in exc_types)
+            )
+            str_context = (
+                (
+                    "\nContext: "
+                    + " ; ".join(
+                        f"{key}={repr(val)}" for key, val in context.items()
+                    )
+                )
+                if context
+                else ""
+            )
+            if exc_obj is not None:
+                msg = (
+                    message
+                    if message
+                    else "An unexpected exception has been raised:"
+                )
+                raise CheckError(
+                    f"{msg}\n  {repr(exc_obj)}\nhas not an exception type in:"
+                    f"\n  {str_exc_types}{str_context}\n"
+                )
+            msg = message if message else "No exception has been raised:"
+            raise CheckError(
+                f"{msg}\n\nAn exception was expected with a type in:\n"
+                f"  {str_exc_types}{str_context}\n"
+            )

marimo_logilab_helper-0.1.1/src/mo_logilab_helpers/utils.py

@@ -0,0 +1,69 @@
+"""
+Module containing the localised messages that will be displayed in the Marimo
+notebook.
+"""
+
+_MESSAGES: dict[str, dict[str, str]] = {
+    "en": {
+        "ok": "ok",
+        "failed": "Failed test",
+        "error": "Execution error",
+        "mock_open_1": (
+            "This notebook is executed as a Web Component inside the browser. "
+            "Python is not executed in regular operating system on a computer "
+            "but inside the Web browser. As such, the standard `open` "
+            "function can't be used to read files because, for security "
+            "reasons, the Web browser can't access to the computer "
+            "filesystem. Therefore, we have replaced the `open` function with "
+            "a custom function that can get a file at a given URL and that "
+            "emulates the behaviour of the standard function."
+        ),
+        "mock_open_2": (
+            "Please note that we can't emulate all the behaviour of the "
+            "standard `open` function because getting a document by "
+            "requesting an URL is quite different from reading a file on a "
+            "disk. Our custom function has only three parameters: `filename`, "
+            "`mode` and `encoding`. This is enough to cover most of the use "
+            "cases. Be aware that our custom function can **only read files** "
+            '(`mode="r"`) because, as you might suspect, it is impossible '
+            "to write files through a Web GET request."
+        ),
+    },
+    "fr": {
+        "ok": "ok",
+        "failed": "Échec du test",
+        "error": "Erreur d'exécution",
+        "mock_open_1": (
+            "Ce calepin est exécuté comme Composant Web (*Web Component*) "
+            "dans le navigateur Web. Python n'est pas exécuté sur le "
+            "système d'exploitation classique d'un ordinateur mais dans le "
+            "navigateur Web. Ainsi, la fonction standard `open` ne peut pas "
+            "être utilisée pour lire des fichiers car le navigateur, pour "
+            "des raisons de sécurité, n'a pas accès au système de fichiers "
+            "de l'ordinateur. Par conséquent, nous avons remplacé la "
+            "fonction `open` par une fonction personnalisée qui récupère un "
+            "fichier à une URL donnée et qui émule le comportement de la "
+            "fonction standard."
+        ),
+        "mock_open_2": (
+            "Notez que nous ne pouvons pas émuler le comportement complet de "
+            "la fonction standard `open` car récupérer un document en "
+            "requêtant une URL est très différent de lire un fichier sur "
+            "un disque. Notre fonction personnalisée a seulement trois "
+            "paramètres: `filename`, `mode` et `encoding`. Cela suffit pour "
+            "couvrir la plupart des cas d'utilisation. Soyez bien conscients "
+            "que notre fonction personnalisée peut uniquement **lire des "
+            'fichiers** (`mode="r"`) car, comme vous vous en doutez, il est '
+            "impossible d'écrire des fichiers au travers d'une requête Web "
+            "de type GET."
+        ),
+    },
+}
+
+
+def get_message(message_id, lang="en"):
+    """
+    Get the message corresponding to `message_id` in the `lang` language.
+    """
+    localised_msgs = _MESSAGES[lang]
+    return localised_msgs[message_id]