[Bf-blender-cvs] [bc1e517bb37] master: Docs: improve on doc-strings for BPY_extern_run.h
Campbell Barton
noreply at git.blender.org
Mon Dec 13 04:06:50 CET 2021
Commit: bc1e517bb378dc71fe9c45386e72dbbbe852284b
Author: Campbell Barton
Date: Mon Dec 13 13:09:14 2021 +1100
Branches: master
https://developer.blender.org/rBbc1e517bb378dc71fe9c45386e72dbbbe852284b
Docs: improve on doc-strings for BPY_extern_run.h
Also add ATTR_NONNULL function attributes.
===================================================================
M source/blender/python/BPY_extern_run.h
M source/blender/python/generic/py_capi_utils.h
M source/blender/python/intern/bpy_interface_run.c
===================================================================
diff --git a/source/blender/python/BPY_extern_run.h b/source/blender/python/BPY_extern_run.h
index 8eb8674d058..30740d7fb60 100644
--- a/source/blender/python/BPY_extern_run.h
+++ b/source/blender/python/BPY_extern_run.h
@@ -16,6 +16,20 @@
/** \file
* \ingroup python
+ *
+ * \subsection common_args Common Arguments
+ *
+ * - `C` the #bContext (never NULL).
+ *
+ * - `imports`: This is simply supported for convenience since imports can make constructing
+ * strings more cumbersome as otherwise small expressions become multi-line code-blocks.
+ * Optional (ignored when NULL), otherwise this is a NULL terminated array of module names.
+ *
+ Failure to import any modules prevents any further execution.
+ *
+ * - `err_info` #BPy_RunErrInfo is passed to some functions so errors can be forwarded to the UI.
+ * Option (when NULL errors are printed to the `stdout` and cleared).
+ * However this should be used in any case the error would be useful to show to the user.
*/
#pragma once
@@ -26,33 +40,85 @@ extern "C" {
#include "BLI_sys_types.h"
+#include "BLI_compiler_attrs.h"
+
struct ReportList;
struct Text;
struct bContext;
/* bpy_interface_run.c */
+/* -------------------------------------------------------------------- */
+/** \name Run File/Text as a Script
+ *
+ * \note #BPY_run_filepath and #BPY_run_filepath have almost identical behavior
+ * one operates on a file-path, the other on a blender text-block.
+ * \{ */
+
/**
- * Can run a file or text block.
+ * Execute `filepath` as a Python script.
+ *
+ * Wrapper for `PyRun_File` (similar to calling python with a script argument).
+ * Used for the `--python` command line argument.
+ *
+ * \param C: The context (never NULL).
+ * \param filepath: The file path to execute.
+ * \param reports: Failure to execute the script will report the exception here (may be NULL).
+ * \return true on success, otherwise false with an error reported to `reports`.
+ *
+ * \note Python scripts could consider `bpy.utils.execfile`, which has the advantage of returning
+ * the object as a module for data access & caching `pyc` file for faster re-execution.
+ */
+bool BPY_run_filepath(struct bContext *C, const char *filepath, struct ReportList *reports)
+ ATTR_NONNULL(1, 2);
+/**
+ * Execute a Blender `text` block as a Python script.
+ *
+ * Wrapper for `Py_CompileStringObject` & `PyEval_EvalCode`.
+ * Used for the `--python-text` command line argument.
+ *
+ * \param C: The context (never NULL).
+ * \param text: The text-block to execute.
+ * \param reports: Failure to execute the script will report the exception here (may be NULL).
+ * \param do_jump: When true, any error moves the cursor to the location of that error.
+ * Useful for executing scripts interactively from the text editor.
+ * \return true on success, otherwise false with an error reported to `reports`.
+ *
+ * \note The `__file__` is constructed by joining the blend file-path to the name of the text.
+ * This is done so error messages give useful output however there are rare cases causes problems
+ * with introspection tools which attempt to load `__file__`.
*/
-bool BPY_run_filepath(struct bContext *C, const char *filepath, struct ReportList *reports);
bool BPY_run_text(struct bContext *C,
struct Text *text,
struct ReportList *reports,
- const bool do_jump);
+ const bool do_jump) ATTR_NONNULL(1, 2);
-/* Use the 'eval' for simple single-line expressions,
- * otherwise 'exec' for full multi-line scripts. */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Run a String as a Script
+ *
+ * - Use 'eval' for simple single-line expressions.
+ * - Use 'exec' for full multi-line scripts.
+ * \{ */
/**
* Run an entire script, matches: `exec(compile(..., "exec"))`
*/
bool BPY_run_string_exec(struct bContext *C, const char *imports[], const char *expr);
/**
- * Run an expression, matches: `exec(compile(..., "eval"))`
+ * Run an expression, matches: `exec(compile(..., "eval"))`.
*/
bool BPY_run_string_eval(struct bContext *C, const char *imports[], const char *expr);
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Run a String as a Script & Return the Result
+ *
+ * Convenience functions for executing a script and returning the result as an expected type.
+ * \{ */
+
/**
* \note When this struct is passed in as NULL,
* print errors to the `stdout` and clear.
@@ -69,40 +135,63 @@ struct BPy_RunErrInfo {
char **r_string;
};
-/* Run, evaluating to fixed type result. */
-
/**
- * \return success
+ * Evaluate `expr` as a number (double).
+ *
+ * \param C: See \ref common_args.
+ * \param imports: See \ref common_args.
+ * \param expr: The expression to evaluate.
+ * \param err_info: See \ref common_args.
+ * \param r_value: The resulting value.
+ * \return Success.
*/
bool BPY_run_string_as_number(struct bContext *C,
const char *imports[],
const char *expr,
struct BPy_RunErrInfo *err_info,
- double *r_value);
+ double *r_value) ATTR_NONNULL(1, 3, 5);
/**
- * Support both int and pointers.
+ * Evaluate `expr` as an integer or pointer.
+ *
+ * \note Support both int and pointers.
*
- * \return success
+ * \param C: See \ref common_args.
+ * \param imports: See \ref common_args.
+ * \param expr: The expression to evaluate.
+ * \param err_info: See \ref common_args.
+ * \param r_value: The resulting value.
+ * \return Success.
*/
bool BPY_run_string_as_intptr(struct bContext *C,
const char *imports[],
const char *expr,
struct BPy_RunErrInfo *err_info,
- intptr_t *r_value);
+ intptr_t *r_value) ATTR_NONNULL(1, 3, 5);
/**
- * \return success
+ * Evaluate `expr` as a string.
+ *
+ * \param C: See \ref common_args.
+ * \param imports: See \ref common_args.
+ * \param expr: The expression to evaluate.
+ * \param err_info: See \ref common_args.
+ * \param r_value: The resulting value.
+ * \return Success.
*/
bool BPY_run_string_as_string_and_size(struct bContext *C,
const char *imports[],
const char *expr,
struct BPy_RunErrInfo *err_info,
char **r_value,
- size_t *r_value_size);
+ size_t *r_value_size) ATTR_NONNULL(1, 3, 5, 6);
+
+/** See #BPY_run_string_as_string_and_size */
bool BPY_run_string_as_string(struct bContext *C,
const char *imports[],
const char *expr,
struct BPy_RunErrInfo *err_info,
- char **r_value);
+ char **r_value) ATTR_NONNULL(1, 3, 5);
+
+/** \} */
#ifdef __cplusplus
} /* extern "C" */
diff --git a/source/blender/python/generic/py_capi_utils.h b/source/blender/python/generic/py_capi_utils.h
index 09eade9c477..f6d8d7298af 100644
--- a/source/blender/python/generic/py_capi_utils.h
+++ b/source/blender/python/generic/py_capi_utils.h
@@ -138,6 +138,14 @@ const char *PyC_UnicodeAsByteAndSize(PyObject *py_str, Py_ssize_t *size, PyObjec
*/
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[]);
/**
diff --git a/source/blender/python/intern/bpy_interface_run.c b/source/blender/python/intern/bpy_interface_run.c
index e9e5e9634d6..a4d54a4ce83 100644
--- a/source/blender/python/intern/bpy_interface_run.c
+++ b/source/blender/python/intern/bpy_interface_run.c
@@ -80,6 +80,14 @@ typedef struct {
} PyModuleObject;
#endif
+/**
+ * Execute a file-path or text-block.
+ *
+ * \param reports: Report exceptions as errors (may be NULL).
+ * \param do_jump: See #BPY_run_text.
+ *
+ * \note Share a function for this since setup/cleanup logic is the same.
+ */
static bool python_script_exec(
bContext *C, const char *fn, struct Text *text, struct ReportList *reports, const bool do_jump)
{
More information about the Bf-blender-cvs
mailing list