mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-07-24 11:44:31 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

Misc Mac mods by Jack. Added libmacic.tex, and these patches:

Browse source 
libmacfs.tex	Document NewAliasMinimalFromFullPath
libmacos.tex	Document SetEventHandler and SchedParams
libmacui.tex	Document asynchronous event handling
libmailbox.tex	Removed mime-turds that somehow got in here
This commit is contained in:
Guido van Rossum 1997-08-18 15:14:26 +00:00
parent 9918e0c750
commit e229d8636d
13 changed files with 375 additions and 93 deletions
Download patch file Download diff file Expand all files Collapse all files

2
Doc/Makefile
View file

@ -112,7 +112,7 @@ LIBFILES = lib.tex \
libuser.tex libanydbm.tex librandom.tex libsite.tex libwhichdb.tex \
libbase64.tex libfnmatch.tex libquopri.tex libzlib.tex libsocksvr.tex \
libmailbox.tex libcommands.tex libcmath.tex libni.tex libgzip.tex \
libpprint.tex libcode.tex libmimify.tex libre.tex
libpprint.tex libcode.tex libmimify.tex libre.tex libmacic.tex
# Library document
lib.dvi: $(LIBFILES)

1
Doc/lib.tex
View file

@ -195,6 +195,7 @@ to Python and how to embed it in other applications.
\input{libmacconsole}
\input{libmacdnr}
\input{libmacfs}
\input{libmacic}
\input{libmacos}
\input{libmacostools}
\input{libmactcp}

1
Doc/lib/lib.tex
View file

@ -195,6 +195,7 @@ to Python and how to embed it in other applications.
\input{libmacconsole}
\input{libmacdnr}
\input{libmacfs}
\input{libmacic}
\input{libmacos}
\input{libmacostools}
\input{libmactcp}

10
Doc/lib/libmailbox.tex
View file

@ -31,12 +31,10 @@ All implementations of Mailbox objects have one externally visible
method:
\begin{funcdesc}{next}{}
Return the next message in the mailbox, as a \code{rfc822.Message} object=
=2E
Return the next message in the mailbox, as a \code{rfc822.Message} object.
Depending on the mailbox implementation the \var{fp} attribute of this
object may be a true file object or a class instance simulating a file ob=
ject,
taking care of things like message boundaries if multiple mail messages a=
re
object may be a true file object or a class instance simulating a file object,
taking care of things like message boundaries if multiple mail messages are
contained in a single file, etc.
\end{funcdesc}

9
Doc/libmacfs.tex
View file

@ -86,6 +86,11 @@ search, \var{which} is the 4-char string specifying which folder to
locate. Setting \var{create} causes the folder to be created if it
does not exist. Returns a \code{(vrefnum, dirid)} tuple.
\begin{funcdesc}{NewAliasMinimalFromFullPath}{pathname}
Return a minimal alias record object that points to the given file, which
must be specified as a full pathname. This is the only way to create an
alias record pointing to a non-existing file.
The constants for \var{where} and \var{which} can be obtained from the
standard module \var{MACFS}.
\end{funcdesc}
@ -164,7 +169,9 @@ or transmitting to other programs.
Resolve the alias. If the alias was created as a relative alias you
should pass the file relative to which it is. Return the FSSpec for
the file pointed to and a flag indicating whether the alias object
itself was modified during the search process.
itself was modified during the search process. If the file does
not exist but the path leading up to it does exist a valid fsspec
is returned.
\end{funcdesc}
\begin{funcdesc}{GetInfo}{num}

120
Doc/libmacic.tex Normal file
View file

@ -0,0 +1,120 @@
\section{Standard Module \sectcode{ic}}
\bimodindex{ic}
\renewcommand{\indexsubitem}{(in module ic)}
This module provides access to macintosh Internet Config package,
which stores preferences for Internet programs such as mail address,
default homepage, etc. Also, Internet Config contains an elaborate set
of mappings from Macintosh creator/type codes to foreign filename
extensions plus information on how to transfer files (binary, ascii,
etc).
There is a low-level companion module \code{icglue} which provides the
basic ic access functionality. This low-level module is not
documented, but the docstrings of the routines document the parameters
and the routine names are the same as for the Pascal or C API to
Internet Config, so the standard IC programmers documentation can be
used if this module is needed.
The \code{ic} module defines the \code{error} exception and symbolic
names for all error codes IC can produce, see the source for details.
The \code{ic} module defines the following functions:
\begin{funcdesc}{IC}{\optional{signature\, ic}}
Create an internet config object. The signature is a 4-char creator
code of the current application (default \code{'Pyth'}) which may
influence some of ICs settings. The optional \var{ic} argument is a
low-level \code{icinstance} created beforehand, this may be useful if
you want to get preferences from a different config file, etc.
\end{funcdesc}
\begin{funcdesc}{launchurl}{url \optional{\, hint}}
\end{funcdesc}
\begin{funcdesc}{parseurl}{data \optional{\, start\, end\, hint}}
\end{funcdesc}
\begin{funcdesc}{mapfile}{file}
\end{funcdesc}
\begin{funcdesc}{maptypecreator}{type\, creator \optional{\,
filename}}
\end{funcdesc}
\begin{funcdesc}{settypecreator}{file}
These functions are ``shortcuts'' to the methods of the same name,
described below.
\end{funcdesc}
\subsection{IC objects}
IC objects have a mapping interface, hence to obtain the mail address
you simply get \code{ic['MailAddress']}. Assignment also works, and
changes the option in the configuration file.
The module knows about various datatypes, and converts the internal IC
representation to a ``logical'' python datastructure. Running the
\code{ic} module standalone will run a test program that lists all
keys and values in your IC database, this will have to server as
documentation.
If the module does not know how to represent the data it returns an
instance of the \var{ICOpaqueData} type, with the raw data in its
\var{data} attribute. Objects of this type are also acceptable values
for assignment.
Besides the dictionary interface IC objects have the following methods:
\renewcommand{\indexsubitem}{(IC object attribute)}
\begin{funcdesc}{launchurl}{url \optional{\, hint}}
Parse the given URL, lauch the correct application and pass it the
URL. The optional \var{hint} can be a scheme name such as
\code{mailto:}, in which case incomplete URLs are completed with this
scheme (otherwise incomplete URLs are invalid).
\end{funcdesc}
\begin{funcdesc}{parseurl}{data \optional{\, start\, end\, hint}}
Find an URL somewhere in \var{data} and return start position, end
position and the URL. The optional \var{start} and \var{end} can be
used to limit the search, so for instance if a user clicks in a long
textfield you can pass the whole textfield and the click-position in
\var{start} and this routine will return the whole URL in which the
user clicked. \var{Hint} is again an optional scheme used to complete
incomplete URLs.
\end{funcdesc}
\begin{funcdesc}{mapfile}{file}
Return the mapping entry for the given \var{file}, which can be passed
as either a filename or an \var{FSSpec} object, and which need not
exist.
The mapping entry is returned as a tuple \code{(version\, type\,
creator\, postcreator\, flags\, extension\, appname\, postappname\,
mimetype\, entryname)}, where \var{version} is the entry version
number, \var{type} is the 4-char filetype, \var{creator} is the 4-char
creator type, \var{postcreator} is the 4-char creator code of an
optional application to post-process the file after downloading,
\var{flags} are various bits specifying whether to transfer in binary
or ascii and such, \var{extension} is the filename extension for this
file type, \var{appname} is the printable name of the application to
which this file belongs, \var{postappname} is the name of the
postprocessing application, \var{mimetype} is the MIME type of this
file and \var{entryname} is the name of this entry.
\end{funcdesc}
\begin{funcdesc}{maptypecreator}{type\, creator \optional{\,
filename}}
Return the mapping entry for files with given 4-char \var{type} and
\var{creator} codes. The optional \var{filename} may be specified to
further help finding the correct entry (if the creator code is
\code{'????'}, for instance).
The mapping entry is returned in the same format as for \var{mapfile}.
\end{funcdesc}
\begin{funcdesc}{settypecreator}{file}
Given an existing \var{file}, specified either as a filename or as an
\var{FSSpec} record, set its creator and type correctly based on its
extension. The finder is told about the change, so the finder icon
will be updated quickly.
\end{funcdesc}

66
Doc/libmacos.tex
View file

@ -20,48 +20,35 @@ Symbolic names for all known error codes are defined in the standard
module \var{macerrors}.
\end{excdesc}
\begin{funcdesc}{SetHighLevelEventHandler}{handler}
Pass a python function that will be called upon reception of a
high-level event. The previous handler is returned. The handler
function is called with the event as argument.
\begin{funcdesc}{SetEventHandler}{handler}
In the inner interpreter loop Python will occasionally check for events,
unless disabled with \var{ScheduleParams}. With this function you
can pass a Python event-handler function that will be called if an event
is available. The event is passed as parameter and the function should return
non-zero if the event has been fully processed, otherwise event processing
continues (by passing the event to the console window package, for instance).
Note that your event handler is currently only called dependably if
your main event loop is in \var{stdwin}.
Call SetEventHandler without parameter to clear the event handler. Setting
an eventhandler while one is already set is an error.
\end{funcdesc}
\begin{funcdesc}{AcceptHighLevelEvent}{}
Read a high-level event. The return value is a tuple \code{(sender,
refcon, data)}.
\end{funcdesc}
\begin{funcdesc}{SchedParams}{\optional{doint\, evtmask\, besocial\,
interval\, bgyield}}
Influence the interpreter inner loop event handling. \var{Interval}
specifies how often (in seconds, floating point) the interpreter
should enter the event processing code. When true, \var{doint} causes
interrupt (command-dot) checking to be done. \var{Evtmask} tells the
interpreter to do event processing for events in the mask (redraws,
mouseclicks to switch to other applications, etc). \bar{Besocial}
gives other processes a chance to run. They are granted minimal
runtime when Python is in the foreground and \var{bgyield} seconds per
\var{interval} when Python runs in the background.
\begin{funcdesc}{SetScheduleTimes}{fgi\, fgy \optional{\, bgi\, bgy}}
Controls how often the interpreter checks the event queue and how
long it will yield the processor to other processes. \var{fgi}
specifies after how many clicks (one click is one 60th of a second)
the interpreter should check the event queue, and \var{fgy} specifies
for how many clicks the CPU should be yielded when in the
foreground. The optional \var{bgi} and \var{bgy} allow you to specify
different values to use when python runs in the background, otherwise
the background values will be set the the same as the foreground
values. The function returns nothing.
The default values, which are based on minimal empirical testing, are 12, 1, 6
and 2 respectively.
\end{funcdesc}
\begin{funcdesc}{EnableAppswitch}{onoff}
Enable or disable the python event loop, based on the value of
\var{onoff}. The old value is returned. If the event loop is disabled
no time is granted to other applications, checking for command-period
is not performed and it is impossible to switch applications. This
should only be used by programs providing their own complete event
loop.
Note that based on the compiler used to build python it is still
possible to loose events even with the python event loop disabled. If
you have a \code{sys.stdout} window its handler will often also look
in the event queue. Making sure nothing is ever printed works around
this.
All parameters are optional, and default to the current value. The return
value of this function is a tuple with the old values of these options.
Initial defaults are that all processing is enabled, checking is done every
quarter second and the CPU is given up for a quarter second when in the
background.
\end{funcdesc}
\begin{funcdesc}{HandleEvent}{ev}
@ -70,6 +57,9 @@ possibly to the handler for the \code{sys.stdout} window (based on the
compiler used to build python). This allows python programs that do
their own event handling to still have some command-period and
window-switching capability.
If you attempt to call this function from an event handler set through
\code{SetEventHandler} you will get an exception.
\end{funcdesc}
\begin{funcdesc}{GetErrorString}{errno}

27
Doc/libmacui.tex
View file

@ -4,7 +4,9 @@
The \code{EasyDialogs} module contains some simple dialogs for
the Macintosh, modelled after the \code{stdwin} dialogs with similar
names.
names. All routines have an optional parameter \var{id} with which you
can override the DLOG resource used for the dialog, as long as the
item numbers correspond. See the source for details.
The \code{EasyDialogs} module defines the following functions:
@ -170,6 +172,29 @@ The event loop is split into many small parts, each of which can be
overridden. The default methods take care of dispatching events to
windows and dialogs, handling drags and resizes, Apple Events, events
for non-FrameWork windows, etc.
In general, all event handlers should return 1 if the event is fully
handled and 0 otherwise (because the front window was not a FrameWork
window, for instance). This is needed so that update events and such
can be passed on to other windows like the Sioux console window.
Calling \code{MacOS.HandleEvent} is not allowed within \var{our_dispatch}
or its callees, since this may result in an infinite loop if the
code is called through the python inner-loop event handler.
\end{funcdesc}
\begin{funcdesc}{asyncevents}{onoff}
Call this method with a nonzero parameter to enable
asynchronous event handling. This will tell the inner interpreter loop
to call the application event handler \var{async_dispatch} whenever events
are available. This will cause FrameWork window updates and the user
interface to remain working during long computations, but will slow the
interpreter down and may cause surprising results in non-reentrant code
(such as FrameWork itself). By default \var{async_dispatch} will immedeately
call \var{our_dispatch} but you may override this to handle only certain
events asynchronously. Events you do not handle will be passed to Sioux
and such.
The old on/off value is returned.
\end{funcdesc}
\begin{funcdesc}{_quit}{}

10
Doc/libmailbox.tex
View file

@ -31,12 +31,10 @@ All implementations of Mailbox objects have one externally visible
method:
\begin{funcdesc}{next}{}
Return the next message in the mailbox, as a \code{rfc822.Message} object=
=2E
Return the next message in the mailbox, as a \code{rfc822.Message} object.
Depending on the mailbox implementation the \var{fp} attribute of this
object may be a true file object or a class instance simulating a file ob=
ject,
taking care of things like message boundaries if multiple mail messages a=
re
object may be a true file object or a class instance simulating a file object,
taking care of things like message boundaries if multiple mail messages are
contained in a single file, etc.
\end{funcdesc}

9
Doc/mac/libmacfs.tex
View file

@ -86,6 +86,11 @@ search, \var{which} is the 4-char string specifying which folder to
locate. Setting \var{create} causes the folder to be created if it
does not exist. Returns a \code{(vrefnum, dirid)} tuple.
\begin{funcdesc}{NewAliasMinimalFromFullPath}{pathname}
Return a minimal alias record object that points to the given file, which
must be specified as a full pathname. This is the only way to create an
alias record pointing to a non-existing file.
The constants for \var{where} and \var{which} can be obtained from the
standard module \var{MACFS}.
\end{funcdesc}
@ -164,7 +169,9 @@ or transmitting to other programs.
Resolve the alias. If the alias was created as a relative alias you
should pass the file relative to which it is. Return the FSSpec for
the file pointed to and a flag indicating whether the alias object
itself was modified during the search process.
itself was modified during the search process. If the file does
not exist but the path leading up to it does exist a valid fsspec
is returned.
\end{funcdesc}
\begin{funcdesc}{GetInfo}{num}

120
Doc/mac/libmacic.tex Normal file
View file

@ -0,0 +1,120 @@
\section{Standard Module \sectcode{ic}}
\bimodindex{ic}
\renewcommand{\indexsubitem}{(in module ic)}
This module provides access to macintosh Internet Config package,
which stores preferences for Internet programs such as mail address,
default homepage, etc. Also, Internet Config contains an elaborate set
of mappings from Macintosh creator/type codes to foreign filename
extensions plus information on how to transfer files (binary, ascii,
etc).
There is a low-level companion module \code{icglue} which provides the
basic ic access functionality. This low-level module is not
documented, but the docstrings of the routines document the parameters
and the routine names are the same as for the Pascal or C API to
Internet Config, so the standard IC programmers documentation can be
used if this module is needed.
The \code{ic} module defines the \code{error} exception and symbolic
names for all error codes IC can produce, see the source for details.
The \code{ic} module defines the following functions:
\begin{funcdesc}{IC}{\optional{signature\, ic}}
Create an internet config object. The signature is a 4-char creator
code of the current application (default \code{'Pyth'}) which may
influence some of ICs settings. The optional \var{ic} argument is a
low-level \code{icinstance} created beforehand, this may be useful if
you want to get preferences from a different config file, etc.
\end{funcdesc}
\begin{funcdesc}{launchurl}{url \optional{\, hint}}
\end{funcdesc}
\begin{funcdesc}{parseurl}{data \optional{\, start\, end\, hint}}
\end{funcdesc}
\begin{funcdesc}{mapfile}{file}
\end{funcdesc}
\begin{funcdesc}{maptypecreator}{type\, creator \optional{\,
filename}}
\end{funcdesc}
\begin{funcdesc}{settypecreator}{file}
These functions are ``shortcuts'' to the methods of the same name,
described below.
\end{funcdesc}
\subsection{IC objects}
IC objects have a mapping interface, hence to obtain the mail address
you simply get \code{ic['MailAddress']}. Assignment also works, and
changes the option in the configuration file.
The module knows about various datatypes, and converts the internal IC
representation to a ``logical'' python datastructure. Running the
\code{ic} module standalone will run a test program that lists all
keys and values in your IC database, this will have to server as
documentation.
If the module does not know how to represent the data it returns an
instance of the \var{ICOpaqueData} type, with the raw data in its
\var{data} attribute. Objects of this type are also acceptable values
for assignment.
Besides the dictionary interface IC objects have the following methods:
\renewcommand{\indexsubitem}{(IC object attribute)}
\begin{funcdesc}{launchurl}{url \optional{\, hint}}
Parse the given URL, lauch the correct application and pass it the
URL. The optional \var{hint} can be a scheme name such as
\code{mailto:}, in which case incomplete URLs are completed with this
scheme (otherwise incomplete URLs are invalid).
\end{funcdesc}
\begin{funcdesc}{parseurl}{data \optional{\, start\, end\, hint}}
Find an URL somewhere in \var{data} and return start position, end
position and the URL. The optional \var{start} and \var{end} can be
used to limit the search, so for instance if a user clicks in a long
textfield you can pass the whole textfield and the click-position in
\var{start} and this routine will return the whole URL in which the
user clicked. \var{Hint} is again an optional scheme used to complete
incomplete URLs.
\end{funcdesc}
\begin{funcdesc}{mapfile}{file}
Return the mapping entry for the given \var{file}, which can be passed
as either a filename or an \var{FSSpec} object, and which need not
exist.
The mapping entry is returned as a tuple \code{(version\, type\,
creator\, postcreator\, flags\, extension\, appname\, postappname\,
mimetype\, entryname)}, where \var{version} is the entry version
number, \var{type} is the 4-char filetype, \var{creator} is the 4-char
creator type, \var{postcreator} is the 4-char creator code of an
optional application to post-process the file after downloading,
\var{flags} are various bits specifying whether to transfer in binary
or ascii and such, \var{extension} is the filename extension for this
file type, \var{appname} is the printable name of the application to
which this file belongs, \var{postappname} is the name of the
postprocessing application, \var{mimetype} is the MIME type of this
file and \var{entryname} is the name of this entry.
\end{funcdesc}
\begin{funcdesc}{maptypecreator}{type\, creator \optional{\,
filename}}
Return the mapping entry for files with given 4-char \var{type} and
\var{creator} codes. The optional \var{filename} may be specified to
further help finding the correct entry (if the creator code is
\code{'????'}, for instance).
The mapping entry is returned in the same format as for \var{mapfile}.
\end{funcdesc}
\begin{funcdesc}{settypecreator}{file}
Given an existing \var{file}, specified either as a filename or as an
\var{FSSpec} record, set its creator and type correctly based on its
extension. The finder is told about the change, so the finder icon
will be updated quickly.
\end{funcdesc}

66
Doc/mac/libmacos.tex
View file

@ -20,48 +20,35 @@ Symbolic names for all known error codes are defined in the standard
module \var{macerrors}.
\end{excdesc}
\begin{funcdesc}{SetHighLevelEventHandler}{handler}
Pass a python function that will be called upon reception of a
high-level event. The previous handler is returned. The handler
function is called with the event as argument.
\begin{funcdesc}{SetEventHandler}{handler}
In the inner interpreter loop Python will occasionally check for events,
unless disabled with \var{ScheduleParams}. With this function you
can pass a Python event-handler function that will be called if an event
is available. The event is passed as parameter and the function should return
non-zero if the event has been fully processed, otherwise event processing
continues (by passing the event to the console window package, for instance).
Note that your event handler is currently only called dependably if
your main event loop is in \var{stdwin}.
Call SetEventHandler without parameter to clear the event handler. Setting
an eventhandler while one is already set is an error.
\end{funcdesc}
\begin{funcdesc}{AcceptHighLevelEvent}{}
Read a high-level event. The return value is a tuple \code{(sender,
refcon, data)}.
\end{funcdesc}
\begin{funcdesc}{SchedParams}{\optional{doint\, evtmask\, besocial\,
interval\, bgyield}}
Influence the interpreter inner loop event handling. \var{Interval}
specifies how often (in seconds, floating point) the interpreter
should enter the event processing code. When true, \var{doint} causes
interrupt (command-dot) checking to be done. \var{Evtmask} tells the
interpreter to do event processing for events in the mask (redraws,
mouseclicks to switch to other applications, etc). \bar{Besocial}
gives other processes a chance to run. They are granted minimal
runtime when Python is in the foreground and \var{bgyield} seconds per
\var{interval} when Python runs in the background.
\begin{funcdesc}{SetScheduleTimes}{fgi\, fgy \optional{\, bgi\, bgy}}
Controls how often the interpreter checks the event queue and how
long it will yield the processor to other processes. \var{fgi}
specifies after how many clicks (one click is one 60th of a second)
the interpreter should check the event queue, and \var{fgy} specifies
for how many clicks the CPU should be yielded when in the
foreground. The optional \var{bgi} and \var{bgy} allow you to specify
different values to use when python runs in the background, otherwise
the background values will be set the the same as the foreground
values. The function returns nothing.
The default values, which are based on minimal empirical testing, are 12, 1, 6
and 2 respectively.
\end{funcdesc}
\begin{funcdesc}{EnableAppswitch}{onoff}
Enable or disable the python event loop, based on the value of
\var{onoff}. The old value is returned. If the event loop is disabled
no time is granted to other applications, checking for command-period
is not performed and it is impossible to switch applications. This
should only be used by programs providing their own complete event
loop.
Note that based on the compiler used to build python it is still
possible to loose events even with the python event loop disabled. If
you have a \code{sys.stdout} window its handler will often also look
in the event queue. Making sure nothing is ever printed works around
this.
All parameters are optional, and default to the current value. The return
value of this function is a tuple with the old values of these options.
Initial defaults are that all processing is enabled, checking is done every
quarter second and the CPU is given up for a quarter second when in the
background.
\end{funcdesc}
\begin{funcdesc}{HandleEvent}{ev}
@ -70,6 +57,9 @@ possibly to the handler for the \code{sys.stdout} window (based on the
compiler used to build python). This allows python programs that do
their own event handling to still have some command-period and
window-switching capability.
If you attempt to call this function from an event handler set through
\code{SetEventHandler} you will get an exception.
\end{funcdesc}
\begin{funcdesc}{GetErrorString}{errno}

27
Doc/mac/libmacui.tex
View file

@ -4,7 +4,9 @@
The \code{EasyDialogs} module contains some simple dialogs for
the Macintosh, modelled after the \code{stdwin} dialogs with similar
names.
names. All routines have an optional parameter \var{id} with which you
can override the DLOG resource used for the dialog, as long as the
item numbers correspond. See the source for details.
The \code{EasyDialogs} module defines the following functions:
@ -170,6 +172,29 @@ The event loop is split into many small parts, each of which can be
overridden. The default methods take care of dispatching events to
windows and dialogs, handling drags and resizes, Apple Events, events
for non-FrameWork windows, etc.
In general, all event handlers should return 1 if the event is fully
handled and 0 otherwise (because the front window was not a FrameWork
window, for instance). This is needed so that update events and such
can be passed on to other windows like the Sioux console window.
Calling \code{MacOS.HandleEvent} is not allowed within \var{our_dispatch}
or its callees, since this may result in an infinite loop if the
code is called through the python inner-loop event handler.
\end{funcdesc}
\begin{funcdesc}{asyncevents}{onoff}
Call this method with a nonzero parameter to enable
asynchronous event handling. This will tell the inner interpreter loop
to call the application event handler \var{async_dispatch} whenever events
are available. This will cause FrameWork window updates and the user
interface to remain working during long computations, but will slow the
interpreter down and may cause surprising results in non-reentrant code
(such as FrameWork itself). By default \var{async_dispatch} will immedeately
call \var{our_dispatch} but you may override this to handle only certain
events asynchronously. Events you do not handle will be passed to Sioux
and such.
The old on/off value is returned.
\end{funcdesc}
\begin{funcdesc}{_quit}{}