Improve reloading

.gitattributes

@@ -0,0 +1,2 @@
+# git-archive: ignore .gitignore, .gitattributes, .github/ etc. 
+.git* export-ignore

.github/workflows/CI.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+
+jobs:
+  test_2004:
+    name: ${{ matrix.os }} - Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-20.04, windows-latest]
+        python-version: ["3.6", "3.7"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+        env:
+          PIP_TRUSTED_HOST: "pypi.python.org pypi.org files.pythonhosted.org"
+      - name: Install reloading
+        run: python -m pip install .
+      - name: Test with unittest
+        run: python -m unittest
+  test_2204:
+    name: ${{ matrix.os }} - Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-22.04, windows-latest]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install reloading
+        run: python -m pip install ".[development]"
+      - name: Lint with flake8
+        run: flake8
+      - name: Lint with ruff
+        run: ruff check .
+      - name: Type check with pyright
+        run: pyright
+      - name: Type check with mypy
+        run: mypy .
+      - name: Test with unittest
+        run: python -m unittest

README.md

@@ -1,156 +1,161 @@
-# reloading
-[![pypi badge](https://img.shields.io/pypi/v/reloading?color=%230c0)](https://pypi.org/project/reloading/)
+# Reloading
+[![CI](https://github.com/nneskildsf/reloading/actions/workflows/CI.yml/badge.svg)](https://github.com/nneskildsf/reloading/actions/workflows/CI.yml)
+[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
+[![Linting: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 
-A Python utility to reload a loop body from source on each iteration without
-losing state
+A Python utility to reload a function or loop body from source on each iteration without losing state.
 
-Useful for editing source code during training of deep learning models. This lets
-you e.g. add logging, print statistics or save the model without restarting the
-training and, therefore, without losing the training progress.
+## Installing Reloading and Supported Versions
+This fork of reloading is *not* available on PyPi. Install it from Github:
+```console
+$ pip install https://github.com/nneskildsf/reloading/archive/refs/heads/master.zip
+```
 
-![Demo](https://github.com/julvo/reloading/blob/master/examples/demo/demo.gif)
+This fork of reloading supports Python 3.6+.
 
-## Install
-```
-pip install reloading
-```
+## Supported Features
+- Reload functions, `for` loops and `while` loops
+- Works in Jupyter Notebook
+- `break` and `continue` in loops
+- Multiple reloading functions and loops in one file
+- Reloaded functions preserve their original call signature
+- Only reload source code when changed for faster performance
+- Comprehensive exceptions and logging
+- Exports locals of reloaded loops to parent locals (Python 3.13 and newer)
 
 ## Usage
 
-To reload the body of a `for` loop from source before each iteration, simply 
-wrap the iterator with `reloading`, e.g.
+### For Loop
+To reload the body of a `for` loop from source before each iteration, wrap the iterator with `reloading`:
 ```python
 from reloading import reloading
 
 for i in reloading(range(10)):
-    # this code will be reloaded before each iteration
+    # This code will be reloaded before each iteration
     print(i)
+```
+
+### While Loop
+To reload the body and condition of a `while` loop from source before each iteration, wrap the condition with `reloading`:
+```python
+from reloading import reloading
 
+i = 0
+while reloading(i<10):
+    # This code and the condition (i<10) will be reloaded before each iteration
+    print(i)
+    i += 1
 ```
 
+### Function
 To reload a function from source before each execution, decorate the function
-definition with `@reloading`, e.g.
+definition with `@reloading`:
 ```python
 from reloading import reloading
 
 @reloading
-def some_function():
-    # this code will be reloaded before each invocation
+def function():
+    # This code will be reloaded before each function call
     pass
 ```
 
-## Additional Options
-
-Pass the keyword argument `every` to reload only on every n-th invocation or iteration. E.g.
+It is also possible to mark a function for reload after defining it:
 ```python
-for i in reloading(range(1000), every=10):
-    # this code will only be reloaded before every 10th iteration
-    # this can help to speed-up tight loops
-    pass
+from reloading import reloading
 
-@reloading(every=10)
-def some_function():
-    # this code with only be reloaded before every 10th invocation
+def function():
+    # This function will be reloaded before each function call
     pass
-```
 
-Pass `forever=True` instead of an iterable to create an endless reloading loop, e.g. 
-```python
-for i in reloading(forever=True):
-    # this code will loop forever and reload from source before each iteration
-    pass
+function = reloading(function)
 ```
 
-## Examples
-
-Here are the short snippets of how to use reloading with your favourite library.
-For complete examples, check out the [examples folder](https://github.com/julvo/reloading/blob/master/examples).
+## Additional Options
 
-### PyTorch
+### Interactive Exception Handling
+Exceptions are handled interactively by default to avoid losing state.
+When an exception occurs you will be notified and have the opportunity
+to rectify the issue and continue. However, if reloading is
+used in a setting where exceptions are better handled in the application
+using reloading then it can be disabled by setting `interactive_exception`
+to `False`. Example:
 ```python
-for epoch in reloading(range(NB_EPOCHS)):
-    # the code inside this outer loop will be reloaded before each epoch
-
-    for images, targets in dataloader:
-        optimiser.zero_grad()
-        predictions = model(images)
-        loss = F.cross_entropy(predictions, targets)
-        loss.backward()
-        optimiser.step()
-```
-[Here](https://github.com/julvo/reloading/blob/master/examples/pytorch/train.py) is a full PyTorch example.
+from reloading import reloading
 
-### fastai
-```python
-@reloading
-def update_learner(learner):
-    # this function will be reloaded from source before each epoch so that you
-    # can make changes to the learner while the training is running
+@reloading(interactive_exception=False)
+def reloading_function():
     pass
 
-class LearnerUpdater(LearnerCallback):
-    def on_epoch_begin(self, **kwargs):
-        update_learner(self.learn)
+for i in reloading(range(10), interactive_exception=False):
+    pass
 
-path = untar_data(URLs.MNIST_SAMPLE)
-data = ImageDataBunch.from_folder(path)
-learn = cnn_learner(data, models.resnet18, metrics=accuracy, 
-                    callback_fns=[LearnerUpdater])
-learn.fit(10)
+j = 0
+while reloading(j<10, interactive_exception=False):
+    j += 1
 ```
-[Here](https://github.com/julvo/reloading/blob/master/examples/fastai/train.py) is a full fastai example.
 
-### Keras
+### Iterate Forever in For Loop
+To iterate forever in a `for` loop you can omit the argument:
 ```python
-@reloading
-def update_model(model):
-    # this function will be reloaded from source before each epoch so that you
-    # can make changes to the model while the training is running using
-    # K.set_value()
-    pass
+from reloading import reloading
 
-class ModelUpdater(Callback):
-    def on_epoch_begin(self, epoch, logs=None):
-        update_model(self.model)
+for _ in reloading():
+    # This code will loop forever and reload from source before each iteration
+    pass
+```
 
-model = Sequential()
-model.add(Dense(64, activation='relu', input_dim=20))
-model.add(Dense(10, activation='softmax'))
+### Code Changes Logged
+On Python 3.9 and newer, a diff is logged when the source code is updated.
+Consider the following code as an example.
+```python
+from reloading import reloading
+from time import sleep
+import logging
 
-sgd = SGD(lr=0.01, decay=1e-6, momentum=0.9, nesterov=True)
-model.compile(loss='categorical_crossentropy',
-              optimizer=sgd,
-              metrics=['accuracy'])
+log = logging.getLogger("reloading")
+log.setLevel(logging.DEBUG)
 
-model.fit(x_train, y_train,
-          epochs=200,
-          batch_size=128,
-          callbacks=[ModelUpdater()])
+for i in reloading(range(100)):
+    print(i)
+    sleep(1.0)
+```
+After some time the code is edited. `i = 2*i` is added before `print(i)`,
+resulting in the following log output:
+```console
+INFO:reloading:For loop at line 10 of file "../example.py" has been reloaded.
+DEBUG:reloading:Code changes:
++i = i * 2
+ print(i)
+ sleep(1.0)
 ```
-[Here](https://github.com/julvo/reloading/blob/master/examples/keras/train.py) is a full Keras example.
 
-### TensorFlow
+## Known Issus
+
+On Python version [less than 3.13](https://docs.python.org/3/reference/datamodel.html#frame.f_locals) it is not possible to properly export the local variables from a loop to parent locals. The following example demonstrates this:
 ```python
-for epoch in reloading(range(NB_EPOCHS)):
-    # the code inside this outer loop will be reloaded from source
-    # before each epoch so that you can change it during training
-
-    train_loss.reset_states()
-    train_accuracy.reset_states()
-    test_loss.reset_states()
-    test_accuracy.reset_states()
-
-    for images, labels in tqdm(train_ds):
-      train_step(images, labels)
-
-    for test_images, test_labels in tqdm(test_ds):
-      test_step(test_images, test_labels)
-```
-[Here](https://github.com/julvo/reloading/blob/master/examples/tensorflow/train.py) is a full TensorFlow example.
+from reloading import reloading
 
-## Testing
+def function():
+    i = 0
+    while reloading(i < 10):
+        i += 1
+    print(i)
 
-Make sure you have `python` and `python3` available in your path, then run:
+function() # Prints 0. Not 10 as expected. Fixed in Python 3.13.
+```
+A warning is emitted when the issue arises:
+```console
+WARNING:reloading:Variable(s) "i" in reloaded loop were not exported to the scope which called the reloaded loop at line...
 ```
-$ python3 reloading/test_reloading.py
+
+## Lint, Type Check and Testing
+
+Run:
+```console
+$ pip install -e ".[development]"
+$ ruff check .
+$ flake8
+$ pyright
+$ mypy .
+$ python -m unittest
 ```