From 8e6bec7481652993c4ffe7311f55f8fc2f115432 Mon Sep 17 00:00:00 2001 From: Taylor Barnett Date: Sat, 25 Oct 2014 15:35:28 -0500 Subject: [PATCH 01/12] Consolidating info from dev/env.rst on virtualenv --- docs/dev/virtualenvs.rst | 59 ++++++++++++++++++++++++++++++++++------ 1 file changed, 50 insertions(+), 9 deletions(-) diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index ea579e5..4b97ddd 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -1,9 +1,10 @@ Virtual Environments ==================== -A Virtual Environment, put simply, is an isolated working copy of Python which -allows you to work on a specific project without worry of affecting other -projects. +A Virtual Environment 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. For example, you can work on a project which requires Django 1.3 while also maintaining a project which requires Django 1.0. @@ -12,7 +13,8 @@ virtualenv ---------- `virtualenv `_ is a tool to create -isolated Python environments. +isolated Python environments. virtualenv creates a folder which contains all the +necessary executables to use the packages that a Python project would need. Install it via pip: @@ -23,12 +25,17 @@ Install it via pip: Basic Usage ~~~~~~~~~~~ -1. Create a virtual environment: +1. Create a virtual environment for a project: .. code-block:: console - + $ cd my_project_folder $ virtualenv venv +``virtualenv venv`` will create a folder in the current 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. + This creates a copy of Python in whichever directory you ran the command in, placing it in a folder named :file:`venv`. @@ -46,8 +53,10 @@ This will use the Python interpreter in :file:`/usr/bin/python2.7` $ source venv/bin/activate -You can then begin installing any new modules without affecting the system -default Python or other virtual environments. +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. 3. If you are done working in the virtual environment for the moment, you can deactivate it: @@ -59,12 +68,44 @@ default Python or other virtual environments. This puts you back to the system's default Python interpreter with all its installed libraries. -To delete a virtual environment, just delete its folder. +To delete a virtual environment, just delete its folder. (In this case, +it would be ``rm -rf venv``.) After a while, though, you might end up with a lot of virtual environments littered across your system, and its possible you'll forget their names or where they were placed. +Other Notes +^^^^^^^^^^^ + +Running ``virtualenv`` with the option :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. +[This is the default behavior for ``virtualenv`` 1.7 and 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 + +.. code-block:: console + + $ pip freeze > requirements.txt + +This will create a :file:`requirements.txt` file, which contains a simple +list of all the packages in the current environment, and their respective +versions. Later it will be easier for a different developer (or you, if you +need to re-create the environment) to install the same packages using the +same versions: + +.. code-block:: console + + $ 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 cb984f2b7b11fba59fd503a9f2e5876bc92ca5dc Mon Sep 17 00:00:00 2001 From: Taylor Barnett Date: Sat, 25 Oct 2014 16:00:36 -0500 Subject: [PATCH 02/12] Fixed new line so code-block shows --- docs/dev/virtualenvs.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index 4b97ddd..f320e5e 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -28,6 +28,7 @@ Basic Usage 1. Create a virtual environment for a project: .. code-block:: console + $ cd my_project_folder $ virtualenv venv From 53865c5ff7ad17f046349c8d2a5cd27973fc94d3 Mon Sep 17 00:00:00 2001 From: Taylor Barnett Date: Sat, 25 Oct 2014 17:57:19 -0500 Subject: [PATCH 03/12] Added example --- docs/dev/virtualenvs.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index f320e5e..04494a3 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -59,6 +59,12 @@ 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. +Install packages as usual, for example: + +.. code-block:: console + + $ pip install requests + 3. If you are done working in the virtual environment for the moment, you can deactivate it: @@ -77,7 +83,7 @@ littered across your system, and its possible you'll forget their names or where they were placed. Other Notes -^^^^^^^^^^^ +~~~~~~~~~~~ Running ``virtualenv`` with the option :option:`--no-site-packages` will not include the packages that are installed globally. This can be useful From c5ab9e86bec5077aac112d4bbaa8c07c3867d87b Mon Sep 17 00:00:00 2001 From: Taylor Barnett Date: Mon, 10 Nov 2014 20:01:07 -0600 Subject: [PATCH 04/12] Grammar fix --- docs/dev/virtualenvs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index 04494a3..86b9421 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -16,7 +16,7 @@ virtualenv isolated Python environments. virtualenv creates a folder which contains all the necessary executables to use the packages that a Python project would need. -Install it via pip: +Install virtualenv via pip: .. code-block:: console From e4025c1f3fee69935c94b8b651d8ef5de2e96e9e Mon Sep 17 00:00:00 2001 From: Taylor Barnett Date: Mon, 10 Nov 2014 20:02:38 -0600 Subject: [PATCH 05/12] Removed virtualenv and linked to central location --- docs/dev/env.rst | 111 ++++------------------------------------------- 1 file changed, 8 insertions(+), 103 deletions(-) diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 3e4738e..45724a7 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -218,113 +218,18 @@ Interpreter Tools ::::::::::::::::: -virtualenv +Virtual Environments ---------- -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. +A Virtual Environment 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 use the -packages that a Python project would need. An example workflow is given -below. +For example, you can work on a project which requires Django 1.3 while also +maintaining a project which requires Django 1.0. -Install virtualenv: - -.. code-block:: console - - $ pip install virtualenv - - -Create a virtual environment for a project: - -.. code-block:: console - - $ cd my_project - $ virtualenv venv - -``virtualenv venv`` will create a folder in the current 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. - -To start using the virtual environment, run: - -.. code-block:: console - - $ source 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. - -Install packages as usual: - -.. code-block:: console - - $ 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``.) - -Other Notes -^^^^^^^^^^^ - -Running ``virtualenv`` with the option :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. -[This is the default behavior for ``virtualenv`` 1.7 and 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 - -.. code-block:: console - - $ pip freeze > requirements.txt - -This will create a :file:`requirements.txt` file, which contains a simple -list of all the packages in the current environment, and their respective -versions. Later it will be easier for a different developer (or you, if you -need to re-create the environment) to install the same packages using the -same versions: - -.. code-block:: console - - $ 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 ------------------ - -`Virtualenvwrapper `_ makes -virtualenv a pleasure to use by wrapping the command line API with a nicer CLI. - -.. code-block:: console - - $ pip install virtualenvwrapper - - -Put this into your :file:`~/.bash_profile` (Linux/Mac) file: - -.. code-block:: console - - $ export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--no-site-packages' - -This will prevent your virtualenvs from relying on your (global) site packages -directory, so that they are completely separate. -[Note: This is the default behavior for ``virtualenv`` 1.7 and later] +To start using and see more information: `Virtual Environments `_ docs. Other Tools ::::::::::: From 86148b34d1996a88abfb53713bbce7dddd1fcd40 Mon Sep 17 00:00:00 2001 From: Taylor Barnett Date: Mon, 10 Nov 2014 20:10:44 -0600 Subject: [PATCH 06/12] Removed virtualenv and linked to central location --- docs/starting/install/linux.rst | 39 +++++++-------------------------- 1 file changed, 8 insertions(+), 31 deletions(-) diff --git a/docs/starting/install/linux.rst b/docs/starting/install/linux.rst index 5eaadbc..5a770b1 100644 --- a/docs/starting/install/linux.rst +++ b/docs/starting/install/linux.rst @@ -45,41 +45,18 @@ To install pip, simply open a command prompt and run $ easy_install pip -Virtualenv +Virtual Environments ---------- -After Setuptools & Pip, the next development tool that you should install is -`virtualenv `_. Use pip +A Virtual Environment 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. -.. code-block:: console +For example, you can work on a project which requires Django 1.3 while also +maintaining a project which requires Django 1.0. - $ pip install virtualenv - -The virtualenv kit provides the ability to create virtual Python environments -that do not interfere with either each other, or the main Python installation. -If you install virtualenv before you begin coding then you can get into the -habit of using it to create completely clean Python environments for each -project. This is particularly important for Web development, where each -framework and application will have many dependencies. - -To set up a new Python environment, change the working directory to where ever -you want to store the environment, and run the virtualenv utility in your -project's directory - -.. code-block:: console - - $ virtualenv venv - -To use an environment, run ``source venv/bin/activate``. Your command prompt -will change to show the active environment. Once you have finished working in -the current virtual environment, run ``deactivate`` to restore your settings -to normal. - -Each new environment automatically includes a copy of ``pip``, so that you can -setup the third-party libraries and tools that you want to use in that -environment. Put your own code within a subdirectory of the environment, -however you wish. When you no longer need a particular environment, simply -copy your code out of it, and then delete the main directory for the environment. +To start using and see more information: `Virtual Environments `_ docs. -------------------------------- From 1123507978abc1099ec904e5b16c24df50ee6504 Mon Sep 17 00:00:00 2001 From: Taylor Barnett Date: Mon, 10 Nov 2014 20:11:24 -0600 Subject: [PATCH 07/12] Removed virtualenv and linked to central location --- docs/starting/install/osx.rst | 41 +++++++---------------------------- 1 file changed, 8 insertions(+), 33 deletions(-) diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index 6c1945f..3cd9640 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -77,44 +77,19 @@ that is recommended over ``easy_install``. It is superior to ``easy_install`` in and is actively maintained. -Virtualenv +Virtual Environments ---------- -After Setuptools & Pip, the next development tool that you should install is -`virtualenv `_. Use pip +A Virtual Environment 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. -.. code-block:: console +For example, you can work on a project which requires Django 1.3 while also +maintaining a project which requires Django 1.0. - $ pip install virtualenv +To start using and see more information: `Virtual Environments `_ docs. -The virtualenv kit provides the ability to create virtual Python environments -that do not interfere with either each other, or the main Python installation. -If you install virtualenv before you begin coding then you can get into the -habit of using it to create completely clean Python environments for each -project. This is particularly important for Web development, where each -framework and application will have many dependencies. - -To set up a new Python environment, move into the directory where you would -like to store the environment, and use the ``virtualenv`` utility to create -the new environment. - -.. code-block:: console - - $ virtualenv venv - -To use an environment, run ``source venv/bin/activate``. Your command prompt -will change to show the active environment. Once you have finished working in -the current virtual environment, run ``deactivate`` to restore your settings -to normal. - -Each new environment automatically includes a copy of ``pip``, so that you can -setup the third-party libraries and tools that you want to use in that -environment. Put your own code within a subdirectory of the environment, -however you wish. When you no longer need a particular environment, simply -copy your code out of it, and then delete the main directory for the environment. - -A useful set of extensions to virtualenv is available in virtualenvwrapper, -`RTFD `_ to find out more. -------------------------------- From 34bfcfc5872340f14b200d325e5741bae69917ad Mon Sep 17 00:00:00 2001 From: Taylor Barnett Date: Mon, 10 Nov 2014 20:12:04 -0600 Subject: [PATCH 08/12] Removed virtualenv and linked to central location --- docs/starting/install/win.rst | 43 +++++++---------------------------- 1 file changed, 8 insertions(+), 35 deletions(-) diff --git a/docs/starting/install/win.rst b/docs/starting/install/win.rst index 033a213..b6b1356 100644 --- a/docs/starting/install/win.rst +++ b/docs/starting/install/win.rst @@ -66,45 +66,18 @@ To install pip, run the Python script available here: `get-pip.py `_ -Virtualenv +Virtual Environments ---------- -After Setuptools & Pip, the next development tool that you should install is -`virtualenv `_. Use pip +A Virtual Environment 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. -.. code-block:: console - - > pip install virtualenv - -The virtualenv kit provides the ability to create virtual Python environments -that do not interfere with either each other, or the main Python installation. -If you install virtualenv before you begin coding then you can get into the -habit of using it to create completely clean Python environments for each -project. This is particularly important for Web development, where each -framework and application will have many dependencies. - - -To set up a new Python environment, change the working directory to wherever -you want to store the environment, and run the virtualenv utility in your -project's directory - -.. code-block:: console - - > virtualenv venv - -To use an environment, run the :file:`activate.bat` batch file in the :file:`Scripts` -subdirectory of that environment. Your command prompt will change to show the -active environment. Once you have finished working in the current virtual -environment, run the :file:`deactivate.bat` batch file to restore your settings to -normal. - -Each new environment automatically includes a copy of ``pip`` in the -:file:`Scripts` subdirectory, so that you can setup the third-party libraries and -tools that you want to use in that environment. Put your own code within a -subdirectory of the environment, however you wish. When you no longer need a -particular environment, simply copy your code out of it, and then delete the -main directory for the environment. +For example, you can work on a project which requires Django 1.3 while also +maintaining a project which requires Django 1.0. +To start using and see more information: `Virtual Environments `_ docs. -------------------------------- From 17d0f7f005d1c2f21b2ab40a393ff8c950c16c46 Mon Sep 17 00:00:00 2001 From: Taylor Barnett Date: Wed, 19 Nov 2014 18:18:08 -0600 Subject: [PATCH 09/12] Title style fix in env.rst --- docs/dev/env.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 45724a7..bdee11c 100644 --- a/docs/dev/env.rst +++ b/docs/dev/env.rst @@ -219,7 +219,7 @@ Interpreter Tools Virtual Environments ----------- +-------------------- A Virtual Environment is a tool to keep the dependencies required by different projects in separate places, by creating virtual Python environments for them. It solves the From 8f2a936c47daeb6d7e9642d71def3ca6963741d0 Mon Sep 17 00:00:00 2001 From: Taylor Barnett Date: Wed, 19 Nov 2014 18:18:54 -0600 Subject: [PATCH 10/12] Title style fix in linux.rst --- docs/starting/install/linux.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/starting/install/linux.rst b/docs/starting/install/linux.rst index 5a770b1..a742675 100644 --- a/docs/starting/install/linux.rst +++ b/docs/starting/install/linux.rst @@ -46,7 +46,7 @@ To install pip, simply open a command prompt and run Virtual Environments ----------- +-------------------- A Virtual Environment is a tool to keep the dependencies required by different projects in separate places, by creating virtual Python environments for them. It solves the From c4947830d69141c8e239156aaf9ca43cc25ea9fc Mon Sep 17 00:00:00 2001 From: Taylor Barnett Date: Wed, 19 Nov 2014 18:19:29 -0600 Subject: [PATCH 11/12] Title style fix in osx.rst --- docs/starting/install/osx.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index 3cd9640..3b31478 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -78,7 +78,7 @@ and is actively maintained. Virtual Environments ----------- +-------------------- A Virtual Environment is a tool to keep the dependencies required by different projects in separate places, by creating virtual Python environments for them. It solves the From 9c7df812c40018682dd389995bae32a8db747d61 Mon Sep 17 00:00:00 2001 From: Taylor Barnett Date: Wed, 19 Nov 2014 18:19:51 -0600 Subject: [PATCH 12/12] Title style fix in win.rst --- docs/starting/install/win.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/starting/install/win.rst b/docs/starting/install/win.rst index b6b1356..c70fc78 100644 --- a/docs/starting/install/win.rst +++ b/docs/starting/install/win.rst @@ -67,7 +67,7 @@ To install pip, run the Python script available here: Virtual Environments ----------- +-------------------- A Virtual Environment is a tool to keep the dependencies required by different projects in separate places, by creating virtual Python environments for them. It solves the