[Python-checkins] r59281 - in python/trunk/Doc: ACKS.txt c-api/init.rst c-api/utilities.rst data/refcounts.dat

[georg.brandl]

Author: georg.brandl
Date: Sun Dec  2 22:58:54 2007
New Revision: 59281

Modified:
   python/trunk/Doc/ACKS.txt
   python/trunk/Doc/c-api/init.rst
   python/trunk/Doc/c-api/utilities.rst
   python/trunk/Doc/data/refcounts.dat
Log:
Add documentation for PySys_* functions.
Written by Charlie Shepherd for GHOP. Also fixes #1245.


Modified: python/trunk/Doc/ACKS.txt
==============================================================================
--- python/trunk/Doc/ACKS.txt	(original)
+++ python/trunk/Doc/ACKS.txt	Sun Dec  2 22:58:54 2007
@@ -160,6 +160,7 @@
 * Barry Scott
 * Joakim Sernbrant
 * Justin Sheehy
+* Charlie Shepherd
 * Michael Simcich
 * Ionel Simionescu
 * Michael Sloan

Modified: python/trunk/Doc/c-api/init.rst
==============================================================================
--- python/trunk/Doc/c-api/init.rst	(original)
+++ python/trunk/Doc/c-api/init.rst	Sun Dec  2 22:58:54 2007
@@ -364,8 +364,6 @@
    .. % XXX impl. doesn't seem consistent in allowing 0/NULL for the params;
    .. % check w/ Guido.
 
-.. % XXX Other PySys thingies (doesn't really belong in this chapter)
-
 
 .. _threads:
 

Modified: python/trunk/Doc/c-api/utilities.rst
==============================================================================
--- python/trunk/Doc/c-api/utilities.rst	(original)
+++ python/trunk/Doc/c-api/utilities.rst	Sun Dec  2 22:58:54 2007
@@ -66,6 +66,66 @@
    not call those functions directly!  :ctype:`PyOS_sighandler_t` is a typedef
    alias for :ctype:`void (\*)(int)`.
 
+.. _systemfunctions:
+
+System Functions
+================
+
+These are utility functions that make functionality from the :mod:`sys` module
+accessible to C code.  They all work with the current interpreter thread's
+:mod:`sys` module's dict, which is contained in the internal thread state structure.
+
+.. cfunction:: PyObject *PySys_GetObject(char *name)
+
+   Return the object *name* from the :mod:`sys` module or *NULL* if it does
+   not exist, without setting an exception.
+
+.. cfunction:: FILE *PySys_GetFile(char *name, FILE *def)
+
+   Return the :ctype:`FILE*` associated with the object *name* in the
+   :mod:`sys` module, or *def* if *name* is not in the module or is not associated
+   with a :ctype:`FILE*`.
+
+.. cfunction:: int PySys_SetObject(char *name, PyObject *v)
+
+   Set *name* in the :mod:`sys` module to *v* unless *v* is *NULL*, in which
+   case *name* is deleted from the sys module. Returns ``0`` on success, ``-1``
+   on error.
+
+.. cfunction:: void PySys_ResetWarnOptions(void)
+
+   Reset :data:`sys.warnoptions` to an empty list.
+
+.. cfunction:: void PySys_AddWarnOption(char *s)
+
+   Append *s* to :data:`sys.warnoptions`.
+
+.. cfunction:: void PySys_SetPath(char *path)
+
+   Set :data:`sys.path` to a list object of paths found in *path* which should
+   be a list of paths separated with the platform's search path delimiter
+   (``:`` on Unix, ``;`` on Windows).
+
+.. cfunction:: void PySys_WriteStdout(const char *format, ...)
+
+   Write the output string described by *format* to :data:`sys.stdout`.  No
+   exceptions are raised, even if truncation occurs (see below).
+
+   *format* should limit the total size of the formatted output string to
+   1000 bytes or less -- after 1000 bytes, the output string is truncated.
+   In particular, this means that no unrestricted "%s" formats should occur;
+   these should be limited using "%.<N>s" where <N> is a decimal number
+   calculated so that <N> plus the maximum size of other formatted text does not
+   exceed 1000 bytes.  Also watch out for "%f", which can print hundreds of
+   digits for very large numbers.
+
+   If a problem occurs, or :data:`sys.stdout` is unset, the formatted message
+   is written to the real (C level) *stdout*.
+
+.. cfunction:: void PySys_WriteStderr(const char *format, ...)
+
+   As above, but write to :data:`sys.stderr` or *stderr* instead.
+
 
 .. _processcontrol:
 

Modified: python/trunk/Doc/data/refcounts.dat
==============================================================================
--- python/trunk/Doc/data/refcounts.dat	(original)
+++ python/trunk/Doc/data/refcounts.dat	Sun Dec  2 22:58:54 2007
@@ -1251,10 +1251,32 @@
 PyString_AsEncodedString:const char*:encoding::
 PyString_AsEncodedString:const char*:errors::
 
+PySys_AddWarnOption:void:::
+PySys_AddWarnOption:char*:s::
+
+PySys_GetFile:FILE*:::
+PySys_GetFile:char*:name::
+PySys_GetFile:FILE*:def::
+
+PySys_GetObject:PyObject*::0:
+PySys_GetObject:char*:name::
+
 PySys_SetArgv:int:::
 PySys_SetArgv:int:argc::
 PySys_SetArgv:char**:argv::
 
+PySys_SetObject:int:::
+PySys_SetObject:char*:name::
+PySys_SetObject:PyObject*:v:+1:
+
+PySys_ResetWarnOptions:void:::
+
+PySys_WriteStdout:void:::
+PySys_WriteStdout:char*:format::
+
+PySys_WriteStderr:void:::
+PySys_WriteStderr:char*:format::
+
 PyThreadState_Clear:void:::
 PyThreadState_Clear:PyThreadState*:tstate::