[pypy-svn] r29147 - in pypy/dist/pypy/module: _weakref gc marshal posix select sys thread time

arigo at codespeak.net arigo at codespeak.net
Thu Jun 22 17:34:30 CEST 2006


Author: arigo
Date: Thu Jun 22 17:34:28 2006
New Revision: 29147

Modified:
   pypy/dist/pypy/module/_weakref/interp__weakref.py
   pypy/dist/pypy/module/gc/app_gc.py
   pypy/dist/pypy/module/gc/interp_gc.py
   pypy/dist/pypy/module/marshal/interp_marshal.py
   pypy/dist/pypy/module/posix/interp_posix.py
   pypy/dist/pypy/module/select/app_select.py
   pypy/dist/pypy/module/select/interp_select.py
   pypy/dist/pypy/module/sys/app.py
   pypy/dist/pypy/module/sys/hook.py
   pypy/dist/pypy/module/sys/vm.py
   pypy/dist/pypy/module/thread/os_lock.py
   pypy/dist/pypy/module/time/interp_time.py
Log:
issue22 resolved

Finished adding docstrings on functions of built-in modules.


Modified: pypy/dist/pypy/module/_weakref/interp__weakref.py
==============================================================================
--- pypy/dist/pypy/module/_weakref/interp__weakref.py	(original)
+++ pypy/dist/pypy/module/_weakref/interp__weakref.py	Thu Jun 22 17:34:28 2006
@@ -139,6 +139,9 @@
     return space.not_(space.eq(ref1, ref2))
 
 W_Weakref.typedef = TypeDef("weakref",
+    __doc__ = """A weak reference to an object 'obj'.  A 'callback' can given,
+which is called with the weak reference as an argument when 'obj'
+is about to be finalized.""",
     __new__ = interp2app(descr__new__weakref),
     __eq__ = interp2app(descr__eq__,
                         unwrap_spec=[ObjSpace, W_Weakref, W_Weakref]),
@@ -150,6 +153,7 @@
 
 
 def getweakrefcount(space, w_obj):
+    """Return the number of weak references to 'obj'."""
     lifeline = w_obj.getweakref()
     if lifeline is None:
         return space.wrap(0)
@@ -161,6 +165,7 @@
         return space.wrap(result)
 
 def getweakrefs(space, w_obj):
+    """Return a list of all weak reference objects that point to 'obj'."""
     lifeline = w_obj.getweakref()
     if lifeline is None:
         return space.newlist([])
@@ -186,6 +191,9 @@
         return space.call_args(w_obj, __args__)
 
 def proxy(space, w_obj, w_callable=None):
+    """Create a proxy object that weakly references 'obj'.
+'callback', if given, is called with the proxy as an argument when 'obj'
+is about to be finalized."""
     lifeline = w_obj.getweakref()
     if lifeline is None:
         lifeline = WeakrefLifeline()

Modified: pypy/dist/pypy/module/gc/app_gc.py
==============================================================================
--- pypy/dist/pypy/module/gc/app_gc.py	(original)
+++ pypy/dist/pypy/module/gc/app_gc.py	Thu Jun 22 17:34:28 2006
@@ -1,9 +1,9 @@
 
 def isenabled():
-    pass
+    "Not implemented."
 
 def enable():
-    pass
+    "Not implemented."
 
 def disable():
-    pass
+    "Not implemented."

Modified: pypy/dist/pypy/module/gc/interp_gc.py
==============================================================================
--- pypy/dist/pypy/module/gc/interp_gc.py	(original)
+++ pypy/dist/pypy/module/gc/interp_gc.py	Thu Jun 22 17:34:28 2006
@@ -3,6 +3,7 @@
 import gc
 
 def collect(space):
+    "Run a full collection."
     gc.collect()
     
 collect.unwrap_spec = [ObjSpace]

Modified: pypy/dist/pypy/module/marshal/interp_marshal.py
==============================================================================
--- pypy/dist/pypy/module/marshal/interp_marshal.py	(original)
+++ pypy/dist/pypy/module/marshal/interp_marshal.py	Thu Jun 22 17:34:28 2006
@@ -13,6 +13,7 @@
 Py_MARSHAL_VERSION = 1
 
 def dump(space, w_data, w_f, w_version=Py_MARSHAL_VERSION):
+    """Write the 'data' object into the open file 'f'."""
     writer = FileWriter(space, w_f)
     # note: bound methods are currently not supported,
     # so we have to pass the instance in, instead.
@@ -21,16 +22,21 @@
     m.put_w_obj(w_data)
 
 def dumps(space, w_data, w_version=Py_MARSHAL_VERSION):
+    """Return the string that would have been written to a file
+by dump(data, file)."""
     m = StringMarshaller(space, space.int_w(w_version))
     m.put_w_obj(w_data)
     return space.wrap(m.get_value())
 
 def load(space, w_f):
+    """Read one value from the file 'f' and return it."""
     reader = FileReader(space, w_f)
     u = Unmarshaller(space, reader)
     return u.get_w_obj(False)
 
 def loads(space, w_str):
+    """Convert a string back to a value.  Extra characters in the string are
+ignored."""
     u = StringUnmarshaller(space, w_str)
     return u.get_w_obj(False)
 

Modified: pypy/dist/pypy/module/posix/interp_posix.py
==============================================================================
--- pypy/dist/pypy/module/posix/interp_posix.py	(original)
+++ pypy/dist/pypy/module/posix/interp_posix.py	Thu Jun 22 17:34:28 2006
@@ -19,6 +19,8 @@
     return OperationError(space.w_OSError, w_error)
                           
 def open(space, fname, flag, mode=0777):
+    """Open a file (for low level IO).
+Return a file descriptor (a small integer)."""
     try: 
         fd = os.open(fname, flag, mode)
     except OSError, e: 
@@ -27,6 +29,9 @@
 open.unwrap_spec = [ObjSpace, str, int, int]
 
 def lseek(space, fd, pos, how):
+    """Set the current position of a file descriptor.  Return the new position.
+If how == 0, 'pos' is relative to the start of the file; if how == 1, to the
+current position; if how == 2, to the end."""
     try:
         pos = os.lseek(fd, pos, how)
     except OSError, e: 
@@ -36,6 +41,8 @@
 lseek.unwrap_spec = [ObjSpace, int, int, int]
 
 def isatty(space, fd):
+    """Return True if 'fd' is an open file descriptor connected to the
+slave end of a terminal."""
     try:
         res = os.isatty(fd)
     except OSError, e: 
@@ -45,6 +52,7 @@
 isatty.unwrap_spec = [ObjSpace, int]
 
 def read(space, fd, buffersize):
+    """Read data from a file descriptor."""
     try: 
         s = os.read(fd, buffersize)
     except OSError, e: 
@@ -54,6 +62,8 @@
 read.unwrap_spec = [ObjSpace, int, int]
 
 def write(space, fd, data):
+    """Write a string to a file descriptor.  Return the number of bytes
+actually written, which may be smaller than len(data)."""
     try: 
         res = os.write(fd, data)
     except OSError, e: 
@@ -63,6 +73,7 @@
 write.unwrap_spec = [ObjSpace, int, str]
 
 def close(space, fd):
+    """Close a file descriptor (for low level IO)."""
     try: 
         os.close(fd)
     except OSError, e: 
@@ -70,6 +81,7 @@
 close.unwrap_spec = [ObjSpace, int]
 
 def ftruncate(space, fd, length):
+    """Truncate a file to a specified length."""
     try:
         os.ftruncate(fd, length)
     except OSError, e: 
@@ -86,6 +98,8 @@
     return space.call_function(w_stat_result, w_tuple)
 
 def fstat(space, fd):
+    """Perform a stat system call on the file referenced to by an open
+file descriptor."""
     try:
         st = os.fstat(fd)
     except OSError, e: 
@@ -95,6 +109,20 @@
 fstat.unwrap_spec = [ObjSpace, int]
 
 def stat(space, path):
+    """Perform a stat system call on the given path.  Return an object
+with (at least) the following attributes:
+    st_mode
+    st_ino
+    st_dev
+    st_nlink
+    st_uid
+    st_gid
+    st_size
+    st_atime
+    st_mtime
+    st_ctime
+"""
+
     try:
         st = os.stat(path)
     except OSError, e: 
@@ -104,6 +132,8 @@
 stat.unwrap_spec = [ObjSpace, str]
 
 def dup(space, fd):
+    """Create a copy of the file descriptor.  Return the new file
+descriptor."""
     try:
         newfd = os.dup(fd)
     except OSError, e: 
@@ -113,9 +143,7 @@
 dup.unwrap_spec = [ObjSpace, int]
 
 def system(space, cmd):
-    """system(command) -> exit_status
-
-Execute the command (a string) in a subshell."""
+    """Execute the command (a string) in a subshell."""
     try:
         rc = os.system(cmd)
     except OSError, e: 
@@ -125,9 +153,7 @@
 system.unwrap_spec = [ObjSpace, str]
 
 def unlink(space, path):
-    """unlink(path)
-
-Remove a file (same as remove(path))."""
+    """Remove a file (same as remove(path))."""
     try:
         os.unlink(path)
     except OSError, e: 
@@ -135,9 +161,7 @@
 unlink.unwrap_spec = [ObjSpace, str]
 
 def remove(space, path):
-    """remove(path)
-
-Remove a file (same as unlink(path))."""
+    """Remove a file (same as unlink(path))."""
     try:
         os.unlink(path)
     except OSError, e: 
@@ -145,6 +169,7 @@
 remove.unwrap_spec = [ObjSpace, str]
 
 def getcwd(space):
+    """Return the current working directory."""
     try:
         cur = os.getcwd()
     except OSError, e: 
@@ -154,9 +179,7 @@
 getcwd.unwrap_spec = [ObjSpace]
 
 def chdir(space, path):
-    """chdir(path)
-
-Change the current working directory to the specified path."""
+    """Change the current working directory to the specified path."""
     try:
         os.chdir(path)
     except OSError, e: 
@@ -164,9 +187,7 @@
 chdir.unwrap_spec = [ObjSpace, str]
 
 def mkdir(space, path, mode=0777):
-    """mkdir(path [, mode=0777])
-
-Create a directory."""
+    """Create a directory."""
     try:
         os.mkdir(path, mode)
     except OSError, e: 
@@ -174,9 +195,7 @@
 mkdir.unwrap_spec = [ObjSpace, str, int]
 
 def rmdir(space, path):
-    """rmdir(path)
-
-Remove a directory."""
+    """Remove a directory."""
     try:
         os.rmdir(path)
     except OSError, e: 
@@ -184,7 +203,7 @@
 rmdir.unwrap_spec = [ObjSpace, str]
 
 def strerror(space, errno):
-    'strerror(code) -> string\n\nTranslate an error code to a message string.'
+    """Translate an error code to a message string."""
     try:
         text = os.strerror(errno)
     except ValueError:
@@ -221,9 +240,7 @@
         idx += 1
 
 def putenv(space, name, value):
-    """putenv(key, value)
-
-Change or add an environment variable."""
+    """Change or add an environment variable."""
     txt = '%s=%s' % (name, value)
     ros.putenv(txt)
     # Install the first arg and newstr in posix_putenv_garbage;
@@ -234,9 +251,7 @@
 putenv.unwrap_spec = [ObjSpace, str, str]
 
 def unsetenv(space, name):
-    """unsetenv(key)
-
-Delete an environment variable."""
+    """Delete an environment variable."""
     if name in get(space).posix_putenv_garbage:
         os.unsetenv(name)
         # Remove the key from posix_putenv_garbage;
@@ -258,9 +273,7 @@
     return space.newlist(result)
 
 def listdir(space, dirname):
-    """listdir(path) -> list_of_strings
-
-Return a list containing the names of the entries in the directory.
+    """Return a list containing the names of the entries in the directory.
 
 \tpath: path of directory to list
 

Modified: pypy/dist/pypy/module/select/app_select.py
==============================================================================
--- pypy/dist/pypy/module/select/app_select.py	(original)
+++ pypy/dist/pypy/module/select/app_select.py	Thu Jun 22 17:34:28 2006
@@ -16,6 +16,26 @@
     return fd
 
 def select(iwtd, owtd, ewtd, timeout=None):
+    """Wait until one or more file descriptors are ready for some kind of I/O.
+The first three arguments are sequences of file descriptors to be waited for:
+rlist -- wait until ready for reading
+wlist -- wait until ready for writing
+xlist -- wait for an ``exceptional condition''
+If only one kind of condition is required, pass [] for the other lists.
+A file descriptor is either a socket or file object, or a small integer
+gotten from a fileno() method call on one of those.
+
+The optional 4th argument specifies a timeout in seconds; it may be
+a floating point number to specify fractions of seconds.  If it is absent
+or None, the call will never time out.
+
+The return value is a tuple of three lists corresponding to the first three
+arguments; each contains the subset of the corresponding file descriptors
+that are ready.
+
+*** IMPORTANT NOTICE ***
+On Windows, only sockets are supported; on Unix, all file descriptors.
+"""
     from select import poll, POLLIN, POLLOUT, POLLPRI
     fddict = {}
     polldict = {}

Modified: pypy/dist/pypy/module/select/interp_select.py
==============================================================================
--- pypy/dist/pypy/module/select/interp_select.py	(original)
+++ pypy/dist/pypy/module/select/interp_select.py	Thu Jun 22 17:34:28 2006
@@ -8,6 +8,8 @@
 defaultevents = _c.POLLIN | _c.POLLOUT | _c.POLLPRI
 
 def poll(space):
+    """Returns a polling object, which supports registering and
+unregistering file descriptors, and then polling them for I/O events."""
     return Poll()
 
 def as_fd_w(space, w_fd):

Modified: pypy/dist/pypy/module/sys/app.py
==============================================================================
--- pypy/dist/pypy/module/sys/app.py	(original)
+++ pypy/dist/pypy/module/sys/app.py	Thu Jun 22 17:34:28 2006
@@ -8,24 +8,29 @@
 import sys 
 
 def excepthook(exctype, value, traceback):
+    """Handle an exception by displaying it with a traceback on sys.stderr."""
     from traceback import print_exception
     print_exception(exctype, value, traceback)
 
 def exit(exitcode=0):
+    """Exit the interpreter by raising SystemExit(exitcode).
+If the exitcode is omitted or None, it defaults to zero (i.e., success).
+If the exitcode is numeric, it will be used as the system exit status.
+If it is another kind of object, it will be printed and the system
+exit status will be one (i.e., failure)."""
     # note that we cannot use SystemExit(exitcode) here.
     # The comma version leads to an extra de-tupelizing
     # in normalize_exception, which is exactly like CPython's.
     raise SystemExit, exitcode
 
 def exitfunc():
-    pass
+    """Placeholder for sys.exitfunc(), which is called when PyPy exits."""
 
 #import __builtin__
 
 def getfilesystemencoding():
-    """ getfilesystemencoding() -> string
-        Return the encoding used to convert Unicode filenames in
-        operating system filenames.
+    """Return the encoding used to convert Unicode filenames in
+operating system filenames.
     """
     if sys.platform == "win32":
         encoding = "mbcs"
@@ -36,34 +41,19 @@
     return encoding
 
 def callstats():
-    """callstats() -> tuple of integers
-
-Return a tuple of function call statistics, if CALL_PROFILE was defined
-when Python was built.  Otherwise, return None.
-
-When enabled, this function returns detailed, implementation-specific
-details about the number of function calls executed. The return value is
-a 11-tuple where the entries in the tuple are counts of:
-0. all function calls
-1. calls to PyFunction_Type objects
-2. PyFunction calls that do not create an argument tuple
-3. PyFunction calls that do not create an argument tuple
-   and bypass PyEval_EvalCodeEx()
-4. PyMethod calls
-5. PyMethod calls on bound methods
-6. PyType calls
-7. PyCFunction calls
-8. generator calls
-9. All other calls
-10. Number of stack pops performed by call_function()"""
+    """Not implemented."""
     return None
 
 defaultencoding = 'ascii'
 
 def getdefaultencoding():
+    """Return the current default string encoding used by the Unicode 
+implementation."""
     return defaultencoding
 
 def setdefaultencoding(encoding):
+    """Set the current default string encoding used by the Unicode 
+implementation."""
     global defaultencoding
     import codecs
     codecs.lookup(encoding)

Modified: pypy/dist/pypy/module/sys/hook.py
==============================================================================
--- pypy/dist/pypy/module/sys/hook.py	(original)
+++ pypy/dist/pypy/module/sys/hook.py	Thu Jun 22 17:34:28 2006
@@ -1,6 +1,7 @@
 from pypy.interpreter.pyopcode import print_item_to, print_newline_to, sys_stdout 
 
 def displayhook(space, w_obj):
+    """Print an object to sys.stdout and also save it in __builtin__._"""
     if not space.is_w(w_obj, space.w_None): 
         space.setitem(space.builtin.w_dict, space.wrap('_'), w_obj)
         # NB. this is slightly more complicated in CPython,

Modified: pypy/dist/pypy/module/sys/vm.py
==============================================================================
--- pypy/dist/pypy/module/sys/vm.py	(original)
+++ pypy/dist/pypy/module/sys/vm.py	Thu Jun 22 17:34:28 2006
@@ -16,6 +16,13 @@
     space.setitem(w_modules, space.wrap(name), w_module)
 
 def _getframe(space, w_depth=0):
+    """Return a frame object from the call stack.  If optional integer depth is
+given, return the frame object that many calls below the top of the stack.
+If that is deeper than the call stack, ValueError is raised.  The default
+for depth is zero, returning the frame at the top of the call stack.
+
+This function should be used for internal and specialized
+purposes only."""
     depth = space.int_w(w_depth)
     try:
         f = space.getexecutioncontext().framestack.top(depth)
@@ -30,9 +37,7 @@
 # directly from the C code in ceval.c, might be moved somewhere else.
 
 def setrecursionlimit(space, w_new_limit):
-    """setrecursionlimit(n)
-
-Set the maximum depth of the Python interpreter stack to n.  This
+    """Set the maximum depth of the Python interpreter stack to n.  This
 limit prevents infinite recursion from causing an overflow of the C
 stack and crashing Python.  The highest possible limit is platform
 dependent."""
@@ -45,8 +50,7 @@
     space.sys.recursionlimit = new_limit
 
 def getrecursionlimit(space):
-    """getrecursionlimit()
-    Return the current value of the recursion limit, the maximum depth
+    """Return the current value of the recursion limit, the maximum depth
     of the Python interpreter stack.  This limit prevents infinite
     recursion from causing an overflow of the C stack and crashing Python.
     """
@@ -54,17 +58,19 @@
     return space.wrap(space.sys.recursionlimit)
 
 def setcheckinterval(space, w_interval):
-    """setcheckinterval(n)
-    Tell the Python interpreter to check for asynchronous events every
+    """Tell the Python interpreter to check for asynchronous events every
     n instructions.  This also affects how often thread switches occur."""
     space.sys.checkinterval = space.int_w(w_interval) 
     space.getexecutioncontext().ticker = 0
 
 def getcheckinterval(space):
-    """getcheckinterval() -> current check interval; see setcheckinterval()."""
+    """Return the current check interval; see setcheckinterval()."""
     return space.wrap(space.sys.checkinterval)
 
 def exc_info(space):
+    """Return the (type, value, traceback) of the most recent exception
+caught by an except clause in the current stack frame or in an older stack
+frame."""
     operror = space.getexecutioncontext().sys_exc_info()
     if operror is None:
         return space.newtuple([space.w_None,space.w_None,space.w_None])
@@ -73,6 +79,10 @@
                                space.wrap(operror.application_traceback)])
 
 def exc_clear(space):
+    """Clear global information on the current exception.  Subsequent calls
+to exc_info() will return (None,None,None) until another exception is
+raised and caught in the current thread or the execution stack returns to a
+frame where another exception is being handled."""
     operror = space.getexecutioncontext().sys_exc_info()
     if operror is not None:
         operror.clear(space)
@@ -93,23 +103,17 @@
 ##     return space.wrap(sys.getrefcount(w_obj) - 6)
 
 def settrace(space, w_func):
-    """settrace(function)
-
-Set the global debug tracing function.  It will be called on each
+    """Set the global debug tracing function.  It will be called on each
 function call.  See the debugger chapter in the library manual."""
     space.getexecutioncontext().settrace(w_func)
     
 def setprofile(space, w_func):
-    """setprofile(function)
-
-Set the profiling function.  It will be called on each function call
+    """Set the profiling function.  It will be called on each function call
 and return.  See the profiler chapter in the library manual."""
     space.getexecutioncontext().setprofile(w_func)
 
 def call_tracing(space, w_func, w_args):
-    """call_tracing(func, args) -> object
-
-Call func(*args), while tracing is enabled.  The tracing state is
+    """Call func(*args), while tracing is enabled.  The tracing state is
 saved, and restored afterwards.  This is intended to be called from
 a debugger from a checkpoint, to recursively debug some other code."""
     return space.getexecutioncontext().call_tracing(w_func, w_args)

Modified: pypy/dist/pypy/module/thread/os_lock.py
==============================================================================
--- pypy/dist/pypy/module/thread/os_lock.py	(original)
+++ pypy/dist/pypy/module/thread/os_lock.py	Thu Jun 22 17:34:28 2006
@@ -98,6 +98,8 @@
 
 
 def allocate_lock(space):
+    """Create a new lock object.  (allocate() is an obsolete synonym.)
+See LockType.__doc__ for information about locks."""
     return space.wrap(Lock())
 
 def getlocktype(space):

Modified: pypy/dist/pypy/module/time/interp_time.py
==============================================================================
--- pypy/dist/pypy/module/time/interp_time.py	(original)
+++ pypy/dist/pypy/module/time/interp_time.py	Thu Jun 22 17:34:28 2006
@@ -3,12 +3,19 @@
 
 
 def clock(space):
+    """Return the CPU time or real time since the start of the process or
+since the first call to clock().  This returns a floating point measured
+in seconds with as much precision as the system records."""
     return space.wrap(time.clock())
 
 def time_(space):
+    """Return the current time in seconds since the Epoch.  Fractions of a
+second may be present if the system clock provides them."""
     return space.wrap(time.time())
 
 def sleep(space, seconds):
+    """Delay execution for a given number of seconds.  The argument may
+be a floating point number for subsecond precision."""
     # XXX Temporary hack: we need to make sure the GIL is released while
     #     sleeping.  XXX should be done differently !!!
     GIL = space.threadlocals.getGIL()



More information about the Pypy-commit mailing list