Doc/mac/libmacos.tex

   1 \section{\module{MacOS} ---
   2          Access to Mac OS interpreter features}
   3
   4 \declaremodule{builtin}{MacOS}
   5   \platform{Mac}
   6 \modulesynopsis{Access to Mac OS-specific interpreter features.}
   7
   8
   9 This module provides access to MacOS specific functionality in the
  10 Python interpreter, such as how the interpreter eventloop functions
  11 and the like. Use with care.
  12
  13 Note the capitalization of the module name; this is a historical
  14 artifact.
  15
  16 \begin{datadesc}{runtimemodel}
  17 Always \code{'macho'}, from Python 2.4 on.
  18 In earlier versions of Python the value could
  19 also be \code{'ppc'} for the classic Mac OS 8 runtime model or
  20 \code{'carbon'} for the Mac OS 9 runtime model.
  21 \end{datadesc}
  22
  23 \begin{datadesc}{linkmodel}
  24 The way the interpreter has been linked. As extension modules may be
  25 incompatible between linking models, packages could use this information to give
  26 more decent error messages. The value is one of \code{'static'} for a
  27 statically linked Python, \code{'framework'} for Python in a Mac OS X framework,
  28 \code{'shared'} for Python in a standard unix shared library.
  29 Older Pythons could also have the value
  30 \code{'cfm'} for Mac OS 9-compatible Python.
  31 \end{datadesc}
  32
  33 \begin{excdesc}{Error}
  34 This exception is raised on MacOS generated errors, either from
  35 functions in this module or from other mac-specific modules like the
  36 toolbox interfaces. The arguments are the integer error code (the
  37 \cdata{OSErr} value) and a textual description of the error code.
  38 Symbolic names for all known error codes are defined in the standard
  39 module \refmodule{macerrors}.\refstmodindex{macerrors}
  40 \end{excdesc}
  41
  42
  43 \begin{funcdesc}{GetErrorString}{errno}
  44 Return the textual description of MacOS error code \var{errno}.
  45 \end{funcdesc}
  46
  47 \begin{funcdesc}{DebugStr}{message \optional{, object}}
  48 On Mac OS X the string is simply printed to stderr (on older
  49 Mac OS systems more elaborate functionality was available),
  50 but it provides a convenient location to attach a breakpoint
  51 in a low-level debugger like \program{gdb}.
  52 \end{funcdesc}
  53
  54 \begin{funcdesc}{SysBeep}{}
  55 Ring the bell.
  56 \end{funcdesc}
  57
  58 \begin{funcdesc}{GetTicks}{}
  59 Get the number of clock ticks (1/60th of a second) since system boot.
  60 \end{funcdesc}
  61
  62 \begin{funcdesc}{GetCreatorAndType}{file}
  63 Return the file creator and file type as two four-character strings.
  64 The \var{file} parameter can be a pathname or an \code{FSSpec} or
  65 \code{FSRef} object.
  66 \end{funcdesc}
  67
  68 \begin{funcdesc}{SetCreatorAndType}{file, creator, type}
  69 Set the file creator and file type.
  70 The \var{file} parameter can be a pathname or an \code{FSSpec} or
  71 \code{FSRef} object. \var{creator} and \var{type} must be four character
  72 strings.
  73 \end{funcdesc}
  74
  75 \begin{funcdesc}{openrf}{name \optional{, mode}}
  76 Open the resource fork of a file. Arguments are the same as for the
  77 built-in function \function{open()}. The object returned has file-like
  78 semantics, but it is not a Python file object, so there may be subtle
  79 differences.
  80 \end{funcdesc}
  81
  82 \begin{funcdesc}{WMAvailable}{}
  83 Checks whether the current process has access to the window manager.
  84 The method will return \code{False} if the window manager is not available,
  85 for instance when running on Mac OS X Server or when logged in via ssh,
  86 or when the current interpreter is not running from a fullblown application
  87 bundle. A script runs from an application bundle either when it has been
  88 started with \program{pythonw} instead of \program{python} or when running
  89 as an applet.
  90 \end{funcdesc}