From e03d247d2974464c161f64202181107a9d048eb8 Mon Sep 17 00:00:00 2001 From: George Gritsouk Date: Fri, 30 Dec 2011 02:08:13 -0500 Subject: [PATCH 1/3] Expanded the virtualenv section with an example workflow. --- docs/starting/dev-env.rst | 81 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) diff --git a/docs/starting/dev-env.rst b/docs/starting/dev-env.rst index b1f249846..c87a6d01c 100644 --- a/docs/starting/dev-env.rst +++ b/docs/starting/dev-env.rst @@ -97,6 +97,87 @@ virtualenv Virtualenv is a tool to keep the dependencies required by different projects in separate places, by creating virtual Python environments for them. It solves the "Project X depends on version 1.x but, Project Y needs 4.x" dilemma and keeps your global site-packages directory clean and manageable. +`virtualenv `_ creates +a folder which contains all the necessary executables to contain the +packages that a Python project would need. An example workflow: + +Install virtualenv: + +:: + + $ pip install virtualenv + +or, depending on what's available: + +:: + + $ easy_install virtualenv + +Create a virtual environment for a project: + +:: + + $ cd my_project + $ virtualenv venv + +``virtualenv venv`` will create a folder in the currect directory +which will contain the Python executable files, and a copy of the ``pip`` +library which you can use to install other packages. The name of the +virtual environment (in this case, it was ``venv``) can be anything; +omitting the name will place the files in the current directory instead. + +In order the start using the virtual environment, run + +:: + + $ source venv/bin/activate + +or + +:: + + $ . venv/bin/activate + +The name of the current virtual environment will now appear on the left +of the prompt (e.g. ``(venv)Your-Computer:your_project UserName$``) to +let you know that it's active. From now on, any package that you install +using ``pip`` will be placed in the venv folder, isolated from the global +Python installation. + +To stop using an environment simply type ``deactivate``. To remove the +environment, just remove the directory it was installed into. (In this +case, it would be ``rm -rf venv``. + +Other Notes +~~~~~~~~~~~ + +Running ``virtualenv`` with the option ``--no-site-packages`` will not +include the packages that are installed globally. This can be useful +for keeping the package list clean in case it needs to be accessed later. + +In order to keep your environment consistent, it's a good idea to "freeze" +the current state of the environment packages. To do this, run + +:: + + pip freeze > requirements.txt + +This will create a ``requirements.txt`` file, which contains a simple +list of all the packages in the current environment, and their respective +versions. Later, when a different developer (or you, if you need to re- +create the environment) can install the same packages, with the same +versions by running + +:: + + pip install -r requirements.txt + +This can help ensure consistency across installations, across deployments, +and across developers. + +Lastly, remember to exclude the virtual environment folder from source +control by adding it to the ignore list. + virtualenvwrapper ----------------- From 00e76557b07bb80f6a8e4c0cfe7b1ed80d701a7f Mon Sep 17 00:00:00 2001 From: George Gritsouk Date: Fri, 30 Dec 2011 02:11:47 -0500 Subject: [PATCH 2/3] Fixed a missing bracket, added a small chunk to the example. --- docs/starting/dev-env.rst | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/starting/dev-env.rst b/docs/starting/dev-env.rst index c87a6d01c..c3e3108c3 100644 --- a/docs/starting/dev-env.rst +++ b/docs/starting/dev-env.rst @@ -99,21 +99,21 @@ It solves the "Project X depends on version 1.x but, Project Y needs 4.x" dilemm `virtualenv `_ creates a folder which contains all the necessary executables to contain the -packages that a Python project would need. An example workflow: +packages that a Python project would need. An example workflow is given. -Install virtualenv: +Install virtualenv :: $ pip install virtualenv -or, depending on what's available: +or, depending on what's available :: $ easy_install virtualenv -Create a virtual environment for a project: +Create a virtual environment for a project :: @@ -142,11 +142,14 @@ The name of the current virtual environment will now appear on the left of the prompt (e.g. ``(venv)Your-Computer:your_project UserName$``) to let you know that it's active. From now on, any package that you install using ``pip`` will be placed in the venv folder, isolated from the global -Python installation. +Python installation. Install packages as usual. + +:: + $ pip install requests To stop using an environment simply type ``deactivate``. To remove the environment, just remove the directory it was installed into. (In this -case, it would be ``rm -rf venv``. +case, it would be ``rm -rf venv``). Other Notes ~~~~~~~~~~~ From 4043a5e18c1804b87ac681a59d313350853c6897 Mon Sep 17 00:00:00 2001 From: George Gritsouk Date: Fri, 30 Dec 2011 02:15:22 -0500 Subject: [PATCH 3/3] Added a missing space. --- docs/starting/dev-env.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/starting/dev-env.rst b/docs/starting/dev-env.rst index c3e3108c3..20a79045d 100644 --- a/docs/starting/dev-env.rst +++ b/docs/starting/dev-env.rst @@ -145,6 +145,7 @@ using ``pip`` will be placed in the venv folder, isolated from the global Python installation. Install packages as usual. :: + $ pip install requests To stop using an environment simply type ``deactivate``. To remove the