[pypy-svn] r72779 - pypy/branch/cpython-extension/pypy/module/cpyext

[afa at codespeak.net]

Author: afa
Date: Thu Mar 25 02:23:11 2010
New Revision: 72779

Modified:
   pypy/branch/cpython-extension/pypy/module/cpyext/api.py
Log:
Add some notes, to implement...


Modified: pypy/branch/cpython-extension/pypy/module/cpyext/api.py
==============================================================================
--- pypy/branch/cpython-extension/pypy/module/cpyext/api.py	(original)
+++ pypy/branch/cpython-extension/pypy/module/cpyext/api.py	Thu Mar 25 02:23:11 2010
@@ -50,6 +50,25 @@
 _NOT_SPECIFIED = object()
 CANNOT_FAIL = object()
 
+# The same function can be called in three different contexts:
+# (1) from C code
+# (2) in the test suite, though the "api" object
+# (3) from RPython code, for example in the implementation of another function.
+#
+# In contexts (2) and (3), a function declaring a PyObject argument type will
+# receive a wrapped pypy object if the parameter name starts with 'w_', a
+# reference (= rffi pointer) otherwise; conversion is automatic.  Context (2)
+# only allows calls with a wrapped object.
+#
+# Functions with a PyObject return type should return a wrapped object.
+#
+# Functions may raise exceptions.  In context (3), the exception flows normally
+# through the calling function.  In context (1) and (2), the exception is
+# caught; if it is an OperationError, it is stored in the thread state; other
+# exceptions generate a OperationError(w_SystemError).  In every case the
+# funtion returns the error value specifed in the API.
+#
+
 class ApiFunction:
     def __init__(self, argtypes, restype, callable, borrowed, error):
         self.argtypes = argtypes