diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 3e4738e..bdee11c 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 ::::::::::: diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index ea579e5..86b9421 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,9 +13,10 @@ 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: +Install virtualenv via pip: .. code-block:: console @@ -23,12 +25,18 @@ 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 +54,16 @@ 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. + +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: @@ -59,12 +75,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 ----------------- diff --git a/docs/starting/install/linux.rst b/docs/starting/install/linux.rst index 5eaadbc..a742675 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. -------------------------------- diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index 6c1945f..3b31478 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. -------------------------------- diff --git a/docs/starting/install/win.rst b/docs/starting/install/win.rst index 033a213..c70fc78 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. --------------------------------