Metadata-Version: 2.4
Name: learnlog
Version: 0.20
Summary: Automatic logging of student code development and test runs
License-Expression: MIT
License-File: LICENSE
Author: Daniel Bosk
Author-email: daniel@bosk.se
Maintainer: Daniel Bosk
Maintainer-email: dbosk@kth.se
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Education
Classifier: Topic :: Education
Requires-Dist: pylint (>=4.0)
Requires-Dist: pytorial (>=0.8,<0.9)
Requires-Dist: radon (>=6.0)
Requires-Dist: ruff (>=0.16)
Requires-Dist: typer (>=0.9.0)
Requires-Dist: virtualenv (>=20)
Project-URL: Bug Tracker, https://github.com/dbosk/learnlog/issues
Project-URL: Repository, https://github.com/dbosk/learnlog
Description-Content-Type: text/markdown

# learnlog

A Python package that automatically logs code development and program runs.

By adding `import learnlog` as the first import in a Python file, every
program run is recorded transparently: source code changes, command-line
arguments, standard input/output/error, and unhandled exceptions. The data is
stored in a hidden local Git repository.

## Use cases

- **Sharing live-coding sessions.**
  A teacher adds `import learnlog` to demonstration scripts during a lecture
  or tutorial. After the session the teacher pushes the log to a remote
  repository:

  ```bash
  learnlog set-remote git@gitlab.kth.se:dbosk/lecture01.git
  learnlog push
  ```

  Students clone the log and replay it step by step:

  ```bash
  learnlog clone git@gitlab.kth.se:dbosk/lecture01.git
  learnlog play
  ```

  Alternatively, when a shared Git remote is not available, the teacher can
  export the log as a portable bundle file:

  ```bash
  learnlog export -o lecture01.bundle
  ```

  The teacher distributes the file (e.g. via a course page) and students
  replay it directly:

  ```bash
  learnlog play lecture01.bundle
  ```

  Older recordings can also be reused as debugging case studies for later
  students.

- **Studying, supporting, and reviewing how students code.**
  A researcher creates an empty Git repository for each student. Each student
  adds `import learnlog` to their programs and pushes the log:

  ```bash
  learnlog set-remote git@gitlab.kth.se:dbosk/alice-log.git
  learnlog push
  ```

  The researcher then clones each student's repository to analyse the
  development data:

  ```bash
  learnlog clone git@gitlab.kth.se:dbosk/alice-log.git
  learnlog play
  learnlog analyse X-Tag=lab1 X-Tag=lab2
  ```

  The `analyse` command generates LaTeX reports of edit--run cycles.
  The optional positional arguments filter events by `Column=Regex`
  boundaries—here, only events between tags `lab1` and `lab2` are
  included.

  Alternatively, the student can export the log as a bundle and submit it
  through the course platform:

  ```bash
  learnlog export -o alice-log.bundle
  ```

  The researcher then replays it directly:

  ```bash
  learnlog play alice-log.bundle
  ```

  This gives a complete timeline of how students develop and debug their
  code. Students can use it for self-review, or show a TA what they already
  tried before asking for help. Teachers can reuse old recordings of
  authentic problems as debugging instruction material, train TAs on common
  difficulty patterns and authentic debugging traces, inspect development
  paths during assessment moderation, improve assignments and curricula, and
  compare cohorts or interventions. The same recordings also support
  reproducible bug reports, research on programming process, and authorship
  review, including possible AI-assisted or externally authored work when the
  final submission does not match the recorded development path.

