From cfb196037d5a2cc2d2721ba94eeb5a5f92645ab6 Mon Sep 17 00:00:00 2001 From: Jens Hedegaard Nielsen Date: Fri, 15 Jul 2016 16:51:06 +0100 Subject: [PATCH 1/7] Document the use of pythonw in the docs --- src/_macosx.m | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/_macosx.m b/src/_macosx.m index 2051aac8d646..caed23987a4f 100644 --- a/src/_macosx.m +++ b/src/_macosx.m @@ -3092,8 +3092,9 @@ static bool verify_framework(void) "framework. See the Python documentation for more information on " "installing Python as a framework on Mac OS X. Please either reinstall " "Python as a framework, or try one of the other backends. If you are " - "Working with Matplotlib in a virtual enviroment see 'Working with " - "Matplotlib in Virtual environments' in the Matplotlib FAQ"); + "using (Ana)Conda please install python.app and replace the use of 'python' " + "with 'pythonw'. If you are working with Matplotlib in a virtual enviroment " + "see 'Working with Matplotlib in Virtual environments' in the Matplotlib FAQ"); return false; } From 9e09425abacbfb21d58fd5c18f5a3aa69cbf91e3 Mon Sep 17 00:00:00 2001 From: Jens Hedegaard Nielsen Date: Fri, 15 Jul 2016 17:28:57 +0100 Subject: [PATCH 2/7] wip update virtualenv faq --- doc/faq/virtualenv_faq.rst | 98 ++++++++++++++++++++++++-------------- 1 file changed, 61 insertions(+), 37 deletions(-) diff --git a/doc/faq/virtualenv_faq.rst b/doc/faq/virtualenv_faq.rst index 8ec25decc15e..6861fb861624 100644 --- a/doc/faq/virtualenv_faq.rst +++ b/doc/faq/virtualenv_faq.rst @@ -40,6 +40,7 @@ exist. Some of these are given here: * The ``TKAgg`` backend doesn't require any external dependencies and is normally always available. * The ``QT4`` framework ``PySide`` is pip installable. +* ``PYQT5`` is pip installable on Python 3.5. * The upcoming `WX Phoenix `_ toolkit is ``pip`` installable. @@ -59,8 +60,8 @@ I.e. to use PyQt5, you should symlink ``PyQt5`` and ``sip`` from your system site packages directory into the environment taking care that the environment and the systemwide install use the same python version. -OSX -=== +OSX Framework builds +==================== Short version ------------- @@ -76,15 +77,35 @@ Long version ------------ On OSX, two different types of Python Builds exist: a regular build and a -framework build. In order to interact correctly with OSX through some +framework build. In order to interact correctly with OSX through the native GUI frameworks you need a framework build of Python. -At the time of writing the ``macosx``, ``WX`` and ``WXAgg`` backends require a -framework build to function correctly. Unfortunately virtualenv creates a non -framework build even if created from a framework build of Python. Conda -environments are framework builds. From -Matplotlib 1.5 onwards the ``macosx`` backend checks that a framework build is -available and fails if a non framework build is found. -WX has a similar check build in. +At the time of writing the ``macosx`` and ``WXAgg`` backends require a +framework build to function correctly. This can result in issues for +a python installation not build as a framework. In virtual envs and when +using (Ana)Conda. From Matplotlib 1.5 onwards the ``macosx`` backend +checks that a framework build is available and fails if a non framework +build is found. WX has a similar check build in. + +Without this check a partially functional figure is created. +Among the issues with it is that it is produced in the background and +cannot be put in front of any other window. + + +OSX Conda +========= + +The default python provided in (Ana)Conda is not a framework +build. However, the Conda developers have made it easy to install +a framework build in both the main environment and in Conda envs. +To use this install python.app ``conda install python.app`` and +use ``pythonw`` rather than ``python`` + + +OSX virtualenv +============== + +Unfortunately virtualenv creates a non +framework build even if created from a framework build of Python. The issue has been reported on the virtualenv bug tracker `here `__ and `here @@ -92,12 +113,37 @@ The issue has been reported on the virtualenv bug tracker `here Until this is fixed, one of the following workarounds must be used: +``PYTHONHOME`` Function +----------------------- + +The best known work around is to use the non +virtualenv python along with the PYTHONHOME environment variable. +This can be done by defining a function in your ``.bashrc`` using + +.. code:: bash + + function frameworkpython { + if [[ ! -z "$VIRTUAL_ENV" ]]; then + PYTHONHOME=$VIRTUAL_ENV /usr/local/bin/python "$@" + else + /usr/local/bin/python "$@" + fi + } + +This function can then be used in all of your virtualenvs without having to +fix every single one of them. + +With this in place you can run ``frameworkpython`` to get an interactive +framework build within the virtualenv. To run a script you can do +``frameworkpython test.py`` where ``test.py`` is a script that requires a +framework build. To run an interactive ``IPython`` session with the framework +build within the virtual environment you can do ``frameworkpython -m IPython`` + ``PYTHONHOME`` Script ^^^^^^^^^^^^^^^^^^^^^ -The best known workaround, -borrowed from the `WX wiki -`_, is to use the non +An alternative work around borrowed from the `WX wiki +`_, is to use the non virtualenv python along with the PYTHONHOME environment variable. This can be implemented in a script as below. To use this modify ``PYVER`` and ``PATHTOPYTHON`` and put the script in the virtualenv bin directory i.e. @@ -119,30 +165,8 @@ implemented in a script as below. To use this modify ``PYVER`` and export PYTHONHOME=$ENV exec $PYTHON "$@" - -With this in place you can run ``frameworkpython`` to get an interactive -framework build within the virtualenv. To run a script you can do -``frameworkpython test.py`` where ``test.py`` is a script that requires a -framework build. To run an interactive ``IPython`` session with the framework -build within the virtual environment you can do ``frameworkpython -m IPython`` - -``PYTHONHOME`` Function -^^^^^^^^^^^^^^^^^^^^^^^ - -Alternatively you can define a function in your ``.bashrc`` using - -.. code:: bash - - function frameworkpython { - if [[ ! -z "$VIRTUAL_ENV" ]]; then - PYTHONHOME=$VIRTUAL_ENV /usr/local/bin/python "$@" - else - /usr/local/bin/python "$@" - fi - } - -This function can then be used in all of your virtualenvs without having to -fix every single one of them. +With this in place you can run ``frameworkpython`` as above but will need to add this script +to every virtualenv PythonW Compiler ^^^^^^^^^^^^^^^^ From 92cc18ea91efa2a6e8f3036dd273af51bfda9335 Mon Sep 17 00:00:00 2001 From: Jens Hedegaard Nielsen Date: Sun, 4 Sep 2016 18:31:20 +0100 Subject: [PATCH 3/7] refresh docs --- doc/faq/index.rst | 1 + doc/faq/osx_framework.rst | 129 +++++++++++++++++++++++++++++++++++++ doc/faq/virtualenv_faq.rst | 120 ++-------------------------------- 3 files changed, 134 insertions(+), 116 deletions(-) create mode 100644 doc/faq/osx_framework.rst diff --git a/doc/faq/index.rst b/doc/faq/index.rst index 4d2a511ecea1..492491efca52 100644 --- a/doc/faq/index.rst +++ b/doc/faq/index.rst @@ -20,3 +20,4 @@ The Matplotlib FAQ troubleshooting_faq.rst environment_variables_faq.rst virtualenv_faq.rst + osx_framework.rst diff --git a/doc/faq/osx_framework.rst b/doc/faq/osx_framework.rst new file mode 100644 index 000000000000..6deccf36013a --- /dev/null +++ b/doc/faq/osx_framework.rst @@ -0,0 +1,129 @@ +.. _osxframework-faq: + +****************************** +Working with Matplotlib on OSX +****************************** + +.. contents:: + :backlinks: none + + +.. _osxframework_introduction: + +Introduction +============ + +On OSX, two different types of Python Builds exist: a regular build and a +framework build. In order to interact correctly with OSX through the native +GUI frameworks you need a framework build of Python. +At the time of writing the ``macosx`` and ``WXAgg`` backends require a +framework build to function correctly. This can result in issues for +a python installation not build as a framework andmay also happen in +virtual envs and when using (Ana)Conda. +From Matplotlib 1.5 onwards the ``macosx`` backend +checks that a framework build is available and fails if a non framework +build is found. WX has a similar check build in. + +Without this check a partially functional figure is created. +Among the issues with it is that it is produced in the background and +cannot be put in front of any other window. Several solutions and work +arounds exist see below. + +Short version +============= + +VirtualEnv +---------- + +If you are on Python 3, use +`venv `_ +instead of `virtualenv `_:: + + python -m venv my-virtualenv + source my-virtualenv/bin/activate + +Otherwise you will need one of the workarounds below. + +Conda +----- + +The default python provided in (Ana)Conda is not a framework +build. However, the Conda developers have made it easy to install +a framework build in both the main environment and in Conda envs. +To use this install python.app ``conda install python.app`` and +use ``pythonw`` rather than ``python`` + + +Long version +============ + +Unfortunately virtualenv creates a non +framework build even if created from a framework build of Python. + +The issue has been reported on the virtualenv bug tracker `here +`__ and `here +`__ + +Until this is fixed, one of the following workarounds can be used: + +``PYTHONHOME`` Function +----------------------- + +The best known work around is to use the non +virtualenv python along with the PYTHONHOME environment variable. +This can be done by defining a function in your ``.bashrc`` using + +.. code:: bash + + function frameworkpython { + if [[ ! -z "$VIRTUAL_ENV" ]]; then + PYTHONHOME=$VIRTUAL_ENV /usr/local/bin/python "$@" + else + /usr/local/bin/python "$@" + fi + } + +This function can then be used in all of your virtualenvs without having to +fix every single one of them. + +With this in place you can run ``frameworkpython`` to get an interactive +framework build within the virtualenv. To run a script you can do +``frameworkpython test.py`` where ``test.py`` is a script that requires a +framework build. To run an interactive ``IPython`` session with the framework +build within the virtual environment you can do ``frameworkpython -m IPython`` + +``PYTHONHOME`` Script +^^^^^^^^^^^^^^^^^^^^^ + +An alternative work around borrowed from the `WX wiki +`_, is to use the non +virtualenv python along with the PYTHONHOME environment variable. This can be +implemented in a script as below. To use this modify ``PYVER`` and +``PATHTOPYTHON`` and put the script in the virtualenv bin directory i.e. +``PATHTOVENV/bin/frameworkpython`` + +.. code:: bash + + #!/bin/bash + + # what real Python executable to use + PYVER=2.7 + PATHTOPYTHON=/usr/local/bin/ + PYTHON=${PATHTOPYTHON}python${PYVER} + + # find the root of the virtualenv, it should be the parent of the dir this script is in + ENV=`$PYTHON -c "import os; print(os.path.abspath(os.path.join(os.path.dirname(\"$0\"), '..')))"` + + # now run Python with the virtualenv set as Python's HOME + export PYTHONHOME=$ENV + exec $PYTHON "$@" + +With this in place you can run ``frameworkpython`` as above but will need to add this script +to every virtualenv + +PythonW Compiler +^^^^^^^^^^^^^^^^ + +In addition +`virtualenv-pythonw-osx `_ +provides an alternative workaround which may be used to solve the issue. diff --git a/doc/faq/virtualenv_faq.rst b/doc/faq/virtualenv_faq.rst index 6861fb861624..ae91f9e6efc7 100644 --- a/doc/faq/virtualenv_faq.rst +++ b/doc/faq/virtualenv_faq.rst @@ -8,7 +8,7 @@ Working with Matplotlib in Virtual environments :backlinks: none -.. _introduction: +.. _virtualenv_introduction: Introduction ============ @@ -25,6 +25,9 @@ If you only use the ``IPython/Jupyter Notebook``'s ``inline`` and ``notebook`` backends and non interactive backends you should not have any issues and can ignore everything below. +If you are using Matplotlib on OSX you may also want to consider the +:ref:`OSX framework FAQ `. + GUI Frameworks ============== @@ -59,118 +62,3 @@ Alternatively, you can manually symlink the GUI frameworks into the environment. I.e. to use PyQt5, you should symlink ``PyQt5`` and ``sip`` from your system site packages directory into the environment taking care that the environment and the systemwide install use the same python version. - -OSX Framework builds -==================== - -Short version -------------- - -If you are on Python 3, use ``venv`` instead of ``virtualenv``:: - - python -m venv my-virtualenv - source my-virtualenv/bin/activate - -Otherwise you will need one of the workarounds below. - -Long version ------------- - -On OSX, two different types of Python Builds exist: a regular build and a -framework build. In order to interact correctly with OSX through the native -GUI frameworks you need a framework build of Python. -At the time of writing the ``macosx`` and ``WXAgg`` backends require a -framework build to function correctly. This can result in issues for -a python installation not build as a framework. In virtual envs and when -using (Ana)Conda. From Matplotlib 1.5 onwards the ``macosx`` backend -checks that a framework build is available and fails if a non framework -build is found. WX has a similar check build in. - -Without this check a partially functional figure is created. -Among the issues with it is that it is produced in the background and -cannot be put in front of any other window. - - -OSX Conda -========= - -The default python provided in (Ana)Conda is not a framework -build. However, the Conda developers have made it easy to install -a framework build in both the main environment and in Conda envs. -To use this install python.app ``conda install python.app`` and -use ``pythonw`` rather than ``python`` - - -OSX virtualenv -============== - -Unfortunately virtualenv creates a non -framework build even if created from a framework build of Python. - -The issue has been reported on the virtualenv bug tracker `here -`__ and `here -`__ - -Until this is fixed, one of the following workarounds must be used: - -``PYTHONHOME`` Function ------------------------ - -The best known work around is to use the non -virtualenv python along with the PYTHONHOME environment variable. -This can be done by defining a function in your ``.bashrc`` using - -.. code:: bash - - function frameworkpython { - if [[ ! -z "$VIRTUAL_ENV" ]]; then - PYTHONHOME=$VIRTUAL_ENV /usr/local/bin/python "$@" - else - /usr/local/bin/python "$@" - fi - } - -This function can then be used in all of your virtualenvs without having to -fix every single one of them. - -With this in place you can run ``frameworkpython`` to get an interactive -framework build within the virtualenv. To run a script you can do -``frameworkpython test.py`` where ``test.py`` is a script that requires a -framework build. To run an interactive ``IPython`` session with the framework -build within the virtual environment you can do ``frameworkpython -m IPython`` - -``PYTHONHOME`` Script -^^^^^^^^^^^^^^^^^^^^^ - -An alternative work around borrowed from the `WX wiki -`_, is to use the non -virtualenv python along with the PYTHONHOME environment variable. This can be -implemented in a script as below. To use this modify ``PYVER`` and -``PATHTOPYTHON`` and put the script in the virtualenv bin directory i.e. -``PATHTOVENV/bin/frameworkpython`` - -.. code:: bash - - #!/bin/bash - - # what real Python executable to use - PYVER=2.7 - PATHTOPYTHON=/usr/local/bin/ - PYTHON=${PATHTOPYTHON}python${PYVER} - - # find the root of the virtualenv, it should be the parent of the dir this script is in - ENV=`$PYTHON -c "import os; print(os.path.abspath(os.path.join(os.path.dirname(\"$0\"), '..')))"` - - # now run Python with the virtualenv set as Python's HOME - export PYTHONHOME=$ENV - exec $PYTHON "$@" - -With this in place you can run ``frameworkpython`` as above but will need to add this script -to every virtualenv - -PythonW Compiler -^^^^^^^^^^^^^^^^ - -In addition -`virtualenv-pythonw-osx `_ -provides an alternative workaround which may be used to solve the issue. From fea3d542ad57d41fe4ec9283ac04fa77bf8eb4bc Mon Sep 17 00:00:00 2001 From: Jens Hedegaard Nielsen Date: Sun, 4 Sep 2016 18:32:01 +0100 Subject: [PATCH 4/7] point to osx faq rather than venv faq --- src/_macosx.m | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/_macosx.m b/src/_macosx.m index caed23987a4f..ad0cd14acddb 100644 --- a/src/_macosx.m +++ b/src/_macosx.m @@ -3093,8 +3093,8 @@ static bool verify_framework(void) "installing Python as a framework on Mac OS X. Please either reinstall " "Python as a framework, or try one of the other backends. If you are " "using (Ana)Conda please install python.app and replace the use of 'python' " - "with 'pythonw'. If you are working with Matplotlib in a virtual enviroment " - "see 'Working with Matplotlib in Virtual environments' in the Matplotlib FAQ"); + "with 'pythonw'. See 'Working with Matplotlib on OSX' " + "in the Matplotlib FAQ for more information."); return false; } From c2239904fbfa86a3a8ebf455aba5c6e9b37ae886 Mon Sep 17 00:00:00 2001 From: Jens Hedegaard Nielsen Date: Sun, 4 Sep 2016 18:38:30 +0100 Subject: [PATCH 5/7] Typo --- doc/faq/osx_framework.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/faq/osx_framework.rst b/doc/faq/osx_framework.rst index 6deccf36013a..a95d0744243e 100644 --- a/doc/faq/osx_framework.rst +++ b/doc/faq/osx_framework.rst @@ -18,7 +18,7 @@ framework build. In order to interact correctly with OSX through the native GUI frameworks you need a framework build of Python. At the time of writing the ``macosx`` and ``WXAgg`` backends require a framework build to function correctly. This can result in issues for -a python installation not build as a framework andmay also happen in +a python installation not build as a framework and may also happen in virtual envs and when using (Ana)Conda. From Matplotlib 1.5 onwards the ``macosx`` backend checks that a framework build is available and fails if a non framework From fc4744d1fc3914d86c78285765a45d3e1c026da4 Mon Sep 17 00:00:00 2001 From: Jens Hedegaard Nielsen Date: Mon, 5 Sep 2016 09:05:05 +0100 Subject: [PATCH 6/7] Remove mention of wx phoenix. We will readd it when there is an official release --- doc/faq/virtualenv_faq.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/doc/faq/virtualenv_faq.rst b/doc/faq/virtualenv_faq.rst index ae91f9e6efc7..094c3ca3432e 100644 --- a/doc/faq/virtualenv_faq.rst +++ b/doc/faq/virtualenv_faq.rst @@ -44,8 +44,6 @@ exist. Some of these are given here: normally always available. * The ``QT4`` framework ``PySide`` is pip installable. * ``PYQT5`` is pip installable on Python 3.5. -* The upcoming `WX Phoenix `_ toolkit - is ``pip`` installable. Other frameworks are harder to install into a virtual environment. There are at least two possible ways to get access to these in a virtual environment. From 00f7ab545231e86f5f651e97df09139b167c8136 Mon Sep 17 00:00:00 2001 From: Jens Hedegaard Nielsen Date: Mon, 5 Sep 2016 20:04:16 +0100 Subject: [PATCH 7/7] Add ref in long version to short version --- doc/faq/osx_framework.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/faq/osx_framework.rst b/doc/faq/osx_framework.rst index a95d0744243e..9953f1349768 100644 --- a/doc/faq/osx_framework.rst +++ b/doc/faq/osx_framework.rst @@ -59,6 +59,7 @@ Long version Unfortunately virtualenv creates a non framework build even if created from a framework build of Python. +As documented above you can use venv as an alternative on Python 3. The issue has been reported on the virtualenv bug tracker `here `__ and `here