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.

1 files changed, 223 insertions, 0 deletions

diff --git a/Doc/lib/libplatform.tex b/Doc/lib/libplatform.tex
new file mode 100644
index 0000000..3c78eb5
--- /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}