python-interactive-courses 1.0.0__py3-none-any.whl

pyics/util/json_handling.py

@@ -0,0 +1,182 @@
+import copy
+from dataclasses import dataclass
+from decimal import Decimal
+from fractions import Fraction
+from datetime import date, time, datetime, timedelta
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+import json_tricks
+from json_tricks.decoders import pathlib_hook
+
+from pyics.util.paths import StrPath
+
+_OPAQUE_TYPES = (
+    str,
+    bytes,
+    int,
+    float,
+    bool,
+    type(None),
+    Decimal,
+    Fraction,
+    date,
+    time,
+    datetime,
+    timedelta,
+    Enum,
+    complex,
+)
+
+
+def _tag_tuples(obj):
+    if isinstance(obj, tuple):
+        return {"__tuple__": [_tag_tuples(v) for v in obj]}
+    if isinstance(obj, (set, frozenset)):
+        kind = "__pyics_frozenset__" if isinstance(obj, frozenset) else "__pyics_set__"
+        try:
+            items = sorted(obj)
+        except TypeError:
+            items = list(obj)
+        return {kind: [_tag_tuples(v) for v in items]}
+    if isinstance(obj, Path):
+        # json_tricks would store str(obj), i.e. backslashes on Windows. Forward slashes
+        # are read correctly on all platforms.
+        return {"__pathlib__": obj.as_posix()}
+    if isinstance(obj, list):
+        return [_tag_tuples(v) for v in obj]
+    if isinstance(obj, dict):
+        return {k: _tag_tuples(v) for k, v in obj.items()}
+    if isinstance(obj, _OPAQUE_TYPES):
+        return obj
+    if hasattr(obj, "__dict__"):
+        new_obj = copy.copy(obj)
+        object.__setattr__(
+            new_obj, "__dict__", {k: _tag_tuples(v) for k, v in obj.__dict__.items()}
+        )
+        return new_obj
+    return obj
+
+
+def _untag_tuples(dct):
+    if isinstance(dct, dict):
+        if "__tuple__" in dct:
+            return tuple(dct["__tuple__"])
+        if "__pyics_set__" in dct:
+            return set(dct["__pyics_set__"])
+        if "__pyics_frozenset__" in dct:
+            return frozenset(dct["__pyics_frozenset__"])
+    return dct
+
+
+def dumps(obj: Any, **kw: Any) -> str:
+    """Wrapper around ``json_tricks.dumps`` to tag tuples early. Compression isn't
+    supported, since its result is bytes."""
+    txt = json_tricks.dumps(_tag_tuples(obj), **kw)
+    if not isinstance(txt, str):
+        raise TypeError("compressed output isn't supported, use json_tricks directly")
+    return txt
+
+
+def dump(obj, fp, **kw):
+    """Wrapper around ``json_tricks.dump`` to tag tuples early."""
+    return json_tricks.dump(_tag_tuples(obj), fp, **kw)
+
+
+def loads(s, **kw):
+    """Wrapper around ``json_tricks.loads`` to automatically add the _untag_tuples hook."""
+    extra_hooks = (_untag_tuples,) + kw.get("extra_obj_pairs_hooks", tuple())
+    return json_tricks.loads(s, extra_obj_pairs_hooks=extra_hooks, **kw)
+
+
+def load(fp, **kw):
+    """Wrapper around ``json_tricks.load`` to automatically add the _untag_tuples hook."""
+    extra_hooks = (_untag_tuples,) + kw.get("extra_obj_pairs_hooks", tuple())
+    return json_tricks.load(fp, extra_obj_pairs_hooks=extra_hooks, **kw)
+
+
+def _plain_hook(dct: Any) -> Any:
+    """Decode the tags of paths, tuples and sets, if they are all a dict holds, so that
+    nothing that is decoded hides other data from ``scan_tags``."""
+    if not isinstance(dct, dict) or len(dct) != 1:
+        return dct
+    key, value = next(iter(dct.items()))
+    if key == "__pathlib__" and isinstance(value, str):
+        return pathlib_hook(dct)
+    if key in ("__tuple__", "__pyics_set__", "__pyics_frozenset__"):
+        if isinstance(value, list):
+            try:
+                return _untag_tuples(dct)
+            except TypeError:  # unhashable items of a set
+                pass
+    return dct
+
+
+def loads_plain(s: str) -> Any:
+    """
+    Decode ``s`` as plain data: dicts, lists, strings and numbers, paths, and tuples and
+    sets as tagged by ``dumps``. Nothing else is decoded, e.g. class instances stay the
+    dicts json_tricks tagged them as, so that decoding never imports a module or
+    creates an object. For files of plain data, like course manifests, and to inspect a
+    file before it is decoded (see ``scan_tags``).
+    """
+    return json_tricks.loads(s, obj_pairs_hooks=(_plain_hook,))
+
+
+def load_plain(fp: StrPath) -> Any:
+    """``loads_plain`` the file at ``fp``."""
+    with open(fp, encoding="utf-8") as f:
+        return loads_plain(f.read())
+
+
+@dataclass(frozen=True)
+class Tags:
+    """What decoding data tagged by json_tricks needs (see ``scan_tags``)."""
+
+    # the modules that json_tricks imports to decode the classes and enums named by the
+    # tags, None for one defined in a script (i.e. in ``__main__``)
+    modules: frozenset[str | None]
+    # the packages that json_tricks needs for its own tags: numpy for arrays, pandas
+    # for data frames and series, pytz for (date)times with a time zone
+    packages: frozenset[str]
+
+
+def scan_tags(data: Any) -> Tags:
+    """
+    Find what decoding ``data``, as read by ``loads_plain``, needs besides the standard
+    library: the modules of the classes and enums whose instances it holds, and the
+    packages json_tricks needs for some of its tags.
+    """
+    modules: set[str | None] = set()
+    packages: set[str] = set()
+
+    def walk(obj: Any) -> None:
+        if isinstance(obj, dict):
+            if "__instance_type__" in obj:
+                modules.add(_tagged_module(obj["__instance_type__"]))
+            enum = obj.get("__enum__")
+            if isinstance(enum, dict) and "__enum_instance_type__" in enum:
+                modules.add(_tagged_module(enum["__enum_instance_type__"]))
+            if "__ndarray__" in obj:
+                packages.add("numpy")
+            if "__pandas_dataframe__" in obj or "__pandas_series__" in obj:
+                packages.update(("pandas", "numpy"))
+            if ("__datetime__" in obj or "__time__" in obj) and "tzinfo" in obj:
+                packages.add("pytz")
+            for value in obj.values():
+                walk(value)
+        elif isinstance(obj, (list, tuple, set, frozenset)):
+            for value in obj:
+                walk(value)
+
+    walk(data)
+    return Tags(frozenset(modules), frozenset(packages))
+
+
+def _tagged_module(instance_type: Any) -> str | None:
+    """The module of a class tagged as ``[module, name]``."""
+    if isinstance(instance_type, (list, tuple)) and instance_type:
+        module = instance_type[0]
+        return module if isinstance(module, str) and module else None
+    return None

pyics/util/logging.py

@@ -0,0 +1,39 @@
+import logging
+from os import PathLike
+from pathlib import Path
+
+_setup_done: bool = False
+
+
+def setup_logging(
+    level: logging._Level = logging.INFO, fp: PathLike = Path("./.pyics.log")
+):
+    """
+    Perform logging setup
+    """
+    global _setup_done
+
+    logging.root.setLevel(level)
+    logging.root.handlers.clear()
+
+    fp = fp if isinstance(fp, Path) else Path(fp)
+    fp.parent.mkdir(exist_ok=True)
+
+    file_handler = logging.FileHandler(fp, delay=True)
+    file_handler.setFormatter(
+        logging.Formatter(
+            fmt="%(asctime)s [%(levelname)s] %(name)s: %(message)s (%(lineno)d)",
+            datefmt="%H:%M:%S",
+        )
+    )
+
+    logging.root.addHandler(file_handler)
+
+    _setup_done = True
+
+
+def get_logger(name: str) -> logging.Logger:
+    if not _setup_done:
+        setup_logging()
+
+    return logging.getLogger(name)

pyics/util/paths.py

@@ -0,0 +1,38 @@
+import os
+from os import PathLike
+from pathlib import Path
+
+# a path given as a string or path object, as accepted by ``open`` or ``Path``
+type StrPath = str | PathLike[str]
+
+
+def relative_to(path: StrPath, base: StrPath) -> Path:
+    """
+    Express ``path`` relative to the directory ``base`` (e.g. ``../ex/a.py``), so that it
+    can be stored in a file located in ``base``. Relative inputs are interpreted relative
+    to the working directory.
+
+    If no relative path exists (on Windows, ``path`` and ``base`` on different drives),
+    returns ``path`` as an absolute path.
+    """
+    try:
+        return Path(os.path.relpath(Path(path).absolute(), Path(base).absolute()))
+    except ValueError:
+        return Path(path).absolute()
+
+
+def resolve(path: StrPath, base: StrPath) -> Path:
+    """
+    Inverse of ``relative_to``: the path ``path`` points to when read from a file located
+    in the directory ``base``, normalized (``a/../b`` becomes ``b``). Absolute paths are
+    kept as they are.
+    """
+    return Path(os.path.normpath(Path(base) / path))
+
+
+def absolute(path: StrPath) -> Path:
+    """
+    ``path`` as an absolute, normalized path (``a/../b`` becomes ``b``), so that paths
+    given relative to different directories can be compared.
+    """
+    return Path(os.path.abspath(path))

pyics/util/terminal.py

@@ -0,0 +1,57 @@
+"""
+Terminal handling that works the same on all platforms: the escape codes the interface is
+drawn with, the alternate screen it is drawn on, and the terminal's mode.
+"""
+
+import sys
+from collections.abc import Generator
+from contextlib import contextmanager
+
+from prompt_toolkit.input import create_input
+
+LINE_UP = "\033[1A"
+LINE_CLEAR = "\x1b[2K"
+HIDE_CURSOR = "\033[?25l"
+SHOW_CURSOR = "\033[?25h"
+ALT_SCREEN_ENTER = "\033[?1049h"
+ALT_SCREEN_LEAVE = "\033[?1049l"
+
+
+@contextmanager
+def fullscreen() -> Generator[None]:
+    """
+    Draw on the alternate screen while in this context. The cursor is shown again when
+    it is left.
+
+    On Windows, the console only processes escape codes once that is switched on, which
+    is done first. ``rich`` checks for it when a ``Console`` is created, so the ``CLI``
+    has to be created inside this context.
+    """
+    if sys.platform == "win32":
+        import colorama
+
+        colorama.just_fix_windows_console()
+
+    sys.stdout.write(ALT_SCREEN_ENTER)
+    sys.stdout.flush()
+    try:
+        yield
+    finally:
+        sys.stdout.write(SHOW_CURSOR)
+        sys.stdout.write(ALT_SCREEN_LEAVE)
+        sys.stdout.flush()
+
+
+@contextmanager
+def preserve_terminal_mode() -> Generator[None]:
+    """
+    Restore the terminal's mode when this context is left, e.g. around code that may
+    change it. In the meantime, the terminal is in raw mode, as it is while keys are read
+    (see ``KeyListener``). Does nothing if stdin isn't a terminal.
+    """
+    if sys.stdin is None or not sys.stdin.isatty():
+        yield
+        return
+
+    with create_input().raw_mode():
+        yield

python_interactive_courses-1.0.0.dist-info/METADATA

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: python-interactive-courses
+Version: 1.0.0
+Summary: PyICs (Python Interactive Courses) is a modular framework for teaching programming in Python locally, allowing for co-learning of a programming environment.
+Author: johannes-langer
+Author-email: johannes-langer <johannes.langer@uni-bamberg.de>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: colorama>=0.4.6 ; sys_platform == 'win32'
+Requires-Dist: ipykernel>=7.3.0
+Requires-Dist: json-tricks>=3.17.3
+Requires-Dist: jsonargparse>=4.48.0
+Requires-Dist: packaging>=24
+Requires-Dist: platformdirs>=4
+Requires-Dist: pluggy>=1.5
+Requires-Dist: prompt-toolkit>=3.0.53
+Requires-Dist: pyfiglet>=1.0.4
+Requires-Dist: pytest>=9.0.3
+Requires-Dist: rich>=15.0.0
+Requires-Dist: ruff>=0.15.12
+Requires-Dist: snoop>=0.6.0
+Requires-Python: >=3.14
+Project-URL: Repository, https://github.com/johannes-langer/PyICs
+Project-URL: Issues, https://github.com/johannes-langer/PyICs/issues
+Description-Content-Type: text/markdown
+
+# PyICs
+
+_Python Interactive Courses_
+
+## What is PyICs?
+
+PyICs is a framework for interactive Python tutorials, inspired by the _rustlings_ tutorial for the _Rust_ programming language. It strives to strike a balance between ease of use and feature volume, for both instructors and students.
+
+## Installation
+
+PyICs is available via ``pip``. Install the latest version using ``pip install python-interactive-courses``, requiring ``python>=3.14``. PyICs is available on Windows (Windows 10 or later), MacOS, and Linux.
+
+## Using the PyICs App
+
+### As a Student
+
+#### Accessing Courses
+
+Courses come from your instructor: either as files (a course manifest, ``*.pyicscourse.json``, and its task files) or as a course archive (a ``.zip`` file), or from a course library (a _source_) that you add once by the URL of its index, which your instructor gives you:
+
+```sh
+pyics [options] add_source [--name NAME] https://example.org/pyics-courses/index.json
+pyics search                    # the courses of your sources; pyics search graphs finds matching ones
+pyics pull search-algorithms    # pulls it into ./search-algorithms
+pyics                           # start it from the course selector
+```
+
+- ``pyics pull`` can also take the URL or path of a course archive, and ``<source>/<course>`` if everal of your sources have a course of that name. ``--dest <directory>`` pulls it elsewhere.
+- ``pyics update`` (in the course's directory, or ``pyics update <directory>``) updates a pulled course to its latest version. Your exercise files are kept as they are, and so is your progress.
+- ``pyics sources`` lists your sources, and ``pyics remove_source <name>`` removes one. Sources are stored in ``sources.json`` in your pyics configuration directory (e.g. ``~/.config/pyics`` on Linux, ``~/Library/Application Support/pyics`` on macOS, ``%APPDATA%\pyics`` on Windows), so they stay when pyics is upgraded. Administrators can add sources for all users of a computer in the site configuration directory (e.g. ``/etc/xdg/pyics/sources.json``). The ``PYICS_CONFIG_DIR`` environment variable sets another configuration directory, whose sources are then the only ones used.
+- The course selector also offers the courses of your sources that you haven't pulled yet, as they were when you last added, searched or pulled from them. Selecting one pulls it into the working directory.
+
+> Courses run code on your computer, as their tests run your code together with theirs: only add sources and pull courses from people you trust. Sources are fetched over ``https`` (or from local files, e.g. on a network share); plain ``http`` has to be allowed with ``--allow_http``.
+
+Some courses need packages besides ``pyics``, e.g. ``numpy``. They have to be installed in the same environment where PyICs is installed, siunce the tests run in the same Python interpreter. ``pyics search`` and the course selector show which of them are missing, and ``pyics pull`` prints the command that installs them (or runs it with ``--install_deps``, after asking). Packages are never installed without asking.
+
+#### Navigating Courses
+
+The main app starts with a course selector, listing the course manifests found in the working directory and up to two directories below it (``.venv``, ``.git`` and the like are skipped). Once you have selected a course, <kbd>c</kbd> goes back to the course selector, and <kbd>esc</kbd> from there returns to the course that was left. Courses left this way resume where they were left.
+
+When a course is opened, it opens to the first unsolved task in the course. The main body of the app shows a number of tests which fail for the exercise file(s) for the current task, and a link to the file(s) at the very top.  
+Once all tests configured for a task pass, the task counts as completed. When that is the case <kbd>n</kbd> progresses to the next task, and <kbd>p</kbd> returns to the previous one.
+
+##### Help Display
+
+Tasks can have hints (``help`` in the task file), which ``create_task`` and ``edit_task`` ask for after the instructions. In the main app, <kbd>h</kbd> reveals the current task's next hint above its test results, one at a time  and in order. Revealed hints stay revealed until the app is quit, also when you go to another task and back.
+
+##### Tracing Failed Tests
+
+When a test fails, <kbd>t</kbd> runs the task's tests again with [snoop](https://github.com/alexmojaki/snoop), which shows below each failed test what your code did: every line that was run, the values of the variables it changed, and the calls it made, with their arguments and return values. This trace mode stays on while you keep saving your exercise file, until <kbd>t</kbd> is pressed again, and it is off again for every other task you move to.
+
+Function tests (``SimpleTest``) trace the call of the tested function, and output tests (``PrintTest``) the run of the whole file. Their authors can turn tracing off for a test by creating it with ``traceable=False``, e.g. so that its arguments aren't revealed. Tests that check the structure or the signatures of your code (``StructureTest``, ``SpecTest``) aren't traced.
+
+#### Jupyter Notebooks
+
+- A notebook comes without a kernel, so Jupyter or VS Code asks you to select one. Choose the environment in which PyICs is installed, as that is where the tests run.
+- The tests of a task run whenever you **save** its notebook (<kbd>ctrl</kbd>+<kbd>s</kbd>, or when Jupyter autosaves it), like when you save a Python file.
+- They run the code cells of the saved notebook from the top, the way _Restart Kernel and Run All Cells_ does. An error in a cell doesn't stop the run, so an unfinished exercise further down doesn't fail the tests of the exercises above it. When a test fails, its message names the cells that raised an error, e.g. ``cell 7 raised NameError: name 'qeue' is not defined``. Cells are counted from the top, markdown cells included.
+- Notebook-only syntax in a test run:
+  - ``%%time``, ``%%timeit`` and ``%%capture`` run their cell once, without timing it, and so do ``%time`` and ``%timeit`` for their line. What ``%%capture`` captures isn't part of the output.
+  - Other cell magics (e.g. ``%%writefile``, ``%%bash``) skip their cell, and line magics (e.g. ``%matplotlib inline``, ``%pip install``) and shell commands (``!ls``) do nothing: ``files = !ls`` gives an empty list.
+  - ``display(x)`` prints ``x`` as Jupyter shows it as text (its ``repr``), whether or not you import it from ``IPython.display``. Plots are drawn without a window, so ``plt.show()`` doesn't wait for one to be closed.
+- Cells tagged ``skip-execution`` don't run in tests, e.g. a long download or training run. Tags are edited in JupyterLab's property inspector, or with _Add Cell Tag_ in VS Code.
+- Output tests (``PrintTest``) compare what all cells output: what they print, and what Jupyter shows as text, i.e. displayed objects, and the value of a cell whose last line is an expression (``Out[n]``), unless it is ``None`` or the line ends with ``;``. The expected output only has to be part of it, so what you output besides, e.g. while trying things out, doesn't fail the test.
+- Traces (<kbd>t</kbd>) and the messages of structure tests name cells and their lines, e.g. ``bfs.ipynb:cell 3`` or ``cell 3, line 2``.
+
+### As an Instructor
+
+PyICs packages a number of scripts to create, edit, and distribute courses. The process of creating a course and recommended practices are described below.
+
+#### Courses and Tasks
+
+In its background PyICs distinguishes courses and tasks. A course packages multiple tasks, and is detected by PyICs in the current working directory (recursively, up to 3 layers deep) via its file extension (``.pyicscourse.json``). A course does **not** store any information on its tasks other than paths to the course files. This will most likely be addressed in a future version.
+
+Tasks on the other hand package information on a single task, including the paths and contents of exercise and solution files, as well as serialized versions of the configured dynamic tests (see below).
+
+You can create a _course_ by running the following command:
+
+```sh
+pyics create_course [--fp file_path]
+```
+
+The script will ask you to either add tasks you have already created, or directly launch the task creation script which is also available as a standalone using the following command:
+
+```sh
+pyics create_task [--fp file_path]
+```
+
+Note that while the task name is mostly for indexing purposes, the task instructions are displayed in the PyICs header while the task is active. Both task and course creation scripts run interactively, but the task creation script requires you to provide **at least one exercise file**. The script does not create the file for you; it expects a path to an existing file. Exercise files are created on the student's machine when a task is opened.
+
+Similarly, solution files are provided as paths to existing files, but a task can be created without a solution file.
+
+Finally, test creation is run interactively (see below for details on available tests). It is recommended to have a file ready which contains Python objects required for the tests, i.e. the parameters of the tests' constructors. If such a file is provided, the script allows you to select symbols for each of the parameters from those available in the provided file. This is particularly helpful for ``SpecTest``s, as the signatures can be inferred from class or function definitions in a file.  
+**Note:** If a symbol name matches a parameter name in the test's constructor, the symbol is automatically selected.
+
+Existing tasks and courses can be edited using the following commands
+
+```sh
+pyics edit_task path-to-task-file
+pyics edit_course path-to-course-file
+```
+
+#### Tests
+
+The following tests can be configured. If a desired test can't be represented by the options below, please open an issue describing the desired behavior. Any test requires the following two parameters:
+
+- ``name``: The name of the test, displayed in the test results if the test fails.
+- ``file_path``: The path to the exercise file the test targets.
+
+##### ``SimpleTest``
+
+Simple tests are unit tests run on student's code. A ``SimpleTest`` additionally expects the following parameters:
+
+- ``function_name``: The name of the function the test executes.
+- ``expected``: The expected result, i.e. output of the function wrt...
+- ``function_args``: Positional arguments to pass to the function in order to produce the expected output
+- ``function_kwargs``: Keyword arguments to pass to the function in order to produce the expected output
+- ``traceable``: Whether a detailed trace of the function can be displayed. Defaults to ``True``, can be turned off if the trace would give away too much of the solution (use sparingly).
+
+##### ``SpecTest``
+
+Spec tests are signature checks on the student's code. A ``SpecTest`` additionally expects the following parameters:
+
+- ``symbol_name``: The name of the symbol where the expected signature needs to be located.
+- ``expected``: The expected signature. Pass a Type (class) or function/method here. It will be converted to a spec_dict, which can then be serialized and checked against.
+- ``by_type``: If this flag is set to true, check the signature based on type annotations instead of parameter/attribute names. This excludes the ``symbol_name``, which still needs to match.
+
+##### ``StructureTest``
+
+Structure tests can test _how_ tasks are solved by leveraging the ``ast`` builtin library. A ``StructureTest`` additionally expects the following parameter:
+
+- ``rules``: A list of rules enforced by this test. A detailed documentation on how these rules can be configured is found in the [``StructureTest`` documentation](./structure_test.md).
+
+##### ``PrintTest``
+
+Print tests can test whether the stdout of students' files match a desired output. A ``PrintTest`` additionally expects the following parameters:
+
+- ``expected``: The expected output of the targeted file to stdout. The output of a Python file has to match it, while the output of a notebook only has to contain it (see [Jupyter Notebooks](#jupyter-notebooks)).
+- ``inputs``: A list of inputs to provide to the file in case the running script expects inputs (from the builtin ``input()`` function).
+- ``traceable``: Whether a detailed trace of teh function can be displayed. Defaults to ``True``, can be turned off if the trace would give away too much of the solution (use sparingly).
+
+#### Distribution
+
+A course is distributed as an archive holding the course manifest and its task files, but not the exercise or solution files, which are created from the data stored in the task files. Progress is not tracked via the course files, but rather via the exercises that are already solved (exercise files are not overwritten if they already exist). The following command automatically creates a course archive:
+
+```sh
+pyics [options] pack [--out OUT] [--version VERSION] [--description DESCRIPTION] [--slug SLUG] [--tags TAGS [TAGS ...]] [--include INCLUDE [INCLUDE ...]] [--no_solutions] [--yes] manifest
+```
+
+The ``--include`` option can be used to add other files the course needs (e.g. datasets), and ``--no_solutions`` removes the solution files from the tasks (if they existed). ``--version``, ``--description``, and ``--tags`` are stored in the manifest, so if a course is ever re-packed it will re-use the given values. ``--slug`` is the name a course is pulled by, and it is derived from the course's name unless an explicit name is provided via this option. ``--yes`` automatically accepts confirmation prompts.  
+``pack`` also finds the packages the course uses besides ``pyics`` and the standard library (imported by its exercise and solution code, or needed for the values its tests store, like numpy arrays), and offers to declare those that aren't declared in the manifest's ``requires`` yet. A task file may only make PyICs import modules of the packages its course declares: any other module is refused before the task is loaded.
+
+``build`` indes lists the newest version of each course in the archives below the directory in ``index.json``.
+
+```sh
+pyics [options] build_index [--out OUT] [--name NAME] [directory]
+```
+
+Students add its URL with ``pyics add_source``. A course archive can also be pulled directly by its URL or path. An index looks like this, with the archives' URLs relative to it.
+
+```json
+{
+    "pyics_index": 1,
+    "name": "Uni Bamberg AI courses",
+    "courses": {
+        "search-algorithms": {
+            "title": "Search Algorithms",
+            "description": "DFS and BFS",
+            "version": "1.0.0",
+            "requires_pyics": ">=0.0.1",
+            "requires": ["numpy>=1.26"],
+            "url": "search-algorithms-1.0.0.zip",
+            "sha256": "...",
+            "tags": ["graphs"]
+        }
+    }
+}
+```
+
+Archives are checked before anything of them is used: they can't write files outsinde the directory they are pulled to, their has h has to match the index, and they can only name the modules of the packages they declare.
+
+#### Jupyter Notebooks
+
+- ``create_task`` and ``edit_task`` accept notebooks as exercise and solution files, and all tests work with them. ``SimpleTest``s and ``SpecTest``s find functions and classes by name, in whichever cell students define them. ``StructureTest``s check the code of all code cells: cells that can't be parsed are left out, and named in the message if the test fails. ``PrintTest``s compare the output of all cells. Both can be restricted to a part of the notebook instead (see [Sections](#sections)).
+- The output of a notebook only has to **contain** the ``expected`` output of a ``PrintTest``, rather than match it like the output of a Python file, since students also output other things in the cells of an exercise, e.g. the value of an expression they left at the end of a cell. Whitespace at the ends of lines is ignored, as usual. Short expected outputs are found easily: ``[a, b]`` is also found in ``[[a, b]]``, and ``3`` in ``13``, so expect enough to tell a right output from a wrong one, e.g. ``Sum: 3``. A test that expects no output still fails if there is any.
+- Notebooks are stored normalized in task files: without their outputs and execution counts, so that the outputs of solutions don't reach students and task files stay small. Their kernel (``kernelspec``) isn't stored either, as it names an environment on your machine: students are asked to select a kernel of their own when they first open or run the notebook. A notebook you merely ran, or ran with another kernel, doesn't count as changed when you edit the task. If it did change, ``edit_task`` shows the difference as the text of its cells (``# %% cell 3`` blocks) rather than as JSON. If only its metadata changed (e.g. the tags of its cells), it says so.
+- A notebook, e.g. the solution notebook, can be the test information file. Its code cells run as they do in tests, and its variables are offered for the test's parameters, e.g. a function as the ``expected`` signature of a ``SpecTest``. An error in a cell doesn't stop the run, and the prompts name the cell that raised it.
+- The tests run in the directory PyICs was started in, while Jupyter runs a notebook in the notebook's directory: a file that a notebook opens by a relative path is looked up in different directories by the two.
+- Keep the exercise notebooks in a visible directory, as ``examples/search_notebook`` does, rather than in ``.exercises/``: JupyterLab only opens notebooks in hidden directories if it runs with ``--ContentsManager.allow_hidden=True``.
+- ``pack`` finds the packages imported in the code cells of notebooks, too. If the course's ``requires`` don't declare them, it shows the ``%pip install`` (and ``!pip install``) lines of its notebooks as hints, e.g. ``lecture.ipynb (cell 2): %pip install numpy``. These lines do nothing in tests, so the packages have to be declared. ``pack`` also warns about tasks that share a notebook, but store different contents for it (see [Sections](#sections)).
+- An alternative that needs no notebook support is to pair a notebook with a Python file using [Jupytext](https://jupytext.readthedocs.io), and to use the ``.py`` file as the exercise file (magics are commented out in it). Students then need Jupytext in their Jupyter, and pairing tends to confuse beginners.
+
+Sections link a task to a part of a notebook, e.g. to one exercise of a lecture's notebook that holds several.
+
+- **Where a section starts:** at a cell tagged ``pyics:<name>``, or at a cell whose first line is the marker ``<!-- pyics: <name> -->`` (a markdown cell) or ``# pyics: <name>`` (a code cell). Names consist of letters, digits, ``_``, ``.`` and ``-``, e.g. ``ex2``. Tags are Jupyter's own way to mark cells, but hidden in most frontends. Markers are visible everywhere, and students can restore one they deleted.
+- **Where it ends:** just before the next section starts, or at the end of the notebook. Cells above the first section belong to none. If several cells start a section of the same name (e.g. a copied cell), the first of them does.
+- **Where to put it:** on the exercise's description, a markdown cell that students have no reason to change. The cells they add below it, split or move belong to the section, as long as they stay above the next one.
+- **A task's section:** ``create_task`` and ``edit_task`` ask which section of each notebook exercise file the task is about (if the notebook has sections), and store it in the task file (``"sections"``, by the notebook's path relative to the task file). Older versions of PyICs ignore it.
+- **Its tests:** ``StructureTest``s check only the code cells of the section, and fail if one of them can't be parsed. ``PrintTest``s compare only the output of the section's cells, while the whole notebook still runs, as a section usually needs the imports and data above it. ``SimpleTest``s and ``SpecTest``s find functions and classes by name, wherever they are defined, and aren't affected by sections.
+- **A test's own section:** ``StructureTest``s and ``PrintTest``s use the task's section, unless they are given one of their own: ``section="ex1"`` for another section, or ``section=None`` for the whole notebook. ``create_task`` offers _The task's section_, _Whole notebook_ and the notebook's other sections. A test that uses the task's section stores nothing, so it follows when the task's section is changed.
+- **Finding it:** the title of the main panel names the task's section after the notebook's path, e.g. ``lecture.ipynb › Exercise 2: Breadth-First Search``: the first heading of the cell that starts it, or else its name, looked up in the saved notebook. JupyterLab's _Table of Contents_ and VS Code's _Outline_ (<kbd>ctrl</kbd>+<kbd>shift</kbd>+<kbd>o</kbd>) list the notebook's headings.
+- **A missing section fails its tests** with an explanation, e.g. ``Section 'ex2' not found: the cell that starts it (tagged 'pyics:ex2', or starting with the marker '# pyics: ex2') was removed or its tag changed.``, and the title shows ``section 'ex2' not found``. Tests never check another part of the notebook instead.
+- **Several tasks in one notebook:** each task lists the same notebook among its exercise files, with its own section, and is solved on its own. The first of them that is set up creates the notebook (an existing exercise file is never overwritten), so they should all store the same contents for it: ``pack`` warns if they don't, and so does ``edit_task`` after writing a task (choose _Update_ for the notebook to store it as it is on disk).
+
+## Technical Information
+
+This project is managed using ``uv``. If you want to contribute to the project, run ``uv sync`` after cloning the repository at the top level to create a virtual environment with the required packages installed.
+
+### Repository/App Structure
+
+The ``src/pyics`` directory contains the following submodules:
+
+- ``data`` which models ``Task``s and ``Course``s
+- ``scripts`` which contains the executable scripts
+- ``tests`` which contains anything related to dynamic test objects (the core testing logic for student code)
+- ``distribution`` which packs, publishes and pulls courses, and checks the packages they need
+- ``notebook`` which reads Jupyter notebooks, runs their code cells as exercise files, and finds their sections
+- ``plugins`` which loads plugins, packages that extend pyics through [pluggy](https://pluggy.readthedocs.io) hooks, e.g. ``pyics-jupyter``
+- ``util`` containing logic for json handling and logging

python_interactive_courses-1.0.0.dist-info/RECORD

@@ -0,0 +1,49 @@
+pyics/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyics/app/actions.py,sha256=wig2BYXJLL6FTT3c0YuDMGEHyS3Hxr_Gx-uXOymMaFo,4747
+pyics/app/cli.py,sha256=9LBf5ssA99MUjHwLzi_kN_cDJK_gkqsR94nHOcm4EZ4,12620
+pyics/app/key_listener.py,sha256=rXiZbehuyukCfBO2dyftyZaXFTVbyOgwr6eNmvVkuY0,4726
+pyics/app/prompts.py,sha256=Vmr7z0_o2EXu46mNf3iLhkcfLx0bogemdE6oAAeiCbc,16362
+pyics/app/pyics.py,sha256=AzGAbzxMcXds_WBTW-0zisk_odbpsyzHe_7-jrYDvW0,17528
+pyics/data/__init__.py,sha256=TB-H_exM3p3MCF5lR-FYZ3f9pJmHOr-LN1xZGCWdyn0,76
+pyics/data/course.py,sha256=xipAnrwUp8hx3sVhvahVsve9jHF3Ehvz4iesvN9EAd4,19875
+pyics/data/task.py,sha256=SnC2O9qSzzNXlsnmFzhVXXk3DgU0tcsdIFdXor5toeY,28440
+pyics/distribution/__init__.py,sha256=wDCDT-tkS62EsLTJwnGzjbiKsYm72ur1WgV1a4sQnT0,226
+pyics/distribution/archive.py,sha256=QsOp9LcdKxQgRYW5M3XAlQEg931Ls6NBmcFTRT8KYf4,25704
+pyics/distribution/dependencies.py,sha256=Lteez1HRNaZOwUwmd1XFYoOmJ6bukFBwB9d9f4pw9DY,17177
+pyics/distribution/fetch.py,sha256=TkR6yk22IQXG6jOTLp72ERWDuLjWRnr7UYq3zHlIDIk,4753
+pyics/distribution/pull.py,sha256=-oPh5gN_xXS53igt6aTAMLiB3OlfAVi4YkDEmnNSAQk,13767
+pyics/distribution/slugs.py,sha256=QCtaOsra79v3HH_mN-zQLDUxXPAxc-cg4pud1xme3cI,778
+pyics/distribution/sources.py,sha256=PiTng8-0sE168xij2PGNuEy40ZK2GGx_0FAufMMBAIk,19822
+pyics/notebook/__init__.py,sha256=nKZG7OesmxBWWR10XD_0EXz0YfgaO37tofGeA6z5j7I,81
+pyics/notebook/cells.py,sha256=eu5FLfPWPfboDD5xqmakgtd-r-p-SE1AOmB4FFi2vzk,6556
+pyics/notebook/loader.py,sha256=hVB9eZbTwBOBqECESwgxnpq9wINlzAgxpACSGw6KxF4,22742
+pyics/notebook/sections.py,sha256=IIWTqJee4pM4pMqi46FgR2uzD4U0FBAntF6QDuEsVKw,7329
+pyics/plugins.py,sha256=PkQMX9l0P6UAwsgBfk6-xAbZBQ9QKmz_NwN1ob9FnvA,3138
+pyics/scripts/console.py,sha256=ZKEVX4oE6p9EpHJtEnkyHzxaxCKFnMYi46q9SS6_QMQ,3003
+pyics/scripts/create_course.py,sha256=dTEzlxHqbaXKgwglKVWK2WFyUgUlCe7fKrWuJ2EX_dw,11140
+pyics/scripts/create_task.py,sha256=ywRboKNt6kaIIb2Mj7pyxgtk8n3GlNY5tbLwaIbeeeQ,32927
+pyics/scripts/edit_course.py,sha256=xR_b-E_SGySsLya2UaEw33J8IFESujx46dTYgmN7-ao,5446
+pyics/scripts/edit_task.py,sha256=6EcxQSMC4uogjNvkiDOo4ENB5-VYm_pRFU8tg-hsA3E,4299
+pyics/scripts/main.py,sha256=5bYOmWcgc1JTokzU1JL8Ex-Ff1iuqhbubYuyynx2Wjs,4516
+pyics/scripts/pack.py,sha256=8E_XAGuY8vnsomOHeLttE2PiCQL4k1NoJnyMIGBIMVs,7916
+pyics/scripts/pull.py,sha256=mUS_hz2vBTULjdZFG5dkKc9xk22sYwlnHPo65YqkxxQ,4420
+pyics/scripts/sources.py,sha256=jGeJDH32nebVnAcEjmlaveFa4wY-yb0vD_1ueNmiGTw,4164
+pyics/tests/__init__.py,sha256=1CMagUMIq3lkC5q2Qq2TaQPrT6X3HcVXKYHXuD6U3Oo,166
+pyics/tests/capture.py,sha256=8OKVK5U4HSqRB7Nj6tiXkuamUDmRE-IeOBjIGZrdS4M,3281
+pyics/tests/check_specs.py,sha256=x3KxDQ1KgktnJmRnNpKbIcdJ7wEVAgdfgETBEylpC6c,19385
+pyics/tests/check_structure.py,sha256=QXrAWhbznx0ZQIKHcDMWXFmWSLiu89mWU2gAJOwsdls,26875
+pyics/tests/compare.py,sha256=WatNKrho4eyoIM8CvANqAdT8jy3ZgDcEoUMqIR6i6N4,7109
+pyics/tests/pytest_integration.py,sha256=vgTrQnK9RqZ3LudDTmLdAD4fm9BpFmE1LhuQ1uTi2cU,8276
+pyics/tests/results.py,sha256=2A23iqIV_6kN5pCzCbcjCOUvnP8jawEvBe6Y87mxJpc,5240
+pyics/tests/tests.py,sha256=b844VKGzzvZsvul-6a5pUHLvus7CxPP6dMadnWlnZpY,17126
+pyics/tests/trace.py,sha256=zRgKClJXUxDf0p36XN0szbYOKRAPj3ooeecSdox60Z4,5545
+pyics/util/discovery.py,sha256=g3jtWhn2BHny4T0v7h1x0RoKN9jzu38str3rjpz407s,3084
+pyics/util/json_handling.py,sha256=HX_xp9v6PtQc60Y7YN0yOkiIp45SJNZovkFo2fTx9FY,6361
+pyics/util/logging.py,sha256=qQKAJZ2th5Q_2add7XN-zCzRkvus_wgKHVvt3-eMN2E,854
+pyics/util/paths.py,sha256=RH__GAywFPQf_E1mrQGA6JzrqHQvIgGKsPiKGmxxoHc,1305
+pyics/util/terminal.py,sha256=nyTvNC4wxKYxtBd9URxIz65xNeVMluNbnct9bKVLYNI,1628
+python_interactive_courses-1.0.0.dist-info/licenses/LICENSE,sha256=PUrGQXGE5VsEi2wCS6xiW9J1N75eJtSkg12DWpiy-n4,1072
+python_interactive_courses-1.0.0.dist-info/WHEEL,sha256=xTCBFIZIIyRSxyowOv5Wqg_jFU6KsdIffuulBB09Ph8,80
+python_interactive_courses-1.0.0.dist-info/entry_points.txt,sha256=YDzxN7dg2P2fh9rAfv11R-9cZqVeUv51odlXv68lgdo,50
+python_interactive_courses-1.0.0.dist-info/METADATA,sha256=uhmvi23b_sKvkEhHx4fSi4RUHb67Njnuq-nLnjkp-KA,23506
+python_interactive_courses-1.0.0.dist-info/RECORD,,

python_interactive_courses-1.0.0.dist-info/WHEEL

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

python_interactive_courses-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+pyics = pyics.scripts.main:run
+

python_interactive_courses-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Johannes Langer
+
+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.