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 #include <UT/UT_UniquePtr.h>
17 
19 class UT_Thread;
20 
21 /// Expressions cannot contain multiple statements (defs, classes, print
22 /// statements, etc.) and they cannot contain multiple expressions. The
23 /// *InNewContext version creates a new PY_EvaluationContext, run the Python
24 /// code inside it, and destroys the context afterward.
25 /// @{
27  const char *python_code, PY_Result::Type desired_result_type,
30  const char *python_code, PY_Result::Type desired_result_type);
31 /// @}
32 
33 /// Evaluate a Python expression that should not generate any exceptions. If an
34 /// exception is raised the traceback will be displayed to the user, prefixed by
35 /// the specified heading.
37  const char *python_code,
38  PY_Result::Type desired_result_type,
39  const char *heading = NULL,
41 
42 /// Evaluate a Python expression that should not generate any exceptions and
43 /// should evaluate to an exact type. If an exception is raised a traceback
44 /// is displayed with the specified heading. If the wrong type is returned,
45 /// the specified error message is displayed with the heading. Returns true
46 /// on success and stores the result in "result".
48  const char *python_code,
49  PY_Result::Type desired_result_type,
50  PY_Result &result,
51  const char *error_heading,
52  const char *error_for_wrong_type,
54 
55 /// The result type from running statements in the current thread can be none
56 /// (indicating normal completion), error, or exit. The *InNewContext version
57 /// creates a new PY_EvaluationContext, run the Python code inside it, and
58 /// destroys the context afterward.
59 ///
60 /// If `as_file` is not null, then `as_file` is used as the filename
61 /// that appears in syntax errors.
62 /// @{
64  const char *python_code,
66  const char *as_file=nullptr);
68  const char *python_code, const char *as_file=nullptr);
69 /// @}
70 
71 /// This version of PYrunPythonStatements will set Python's sys.argv to the
72 /// arguments you supply. argv[0] will be the name of the Python file.
74  const char *python_code,
75  int argc, char *argv[],
77  bool update_path=true);
78 
79 /// Run Python code that should not generate any exceptions. If an exception
80 /// is raised the traceback will be displayed to the user, prefixed by the
81 /// specified heading.
82 ///
83 /// If `as_file` is not null, then `as_file` is used as the filename
84 /// that appears in syntax errors.
85 /// @{
87  const char *python_code,
88  const char *heading = NULL,
90  const char *as_file=nullptr);
92  const char *python_code,
93  const char *heading = NULL,
94  const char *as_file=nullptr);
95 /// @}
96 
97 /// The argv version of PYrunPythonStatementsFromFile will set Python's sys.argv
98 /// to the arguments you supply. argv[0] will be the name of the Python file.
99 /// @{
101  const char *filename,
102  PY_EvaluationContext *context = NULL);
104  int argc, char *argv[],
106  bool update_path=true);
107 /// @}
108 
109 /// Run python code asynchronously and return the started thread if
110 /// successfully scheduled. If there are parse errors, a new thread could not
111 /// be started, or the file could not be loaded, then errors will be set to the
112 /// reason.
113 /// @{
115  const char *python_code, UT_String &errors);
117  const char *file_name, UT_String &errors);
119  int argc, char *argv[], UT_String &errors, bool update_path=true);
120 /// @}
121 
122 /// Return the python result containing a stack trace and exception information.
123 /// If no exception occurred, the result type is none.
125 
126 /// Given a python object and a desired type, try to convert it to that type.
127 /// python_object should be a PyObject*, but it's a void* to avoid having to
128 /// include Python.h from here.
129 ///
130 /// There are two versions: a performance-sensitive version that takes the
131 /// return PY_Result object by reference, and a convenience version one that
132 /// returns it by value.
133 /// @{
135  void *opaque_python_object, PY_Result::Type desired_result_type);
137  void *opaque_python_object, PY_Result::Type desired_result_type,
138  PY_Result &result);
139 /// @}
140 
141 /// Given an (opaque) Python object, call one of its methods with no arguments
142 /// and return its result, converting to the desired type.
144  void *opaque_python_object, const char *method_name,
145  PY_Result::Type desired_result_type);
146 
147 /// Given an (opaque) callable Python object, call it with no arguments and
148 /// return its Python object result. If an exception occurred, it remains set
149 /// in the Python interpreter and this function returns null. This function
150 /// behaves much like calling PyObject_CallObject with a null argument
151 /// parameter, but the difference is that if calling the code generates a crash,
152 /// the signal is caught, an exception is set, and this function returns null.
153 PY_API void *PYcallObjectAndCatchCrashes(void *callable);
154 
155 /// We don't want to have to prefix things with "hou." in expressions.
156 /// So, we create a separate evaluation context for expressions where
157 /// "from hou import *" has been run.
159 
160 /// Given a string containing the contents of a module and the module's name,
161 /// compile the string and import that as a module. If no exception occurred,
162 /// the result type is none.
164  const char *module_name, const char *module_contents);
165 
166 /// Return a PyCodeObject * corresponding to the frame before the current eval
167 /// frame.
169 
170 /// Return a PyCodeObject * corresponding to the specified PyObject
171 PY_API void *PYgetCodeObjectForFunction(void *opaque_python_object);
172 
173 /// Set a callback that will be invoked by PYrunPython*AndExpectNoErrors
174 /// whenever an error occurs. If this callback is not set, the errors will
175 /// be printed to the console. This callback provides an opportunity to
176 /// pop up a dialog to display the errors.
178  void (*callback)(const char *heading, const char *error_message));
179 
180 /// Display a Python traceback with a given heading. If the traceback display
181 /// callback was set, it will be used to display the traceback.
183  const char *heading, const char *traceback_message);
184 
185 /// This function controls whether running Python code automatically sets the
186 /// HOM_Module implementation (by importing the hou Python module). Call
187 /// PYsetAutoInitializeFromPython to false if you don't hou to be imported
188 /// automatically; otherwise, it will. You must call this static method
189 /// before running any Python code. Once any Python code is run, this
190 /// setting has no effect.
191 PY_API void PYsetAutoInitializeFromPython(bool auto_initialize);
192 
193 /// This function is used by PY_InterpreterAutoLock to determine if
194 /// it should automatically import the hou module
196 
197 
198 /// Returns the absolute path to Houdini's Python modules.
199 PY_API const char *PYgetHoudiniModulePath();
200 
201 /// Bind and return a PY_Object 'function' from a specific module. The caller
202 /// is responsible for incrementing the Python object ref count.
203 PY_API PY_Result PYbindFunctionFromModule(const char* module_name, const char *func_name);
204 
205 /// Log result on std error, doesn't print anything if result is not an ERR
206 /// type. The error message is based on the format returned by
207 /// PYgetErrorFormat()
208 /// params:
209 /// result: PY_Result object
210 /// title: title to use for building the error message
211 PY_API void PYlogError(PY_Result const & result, const char* title);
212 
213 /// Return a formatted error message filled with a title and the detailed error
214 /// message set in the PY_Result object. Returns an empty string if the
215 /// PY_Result object is not an ERR type.
216 /// params:
217 /// result: PY_Result object
218 /// title: title to use for building the error message
219 /// format: error message format. Must be of the form "%s %s". See
220 /// PYgetErrorFormat for an example.
222  PY_Result const & result,
223  const char* title,
224  const char* format );
225 
226 /// Returns the default error format string "%s\n%s\n" usable with
227 /// PYformatError and PYprocessError.
228 PY_API const char* PYgetErrorFormat();
229 
230 /// Register a callback function to be executed at exit time immediately before
231 /// Python shuts down.
232 PY_API void PYregisterAtExitCallback(std::function<void(void)> func);
233 
234 /// Process a python error object with a user function. PYprocessError creates
235 /// an error message and passes it to process_func for processing. The
236 /// process_func function would typically log the error on the console, in a
237 /// file or throw an exception.
238 ///
239 /// params:
240 /// result: PY_Result object set to ERR. Function does nothing if not set to
241 /// ERR.
242 /// title: title of the error message
243 /// format: error message format. Must be of the form "%s %s". See
244 /// PYgetErrorFormat for an example.
245 /// process_func: user function to process the error, takes a pre-formatted
246 /// error string of type const char*.
247 
248 template<typename FUNC>
250  PY_Result const & result,
251  const char* title,
252  const char* format,
253  FUNC const& process_func )
254 {
255  if (result.myResultType != PY_Result::ERR)
256  {
257  // just return if the result is not an error
258  return;
259  }
260 
261  auto && errmsg = PYformatError(result, title, format);
262  process_func(errmsg.c_str());
263 }
264 
265 #endif
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 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 UT_UniquePtr< UT_Thread > PYrunPythonStatementsFromFileInNewThread(const char *file_name, UT_String &errors)
PY_API PY_Result PYcallMethodOnPythonObject(void *opaque_python_object, const char *method_name, PY_Result::Type desired_result_type)
GLint GLint GLsizei GLsizei GLsizei GLint GLenum format
Definition: glew.h:1254
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 PYrunPythonStatementsInNewContext(const char *python_code, const char *as_file=nullptr)
PY_API bool PYrunPythonStatementsAndExpectNoErrors(const char *python_code, const char *heading=NULL, PY_EvaluationContext *context=NULL, const char *as_file=nullptr)
std::unique_ptr< T, Deleter > UT_UniquePtr
A smart pointer for unique ownership of dynamically allocated objects.
Definition: UT_UniquePtr.h:33
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()
#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:249
PY_API UT_UniquePtr< UT_Thread > PYrunPythonStatementsInNewThread(const char *python_code, UT_String &errors)
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()
GLenum func
Definition: glcorearb.h:782
PY_API PY_Result PYrunPythonStatements(const char *python_code, PY_EvaluationContext *context=NULL, const char *as_file=nullptr)
PY_API PY_Result PYextractPythonException()
GLuint64EXT * result
Definition: glew.h:14007
PY_API void PYregisterAtExitCallback(std::function< void(void)> func)
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:44
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)
PY_API bool PYrunPythonStatementsInNewContextAndExpectNoErrors(const char *python_code, const char *heading=NULL, const char *as_file=nullptr)