[pypy-svn] r8488 - pypy/dist/pypy/documentation

[mwh at codespeak.net]

Author: mwh
Date: Sun Jan 23 14:39:45 2005
New Revision: 8488

Modified:
   pypy/dist/pypy/documentation/architecture.txt
   pypy/dist/pypy/documentation/objspaceinterface.txt
   pypy/dist/pypy/documentation/wrapping.txt
Log:
Documentation for the post-merge type-specific unwrapping operations.


Modified: pypy/dist/pypy/documentation/architecture.txt
==============================================================================
--- pypy/dist/pypy/documentation/architecture.txt	(original)
+++ pypy/dist/pypy/documentation/architecture.txt	Sun Jan 23 14:39:45 2005
@@ -226,12 +226,13 @@
 
 The ``w_`` prefixes so lavishly used in the previous example indicate,
 by PyPy coding convention, that we are dealing with *wrapped* objects,
-that is, interpreter-level objects which the object space constructs to
-implement corresponding application-level objects.  Each object space
-supplies ``wrap`` and ``unwrap`` operations that move between the two
-levels for objects of simple built-in types; each object space also
-implements other Python types with suitable interpreter-level classes
-with some amount of internal structure.
+that is, interpreter-level objects which the object space constructs
+to implement corresponding application-level objects.  Each object
+space supplies ``wrap`` and ``unwrap``, ``int_w``, ``interpclass_w``,
+etc. operations that move between the two levels for objects of simple
+built-in types; each object space also implements other Python types
+with suitable interpreter-level classes with some amount of internal
+structure.
 
 For example, an application-level Python ``list`` is implemented as an
 instance of ``W_ListObject``, which has an instance attribute

Modified: pypy/dist/pypy/documentation/objspaceinterface.txt
==============================================================================
--- pypy/dist/pypy/documentation/objspaceinterface.txt	(original)
+++ pypy/dist/pypy/documentation/objspaceinterface.txt	Sun Jan 23 14:39:45 2005
@@ -86,6 +86,18 @@
 **unwrap(w_x):**
   Return Interpreter Level equivalent of w_x
 
+**interpclass_w(w_x):**
+  If w_x is a wrapped instance of an interpreter class -- for example Function, Frame, Cell, etc. -- return it unwrapped.  Otherwise return None.
+
+**int_w(w_x):**
+  If w_x is an application-level integer or long which can be converted without overflow to an integer, return an interpreter-level integer.  Otherwise raise TypeError or OverflowError.
+
+**str_w(w_x):**
+  If w_x is an application-level string, return an interpreter-level string.  Otherwise raise TypeError.
+
+**float_w(w_x):**
+  If w_x is an application-level float, integer or long, return interpreter-level float.  Otherwise raise TypeError or OverflowError in case of very large longs.
+
 **is_true(w_x):**
   Return a interpreter level bool (True or False).
 

Modified: pypy/dist/pypy/documentation/wrapping.txt
==============================================================================
--- pypy/dist/pypy/documentation/wrapping.txt	(original)
+++ pypy/dist/pypy/documentation/wrapping.txt	Sun Jan 23 14:39:45 2005
@@ -67,7 +67,15 @@
 
 * ``space.unpackiterable(w_x)``: this helper iterates ``w_x`` (using ``space.iter()`` and ``space.next()``) and collects the resulting wrapped objects in a list.  Of course, in cases where iterating directly is better than collecting the elements in a list first, you should use ``space.iter()`` and ``space.next()`` directly.
 
-* ``space.unwrap(w_x)``: inverse of ``space.wrap()``.  Attention! Using ``space.unwrap()`` must be avoided whenever possible.  Actually, it should only be used when you are sure that ``w_x`` contains a simple object or an internal interpreter object that was wrapped with ``space.wrap()``.  This function is a bit buggy anyway, and it should probably be fixed at some point: we should specify what kind of unwrapped result is expected (and raise a TypeError appropriately).
+* ``space.unwrap(w_x)``: inverse of ``space.wrap()``.  Attention!  Using ``space.unwrap()`` must be avoided whenever possible, i.e. only use this when you are well aware that you are cheating, in unit tests or bootstrapping code.
+
+* ``space.interpclass_w(w_x)``: If w_x is a wrapped instance of an interpreter class -- for example Function, Frame, Cell, etc. -- return it unwrapped.  Otherwise return None.
+
+* ``space.int_w(w_x)``: If w_x is an application-level integer or long which can be converted without overflow to an integer, return an interpreter-level integer.  Otherwise raise TypeError or OverflowError.
+
+* ``space.str_w(w_x)``: If w_x is an application-level string, return an interpreter-level string.  Otherwise raise TypeError.
+
+* ``space.float_w(w_x)``: If w_x is an application-level float, integer or long, return interpreter-level float.  Otherwise raise TypeError or OverflowError in case of very large longs.
 
 Remember that you can usually obtain the information you want by invoking operations or methods on the wrapped objects; e.g. ``space.call_method(w_dict, 'iterkeys')`` returns a wrapped iterable that you can decode with ``space.unpackiterable()``.