1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
/* SPDX-License-Identifier: GPL-2.0-or-later */
/** \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
#ifdef __cplusplus
extern "C" {
#endif
#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.
* \{ */
/**
* 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_text(struct bContext *C, struct Text *text, struct ReportList *reports, bool do_jump)
ATTR_NONNULL(1, 2);
/** \} */
/* -------------------------------------------------------------------- */
/** \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"))`.
*/
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.
*/
struct BPy_RunErrInfo {
/** Brief text, single line (can show this in status bar for e.g.). */
bool use_single_line_error;
/** Report with optional prefix (when non-NULL). */
struct ReportList *reports;
const char *report_prefix;
/** Allocated exception text (assign when non-NULL). */
char **r_string;
};
/**
* 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) ATTR_NONNULL(1, 3, 5);
/**
* Evaluate `expr` as an integer or pointer.
*
* \note Support both int and pointers.
*
* \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) ATTR_NONNULL(1, 3, 5);
/**
* 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) 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) ATTR_NONNULL(1, 3, 5);
/** \} */
#ifdef __cplusplus
} /* extern "C" */
#endif
|
