[Pythonmac-SIG] Suggested revisions for MacPython documentation section 1--please review

Kevin Walzer kw at codebykevin.com
Wed Apr 11 16:39:40 CEST 2007


Thanks for the help! I'll fold these suggestions in to the new docs and 
submit them to the tracker shortly.

Ronald Oussoren wrote:
> 
> On 6 Apr, 2007, at 0:11, Kevin Walzer wrote:
> 
>> 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. :-)
> 
> The next point release (2.5.1) is impossible to get into, that is in a 
> complete freeze. 2.5.2 should be possible.
> 
> File a patch or bug at the SF bugtracker for python when your done (in 
> the documentation category) and let me know the bug number, that way I 
> can at least add a comment to say that these changes should go in.
> 
> The source of the documentation are latex files in the subdirectory 
> Doc/mac. Uploading your changes as a patch to the documentation should 
> expedite things, but otherwise several of the documentation maintainers 
> have publicly stated that they will translate your changes into latex 
> for you.
> 
> Ronald
> 
>>
>> 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.)
> 
> I don't think you should mention ActiveState's python distribution, that 
> just confuses things. Why mention ActiveState but not fink or macports?
> 
>>
>> 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.
> 
> /usr/local/bin/python is deprecated and only present for backward 
> compatiblity. The interpreter lives inside the framework and the binary 
> installer will update your shell profile to point to that location.
> 
>>
>> * A framework /Library/Frameworks/Python.framework, where all the action
>> really is, but which you usually do not have to be aware of.
> 
> That's not quite true. You'll be mightily surprised when using distutils 
> to install scripts and expect them to appear in /usr/local/bin.
> 
>>
>> 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.
> 
> s/may be/are/
> 
>>
>> 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.
> 
> TextMate seems to be very popular these days and appears to be a much 
> better OSX citizen than BBEdit (at least the last time I look at both of 
> these, which for BBEdit is several years ago).
> 
> 
>>
>> 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.
> 
> I'm a bit biased of course but would like to see PyObjC as the first 
> item in the list, we are talking about python on the mac after all :-)
> 
>>
>> 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
> 
> 
> Over all: a good document.  Could you please add a short section about 
> application scripting as well, with a reference to appscript?
> 
> Ronald
>>
>> _______________________________________________
>> Pythonmac-SIG maillist  -  Pythonmac-SIG at python.org
>> http://mail.python.org/mailman/listinfo/pythonmac-sig
> 


-- 
Kevin Walzer
Code by Kevin
http://www.codebykevin.com


More information about the Pythonmac-SIG mailing list