Commits

Ronald Oussoren committed b1eec93

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

  • Participants
  • Parent commits c51e535

Comments (0)

Files changed (12)

File 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 */

File 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 */
 

File 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__) */
     {

File 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"

File 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"

File 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 */

File 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"

File 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

File 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));

File 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"

File 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"

File 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()
-
-
-
-