From d338b6e31727d2ebd7393ec20fa44ab50653e290 Mon Sep 17 00:00:00 2001 From: Jack Jansen Date: Wed, 19 Nov 2003 14:54:25 +0000 Subject: =?UTF-8?q?Removing=20the=20obvious=20OS9-only=20documents=C2=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Mac/Demo/building.html | 424 ------------------------------ Mac/Demo/cgi.html | 90 ------- Mac/Demo/cgi/cgitest.cgi.py | 2 - Mac/Demo/cgi/cgitest.cgi.rsrc | Bin 8072 -> 0 bytes Mac/Demo/cgi/realcgitest.py | 59 ----- Mac/Demo/embed.html | 44 ---- Mac/Demo/embed/demo.c | 71 ----- Mac/Demo/embed/embeddemo.prj | Bin 78479 -> 0 bytes Mac/Demo/freezing.html | 151 ----------- Mac/Demo/interslip/InterslipLib.c | 97 ------- Mac/Demo/interslip/InterslipLib.h | 20 -- Mac/Demo/interslip/interslipmodule.c | 225 ---------------- Mac/Demo/mpwextensions.html | 484 ----------------------------------- Mac/Demo/plugins.html | 324 ----------------------- Mac/Demo/printing/PrintingDemo.py | 93 ------- Mac/Demo/using.html | 429 ------------------------------- 16 files changed, 2513 deletions(-) delete mode 100644 Mac/Demo/building.html delete mode 100644 Mac/Demo/cgi.html delete mode 100644 Mac/Demo/cgi/cgitest.cgi.py delete mode 100644 Mac/Demo/cgi/cgitest.cgi.rsrc delete mode 100644 Mac/Demo/cgi/realcgitest.py delete mode 100644 Mac/Demo/embed.html delete mode 100644 Mac/Demo/embed/demo.c delete mode 100644 Mac/Demo/embed/embeddemo.prj delete mode 100644 Mac/Demo/freezing.html delete mode 100644 Mac/Demo/interslip/InterslipLib.c delete mode 100644 Mac/Demo/interslip/InterslipLib.h delete mode 100644 Mac/Demo/interslip/interslipmodule.c delete mode 100644 Mac/Demo/mpwextensions.html delete mode 100644 Mac/Demo/plugins.html delete mode 100644 Mac/Demo/printing/PrintingDemo.py delete mode 100644 Mac/Demo/using.html diff --git a/Mac/Demo/building.html b/Mac/Demo/building.html deleted file mode 100644 index 06cf399..0000000 --- a/Mac/Demo/building.html +++ /dev/null @@ -1,424 +0,0 @@ - - -Building MacPython-OS9 from source - - -

Building MacPython-OS9 from source

-
- -This document explains how to build MacPython-OS9 from source. This is -necessary if you want to make modifications to the Python core. Building -Python is not something to be undertaken lightly, you need a reasonable -working knowledge of the CodeWarrior development environment, a good net -connection and probably quite some time too.

- -Note that if you only want to build new extension modules you don't need to -build Python from source, see the note on extending Python.

- -The information density in this file is high, so you should probably -print it and read it at your leasure. Most things are explained only -once (and probably in the wrong place:-).

- -

-First a warning: this information may become outdated if a new CodeWarrior is -released after MacPython. The -MacPython homepage will -hopefully have updated instructions in that case. These instructions are for CW7, -it is rumoured you may encounter some problems with newer versions of CodeWarrior. -
- -I am interested in feedback on this document, send your -comments to the Mac Python Special -Interest Group. - -

What you need.

- -The following things you definitely need: - - - -The MacPython project files are configured to -include a plethora of optional modules, and these modules need a -number of extra packages. To use the project files as-is you have to -download these packages too. Python has all such modules as -dynamically loaded modules, so if you don't need a certain package it -suffices to just refrain from builing the extension module. -Here are the locations for the various things -you need: - - - -

Setting Up

- -Now that you have collected everything you should start with building -the various parts. If you don't want to fix -access paths try to set things up as follows: - -
-Top-level-folder:
-	GUSI2
-	imglibs
-		jpeg
-		netpbm
-			libtiff
-		zlib
-		png
-	gdbm
-	Python
-		Modules
-		...
-		Mac
-			Modules
-			Build
-			...
-
- -If your setup of the libraries is exactly the same as mine (which is -not very likely, unless you happen to work from the same CVS -repository) you can use the project buildlibs.prj in the -:Mac:Build folder to build all needed libraries in one -fell swoop, otherwise you will have to build the libraries one by -one.

- -First build GUSI, the Carbon variant. -

- -Next, in -libjpeg, pbmplus, -zlib, libpng, gdbm, -andlibtiff you build all projects. Usually the projects are in "mac" -subfolders, sometimes they are in the main folder. Tcl/tk is a special -case, see below. - -

The organization of the Python source tree

- -Time for a short break, while we have a look at the organization of -the Python source tree. At the top level, we find the following -folders: - -
-
Demo -
Demo programs that are not Mac-specific. Some of these may not -work. - -
Extensions -
Extensions to the interpreter that are not Mac-specific. Contains -the img, Imaging and Numerical extensions -in this distribution. - -
Grammar -
The Python grammar. Included for reference only, you cannot build -the parser on a Mac. - -
Include -
Machine-independent header files. - -
Modules -
Machine-independent optional modules. Not all of these will work -on the Mac. - -
Lib -
Machine-independent modules in Python. - -
Lib:lib-dynload -
This is where the dynamically-loaded plugin modules live. - -
Lib:plat-mac -
This is where most of the Mac-specific modules live. The modules here -are available both in MacPython-OS9 and MacPython-OSX. - -
Objects -
Machine-independent code for various object types. Most of these are -not really optional: the interpreter will not function without them. - -
Parser -
The Python parser (machine-independent). - -
Python -
The core interpreter. Most files are machine-independent, some -are unix-specific and not used on the Mac. - -
Tools -
Tools for python developers. Contains modulator which -builds skeleton C extension modules, bgen which generates -complete interface modules from information in C header files and -freeze which is used to turn Python scripts into real -applications (used by MacFreeze and BuildApplication) There are some -readme files, but more documentation is sorely needed. - -
- -The mac-specific stuff lives in the Mac folder: -
-
Build -
This is where the project files live and where you build the -libraries, shared libraries, executables and plugin modules. All the -resulting binaries, except for intermedeate results, are deposited in -the toplevel folder or the :Lib:lib-dynload folder (for plugin modules). - -
Compat -
Unix-compatability routines. Most of these are not used anymore, -since GUSI provides a rather complete emulation, but you may need -these if you are trying to build a non-GUSI python. - -
Demo -
Mac-specific demo programs, some of them annotated. - -
Include -
Mac-specific but compiler-independent include files. - -
Lib -
MacPython-OS9 specific standard modules which are not shared with -MacPython-OSX. - -
Modules -
Mac-specific builtin modules. Theoretically these are all -optional, but some are rather essential (like -macosmodule). A lot of these modules are generated with -bgen, in which case the bgen input files are included so -you can attempt to regenerate them or extend them. - -
MPW -
MPW-specific files. These have not been used or kept up-to-date -for a long time, so use at your own risk. - -
mwerks -
Mwerks-specific sources and headers. Contains glue code for -Pythons shared-library architecture, a replacement for -malloc and a directory with various projects for building -variations on the Python interpreter. The mwerks_*.h -files here are the option-setting files for the various interpreters -and such, comparable to the unix command-line -D options -to the compiler. Each project uses the correct option file as its -"prefix file" in the "C/C++ language" settings. Disabling optional -modules (for the 68K interpreter), building non-GUSI interpreters and -various other things are accomplished by modifying these files (and -possibly changing the list of files included in the project window, of -course). - -
OSX -
Specific to MacPython-OSX, not used by MacPython-OS9. - -
OSXResources -
Specific to MacPython-OSX, not used by MacPython-OS9. - -
Python -
Mac-specific parts of the core interpreter. - -
Resources -
Resource files needed to build the interpreter. - -
Scripts -
A collection of various mac-specific Python scripts. Some are -essential, some are useful but few are documented, so you will have to -use your imagination to work them out. - -
Tools -
A collection of tools, usually bigger than those in the scripts -folder. The important ones here are the IDE and macfreeze. The IDE is built -with the buildIDE.py script, which puts the resulting applet in the toplevel -folder. Macfreeze is usually invoked through the BuildApplication script, -but for more control over the freezing process you can run the main script here. - - -
Unsupported -
Modules that are not supported any longer but may still work with a little effort. -
- -

Building the PPC interpreter

- -First you optionally build the external libraries with buildlibs.prj.

- -Then, the fullbuild script can be used to build -everything, but you need a fully-functional interpreter before you can -use it (and one that isn't rebuilt in the process: you cannot rebuild -a running program). You could copy the interpreter to a different -place and use that to run fullbuild. The PythonStandSmall.prj -project builds an interpreter that is suited to this, and it can also come -in handy if you need to debug things (which is easier in a static program).

- -In case you want to build by hand, or in case the fullbuild -script does not work, here is a breakdown of the various projects.

- -The projects for interpreter and core library are linked together, so -building the PythonInterpreter target -in PythonInterpreter.prj -will result in the whole core being built, but not the extension modules.

- -You will get about 100 warnings on "missing prototype" for the various module init -routines, ignore these. You will also get numerous warnings on functions from GUSI which -override functions from MSL, ignore these too.

- -Here is a breakdown of the projects: - -

- -
PythonCore -
The shared library that contains the bulk of the interpreter and -its resources. -It is a good idea to immedeately put an alias to this -shared library in the Extensions folder of your system -folder. Do exactly that: put an alias there, copying or -moving the file will cause you grief later if you rebuild the library and -forget to copy it to the extensions folder again. The ConfigurePythonXXX applets -will also do this.
- -
PythonInterpeter -
The interpreter. This is basically a routine to call out to the -shared library.

- -

Plugin projects -
Each plugin module has a separate project, and these can be rebuilt on -the fly. Fullbuild (or actually it's little helper genpluginprojects) takes -care of this. -
- -After creating the alias to PythonCore you remove any old -Python XXXX Preferences file from the Preferences folder -(if you had python installed on your system before) and run the interpreter once -to create the correct preferences file.

- -Next, you have to build the extension modules. -If you don't use fullbuild simply open each project and build it. -

- -Finally, you must build the standard applets: -EditPythonPrefs, BuildApplet, etc. For the N-th time: -fullbuild does this for you, but you can also manually drag/drop them onto -BuildApplet.

- -You are all set now, and should read the release notes and -ReadMe file from the Mac folder. - -Rebuilding .exp files is no longer needed since CodeWarrior 7. - -

Using the CVS source archive

- -It is possible (and probably best) to access the Python sources through remote CVS. The -advantage of this is that you get the very latest sources, so any bug -fixed or new features will be immedeately available. This is also the -disadvantage, of course: as this is the same tree as is used for -development it may sometimes be a little less stable.

- -The CVS client of choice is Alexandre Parenteau's MacCVS. It can be -obtained through the WinCVS -homepage. MacCVS uses Internet Config to set file types correctly -based on the filename extension. In the maccvs preferences you should -also set (in the "binary files" section) "use mac encoding: -applesingle" and (in the "text files" section) "use ISO latin 1 -conversion".

- -It is a good idea to disable Quicktime Exchange in the Quicktime control -panel if you are on OS9 or before. Quicktime Exchange will magically map -some extensions to filetypes, and this can seriously hinder you if, for -instance, .bmp is not a Windows bitmap file.

- -The Python sources are checked out from the main -Python CVS archive on sourceforge.net, see the Source access via -CVS page for details. When you check the sources out you will get -something like Python:dist:src, and under that the -Modules, Lib, Mac etc hierarchy. The -src folder can be renamed to Python, and -is what this document refers to as the "toplevel Python folder".

- -The CVS repository does not contain all the projects for the plugin modules, -these are built with fullbuild.py normally. For this reason -it is probably a good idea to first build PythonStandSmall.prj, -which builds a fairly minimal interpreter, and then follow the -fullbuild instructions. - -

Odds and ends

- -Some remarks that I could not fit in elsewhere: - - - - diff --git a/Mac/Demo/cgi.html b/Mac/Demo/cgi.html deleted file mode 100644 index 01ea85e..0000000 --- a/Mac/Demo/cgi.html +++ /dev/null @@ -1,90 +0,0 @@ -Using python to create CGI scripts - -

Using python to create CGI scripts

-
- -In this document we will (eventually) explain how to create Python CGI scripts -for use with Personal WebServer, WebStar and probably other Mac-based HTTP servers too. -Since CGI scripts are AppleEvent servers on the mac we will also learn -a little about general AppleEvent server programming and about applet -debugging.

- -

Note that the current setup is very preliminary, and hence -itis probably not wise to base your strategic products on the information -in this document:-) In stead, play with the code here and join the -pythonmac-sig, where -we I would like to have a discussion on a real design for a Mac CGI framework -(preferrably something that will make CGI scripts portable to unix and other -platforms). -
- -

AppleEvent servers

- -Since AppleEvent clients are easier to write and understand than servers -you should probably read the section on Open Scripting -clients in Python first.

- -Next, let us have a look at the AE Server framework, -MiniAEFrame.py. -This file contains two classes, MiniApplication and AEServer. -MiniApplication is a tiny replacement for FrameWork.Application, -suitable if your application does not need windows and such. - -AEServer is a bit of glue that does part of the appleevent decoding for you. You -call installaehandler passing it the class and id (4-char strings) -of the event you have a handler for and the handler callback routine. When the -appleevent occurs your callback is called with the right arguments. For now, -your argument names are the 4-char values used internally by Open Scripting, -eventually there will be a translation similar to what the generated OSA client -suites provide.

- -You can test AEServer by double-clicking it. It will react to the standard -run/open/print/quit OSA commands. If it is running as a normal python script and you -drag a file onto the interpreter the script will tell you what event it got.

- -

A Minimal CGI script

- -To try a CGI script you will first need a http server. Apple's Personal Webserver -is fine, but I have also used the -shareware -NetPresenz -by Peter Lewis -(don't forget to pay if you give it more than a test run!). Install your -http server, and make sure that it can serve textual documents.

- -Next, let us have a look at our example CGI scripts. CGI scripts have to be -applications, so we will have to make an applet as explained in -example 2. Our applet code, -cgitest.cgi.py is a rather minimal execfile -statement. The reason for this is debugging: the real code is in -realcgitest.py, and this way you do not have -to run mkapplet again every time you change the code. Rename realcgitest.py -to cgitest.cgi.py once you are satisfied that it works.

- -The resource file is not very special, with one exception: since we want to do -our own appleevent handling we don't want the Python initialization code to -create argc and argv for use, since this might gobble up any appleevents we are -interested in. For this reason we have included a 'Popt' resource that disables -the argv initialization. An easy way to create this resource is to drop -the .rsrc file (or the finished applet, if you like) onto -EditPythonPrefs and set the "no argv processing" option.

- -The code itself is actually not too complicated either. We install handlers -for "open application" and "quit" (stolen from the test code in MiniAEFrame) -and the "WWW\275"/"sdoc" event, the event sent on CGI execution. -The cgi handler pretty-prints the CGI arguments in HTML and returns the whole -string that is to be passed to the client. The actual parameters passed -are explained in -http://www.biap.com/datapig/mrwheat/cgi_params.html.

- -To test the script drop cgitest.cgi.py onto mkapplet, -move the resulting cgitest.cgi to somewhere where it is reachable -by NetPresenz, and point your web browser towards it. Note that this assume you have -already renamed realcgitest.py to cgitest.cgi.py, otherwise you'll also have -to copy that file along.

- -For Apple's Personal Webserver you need to do a bit more: you have to copy the -cgi applet to somewhere in your "Webpages" folder and you have to tell the webserver -(in the control panels) that your CGI script exists. I don't understand what the various -types of cgi scripts mean, but experiment with them. - diff --git a/Mac/Demo/cgi/cgitest.cgi.py b/Mac/Demo/cgi/cgitest.cgi.py deleted file mode 100644 index ce59710..0000000 --- a/Mac/Demo/cgi/cgitest.cgi.py +++ /dev/null @@ -1,2 +0,0 @@ -# Debug applets quickly. -execfile('realcgitest.py') diff --git a/Mac/Demo/cgi/cgitest.cgi.rsrc b/Mac/Demo/cgi/cgitest.cgi.rsrc deleted file mode 100644 index c8aa9f4..0000000 Binary files a/Mac/Demo/cgi/cgitest.cgi.rsrc and /dev/null differ diff --git a/Mac/Demo/cgi/realcgitest.py b/Mac/Demo/cgi/realcgitest.py deleted file mode 100644 index e51cb97..0000000 --- a/Mac/Demo/cgi/realcgitest.py +++ /dev/null @@ -1,59 +0,0 @@ -"""cgitest - A minimal CGI applet. Echos parameters back to the client. -""" - -from MiniAEFrame import AEServer, MiniApplication -import MacOS - -debug=1 - -class CGITest(AEServer, MiniApplication): - - def __init__(self): - MiniApplication.__init__(self) - AEServer.__init__(self) - self.installaehandler('aevt', 'oapp', self.open_app) - self.installaehandler('aevt', 'quit', self.quit) - self.installaehandler('WWW\275', 'sdoc', self.cgihandler) - if debug: - self.installaehandler('****', '****', self.otherhandler) - oldparams = MacOS.SchedParams(0, 0) - self.mainloop() - apply(MacOS.SchedParams, oldparams) - - def quit(self, **args): - self.quitting = 1 - - def open_app(self, **args): - pass - - def otherhandler(self, *args, **kwargs): - print 'Unknown AppleEvent' - print 'args', args - print 'kwargs', kwargs - - def cgihandler(self, pathargs, **args): - if debug: - print 'CGI request', pathargs, args - rv = """HTTP/1.0 200 OK -Server: Unknown; python-cgi-script -MIME-Version: 1.0 -Content-type: text/html - -Python CGI-script results -

Python CGI-script results

-
-""" - rv = rv+'
Direct object: %s\n'%pathargs - - for key in args.keys(): - if key[0] != '_': - rv = rv + '
%s: %s\n'%(key, args[key]) - rv = rv +'
\nSee you next time!\n' - - # Note: if you want to quit after each request enable the line - # self.quitting = 1 - - return rv - -if __name__ == '__main__': - CGITest() diff --git a/Mac/Demo/embed.html b/Mac/Demo/embed.html deleted file mode 100644 index e0ca756..0000000 --- a/Mac/Demo/embed.html +++ /dev/null @@ -1,44 +0,0 @@ - - -Embedding Python on the Mac - - -

Embedding Python on the Mac

-
-Note: if you have a binary-only release of MacPython you will not -have this demo installed. Install the developer option (in the standard installer) or -a source release if you want to embed -Python in other applications.

- -Embedding Python on the mac is pretty similar to embedding it on other -platforms, but a few points need mentioning: - -

- -The Python environment is started with a dummy argc and argv, and initial -startup options are obtained through the usual means, except that the -user pression the option-key will not result in an interactive dialog. -You can, however, set startup options on your program in the same way as you -do for applets, by dragging your application to EditPythonPrefs.

- -The most logical way to embed Python is to link it against the shared -library PythonCore. An example project and source can be -found in the embed folder.

- -This example code also shows how to override the console: if you pass the --q argument in the argument box output is thrown away. If you -pass the -d option the output is sent to DebugStr -(so be sure to use this only when running the example under a debugger). - - diff --git a/Mac/Demo/embed/demo.c b/Mac/Demo/embed/demo.c deleted file mode 100644 index a022f94..0000000 --- a/Mac/Demo/embed/demo.c +++ /dev/null @@ -1,71 +0,0 @@ -/* Example of embedding Python in another program */ - -#include "Python.h" -#include "macglue.h" - -static char *argv0; - -long my_writehandler(char *buf, long count) -{ - long mycount; - unsigned char mybuf[255]; - - mycount = count; - if (mycount > 255 ) mycount = 255; - mybuf[0] = (unsigned char)mycount; - strncpy((char *)mybuf+1, buf, mycount); - DebugStr(mybuf); - return count; -} - -main(argc, argv) - int argc; - char **argv; -{ - /* So the user can set argc/argv to something interesting */ - argc = ccommand(&argv); - /* Save a copy of argv0 */ - argv0 = argv[0]; - - /* If the first option is "-q" we don't open a console */ - if ( argc > 1 && strcmp(argv[1], "-q") == 0 ) { - PyMac_SetConsoleHandler(PyMac_DummyReadHandler, PyMac_DummyWriteHandler, - PyMac_DummyWriteHandler); - } else - if ( argc > 1 && strcmp(argv[1], "-d") == 0 ) { - PyMac_SetConsoleHandler(PyMac_DummyReadHandler, my_writehandler, - my_writehandler); - } - /* Initialize the Python interpreter. Required. */ - PyMac_Initialize(); - - /* Define sys.argv. It is up to the application if you - want this; you can also let it undefined (since the Python - code is generally not a main program it has no business - touching sys.argv...) */ - PySys_SetArgv(argc, argv); - - /* Do some application specific code */ - printf("Hello, brave new world\n\n"); - - /* Execute some Python statements (in module __main__) */ - PyRun_SimpleString("import sys\n"); - PyRun_SimpleString("print sys.builtin_module_names\n"); - PyRun_SimpleString("print sys.argv\n"); - - /* Note that you can call any public function of the Python - interpreter here, e.g. call_object(). */ - - /* Some more application specific code */ - printf("\nGoodbye, cruel world\n"); - /* Exit, cleaning up the interpreter */ - Py_Exit(0); - /*NOTREACHED*/ -} - -/* This function is called by the interpreter to get its own name */ -char * -getprogramname() -{ - return argv0; -} diff --git a/Mac/Demo/embed/embeddemo.prj b/Mac/Demo/embed/embeddemo.prj deleted file mode 100644 index 778755a..0000000 Binary files a/Mac/Demo/embed/embeddemo.prj and /dev/null differ diff --git a/Mac/Demo/freezing.html b/Mac/Demo/freezing.html deleted file mode 100644 index 1580bce..0000000 --- a/Mac/Demo/freezing.html +++ /dev/null @@ -1,151 +0,0 @@ - - -Creating standalone applications with Python - - -

Creating standalone applications with Python

- -With BuildApplet you can build a standalone -Python application that works like -any other Mac application: you can double-click it, run it while the -Python interpreter is running other scripts, drop files on it, etc. It is, however, -still dependent on the whole Python installation on your machine: the PythonCore -engine, the plugin modules and the various Lib folders.

- -In some cases you may want to create a true application, for instance because -you want to send it off to people who may not have Python installed on their -machine, or because you the application is important and you do not want changes -in your Python installation like new versions to influence it. - -

The easy way

- -The easiest way to create an application from a Python script is simply by dropping -it on the BuildApplication applet in the main Python folder. -BuildApplication has a similar interface as BuildApplet: you drop a script on -it and it will process it, along with an optional .rsrc file. -

- -What BuildApplication does, however, is very different. It parses your script, -recursively looking for all modules you use, bundles the compiled code for -all these modules in PYC resources, adds the executable machine code for the -PythonCore engine, any dynamically loaded modules you use and a main program, combines -all this into a single file and adds a few preference resources (which you -can inspect with EditPythonPrefs, incidentally) to isolate the -new program from the existing Python installation.

- -Usually you do not need to worry about all this, but occasionally you may have -to exercise some control over the process, for instance because your -program imports modules that don't exist (which can happen if your script -is multi-platform and those modules will never be used on the Mac). See -the section on directives below for details. -If you get strange error messages about missing modules it may also be worthwhile -to run macfreeze in report mode on your program, see below. -

- -

Doing it the hard way

- -With the macfreeze script, for which BuildApplication is a simple -wrapper, you can go a step further and create CodeWarrior projects and -sourcefiles which can then be used to build your final application. While -BuildApplication is good enough for 90% of the use cases there are situations -where you need macfreeze itself, mainly if you want to embed your frozen Python -script into an existing C application, or when you need the extra bit of speed: -the resulting application will start up a bit quicker than one generated -with BuildApplication.

- -When you start -Mac:Tools:macfreeze:macfreeze.py you are asked for the -script file, and you can select which type of freeze to do. The first -time you should always choose report only, which will produce a -listing of modules and where they are included from in the console -window. Macfreeze actually parses all modules, so it may crash in the -process. If it does try again with a higher debug value, this should -show you where it crashes.

- -

Directives

- -For more elaborate programs you will often see that freeze includes -modules you don't need (because they are for a different platform, for -instance) or that it cannot find all your modules (because you modify -sys.path early in your initialization). It is possible to -include directives to tell macfreeze to add items to the search path and -include or exclude certain modules. All your directives should be in the -main script file.

- -Directives have the following form: -

-# macfreeze: command argument
-
-The trigger macfreeze: must be spelled exactly like that, -but the whitespace can be any combination of spaces and tabs. Macfreeze -understands the following directives: - -
-
path -
Prepend a folder to sys.path. The argument is a -pathname, which should probably be relative (starting with a colon) and -is interpreted relative to the folder where the script lives. - -
include -
Include a module. The module can either be given by filename or by -module name, in which case it is looked up through the normal method. - -
exclude -
Exclude a module. The module must be given by modulename. Even when -freeze deems the module necessary it will not be included in the -application. - -
optional -
Include a module if it can be found, but don't complain if it can't. - -
- -There is actually a fourth way that macfreeze can operate: it can be used -to generate only the resource file containing the compiled PYC -resources. This may be useful if you have embedded Python in your own -application. The resource file generated is the same as for the CodeWarrior -generation process.

- -

Freezing with CodeWarrior

- -To freeze with CodeWarrior you need CodeWarrior, obviously, and a full -source distribution of Python. You select the Codewarrior source and -project option. You specify an output folder, which is by default -the name of your script with .py removed and -build. prepended. If the output folder does not exist yet -it is created, and a template project file and bundle resource file are -deposited there. Next, a source file macfreezeconfig.c is -created which includes all builtin modules your script uses, and a -resource file frozenmodules.rsrc which contains the -PYC resources for all your Python modules.

- -The project expects to live in a folder one level below the Python root -folder, so the next thing you should do is move the build folder there. -It is a good idea to leave an alias with the same name in the original -location: when you run freeze again it will regenerate the -frozenmodules.rsrc file but not the project and bundle -files. This is probably what you want: if you modify your python sources -you have to re-freeze, but you may have changed the project and bundle -files, so you don't want to regenerate them.

- -An alternative is to leave the build folder where it is, but then you -have to adapt the search path in the project.

- -The project is set up to include all the standard builtin modules, but -the CW linker is smart enough to exclude any object code that isn't -referenced. Still, it may be worthwhile to remove any sources for -modules that you are sure are not used to cut back on compilation time. -You may also want to examine the various resource files (for Tcl/Tk, for -instance): the loader has no way to know that these aren't used.

- -You may also need to add sourcefiles if your script uses non-standard -builtin modules, like anything from the Extensions folder.

- -The frozenbundle.rsrc resource file contains the bundle -information. It is almost identical to the bundle file used for applets, -with the exception that it sets the sys.path initialization -to $(APPLICATION) only. This means that all modules will only -be looked for in PYC resources in your application.

- - - diff --git a/Mac/Demo/interslip/InterslipLib.c b/Mac/Demo/interslip/InterslipLib.c deleted file mode 100644 index 32c9717..0000000 --- a/Mac/Demo/interslip/InterslipLib.c +++ /dev/null @@ -1,97 +0,0 @@ -/* -** InterslipLib - Routines to talk to InterSLIP. Version 1.1, 31-Oct-1995. -** -** -** (c) Jack Jansen, CWI, 1995 -*/ - -#include - -#include "InterslipLib.h" - -static CntrlParam iopb; -static short refnum = -1; - -OSErr is_open() -{ - if ( refnum >= 0 ) return 0; - return OpenDriver("\p.InterSLIP", &refnum); -} - -OSErr is_connect() -{ - iopb.ioCRefNum = refnum; - iopb.ioVRefNum = refnum; - iopb.ioCompletion = (UniversalProcPtr) 0; - iopb.csCode = 2; - return PBControlImmed((ParmBlkPtr)&iopb); -} - -OSErr is_disconnect() -{ - iopb.ioCRefNum = refnum; - iopb.ioVRefNum = refnum; - iopb.ioCompletion = (UniversalProcPtr) 0; - iopb.csCode = 3; - return PBControlImmed((ParmBlkPtr)&iopb); -} - -OSErr is_status(long *status, long *msgseqnum, StringPtr *msg) -{ - long *csp; - OSErr err; - - iopb.ioCRefNum = refnum; - iopb.ioVRefNum = refnum; - iopb.ioCompletion = (UniversalProcPtr) 0; - iopb.csCode = 4; - if( err = PBControlImmed((ParmBlkPtr)&iopb) ) - return err; - csp = (long *)&iopb.csParam; - *status = csp[0]; - *msgseqnum = csp[1]; - *msg = (unsigned char *)csp[2]; - return 0; -} - -OSErr is_getconfig(long *baudrate, long *flags, - Str255 idrvnam, Str255 odrvnam, Str255 cfgnam) -{ - long *csp; - OSErr err; - - iopb.ioCRefNum = refnum; - iopb.ioVRefNum = refnum; - iopb.ioCompletion = (UniversalProcPtr) 0; - iopb.csCode = 6; - csp = (long *)&iopb.csParam; - csp[2] = (long)idrvnam; - csp[3] = (long)odrvnam; - csp[4] = (long)cfgnam; - if( err = PBControlImmed((ParmBlkPtr)&iopb) ) - return err; - *baudrate = csp[0]; - *flags = csp[1]; - return 0; -} - -OSErr is_setconfig(long baudrate, long flags, - Str255 idrvnam, Str255 odrvnam, Str255 cfgnam) -{ - long *csp; - OSErr err; - - iopb.ioCRefNum = refnum; - iopb.ioVRefNum = refnum; - iopb.ioCompletion = (UniversalProcPtr) 0; - iopb.csCode = 7; - csp = (long *)&iopb.csParam; - csp[0] = baudrate; - csp[1] = flags; - csp[2] = (long)idrvnam; - csp[3] = (long)odrvnam; - csp[4] = (long)cfgnam; - return PBControlImmed((ParmBlkPtr)&iopb); -} - - diff --git a/Mac/Demo/interslip/InterslipLib.h b/Mac/Demo/interslip/InterslipLib.h deleted file mode 100644 index 1ca2276..0000000 --- a/Mac/Demo/interslip/InterslipLib.h +++ /dev/null @@ -1,20 +0,0 @@ -/* -** InterSLIP API. -*/ - -#include - -/* States */ -#define IS_IDLE 0 -#define IS_WMODEM 1 -#define IS_DIAL 2 -#define IS_LOGIN 3 -#define IS_RUN 4 -#define IS_DISC 5 - -OSErr is_open(); /* Open InterSLIP driver (optional) */ -OSErr is_connect();/* Connect */ -OSErr is_disconnect(); /* Disconnect */ -OSErr is_status(long *, long *, StringPtr *); /* Get status, msg seq#, msg pointer */ -OSErr is_getconfig(long *, long *, Str255 , Str255 , Str255 ); /* get config */ -OSErr is_setconfig(long , long , Str255 , Str255 , Str255 ); /* set config */ diff --git a/Mac/Demo/interslip/interslipmodule.c b/Mac/Demo/interslip/interslipmodule.c deleted file mode 100644 index dc2c7a8..0000000 --- a/Mac/Demo/interslip/interslipmodule.c +++ /dev/null @@ -1,225 +0,0 @@ -/*********************************************************** -Copyright 1991-1995 by Stichting Mathematisch Centrum, Amsterdam, -The Netherlands. - - All Rights Reserved - -Permission to use, copy, modify, and distribute this software and its -documentation for any purpose and without fee is hereby granted, -provided that the above copyright notice appear in all copies and that -both that copyright notice and this permission notice appear in -supporting documentation, and that the names of Stichting Mathematisch -Centrum or CWI not be used in advertising or publicity pertaining to -distribution of the software without specific, written prior permission. - -STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO -THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND -FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE -FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT -OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. - -******************************************************************/ - -#include "Python.h" -#include "InterslipLib.h" -#include "macglue.h" - -static PyObject *ErrorObject; - -/* ----------------------------------------------------- */ - -static char pyis_open__doc__[] = -"Load the interslip driver (optional)" -; - -static PyObject * -pyis_open(self, args) - PyObject *self; /* Not used */ - PyObject *args; -{ - OSErr err; - - if (!PyArg_ParseTuple(args, "")) - return NULL; - err = is_open(); - if ( err ) { - PyErr_Mac(ErrorObject, err); - return NULL; - } - Py_INCREF(Py_None); - return Py_None; -} - -static char pyis_connect__doc__[] = -"Tell the driver to start a connect" -; - -static PyObject * -pyis_connect(self, args) - PyObject *self; /* Not used */ - PyObject *args; -{ - OSErr err; - - if (!PyArg_ParseTuple(args, "")) - return NULL; - err = is_connect(); - if ( err ) { - PyErr_Mac(ErrorObject, err); - return NULL; - } - Py_INCREF(Py_None); - return Py_None; -} - -static char pyis_disconnect__doc__[] = -"Tell the interslip driver to start a disconnect" -; - -static PyObject * -pyis_disconnect(self, args) - PyObject *self; /* Not used */ - PyObject *args; -{ - OSErr err; - - if (!PyArg_ParseTuple(args, "")) - return NULL; - err = is_disconnect(); - if ( err ) { - PyErr_Mac(ErrorObject, err); - return NULL; - } - Py_INCREF(Py_None); - return Py_None; -} - -static char pyis_status__doc__[] = -"Return (numeric_status, message_seqnum, message_string) status tuple" -; - -static PyObject * -pyis_status(self, args) - PyObject *self; /* Not used */ - PyObject *args; -{ - long status, seqnum; - StringPtr message; - OSErr err; - - if (!PyArg_ParseTuple(args, "")) - return NULL; - err = is_status(&status, &seqnum, &message); - if ( err ) { - PyErr_Mac(ErrorObject, err); - return NULL; - } - return Py_BuildValue("iiO&", (int)status, (int)seqnum, PyMac_BuildStr255, message); -} - -static char pyis_getconfig__doc__[] = -"Return configuration data (ibaud, obaud, flags, idrvname, odrvname, cfgname)" -; - -static PyObject * -pyis_getconfig(self, args) - PyObject *self; /* Not used */ - PyObject *args; -{ - long baudrate, flags; - Str255 idrvname, odrvname, cfgname; - OSErr err; - int ibaud, obaud; - - if (!PyArg_ParseTuple(args, "")) - return NULL; - err = is_getconfig(&baudrate, &flags, idrvname, odrvname, cfgname); - if ( err ) { - PyErr_Mac(ErrorObject, err); - return NULL; - } - ibaud = (baudrate >> 16) & 0xffff; - obaud = baudrate & 0xffff; - return Py_BuildValue("iiiO&O&O&", ibaud, obaud, (int)flags, PyMac_BuildStr255, idrvname, - PyMac_BuildStr255, odrvname, PyMac_BuildStr255, cfgname); -} - -static char pyis_setconfig__doc__[] = -"Set configuration data (ibaud, obaud, flags, idrvname, odrvname, cfgname)" -; - -static PyObject * -pyis_setconfig(self, args) - PyObject *self; /* Not used */ - PyObject *args; -{ - long baudrate; - int flags; - Str255 idrvname, odrvname, cfgname; - OSErr err; - int ibaud, obaud; - - if (!PyArg_ParseTuple(args, "iiiO&O&O&", &ibaud, &obaud, &flags, PyMac_GetStr255, idrvname, - PyMac_GetStr255, odrvname, PyMac_GetStr255, cfgname)) - return NULL; - baudrate = (ibaud << 16) | obaud; - err = is_setconfig(baudrate, (long)flags, idrvname, odrvname, cfgname); - if ( err ) { - PyErr_Mac(ErrorObject, err); - return NULL; - } - Py_INCREF(Py_None); - return Py_None; -} - -/* List of methods defined in the module */ - -static struct PyMethodDef pyis_methods[] = { - {"open", pyis_open, 1, pyis_open__doc__}, - {"connect", pyis_connect, 1, pyis_connect__doc__}, - {"disconnect", pyis_disconnect, 1, pyis_disconnect__doc__}, - {"status", pyis_status, 1, pyis_status__doc__}, - {"getconfig", pyis_getconfig, 1, pyis_getconfig__doc__}, - {"setconfig", pyis_setconfig, 1, pyis_setconfig__doc__}, - - {NULL, NULL} /* sentinel */ -}; - - -/* Initialization function for the module (*must* be called initinterslip) */ - -static char interslip_module_documentation[] = -"" -; - -void -initinterslip() -{ - PyObject *m, *d; - - /* Create the module and add the functions */ - m = Py_InitModule4("interslip", pyis_methods, - interslip_module_documentation, - (PyObject*)NULL,PYTHON_API_VERSION); - - /* Add some symbolic constants to the module */ - d = PyModule_GetDict(m); - ErrorObject = PyString_FromString("interslip.error"); - PyDict_SetItemString(d, "error", ErrorObject); - - /* XXXX Add constants here */ - - PyDict_SetItemString(d, "IDLE", PyInt_FromLong(IS_IDLE)); - PyDict_SetItemString(d, "WMODEM", PyInt_FromLong(IS_WMODEM)); - PyDict_SetItemString(d, "DIAL", PyInt_FromLong(IS_DIAL)); - PyDict_SetItemString(d, "LOGIN", PyInt_FromLong(IS_LOGIN)); - PyDict_SetItemString(d, "RUN", PyInt_FromLong(IS_RUN)); - PyDict_SetItemString(d, "DISC", PyInt_FromLong(IS_DISC)); - - /* Check for errors */ - if (PyErr_Occurred()) - Py_FatalError("can't initialize module interslip"); -} - diff --git a/Mac/Demo/mpwextensions.html b/Mac/Demo/mpwextensions.html deleted file mode 100644 index 742cbc2..0000000 --- a/Mac/Demo/mpwextensions.html +++ /dev/null @@ -1,484 +0,0 @@ - - - - - -HOWTO: Compiling Python Modules with MPW - - - - - -

HOWTO: Compiling Python Modules with MPW

- -
-This HOWTO is a slightly reformatted version of an original by -Corran Webster, whose -Python page -may contain a more up-to-date version. -
-
- -

-The Macintosh version -of the Python programming language is -usually compiled with Metrowerks -CodeWarrior. As a result, C extension modules are also usually -compiled with CodeWarrior, and the documentation and sample code reflects -this. CodeWarrior is a commercial product, and may be beyond the budgets -of hobbyist hackers, making them dependent on others to compile C extension -modules. At the present time, many standard C extension modules compile -"out of the box" on the Macintosh, but in only a few cases is the plugin -for the Macintosh included in the distribution. -

- -

-The Macintosh -Programmer's Workshop (MPW) is Apple's development environment, and is -freely available for download -from Apple, as well as on their Developer CDs. Since Python was originally -developed using MPW, before CodeWarrior became the dominant MacOS -development environment, most of the idiosyncrasies of MPW are already -supported, and compilation of C extension modules in MPW is possible. -

- -

-This HOWTO only deals with compiling for PowerPC Macintoshes. The process -should be similar for 68k Macintoshes using the code fragment manager, but -I have not attempted this - my old Mac is running NetBSD. -

- -

-This way of compiling modules is still experimental. Please read the -caveats section below. -

- -

Setting Up MPW for Compiling Python Modules

- -

-This assumes that you have successfully installed both MPW and Python with -the Developer's Kit on your Macintosh. -

- -

-The first step is to let MPW know where you keep Python. This step is not -strictly necessary, but will make development easier and improve -portability. Create a new file in the Startup Items folder of -MPW called Python. Type the lines: -

- -
-set Python "Macintosh HD:Applications:Python 1.5.2c1:"
-set PythonIncludes "{Python}Include"
-set PythonMacIncludes "{Python}Mac:Include"
-set PythonCore "{Python}PythonCore"
-
-export Python PythonIncludes PythonMacIncludes PythonCore
-
- -

-where Macintosh HD:Applications:Python 1.5.2c1: is replaced by -the path to the directory where you keep your copy of Python, and the other -variables reflect where you keep your header files and Python core files. -The locations here are the standard for Python 1.5.2c1, but they are -different for Python 1.52b2 and earlier (most notably, the PythonCore is -kept in the Extensions folder). -

- -

-Next, you need to update the config.h -file for the MrC compiler included with MPW. This header file -is located in the :Mac:Include folder in the standard -distribution. You can update it by hand, by adding the lines: -

- -
-#ifdef __MRC__
-#define BAD_STATIC_FORWARD
-#endif
-
- -

-at the after the similar defines for __MWERKS__ and -__SC__ in the file. This step is critical: many modules, -including ones in the standard distribution, will not compile properly -without this modification (see common problems below). -

- -

-Copies of both the Python startup item -for MPW and the config.h are included -here for your convenience. -

- -

-If you are porting Unix modules to the mac, you may find it useful to -install GUSI for -your copy of MPW. GUSI provides some amount of POSIX compatibility, and is -used by Python itself for this purpose - at the very least having it's -header files available may be useful. Also of note for people porting Unix -modules, the most recent alpha version (4.1a8) of MrC and -MrCpp at this writing permits using unix-style pathnames for -includes via the -includes unix command line option. I have -not experimented heavily with this, but will be doing so in the future and -report my findings. -

- -

-You now have MPW and Python set up to allow compilation of modules. -

- -

Compiling a Module

- -

-This assumes that you have a C extension module ready to compile. For -instructions on how to write a module, see the Python documentation. -

- -

-There are three approaches you can take to compiling in MPW: using the -command line interface, using the MPW CreateMake command -(available as the "Create build commands..." menu item, and writing a -Makefile by hand. -

- -

-Before you start any of these, you'll need to know: -

- - - -

Using the Command Line

- -

-For simple modules consisting of one or two C files, it's often convenient -to simply use commands in a MPW Worksheet. Usually you will want to set -MPW's working directory to the directory containing the C source code. The -following commands compile and link the standard Python test module xxmodule.c: -

- -
-MrC "xxmodule.c" -o "xx.c.x" -w off  -d HAVE_CONFIG_H ∂
-        -i "{PythonMacIncludes}" ∂
-        -i "{PythonIncludes}" 
-PPCLink ∂
-        -o "xx.ppc.slb"  ∂
-        "xx.c.x" ∂
-        -t 'shlb' ∂
-        -c 'Pyth' ∂
-        -xm s ∂
-        -d ∂
-        "{PythonCore}" ∂
-        "{SharedLibraries}InterfaceLib" ∂
-        "{SharedLibraries}MathLib" ∂
-        "{SharedLibraries}StdCLib" ∂
-        "{PPCLibraries}StdCRuntime.o" ∂
-        "{PPCLibraries}PPCCRuntime.o" ∂
-        "{PPCLibraries}PPCToolLibs.o" ∂
-        -export initxx
-
- -

-(Note: The last character on each line should appear as "partial -derivative" symbol, which you type as option-d and which is -MPW's line continuation symbol.) -

- -

-Any additional header files should be specified by adding their directories -as extra -i options to the MrC command. Any -additional shared libraries should be added before the PythonCore library -in the PPCLink command. -

- -

-If there is more than one source file, you will need to duplicate the -compile command for each source file, and you will need to include all the -object files in the place where "xx.c.x" appears in the -PPCLink command. -

- -

Using CreateMake

- -

-For more complex modules, or modules that you are writing yourself, you -will probably want to use a makefile. Unfortunately MPW's makefiles are -incompatible with the standard Unix makefiles, so you will not be able to -use any makefiles which come with a C module. -

- -

-Usually, you will want the makefile to reside in the same directory as the -C source code, so you should set MPW's working directory to that directory -before proceeding. -

- -

-To create a makefile for the standard Python test module xxmodule.c: -

- - - -

-You will now need to edit the makefile that was just created. Open the -file "xx.ppc.slb.make" in the current directory and make the following -changes: -

- - - -

Save the file. You are now ready to build. -

- -

-Go to the "Build" or "Full Build" menu items, type in -xx.ppc.slb, and MPW should take things from there. Any time you -need to rebuild the shared library, you can simply do another "Build" or -"Full Build". -

- -

Writing a Makefile by Hand

- -

-For modules which have complex interdependencies between files, you will -likely need a more sophisticated makefile than the one created by -CreateMake. You will need to be familiar with the MPW -makefile format, but you can get a start by either using -CreateMake to get a simple starting point, or taking another -MPW makefile as a starting point. -

- -

-It is beyond the scope of this HOWTO to go into the generalities of MPW -makefiles. Documentation on MPW's Make command can be found -with the MPW distribution, in particular the documents Building -and Maintaining Programs with MPW (2nd Edition) and the MPW -Command Reference. -

- -

-There are a couple of important points to keep in mind when writing a -makefile by hand:

- - - -

-The file xx.ppc.slb.make -is included here for you to use as a starting point. -

- -

Using the Extension Module

- -

-Once you have compiled your extension module, you will need to let Python -know where it is. You can either move it into a place on Python's search -path - such as the :Mac:Plugins folder - or modify the path to -include the location of your new module using the -EditPythonPrefs applet. -

- -

-Your work may not be completely done, as many extension modules have a -Python wrapper around them. If the Python was not written with portability -in mind, you may need to do some more work to get that up and running. -Indeed, if the Python part uses OS-specific features, like pipes, you may -have to completely rewrite it if you can make it work at all. -

- -

Common Problems

- -

-There are a couple of common problems which occur when porting a module -from another platform. Fortunately, they are often easy to fix. -

- -

Static Forward Definitions

- -

-If you get a compiler error which looks something like: -

- -
-File "xxmodule.c"; line 135 #Error: 'Xxo_Type' is already defined
-
- -

-then most likely either you have not set up config.h correctly -to handle static forward definitions, or the module author has not adhered -to the standard python conventions. If the second is the case, find where -the variable is first defined, and replace the static with -staticforward. Then find the second place it is defined -(usually the line where the compiler complained) and replace -static with statichere. -

- -

-If you have set up things correctly, you should now be able to compile. -

- -

Automatic Type Conversion

- -

-MrC seems to be a little pickier about automatically -converting from one type to another than some other C compilers. These can -often be fixed by simply adding an explicit cast to the desired type. -

- -

-XXX There may be a compiler option which relaxes this. That would be a -better solution. -

- -

Caveats

- -

-As Jack Jansen pointed out on the Mac Python mailing list, there could -potentially be conflicts between the MetroWerks C runtime which the Python -core and standard modules was compiled with, and the MPW C runtime which -your extension module is compiled with. While things seem to work fine in -everyday use, it is possible that there are bugs which have not been -discovered yet. Most likely these world take the form of standard C -functions (most likely I/O functions due to conflicts between the SIOUX -libraries and the SIOW libraries) not working as they are supposed to, or -memory leaks caused by improper malloc/free. -

- -

-Some such problems have been demonstrated by compiling modules with -PythonCore linked after StdCLib - printf does not work properly in this -setup, and I suspect that there will also be malloc/free problems in -situations where the module allocates memory which is later disposed of by -Python, or vice-versa. Compiling with PythonCore taking precedence over -StdCLib seems to give the correct behaviour. -

- -

-This method of compiling should be considered experimental for the time -being. Use it at your own risk. -

- -

-If you notice any quirks in modules compiled this way, or have insight into -what may go wrong or right with this situation, please contact me so that I can add -it to the HOWTO. -

- -

-The ideal solution to this problem would be to get Python to compile using -MPW (and a Python MPW Tool would be very neat indeed). However, that does -seem to be a major project. -

- -
-
-
-©Corran Webster, 1999.
- -Last modified 14/12/99 12:17 PM - -
- - - - diff --git a/Mac/Demo/plugins.html b/Mac/Demo/plugins.html deleted file mode 100644 index a49da68..0000000 --- a/Mac/Demo/plugins.html +++ /dev/null @@ -1,324 +0,0 @@ -Creating a C extension module on the Macintosh - -

Creating a C extension module on the Macintosh

-
- -This document gives a step-by-step example of how to create a new C -extension module on the mac. For this example, we will create a module -to interface to the programmers' API of InterSLIP, a package that -allows you to use MacTCP (and, hence, all internet services) over a -modem connection. The actual example does not work anymore, as both -MacTCP and Interslip died long ago, but the text is still mostly -correct.

- -

Prerequisites

- -There are a few things you need to pull this off. First and foremost, -you need a C development environment. Actually, you need a specific -development environment, CodeWarrior by MetroWerks. You will -need Version 7 or later. You may be able to get by with an older -version of CodeWarrior or with another development environment (Up to -about 1994 python was developed with THINK C, and in the dim past it -was compiled with MPW C) assuming you have managed to get Python to -compile under your development environment, but the step-by-step -character of this document will be lost.

- -Next, you need to install the Developer option in the MacPython installer. -You may also find that Guido's Extending and embedding -the Python interpreter is a very handy piece of documentation. I -will skip lots of details that are handled there, like complete -descriptions of Py_ParseTuple and such utility routines, or -the general structure of extension modules.

- -

InterSLIP and the C API to it

- -InterSLIP, the utility to which we are going to create a python -interface, is a system extension that does all the work of connecting -to the internet over a modem connection. InterSLIP is provided -free-of-charge by InterCon. First it connects to -your modem, then it goes through the whole process of dialling, -logging in and possibly starting the SLIP software on the remote -computer and finally it starts with the real work: packing up IP -packets handed to it by MacTCP and sending them to the remote side -(and, of course, the reverse action of receiving incoming packets, -unpacking them and handing them to MacTCP). InterSLIP is a device -driver, and you control it using a application supplied with it, -InterSLIP Setup. The API that InterSLIP Setup uses to talk to the -device driver is published in the documentation and, hence, also -useable by other applications.

- -I happened to have a C interface to the API, which is all ugly -low-level device-driver calls by itself. The C interface is in InterslipLib.c and InterslipLib.h, we'll -concentrate here on how to build the Python wrapper module around -it. Note that this is the "normal" situation when you are writing a -Python extension module: you have some sort of functionality available -to C programmers and want to make a Python interface to it.

- -

Using Modulator

- -The method we describe in this document, using Modulator, is the best -method for small interfaces. For large interfaces there is another -tool, Bgen, which actually generates the complete module without you -lifting a single finger. Bgen, however, has the disadvantage of having -a very steep learning curve, so an example using it will have to wait -until another document, when I have more time.

- -First, let us look at the InterslipLib.h header file, -and see that the whole interface consists of six routines: -is_open, is_connect, -is_disconnect, is_status, -is_getconfig and is_setconfig. Our first -step will be to create a skeleton file @interslipmodule.c, a -dummy module that will contain all the glue code that python expects -of an extension module. Creating this glue code is a breeze with -modulator, a tool that we only have to tell that we want to create a -module with methods of the six names above and that will create the -complete skeleton C code for us.

- -Why call this dummy module @interslipmodule.c and not -interslipmodule.c? Self-preservation: if ever you happen -to repeat the whole process after you have actually turned the -skeleton module into a real module you would overwrite your -hand-written code. By calling the dummy module a different name you -have to make two mistakes in a row before you do this.

- -If you installed Tk support when you installed Python this is extremely -simple. You start modulator and are provided with a form in which you -fill out the details of the module you are creating.

- -

- -You'll need to supply a module name (interslip, in our -case), a module abbreviation (pyis, which is used as a -prefix to all the routines and data structures modulator will create -for you) and you enter the names of all the methods your module will -export (the list above, with is_ stripped off). Note that -we use pyis as the prefix instead of the more logical -is, since the latter would cause our routine names to -collide with those in the API we are interfacing to! The method names -are the names as seen by the python program, and the C routine names -will have the prefix and an underscore prepended. Modulator can do -much more, like generating code for objects and such, but that is a -topic for a later example.

- -Once you have told modulator all about the module you want to create -you press "check", which checks that you haven't omitted any -information and "Generate code". This will prompt you for a C output -file and generate your module for you.

- -

Using Modulator without Tk

- - -Modulator actually uses a two-stage process to create your code: first -the information you provided is turned into a number of python -statements and then these statements are executed to generate your -code. This is done so that you can even use modulator if you don't -have Tk support in Python: you'll just have to write the modulator -python statements by hand (about 10 lines, in our example) and -modulator will generate the C code (about 150 lines, in our -example). Here is the Python code you'll want to execute to generate -our skeleton module:

- -

-	import addpack
-	addpack.addpack('Tools')
-	addpack.addpack('modulator')
-	import genmodule
-
-	m = genmodule.module()
-	m.name = 'interslip'
-	m.abbrev = 'pyis'
-	m.methodlist = ['open', 'connect', 'disconnect', 'status', \
-		'getconfig', 'setconfig']
-	m.objects = []
-
-	fp = open('@interslipmodule.c', 'w')
-	genmodule.write(fp, m)
-
- -Drop this program on the python interpreter and out will come your -skeleton module.

- -Now, rename the file to interslipmodule.c and you're all set to start -developing. The module is complete in the sense that it should -compile, and that if you import it in a python program you will see -all the methods. It is, of course, not yet complete in a functional -way...

- -

Creating a plugin module

- -The easiest way to build a plugin module is to use the distutils package, -this works fine on MacOS with CodeWarrior. See the distutils documentation -for details. Keep in mind that even though you are on the Mac you specify -filenames with Unix syntax: they are actually URLs, not filenames. -

- -Alternatively you can build the project file by hand. -Go to the ":Mac:Build" folder and copy the files xx.carbon.mcp, -and xx.carbon.mcp.exp to interslipmodule.carbon.mcp and -interslipmodule.carbon.mcp.exp, respectively. Edit -interslipmodule.carbon.mcp.exp and change the name of the exported routine -"initxx" to "initinterslip". Open interslipmodule.carbon.mcp with CodeWarrior, -remove the file xxmodule.c and add interslipmodule.c and make a number -of adjustments to the preferences: -

-Next, compile and link your module, fire up python and test it.

- -

Getting the module to do real work

- -So far, so good. In half an hour or so we have created a complete new -extension module for Python. The downside, however, is that the module -does not do anything useful. So, in the next half hour we will turn -our beautiful skeleton module into something that is at least as -beautiful but also gets some serious work done. For this once, -I have spent that half hour for you, and you can see the -results in interslipmodule.c.

- -We add -

-	#include "InterslipLib.h"
-	#include "macglue.h"
-
-to the top of the file, and work our way through each of the methods -to add the functionality needed. Starting with open, we fill in the -template docstring, the value accessible from Python by looking at -interslip.open.__doc__. There are not many tools using -this information at the moment, but as soon as class browsers for -python become available having this minimal documentation available is -a good idea. We put "Load the interslip driver" as the comment -here.

- -Next, we tackle the body of pyis_open(). Since it has no -arguments and no return value we don't need to mess with that, we just -have to add a call to is_open() and check the return for -an error code, in which case we raise an error: -

-	err = is_open();
-	if ( err ) {
-		PyErr_Mac(ErrorObject, err);
-		return NULL;
-	}
-
-The routine PyErr_Mac() is a -useful routine that raises the exception passed as its first -argument. The data passed with the exception is based on the standard -MacOS error code given, and PyErr_Mac() attempts to locate a textual -description of the error code (which sure beats the "error -14021" -messages that so many macintosh applications tell their poor -users).

- -We will skip pyis_connect and pyis_disconnect here, which are pretty -much identical to pyis_open: no arguments, no return value, just a -call and an error check. With pyis_status() things get interesting -again: this call still takes 3 arguments, and all happen to be values -returned (a numeric connection status indicator, a message sequence -number and a pointer to the message itself, in MacOS pascal-style -string form). We declare variables to receive the returned values, do -the call, check the error and format the return value.

- -Building the return value is done using Py_BuildValue: -

-	return Py_BuildValue("iiO&", (int)status, (int)seqnum, PyMac_BuildStr255, message);
-
-Py_BuildValue() is a very handy routine that builds tuples according -to a format string, somewhat similar to the way printf() -works. The format string specifies the arguments expected after the -string, and turns them from C objects into python objects. The -resulting objects are put in a python tuple object and returned. The -"i" format specifier signifies an "int" (hence the cast: status and -seqnum are declared as "long", which is what the is_status() routine -wants, and even though we use a 4-byte project there is really no -reason not to put the cast here). Py_BuildValue and its counterpart -Py_ParseTuple have format codes for all the common C types like ints, -shorts, C-strings, floats, etc. Also, there is a nifty escape -mechanism to format values about which is does not know. This is -invoked by the "O&" format: it expects two arguments, a routine -pointer and an int-sized data object. The routine is called with the -object as a parameter and it should return a python objects -representing the data. Macglue.h declares a number of -such formatting routines for common MacOS objects like Str255, FSSpec, -OSType, Rect, etc. See the comments in the include file for -details.

- -Pyis_getconfig() is again similar to pyis_getstatus, only -two minor points are worth noting here. First, the C API return the -input and output baudrate squashed together into a single 4-byte -long. We separate them out before returning the result to -python. Second, whereas the status call returned us a pointer to a -Str255 it kept we are responsible for allocating the -Str255 for getconfig. This is something that would have -been easy to get wrong had we not used prototypes everywhere. Morale: -always try to include the header files for interfaces to libraries and -other stuff, so that the compiler can catch any mistakes you make.

- -Pyis_setconfig() finally shows off -Py_ParseTuple, the companion function to -Py_BuildValue. You pass it the argument tuple "args" -that your method gets as its second argument, a format string and -pointers to where you want the arguments stored. Again, standard C -types such as strings and integers Py_ParseTuple knows all about and -through the "O&" format you can extend the functionality. For each -"O&" you pass a function pointer and a pointer to a data area. The -function will be called with a PyObject pointer and your data pointer -and it should convert the python object to the correct C type. It -should return 1 on success and 0 on failure. Again, a number of -converters for standard MacOS types are provided, and declared in -macglue.h.

- -Next in our source file comes the method table for our module, which -has been generated by modulator (and it did a good job too!), but -which is worth looking at for a moment. Entries are of the form -

-	{"open",	pyis_open,	1,	pyis_open__doc__},
-
-where the entries are python method name, C routine pointer, flags and -docstring pointer. The value to note is the 1 for the flags: this -signifies that you want to use "new-style" Py_ParseTuple behaviour. If -you are writing a new module always use this, but if you are modifying -old code which calls something like getargs(args, "(ii)", -...) you will have to put zero here. See "extending and -embedding" or possibly the getargs.c source file for details if you -need them.

- -Finally, we add some code to the init module, to put some symbolic -constants (codes that can by returned by the status method) in the -module dictionary, so the python program can use "interslip.RUN" -instead of the cryptic "4" when it wants to check that the interslip -driver is in RUN state. Modulator has already generated code to get at -the module dictionary using PyModule_GetDict() to store the exception -object, so we simply call -

-	PyDict_SetItemString(d, "IDLE", PyInt_FromLong(IS_IDLE));
-
-for each of our items. Since the last bit of code in our init routine -checks for previous errors with PyErr_Occurred() and -since PyDict_SetItemString() gracefully handles the case -of NULL parameters (if PyInt_FromLong() -failed, for instance) we don't have to do error checking here. In some -other cases you may have to do error checking yourself.

- -This concludes our crash-course on writing Python extensions in C on -the Macintosh. If you are not done reading yet I suggest you look -back at the MacPython Crashcourse index to -find another topic to study.

diff --git a/Mac/Demo/printing/PrintingDemo.py b/Mac/Demo/printing/PrintingDemo.py deleted file mode 100644 index a42ac2f..0000000 --- a/Mac/Demo/printing/PrintingDemo.py +++ /dev/null @@ -1,93 +0,0 @@ -import Printing -from Carbon import Qd -from Carbon import Fm -from Carbon import Res - -# some constants -PostScriptBegin = 190 # Set driver state to PostScript -PostScriptEnd = 191 # Restore QuickDraw state -PostScriptHandle = 192 # PostScript data referenced in handle - -CHUNK_SIZE = 0x8000 # max size of PicComment - -def PostScript(text): - """embed text as plain PostScript in print job.""" - handle = Res.Resource('') - Qd.PicComment(PostScriptBegin, 0, handle) - while text: - chunk = text[:CHUNK_SIZE] - text = text[CHUNK_SIZE:] - handle.data = chunk - Qd.PicComment(PostScriptHandle, len(chunk), handle) - handle.data = '' - Qd.PicComment(PostScriptEnd, 0, handle) - -# create a new print record -printrecord = Printing.NewTPrintRecord() - -# open the printer -Printing.PrOpen() -try: - # initialize print record with default values - Printing.PrintDefault(printrecord) - - # page setup, ok is 0 when user cancelled - ok = Printing.PrStlDialog(printrecord) - if not ok: - raise KeyboardInterrupt - # at this stage, you should save the print record in your document for later - # reference. - - # print job dialog, ok is 0 when user cancelled - ok = Printing.PrJobDialog(printrecord) - if not ok: - raise KeyboardInterrupt - - # once per document - port = Printing.PrOpenDoc(printrecord) - # port is the Printer's GrafPort, it is also the current port, so no need to Qd.SetPort(port) - try: - # start printing a page - # XXX should really look up what pages to print by - # inspecting the print record. - Printing.PrOpenPage(port, None) - try: - # use QuickDraw like in any other GrafPort - Qd.FrameRect((10, 250, 100, 500)) - Qd.FrameRect((10, 510, 100, 600)) - Qd.MoveTo(10, 100) - Qd.TextSize(50) - Qd.TextFont(Fm.GetFNum("Helvetica")) - Qd.DrawString("It rreally works!") - Qd.MoveTo(10, 150) - Qd.TextSize(20) - Qd.DrawString("(and now for a little PostScript...)") - - # example PostScript code - ps = """ - % the coordinate system is the quickdraw one, which is flipped - % compared to the default PS one. That means text will appear - % flipped when used directly from PostScript. - % As an example we start by defining a custom scalefont operator - % that corrects this. - /myscalefont{[exch 0 0 2 index neg 0 0]makefont}def - 0.75 setgray - 0 0 moveto - 0 30 lineto 10000 30 lineto - 10000 0 lineto closepath fill - 0 setgray - 5 25 moveto /Courier findfont 20 myscalefont setfont - (Printed with PostScript!) show - 2 setlinewidth [10 10 5 10] 0 setdash 5 5 moveto 400 0 rlineto stroke - """ - # embed the PostScript code in the print job - PostScript(ps) - finally: - # when done with the page - Printing.PrClosePage(port) - finally: - # when done with the document - Printing.PrCloseDoc(port) -finally: - # when done printing - Printing.PrClose() diff --git a/Mac/Demo/using.html b/Mac/Demo/using.html deleted file mode 100644 index 5048ac3..0000000 --- a/Mac/Demo/using.html +++ /dev/null @@ -1,429 +0,0 @@ - - -Using Python 2.0 on the Macintosh - - -

Using Python 2.0 on the Macintosh

-
- -This document is an introduction to using Python on the Apple -Macintosh. It does not introduce the language itself, for this you -should refer to the Python Tutorial by -Guido van Rossum. This guide more-or-less replaces chapter two of the -tutorial, and provides some additional material.

- -The tutorial, along with other indispensible documentation like the -library reference and such, is also available in a number of different -formats at -www.python.org. The Adobe Acrobat .pdf -files are probably a good choice for reading or printing the documents -from your mac.

- -There is currently no good tutorial for the mac-specific features of -Python, but to whet your appetite: it has interfaces to many MacOS -toolboxes (quickdraw, sound, quicktime, open scripting, etc) and -various portable toolboxes are available too (Tk, complex -numbers, image manipulation, etc). Some -annotated sample programs are available to give you an idea of -Python's power.

- -

Using Python

- -The best way to start using Python is by using the Python IDE, -an integrated development environment with editor, debugger, class browser, etc. -Unfortunately the IDE is not yet documented here. Fortunately, however, it does not -need much documentation, so your best bet is to try it.

- -

Invoking the bare interpreter

- -An alternative method to use Python (and the method this document unfortunately emphasizes, -see the comment above) is to use the bare interpreter and an external text editor. -The name of the interpreter is PythonInterpreter and it is -recognizable by the "16 ton" icon. You start the -interpreter in interactive mode by double-clicking its icon:

- -

- -This should give you a text window with an informative version string -and a prompt, something like the following: -

-Python 1.5.1 (#122 Aug 27, 1997)  [CW PPC w/GUSI MSL]
-Copyright 1991-1997 Stichting Mathematisch Centrum, Amsterdam
->>>
-
-The version string tells you the version of Python, whether it was -built for PPC or 68K macs and possibly some options used to build the -interpreter. If you find a bug or have a question about how the -interpreter works it is a good idea to include the version information -in your message.

- -At the prompt you can type interactive python commands. See the -tutorial for more information. The interactive window works -more-or-less like a Communication Toolbox or Telnet window: you type -commands at the bottom and terminate them with the [return] -or [enter] key. Interpreter feedback also appears at the -bottom of the window, and the contents scroll as output is added. You -can use copy and paste in the normal way, but be sure to paste only at -the bottom of the document. - -

Creating Python scripts

- -The Python interpreter works in a way that is different from what you -would expect of a macintosh program: the interpreter is just that: an -interpreter. There is no builtin editor or other development -support. Hence, to create a Python script you need an external text -editor. For a first script you can use any editor that can create -plain, unstyled text files, such as SimpleText.

- -For more serious scripts, though, it is advisable to use a programmers -editor, such as BBEdit or Alpha. BBEdit is -my favorite: it comes in a commercial version but also in a -fully-functional free version BBEdit Lite. You can -download it from the BareBones -site. The free version will probably provide all the functionality -you will ever need. Besides the standard edit facilities it has -multi-file searches and many other goodies that can be very handy when -editing programs.

- -After you have created your script in the editor of your choice you -drop it on the interpreter. This will start the interpreter executing -the script, again with a console window in which the output appears -and in which you can type input if the script requires it. Normally -the interpreter will close the window and quit as soon as the script -is done executing, see below under startup -options for a way to change this.

- -

-There is a BBEdit extension available that allows you to run Python -scripts more-or-less straight from your bbedit source window. Check -out the Mac:Tools:BBPy folder. -
- -It is a good idea to have the names of all your scripts end in -.py. While this is not necessary for standalone scripts -it is needed for modules, and it is probably a good idea to start the -habit now.

- -If you do not like to start the Python interpreter afresh for each -edit-run cycle you can use the import statement and -reload() function to speed things up in some cases. Here -is Guido's original comment for how to do this, from the 1.1 release -notes:

- -

- -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.

- -

Clickable python scripts

- -If you create your script with the correct creator and type, creator -'Pyth' and type 'TEXT', you can double-click -your script and it will automatically invoke the interpreter. If you -use BBEdit you can tell it about the Python file type by adding it to -the "file types" sections of the preferences. Then, if you save a file -for the first time you can tell BBEdit to save the file as a Python -script through the "options" choice of the save dialog.

- -The Scripts folder contains a script -fixfiletypes that will recursively traverse a folder and -set the correct creator and type for all files ending in -.py.

- -

-Older releases of Python used the creator code -'PYTH' in stead of 'Pyth'. If you still have -older Python sources on your system and named them with -'.py' extension the fixfiletypes script will -correct them. -
- -

Interaction with the user

- -Normally, the interpreter will check for user input (mouse clicks, -keyboard input) every once in a while, so it is possible to switch to -other applications while a script runs. It is also possible to -interrupt the interpreter with the standard command-period keypress, -this will raise the KeyboardInterrupt exception. Scripts -may, however, turn off this behaviour to facilitate their own event -handling. Such scripts can only be killed with the -command-option-escape shortcut. - -

startup options

- -If the option key is depressed when Python starts executing -the interpreter will bring up an options dialog thru which you can -influence the way the interpreter behaves. Keep the option key -depressed until the dialog comes up.

- -

- -The options modify the interpreters behaviour in the following way: -

-In addition, you can enter a unix-style command line which is passed -to the script in sys.argv. Sys.argv[0] is always the name -of the script being executed, additional values can be passed -here. Quoting works as expected.

- -

-Warning: redirecting standard input or standard output in the -command-line dialog does not work. This is due to circumstances beyond my -control, hence I cannot say when this will be fixed. -
- -The default options are also settable on a system-wide basis, see the -section on editing preferences.

- -

Module search path

- -The module search path, sys.path, contains the folders -python will search when you import a module. The path is settable on a -system-wide basis (see the preferences section), and normally -comprises the current folder (where the script lives), the -Lib folder and some of its subfolders and possibly some -more.

- -

Working folder

- -The unix concept of a working directory does not translate -directly to a similar concept on the Macintosh. To facilitate easy -porting and the use of relative pathnames in scripts the interpreter -simulates a working directory. When a script is started the initial -working directory is the folder where the script lives. In case of an -interactive interpreter the working directory is the folder where the -interpreter lives.

- -By the way: the "standard file" folder, the folder that is presented -to the user initially for an open or save dialog, does -not follow the Python working directory. Which folder is -initially shown to the user is usually one of (a) the application -folder, (b) the "Documents" folder or (c) the folder most recently -used for such a dialog (in any Python program). This is standard MacOS -behaviour, so don't blame Python for it. The exact behaviour is -settable through a control panel since System 7.5. - -

Interactive startup file

- -If the folder containing the interpreter contains a file named -PythonStartup this file is executed when you start an -interactive interpreter. In this file you could import modules you -often use and other such things.

- - -

Compiled python scripts

- -Once a python module has been imported the interpreter creates a -compiled version which is stored in a file with the ".py" extension -replaced by ".pyc". These compiled files, with creator -'Pyth' and type 'PYC ' load faster when -imported (because they do not have to be parsed). The Lib -folder contains a script compileall.py, running this -script will cause all modules along the python search path to be -precompiled, which will speed up your programs. Compiled files are -also double-clickable.

- -

Python resources

- -MacPython has the ability to collect a number of compiled modules -together in the resource fork of a single file. This feature is useful -if you distribute a python program and want to minimize clutter: you -can put all the needed modules in a single file (which could even be -the interpreter itself).

- -If the module search path contains a filename as one of its entries -(as opposed to a folder name, which is the normal case) this file will -be searched for a resource with type 'PYC ' and a name -matching the module being imported.

- -The scripts folder contains a script -PackLibDir which will convert a number of modules (or -possibly a complete subtree full of modules) into such a resource -file. - -

Setting interpreter preferences

- -The python interpreter keeps a preferences file in the standard -location in the system folder. In this preferences file it remembers -the default module search path and the default settings for the -runtime options. The preferences are settable via -EditPythonPrefs. For PPC/cfm68k python this is a standalone -program living in the main Python folder, for 68K python it is a -script in the Mac:Scripts folder.

- -The interface to edit the preferences is rather clunky for the current -release.

- -

- -In the editable text field at the top you enter the initial module -search path, using newline as a separator. There are two special -values you can use here: an initial substring $(PYTHON) -will expand to the Python home folder and a value of -$(APPLICATION) will expand to the the python application -itself. Note that the text field may extend "beyond the bottom" even -though it does not have a scroll bar. Using the arrow keys works, -though.

- -The Python home folder $(PYTHON) is initially, when you install Python, -set to the folder where the interpreter lives. You can change it here.

- -Finally, you can set the default startup options here, through a -sub-dialog. - -

Applets

- -An applet is a fullblown application written in Python, similar to an -AppleScript applet (and completely different from a Java -applet). Applets are currently supported on PowerPC macintoshes and on -68K macintoshes if you use the CFM68K version of the interpreter, -and are created using the BuildApplet program. You create an -applet by dropping the python source script onto BuildApplet. -Example 2 is a more involved applet -with its own resource file, etc.

- -Note that while an applet behaves as a fullblown Macintosh application -it is not self-sufficient, so distributing it to a machine without an -installed Python interpreter will not work: it needs the shared python -execution engine PythonCore, and probably various modules -from the Lib and PlugIns folders. Distributing it to a machine that does -have a Python system will work.

- -

Customizing applets

- -Applets can have their own settings for the startup options and module -search path. Dropping an applet on the EditPythonPrefs -application allows you to set these, in the same way as -double-clicking EditPythonPrefs allows you to set the system-wide -defaults.

- -Actually, not only applets but also the interpreter itself can have -non-default settings for path and options. If you make a copy of the -interpreter and drop this copy onto EditPythonPrefs you will have an -interpreter that has a different set of default settings.

- -

Where to go from here

- -The previously mentioned Python Tutorial is -an excellent place to start reading if you have never used Python -before. Other documentation such as the library reference manual is -indexed at the Python -Documentation page.

- -There are some annotated sample programs -available that show some mac-specific issues, like use of various -toolboxes and creation of Python applets.

- -The Demo and Mac:Demo -folders in the Macintosh distribution -contains a number of other example programs. Most of these are only -very lightly documented, but they may help you to understand some -aspects of using Python.

- -Finally, there is a Mac:Contrib folder that contains -a few contributions to Python that I couldn't fit in the normal tree -but did want to distribute (many other contributions are contained -throughout the distribution, but you don't see them, really). - -The best way to contact fellow Macintosh Python programmers is to join -the MacPython Special Interest Group mailing list. Send a message with -"info" in the body to pythonmac-sig-request@python.org -or view the Pythonmac SIG -page on the www.python.org WWW -server.

- -

Troubleshooting

- -A rather baffling error message can be "PythonCore not found" when you -start the interpreter and you are sure that PythonCore is available. The -message should actually say "Not enough memory in the system heap to -load PythonCore". -Blame Apple for the confusing message.

- -There appear to be problems with QuickTime for the CFM68K version of the -interpreter. If you experience these please contact the SIG: some people -use quicktime without problems and some not, and we are still hunting for -the cause.

- -Python is a rather safe language, and hence it should be difficult to -crash the interpreter of the system with a Python script. There is an -exception to this rule, though: the modules that interface to the -system toolboxes (windowing, quickdraw, etc) do very little error -checking and therefore a misbehaving program using these modules may -indeed crash the system. Such programs are unfortunately rather -difficult to debug, since the crash does not generate the standard -Python stack trace, obviously, and since debugging print statements -will often interfere with the operation of the program. There is -little to do about this currently.

- -Probably the most common cause of problems with modules ported from -other systems is the Mac end-of-line convention. Where unix uses -linefeed, 0x0a, to separate lines the mac uses carriage return, -0x0d. To complicate matters more a lot of mac programming editors like -BBEdit and emacs will work happily with both conventions, so the file -will appear to be correct in the editor but cause strange errors when -imported. BBEdit has a popup menu which allows you to inspect (and -set) the end-of-line convention used in a file.

- -Python attempts to keep its preferences file up-to-date even when you -move the Python folder around, etc. If this fails the effect will be -that Python cannot start or, worse, that it does work but it cannot find -any standard modules. In this case, start Python and examine sys.path. -If it is incorrect remove any Python preferences file from the system -folder and start the interpreter while the interpreter sits in the main -Python folder. This will regenerate the preferences file. You may also -have to run the ConfigurePython applet again.

- -

Your five minutes are up. Next!

- -The next section to check out is the annotated sample programs.

- -

-Jack Jansen, -jack@cwi.nl, 10-Sep-00. - - - -- cgit v0.12