[pypy-svn] r74312 - in pypy/branch/py-packagecontext/pypy/module/cpyext: . test

[exarkun at codespeak.net]

Author: exarkun
Date: Sat May  1 23:28:14 2010
New Revision: 74312

Modified:
   pypy/branch/py-packagecontext/pypy/module/cpyext/modsupport.py
   pypy/branch/py-packagecontext/pypy/module/cpyext/state.py
   pypy/branch/py-packagecontext/pypy/module/cpyext/test/test_cpyext.py
Log:
write some docstrings; update the package_context comment.

Modified: pypy/branch/py-packagecontext/pypy/module/cpyext/modsupport.py
==============================================================================
--- pypy/branch/py-packagecontext/pypy/module/cpyext/modsupport.py	(original)
+++ pypy/branch/py-packagecontext/pypy/module/cpyext/modsupport.py	Sat May  1 23:28:14 2010
@@ -8,7 +8,17 @@
 from pypy.module.cpyext.state import State
 from pypy.interpreter.error import OperationError
 
+#@cpython_api([rffi.CCHARP], PyObject, borrowed=True)
 def PyImport_AddModule(space, name):
+    """Return the module object corresponding to a module name.  The name argument
+    may be of the form package.module. First check the modules dictionary if
+    there's one there, and if not, create a new one and insert it in the modules
+    dictionary.
+
+    This function does not load or import the module; if the module wasn't already
+    loaded, you will get an empty module object. Use PyImport_ImportModule()
+    or one of its variants to import a module.  Package structures implied by a
+    dotted name for name are not created if not already present."""
     w_name = space.wrap(name)
     w_modules = space.sys.get('modules')
 
@@ -22,6 +32,20 @@
 @cpython_api([CONST_STRING, lltype.Ptr(PyMethodDef), CONST_STRING,
               PyObject, rffi.INT_real], PyObject, borrowed=False) # we cannot borrow here
 def Py_InitModule4(space, name, methods, doc, w_self, apiver):
+    """
+    Create a new module object based on a name and table of functions, returning
+    the new module object. If doc is non-NULL, it will be used to define the
+    docstring for the module. If self is non-NULL, it will passed to the
+    functions of the module as their (otherwise NULL) first parameter. (This was
+    added as an experimental feature, and there are no known uses in the current
+    version of Python.) For apiver, the only value which should be passed is
+    defined by the constant PYTHON_API_VERSION.
+
+    Note that the name parameter is actually ignored, and the module name is
+    taken from the package_context attribute of the cpyext.State in the space
+    cache.  CPython includes some extra checking here to make sure the module
+    being initialized lines up with what's expected, but we don't.
+    """
     from pypy.module.cpyext.typeobjectdefs import PyTypeObjectPtr
     modname = rffi.charp2str(name)
     state = space.fromcache(State)

Modified: pypy/branch/py-packagecontext/pypy/module/cpyext/state.py
==============================================================================
--- pypy/branch/py-packagecontext/pypy/module/cpyext/state.py	(original)
+++ pypy/branch/py-packagecontext/pypy/module/cpyext/state.py	Sat May  1 23:28:14 2010
@@ -25,11 +25,10 @@
         # When importing a package, use this to keep track of its name.  This is
         # necessary because an extension module in a package might not supply
         # its own fully qualified name to Py_InitModule.  If it doesn't, we need
-        # to be able to figure out what module is being initialized.  When a
-        # package import is in progress, this is set to the name of the package.
-        # The rest of the time, it's None.  Packages may be imported
-        # recursively, in which case the outer state is preserved somewhere in
-        # the stack and then restored when the inner import is complete.
+        # to be able to figure out what module is being initialized.  Recursive
+        # imports will clobber this value, which might be confusing, but it
+        # doesn't hurt anything because the code that cares about it will have
+        # already read it by that time.
         self.package_context = None
 
 

Modified: pypy/branch/py-packagecontext/pypy/module/cpyext/test/test_cpyext.py
==============================================================================
--- pypy/branch/py-packagecontext/pypy/module/cpyext/test/test_cpyext.py	(original)
+++ pypy/branch/py-packagecontext/pypy/module/cpyext/test/test_cpyext.py	Sat May  1 23:28:14 2010
@@ -50,6 +50,16 @@
         raises(ImportError, cpyext.load_module, self.libc, "invalid.function")
 
 def compile_module(modname, **kwds):
+    """
+    Build an extension module and return the filename of the resulting native
+    code file.
+
+    modname is the name of the module, possibly including dots if it is a module
+    inside a package.
+
+    Any extra keyword arguments are passed on to ExternalCompilationInfo to
+    build the module (so specify your source with one of those).
+    """
     modname = modname.split('.')[-1]
     eci = ExternalCompilationInfo(
         export_symbols=['init%s' % (modname,)],
@@ -137,6 +147,9 @@
         importhook(cls.space, "os") # warm up reference counts
 
     def compile_module(self, name, **kwds):
+        """
+        Build an extension module linked against the cpyext api library.
+        """
         state = self.space.fromcache(State)
         api_library = state.api_lib
         if sys.platform == 'win32':
@@ -212,12 +225,19 @@
         return self.import_module(name=modname, init=init, body=body)
 
     def record_imported_module(self, name):
+        """
+        Record a module imported in a test so that it can be cleaned up in
+        teardown before the check for leaks is done.
+
+        name gives the name of the module in the space's sys.modules.
+        """
         self.imported_module_names.append(name)
 
     def setup_method(self, func):
         # A list of modules which the test caused to be imported (in
         # self.space).  These will be cleaned up automatically in teardown.
         self.imported_module_names = []
+
         self.w_import_module = self.space.wrap(self.import_module)
         self.w_import_extension = self.space.wrap(self.import_extension)
         self.w_compile_module = self.space.wrap(self.compile_module)
@@ -234,6 +254,10 @@
         #self.check_and_print_leaks()
 
     def unimport_module(self, name):
+        """
+        Remove the named module from the space's sys.modules and discard the
+        reference (owned by "the test") to it.
+        """
         w_modules = self.space.sys.get('modules')
         w_name = self.space.wrap(name)
         w_mod = self.space.getitem(w_modules, w_name)