Doc/lib/libplatform.tex

   1 \section{\module{platform} ---
   2    Access to underlying platform's identifying data.}
   3
   4 \declaremodule{standard}{platform}
   5 \modulesynopsis{Retrieves as much platform identifying data as possible.}
   6 \moduleauthor{Marc-Andre Lemburg}{mal@egenix.com}
   7 \sectionauthor{Bjorn Pettersen}{bpettersen@corp.fairisaac.com}
   8
   9 \versionadded{2.3}
  10
  11 \begin{notice}
  12   Specific platforms listed alphabetically, with Linux included in the
  13   \UNIX{} section.
  14 \end{notice}
  15
  16 \subsection{Cross Platform}
  17
  18 \begin{funcdesc}{architecture}{executable=sys.executable, bits='', linkage=''}
  19   Queries the given executable (defaults to the Python interpreter
  20   binary) for various architecture information.
  21
  22   Returns a tuple \code{(bits, linkage)} which contain information about
  23   the bit architecture and the linkage format used for the
  24   executable. Both values are returned as strings.
  25
  26   Values that cannot be determined are returned as given by the
  27   parameter presets. If bits is given as \code{''}, the
  28   \cfunction{sizeof(pointer)}
  29   (or \cfunction{sizeof(long)} on Python version < 1.5.2) is used as
  30   indicator for the supported pointer size.
  31
  32   The function relies on the system's \file{file} command to do the
  33   actual work. This is available on most if not all \UNIX{}
  34   platforms and some non-\UNIX{} platforms and then only if the
  35   executable points to the Python interpreter.  Reasonable defaults
  36   are used when the above needs are not met.
  37 \end{funcdesc}
  38
  39 \begin{funcdesc}{machine}{}
  40   Returns the machine type, e.g. \code{'i386'}.
  41   An empty string is returned if the value cannot be determined.
  42 \end{funcdesc}
  43
  44 \begin{funcdesc}{node}{}
  45   Returns the computer's network name (may not be fully qualified!).
  46   An empty string is returned if the value cannot be determined.
  47 \end{funcdesc}
  48
  49 \begin{funcdesc}{platform}{aliased=0, terse=0}
  50   Returns a single string identifying the underlying platform
  51   with as much useful information as possible.
  52
  53   The output is intended to be \emph{human readable} rather than
  54   machine parseable. It may look different on different platforms and
  55   this is intended.
  56
  57   If \var{aliased} is true, the function will use aliases for various
  58   platforms that report system names which differ from their common
  59   names, for example SunOS will be reported as Solaris.  The
  60   \function{system_alias()} function is used to implement this.
  61
  62   Setting \var{terse} to true causes the function to return only the
  63   absolute minimum information needed to identify the platform.
  64 \end{funcdesc}
  65
  66 \begin{funcdesc}{processor}{}
  67   Returns the (real) processor name, e.g. \code{'amdk6'}.
  68
  69   An empty string is returned if the value cannot be determined. Note
  70   that many platforms do not provide this information or simply return
  71   the same value as for \function{machine()}.  NetBSD does this.
  72 \end{funcdesc}
  73
  74 \begin{funcdesc}{python_build}{}
  75   Returns a tuple \code{(\var{buildno}, \var{builddate})} stating the
  76   Python build number and date as strings.
  77 \end{funcdesc}
  78
  79 \begin{funcdesc}{python_compiler}{}
  80   Returns a string identifying the compiler used for compiling Python.
  81 \end{funcdesc}
  82
  83 \begin{funcdesc}{python_version}{}
  84   Returns the Python version as string \code{'major.minor.patchlevel'}
  85
  86   Note that unlike the Python \code{sys.version}, the returned value
  87   will always include the patchlevel (it defaults to 0).
  88 \end{funcdesc}
  89
  90 \begin{funcdesc}{python_version_tuple}{}
  91   Returns the Python version as tuple \code{(\var{major}, \var{minor},
  92   \var{patchlevel})} of strings.
  93
  94   Note that unlike the Python \code{sys.version}, the returned value
  95   will always include the patchlevel (it defaults to \code{'0'}).
  96 \end{funcdesc}
  97
  98 \begin{funcdesc}{release}{}
  99   Returns the system's release, e.g. \code{'2.2.0'} or \code{'NT'}
 100   An empty string is returned if the value cannot be determined.
 101 \end{funcdesc}
 102
 103 \begin{funcdesc}{system}{}
 104   Returns the system/OS name, e.g. \code{'Linux'}, \code{'Windows'},
 105   or \code{'Java'}.
 106   An empty string is returned if the value cannot be determined.
 107 \end{funcdesc}
 108
 109 \begin{funcdesc}{system_alias}{system, release, version}
 110   Returns \code{(\var{system}, \var{release}, \var{version})} aliased
 111   to common marketing names used for some systems.  It also does some
 112   reordering of the information in some cases where it would otherwise
 113   cause confusion.
 114 \end{funcdesc}
 115
 116 \begin{funcdesc}{version}{}
 117   Returns the system's release version, e.g. \code{'\#3 on degas'}.
 118   An empty string is returned if the value cannot be determined.
 119 \end{funcdesc}
 120
 121 \begin{funcdesc}{uname}{}
 122   Fairly portable uname interface. Returns a tuple of strings
 123   \code{(\var{system}, \var{node}, \var{release}, \var{version},
 124   \var{machine}, \var{processor})} identifying the underlying
 125   platform.
 126
 127   Note that unlike the \function{os.uname()} function this also returns
 128   possible processor information as additional tuple entry.
 129
 130   Entries which cannot be determined are set to \code{''}.
 131 \end{funcdesc}
 132
 133
 134 \subsection{Java Platform}
 135
 136 \begin{funcdesc}{java_ver}{release='', vendor='', vminfo=('','',''),
 137                            osinfo=('','','')}
 138   Version interface for JPython.
 139
 140   Returns a tuple \code{(\var{release}, \var{vendor}, \var{vminfo},
 141   \var{osinfo})} with \var{vminfo} being a tuple \code{(\var{vm_name},
 142   \var{vm_release}, \var{vm_vendor})} and \var{osinfo} being a tuple
 143   \code{(\var{os_name}, \var{os_version}, \var{os_arch})}.
 144   Values which cannot be determined are set to the defaults
 145   given as parameters (which all default to \code{''}).
 146 \end{funcdesc}
 147
 148
 149 \subsection{Windows Platform}
 150
 151 \begin{funcdesc}{win32_ver}{release='', version='', csd='', ptype=''}
 152   Get additional version information from the Windows Registry
 153   and return a tuple \code{(\var{version}, \var{csd}, \var{ptype})}
 154   referring to version number, CSD level and OS type (multi/single
 155   processor).
 156
 157   As a hint: \var{ptype} is \code{'Uniprocessor Free'} on single
 158   processor NT machines and \code{'Multiprocessor Free'} on multi
 159   processor machines. The \emph{'Free'} refers to the OS version being
 160   free of debugging code. It could also state \emph{'Checked'} which
 161   means the OS version uses debugging code, i.e. code that
 162   checks arguments, ranges, etc.
 163
 164   \begin{notice}[note]
 165     This function only works if Mark Hammond's \module{win32all}
 166     package is installed and (obviously) only runs on Win32
 167     compatible platforms.
 168   \end{notice}
 169 \end{funcdesc}
 170
 171 \subsubsection{Win95/98 specific}
 172
 173 \begin{funcdesc}{popen}{cmd, mode='r', bufsize=None}
 174   Portable \function{popen()} interface.  Find a working popen
 175   implementation preferring \function{win32pipe.popen()}.  On Windows
 176   NT, \function{win32pipe.popen()} should work; on Windows 9x it hangs
 177   due to bugs in the MS C library.
 178   % This KnowledgeBase article appears to be missing...
 179   %See also \ulink{MS KnowledgeBase article Q150956}{}.
 180 \end{funcdesc}
 181
 182
 183 \subsection{Mac OS Platform}
 184
 185 \begin{funcdesc}{mac_ver}{release='', versioninfo=('','',''), machine=''}
 186   Get Mac OS version information and return it as tuple
 187   \code{(\var{release}, \var{versioninfo}, \var{machine})} with
 188   \var{versioninfo} being a tuple \code{(\var{version},
 189   \var{dev_stage}, \var{non_release_version})}.
 190
 191   Entries which cannot be determined are set to \code{''}.  All tuple
 192   entries are strings.
 193
 194   Documentation for the underlying \cfunction{gestalt()} API is
 195   available online at \url{http://www.rgaros.nl/gestalt/}.
 196 \end{funcdesc}
 197
 198
 199 \subsection{\UNIX{} Platforms}
 200
 201 \begin{funcdesc}{dist}{distname='', version='', id='',
 202                        supported_dists=('SuSE','debian','redhat','mandrake')}
 203   Tries to determine the name of the OS distribution name
 204   Returns a tuple \code{(\var{distname}, \var{version}, \var{id})}
 205   which defaults to the args given as parameters.
 206 \end{funcdesc}
 207
 208
 209 \begin{funcdesc}{libc_ver}{executable=sys.executable, lib='',
 210                            version='', chunksize=2048}
 211   Tries to determine the libc version against which the file
 212   executable (defaults to the Python interpreter) is linked.  Returns
 213   a tuple of strings \code{(\var{lib}, \var{version})} which default
 214   to the given parameters in case the lookup fails.
 215
 216   Note that this function has intimate knowledge of how different
 217   libc versions add symbols to the executable is probably only
 218   useable for executables compiled using \program{gcc}.
 219
 220   The file is read and scanned in chunks of \var{chunksize} bytes.
 221 \end{funcdesc}