Oops -- Lib/Test should be Lib/test, of course!

[python/dscho.git] / Mac / HISTORY

This file contains the release notes of older MacPython versions.

        Changes between 1.4 and 1.3.3
        -------------------------------

Aside from all the changes Guido made to the machine-independent part
of Python (see NEWS for those)the following mac-specific changes have
been made:

- Preference file and other items in the System folder now have the
  version number in their name, so old and new python installations
  can coexist.
- Fixed a GUSI crash when exiting with files open.
- Fixed interference with some extensions that added resources that
  looked like ours.
- Fixed slowness of Python in the background.
- About box added (at last...).
- New release of CWGUSI (1.8.0) incorporated. Note that for Tcl/Tk the
  4.1p1 release is still used (4.2 was a little too late). Everything
  ported to CW10.
- Applets can now turn off argc/argv processing (so they can do their
  own initial AppleEvent handling). Applets can also delay opening the
  console window until it is actually used (and, hence, not open it at
  all by refraining from using it).
- MiniAEFrame: Preliminary AppleScript server support. Example code
  provided, including an initial stab at writing CGI scripts in Python.
- macfs: FindApplication() locates application given 4-char creator
  code.
- macfs: GetDates and SetDates get and set creation date, etc.
- FrameWork: preferred method of ending mainloop() is calling _quit().
- FrameWork: different menubar handling resulting in less flashing
  during menu creation.
- FrameWork: added setarrowcursor and setwatchcursor functions.
- findertools: new module that makes various finder features
  available.
- macostools: copy file times too.
- macostools: added touch() to tell finder about changes to a file.
- macerrors: New module with symbolic names for all os-releated
  errors.
- EasyDialogs: ProgressBar fixed.
- aetools: start application if needed
- aetools: use aetools.error for server-generated errors, MacOS.error
  for communication errors, etc.
- Finder_7_0_Suite: New module with the "simple" finder scripting
  interface.
- mac (aka os): xstat() returns resourcesize, creator, type in
  addition to stat() information.
- MacOS: added DebugStr method to drop to low-level debugger.
- MacOS: fixed splash() to actually draw the splash box:-)
- Ctl: fixed very nasty bug in DisposeControl and object deletion.
- Dlg: Added GetDialogWindow and other accessor functions
- Waste: fixed bug with object hanlder installation
- Waste: added tab support
- time: added strftime
- twit: a windowing debugger for Python (preliminary release)
- BBPy: a BBEdit extension that send scripts to the Python interpreter,
  by Just van Rossum.

The following set of changes were already in place for the 1.4b3
release:
- The standard 68K Python is built for CFM68K. This means that PPC and
  68K Python are now largely compatible, both supporting dynamically
  loaded modules, python applets, etc.
  As a result of this there have been numerous subtle changes in
  filenames for PPC plugin modules and such, but these changes should
  be transparent to Python programs.
  The one missing module in cfm68k is Macspeech, for which no CFM68K
  interface library is available (yet?).
- Raise MemoryError on stack overflow.
- Python now always uses 8-byte doubles.
- Removed mactcp, macdnr and stdwin modules from standard
  distribution.
- New releases of Tcl/Tk (4.1p1), CWGUSI (1.7.2) and Waste (1.2f) have
  been incorporated.
- Macfs.SetFolder method added, which sets initial folder for standard
  file dialogs.
- New py_resource module to handle PYC resources.
- List mgr objects "selFlags" and "listFlags" members now accessible.
- QuickDraw got a few new symbolic constants.
- Qt and Cm modules now live in a separate dynamically loadable
  module, so other toolbox modules work if you don't have QuickTime
  installed.
- Old sound mgr calls {Set,Get}SoundVol removed, version number
  interface changed.
- Added convenience routines setarrowcursor and setwatchcursor to
  FrameWork.
- Bugfixes to time.sleep(), FrameWork, macostools,
- Minor fixes/additions/updates to demos and documentation in the Demo
  folder.
- Internal changes:
  - Ported to CW9
  - mwerks_????_config.h organization rationalized
  - Projects renamed to reflect architecture (ppc, cfm68k, 68k).
  - various defines (HAVE_CONFIG_H, USE_MAC_DYNAMIC_LOADING) no longer
    needed.
  - shared-library architecture made more conforming to metrowerks
    documentation. Check xx plugin projects if you have built your own
    dynamically loaded modules.
  
        
        Changes between 1.3.3 and 1.3.2
        --------------------------------

A major change since 1.3.2 is in the organization of the files: The
Mac folder has mac-specific demo programs, attempts at documentation and
more. Browse the HTML files in Mac:Demo for more info.

Also, Toolbox:bgen is not needed anymore for normal use: the relevant
python modules have been moved to Mac:Lib:toolbox.

Other changes:
- Uses final Tk 4.1 and Tcl 7.5 distributions.
- Override preferences (stored in the interpreter/applet application)
  allow overriding of system-wide preferences. Explained in
  "using.html".
- New functionality in FrameWork.py:
  - ScrolledWindow class
  - enable(), settext(), setitem(), setmark(), seticon(),
    checkmenu() and delete() methods for menu entries.
  - event parameter added to idle() method
  - windowbounds() function helps programmer with staggering windows.
  - Erase only visRgn on an update event.
- TextEdit interface module added
- Waste interface module added
- Demos for waste, including skeleton for html editor
- Scrap manager interface added
- Ctl.FindControl() could return reference to deleted object. Fixed.
- GrafPorts have an _id attribute (address of grafport) allowing them
  to be compared (since a new python object is created each time).
- Standard File folder no longer changed on chdir() (this was
  introduced in 1.3.2).
- sys.argv can now be set if you option-drag or option-click a python
  source.
- Various dialogs now have sensible defaults.
- binhextree is now a bit more intelligent about when to binhex.
- gensuitemodule fixed to hand '****' type arguments.

        Changes between 1.3.2 and 1.3.1
        -------------------------------

The main reason for the 1.3.2 distribution is the availability of Tk
for the mac. The Tk port and its integration in Python is definitely
not bug-free, hence this distribution should be treated as beta
software at best.

Another major change in this release is that the Python I/O system is
now based on the GUSI library. This is an I/O library that attempts to
mimic a Posix I/O system. Hence, modules like socket and select are
now available in MacPython. If you build dynamically loaded modules
and you use any unix-like feature such as stat() calls you should
compile using the GUSI include files.

A third major change is that the MacOS creator code has been changed
from 'PYTH' to 'Pyth', due to a conflict. This means that you will
have to change the creator of all your old python programs. The
distribution contains a script "FixCreator.py" that does this
recursively for a whole folder.

Here are all the changes since 1.3.1, in no particular order:
- complex number support added
- cmath module added
- startup options ("option-drag" dialog) can be retrieved from the
  preferences file. EditPythonPrefs hasn't been updated yet, though.
- Creator changed from PYTH to Pyth
- {mac,os}.unlink is now also called {mac,os}.remove
- {mac,os}.mkdir second arg optional
- dup and fdopen calls added
- select module added
- socket module added
- open(file, '*r') for opening resource forks has been removed. It is
  replaced by MacOS.openrf(file, 'r'), which returns a simple
  file-like object to read (or write) resource forks.
- Added AppleEvent URL suite
- Added AppleEvent netscape suite
- QuickDraw globals are now all accessible, as Qd.qd.xxxx


        Mac-specific changes between 1.3 and 1.3.1
        --------------------------------------

Aside from the changes mentioned here there have also been some
changes in the core python, but these are not documented here.
However, these changes are mainly bugfixes, so there shouldn't be any
incompatabilities.

- imgsgi and imgpbm modules added
- Various hooks installed to allow integration with MacTk (currently
  disabled)
- Added support for MacOS Fixed type in toolbox arguments (represented
  as floats in python)
- Added option to keep output window open on normal termination
- Decreased minimum heapsize to run interpreter
- Added progress-bar to EasyDialogs
- Fixed socket.getportname()
- Renamed MACTCP.py to MACTCPconst.py

- Many fixes to FrameWork.py:
  - Added window.SetPort() method
  - Added optional bounds and resid parameters to Window.open()
  - Fixed apple-menu DA handling
  - Fixed activate-event handling
  - Added default Application.makeusermenus() (File:Quit only)
  - Fixed bug with keyboard input handling
  - added idle() method, called from event loop if there are no events
    pending

Toolbox modules:
- component manager module added
- quicktime module added
- font manager module added
- Added color window support
- Added support to obtain pixmap from a window
- Added BitMap type
- Added GrafPort type
- Added support for PenState, Patterns, FontInfo, RGB colors,
- Fixed GetPen and SetPt arguments
- Added read access to members of {C}GrafPort objects
- Added support for cursors
- Provide access to some QuickDraw globals
- Fixed InsetRect, OffsetRect, MapRect
- Added support for various handles such as PatHandle, CursHandle
- Added functions to access members of Window objects



        Changes since 1.3beta3
        ----------------------
- MkPluginAliases.py now works in a virgin distribution environment. It is
  also distributed as an applet.
- hexbin from binhex.py has been fixed
- various bits and pieces in readme files clarified
- mkapplet bug wrt owner resource (and, hence, trouble starting applets) fixed.
- Compiled with CodeWarrior 7.
- AE client modules generated with gensuitemodule.py now use keyword args.
- img modules updated to latest version (including pbm and sgi support).
- Everything compiled with all optimization options available. Let me know
  if you suspect errors that are due to this.

        Changes since Python 1.2 for the mac
        ------------------------------------
- PPC python now uses a shared library organization. This allows the
  creation of dynamically loadable extension modules (contact me) and
  creation of python applets (see mkapplet.py). A number of previously
  builtin modules are now dynamically loaded. Dynamically loaded
  modules are distributed in the PlugIns folder.
- Python modules can live in 'PYC ' resources (with a name equal to the
  module name, so many modules can live in a single file). If you put a
  file (in stead of a folder) in sys.path its resources will be searched.
  See the PackLibDir script for creating such a file.
- new binhex module (partially working, hexbin has problems)
- Python now has a Preferences file, editable with
  EditPythonPrefs. Remembered are the python 'home folder' and the
  initial value for sys.path. If no preferences file is found a simple
  one is created.
  NOTE: this only works correctly if you start python the first time
  from the correct folder.
- new img modules, to read/write/convert images in various formats
- new MacOS toolbox modules: AE, Ctl, Dlg, Event, List, Qd, Res, Snd
  and Win. These provide access to various of the MacOS toolbox
  interfaces. No documentation yet, but the __doc__ strings provide at
  least the calling sequence (and Inside Mac will give you the
  semantics). Minimal demos are provided for most toolbox interfaces,
  and the 'scripts' directory has some more examples.
- AppleEvent client interfaces can be generated from aete/aeut
  resources. No support for objects yet, nor for server interfaces.
- Lib:mac:FrameWork.py has an application framework (under
  construction). 
- (PPC Only) support for building Python applets: tiny standalone
  python applications.
- fp = open(filename, '*r') opens resource-fork of a file for reading
  (and similar for writing).
- option-dragging a file to the interpreter (or immedeately pressing
  <option> after launching python) will bring up an Options dialog
  allowing you to set options like import-tracing, etc.
- MacOS module method added: GetErrorString(OSErr) -> error string
- There is now a numbering convention for resource-ID's:
  128-255       Resources used by the interpreter itself
  256-511       Resources used by standard modules
  512-          Resources for applications
- macfs module changes:
  - StandardGetFile without type arguments now shows all files
  - PromptGetFile(prompt, ...) is like StandardGetFile but with a
    prompt
  - GetDirectory (let user select a folder) added
  - GetFInfo and SetFInfo methods of FSSpec objects get/set finder
    info. FInfo objects have attributes Creator, Type, etc.
  - FindFolder (locate trash/preferences/etc) added
- mactcp/macdnr changes: bug fix wrt idle-loop.
- EditPythonPrefs script: change initial sys.path and python home
  folder
- (PPC only) MkPluginAliases: Setup aliases for dynamically loadable
  modules that live in a single shared library
- PackLibDir: Convert Lib directory to a single resource file
  containing all .pyc code
- fixfiletypes: Set file types based on file extension over a whole
  tree.
- RunLibScript: Run any script as main program, optionally redirecting
  stdin/stdout, supplying arguments, etc.
- binhextree: Binhex all files in a tree, depending on the extension.
- (PPC only) mkapplet: Create a python applet from a sourcefile and
  (optional) resourcefile.
  
        PYTHON 1.2 FOR THE MACINTOSH
        ****************************

Python can be built on the Mac using either THINK C 6.0 (or 7.0), or
CodeWarrior 5.0 (for 68K and PPC).  In the past it has also been compiled
with earlier versions of Think, but no guarantees are made that the
source is still compatible with those versions.  (Think C 5.0 appears
to be OK.)  Likewise, new compiler versions may effectively change the
language accepted (or the library provided!)  and thus cause problems.

MPW is a special case -- it used to be possible to build Python as
an MPW tool using MPW 3.2, and this may still work, but I haven't
tried this lately.  What I have tried, however, is building Python
as a shared library for CFM-68K, using the Symantec C compiler for MPW.
See subdirectory MPW and the README file there for more info.


1. Using Think C 6.0 (or 7.0)
=============================

1.1 The directory structure
---------------------------

I duplicate the UNIX directory structure from the distribution.  The
subdirectories needed to compile are: Mac, Include, Parser, Python,
Objects, Modules.  (Don't bother with Grammar and the parser
generator, nor with the Doc subdirectory.)

For running and testing, you also need Lib and its subdirectories test
and stdwin.  You could also copy some things from the Demo/stdwin
directory (unfortunately most other demos are UNIX specific and even
many stdwin demos are).

Make sure there is no config.c file in the Modules subdirectory (if
you copy from a directory where you have done a UNIX build this might
occur).  Also don't use the config.h generated on UNIX.

1.2 The project file
--------------------

I put all source files in one project, which I place in the parent
directory of the source directories.

1.2.1 Project type

(This is the Set Project Type... dialog in the Project menu.)

Set the creator to PYTH; turn on "far data"; leave "far code" and
"separate strs" unchecked (they just serve to bloat the application).
A partition size of 1000K should be enough to run the standard test
suite (which requires a lot of memory because it stress tests the
parser quite a bit) and most demos or medium-size applications.  The
interpreter will do basic things in as little at 500K but this may
prevent parsing larger modules.

1.2.2 Compiler options

(This is the Options -> THINK C ... dialog in the Edit menu.)

        - Start with Factory Settings.

        - In the Prefix, remove #include <MacHeaders> and add
                #define HAVE_CONFIG_H

        - Choose any optimizer and debugger settings you like.  - You
        can choose 4-byte ints if you want.  This requires that you
        rebuild the ANSI and unix libraries with 4-bytes ints as well
        (better make copies with names like ANSI 32 bit).  With 4-byte
        ints the interpreter is marginally bigger and somewhat (~10%)
        slower, but Python programs can use strings and lists with
        more than 32000 items (with 2-byte ints these can cause
        crashes).  The range of Python integers is not affected (these
        are always represented as longs).  In fact, nowadays I always
        use 4-byte integers, since it is actually rather annoying that
        strings >= 64K cause crashes.

1.2.3 Files to add

(This is the Add Files... dialog in the Source menu.)

The following source files must be added to the project.  I use a
separate segment for each begin letter -- this avoids segment
overflow, except for 'c', where you have to put either ceval.c or
compile.c in a separate segment.  You could also group them by
subdirectory or function, but you may still have to split segments
arbitrarily because of the 32000 bytes restriction.

        - From Mac: all .c files.

        - From Parser: acceler.c, grammar1.c,
        myreadline.c, node.c, parser.c, parsetok.c, tokenizer.c.

        - From Python: bltinmodule.c, ceval.c, cgensupport.c,
        compile.c, errors.c, getargs.c getopt.c, graminit.c, import.c,
        importdl.c, marshal.c, modsupport.c, mystrtoul.c,
        pythonmain.c, pythonrun.c, sigcheck.c, structmember.c,
        sysmodule.c, traceback.c (i.e. all .c files except dup2.c,
        fmod.c, frozenmain.c, getcwd.c, getmtime.c, memmove.c,
        sigcheck.c, strerror.c, strtod.c, thread.c)

        - From Objects: all .c files except xxobject.c.

        - From Modules: all the modules listed in config.c (in the Mac
        subdirectory) in the initializer for inittab[], before
        "ADDMODULE MARKER 2".  Also add md5c.c if you add md5module.c,
        and regexpr.c if you add regexmodule.c.  (You'll find
        macmodule.c in the Mac subdirectory, so it should already have
        been added in a previous step.)  Note that for most modules,
        the source file is called <name>module.c, but for a few long
        module names it is just <module>.c.  Don't add stdwinmodule.c
        yet,

The following THINK C libraries must be added: from Standard
Libraries, ANSI and unix; from Mac Libraries, MacTraps.  I put each
library in a separate segment.  Also see my earlier remark on 4-byte
ints.

1.4 Adding STDWIN
-----------------

STDWIN is built in two separate projects: stdwin.pi contains the core
STDWIN implementation from Ports/mac, textedit.pi contains the files
from Packs/textedit.  Use the same compiler options as for Python and
the same general source setup (in a sister directory of the toplevel
Python directory).  Put all sources in the same segment.  To
stdwin.pi, also add Tools/strdup.c and Gen/wtextbreak.c.

The two projects can now be added as libraries to the Python project.
You must also add stdwinmodule.c and add "#define USE_STDWIN" to the
Prefix in the compiler options dialog (this only affects macmain.c and
config.c).

Note that stdwinmodule.c contains an #include statement that
references "stdwin.h" by relative path name -- if the stdwin toplevel
directory is not a sibling of the python toplevel directory, you may
have to adjust the number of colons in the pathname.

1.5 Resources
-------------

Since I created them with ResEdit I have no text source of the
resources needed to give the application an icon etc...  You can copy
the size, bundle, file reference and icon resources from the
distributed Python application with ResEdit.  THINK C automatically
copies resources into the application file from a file
<projectname>.rsrc.

1.6 Think C 5.0
---------------

Tim Gilbert adds one note that will be helpful to future Think C 5.0
users: When you have a really big project like python, and you want to
compile and run it, if you just hit Command-R, often Think C will
compile the remaining files, think for a moment, and then give you a
warning "internal error(ZREF)--please remove objects."  Don't listen
to it.  It is lying.  What you should do instead is "Check Link..."
and _then_ hit Run.  Why?  Ask Symantec.


2. Using MicroWerks CodeWarrior 5.0
===================================

Essentially, follow the instructions for Think C.

XXX Should at least list the project options.


--Guido van Rossum, CWI, Amsterdam <Guido.van.Rossum@cwi.nl>
<URL:http://www.cwi.nl/cwi/people/Guido.van.Rossum.html>

        PYTHON RELEASE NOTES FOR THE MACINTOSH
        VERSION 1.1

For the most part, Python on the Mac works just like Python under UNIX.
The most important differences are:

- Since there is no shell environment on the Mac, the start-up file
  has a fixed name: PythonStartup.  If a file by this name exists
  (either in the current folder or in the system folder) it is executed
  when an interactive interpreter is started.

- The default search path for modules is different: first the current
  directory is searched, then the subdirectories 'lib', 'lib:stdwin' and
  'demo'.  As always, you can change this (e.g. in your PythonStartup
  file) by assigning or appending to sys.path -- use Macintosh pathnames!
  (The default contains no absolute paths because these are unlikely
  to make sense on other people's hard disks.)

- The user interface for typing interactive commands is different.
  This is actually the THINK C console I/O module, which is based on
  the Mac toolbox TextEdit.  A standard Edit menu provides Cut, Copy,
  Paste and Clear (Undo is only there for Desk Accessories).  A minimal
  File menu provides Quit, which immediately exits the application,
  without the usual cleanup.  You can Copy from previous output,
  but you can't scroll back beyond the 24x80 screen.  The TAB key
  always brings you to the end of the current input line; indentation
  must be entered with spaces (a single space is enough).
  End-of-file is generated by Command-D; Command-Period interrupts.
  There is an annoying limit in the length of an input line to a single
  screen line (less the prompt).  Use \ to input long statements.
  Change your program if it requires long lines typed on input.
  Even though there is no resize box, the window can be resized by
  dragging its bottom right corner, but the maximum size is 24x80.

- Tabs in module files are interpreted as 4 (four!) spaces.  This is
  consistent with most Mac editors that I know.  For individual files
  you can change the tab size with a comment like

        # vi:set tabsize=8:

  (exactly as shown here, including the colons!).  If you are consistent
  in always using tabs for indentation on UNIX, your files will be
  parsed correctly on the Mac, although they may look funny if you
  have nicely lined-up comments or tables using tabs.  Never using tabs
  also works.  Mixing tabs and spaces to simulate 4-character indentation
  levels is likely to fail.

- You can start a script from the Finder by selecting the script and
  the Python interpreter together and then double clicking.  If you
  make the owner of the script PYTH (the type should always be TEXT)
  Python will be launched if you double click it!
  There is no way to pass command line arguments to Python scripts.

- The set of built-in modules is different:

  = Operating system functions for the 'os' module is provided by the
    built-in module 'mac', not 'posix'.  This doesn't have all the
    functions from posix, for obvious reasons (if you know the Mac
    O/S a little bit).  The functions in os.path are provided by
    macpath, they know about Mac pathnames etc.
    
  = None of the UNIX specific modules ('socket', 'pwd', 'grp' etc.)
    exists.
    
  = Module 'stdwin' is always available.  It uses the Mac version of
    STDWIN, which interfaces directly with the Mac toolbox.  The most
    important difference is in the font names; setfont() has a second
    argument specifying the point size and an optional third one
    specifying the variation: a single letter character string,
    'i' for italics, 'b' for bold.  Note that when STDWIN is waiting
    for events, the standard File and Edit menus are inactive but
    still visible, and (most annoyingly) the Apple menu is also inactive;
    conversely, menus put up by STDWIN are not active when the Python is
    reading from the keyboard.  If you open Python together with a text
    file containing a Python script, the script will be executed and
    a console window is only generated when the script uses standard
    input or output.  A script that uses STDWIN exclusively for its I/O
    will have a working Apple menu and no extraneous File/Edit menus.
    (This is because both stdwin and stdio try to initialize the
    windowing environment; whoever gets there first owns the Apple menu.)
    LIMITATIONS: a few recent additions to STDWIN for X11 have not yet
    been added to the Mac version.  There are no bitmap objects, and
    the setwinpos() and setwinsize() methods are non--functional.

- Because launching an application on the Mac is so tedious, you will
  want to edit your program with a desk accessory editor (e.g., Sigma
  edit) and test the changed version without leaving Python.  This is
  possible but requires some care.  Make sure the program is a module
  file (filename must be a Python identifier followed by '.py').  You
  can then import it when you test it for the first time.  There are
  now three possibilities: it contains a syntax error; it gets a runtime
  error (unhandled exception); or it runs OK but gives wrong results.
  (If it gives correct results, you are done testing and don't need
  to read the rest of this paragraph. :-)  Note that the following
  is not Mac-specific -- it's just that on UNIX it's easier to restart
  the entire script so it's rarely useful.
  
  Recovery from a syntax error is easy: edit the file and import it
  again.
  
  Recovery from wrong output is almost as easy: edit the file and,
  instead of importing it, call the function reload() with the module
  name as argument (e.g., if your module is called foo, type
  "reload(foo)").
  
  Recovery from an exception is trickier.  Once the syntax is correct,
  a 'module' entry is placed in an internal table, and following import
  statements will not re-read the file, even if the module's initialization
  terminated with an error (one reason why this is done is so that
  mutually recursive modules are initialized only once).  You must
  therefore force re-reading the module with reload(), however, if this
  happens the first time you try to import the module, the import statement
  itself has not completed, and your workspace does not know the module
  name (even though the internal table of moduesl does!).  The trick is
  to first import the module again, then reload it.  For instance,
  "import foo; reload(foo)".  Because the module object already exists
  internally, the import statement does not attempt to execute the
  module again -- it just places it in your workspace.
  
  When you edit a module you don't have to worry about the corresponding
  '.pyc' file (a "compiled" version of the module, which loads much faster
  than the textual version): the interpreter notices that the '.py' file
  has changed (because its modification time has changed) and ignores the
  '.pyc' file.  When parsing is successful, a new '.pyc' file is written;
  if this fails (no write permission, disk full or whatever) it is
  silently skipped but attempted again the next time the same module
  is loaded.  (Thus, if you plan to place a Python library on a read-only
  disk, it is advisable to "warm the cache" by making the disk writable
  and importing all modules once.  The standard module 'importall' helps
  in doing this.)