Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 92cc18e

Browse files
jenshnielsenjenshnielsen
committed
refresh docs
1 parent 9e09425 commit 92cc18e

3 files changed

Lines changed: 134 additions & 116 deletions

File tree

‎doc/faq/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,4 @@ The Matplotlib FAQ
2020
troubleshooting_faq.rst
2121
environment_variables_faq.rst
2222
virtualenv_faq.rst
23+
osx_framework.rst

‎doc/faq/osx_framework.rst‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
.. _osxframework-faq:
2+
3+
******************************
4+
Working with Matplotlib on OSX
5+
******************************
6+
7+
.. contents::
8+
:backlinks: none
9+
10+
11+
.. _osxframework_introduction:
12+
13+
Introduction
14+
============
15+
16+
On OSX, two different types of Python Builds exist: a regular build and a
17+
framework build. In order to interact correctly with OSX through the native
18+
GUI frameworks you need a framework build of Python.
19+
At the time of writing the ``macosx`` and ``WXAgg`` backends require a
20+
framework build to function correctly. This can result in issues for
21+
a python installation not build as a framework andmay also happen in
22+
virtual envs and when using (Ana)Conda.
23+
From Matplotlib 1.5 onwards the ``macosx`` backend
24+
checks that a framework build is available and fails if a non framework
25+
build is found. WX has a similar check build in.
26+
27+
Without this check a partially functional figure is created.
28+
Among the issues with it is that it is produced in the background and
29+
cannot be put in front of any other window. Several solutions and work
30+
arounds exist see below.
31+
32+
Short version
33+
=============
34+
35+
VirtualEnv
36+
----------
37+
38+
If you are on Python 3, use
39+
`venv <https://docs.python.org/3/library/venv.html>`_
40+
instead of `virtualenv <https://virtualenv.pypa.io/en/latest/>`_::
41+
42+
python -m venv my-virtualenv
43+
source my-virtualenv/bin/activate
44+
45+
Otherwise you will need one of the workarounds below.
46+
47+
Conda
48+
-----
49+
50+
The default python provided in (Ana)Conda is not a framework
51+
build. However, the Conda developers have made it easy to install
52+
a framework build in both the main environment and in Conda envs.
53+
To use this install python.app ``conda install python.app`` and
54+
use ``pythonw`` rather than ``python``
55+
56+
57+
Long version
58+
============
59+
60+
Unfortunately virtualenv creates a non
61+
framework build even if created from a framework build of Python.
62+
63+
The issue has been reported on the virtualenv bug tracker `here
64+
<https://github.com/pypa/virtualenv/issues/54>`__ and `here
65+
<https://github.com/pypa/virtualenv/issues/609>`__
66+
67+
Until this is fixed, one of the following workarounds can be used:
68+
69+
``PYTHONHOME`` Function
70+
-----------------------
71+
72+
The best known work around is to use the non
73+
virtualenv python along with the PYTHONHOME environment variable.
74+
This can be done by defining a function in your ``.bashrc`` using
75+
76+
.. code:: bash
77+
78+
function frameworkpython {
79+
if [[ ! -z "$VIRTUAL_ENV" ]]; then
80+
PYTHONHOME=$VIRTUAL_ENV /usr/local/bin/python "$@"
81+
else
82+
/usr/local/bin/python "$@"
83+
fi
84+
}
85+
86+
This function can then be used in all of your virtualenvs without having to
87+
fix every single one of them.
88+
89+
With this in place you can run ``frameworkpython`` to get an interactive
90+
framework build within the virtualenv. To run a script you can do
91+
``frameworkpython test.py`` where ``test.py`` is a script that requires a
92+
framework build. To run an interactive ``IPython`` session with the framework
93+
build within the virtual environment you can do ``frameworkpython -m IPython``
94+
95+
``PYTHONHOME`` Script
96+
^^^^^^^^^^^^^^^^^^^^^
97+
98+
An alternative work around borrowed from the `WX wiki
99+
<http://wiki.wxpython.org/wxPythonVirtualenvOnMac>`_, is to use the non
100+
virtualenv python along with the PYTHONHOME environment variable. This can be
101+
implemented in a script as below. To use this modify ``PYVER`` and
102+
``PATHTOPYTHON`` and put the script in the virtualenv bin directory i.e.
103+
``PATHTOVENV/bin/frameworkpython``
104+
105+
.. code:: bash
106+
107+
#!/bin/bash
108+
109+
# what real Python executable to use
110+
PYVER=2.7
111+
PATHTOPYTHON=/usr/local/bin/
112+
PYTHON=${PATHTOPYTHON}python${PYVER}
113+
114+
# find the root of the virtualenv, it should be the parent of the dir this script is in
115+
ENV=`$PYTHON -c "import os; print(os.path.abspath(os.path.join(os.path.dirname(\"$0\"), '..')))"`
116+
117+
# now run Python with the virtualenv set as Python's HOME
118+
export PYTHONHOME=$ENV
119+
exec $PYTHON "$@"
120+
121+
With this in place you can run ``frameworkpython`` as above but will need to add this script
122+
to every virtualenv
123+
124+
PythonW Compiler
125+
^^^^^^^^^^^^^^^^
126+
127+
In addition
128+
`virtualenv-pythonw-osx <https://github.com/gldnspud/virtualenv-pythonw-osx>`_
129+
provides an alternative workaround which may be used to solve the issue.

‎doc/faq/virtualenv_faq.rst‎

Lines changed: 4 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Working with Matplotlib in Virtual environments
88
:backlinks: none
99

1010

11-
.. _introduction:
11+
.. _virtualenv_introduction:
1212

1313
Introduction
1414
============
@@ -25,6 +25,9 @@ If you only use the ``IPython/Jupyter Notebook``'s ``inline`` and ``notebook``
2525
backends and non interactive backends you should not have any issues and can
2626
ignore everything below.
2727

28+
If you are using Matplotlib on OSX you may also want to consider the
29+
:ref:`OSX framework FAQ <osxframework-faq>`.
30+
2831
GUI Frameworks
2932
==============
3033

@@ -59,118 +62,3 @@ Alternatively, you can manually symlink the GUI frameworks into the environment.
5962
I.e. to use PyQt5, you should symlink ``PyQt5`` and ``sip`` from your system
6063
site packages directory into the environment taking care that the environment
6164
and the systemwide install use the same python version.
62-
63-
OSX Framework builds
64-
====================
65-
66-
Short version
67-
-------------
68-
69-
If you are on Python 3, use ``venv`` instead of ``virtualenv``::
70-
71-
python -m venv my-virtualenv
72-
source my-virtualenv/bin/activate
73-
74-
Otherwise you will need one of the workarounds below.
75-
76-
Long version
77-
------------
78-
79-
On OSX, two different types of Python Builds exist: a regular build and a
80-
framework build. In order to interact correctly with OSX through the native
81-
GUI frameworks you need a framework build of Python.
82-
At the time of writing the ``macosx`` and ``WXAgg`` backends require a
83-
framework build to function correctly. This can result in issues for
84-
a python installation not build as a framework. In virtual envs and when
85-
using (Ana)Conda. From Matplotlib 1.5 onwards the ``macosx`` backend
86-
checks that a framework build is available and fails if a non framework
87-
build is found. WX has a similar check build in.
88-
89-
Without this check a partially functional figure is created.
90-
Among the issues with it is that it is produced in the background and
91-
cannot be put in front of any other window.
92-
93-
94-
OSX Conda
95-
=========
96-
97-
The default python provided in (Ana)Conda is not a framework
98-
build. However, the Conda developers have made it easy to install
99-
a framework build in both the main environment and in Conda envs.
100-
To use this install python.app ``conda install python.app`` and
101-
use ``pythonw`` rather than ``python``
102-
103-
104-
OSX virtualenv
105-
==============
106-
107-
Unfortunately virtualenv creates a non
108-
framework build even if created from a framework build of Python.
109-
110-
The issue has been reported on the virtualenv bug tracker `here
111-
<https://github.com/pypa/virtualenv/issues/54>`__ and `here
112-
<https://github.com/pypa/virtualenv/issues/609>`__
113-
114-
Until this is fixed, one of the following workarounds must be used:
115-
116-
``PYTHONHOME`` Function
117-
-----------------------
118-
119-
The best known work around is to use the non
120-
virtualenv python along with the PYTHONHOME environment variable.
121-
This can be done by defining a function in your ``.bashrc`` using
122-
123-
.. code:: bash
124-
125-
function frameworkpython {
126-
if [[ ! -z "$VIRTUAL_ENV" ]]; then
127-
PYTHONHOME=$VIRTUAL_ENV /usr/local/bin/python "$@"
128-
else
129-
/usr/local/bin/python "$@"
130-
fi
131-
}
132-
133-
This function can then be used in all of your virtualenvs without having to
134-
fix every single one of them.
135-
136-
With this in place you can run ``frameworkpython`` to get an interactive
137-
framework build within the virtualenv. To run a script you can do
138-
``frameworkpython test.py`` where ``test.py`` is a script that requires a
139-
framework build. To run an interactive ``IPython`` session with the framework
140-
build within the virtual environment you can do ``frameworkpython -m IPython``
141-
142-
``PYTHONHOME`` Script
143-
^^^^^^^^^^^^^^^^^^^^^
144-
145-
An alternative work around borrowed from the `WX wiki
146-
<http://wiki.wxpython.org/wxPythonVirtualenvOnMac>`_, is to use the non
147-
virtualenv python along with the PYTHONHOME environment variable. This can be
148-
implemented in a script as below. To use this modify ``PYVER`` and
149-
``PATHTOPYTHON`` and put the script in the virtualenv bin directory i.e.
150-
``PATHTOVENV/bin/frameworkpython``
151-
152-
.. code:: bash
153-
154-
#!/bin/bash
155-
156-
# what real Python executable to use
157-
PYVER=2.7
158-
PATHTOPYTHON=/usr/local/bin/
159-
PYTHON=${PATHTOPYTHON}python${PYVER}
160-
161-
# find the root of the virtualenv, it should be the parent of the dir this script is in
162-
ENV=`$PYTHON -c "import os; print(os.path.abspath(os.path.join(os.path.dirname(\"$0\"), '..')))"`
163-
164-
# now run Python with the virtualenv set as Python's HOME
165-
export PYTHONHOME=$ENV
166-
exec $PYTHON "$@"
167-
168-
With this in place you can run ``frameworkpython`` as above but will need to add this script
169-
to every virtualenv
170-
171-
PythonW Compiler
172-
^^^^^^^^^^^^^^^^
173-
174-
In addition
175-
`virtualenv-pythonw-osx <https://github.com/gldnspud/virtualenv-pythonw-osx>`_
176-
provides an alternative workaround which may be used to solve the issue.

0 commit comments

Comments
 (0)