I've taken some time to prepare a draft update to section 1 of the MacPython documentation that ships with the standard Python 2.5 distribution: the anchor link for this is file:///Library/Frameworks/Python.framework/Versions/2.5/Resources/English.lproj/Documentation/mac/using.html.
The current docs are obsolete, referring to the old PythonIDE, PackageManager, bundlebuilder/build as applet, etc. I've taken some time to revise them to reflect the current state of Python on the Mac, at least in terms of "getting started." I've added stuff on downloading from Python.org, IDLE as the standard editor with MacPython, a brief intro on GUI toolkits, py2app, and so on. I'm not going to touch the other documentation, i.e. the Carbon modules, as I'm not knowledgable enough about the Carbon bits. (I would suggest replacing all the OSA bits with a reference to appscript, but I'm not going to write that part myself.) I am wondering, however, if some additional sections to the Mac library could simply be lifted from docstrings and added? Running pydoc shows stuff like plistlib, Terminal(?) and other stuff that isn't included in the standard documentation. Could someone review the text below and let me know what should be changed? Also, what is the best way to get this submitted/committed for the next point release of Python 2.5.x? I'm still learning that process. :-) Thanks, Kevin ------ "Using MacPython on a Macintosh" 1.1, Getting and Installing MacPython Mac OS X 10.4 comes with Python 2.3 pre-installed by Apple. However, you are encouraged to install the most recent of version of Python from the Python website (http://www.python.org). A "universal binary" build of Python 2.5, which runs natively on the Mac's new Intel and legacy PPC CPU's, is available there. (A separate, freeware commercial build of Python for OS X is available from http:///www.activestate.com.) What you get after installing is a number of things: * A MacPython 2.5 folder in your Applications folder. In here you find IDLE, the development environment that is a standard part of official Python distributions; PythonLauncher, which handles double-clicking Python scripts from the Finder; and the "Build Applet" tool, which allows you to package Python scripts as standalone applications on your system. * A fairly standard Unix commandline Python interpreter in /usr/local/bin/python, but without the usual /usr/local/lib/python. * A framework /Library/Frameworks/Python.framework, where all the action really is, but which you usually do not have to be aware of. To uninstall MacPython you can simply remove these three things. The Apple-provided build of Python is installed in /System/Library/Frameworks/Python.framework and /usr/bin/python, respectively. You should in principle never modify or delete these, as they are Apple-controlled and may be used by Apple- or third-party software. IDLE includes a help menu that allows you to access Python documentation. If you are completely new to Python you should start reading the IDE introduction in that document. If you are familiar with Python on other Unix platforms you should read the section on running Python scripts from the Unix shell. 1.1.1 How to run a Python script Your best way to get started with Python on Mac OS X is through the IDLE integrated development environment, see section 1.2 and use the Help menu when the IDE is running. If you want to run Python scripts from the Terminal window command line or from the Finder you first need an editor to create your script. Mac OS X comes with a number of standard Unix command line editors, vim and emacs among them. If you want a more Mac-like editor BBEdit or TextWrangler from Bare Bones Software (see http://www.barebones.com/products/bbedit/index.shtml) are good choices. To run your script from the Terminal window you must make sure that /usr/local/bin is in your shell search path. To run your script from the Finder you have two options: * Drag it to PythonLauncher * Select PythonLauncher as the default application to open your script (or any .py script) through the finder Info window and double-click it. PythonLauncher has various preferences to control how your script is launched. Option-dragging allows you to change these for one invocation, or use its Preferences menu to change things globally. 1.1.2 Running scripts with a GUI With older versions of Python, there is one Mac OS X quirk that you need to be aware of: programs that talk to the Aqua window manager (in other words, anything that has a GUI) need to be run in a special way. Use pythonw instead of python to start such scripts. With Python 2.5, you can use either python or pythonw. 1.1.3 configuration MacPython honours all standard Unix environment variables such as PYTHONPATH, but setting these variables for programs started from the Finder is non-standard as the Finder does not read your .profile or .cshrc at startup. You need to create a file ~/.MacOSX/environment.plist. See Apple's Technical Document QA1067 for details. For more information on installation Python packages in MacPython, see section 1.3, "Installing Additional Python Packages." 1.2 The IDE MacPython ships with the standard IDLE development environment. A good introduction to using IDLE can be found at http://hkn.eecs.berkeley.edu/~dyoo/python/idle_intro/index.html. ***remove all 1.2.x subsections--they pertain to the obsolete PythonIDE*** 1.3 Installing Additional Python Packages There are several methods to install additional Python packages: * http://pythonmac.org/packages/ contains selected compiled packages for Python 2.5, 2.4, and 2.3. * Packages can be installed via the standard Python distutils mode ("python setup.py install"). * Many packages can also be installed via the setuptools extension. 1.4 GUI Programming on the Mac There are several options for building GUI applications on the Mac with Python. The standard Python GUI toolkit is tkinter, based on the cross-platform Tk toolkit (http://www.tcl.tk). An Aqua-native version of Tk is bundled with OS X by Apple, and the latest version can be downloaded and installed from http://www.activestate.com; it can also be built from source. wxPython is another popular cross-platform GUI toolkit that runs natively on Mac OS X. Packages and documentation are available from http://www.wxpython.org. PyObjC is a Mac-only Python binding to the Cocoa toolkit that ships with Mac OS X. Information on PyObjC is available from http://pybojc.sourceforge.net. 1.4 Distributing Python Applications on the Mac The "Build Applet" tool that is placed in the MacPython 2.5 folder is fine for packaging small Python scripts on your own machine to run as a standard Mac application. This tool, however, is not robust enough to distribute Python applications to other users. The standard tool for deploying standalone Python applications on the Mac is py2app. More information on installing and using py2app can be found at http://undefined.org/python/#py2app. 1.5 Other Resources A useful resource for Python on the Mac is at the MacPython wiki: http://wiki.python.org/moin/MacPython _______________________________________________ Pythonmac-SIG maillist - Pythonmac-SIG@python.org http://mail.python.org/mailman/listinfo/pythonmac-sig
