HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros 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 
68 /// Run Python code that should not generate any exceptions. If an exception
69 /// is raised the traceback will be displayed to the user, prefixed by the
70 /// specified heading.
72  const char *python_code,
73  const char *heading = NULL,
74  PY_EvaluationContext *context = NULL);
76  const char *python_code,
77  const char *heading = NULL);
78 
79 /// The argv version of PYrunPythonStatementsFromFile will set Python's sys.argv
80 /// to the arguments you supply. argv[0] will be the name of the Python file.
82  const char *filename,
83  PY_EvaluationContext *context = NULL);
85  int argc, char *argv[],
86  PY_EvaluationContext *context = NULL);
87 
88 /// A non-empty string is returned if there are parse errors, a new thread
89 /// could not be started, or the file could not be loaded.
91  const char *python_code);
93  const char *file_name);
95  int argc, char *argv[]);
96 
97 /// Return the python result containing a stack trace and exception information.
98 /// If no exception occurred, the result type is none.
100 
101 /// Given a python object and a desired type, try to convert it to that type.
102 /// python_object should be a PyObject*, but it's a void* to avoid having to
103 /// include Python.h from here.
104 ///
105 /// There are two versions: a performance-sensitive version that takes the
106 /// return PY_Result object by reference, and a convenience version one that
107 /// returns it by value.
109  void *opaque_python_object, PY_Result::Type desired_result_type);
111  void *opaque_python_object, PY_Result::Type desired_result_type,
112  PY_Result &result);
113 
114 /// Given an (opaque) callable Python object, call it with no arguments and
115 /// return its Python object result. If an exception occurred, it remains set
116 /// in the Python interpreter and this function returns null. This function
117 /// behaves much like calling PyObject_CallObject with a null argument
118 /// parameter, but the difference is that if calling the code generates a crash,
119 /// the signal is caught, an exception is set, and this function returns null.
120 PY_API void *PYcallObjectAndCatchCrashes(void *callable);
121 
122 /// We don't want to have to prefix things with "hou." in expressions.
123 /// So, we create a separate evaluation context for expressions where
124 /// "from hou import *" has been run.
126 
127 /// Given a string containing the contents of a module and the module's name,
128 /// compile the string and import that as a module. If no exception occurred,
129 /// the result type is none.
131  const char *module_name, const char *module_contents);
132 
133 /// Return a PyCodeObject * corresponding to the frame before the current eval
134 /// frame.
136 
137 /// Return a PyCodeObject * corresponding to the specified PyObject
138 PY_API void *PYgetCodeObjectForFunction(void *opaque_python_object);
139 
140 /// Set a callback that will be invoked by PYrunPython*AndExpectNoErrors
141 /// whenever an error occurs. If this callback is not set, the errors will
142 /// be printed to the console. This callback provides an opportunity to
143 /// pop up a dialog to display the errors.
145  void (*callback)(const char *heading, const char *error_message));
146 
147 /// Display a Python traceback with a given heading. If the traceback display
148 /// callback was set, it will be used to display the traceback.
150  const char *heading, const char *traceback_message);
151 
152 /// This function controls whether running Python code automatically sets the
153 /// HOM_Module implementation (by importing the hou Python module). Call
154 /// PYsetAutoInitializeFromPython to false if you don't hou to be imported
155 /// automatically; otherwise, it will. You must call this static method
156 /// before running any Python code. Once any Python code is run, this
157 /// setting has no effect.
158 PY_API void PYsetAutoInitializeFromPython(bool auto_initialize);
159 
160 /// This function is used by PY_InterpreterAutoLock to determine if
161 /// it should automatically import the hou module
163 
164 
165 /// Returns the absolute path to Houdini's Python modules.
166 PY_API const char *PYgetHoudiniModulePath();
167 
168 #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)
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 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 UT_String PYrunPythonStatementsInNewThread(const char *python_code)
#define PY_API
Definition: PY_API.h:10
PY_API void * PYcallObjectAndCatchCrashes(void *callable)
PY_API PY_Result PYrunPythonExpressionInNewContext(const char *python_code, PY_Result::Type desired_result_type)
PY_API PY_EvaluationContext & PYgetPythonExpressionEvaluationContext()
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()
PY_API PY_Result PYrunPythonExpression(const char *python_code, PY_Result::Type desired_result_type, PY_EvaluationContext *context=NULL)