Docs: add initial idprop.types API docs
authorCampbell Barton <ideasman42@gmail.com>
Sun, 31 Jul 2016 05:39:30 +0000 (15:39 +1000)
committerCampbell Barton <ideasman42@gmail.com>
Sun, 31 Jul 2016 05:40:40 +0000 (15:40 +1000)
doc/python_api/epy/IDProp.py [deleted file]
doc/python_api/sphinx_doc_gen.py
source/blender/python/generic/idprop_py_api.c

diff --git a/doc/python_api/epy/IDProp.py b/doc/python_api/epy/IDProp.py
deleted file mode 100644 (file)
index 1fc26d7..0000000
+++ /dev/null
@@ -1,132 +0,0 @@
-class IDGroup:
-       """
-       The IDGroup Type
-       ================
-       This type supports both iteration and the []
-       operator to get child ID properties.
-       
-       You can also add new properties using the [] operator.
-       For example::
-       
-               group['a float!'] = 0.0
-               group['an int!'] = 0
-               group['a string!'] = "hi!"
-               group['an array!'] = [0, 0, 1.0, 0]
-               
-               group['a subgroup!] = {"float": 0.0, "an int": 1.0, "an array": [1, 2],
-                 "another subgroup": {"a": 0.0, "str": "bleh"}}
-       
-       Note that for arrays, the array type defaults to int unless a float is found
-       while scanning the template list; if any floats are found, then the whole
-       array is float.  Note that double-precision floating point numbers are used for
-       python-created float ID properties and arrays (though the internal C api does 
-       support single-precision floats, and the python code will read them).
-       
-       You can also delete properties with the del operator.  For example:
-       
-       del group['property']
-       
-       To get the type of a property, use the type() operator, for example::
-       
-               if type(group['bleh']) == str: pass
-       
-       To tell if the property is a group or array type, import the Blender.Types module and test
-       against IDGroupType and IDArrayType, like so::
-       
-               from Blender.Types import IDGroupType, IDArrayType.
-       
-               if type(group['bleghr']) == IDGroupType:
-                       (do something)
-       
-       @ivar name: The name of the property
-       @type name: string
-       """
-       
-       def pop(item):
-               """
-               Pop an item from the group property.
-               @type item: string
-               @param item: The item name.
-               @rtype: can be dict, list, int, float or string.
-               @return: The removed property.  
-               """
-               
-       def update(updatedict):
-               """
-               Updates items in the dict, similar to normal python
-               dictionary method .update().
-               @type updatedict: dict
-               @param updatedict: A dict of simple types to derive updated/new IDProperties from.
-               @rtype: None
-               @return: None
-               """
-       
-       def keys():
-               """
-               Returns a list of the keys in this property group.
-               @rtype: list of strings.
-               @return: a list of the keys in this property group.     
-               """
-       
-       def values():
-               """
-               Returns a list of the values in this property group.
-               
-               Note that unless a value is itself a property group or an array, you 
-               cannot change it by changing the values in this list, you must change them
-               in the parent property group.
-               
-               For example,
-               
-               group['some_property'] = new_value
-               
-               . . .is correct, while,
-               
-               values = group.values()
-               values[0] = new_value
-               
-               . . .is wrong.
-               
-               @rtype: list of strings.
-               @return: a list of the values in this property group.
-               """
-       
-       def iteritems():
-               """
-               Implements the python dictionary iteritmes method.
-               
-               For example::
-
-                       for k, v in group.iteritems():
-                               print "Property name: " + k
-                               print "Property value: " + str(v)
-                       
-               @rtype: an iterator that spits out items of the form [key, value]
-               @return: an iterator.   
-               """
-       
-       def convert_to_pyobject():
-               """
-               Converts the entire property group to a purely python form.
-               
-               @rtype: dict
-               @return: A python dictionary representing the property group
-               """
-               
-class IDArray:
-       """
-       The IDArray Type
-       ================
-       
-       @ivar type: returns the type of the array, can be either IDP_Int or IDP_Float
-       """
-       
-       def __getitem__(index):
-               pass
-       
-       def __setitem__(index, value):
-               pass
-       
-       def __len__():
-               pass
-       
index 7e9868f35989db219620952844d57d720b03a81f..2a3213e4e6ff5aab7a2eae4e0543fe274c2ab7bc 100644 (file)
@@ -260,6 +260,7 @@ else:
         "bpy_extras",
         "gpu",
         "gpu.offscreen",
+        "idprop.types",
         "mathutils",
         "mathutils.bvhtree",
         "mathutils.geometry",
@@ -1731,6 +1732,7 @@ def write_rst_contents(basepath):
         "freestyle", "bgl", "blf",
         "gpu", "gpu.offscreen",
         "aud", "bpy_extras",
+        "idprop.types",
         # bmesh, submodules are in own page
         "bmesh",
     )
@@ -1880,6 +1882,7 @@ def write_rst_importable_modules(basepath):
         "bpy.app.handlers": "Application Handlers",
         "bpy.app.translations": "Application Translations",
         "bpy.props": "Property Definitions",
+        "idprop.types": "ID Property Access",
         "mathutils": "Math Types & Utilities",
         "mathutils.geometry": "Geometry Utilities",
         "mathutils.bvhtree": "BVHTree Utilities",
index 11646f3f3df25fc43a522f8ef74698b4b3cd8955..fe4a63e1e3d83b0dfd15964e19d30c1ceffbec01 100644 (file)
@@ -702,7 +702,17 @@ static PyObject *BPy_IDGroup_MapDataToPy(IDProperty *prop)
        return NULL;
 }
 
-static PyObject *BPy_IDGroup_Pop(BPy_IDProperty *self, PyObject *value)
+PyDoc_STRVAR(BPy_IDGroup_pop_doc,
+".. method:: pop(key)\n"
+"\n"
+"   Remove an item from the group, returning a Python representation.\n"
+"\n"
+"   :raises KeyError: When the item doesn't exist.\n"
+"\n"
+"   :arg key: Name of item to remove.\n"
+"   :type key: string\n"
+);
+static PyObject *BPy_IDGroup_pop(BPy_IDProperty *self, PyObject *value)
 {
        IDProperty *idprop;
        PyObject *pyform;
@@ -735,7 +745,12 @@ static PyObject *BPy_IDGroup_Pop(BPy_IDProperty *self, PyObject *value)
        return NULL;
 }
 
-static PyObject *BPy_IDGroup_IterItems(BPy_IDProperty *self)
+PyDoc_STRVAR(BPy_IDGroup_iter_items_doc,
+".. method:: iteritems()\n"
+"\n"
+"   Iterate through the items in the dict; behaves like dictionary method iteritems.\n"
+);
+static PyObject *BPy_IDGroup_iter_items(BPy_IDProperty *self)
 {
        BPy_IDGroup_Iter *iter = PyObject_New(BPy_IDGroup_Iter, &BPy_IDGroup_Iter_Type);
        iter->group = self;
@@ -829,18 +844,32 @@ PyObject *BPy_Wrap_GetItems(ID *id, IDProperty *prop)
        return seq;
 }
 
-
-static PyObject *BPy_IDGroup_GetKeys(BPy_IDProperty *self)
+PyDoc_STRVAR(BPy_IDGroup_keys_doc,
+".. method:: keys()\n"
+"\n"
+"   Return the keys associated with this group as a list of strings.\n"
+);
+static PyObject *BPy_IDGroup_keys(BPy_IDProperty *self)
 {
        return BPy_Wrap_GetKeys(self->prop);
 }
 
-static PyObject *BPy_IDGroup_GetValues(BPy_IDProperty *self)
+PyDoc_STRVAR(BPy_IDGroup_values_doc,
+".. method:: values()\n"
+"\n"
+"   Return the values associated with this group.\n"
+);
+static PyObject *BPy_IDGroup_values(BPy_IDProperty *self)
 {
        return BPy_Wrap_GetValues(self->id, self->prop);
 }
 
-static PyObject *BPy_IDGroup_GetItems(BPy_IDProperty *self)
+PyDoc_STRVAR(BPy_IDGroup_items_doc,
+".. method:: items()\n"
+"\n"
+"   Return the items associated with this group.\n"
+);
+static PyObject *BPy_IDGroup_items(BPy_IDProperty *self)
 {
        return BPy_Wrap_GetItems(self->id, self->prop);
 }
@@ -859,7 +888,15 @@ static int BPy_IDGroup_Contains(BPy_IDProperty *self, PyObject *value)
        return IDP_GetPropertyFromGroup(self->prop, name) ? 1 : 0;
 }
 
-static PyObject *BPy_IDGroup_Update(BPy_IDProperty *self, PyObject *value)
+PyDoc_STRVAR(BPy_IDGroup_update_doc,
+".. method:: update(other)\n"
+"\n"
+"   Update key, values.\n"
+"\n"
+"   :arg other: Updates the values in the group with this.\n"
+"   :type other: :class:`IDPropertyGroup` or dict\n"
+);
+static PyObject *BPy_IDGroup_update(BPy_IDProperty *self, PyObject *value)
 {
        PyObject *pkey, *pval;
        Py_ssize_t i = 0;
@@ -890,19 +927,33 @@ static PyObject *BPy_IDGroup_Update(BPy_IDProperty *self, PyObject *value)
        Py_RETURN_NONE;
 }
 
+PyDoc_STRVAR(BPy_IDGroup_to_dict_doc,
+".. method:: to_dict()\n"
+"\n"
+"   Return a purely python version of the group.\n"
+);
 static PyObject *BPy_IDGroup_to_dict(BPy_IDProperty *self)
 {
        return BPy_IDGroup_MapDataToPy(self->prop);
 }
 
+PyDoc_STRVAR(BPy_IDGroup_clear_doc,
+".. method:: clear()\n"
+"\n"
+"   Clear all members from this group.\n"
+);
 static PyObject *BPy_IDGroup_clear(BPy_IDProperty *self)
 {
        IDP_ClearProperty(self->prop);
        Py_RETURN_NONE;
 }
 
-/* Matches python dict.get(key, [default]) */
-static PyObject *BPy_IDGroup_Get(BPy_IDProperty *self, PyObject *args)
+PyDoc_STRVAR(BPy_IDGroup_get_doc,
+".. method:: get(key, default=None)\n"
+"\n"
+"   Return the value for key, if it exists, else default.\n"
+);
+static PyObject *BPy_IDGroup_get(BPy_IDProperty *self, PyObject *args)
 {
        IDProperty *idprop;
        const char *key;
@@ -923,24 +974,15 @@ static PyObject *BPy_IDGroup_Get(BPy_IDProperty *self, PyObject *args)
 }
 
 static struct PyMethodDef BPy_IDGroup_methods[] = {
-       {"pop", (PyCFunction)BPy_IDGroup_Pop, METH_O,
-        "pop an item from the group; raises KeyError if the item doesn't exist"},
-       {"iteritems", (PyCFunction)BPy_IDGroup_IterItems, METH_NOARGS,
-        "iterate through the items in the dict; behaves like dictionary method iteritems"},
-       {"keys", (PyCFunction)BPy_IDGroup_GetKeys, METH_NOARGS,
-        "get the keys associated with this group as a list of strings"},
-       {"values", (PyCFunction)BPy_IDGroup_GetValues, METH_NOARGS,
-        "get the values associated with this group"},
-       {"items", (PyCFunction)BPy_IDGroup_GetItems, METH_NOARGS,
-        "get the items associated with this group"},
-       {"update", (PyCFunction)BPy_IDGroup_Update, METH_O,
-        "updates the values in the group with the values of another or a dict"},
-       {"get", (PyCFunction)BPy_IDGroup_Get, METH_VARARGS,
-        "idprop.get(k[,d]) -> idprop[k] if k in idprop, else d.  d defaults to None"},
-       {"to_dict", (PyCFunction)BPy_IDGroup_to_dict, METH_NOARGS,
-        "return a purely python version of the group"},
-       {"clear", (PyCFunction)BPy_IDGroup_clear, METH_NOARGS,
-        "clear all members from this group"},
+       {"pop", (PyCFunction)BPy_IDGroup_pop, METH_O, BPy_IDGroup_pop_doc},
+       {"iteritems", (PyCFunction)BPy_IDGroup_iter_items, METH_NOARGS, BPy_IDGroup_iter_items_doc},
+       {"keys", (PyCFunction)BPy_IDGroup_keys, METH_NOARGS, BPy_IDGroup_keys_doc},
+       {"values", (PyCFunction)BPy_IDGroup_values, METH_NOARGS, BPy_IDGroup_values_doc},
+       {"items", (PyCFunction)BPy_IDGroup_items, METH_NOARGS, BPy_IDGroup_items_doc},
+       {"update", (PyCFunction)BPy_IDGroup_update, METH_O, BPy_IDGroup_update_doc},
+       {"get", (PyCFunction)BPy_IDGroup_get, METH_VARARGS, BPy_IDGroup_get_doc},
+       {"to_dict", (PyCFunction)BPy_IDGroup_to_dict, METH_NOARGS, BPy_IDGroup_to_dict_doc},
+       {"clear", (PyCFunction)BPy_IDGroup_clear, METH_NOARGS, BPy_IDGroup_clear_doc},
        {NULL, NULL, 0, NULL}
 };
 
@@ -1049,7 +1091,10 @@ static PyObject *BPy_IDArray_repr(BPy_IDArray *self)
        return PyUnicode_FromFormat("<bpy id property array [%d]>", self->prop->len);
 }
 
-static PyObject *BPy_IDArray_GetType(BPy_IDArray *self)
+PyDoc_STRVAR(BPy_IDArray_get_typecode_doc,
+"The type of the data in the array {'f': float, 'd': double, 'i': int}."
+);
+static PyObject *BPy_IDArray_get_typecode(BPy_IDArray *self)
 {
        switch (self->prop->subtype) {
                case IDP_FLOAT:  return PyUnicode_FromString("f");
@@ -1066,18 +1111,22 @@ static PyObject *BPy_IDArray_GetType(BPy_IDArray *self)
 
 static PyGetSetDef BPy_IDArray_getseters[] = {
        /* matches pythons array.typecode */
-       {(char *)"typecode", (getter)BPy_IDArray_GetType, (setter)NULL, (char *)"The type of the data in the array, is an int.", NULL},
+       {(char *)"typecode", (getter)BPy_IDArray_get_typecode, (setter)NULL, BPy_IDArray_get_typecode_doc, NULL},
        {NULL, NULL, NULL, NULL, NULL},
 };
 
+PyDoc_STRVAR(BPy_IDArray_to_list_doc,
+".. method:: to_list()\n"
+"\n"
+"   Return the array as a list.\n"
+);
 static PyObject *BPy_IDArray_to_list(BPy_IDArray *self)
 {
        return BPy_IDGroup_MapDataToPy(self->prop);
 }
 
 static PyMethodDef BPy_IDArray_methods[] = {
-       {"to_list", (PyCFunction)BPy_IDArray_to_list, METH_NOARGS,
-        "return the array as a list"},
+       {"to_list", (PyCFunction)BPy_IDArray_to_list, METH_NOARGS, BPy_IDArray_to_list_doc},
        {NULL, NULL, 0, NULL}
 };