diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index 11f924882..344f56971 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -1,7 +1,8 @@ .. _virtualenvironments-ref: +############################# Pipenv & Virtual Environments -============================= +############################# .. image:: /_static/photos/35294660055_42c02b2316_k_d.jpg @@ -15,12 +16,13 @@ presented here is most directly applicable to the development and deployment of network services (including web applications), but is also very well suited to managing development and testing environments for any kind of project. -.. Note:: This guide is written for Python 3, however, these instructions +.. note:: This guide is written for Python 3, however, these instructions should work fine on Python 2.7—if you are still using it, for some reason. +********************************* Make sure you've got Python & pip ---------------------------------- +********************************* Before you go any further, make sure you have Python and that it's available from your command line. You can check this by simply running: @@ -33,13 +35,14 @@ You should get some output like ``3.6.2``. If you do not have Python, please install the latest 3.x version from `python.org`_ or refer to the `Installing Python`_ section of this guide. -.. Note:: If you're newcomer and you get an error like this: +.. note:: + If you're newcomer and you get an error like this: .. code-block:: python >>> python Traceback (most recent call last): - File "", line 1, in + File "", line 1, in NameError: name 'python' is not defined It's because this command is intended to be run in a *shell* (also called @@ -65,8 +68,9 @@ using your OS package manager, you may have to `install pip =2.5 (from requests) - Using cached idna-2.6-py2.py3-none-any.whl + Using cached idna-2.6-py2.py3-none-any.whl Collecting urllib3<1.23,>=1.21.1 (from requests) - Using cached urllib3-1.22-py2.py3-none-any.whl + Using cached urllib3-1.22-py2.py3-none-any.whl Collecting chardet<3.1.0,>=3.0.2 (from requests) - Using cached chardet-3.0.4-py2.py3-none-any.whl + Using cached chardet-3.0.4-py2.py3-none-any.whl Collecting certifi>=2017.4.17 (from requests) - Using cached certifi-2017.7.27.1-py2.py3-none-any.whl + Using cached certifi-2017.7.27.1-py2.py3-none-any.whl Installing collected packages: idna, urllib3, chardet, certifi, requests Successfully installed certifi-2017.7.27.1 chardet-3.0.4 idna-2.6 requests-2.18.4 urllib3-1.22 @@ -158,9 +163,8 @@ when you share your project with others. You should get output similar to this .. _Requests: https://python-requests.org - Using installed packages ------------------------- +======================== Now that Requests is installed you can create a simple ``main.py`` file to use it: @@ -189,16 +193,15 @@ Using ``$ pipenv run`` ensures that your installed packages are available to your script. It's also possible to spawn a new shell that ensures all commands have access to your installed packages with ``$ pipenv shell``. - Next steps ----------- +========== Congratulations, you now know how to install and use Python packages! ✨ 🍰 ✨ - +*********************** Lower level: virtualenv -======================= +*********************** `virtualenv `_ is a tool to create isolated Python environments. virtualenv creates a folder which contains all the @@ -210,23 +213,23 @@ Install virtualenv via pip: .. code-block:: console - $ pip install virtualenv + $ pip install virtualenv Test your installation .. code-block:: console - $ virtualenv --version + $ virtualenv --version Basic Usage -~~~~~~~~~~~ +=========== 1. Create a virtual environment for a project: .. code-block:: console - $ cd my_project_folder - $ virtualenv my_project + $ cd my_project_folder + $ virtualenv my_project ``virtualenv my_project`` will create a folder in the current directory which will contain the Python executable files, and a copy of the ``pip`` library which you @@ -242,19 +245,19 @@ You can also use the Python interpreter of your choice (like .. code-block:: console - $ virtualenv -p /usr/bin/python2.7 my_project + $ virtualenv -p /usr/bin/python2.7 my_project or change the interpreter globally with an env variable in ``~/.bashrc``: .. code-block:: console - $ export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python2.7 + $ export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python2.7 2. To begin using the virtual environment, it needs to be activated: .. code-block:: console - $ source my_project/bin/activate + $ source my_project/bin/activate The name of the current virtual environment will now appear on the left of the prompt (e.g. ``(my_project)Your-Computer:your_project UserName$)`` to let you know @@ -272,7 +275,7 @@ Install packages as usual, for example: .. code-block:: console - $ deactivate + $ deactivate This puts you back to the system's default Python interpreter with all its installed libraries. @@ -285,7 +288,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 ``--no-site-packages`` will not include the packages that are installed globally. This can be useful @@ -318,8 +321,10 @@ control by adding it to the ignore list (see :ref:`Version Control Ignores`_ provides a set of commands which makes working with virtual environments much @@ -329,9 +334,9 @@ To install (make sure **virtualenv** is already installed): .. code-block:: console - $ pip install virtualenvwrapper - $ export WORKON_HOME=~/Envs - $ source /usr/local/bin/virtualenvwrapper.sh + $ pip install virtualenvwrapper + $ export WORKON_HOME=~/Envs + $ source /usr/local/bin/virtualenvwrapper.sh (`Full virtualenvwrapper install instructions `_.) @@ -341,18 +346,18 @@ To install (make sure **virtualenv** is already installed): .. code-block:: console - $ pip install virtualenvwrapper-win + $ pip install virtualenvwrapper-win In Windows, the default path for WORKON_HOME is %USERPROFILE%\Envs Basic Usage -~~~~~~~~~~~ +=========== 1. Create a virtual environment: .. code-block:: console - $ mkvirtualenv my_project + $ mkvirtualenv my_project This creates the :file:`my_project` folder inside :file:`~/Envs`. @@ -360,7 +365,7 @@ This creates the :file:`my_project` folder inside :file:`~/Envs`. .. code-block:: console - $ workon my_project + $ workon my_project Alternatively, you can make a project, which creates the virtual environment, and also a project directory inside ``$WORKON_HOME``, which is ``cd`` -ed into @@ -368,7 +373,7 @@ when you ``workon myproject``. .. code-block:: console - $ mkproject myproject + $ mkproject myproject **virtualenvwrapper** provides tab-completion on environment names. It really helps when you have a lot of environments and have trouble remembering their @@ -381,16 +386,16 @@ can quickly switch between environments. .. code-block:: console - $ deactivate + $ deactivate 4. To delete: .. code-block:: console - $ rmvirtualenv venv + $ rmvirtualenv venv Other useful commands -~~~~~~~~~~~~~~~~~~~~~ +===================== ``lsvirtualenv`` List all of the environments. @@ -407,14 +412,19 @@ Other useful commands `Full list of virtualenvwrapper commands `_. + +****************** virtualenv-burrito ------------------- +****************** With `virtualenv-burrito `_, you can have a working virtualenv + virtualenvwrapper environment in a single command. + +******* autoenv -------- +******* + When you ``cd`` into a directory containing a :file:`.env`, `autoenv `_ automagically activates the environment. @@ -422,11 +432,11 @@ Install it on Mac OS X using ``brew``: .. code-block:: console - $ brew install autoenv + $ brew install autoenv And on Linux: .. code-block:: console - $ git clone git://github.com/kennethreitz/autoenv.git ~/.autoenv - $ echo 'source ~/.autoenv/activate.sh' >> ~/.bashrc + $ git clone git://github.com/kennethreitz/autoenv.git ~/.autoenv + $ echo 'source ~/.autoenv/activate.sh' >> ~/.bashrc