diff options
Diffstat (limited to 'source/blender/python/generic')
| -rw-r--r-- | source/blender/python/generic/bgl.c | 7 | ||||
| -rw-r--r-- | source/blender/python/generic/bgl.h | 9 | ||||
| -rw-r--r-- | source/blender/python/generic/bpy_threads.c | 2 | ||||
| -rw-r--r-- | source/blender/python/generic/idprop_py_api.c | 9 | ||||
| -rw-r--r-- | source/blender/python/generic/idprop_py_api.h | 9 | ||||
| -rw-r--r-- | source/blender/python/generic/py_capi_rna.c | 24 | ||||
| -rw-r--r-- | source/blender/python/generic/py_capi_rna.h | 24 | ||||
| -rw-r--r-- | source/blender/python/generic/py_capi_utils.c | 72 | ||||
| -rw-r--r-- | source/blender/python/generic/py_capi_utils.h | 86 | ||||
| -rw-r--r-- | source/blender/python/generic/python_utildefines.h | 12 |
10 files changed, 136 insertions, 118 deletions
diff --git a/source/blender/python/generic/bgl.c b/source/blender/python/generic/bgl.c index e416727fa70..3f01ff86f49 100644 --- a/source/blender/python/generic/bgl.c +++ b/source/blender/python/generic/bgl.c @@ -666,13 +666,6 @@ static Buffer *BGL_MakeBuffer_FromData( return buffer; } -/** - * Create a buffer object - * - * \param dimensions: An array of ndimensions integers representing the size of each dimension. - * \param initbuffer: When not NULL holds a contiguous buffer - * with the correct format from which the buffer will be initialized - */ Buffer *BGL_MakeBuffer(int type, int ndimensions, int *dimensions, void *initbuffer) { Buffer *buffer; diff --git a/source/blender/python/generic/bgl.h b/source/blender/python/generic/bgl.h index 4e59eab46ce..479c69b5de2 100644 --- a/source/blender/python/generic/bgl.h +++ b/source/blender/python/generic/bgl.h @@ -22,6 +22,13 @@ PyObject *BPyInit_bgl(void); +/** + * Create a buffer object + * + * \param dimensions: An array of ndimensions integers representing the size of each dimension. + * \param initbuffer: When not NULL holds a contiguous buffer + * with the correct format from which the buffer will be initialized + */ struct _Buffer *BGL_MakeBuffer(int type, int ndimensions, int *dimensions, void *initbuffer); int BGL_typeSize(int type); @@ -50,5 +57,5 @@ typedef struct _Buffer { } buf; } Buffer; -/** The type object */ +/** The type object. */ extern PyTypeObject BGL_bufferType; diff --git a/source/blender/python/generic/bpy_threads.c b/source/blender/python/generic/bpy_threads.c index 8aa8c5c5d92..41e2fb4adf2 100644 --- a/source/blender/python/generic/bpy_threads.c +++ b/source/blender/python/generic/bpy_threads.c @@ -26,7 +26,6 @@ #include "../BPY_extern.h" #include "BLI_utildefines.h" -/* analogue of PyEval_SaveThread() */ BPy_ThreadStatePtr BPY_thread_save(void) { /* Use `_PyThreadState_UncheckedGet()` instead of `PyThreadState_Get()`, to avoid a fatal error @@ -40,7 +39,6 @@ BPy_ThreadStatePtr BPY_thread_save(void) return NULL; } -/* analogue of PyEval_RestoreThread() */ void BPY_thread_restore(BPy_ThreadStatePtr tstate) { if (tstate) { diff --git a/source/blender/python/generic/idprop_py_api.c b/source/blender/python/generic/idprop_py_api.c index 8dc0d2fb857..0a870102b6f 100644 --- a/source/blender/python/generic/idprop_py_api.c +++ b/source/blender/python/generic/idprop_py_api.c @@ -686,12 +686,6 @@ static IDProperty *idp_from_PyObject(PyObject *name_obj, PyObject *ob) /** \name Mapping Get/Set (Internal Access) * \{ */ -/** - * \note group can be a pointer array or a group. - * assume we already checked key is a string. - * - * \return success. - */ bool BPy_IDProperty_Map_ValidateAndCreate(PyObject *name_obj, IDProperty *group, PyObject *ob) { IDProperty *prop = idp_from_PyObject(name_obj, ob); @@ -779,7 +773,6 @@ static PyObject *BPy_IDGroup_iter(BPy_IDProperty *self) return BPy_IDGroup_ViewKeys_CreatePyObject(self); } -/* for simple, non nested types this is the same as BPy_IDGroup_WrapData */ PyObject *BPy_IDGroup_MapDataToPy(IDProperty *prop) { switch (prop->type) { @@ -1975,6 +1968,8 @@ static PyBufferProcs BPy_IDArray_Buffer = { (releasebufferproc)BPy_IDArray_releasebuffer, }; +/** \} */ + /* -------------------------------------------------------------------- */ /** \name ID Array Type * \{ */ diff --git a/source/blender/python/generic/idprop_py_api.h b/source/blender/python/generic/idprop_py_api.h index f53c45b07c2..e4addcecc10 100644 --- a/source/blender/python/generic/idprop_py_api.h +++ b/source/blender/python/generic/idprop_py_api.h @@ -95,8 +95,17 @@ PyObject *BPy_Wrap_GetItems_View_WithID(struct ID *id, struct IDProperty *prop); int BPy_Wrap_SetMapItem(struct IDProperty *prop, PyObject *key, PyObject *val); +/** + * For simple, non nested types this is the same as #BPy_IDGroup_WrapData. + */ PyObject *BPy_IDGroup_MapDataToPy(struct IDProperty *prop); PyObject *BPy_IDGroup_WrapData(struct ID *id, struct IDProperty *prop, struct IDProperty *parent); +/** + * \note group can be a pointer array or a group. + * assume we already checked key is a string. + * + * \return success. + */ bool BPy_IDProperty_Map_ValidateAndCreate(PyObject *key, struct IDProperty *group, PyObject *ob); void IDProp_Init_Types(void); diff --git a/source/blender/python/generic/py_capi_rna.c b/source/blender/python/generic/py_capi_rna.c index 235b136ca74..a6a0d820d07 100644 --- a/source/blender/python/generic/py_capi_rna.c +++ b/source/blender/python/generic/py_capi_rna.c @@ -41,10 +41,6 @@ /** \name Enum Utilities * \{ */ -/** - * Convert all items into a single comma separated string. - * Use for creating useful error messages. - */ char *pyrna_enum_repr(const EnumPropertyItem *item) { DynStr *dynstr = BLI_dynstr_new(); @@ -69,9 +65,6 @@ char *pyrna_enum_repr(const EnumPropertyItem *item) /** \name Enum Conversion Utilities * \{ */ -/** - * Same as #RNA_enum_value_from_id, but raises an exception. - */ int pyrna_enum_value_from_id(const EnumPropertyItem *item, const char *identifier, int *r_value, @@ -88,14 +81,6 @@ int pyrna_enum_value_from_id(const EnumPropertyItem *item, return 0; } -/** - * Takes a set of strings and map it to and array of booleans. - * - * Useful when the values aren't flags. - * - * \param type_convert_sign: Maps signed to unsigned range, - * needed when we want to use the full range of a signed short/char. - */ BLI_bitmap *pyrna_enum_bitmap_from_set(const EnumPropertyItem *items, PyObject *value, int type_size, @@ -159,9 +144,6 @@ error: return NULL; } -/** - * 'value' _must_ be a set type, error check before calling. - */ int pyrna_enum_bitfield_from_set(const EnumPropertyItem *items, PyObject *value, int *r_value, @@ -223,9 +205,6 @@ PyObject *pyrna_enum_bitfield_as_set(const EnumPropertyItem *items, int value) /** \name Argument Parsing Helpers * \{ */ -/** - * Use with #PyArg_ParseTuple's `O&` formatting. - */ int pyrna_enum_value_parse_string(PyObject *o, void *p) { const char *identifier = PyUnicode_AsUTF8(o); @@ -244,9 +223,6 @@ int pyrna_enum_value_parse_string(PyObject *o, void *p) return 1; } -/** - * Use with #PyArg_ParseTuple's `O&` formatting. - */ int pyrna_enum_bitfield_parse_set(PyObject *o, void *p) { if (!PySet_Check(o)) { diff --git a/source/blender/python/generic/py_capi_rna.h b/source/blender/python/generic/py_capi_rna.h index 326ca777a4b..9733cb043ea 100644 --- a/source/blender/python/generic/py_capi_rna.h +++ b/source/blender/python/generic/py_capi_rna.h @@ -25,13 +25,28 @@ struct EnumPropertyItem; +/** + * Convert all items into a single comma separated string. + * Use for creating useful error messages. + */ char *pyrna_enum_repr(const struct EnumPropertyItem *item); +/** + * Same as #RNA_enum_value_from_id, but raises an exception. + */ int pyrna_enum_value_from_id(const struct EnumPropertyItem *item, const char *identifier, int *value, const char *error_prefix); +/** + * Takes a set of strings and map it to and array of booleans. + * + * Useful when the values aren't flags. + * + * \param type_convert_sign: Maps signed to unsigned range, + * needed when we want to use the full range of a signed short/char. + */ unsigned int *pyrna_enum_bitmap_from_set(const struct EnumPropertyItem *items, PyObject *value, int type_size, @@ -39,6 +54,9 @@ unsigned int *pyrna_enum_bitmap_from_set(const struct EnumPropertyItem *items, int bitmap_size, const char *error_prefix); +/** + * 'value' _must_ be a set type, error check before calling. + */ int pyrna_enum_bitfield_from_set(const struct EnumPropertyItem *items, PyObject *value, int *r_value, @@ -62,5 +80,11 @@ struct BPy_EnumProperty_Parse { int value; bool is_set; }; +/** + * Use with #PyArg_ParseTuple's `O&` formatting. + */ int pyrna_enum_value_parse_string(PyObject *o, void *p); +/** + * Use with #PyArg_ParseTuple's `O&` formatting. + */ int pyrna_enum_bitfield_parse_set(PyObject *o, void *p); diff --git a/source/blender/python/generic/py_capi_utils.c b/source/blender/python/generic/py_capi_utils.c index 9cccc2f608f..acb6d76f30b 100644 --- a/source/blender/python/generic/py_capi_utils.c +++ b/source/blender/python/generic/py_capi_utils.c @@ -470,10 +470,6 @@ PyObject *PyC_Tuple_PackArray_Multi_Bool(const bool *array, const int dims[], co /** \name Tuple/List Filling * \{ */ -/** - * Caller needs to ensure tuple is uninitialized. - * Handy for filling a tuple with None for eg. - */ void PyC_Tuple_Fill(PyObject *tuple, PyObject *value) { const uint tot = PyTuple_GET_SIZE(tuple); @@ -502,11 +498,6 @@ void PyC_List_Fill(PyObject *list, PyObject *value) /** \name Bool/Enum Argument Parsing * \{ */ -/** - * Use with PyArg_ParseTuple's "O&" formatting. - * - * \see #PyC_Long_AsBool for a similar function to use outside of argument parsing. - */ int PyC_ParseBool(PyObject *o, void *p) { bool *bool_p = p; @@ -520,9 +511,6 @@ int PyC_ParseBool(PyObject *o, void *p) return 1; } -/** - * Use with PyArg_ParseTuple's "O&" formatting. - */ int PyC_ParseStringEnum(PyObject *o, void *p) { struct PyC_StringEnum *e = p; @@ -598,10 +586,6 @@ void PyC_ObSpit(const char *name, PyObject *var) } } -/** - * A version of #PyC_ObSpit that writes into a string (and doesn't take a name argument). - * Use for logging. - */ void PyC_ObSpitStr(char *result, size_t result_len, PyObject *var) { /* No name, creator of string can manage that. */ @@ -789,13 +773,6 @@ PyObject *PyC_FrozenSetFromStrings(const char **strings) /** \name Exception Utilities * \{ */ -/** - * Similar to #PyErr_Format(), - * - * Implementation - we can't actually prepend the existing exception, - * because it could have _any_ arguments given to it, so instead we get its - * `__str__` output and raise our own exception including it. - */ PyObject *PyC_Err_Format_Prefix(PyObject *exception_type_prefix, const char *format, ...) { PyObject *error_value_prefix; @@ -835,10 +812,6 @@ PyObject *PyC_Err_SetString_Prefix(PyObject *exception_type_prefix, const char * return PyC_Err_Format_Prefix(exception_type_prefix, "%s", str); } -/** - * Use for Python callbacks run directly from C, - * when we can't use normal methods of raising exceptions. - */ void PyC_Err_PrintWithFunc(PyObject *py_func) { /* since we return to C code we can't leave the error */ @@ -1014,7 +987,6 @@ PyObject *PyC_ExceptionBuffer_Simple(void) * In some cases we need to coerce strings, avoid doing this inline. * \{ */ -/* string conversion, escape non-unicode chars, coerce must be set to NULL */ const char *PyC_UnicodeAsByteAndSize(PyObject *py_str, Py_ssize_t *size, PyObject **coerce) { const char *result; @@ -1093,18 +1065,6 @@ PyObject *PyC_UnicodeFromByte(const char *str) /** \name Name Space Creation/Manipulation * \{ */ -/***************************************************************************** - * Description: This function creates a new Python dictionary object. - * NOTE: dict is owned by sys.modules["__main__"] module, reference is borrowed - * NOTE: important we use the dict from __main__, this is what python expects - * for 'pickle' to work as well as strings like this... - * >> foo = 10 - * >> print(__import__("__main__").foo) - * - * NOTE: this overwrites __main__ which gives problems with nested calls. - * be sure to run PyC_MainModule_Backup & PyC_MainModule_Restore if there is - * any chance that python is in the call stack. - ****************************************************************************/ PyObject *PyC_DefaultNameSpace(const char *filename) { PyObject *modules = PyImport_GetModuleDict(); @@ -1143,7 +1103,6 @@ bool PyC_NameSpace_ImportArray(PyObject *py_dict, const char *imports[]) return true; } -/* restore MUST be called after this */ void PyC_MainModule_Backup(PyObject **r_main_mod) { PyObject *modules = PyImport_GetModuleDict(); @@ -1468,11 +1427,6 @@ PyObject *PyC_FlagSet_FromBitfield(PyC_FlagSet *items, int flag) /** \name Run String (Evaluate to Primitive Types) * \{ */ -/** - * \return success - * - * \note it is caller's responsibility to acquire & release GIL! - */ bool PyC_RunString_AsNumber(const char *imports[], const char *expr, const char *filename, @@ -1648,32 +1602,6 @@ bool PyC_RunString_AsString(const char *imports[], # pragma GCC diagnostic ignored "-Wtype-limits" #endif -/** - * - * Comparison with #PyObject_IsTrue - * ================================ - * - * Even though Python provides a way to retrieve the boolean value for an object, - * in many cases it's far too relaxed, with the following examples coercing values. - * - * \code{.py} - * data.value = "Text" # True. - * data.value = "" # False. - * data.value = {1, 2} # True - * data.value = {} # False. - * data.value = None # False. - * \endcode - * - * In practice this is often a mistake by the script author that doesn't behave as they expect. - * So it's better to be more strict for attribute assignment and function arguments, - * only accepting True/False 0/1. - * - * If coercing a value is desired, it can be done explicitly: `data.value = bool(value)` - * - * \see #PyC_ParseBool for use with #PyArg_ParseTuple and related functions. - * - * \note Don't use `bool` return type, so -1 can be used as an error value. - */ int PyC_Long_AsBool(PyObject *value) { const int test = _PyLong_AsInt(value); diff --git a/source/blender/python/generic/py_capi_utils.h b/source/blender/python/generic/py_capi_utils.h index a8695d2330a..f6d8d7298af 100644 --- a/source/blender/python/generic/py_capi_utils.h +++ b/source/blender/python/generic/py_capi_utils.h @@ -26,6 +26,10 @@ #include "BLI_utildefines_variadic.h" void PyC_ObSpit(const char *name, PyObject *var); +/** + * A version of #PyC_ObSpit that writes into a string (and doesn't take a name argument). + * Use for logging. + */ void PyC_ObSpitStr(char *result, size_t result_len, PyObject *var); void PyC_LineSpit(void); void PyC_StackSpit(void); @@ -34,9 +38,20 @@ PyObject *PyC_ExceptionBuffer_Simple(void); PyObject *PyC_Object_GetAttrStringArgs(PyObject *o, Py_ssize_t n, ...); PyObject *PyC_FrozenSetFromStrings(const char **strings); +/** + * Similar to #PyErr_Format(), + * + * Implementation - we can't actually prepend the existing exception, + * because it could have _any_ arguments given to it, so instead we get its + * `__str__` output and raise our own exception including it. + */ PyObject *PyC_Err_Format_Prefix(PyObject *exception_type_prefix, const char *format, ...); PyObject *PyC_Err_SetString_Prefix(PyObject *exception_type_prefix, const char *str); +/** + * Use for Python callbacks run directly from C, + * when we can't use normal methods of raising exceptions. + */ void PyC_Err_PrintWithFunc(PyObject *py_func); void PyC_FileAndNum(const char **r_filename, int *r_lineno); @@ -92,6 +107,10 @@ PyObject *PyC_Tuple_PackArray_Multi_F64(const double *array, const int dims[], c PyObject *PyC_Tuple_PackArray_Multi_I32(const int *array, const int dims[], const int dims_len); PyObject *PyC_Tuple_PackArray_Multi_Bool(const bool *array, const int dims[], const int dims_len); +/** + * Caller needs to ensure tuple is uninitialized. + * Handy for filling a tuple with None for eg. + */ void PyC_Tuple_Fill(PyObject *tuple, PyObject *value); void PyC_List_Fill(PyObject *list, PyObject *value); @@ -99,13 +118,39 @@ void PyC_List_Fill(PyObject *list, PyObject *value); PyObject *PyC_UnicodeFromByte(const char *str); PyObject *PyC_UnicodeFromByteAndSize(const char *str, Py_ssize_t size); const char *PyC_UnicodeAsByte(PyObject *py_str, PyObject **coerce); /* coerce must be NULL */ +/** + * String conversion, escape non-unicode chars + * \param coerce: must be set to NULL. + */ const char *PyC_UnicodeAsByteAndSize(PyObject *py_str, Py_ssize_t *size, PyObject **coerce); -/* name namespace function for bpy */ +/** + * Description: This function creates a new Python dictionary object. + * NOTE: dict is owned by sys.modules["__main__"] module, reference is borrowed + * NOTE: important we use the dict from __main__, this is what python expects + * for 'pickle' to work as well as strings like this... + * >> foo = 10 + * >> print(__import__("__main__").foo) + * + * NOTE: this overwrites __main__ which gives problems with nested calls. + * be sure to run PyC_MainModule_Backup & PyC_MainModule_Restore if there is + * any chance that python is in the call stack. + */ PyObject *PyC_DefaultNameSpace(const char *filename); void PyC_RunQuicky(const char *filepath, int n, ...); +/** + * Import `imports` into `py_dict`. + * + * \param py_dict: A Python dictionary, typically used as a name-space for script execution. + * \param imports: A NULL terminated array of strings. + * \return true when all modules import without errors, otherwise return false. + * The caller is expected to handle the exception. + */ bool PyC_NameSpace_ImportArray(PyObject *py_dict, const char *imports[]); +/** + * #PyC_MainModule_Restore MUST be called after #PyC_MainModule_Backup. + */ void PyC_MainModule_Backup(PyObject **r_main_mod); void PyC_MainModule_Restore(PyObject *main_mod); @@ -131,6 +176,11 @@ int PyC_FlagSet_ToBitfield(const PyC_FlagSet *items, const char *error_prefix); PyObject *PyC_FlagSet_FromBitfield(PyC_FlagSet *items, int flag); +/** + * \return success + * + * \note it is caller's responsibility to acquire & release GIL! + */ bool PyC_RunString_AsNumber(const char **imports, const char *expr, const char *filename, @@ -149,6 +199,11 @@ bool PyC_RunString_AsString(const char **imports, const char *filename, char **r_value); +/** + * Use with PyArg_ParseTuple's "O&" formatting. + * + * \see #PyC_Long_AsBool for a similar function to use outside of argument parsing. + */ int PyC_ParseBool(PyObject *o, void *p); struct PyC_StringEnumItems { @@ -160,6 +215,9 @@ struct PyC_StringEnum { int value_found; }; +/** + * Use with PyArg_ParseTuple's "O&" formatting. + */ int PyC_ParseStringEnum(PyObject *o, void *p); const char *PyC_StringEnum_FindIDFromValue(const struct PyC_StringEnumItems *items, const int value); @@ -167,6 +225,32 @@ const char *PyC_StringEnum_FindIDFromValue(const struct PyC_StringEnumItems *ite int PyC_CheckArgs_DeepCopy(PyObject *args); /* Integer parsing (with overflow checks), -1 on error. */ +/** + * + * Comparison with #PyObject_IsTrue + * ================================ + * + * Even though Python provides a way to retrieve the boolean value for an object, + * in many cases it's far too relaxed, with the following examples coercing values. + * + * \code{.py} + * data.value = "Text" # True. + * data.value = "" # False. + * data.value = {1, 2} # True + * data.value = {} # False. + * data.value = None # False. + * \endcode + * + * In practice this is often a mistake by the script author that doesn't behave as they expect. + * So it's better to be more strict for attribute assignment and function arguments, + * only accepting True/False 0/1. + * + * If coercing a value is desired, it can be done explicitly: `data.value = bool(value)` + * + * \see #PyC_ParseBool for use with #PyArg_ParseTuple and related functions. + * + * \note Don't use `bool` return type, so -1 can be used as an error value. + */ int PyC_Long_AsBool(PyObject *value); int8_t PyC_Long_AsI8(PyObject *value); int16_t PyC_Long_AsI16(PyObject *value); diff --git a/source/blender/python/generic/python_utildefines.h b/source/blender/python/generic/python_utildefines.h index 1f093e633e4..25300c2fd45 100644 --- a/source/blender/python/generic/python_utildefines.h +++ b/source/blender/python/generic/python_utildefines.h @@ -36,16 +36,20 @@ extern "C" { } \ (void)0 -/* wrap Py_INCREF & return the result, - * use sparingly to avoid comma operator or temp var assignment */ +/** + * Wrap #Py_INCREF & return the result, + * use sparingly to avoid comma operator or temp var assignment. + */ Py_LOCAL_INLINE(PyObject *) Py_INCREF_RET(PyObject *op) { Py_INCREF(op); return op; } -/* Append & transfer ownership to the list, - * avoids inline Py_DECREF all over (which is quite a large macro). */ +/** + * Append & transfer ownership to the list, + * avoids inline #Py_DECREF all over (which is quite a large macro). + */ Py_LOCAL_INLINE(int) PyList_APPEND(PyObject *op, PyObject *v) { int ret = PyList_Append(op, v); |