diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index e6be87f89..927d213fa 100644 --- a/docs/dev/virtualenvs.rst +++ b/docs/dev/virtualenvs.rst @@ -15,8 +15,8 @@ virtualenv ---------- `virtualenv `_ is a tool to create -isolated Python environments. virtualenv creates a folder which contains all the -necessary executables to use the packages that a Python project would need. +isolated Python environments. virtualenv creates a folder which contains all the +necessary executables to use the packages that a Python project would need. Install virtualenv via pip: @@ -43,13 +43,18 @@ 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`. -You can also use a Python interpreter of your choice. +You can also use the Python interpreter of your choice (like +:file:`/usr/bin/python2.7`). .. code-block:: console $ virtualenv -p /usr/bin/python2.7 venv -This will use the Python interpreter in :file:`/usr/bin/python2.7` +or change the interpreter globally with an env variable in ``~/.bashrc``: + +.. code-block:: console + + $ export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python2.7 2. To begin using the virtual environment, it needs to be activated: @@ -57,9 +62,9 @@ This will use the Python interpreter in :file:`/usr/bin/python2.7` $ 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 +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: @@ -78,7 +83,7 @@ Install packages as usual, for example: 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. (In this case, +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 @@ -102,8 +107,8 @@ the current state of the environment packages. To do this, run 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. You can see the list of installed packages without the requirements -format using "pip list". Later it will be easier for a different developer +versions. You can see the list of installed packages without the requirements +format using "pip list". 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: @@ -143,7 +148,7 @@ To install (make sure **virtualenv** is already installed): .. code-block:: console $ pip install virtualenvwrapper-win - + In Windows, the default path for WORKON_HOME is %USERPROFILE%\Envs Basic Usage diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index f459ef99e..97baf03d8 100644 --- a/docs/starting/install/osx.rst +++ b/docs/starting/install/osx.rst @@ -3,13 +3,16 @@ Installing Python on Mac OS X ============================= +.. note:: + Check out our :ref:`guide for installing Python 3 on OS X`. + The latest version of Mac OS X, El Capitan, **comes with Python 2.7 out of the box**. -You do not need to install or configure anything else to use Python. Having -said that, I would strongly recommend that you install the tools and libraries -described in the next section before you start building Python applications -for real-world use. In particular, you should always install Setuptools, as it -makes it much easier for you to use other third-party Python libraries. +You do not need to install or configure anything else to use Python. Having said +that, I would strongly recommend that you install the tools and libraries +described in the next section before you start building Python applications for +real-world use. In particular, you should always install Setuptools, as it makes +it much easier for you to install and manage other third-party Python libraries. The version of Python that ships with OS X is great for learning but it's not good for development. The version shipped with OS X may be out of date from the @@ -30,9 +33,14 @@ minimal but unofficial package. .. note:: - If you already have Xcode installed or plan to use Homebrew, do not install - OSX-GCC-Installer. In combination, the software can cause issues that are - difficult to diagnose. + If you already have XCode installed, do not install OSX-GCC-Installer. + In combination, the software can cause issues that are difficult to + diagnose. + +.. note:: + If you perform a fresh install of XCode, you will also need to add the + commandline tools by running ``xcode-select --install`` on the terminal. + While OS X comes with a large number of UNIX utilities, those familiar with Linux systems will notice one key component missing: a decent package manager. @@ -70,7 +78,7 @@ or Python 3: This will take a minute or two. -Setuptools & Pip +Setuptools and Pip ---------------- Homebrew installs Setuptools and ``pip`` for you. @@ -81,23 +89,23 @@ software over a network (usually the Internet) with a single command capability to your own Python software with very little work. ``pip`` is a tool for easily installing and managing Python packages, -that is recommended over ``easy_install``. It is superior to ``easy_install`` in `several ways `_, +that is recommended over ``easy_install``. It is superior to ``easy_install`` +in `several ways `_, 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 -"Project X depends on version 1.x but, Project Y needs 4.x" dilemma, and keeps +A Virtual Environment (commonly referred to as a '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. For example, you can work on a project which requires Django 1.10 while also maintaining a project which requires Django 1.8. -To start using this and see more information: :ref:`Virtual Environments ` docs. - +To start using this and see more information: :ref:`Virtual Environments ` docs. -------------------------------- diff --git a/docs/starting/install3/osx.rst b/docs/starting/install3/osx.rst new file mode 100644 index 000000000..d5a33291c --- /dev/null +++ b/docs/starting/install3/osx.rst @@ -0,0 +1,116 @@ +.. _install3-osx: + +Installing Python 3 on Mac OS X +================================ + +The latest version of Mac OS X, El Capitan, **comes with Python 2.7 out of the box**. + +You do not need to install or configure anything else to use Python 2. These +instructions document the installation of Python 3. + +The version of Python that ships with OS X is great for learning but it's not +good for development. The version shipped with OS X may be out of date from the +`official current Python release `_, +which is considered the stable production version. + +Doing it Right +-------------- + +Let's install a real version of Python. + +Before installing Python, you'll need to install GCC. GCC can be obtained +by downloading `XCode `_, the smaller +`Command Line Tools `_ (must have an +Apple account) or the even smaller `OSX-GCC-Installer `_ +package. + +.. note:: + If you already have XCode installed, do not install OSX-GCC-Installer. + In combination, the software can cause issues that are difficult to + diagnose. + +.. note:: + If you perform a fresh install of XCode, you will also need to add the + commandline tools by running ``xcode-select --install`` on the terminal. + +While OS X comes with a large number of UNIX utilities, those familiar with +Linux systems will notice one key component missing: a package manager. +`Homebrew `_ fills this void. + +To `install Homebrew `_, open :file:`Terminal` or +your favorite OSX terminal emulator and run + +.. code-block:: console + + $ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" + +The script will explain what changes it will make and prompt you before the +installation begins. +Once you've installed Homebrew, insert the Homebrew directory at the top +of your :envvar:`PATH` environment variable. You can do this by adding the following +line at the bottom of your :file:`~/.profile` file + +.. code-block:: console + + export PATH=/usr/local/bin:/usr/local/sbin:$PATH + +Now, we can install Python 3: + +.. code-block:: console + + $ brew install python3 + +This will take a minute or two. + + +Pip +---------------- + +Homebrew installs ``pip3`` for you. + +``pip3`` is the alias for the Python 3 version of ``pip`` on systems with both +the Homebrew'd Python 2 and 3 installed. + +Working with Python3 +-------------------- + +At this point, you have the system Python 2.7 available, potentially the +:ref:`Homebrew version of Python 2 ` installed, and the Homebrew +version of Python 3 as well. + +.. code-block:: console + + $ python + +will launch the Python 2 interpreter. + +.. code-block:: console + + $ python3 + +will launch the Python 3 interpreter + +``pip3`` and ``pip`` will both be available. If the Homebrew version of Python +2 is not installed, they will be the same. If the Homebrew version of Python 2 +is installed then ``pip`` will point to Python 2 and ``pip3`` will point to +Python 3. + + +Virtual Environments +-------------------- + +A Virtual Environment (commonly referred to as a '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. + +For example, you can work on a project which requires Django 1.10 while also +maintaining a project which requires Django 1.8. + +To start using this and see more information: :ref:`Virtual Environments ` docs. + +-------------------------------- + +This page is a remixed version of `another guide `_, +which is available under the same license. diff --git a/docs/starting/installation.rst b/docs/starting/installation.rst index 5df0035f3..55114b21d 100644 --- a/docs/starting/installation.rst +++ b/docs/starting/installation.rst @@ -13,9 +13,10 @@ other third-party Python libraries. Installation Guides ------------------- -These guides go over the proper installation of :ref:`Python 2.7 ` -for development purposes, as well as setuptools, pip, and virtualenv setup. +These guides go over the proper installation of :ref:`Python ` +for development purposes, as well as setuptools, pip and virtualenv. -- :ref:`Mac OS X `. -- :ref:`Microsoft Windows `. -- :ref:`Linux `. +- :ref:`Python 3 on MacOS `. +- :ref:`Python 2 on MacOS `. +- :ref:`Python 2 on Microsoft Windows `. +- :ref:`Python 2 on Ubuntu Linux `.