diff --git a/doc/python_api/epy/IDProp.py b/doc/python_api/epy/IDProp.py deleted file mode 100644 index 1fc26d7f65b..00000000000 --- a/doc/python_api/epy/IDProp.py +++ /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 - diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index 7e9868f3598..2a3213e4e6f 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/doc/python_api/sphinx_doc_gen.py @@ -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", diff --git a/source/blender/python/generic/idprop_py_api.c b/source/blender/python/generic/idprop_py_api.c index 11646f3f3df..fe4a63e1e3d 100644 --- a/source/blender/python/generic/idprop_py_api.c +++ b/source/blender/python/generic/idprop_py_api.c @@ -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("", 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} };