Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 1 | |
| 2 | .. _using-on-mac: |
| 3 | |
| 4 | *************************** |
| 5 | Using Python on a Macintosh |
| 6 | *************************** |
| 7 | |
| 8 | :Author: Bob Savage <bobsavage@mac.com> |
| 9 | |
| 10 | |
| 11 | Python on a Macintosh running Mac OS X is in principle very similar to Python on |
| 12 | any other Unix platform, but there are a number of additional features such as |
| 13 | the IDE and the Package Manager that are worth pointing out. |
| 14 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 15 | .. _getting-osx: |
| 16 | |
| 17 | Getting and Installing MacPython |
| 18 | ================================ |
| 19 | |
Georg Brandl | e095968 | 2013-04-14 10:17:35 +0200 | [diff] [blame] | 20 | Mac OS X 10.8 comes with Python 2.7 pre-installed by Apple. If you wish, you |
| 21 | are invited to install the most recent version of Python 3 from the Python |
Georg Brandl | e73778c | 2014-10-29 08:36:35 +0100 | [diff] [blame] | 22 | website (https://www.python.org). A current "universal binary" build of Python, |
Georg Brandl | e095968 | 2013-04-14 10:17:35 +0200 | [diff] [blame] | 23 | which runs natively on the Mac's new Intel and legacy PPC CPU's, is available |
| 24 | there. |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 25 | |
| 26 | What you get after installing is a number of things: |
| 27 | |
Georg Brandl | 1a41c44 | 2016-02-26 19:18:05 +0100 | [diff] [blame^] | 28 | * A :file:`MacPython 3.6` folder in your :file:`Applications` folder. In here |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 29 | you find IDLE, the development environment that is a standard part of official |
| 30 | Python distributions; PythonLauncher, which handles double-clicking Python |
| 31 | scripts from the Finder; and the "Build Applet" tool, which allows you to |
| 32 | package Python scripts as standalone applications on your system. |
| 33 | |
| 34 | * A framework :file:`/Library/Frameworks/Python.framework`, which includes the |
| 35 | Python executable and libraries. The installer adds this location to your shell |
| 36 | path. To uninstall MacPython, you can simply remove these three things. A |
| 37 | symlink to the Python executable is placed in /usr/local/bin/. |
| 38 | |
| 39 | The Apple-provided build of Python is installed in |
| 40 | :file:`/System/Library/Frameworks/Python.framework` and :file:`/usr/bin/python`, |
| 41 | respectively. You should never modify or delete these, as they are |
Benjamin Peterson | 9aa4299 | 2008-09-10 21:57:34 +0000 | [diff] [blame] | 42 | Apple-controlled and are used by Apple- or third-party software. Remember that |
| 43 | if you choose to install a newer Python version from python.org, you will have |
| 44 | two different but functional Python installations on your computer, so it will |
| 45 | be important that your paths and usages are consistent with what you want to do. |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 46 | |
| 47 | IDLE includes a help menu that allows you to access Python documentation. If you |
| 48 | are completely new to Python you should start reading the tutorial introduction |
| 49 | in that document. |
| 50 | |
| 51 | If you are familiar with Python on other Unix platforms you should read the |
| 52 | section on running Python scripts from the Unix shell. |
| 53 | |
| 54 | |
| 55 | How to run a Python script |
| 56 | -------------------------- |
| 57 | |
| 58 | Your best way to get started with Python on Mac OS X is through the IDLE |
| 59 | integrated development environment, see section :ref:`ide` and use the Help menu |
| 60 | when the IDE is running. |
| 61 | |
| 62 | If you want to run Python scripts from the Terminal window command line or from |
| 63 | the Finder you first need an editor to create your script. Mac OS X comes with a |
| 64 | number of standard Unix command line editors, :program:`vim` and |
| 65 | :program:`emacs` among them. If you want a more Mac-like editor, |
| 66 | :program:`BBEdit` or :program:`TextWrangler` from Bare Bones Software (see |
Georg Brandl | 525d355 | 2014-10-29 10:26:56 +0100 | [diff] [blame] | 67 | http://www.barebones.com/products/bbedit/index.html) are good choices, as is |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 68 | :program:`TextMate` (see http://macromates.com/). Other editors include |
| 69 | :program:`Gvim` (http://macvim.org) and :program:`Aquamacs` |
Ezio Melotti | 19192dd | 2010-04-05 13:25:51 +0000 | [diff] [blame] | 70 | (http://aquamacs.org/). |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 71 | |
| 72 | To run your script from the Terminal window you must make sure that |
| 73 | :file:`/usr/local/bin` is in your shell search path. |
| 74 | |
| 75 | To run your script from the Finder you have two options: |
| 76 | |
| 77 | * Drag it to :program:`PythonLauncher` |
| 78 | |
| 79 | * Select :program:`PythonLauncher` as the default application to open your |
| 80 | script (or any .py script) through the finder Info window and double-click it. |
| 81 | :program:`PythonLauncher` has various preferences to control how your script is |
| 82 | launched. Option-dragging allows you to change these for one invocation, or use |
| 83 | its Preferences menu to change things globally. |
| 84 | |
| 85 | |
| 86 | .. _osx-gui-scripts: |
| 87 | |
| 88 | Running scripts with a GUI |
| 89 | -------------------------- |
| 90 | |
| 91 | With older versions of Python, there is one Mac OS X quirk that you need to be |
| 92 | aware of: programs that talk to the Aqua window manager (in other words, |
| 93 | anything that has a GUI) need to be run in a special way. Use :program:`pythonw` |
| 94 | instead of :program:`python` to start such scripts. |
| 95 | |
Georg Brandl | 1a41c44 | 2016-02-26 19:18:05 +0100 | [diff] [blame^] | 96 | With Python 3.6, you can use either :program:`python` or :program:`pythonw`. |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 97 | |
| 98 | |
| 99 | Configuration |
| 100 | ------------- |
| 101 | |
| 102 | Python on OS X honors all standard Unix environment variables such as |
| 103 | :envvar:`PYTHONPATH`, but setting these variables for programs started from the |
| 104 | Finder is non-standard as the Finder does not read your :file:`.profile` or |
Zachary Ware | 1a83746 | 2015-08-29 22:25:04 -0500 | [diff] [blame] | 105 | :file:`.cshrc` at startup. You need to create a file |
| 106 | :file:`~/.MacOSX/environment.plist`. See Apple's Technical Document QA1067 for |
| 107 | details. |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 108 | |
| 109 | For more information on installation Python packages in MacPython, see section |
| 110 | :ref:`mac-package-manager`. |
| 111 | |
| 112 | |
| 113 | .. _ide: |
| 114 | |
| 115 | The IDE |
| 116 | ======= |
| 117 | |
| 118 | MacPython ships with the standard IDLE development environment. A good |
Benjamin Peterson | d7c3ed5 | 2010-06-27 22:32:30 +0000 | [diff] [blame] | 119 | introduction to using IDLE can be found at |
Georg Brandl | 525d355 | 2014-10-29 10:26:56 +0100 | [diff] [blame] | 120 | https://hkn.eecs.berkeley.edu/~dyoo/python/idle_intro/index.html. |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 121 | |
| 122 | |
| 123 | .. _mac-package-manager: |
| 124 | |
| 125 | Installing Additional Python Packages |
| 126 | ===================================== |
| 127 | |
| 128 | There are several methods to install additional Python packages: |
| 129 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 130 | * Packages can be installed via the standard Python distutils mode (``python |
| 131 | setup.py install``). |
| 132 | |
Georg Brandl | e095968 | 2013-04-14 10:17:35 +0200 | [diff] [blame] | 133 | * Many packages can also be installed via the :program:`setuptools` extension |
Georg Brandl | 525d355 | 2014-10-29 10:26:56 +0100 | [diff] [blame] | 134 | or :program:`pip` wrapper, see https://pip.pypa.io/. |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 135 | |
| 136 | |
| 137 | GUI Programming on the Mac |
| 138 | ========================== |
| 139 | |
| 140 | There are several options for building GUI applications on the Mac with Python. |
| 141 | |
| 142 | *PyObjC* is a Python binding to Apple's Objective-C/Cocoa framework, which is |
| 143 | the foundation of most modern Mac development. Information on PyObjC is |
Georg Brandl | 525d355 | 2014-10-29 10:26:56 +0100 | [diff] [blame] | 144 | available from https://pythonhosted.org/pyobjc/. |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 145 | |
Ezio Melotti | 1a263ad | 2010-03-14 09:51:37 +0000 | [diff] [blame] | 146 | The standard Python GUI toolkit is :mod:`tkinter`, based on the cross-platform |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 147 | Tk toolkit (http://www.tcl.tk). An Aqua-native version of Tk is bundled with OS |
| 148 | X by Apple, and the latest version can be downloaded and installed from |
| 149 | http://www.activestate.com; it can also be built from source. |
| 150 | |
| 151 | *wxPython* is another popular cross-platform GUI toolkit that runs natively on |
| 152 | Mac OS X. Packages and documentation are available from http://www.wxpython.org. |
| 153 | |
| 154 | *PyQt* is another popular cross-platform GUI toolkit that runs natively on Mac |
| 155 | OS X. More information can be found at |
Ezio Melotti | 85232bb | 2009-09-14 00:51:48 +0000 | [diff] [blame] | 156 | http://www.riverbankcomputing.co.uk/software/pyqt/intro. |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 157 | |
| 158 | |
| 159 | Distributing Python Applications on the Mac |
| 160 | =========================================== |
| 161 | |
Georg Brandl | 1a41c44 | 2016-02-26 19:18:05 +0100 | [diff] [blame^] | 162 | The "Build Applet" tool that is placed in the MacPython 3.6 folder is fine for |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 163 | packaging small Python scripts on your own machine to run as a standard Mac |
| 164 | application. This tool, however, is not robust enough to distribute Python |
| 165 | applications to other users. |
| 166 | |
| 167 | The standard tool for deploying standalone Python applications on the Mac is |
| 168 | :program:`py2app`. More information on installing and using py2app can be found |
| 169 | at http://undefined.org/python/#py2app. |
| 170 | |
| 171 | |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 172 | Other Resources |
| 173 | =============== |
| 174 | |
| 175 | The MacPython mailing list is an excellent support resource for Python users and |
| 176 | developers on the Mac: |
| 177 | |
Georg Brandl | e73778c | 2014-10-29 08:36:35 +0100 | [diff] [blame] | 178 | https://www.python.org/community/sigs/current/pythonmac-sig/ |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 179 | |
| 180 | Another useful resource is the MacPython wiki: |
| 181 | |
Georg Brandl | e73778c | 2014-10-29 08:36:35 +0100 | [diff] [blame] | 182 | https://wiki.python.org/moin/MacPython |
Georg Brandl | 3c8ce77 | 2007-11-01 20:58:08 +0000 | [diff] [blame] | 183 | |