From 4fc3855fb2518c890c053139a73f913359479970 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Tue, 14 Oct 2003 21:45:59 +0000 Subject: [PATCH] Initial checkin of docs for Lib/platform.py . Closes patch #785752 and bug #726911. Should be backported after correctness and such has been verified by Fred. --- Doc/lib/lib.tex | 1 + Doc/lib/libplatform.tex | 223 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 224 insertions(+) create mode 100644 Doc/lib/libplatform.tex diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 4d71d9347a8..c8cb73bc810 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -163,6 +163,7 @@ and how to embed it in other applications. \input{liblocale} \input{libgettext} \input{liblogging} +\input{libplatform} \input{libsomeos} % Optional Operating System Services \input{libsignal} diff --git a/Doc/lib/libplatform.tex b/Doc/lib/libplatform.tex new file mode 100644 index 00000000000..3c78eb53614 --- /dev/null +++ b/Doc/lib/libplatform.tex @@ -0,0 +1,223 @@ +\section{\module{platform} --- + Access to underlying platform's identifying data.} + +\declaremodule{standard}{platform} +\modulesynopsis{Retrieves as much platform identifying data as possible.} +\moduleauthor{Marc-Andre Lemburg}{mal@egenix.com} +\sectionauthor{Bjorn Pettersen}{bpettersen@corp.fairisaac.com} + +\versionadded{2.3} + +\begin{notice}[note] + Specific platforms listed alphabetically, with Linux included in the \UNIX + section. +\end{notice} + +\subsection{Cross Platform} + +\begin{funcdesc}{architecture}{executable=sys.executable, bits='', linkage=''} + Queries the given executable (defaults to the Python interpreter + binary) for various architecture informations. + + Returns a tuple \code{(bits, linkage)} which contain information about + the bit architecture and the linkage format used for the + executable. Both values are returned as strings. + + Values that cannot be determined are returned as given by the + parameter presets. If bits is given as \code{''}, the + \cfunction{sizeof(pointer)} + (or \cfunction{sizeof(long)} on Python version < 1.5.2) is used as + indicator for the supported pointer size. + + The function relies on the system's \file{file} command to do the + actual work. This is available on most if not all \UNIX{} + platforms and some non-\UNIX{} platforms and then only if the + executable points to the Python interpreter. Reasonable defaults + are used when the above needs are not met. +\end{funcdesc} + +\begin{funcdesc}{machine}{} + Returns the machine type, e.g. \code{'i386'}. + + An empty string is returned if the value cannot be determined. +\end{funcdesc} + +\begin{funcdesc}{node}{} + Returns the computer's network name (may not be fully qualified!) + + An empty string is returned if the value cannot be determined. +\end{funcdesc} + +\begin{funcdesc}{platform}{aliased=0, terse=0} + Returns a single string identifying the underlying platform + with as much useful information as possible. + + The output is intended to be \emph{human readable} rather than + machine parseable. It may look different on different + platforms and this is intended. + + If \code{aliased} is true, the function will use aliases for + various platforms that report system names which differ from + their common names, e.g. SunOS will be reported as + Solaris. The \function{system_alias()} function is used to implement + this. + + Setting terse to true causes the function to return only the + absolute minimum information needed to identify the platform. +\end{funcdesc} + + +\begin{funcdesc}{processor}{} + Returns the (real) processor name, e.g. 'amdk6' + + An empty string is returned if the value cannot be + determined. Note that many platforms do not provide this + information or simply return the same value as for \function{machine()}, + e.g. NetBSD does this. +\end{funcdesc} + +\begin{funcdesc}{python_build}{} + Returns a tuple \code{(buildno, builddate)} stating the Python + build number and date as strings. +\end{funcdesc} + +\begin{funcdesc}{python_compiler}{} + Returns a string identifying the compiler used for compiling + Python. +\end{funcdesc} + +\begin{funcdesc}{python_version}{} + Returns the Python version as string \code{'major.minor.patchlevel'} + + Note that unlike the Python \code{sys.version}, the returned value + will always include the patchlevel (it defaults to 0). +\end{funcdesc} + +\begin{funcdesc}{python_version_tuple}{} + Returns the Python version as tuple \code{(major, minor, patchlevel)} + of strings. + + Note that unlike the Python \code{sys.version}, the returned value + will always include the patchlevel (it defaults to 0). +\end{funcdesc} + +\begin{funcdesc}{release}{} + Returns the system's release, e.g. \code{'2.2.0'} or \code{'NT'} + + An empty string is returned if the value cannot be determined. +\end{funcdesc} + +\begin{funcdesc}{system}{} + Returns the system/OS name, e.g. \code{'Linux'}, \code{'Windows'}, or \code{'Java'}. + + An empty string is returned if the value cannot be determined. +\end{funcdesc} + +\begin{funcdesc}{system_alias}{system, release, version} + Returns \code{(system, release, version)} aliased to common + marketing names used for some systems. + + It also does some reordering of the information in some cases + where it would otherwise cause confusion. +\end{funcdesc} + +\begin{funcdesc}{version}{} + Returns the system's release version, e.g. \code{'#3 on degas'}. + + An empty string is returned if the value cannot be determined. +\end{funcdesc} + +\begin{funcdesc}{uname}{} + Fairly portable uname interface. Returns a tuple + of strings \code{(system, node, release, version, machine, processor)} + identifying the underlying platform. + + Note that unlike the \function{os.uname()} function this also returns + possible processor information as additional tuple entry. + + Entries which cannot be determined are set to \code{''}. +\end{funcdesc} + +\subsection{Java Platform} + +\begin{funcdesc}{java_ver}{release='', vendor='', vminfo=('','',''), osinfo=('','','')} + Version interface for JPython. + + Returns a tuple \code{(release, vendor, vminfo, osinfo)} with vminfo being + a tuple \code{(vm_name, vm_release, vm_vendor)} and osinfo being a + tuple \code{(os_name, os_version, os_arch)}. + + Values which cannot be determined are set to the defaults + given as parameters (which all default to \code{''}). +\end{funcdesc} + +\subsection{Windows Platform} + +\begin{funcdesc}{win32_ver}{release='', version='', csd='', ptype=''} + Get additional version information from the Windows Registry + and return a tuple \code{(version, csd, ptype)} referring to version + number, CSD level and OS type (multi/single processor). + + As a hint: ptype returns \code{'Uniprocessor Free'} on single + processor NT machines and \code{'Multiprocessor Free'} on multi + processor machines. The \emph{'Free'} refers to the OS version being + free of debugging code. It could also state \emph{'Checked'} which + means the OS version uses debugging code, i.e. code that + checks arguments, ranges, etc. + +\begin{notice}[note] + This function only works if Mark Hammond's \module{win32all} + package is installed and (obviously) only runs on Win32 + compatible platforms. +\end{notice} + +\end{funcdesc} + +\subsubsection{Win95/98 specific} + +\begin{funcdesc}{popen}{cmd, mode='r', bufsize=None} + Portable \function{popen()} interface. + Find a working popen implementation preferring \function{win32pipe.popen}. + On NT \function{win32pipe} should work; on Win9x + it hangs due to bugs in the MS C lib. + \seetext{MS KnowledgeBase article Q150956.} +\end{funcdesc} + + +\subsection{Mac Platform} + +\begin{funcdesc}{mac_ver}{release='', versioninfo=('','',''), machine=''} + Get MacOS version information and return it as tuple \code{(release, + versioninfo, machine)} with versioninfo being a tuple \code{(version, + dev_stage, non_release_version)}. + + Entries which cannot be determined are set to \code{''}. All tuple + entries are strings. + + Documentation for the underlying gestalt() API is available online + at \url{http://www.rgaros.nl/gestalt/} +\end{funcdesc} + +\subsection{\UNIX{} Platforms} + +\begin{funcdesc}{dist}{distname='',version='',id='',supported_dists=('SuSE','debian','redhat','mandrake')} + Tries to determine the name of the OS distribution name + + Returns a tuple \code{(distname, version, id)} which defaults to the + args given as parameters. +\end{funcdesc} + + +\begin{funcdesc}{libc_ver}{executable=sys.executable, lib='', version='', chunksize=2048} + Tries to determine the libc version against which the + file executable (defaults to the Python interpreter) is linked. + + Returns a tuple of strings \code{(lib, version)} which default to the + given parameters in case the lookup fails. + + Note that the function has intimate knowledge of how different + libc versions add symbols to the executable is probably only + useable for executables compiled using \emph{gcc}. + + The file is read and scanned in chunks of chunksize bytes. +\end{funcdesc}