envy

Why?

Ever needed to look at some code living in one of your virtual environments? And then spent a good 3 or 4 seconds typing out the path? At which point you were weary about making changes/setting breakpoints in your site-packages without first creating a backup... which then needed to be restored again after testing, and yada yada yada. This workflow is annoying and tedious.

envy is a utility that allows you to safely interact with all of the site-packages in your currently active virtualenv as if they were in your current working directory.

How?

Let's say you are working in a virtual environment for a project foo but are getting errors thrown from one of foo's depedencies-- a library called bar. The stacktrace tells us the error was thrown from baz.py. Using envy, simply run (from anywhere in your file system):

(foo)$ envy edit bar/baz.py

and you'll instantly be looking at the point-of-error from your favorite text editor!

Great, the file is open, but I shouldn't create a backup before editing a file in my site-packages? 😕

This is a good practice, but with envy, there is no need! Before launching the editor, envy first creates a backup of the package in ~/.envies/foo/bar.

Environment safe from corruption, you can confidentally throw down some pdb breakpoints, print statements, or any little hack you want! Whenever you are ready to restore the package back to it's original state, you need only run:

(foo)$ envy clean bar

And it'll be like you were never there!

Wait, there's more! 🐖 🥚

Say you maintain a library ham, as well as another project eggs that depends on ham. You want to test out some of your recent changes to ham, but are far from ready to start messing with the versioning or running setup.py install. With envy you can very quickly sync the changes from your local dev copy of ham to the one that lives eggs virtual environment like so:

(eggs)$ envy sync ham

You can also sync indivual files:

(eggs)$ envy sync ham/spam.py

Note: envy sync commands must be run from within your local copy of the package you are syncing (i.e. ham)

As with envy edit, an backup of the package's (ham's) state will be created automatically. As with before, to restore the original state:

(eggs)$ envy clean ham

No talk, straight usage 😶

Edit any file from any site-package installed in your active virtual environment:

(active-virtualenv)$ envy edit any-site-package/any-file.py

Discard any and all edits and return any-site-package to its original state:

(active-virtualenv)$ envy clean any-site-package

You can run both edit and clean from anywhere in your filesystem, as long as you are in a virtualenv that contains the package you ask it for.

Restore all edited packages to their original state:

(active-virtualenv)$ envy clean --all

Sync all local changes from random_lib to where it lives in some-virtualenv:

(some-virtualenv):dev/random_lib$ envy sync random_lib

For the time being, sync commands cannot be run as flexibly as edit and clean (they will only work when run from within the python package you wish to sync)- although it would certainly be possible to improve this in the future.

View the differences between the current copy of a package and its backed up (clean) copy:

(some-virtualenv):$ envy diff package

To drop a backup for a specific package:

(foo)$ envy reset package
dropping saved envie for package

To remove all backups for a given environment:

(foo)$ envy reset --all
dropping saved envie for package1
dropping saved envie for package2
dropping saved envie for package3

Note: envy edit uses the $EDITOR environment varible to launch a text editor-- if this is not set, simply add:

export EDITOR=your_editor_of_choice

to your .bashrc file.

Installation

$ pip install envy

For manual installation:

$ git clone https://github.com/shaunvxc/envy.git
$ cd envy
$ python setup.py install

Future work:

• add a envy diff function to compare currently applied changes with the clean, backed-up copy
• Explore the option of packaging in a diff. format (installation with curl), in order for it to be available globally (rather than on a per virtualenv basis)
• handle egg-named locally built packages? or enforce local building with pip instead?
• allow sync to be run from anywhere on filesystem (would likely require an env-var like $DEV_SRC)
• improve test coverage
• add optional virtualenv argument to allow syncing/editing to nonactive virtualenvs

Contributing

1. Fork it ( https://github.com/shaunvxc/envy/fork )
2. Create your feature branch (git checkout -b new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Run the tests (make test)
5. Push change to the branch (git push origin new-feature)
6. Create a Pull Request