diff options
author | Campbell Barton <ideasman42@gmail.com> | 2021-10-11 07:33:42 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2021-10-11 07:33:42 +0300 |
commit | bdd2a7f46646e266bfa7d926fbbffbf938c781fc (patch) | |
tree | ab58d73aaea1abfd594df0a16bc686be79f438c8 /source | |
parent | fef4dc7269099eeac452a14e68c475357d12ee6e (diff) |
Doc: expand on docstring for PyC_Long_AsBool
Diffstat (limited to 'source')
-rw-r--r-- | source/blender/python/generic/py_capi_utils.c | 25 |
1 files changed, 24 insertions, 1 deletions
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) { |