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

Fri Apr 6 08:10:09 CEST 2007

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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 3562 bytes
Desc: not available
Url : http://mail.python.org/pipermail/pythonmac-sig/attachments/20070406/6998090c/attachment.bin 