https://github.com/breuleux/jurigged Skip to content Sign up Sign up * Why GitHub? Features - + Mobile - + Actions - + Codespaces - + Packages - + Security - + Code review - + Project management - + Integrations - + GitHub Sponsors - + Customer stories- * Team * Enterprise * Explore + Explore GitHub - Learn and contribute + Topics - + Collections - + Trending - + Learning Lab - + Open source guides - Connect with others + The ReadME Project - + Events - + Community forum - + GitHub Education - + GitHub Stars program - * Marketplace * Pricing Plans - + Compare plans - + Contact Sales - + Education - [ ] [search-key] * # In this repository All GitHub | Jump to | * No suggested jump to results * # In this repository All GitHub | Jump to | * # In this user All GitHub | Jump to | * # In this repository All GitHub | Jump to | Sign in Sign up Sign up {{ message }} breuleux / jurigged * Notifications * Star 162 * Fork 1 Hot reloading for Python MIT License 162 stars 1 fork Star Notifications * Code * Issues 1 * Pull requests 0 * Actions * Projects 0 * Security * Insights More * Code * Issues * Pull requests * Actions * Projects * Security * Insights master Switch branches/tags [ ] Branches Tags Nothing to show {{ refName }} default View all branches Nothing to show {{ refName }} default View all tags 1 branch 0 tags Go to file Code Clone HTTPS GitHub CLI [https://github.com/b] Use Git or checkout with SVN using the web URL. [gh repo clone breule] Work fast with our official CLI. Learn more. * Open with GitHub Desktop * Download ZIP Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Go back Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Go back Launching Xcode If nothing happens, download Xcode and try again. Go back Launching Visual Studio If nothing happens, download the GitHub extension for Visual Studio and try again. Go back Latest commit @breuleux breuleux Add a gif to the README ... 232010a Apr 6, 2021 Add a gif to the README 232010a Git stats * 58 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time .github/workflows Fix Python versions and tests for CI Jan 31, 2021 jurigged v0.2.2 Mar 26, 2021 tests Improve catalogue Mar 26, 2021 .flake8 Test registry Jan 30, 2021 .gitignore Add initial working version Jan 28, 2021 LICENSE Add initial working version Jan 28, 2021 README.md Add a gif to the README Apr 6, 2021 poetry.lock Upgrade black Feb 3, 2021 pyproject.toml v0.2.2 Mar 26, 2021 View code jurigged Install Command line Troubleshooting API Recoders Caveats How it works Comparison README.md jurigged Jurigged lets you update your code while it runs. Using it is trivial: 1. jurigged your_script.py 2. Change some function or method with your favorite editor and save the file 3. Jurigged will hot patch the new function into the running script 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. demo Install pip install jurigged Command line 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 Full help: usage: jurigged [-h] [--verbose] [--watch PATH] [-m MODULE] [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 --verbose, -v Show watched files and changes as they happen --watch PATH, -w PATH Wildcard path/directory for which files to watch -m MODULE Module or module:function to run Troubleshooting First, if there's a problem, use the verbose flag (jurigged -v) to get more information. It will output a Watch statement for every file that it watches and Update/Add/Delete 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 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. API You can call jurigged.watch() to programmatically start watching for changes. This should also work within IPython or Jupyter as an alternative to the %autoreload magic. 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. Recoders 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. Caveats Jurigged works in a surprisingly large number of situations, but there are several cases where it won't work, or where problems may arise: * Functions that are already running will keep running with the existing code. Only the next invocations will use the new code. + When debugging with a breakpoint, functions currently on the stack can't be changed. + A running generator or async function won't change. + You can use reloading in addition to Jurigged if you want to be able to modify a running for loop. * Changing initializers or attribute names may cause errors on existing instances. + Jurigged modifies all existing instances of a class, but it will not re-run __init__ or rename attributes on existing instances, so you can easily end up with broken objects (new methods, but old data). * Updating the code of a decorator or a closure may or may not work. Jurigged will do its best, but it is possible that some closures will be updated but not others. * Decorators that look at/tweak function code will probably not update properly. + Wrappers that try to compile/JIT Python code won't know about jurigged and won't be able to redo their work for the new code. + They can be made to work if they set the (jurigged-specific) __conform__ attribute on the old function. __conform__ takes a reference to the function that should replace it, or None if it is to be deleted. How it works In a nutshell, jurigged works as follows: 1. Insert an import hook that collects and watches source files. 2. Parse a source file into a set of definitions. 3. Crawl through a module to find function objects and match them to definitions. + It will go through class members, follow functions' __wrapped__ and __closure__ pointers, and so on. 4. When a file is modified, re-parse it into a set of definitions and match them against the original, yielding a set of changes, additions and deletions. 5. For a change, exec the new code (with the decorators stripped out, if they haven't changed), then take the resulting function's internal __code__ pointer and shove it into the old one. If the change fails, it will be reinterpreted as a deletion of the old code followed by the addition of the new code. 6. New additions are run in the module namespace. Comparison 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: * reloading can wrap an iterator to make modifiable for loops. Jurigged cannot do that, but you can use both packages at the same time. About Hot reloading for Python Topics python hot-reloading Resources Readme License MIT License Releases No releases published Packages 0 No packages published Languages * Python 100.0% * (c) 2021 GitHub, Inc. * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can't perform that action at this time. You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.