Commits

Ronald Oussoren committed b1eec93

Tweak docstrings to work with inspect.Signature on Python 3.4 (rc1)

Comments (0)

Files changed (12)

pyobjc-core/Modules/objc/formal-protocol.m

 
 PyDoc_STRVAR(proto_cls_doc,
 "objc.formal_protocol(name, supers, selector_list)\n"
+CLINIC_SEP
 "\n"
 "This class is used to proxy Objective-C formal protocols, and can also be \n"
 "used to define new formal protocols.\n"
         .ml_name    = "name",
         .ml_meth    = (PyCFunction)proto_name,
         .ml_flags   = METH_NOARGS,
-        .ml_doc     = "Return the  protocol name",
+        .ml_doc     = "name()\n" CLINIC_SEP "\nReturn the  protocol name",
     },
     {
         .ml_name    = "conformsTo_",
         .ml_meth    = (PyCFunction)proto_conformsTo_,
         .ml_flags   = METH_VARARGS,
-        .ml_doc     = "Does this protocol conform to another protocol"
+        .ml_doc     = "conformsTo_(other)\n" CLINIC_SEP "\nDoes this protocol conform to another protocol"
     },
     {
         .ml_name    = "descriptionForInstanceMethod_",
         .ml_meth    = (PyCFunction)descriptionForInstanceMethod_,
         .ml_flags   = METH_O,
-        .ml_doc     = "Description for an instance method in the protocol"
+        .ml_doc     = "descriptionForInstanceMethod_(selector)\n" CLINIC_SEP "\nDescription for an instance method in the protocol"
     },
     {
         .ml_name    = "descriptionForClassMethod_",
         .ml_meth    = (PyCFunction)descriptionForClassMethod_,
         .ml_flags   = METH_O,
-        .ml_doc     = "Description for a class method in the protocol"
+        .ml_doc     = "descriptionForClassMethod_(selector)\n" CLINIC_SEP "\nDescription for a class method in the protocol"
     },
     {
         .ml_name    = "instanceMethods",
         .ml_meth    = (PyCFunction)instanceMethods,
         .ml_flags   = METH_NOARGS,
-        .ml_doc     = "List of instance methods in this protocol"
+        .ml_doc     = "instanceMethods()\n" CLINIC_SEP "\nList of instance methods in this protocol"
     },
     {
         .ml_name    = "classMethods",
         .ml_meth    = (PyCFunction)classMethods,
         .ml_flags   = METH_NOARGS,
-        .ml_doc     = "List of class methods in this protocol"
+        .ml_doc     = "classMethods()\n" CLINIC_SEP "\nList of class methods in this protocol"
     },
     {
         .ml_name    = NULL  /* SENTINEL */

pyobjc-core/Modules/objc/fsref.m

         .ml_name    = "as_pathname",
         .ml_meth    = (PyCFunction)fsref_as_path,
         .ml_flags   = METH_NOARGS,
-        .ml_doc     = "as_pathname()\n\nReturn POSIX path for this object (Unicode string)"
+        .ml_doc     = "as_pathname()\n" CLINIC_SEP "\nReturn POSIX path for this object (Unicode string)"
     },
     {
         .ml_name    = "from_pathname",
         .ml_meth    = (PyCFunction)fsref_from_path,
         .ml_flags   = METH_O|METH_CLASS,
-        .ml_doc     = "from_pathname(path)\n\nCreate FSRef instance for an POSIX path"
+        .ml_doc     = "from_pathname(path)\n" CLINIC_SEP "\nCreate FSRef instance for an POSIX path"
     },
 
 #if USE_TOOLBOX_OBJECT_GLUE
         .ml_name    = "as_carbon",
         .ml_meth    = (PyCFunction)fsref_as_carbon,
         .ml_flags   = METH_NOARGS,
-        .ml_doc     = "as_carbon()\n\nReturn Carbon.File.FSRef instance for this object"
+        .ml_doc     = "as_carbon()\n" CLINIC_SEP "\nReturn Carbon.File.FSRef instance for this object"
     },
 #endif /* USE_TOOLBOX_OBJECT_GLUE */
 

pyobjc-core/Modules/objc/fsspec.m

         .ml_name    = "as_carbon",
         .ml_meth    = (PyCFunction)fsspec_as_carbon,
         .ml_flags   = METH_NOARGS,
-        .ml_doc     = "as_carbon()\n\nReturn Carbon.File.FSSpec instance for this object"
+        .ml_doc     = "as_carbon()\n" CLINIC_SEP "\nReturn Carbon.File.FSSpec instance for this object"
     },
 #endif /* defined(USE_TOOLBOX_OBJECT_GLUE) && !defined(__LP64__) */
     {

pyobjc-core/Modules/objc/informal-protocol.m

 
 PyDoc_STRVAR(proto_cls_doc,
 "objc.informal_protocol(name, selector_list)\n"
+CLINIC_SEP
 "\n"
 "This class can be used to specify which methods are supported by an informal\n"
 "protocol. Instances of this type can by used while creating subclasses of \n"

pyobjc-core/Modules/objc/instance-var.m

 
 PyDoc_STRVAR(ivar_doc,
 "ivar(name, type='@', isOutlet=False) -> instance-variable\n"
+CLINIC_SEP
 "\n"
 "Creates a descriptor for accessing an Objective-C instance variable.\n\n"
 "This should only be used in the definition of Objective-C subclasses, and\n"

pyobjc-core/Modules/objc/module.m

 
 PyDoc_STRVAR(pyobjc_id_doc,
   "pyobjc_id(obj)\n"
+  CLINIC_SEP
   "\n"
   "Return the id of the underlying NSObject as an int."
 );
 
 PyDoc_STRVAR(repythonify_doc,
   "repythonify(obj, type='@')\n"
+  CLINIC_SEP
   "\n"
   "Put an object through the bridge by calling \n"
   "depythonify_c_value then pythonify_c_value.\n"
 
 PyDoc_STRVAR(lookUpClass_doc,
   "lookUpClass(class_name)\n"
+  CLINIC_SEP
   "\n"
   "Search for the named classes in the Objective-C runtime and return it.\n"
   "Raises noclass_error when the class doesn't exist.");
 
 PyDoc_STRVAR(classAddMethods_doc,
      "classAddMethods(targetClass, methodsArray)\n"
+     CLINIC_SEP
      "\n"
      "Adds methods in methodsArray to class. The effect is similar to how \n"
      "categories work. If class already implements a method as defined in \n"
 
 PyDoc_STRVAR(remove_autorelease_pool_doc,
   "removeAutoreleasePool()\n"
+  CLINIC_SEP
   "\n"
   "This removes the global NSAutoreleasePool.  You should do this\n"
   "at the end of a plugin's initialization script.\n");
 
 PyDoc_STRVAR(recycle_autorelease_pool_doc,
   "recycleAutoreleasePool()\n"
+  CLINIC_SEP
   "\n"
   "This 'releases' the global autorelease pool and creates a new one.\n"
   "This method is for system use only\n");
 
 PyDoc_STRVAR(set_class_extender_doc,
     "_setClassExtender(func)\n"
+    CLINIC_SEP
     "\n"
     "Register a function that will be called to update the class\n"
     "dict of new Objective-C classes and class-proxies. This will\n"
 
 
 PyDoc_STRVAR(getClassList_doc,
-  "getClassList()"
+  "getClassList()\n"
+  CLINIC_SEP
   "\n"
   "Return a list with all Objective-C classes known to the runtime.\n"
 );
 
 PyDoc_STRVAR(allocateBuffer_doc,
          "allocateBuffer(size)\n"
+         CLINIC_SEP
          "\n"
          "Allocate a buffer of memory of size. Buffer is \n"
          "read/write."
 
 PyDoc_STRVAR(currentBundle_doc,
     "currentBundle()\n"
+    CLINIC_SEP
     "\n"
     "Get the current bundle during module initialization.\n"
     "Works for plug-ins and applications.\n"
 
 PyDoc_STRVAR(loadBundle_doc,
     "loadBundle(module_name, module_globals, bundle_path=None, "
-    "bundle_identifier=None, scan_classes=True) -> bundle\n"
+    "bundle_identifier=None, scan_classes=True)\n"
+    CLINIC_SEP
     "\n"
     "Load the bundle identified by 'bundle_path' or 'bundle_identifier' \n"
     "and add the classes in the bundle to the 'module_globals'.\n"
 
 PyDoc_STRVAR(objc_splitSignature_doc,
     "splitSignature(signature)\n"
+    CLINIC_SEP
     "\n"
     "Split a signature string into a list of items."
 );
 
 PyDoc_STRVAR(objc_splitStructSignature_doc,
     "splitStructSignature(signature)\n"
+    CLINIC_SEP
     "\n"
     "Split a struct signature string into a list of items."
 );
 PyDoc_STRVAR(PyObjC_loadBundleVariables_doc,
     "loadBundleVariables(bundle, module_globals, variableInfo, "
     "skip_undefined=True)\n"
+    CLINIC_SEP
     "\n"
     "Load the specified variables in the bundle. If skip_undefined is \n"
     "True, variables that are not present in the bundle are skipped, \n"
 PyDoc_STRVAR(PyObjC_loadBundleFunctions_doc,
     "loadBundleFunctions(bundle, module_globals, functionInfo, "
     "skip_undefined=True)\n"
+    CLINIC_SEP
     "\n"
     "Load the specified functions in the bundle. If skip_undefined is \n"
     "True, variables that are not present in the bundle are skipped, \n"
 PyDoc_STRVAR(PyObjC_loadFunctionList_doc,
     "loadFunctionList(list, module_globals, functionInfo, "
     "skip_undefined=True)\n"
+    CLINIC_SEP
     "\n"
     "Load the specified functions. List should be a capsule object containing\n"
     "an array of { char*, funcion } structs.");
 PyDoc_STRVAR(PyObjC_loadSpecialVar_doc,
     "loadSpecialVar(bundle, module_globals, typeid, name, skip_undefined=True)\n"
+    CLINIC_SEP
     "\n"
     "Load a magic cookie object from a bundle. A magic cookie is a \n"
     "C pointer that represents a CoreFoundation or Objective-C object \n"
 
 PyDoc_STRVAR(protocolsForProcess_doc,
     "protocolsForProcess()\n"
+    CLINIC_SEP
     "\n"
     "Returns a list of Protocol objects that are present in the process"
 );
 }
 
 PyDoc_STRVAR(protocolNamed_doc,
-    "_protocolNamed(name)\n");
+    "_protocolNamed(name)\n"
+    CLINIC_SEP
+    "\n"
+    "Returns an Objective-C protocol named *name*.\n"
+    "Raises AttributeError when no such protocol can be found.\n"
+    );
 static PyObject*
 protocolNamed(PyObject* self __attribute__((__unused__)), PyObject* args, PyObject* kwds)
 {
 
 PyDoc_STRVAR(protocolsForClass_doc,
     "protocolsForClass(cls)\n"
+    CLINIC_SEP
     "\n"
     "Returns a list of Protocol objects that the class claims\n"
     "to implement directly."
 
 PyDoc_STRVAR(createOpaquePointerType_doc,
     "createOpaquePointerType(name, typestr, doc)\n"
+    CLINIC_SEP
     "\n"
     "Return a wrapper type for opaque pointers of the given type. The type \n"
     "will be registered with PyObjC and will be used to wrap pointers of the \n"
 
 PyDoc_STRVAR(registerMetaData_doc,
     "registerMetaDataForSelector(classObject, selector, metadata)\n"
+    CLINIC_SEP
     "\n"
     "Registers a metadata dictionary for method *selector* in *class*");
 static PyObject*
 
 PyDoc_STRVAR(registerStructAlias_doc,
     "registerStructAlias(typestr, structType)\n"
+    CLINIC_SEP
     "\n"
     "Registers 'typestr' as a type that should be mapped onto 'structType'\n"
     "'structType' must be created using 'createStructType' (or through \n"
 
 PyDoc_STRVAR(createStructType_doc,
     "createStructType(name, typestr, fieldnames, doc, pack)\n"
+    CLINIC_SEP
     "\n"
     "Return a wrapper type for structs of the given type. The wrapper will \n"
     "registered with PyObjC and will be used to wrap structs of the given type.\n"
 
 PyDoc_STRVAR(PyObjCIvar_Info_doc,
     "listInstanceVariables(classOrInstance)\n"
+    CLINIC_SEP
     "\n"
     "Return information about all instance variables of an object or class\n"
 );
 PyDoc_STRVAR(PyObjCIvar_Get_doc,
     "getInstanceVariable(object, name)\n"
+    CLINIC_SEP
     "\n"
     "Return the value of an instance variable\n"
 );
 PyDoc_STRVAR(PyObjCIvar_Set_doc,
     "setInstanceVariable(object, name, value, updateRefCount=False)\n"
+    CLINIC_SEP
     "\n"
     "Modify an instance variable. If the instance variable is an object \n"
     "reference you must include the ``updateRefCount`` argument, otherwise it \n"
 );
 
 PyDoc_STRVAR(registerCFSignature_doc,
-    "registerCFSignature(name, encoding, typeId, tollfreeName=None) -> type\n"
+    "registerCFSignature(name, encoding, typeId, tollfreeName=None)\n"
+    CLINIC_SEP
     "\n"
     "Register a CoreFoundation based type with the bridge. If \n"
     "tollFreeName is supplied the type is tollfree bridged to that class.");
 }
 
 PyDoc_STRVAR(_updatingMetadata_doc,
-    "_updatingMetadata(flag)\n\nPRIVATE FUNCTION");
+    "_updatingMetadata(flag)\n"
+    CLINIC_SEP
+    "\n"
+    "PRIVATE FUNCTION");
 static PyObject*
 _updatingMetadata(PyObject* self __attribute__((__unused__)),
         PyObject* args, PyObject* kwds)
 
 PyDoc_STRVAR(_makeClosure_doc,
   "_makeClosure(callable, closureFor, argIndex=0)\n"
+  CLINIC_SEP
   "\n"
   "Returns a closure object that can be used to call the function from\n"
   "C. This object has no useable interface from Python.\n"
 
 PyDoc_STRVAR(PyObjC_setAssociatedObject_doc,
     "setAssociatedObject(object, key, value, policy=objc.OBJC_ASSOCIATION_RETAIN)\n"
+    CLINIC_SEP
     "\n"
     "Set the value for an object assiociation. Use 'None' as the\n"
     "value to clear an association.");
 
 PyDoc_STRVAR(PyObjC_getAssociatedObject_doc,
     "getAssociatedObject(object, key)\n"
+    CLINIC_SEP
     "\n"
     "Get the value for an object assiociation. Returns None \n"
     "when they association doesn't exist.");
 
 PyDoc_STRVAR(PyObjC_removeAssociatedObjects_doc,
     "removeAssociatedObjects(object)\n"
+    CLINIC_SEP
     "\n"
     "Remove all assocations from an object. This should in general not be used because\n"
     "it clear all references, including those made from unrelated code.\n");
         .ml_name    = "propertiesForClass",
         .ml_meth    = (PyCFunction)mod_propertiesForClass,
         .ml_flags   = METH_O,
-        .ml_doc     = "propertiesForClass(classObject)\n\nReturn information about properties from the runtim",
+        .ml_doc     =
+            "propertiesForClass(classObject)\n"
+            CLINIC_SEP
+            "\n"
+            "Return information about properties from the runtime",
     },
     {
         .ml_name    = "splitSignature",
         .ml_name    = "_ivar_dict",
         .ml_meth    = (PyCFunction)ivar_dict,
         .ml_flags   = METH_NOARGS,
-        .ml_doc     = "_ivar_dict()\n\nPRIVATE FUNCTION\n"
+        .ml_doc     = "_ivar_dict()\n" CLINIC_SEP "\nPRIVATE FUNCTION\n"
     },
     {
         .ml_name    = "_objc_sync_enter",
         .ml_meth    = (PyCFunction)PyObjC_objc_sync_enter,
         .ml_flags   = METH_VARARGS,
-        .ml_doc     = "_objc_sync_enter(object)\n\nacquire mutex for an object"
+        .ml_doc     = "_objc_sync_enter(object)\n" CLINIC_SEP "\nacquire mutex for an object"
     },
     {
         .ml_name    = "_objc_sync_exit",
         .ml_meth    = (PyCFunction)PyObjC_objc_sync_exit,
         .ml_flags   = METH_VARARGS,
-        .ml_doc     = "_objc_sync_exit(object)\n\nrelease mutex for an object"
+        .ml_doc     = "_objc_sync_exit(object)\n" CLINIC_SEP "\nrelease mutex for an object"
     },
     {
         .ml_name    = "_block_call",
         .ml_meth    = (PyCFunction)PyObjCBlock_Call,
         .ml_flags   = METH_VARARGS,
-        "_block_call(block, signature, args, kwds) -> retval"
+        "_block_call(block, signature, args, kwds)\n" CLINIC_SEP "\nCall an Objective-C block"
     },
     {
         .ml_name    = "_block_signature",
         .ml_meth    = (PyCFunction)block_signature,
         .ml_flags   = METH_O,
-        "_block_signature(block) -> signature\n\nreturn signature string for a block, or None"
+        "_block_signature(block)\n" CLINIC_SEP "\nreturn signature string for a block, or None"
     },
     {
         .ml_name    = "_typestr2typestr",
         .ml_meth    = (PyCFunction)typestr2typestr,
         .ml_flags   = METH_O,
-        .ml_doc     = "_typestr2typestr(value)\nReturns the standard Objective-C version for a PyObjC typestr"
+        .ml_doc     = "_typestr2typestr(value)\n" CLINIC_SEP "\nReturns the standard Objective-C version for a PyObjC typestr"
     },
 
 #if    PyObjC_BUILD_RELEASE >= 1006
         .ml_name    = "_loadConstant",
         .ml_meth    = (PyCFunction)PyObjC_LoadConstant,
         .ml_flags   = METH_VARARGS|METH_KEYWORDS,
-        .ml_doc     = "_loadConstant(name, type, magic)\n\nLoad a single C constant and return its value"
+        .ml_doc     = "_loadConstant(name, type, magic)\n" CLINIC_SEP "\nLoad a single C constant and return its value"
     },
     {
         .ml_name    = "_nameForSignature",
         .ml_meth    = (PyCFunction)name_for_signature,
         .ml_flags   = METH_O,
-        .ml_doc     = "_nameForSignature(typestr)\n\nReturn a pretty name for a PyObjC type string"
+        .ml_doc     = "_nameForSignature(typestr)\n" CLINIC_SEP "\nReturn a pretty name for a PyObjC type string"
     },
     {
         .ml_name    = "_rescanClass",
         .ml_meth    = (PyCFunction)force_rescan,
         .ml_flags   = METH_VARARGS|METH_KEYWORDS,
-        .ml_doc     = "_rescanClass(classObject)\n\nForce a rescan of the method table of a class",
+        .ml_doc     = "_rescanClass(classObject)\n" CLINIC_SEP "\nForce a rescan of the method table of a class",
     },
     {
         .ml_name    = NULL /* SENTINEL */

pyobjc-core/Modules/objc/objc-class.m

 
 PyDoc_STRVAR(class_doc,
 "objc_class(name, bases, dict) -> a new Objective-C class\n"
+CLINIC_SEP
 "\n"
 "objc_class is the meta-type for Objective-C classes. It should not be\n"
 "necessary to manually create instances of this type, those are \n"

pyobjc-core/Modules/objc/pyobjc-compat.h

 #define PyObjC__STR(x) #x
 #define PyObjC_STR(x) PyObjC__STR(x)
 
+
+/* Use CLINIC_SEP between the prototype and
+ * description in doc strings, to get clean
+ * docstrings.
+ */
+#if PY_VERSION_HEX >= 0x03040000
+
+# define CLINIC_SEP "--\n"
+
+#else
+
+# define CLINIC_SEP ""
+
+#endif
+
 /* Define PyObjC_UNICODE_FAST_PATH when
  * 1) We're before Python 3.3, and
  * 2) Py_UNICODE has the same size as unichar

pyobjc-core/Modules/objc/selector.m

 }
 
 
-PyDoc_STRVAR(sel_metadata_doc, "Return a dict that describes the metadata for this method, including metadata for the 2 hidden ObjC parameters (self and _sel) ");
+PyDoc_STRVAR(sel_metadata_doc, "__metadata__()\n" CLINIC_SEP "\nReturn a dict that describes the metadata for this method, including metadata for the 2 hidden ObjC parameters (self and _sel) ");
 static PyObject* sel_metadata(PyObject* self)
 {
     PyObject* result = PyObjCMethodSignature_AsDict(PyObjCSelector_GetMetadata(self));

pyobjc-core/Modules/objc/varlist.m

 
 PyDoc_STRVAR(object_as_tuple_doc,
     "as_tuple(count)\n"
+    CLINIC_SEP
     "\n"
     "Return a tuple containing the first ``count`` elements of "
     "this list"

pyobjc-core/Modules/objc/weakref.m

 
 PyDoc_STRVAR(weakref_cls_doc,
 "objc.WeakRef(object)\n"
+CLINIC_SEP
 "\n"
 "Create zeroing weak reference to a Cocoa object.\n"
 "Raises `VAlueError` when *object* is not a Cocoa \n"

pyobjc-core/PyObjCTest/test_inspect_signatures.py

         for nm in dir(objc):
             obj = getattr(objc, nm)
             if isinstance(obj, types.BuiltinMethodType):
-                self.assertIsNot(inspect.signature(obj), None, "No inspect.signature for %s"%(nm,))
+                try:
+                    value = inspect.signature(obj)
+
+                except ValueError:
+                    value = None
+
+                if value is None:
+                    self.fail("No inspect.signature for %s"%(nm,))
 
     @min_python_release("3.4")
     def test_class_signature(self):
             class_list.append(objc.WeakRef)
         for cls in class_list:
             for nm in dir(cls):
-                if nm in ('__new__', '__subclasshook__', '__abstractmethods__'):
+                if nm in ('__new__', '__subclasshook__', '__abstractmethods__', '__prepare__'):
                     continue
                 obj = getattr(cls, nm)
                 if isinstance(obj, types.BuiltinMethodType):
-                    self.assertIsNot(inspect.signature(obj), None, "No inspect.signature for %s.%s"%(cls.__name__, nm,))
+                    try:
+                        value = inspect.signature(obj)
+                    except ValueError:
+                        value = None
+
+                    if value is None:
+                        self.fail("No inspect.signature for %s.%s"%(cls.__name__, nm,))
 
 if __name__ == "__main__":
     main()
-
-
-
-