HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
PY_Python.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * COMMENTS:
7  * This file contains functions to run python code.
8  */
9 
10 #ifndef __PY_Python_h__
11 #define __PY_Python_h__
12 
13 #include "PY_API.h"
14 #include "PY_Result.h"
15 #include <UT/UT_String.h>
16 
18 
19 /// Expressions cannot contain multiple statements (defs, classes, print
20 /// statements, etc.) and they cannot contain multiple expressions. The
21 /// *InNewContext version creates a new PY_EvaluationContext, run the Python
22 /// code inside it, and destroys the context afterward.
24  const char *python_code, PY_Result::Type desired_result_type,
25  PY_EvaluationContext *context = NULL);
27  const char *python_code, PY_Result::Type desired_result_type);
28 
29 /// Evaluate a Python expression that should not generate any exceptions. If an
30 /// exception is raised the traceback will be displayed to the user, prefixed by
31 /// the specified heading.
33  const char *python_code,
34  PY_Result::Type desired_result_type,
35  const char *heading = NULL,
36  PY_EvaluationContext *context = NULL);
37 
38 /// Evaluate a Python expression that should not generate any exceptions and
39 /// should evaluate to an exact type. If an exception is raised a traceback
40 /// is displayed with the specified heading. If the wrong type is returned,
41 /// the specified error message is displayed with the heading. Returns true
42 /// on success and stores the result in "result".
44  const char *python_code,
45  PY_Result::Type desired_result_type,
46  PY_Result &result,
47  const char *error_heading,
48  const char *error_for_wrong_type,
49  PY_EvaluationContext *context = NULL);
50 
51 /// The result type from running statements in the current thread can be none
52 /// (indicating normal completion), error, or exit. The *InNewContext version
53 /// creates a new PY_EvaluationContext, run the Python code inside it, and
54 /// destroys the context afterward.
56  const char *python_code,
57  PY_EvaluationContext *context = NULL);
59  const char *python_code);
60 
61 /// This version of PYrunPythonStatements will set Python's sys.argv to the
62 /// arguments you supply. argv[0] will be the name of the Python file.
64  const char *python_code,
65  int argc, char *argv[],
66  PY_EvaluationContext *context = NULL,
67  bool update_path=true);
68 
69 /// Run Python code that should not generate any exceptions. If an exception
70 /// is raised the traceback will be displayed to the user, prefixed by the
71 /// specified heading.
73  const char *python_code,
74  const char *heading = NULL,
75  PY_EvaluationContext *context = NULL);
77  const char *python_code,
78  const char *heading = NULL);
79 
80 /// The argv version of PYrunPythonStatementsFromFile will set Python's sys.argv
81 /// to the arguments you supply. argv[0] will be the name of the Python file.
83  const char *filename,
84  PY_EvaluationContext *context = NULL);
86  int argc, char *argv[],
87  PY_EvaluationContext *context = NULL,
88  bool update_path=true);
89 
90 /// A non-empty string is returned if there are parse errors, a new thread
91 /// could not be started, or the file could not be loaded.
93  const char *python_code);
95  const char *file_name);
97  int argc, char *argv[], bool update_path=true);
98 
99 /// Return the python result containing a stack trace and exception information.
100 /// If no exception occurred, the result type is none.
102 
103 /// Given a python object and a desired type, try to convert it to that type.
104 /// python_object should be a PyObject*, but it's a void* to avoid having to
105 /// include Python.h from here.
106 ///
107 /// There are two versions: a performance-sensitive version that takes the
108 /// return PY_Result object by reference, and a convenience version one that
109 /// returns it by value.
111  void *opaque_python_object, PY_Result::Type desired_result_type);
113  void *opaque_python_object, PY_Result::Type desired_result_type,
114  PY_Result &result);
115 
116 /// Given an (opaque) callable Python object, call it with no arguments and
117 /// return its Python object result. If an exception occurred, it remains set
118 /// in the Python interpreter and this function returns null. This function
119 /// behaves much like calling PyObject_CallObject with a null argument
120 /// parameter, but the difference is that if calling the code generates a crash,
121 /// the signal is caught, an exception is set, and this function returns null.
122 PY_API void *PYcallObjectAndCatchCrashes(void *callable);
123 
124 /// We don't want to have to prefix things with "hou." in expressions.
125 /// So, we create a separate evaluation context for expressions where
126 /// "from hou import *" has been run.
128 
129 /// Given a string containing the contents of a module and the module's name,
130 /// compile the string and import that as a module. If no exception occurred,
131 /// the result type is none.
133  const char *module_name, const char *module_contents);
134 
135 /// Return a PyCodeObject * corresponding to the frame before the current eval
136 /// frame.
138 
139 /// Return a PyCodeObject * corresponding to the specified PyObject
140 PY_API void *PYgetCodeObjectForFunction(void *opaque_python_object);
141 
142 /// Set a callback that will be invoked by PYrunPython*AndExpectNoErrors
143 /// whenever an error occurs. If this callback is not set, the errors will
144 /// be printed to the console. This callback provides an opportunity to
145 /// pop up a dialog to display the errors.
147  void (*callback)(const char *heading, const char *error_message));
148 
149 /// Display a Python traceback with a given heading. If the traceback display
150 /// callback was set, it will be used to display the traceback.
152  const char *heading, const char *traceback_message);
153 
154 /// This function controls whether running Python code automatically sets the
155 /// HOM_Module implementation (by importing the hou Python module). Call
156 /// PYsetAutoInitializeFromPython to false if you don't hou to be imported
157 /// automatically; otherwise, it will. You must call this static method
158 /// before running any Python code. Once any Python code is run, this
159 /// setting has no effect.
160 PY_API void PYsetAutoInitializeFromPython(bool auto_initialize);
161 
162 /// This function is used by PY_InterpreterAutoLock to determine if
163 /// it should automatically import the hou module
165 
166 
167 /// Returns the absolute path to Houdini's Python modules.
168 PY_API const char *PYgetHoudiniModulePath();
169 
170 /// Bind and return a PY_Object 'function' from a specific module. The caller is responsible to
171 /// increment the Python object ref count.
172 PY_API PY_Result PYbindFunctionFromModule(const char* module_name, const char *func_name);
173 
174 /// Log result on std error, doesn't print anything if result is not an ERR type.
175 /// The error message is based on the format returned by PYgetErrorFormat()
176 /// params:
177 /// result: PY_Result object
178 /// title: title to use for building the error message
179 ///
180 PY_API void PYlogError(PY_Result const & result, const char* title);
181 
182 /// Return a formatted error message filled with a title and the detailed error
183 /// message set in the PY_Result object. Returns an empty string if the PY_Result
184 /// object is not an ERR type.
185 /// params:
186 /// result: PY_Result object
187 /// title: title to use for building the error message
188 /// format: error message format. Must be of the form "%s %s". See PYgetErrorFormat
189 /// for an example.
190 ///
192  PY_Result const & result,
193  const char* title,
194  const char* format );
195 
196 /// Returns the default error format string "%s\n%s\n" usable with PYformatError
197 /// and PYprocessError.
198 PY_API const char* PYgetErrorFormat();
199 
200 /// Process a python error object with a user function. PYprocessError creates an
201 /// error message and passes it to process_func for processing. The process_func
202 /// function would typically log the error on the console, in a file or throw an
203 /// exception.
204 ///
205 /// params:
206 /// result: PY_Result object set to ERR. Function does nothing if not set to ERR.
207 /// title: title of the error message
208 /// format: error message format. Must be of the form "%s %s". See
209 /// PYgetErrorFormat for an example.
210 /// process_func: user function to process the error, takes a pre-formatted error
211 /// string of type const char*.
212 
213 template<typename FUNC>
215  PY_Result const & result,
216  const char* title,
217  const char* format,
218  FUNC const& process_func )
219 {
220  if (result.myResultType != PY_Result::ERR)
221  {
222  // just return if the result is not an error
223  return;
224  }
225 
226  auto && errmsg = PYformatError(result, title, format);
227  process_func(errmsg.c_str());
228 }
229 #endif
PY_API bool PYrunPythonStatementsAndExpectNoErrors(const char *python_code, const char *heading=NULL, PY_EvaluationContext *context=NULL)
PY_API void PYsetAutoInitializeFromPython(bool auto_initialize)
PY_API PY_Result PYextractResultFromPythonObject(void *opaque_python_object, PY_Result::Type desired_result_type)
GT_API const UT_StringHolder filename
PY_API bool PYrunPythonStatementsInNewContextAndExpectNoErrors(const char *python_code, const char *heading=NULL)
PY_API PY_Result PYrunPythonStatementsFromFile(const char *filename, PY_EvaluationContext *context=NULL)
PY_API void PYlogError(PY_Result const &result, const char *title)
PY_API void PYdisplayPythonTraceback(const char *heading, const char *traceback_message)
PY_API bool PYautoInitializeFromPython()
PY_API void * PYgetCodeObjectForFunction(void *opaque_python_object)
Return a PyCodeObject * corresponding to the specified PyObject.
PY_API PY_Result PYrunPythonStatementsInNewContext(const char *python_code)
PY_API bool PYrunPythonExpressionOfExactType(const char *python_code, PY_Result::Type desired_result_type, PY_Result &result, const char *error_heading, const char *error_for_wrong_type, PY_EvaluationContext *context=NULL)
PY_API PY_Result PYrunPythonStatements(const char *python_code, PY_EvaluationContext *context=NULL)
PY_API PY_Result PYrunPythonExpressionAndExpectNoErrors(const char *python_code, PY_Result::Type desired_result_type, const char *heading=NULL, PY_EvaluationContext *context=NULL)
PY_API void PYsetPythonTracebackDisplayCallback(void(*callback)(const char *heading, const char *error_message))
PY_API const char * PYgetErrorFormat()
PY_API UT_String PYrunPythonStatementsInNewThread(const char *python_code)
#define PY_API
Definition: PY_API.h:10
void PYprocessError(PY_Result const &result, const char *title, const char *format, FUNC const &process_func)
Definition: PY_Python.h:214
PY_API void * PYcallObjectAndCatchCrashes(void *callable)
PY_API PY_Result PYbindFunctionFromModule(const char *module_name, const char *func_name)
PY_API PY_Result PYrunPythonExpressionInNewContext(const char *python_code, PY_Result::Type desired_result_type)
PY_API PY_EvaluationContext & PYgetPythonExpressionEvaluationContext()
GLint GLint GLsizei GLint GLenum format
Definition: glcorearb.h:107
PY_API PY_Result PYextractPythonException()
PY_API UT_String PYrunPythonStatementsFromFileInNewThread(const char *file_name)
PY_API const char * PYgetHoudiniModulePath()
Returns the absolute path to Houdini's Python modules.
PY_API PY_Result PYimportModuleFromString(const char *module_name, const char *module_contents)
PY_API void * PYgetCodeObjectForPrevFrame()
Type myResultType
Definition: PY_Result.h:47
PY_API UT_StringHolder PYformatError(PY_Result const &result, const char *title, const char *format)
PY_API PY_Result PYrunPythonExpression(const char *python_code, PY_Result::Type desired_result_type, PY_EvaluationContext *context=NULL)