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@python.org >> http://mail.python.org/mailman/listinfo/pythonmac-sig > -- Kevin Walzer Code by Kevin http://www.codebykevin.com _______________________________________________ Pythonmac-SIG maillist - Pythonmac-SIG@python.org http://mail.python.org/mailman/listinfo/pythonmac-sig
