From bdd2a7f46646e266bfa7d926fbbffbf938c781fc Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Mon, 11 Oct 2021 15:33:42 +1100 Subject: Doc: expand on docstring for PyC_Long_AsBool --- source/blender/python/generic/py_capi_utils.c | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) (limited to 'source/blender/python') 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) { -- cgit v1.2.3