Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 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 | |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 11 | \begin{notice} |
| 12 | Specific platforms listed alphabetically, with Linux included in the |
| 13 | \UNIX{} section. |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 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 informations. |
| 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'}. |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 41 | An empty string is returned if the value cannot be determined. |
| 42 | \end{funcdesc} |
| 43 | |
| 44 | \begin{funcdesc}{node}{} |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 45 | Returns the computer's network name (may not be fully qualified!). |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 46 | An empty string is returned if the value cannot be determined. |
| 47 | \end{funcdesc} |
| 48 | |
| 49 | \begin{funcdesc}{platform}{aliased=0, terse=0} |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 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. |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 64 | \end{funcdesc} |
| 65 | |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 66 | \begin{funcdesc}{processor}{} |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 67 | Returns the (real) processor name, e.g. \code{'amdk6'}. |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 68 | |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 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. |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 72 | \end{funcdesc} |
| 73 | |
| 74 | \begin{funcdesc}{python_build}{} |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 75 | Returns a tuple \code{(\var{buildno}, \var{builddate})} stating the |
| 76 | Python build number and date as strings. |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 77 | \end{funcdesc} |
| 78 | |
| 79 | \begin{funcdesc}{python_compiler}{} |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 80 | Returns a string identifying the compiler used for compiling Python. |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 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}{} |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 91 | Returns the Python version as tuple \code{(\var{major}, \var{minor}, |
| 92 | \var{patchlevel})} of strings. |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 93 | |
| 94 | Note that unlike the Python \code{sys.version}, the returned value |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 95 | will always include the patchlevel (it defaults to \code{'0'}). |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 96 | \end{funcdesc} |
| 97 | |
| 98 | \begin{funcdesc}{release}{} |
| 99 | Returns the system's release, e.g. \code{'2.2.0'} or \code{'NT'} |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 100 | An empty string is returned if the value cannot be determined. |
| 101 | \end{funcdesc} |
| 102 | |
| 103 | \begin{funcdesc}{system}{} |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 104 | Returns the system/OS name, e.g. \code{'Linux'}, \code{'Windows'}, |
| 105 | or \code{'Java'}. |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 106 | An empty string is returned if the value cannot be determined. |
| 107 | \end{funcdesc} |
| 108 | |
| 109 | \begin{funcdesc}{system_alias}{system, release, version} |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 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. |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 114 | \end{funcdesc} |
| 115 | |
| 116 | \begin{funcdesc}{version}{} |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 117 | Returns the system's release version, e.g. \code{'\#3 on degas'}. |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 118 | An empty string is returned if the value cannot be determined. |
| 119 | \end{funcdesc} |
| 120 | |
| 121 | \begin{funcdesc}{uname}{} |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 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. |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 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 | |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 133 | |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 134 | \subsection{Java Platform} |
| 135 | |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 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{''}). |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 146 | \end{funcdesc} |
| 147 | |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 148 | |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 149 | \subsection{Windows Platform} |
| 150 | |
| 151 | \begin{funcdesc}{win32_ver}{release='', version='', csd='', ptype=''} |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 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). |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 156 | |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 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. |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 163 | |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 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} |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 169 | \end{funcdesc} |
| 170 | |
| 171 | \subsubsection{Win95/98 specific} |
| 172 | |
| 173 | \begin{funcdesc}{popen}{cmd, mode='r', bufsize=None} |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 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}{}. |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 180 | \end{funcdesc} |
| 181 | |
| 182 | |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 183 | \subsection{Mac OS Platform} |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 184 | |
| 185 | \begin{funcdesc}{mac_ver}{release='', versioninfo=('','',''), machine=''} |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 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})}. |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 190 | |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 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/}. |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 196 | \end{funcdesc} |
| 197 | |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 198 | |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 199 | \subsection{\UNIX{} Platforms} |
| 200 | |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 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. |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 206 | \end{funcdesc} |
| 207 | |
| 208 | |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 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. |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 215 | |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 216 | Note that this function has intimate knowledge of how different |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 217 | libc versions add symbols to the executable is probably only |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 218 | useable for executables compiled using \program{gcc}. |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 219 | |
Fred Drake | 4e21dc9 | 2003-10-21 17:58:55 +0000 | [diff] [blame] | 220 | The file is read and scanned in chunks of \var{chunksize} bytes. |
Brett Cannon | 4fc3855 | 2003-10-14 21:45:59 +0000 | [diff] [blame] | 221 | \end{funcdesc} |