Jurigged lets you update your code while it runs. Using it is trivial:
Jurigged updates live code smartly: changing a function or method will fudge code pointers so that all existing instances are simultaneously modified to implement the new behavior. When modifying a module, only changed lines will be re-run.
Jurigged requires Python version >= 3.8.
pip install jurigged
The simplest way to use jurigged is to add
-m jurigged to your script invocation, or to use
jurigged instead of
python. You can use
-v to get feedback about what files are watched and what happens when you change a file.
python -m jurigged -v script.py OR jurigged -v script.py
With no arguments given, it will start a live REPL:
python -m jurigged OR jurigged
usage: jurigged [-h] [--interactive] [--watch PATH] [--debounce DEBOUNCE] [-m MODULE] [--verbose] [--version] [PATH] ... Run a Python script so that it is live-editable. positional arguments: PATH Path to the script to run ... Script arguments optional arguments: -h, --help show this help message and exit --interactive, -i Run an interactive session after the program ends --watch PATH, -w PATH Wildcard path/directory for which files to watch --debounce DEBOUNCE, -d DEBOUNCE Interval to wait for to refresh a modified file, in seconds -m MODULE Module or module:function to run --verbose, -v Show watched files and changes as they happen --version Print version
First, if there's a problem, use the verbose flag (
jurigged -v) to get more information. It will output a
Watch <file> statement for every file that it watches and
Update/Add/Delete <function> statements when you update, add or delete a function in the original file and then save it.
The file is not being watched.
By default, scripts are watched in the current working directory. Try
jurigged -w <file> to watch a specific file, or
jurigged -w / to watch all files.
The file is watched, but nothing happens when I change the function.
It's possibly because you are using an editor that saves into a temporary swap file and moves it into place (vi does this). The
watchdog library that Jurigged uses loses track of the file when that happens. Pending a better solution, you can try to configure your editor so that it writes to the file directly. For example, in vi,
:set nowritebackup seems to do the trick (either put it in your .vimrc or execute it before you save for the first time).
Jurigged said it updated the function but it's still running the old code.
If you are editing the body of a for loop inside a function that's currently running, the changes will only be in effect the next time that function is called. A workaround is to extract the body of the for loop into its own helper function, which you can then edit. Alternatively, you can use reloading alongside Jurigged.
Similarly, updating a generator or async function will not change the behavior of generators or async functions that are already running.
I can update some functions but not others.
There may be issues updating some functions when they are decorated or stashed in some data structure that Jurigged does not understand. Jurigged does have to find them to update them, unfortunately.
You can call
jurigged.watch() to programmatically start watching for changes. This should also work within IPython or Jupyter as an alternative to the
import jurigged jurigged.watch()
By default all files in the current directory will be watched, but you can use
jurigged.watch("script.py") to only watch a single file, or
jurigged.watch("/") to watch all modules.
Functions can be programmatically changed using a Recoder. Make one with
jurigged.make_recoder. This can be used to implement hot patching or mocking. The changes can also be written back to the filesystem.
from jurigged import make_recoder def f(x): return x * x assert f(2) == 4 # Change the behavior of the function, but not in the original file recoder = make_recoder(f) recoder.patch("def f(x): return x * x * x") assert f(2) == 8 # Revert changes recoder.revert() assert f(2) == 4 # OR: write the patch to the original file itself recoder.commit()
revert will only revert up to the last
commit, or to the original contents if there was no commit.
A recoder also allows you to add imports, helper functions and the like to a patch, but you have to use
recoder.patch_module(...) in that case.
Jurigged works in a surprisingly large number of situations, but there are several cases where it won't work, or where problems may arise:
__init__or rename attributes on existing instances, so you can easily end up with broken objects (new methods, but old data).
__conform__method (see below).
In order to update a transform of a Python function, for example a transform that generates a new code object based on the original source code, you need to do something like this:
class Custom: __slots__ = ("code",) def __init__(self, transformed_fn, code): self.code = code self.transformed_fn = transformed_fn def __conform__(self, new_code): if new_code is None: # Function is being deleted ... if isinstance(new_code, types.FunctionType): new_code = new_code.__code__ do_something(new_code) self.code = new_code ... transformed_fn.somefield = Custom(transformed_fn, orig_fn.__code__)
Basically, when the original code is changed, jurigged will use the
gc module to find objects that point to it, and if they have a
__conform__ method it will be called with the new code so that the transformed function can be updated. The original code must be in a slot on that object (it is important that it is in
__slots__, otherwise the referrer is a dictionary). Multiple transformed functions may exist.
In a nutshell, jurigged works as follows:
gc.get_objects(). c. Add an audit hook that watches calls to
execin order to inventory any new functions.
gc.get_referrers()to find all functions that use the old code d. Replace their internal
The two most comparable implementations of Jurigged's feature set that I could find (but it can be a bit difficult to find everything comparable) are %autoreload in IPython and limeade. Here are the key differences:
They both re-execute the entire module when its code is changed. Jurigged, by contrast, surgically extracts changed functions from the parse tree and only replaces these. It only executes new or changed statements in a module.
Which is better is somewhat situation-dependent: on one hand, re-executing the module will pick up more changes. On the other hand, it will reinitialize module variables and state, so certain things might break. Jurigged's approach is more conservative and will only pick up on modified functions, but it will not touch anything else, so I believe it is less likely to have unintended side effects. It also tells you what it is doing :)
They will re-execute decorators, whereas Jurigged will instead dig into them and update the functions it finds inside.
Again, there's no objectively superior approach.
%autoreload will properly re-execute changed decorators, but these decorators will return new objects, so if a module imports an already decorated function, it won't update to the new version. If you only modify the function's code and not the decorators, however, Jurigged will usually be able to change it inside the decorator, so all the old instances will use the new behavior.
They rely on synchronization points, whereas Jurigged can be run in its own thread.
This is a double-edged sword, because even though Jurigged can add live updates to existing scripts with zero lines of additional code, it is not thread safe at all (code could be executed in the middle of an update, which is possibly an inconsistent state).
Other similar efforts: