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: -
- --
-
- The names and locations of the C source files. In the examples, this
- is the file
xxmodule.c, and is in - MPW's current working directory. - - The name that Python expects to import your module under. In the
- examples, this is
xx, so the shared library file will be - calledxx.ppc.slb. - - The location of any additional header files use by the C source. The - example does not use any additional header files. -
- The location of any additional shared libraries which the module needs - to link to. The example does not link to any other shared libraries. -
- The name of the entry point to your module. This is usually the last
- function in the main C source file, and the name usually starts with
-
init. In the examples, this isinitxx. -
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:
-
-
-
- Select "Create build commands..." from the "Build" Menu. -
- Type xx.ppc.slb for the Program Name. -
- Select "Shared Library" for the Program Type. -
- Select "PowerPC Only" for the Target. -
- Click on the "Source Files..." button, and add your module's C source - files to the list. -
- Click on the "Other Options..." button and change the creator type to - "Pyth". If you are using additional header files, you can also add their - directories at this stage. Click on "Continue" once you have done this. -
- Click on the "Exported Symbols..." button and type initxx - into the entry field. Click on "Continue" once you have done this. -
- At this stage, your CreateMake window should look like this:
![[picture of commando window for CreateMake]](html.icons/createmake.png)
- - Click on the "CreateMake" button. -
-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: -
- --
-
- Change the line
-
-
-Includes = -
- -- to read -
- --Includes = -i "{PythonIncludes}" -i "{PythonMacIncludes}" -- -- If you have any additional headers than need to be included, you can add - them here as well. -
- Change the line
-
-
-PPCCOptions = {Includes} {Sym•PPC} -- -- to read -
- --PPCCOptions = -w off -d HAVE_CONFIG_H {Includes} {Sym•PPC} -- --
- After the line
-
-
- -xm s ∂ -
- -- add -
- -- -d ∂ - "{PythonCore}" ∂ -- -- If you have any other shared libraries you need to link to, add each on a - line before PythonCore, terminating each line with a
- -∂. -
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:
- --
-
- When there are multiple symbols with the same name in object files or
- shared libraries,
PPCLinkused the symbol from the file which - appears first in arguments of thePPCLinkcommand. For this - reason, you will usually want the PythonCore and any other shared libraries - which are not part of the standard MPW runtime environment to appear before - the standard runtime libraries. This is particularly the case with - StdCLib. The "-d" option turns off the (often copious) warnings about - multiply defined symbols. - - You will want to make sure that the
HAVE_CONFIG_H- preprocessor symbol is defined for most C source files using the-d - HAVE_CONFIG_Hoption toMrC. -
-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. -
- - - - - - diff --git a/Mac/Demo/plugins.html b/Mac/Demo/plugins.html deleted file mode 100644 index a49da68b179..00000000000 --- a/Mac/Demo/plugins.html +++ /dev/null @@ -1,324 +0,0 @@ -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)
-
- -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: -
-
-
- in PPC target, set the output file name to "interslipmodule.carbon.slb", -
- if you are working without a source distribution (i.e. with a normal
-binary distribution plus a development distribution) you will not have
-a file
PythonCoreCarbon. The installation process has deposited this -file in the SystemExtensionsfolder under the name -PythonCoreCarbon version. Add that file to the project, replacing -PythonCoreCarbon. - - you must either download and build GUSI (if your extension module uses sockets -or other Unix I/O constructs) or remove GUSI references from the Access Paths -settings. See the Building document for where to get GUSI -and how to build 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"
-
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;
- }
-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);
-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__},
-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));
-
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 a42ac2f4aba..00000000000 --- 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 5048ac37c60..00000000000 --- a/Mac/Demo/using.html +++ /dev/null @@ -1,429 +0,0 @@ - -
-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 thePython 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 isPythonInterpreter 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 asSimpleText.
-
-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, typereload(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 thefixfiletypesscript 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 theKeyboardInterrupt 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: -
-
-
- the interpreter goes to interactive mode (in stead of -exiting) after a script has terminated normally, -
- for every module imported a line is printed telling you where the -module was loaded from, -
- do not print the values of expressions executed as statements in -an interactive python (obsolete), -
- do not buffer stdout and stderr, -
- print some debugging output during the parsing phase, -
- keep the output window open when a script terminates. -
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 theBuildApplet 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 theEditPythonPrefs
-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. - - -