[Bf-blender-cvs] [bdd2a7f4664] master: Doc: expand on docstring for PyC_Long_AsBool
Campbell Barton
noreply at git.blender.org
Mon Oct 11 06:34:27 CEST 2021
Commit: bdd2a7f46646e266bfa7d926fbbffbf938c781fc
Author: Campbell Barton
Date: Mon Oct 11 15:33:42 2021 +1100
Branches: master
https://developer.blender.org/rBbdd2a7f46646e266bfa7d926fbbffbf938c781fc
Doc: expand on docstring for PyC_Long_AsBool
===================================================================
M source/blender/python/generic/py_capi_utils.c
===================================================================
diff --git a/source/blender/python/generic/py_capi_utils.c b/source/blender/python/generic/py_capi_utils.c
index 9dac5a4f21f..e847a5a5b5c 100644
--- a/source/blender/python/generic/py_capi_utils.c
+++ b/source/blender/python/generic/py_capi_utils.c
@@ -1649,7 +1649,30 @@ bool PyC_RunString_AsString(const char *imports[],
#endif
/**
- * Don't use `bool` return type, so -1 can be used as an error value.
+ *
+ * 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)
{
More information about the Bf-blender-cvs
mailing list