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  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 #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)