Warning: That file was not part of the compilation database. It may have many parsing errors.

1// This file is part of Pate, Kate' Python scripting plugin.
2//
3// A couple of useful macros and functions used inside of pate_engine.cpp and pate_plugin.cpp.
4//
5// Copyright (C) 2006 Paul Giannaros <paul@giannaros.org>
6// Copyright (C) 2012, 2013 Shaheed Haque <srhaque@theiet.org>
7//
8// This library is free software; you can redistribute it and/or
9// modify it under the terms of the GNU Lesser General Public
10// License as published by the Free Software Foundation; either
11// version 2.1 of the License, or (at your option) version 3, or any
12// later version accepted by the membership of KDE e.V. (or its
13// successor approved by the membership of KDE e.V.), which shall
14// act as a proxy defined in Section 6 of version 3 of the license.
15//
16// This library is distributed in the hope that it will be useful,
17// but WITHOUT ANY WARRANTY; without even the implied warranty of
18// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19// Lesser General Public License for more details.
20//
21// You should have received a copy of the GNU Lesser General Public
22// License along with this library. If not, see <http://www.gnu.org/licenses/>.
23//
24
25#ifndef __PATE_UTILITIES_H__
26# define __PATE_UTILITIES_H__
27
28# include <Python.h>
29# include <QString>
30
31class KConfigBase;
32
33/// Save us some ruddy time when printing out QStrings with UTF-8
34# define PQ(x) x.toUtf8().constData()
35
36namespace Pate {
37
38/**
39 * Instantiate this class on the stack to automatically get and release the
40 * GIL.
41 *
42 * Also, making all the utility functions members of this class means that in
43 * many cases the compiler tells us where the class in needed. In the remaining
44 * cases (i.e. bare calls to the Python C API), inspection is used to needed
45 * to add the requisite Python() object. To prevent this object being optimised
46 * away in these cases due to lack of use, all instances have the form of an
47 * assignment, e.g.:
48 *
49 * Python py = Python()
50 *
51 * This adds a little overhead, but this is a small price for consistency.
52 */
53class Python
54{
55public:
56 Python();
57 ~Python();
58
59 /**
60 * Load the Python interpreter.
61 */
62 static void libraryLoad();
63
64 /**
65 * Unload the Python interpreter.
66 */
67 static void libraryUnload();
68
69 /// Convert a QString to a Python unicode object.
70 static PyObject* unicode(const QString& string);
71
72 /// Convert a Python unicode object to a QString.
73 static QString unicode(PyObject* string);
74
75 /// Test if a Python object is compatible with a QString.
76 static bool isUnicode(PyObject* string);
77
78 /// Prepend a QString to a list as a Python unicode object
79 bool prependStringToList(PyObject* list, const QString& value);
80
81 /**
82 * Print and save (see @ref lastTraceback()) the current traceback in a
83 * form approximating what Python would print:
84 *
85 * Traceback (most recent call last):
86 * File "/home/shahhaqu/.kde/share/apps/kate/pate/pluginmgr.py", line 13, in <module>
87 * import kdeui
88 * ImportError: No module named kdeui
89 * Could not import pluginmgr.
90 */
91 void traceback(const QString& description);
92
93 /**
94 * Store the last traceback we handled using @ref traceback().
95 */
96 QString lastTraceback(void) const;
97
98 /**
99 * Create a Python dictionary from a KConfigBase instance, writing the
100 * string representation of the values.
101 */
102 void updateDictionaryFromConfiguration(PyObject* dictionary, const KConfigBase* config);
103
104 /**
105 * Write a Python dictionary to a configuration object, converting objects
106 * to their string representation along the way.
107 */
108 void updateConfigurationFromDictionary(KConfigBase* config, PyObject* dictionary);
109
110 /**
111 * Call the named module's named entry point.
112 */
113 bool functionCall(const char* functionName, const char* moduleName = PATE_ENGINE);
114 PyObject* functionCall(const char* functionName, const char* moduleName, PyObject* arguments);
115
116 /**
117 * Delete the item from the named module's dictionary.
118 */
119 bool itemStringDel(const char* item, const char* moduleName = PATE_ENGINE);
120
121 /**
122 * Get the item from the named module's dictionary.
123 *
124 * @return 0 or a borrowed reference to the item.
125 */
126 PyObject* itemString(const char* item, const char* moduleName = PATE_ENGINE);
127
128 /**
129 * Get the item from the given dictionary.
130 *
131 * @return 0 or a borrowed reference to the item.
132 */
133 PyObject* itemString(const char* item, PyObject* dict);
134
135 /**
136 * Set the item in the named module's dictionary.
137 */
138 bool itemStringSet(const char* item, PyObject* value, const char* moduleName = PATE_ENGINE);
139
140 /**
141 * Get the Actions defined by a module. The returned object is
142 * [ { function, ( text, icon, shortcut, menu ) }... ] for each module
143 * function decorated with @action.
144 *
145 * @return 0 or a new reference to the result.
146 */
147 PyObject* moduleActions(const char* moduleName);
148
149 /**
150 * Get the ConfigPages defined by a module. The returned object is
151 * [ { function, callable, ( name, fullName, icon ) }... ] for each module
152 * function decorated with @configPage.
153 *
154 * @return 0 or a new reference to the result.
155 */
156 PyObject* moduleConfigPages(const char* moduleName);
157
158 /**
159 * Get the named module's dictionary.
160 *
161 * @return 0 or a borrowed reference to the dictionary.
162 */
163 PyObject* moduleDict(const char* moduleName = PATE_ENGINE);
164
165 /**
166 * Get the help text defined by a module.
167 */
168 QString moduleHelp(const char* moduleName);
169
170 /**
171 * Import the named module.
172 *
173 * @return 0 or a borrowed reference to the module.
174 */
175 PyObject* moduleImport(const char* moduleName);
176
177 /**
178 * A void * for an arbitrary Qt/KDE object that has been wrapped by SIP. Nifty.
179 *
180 * @param o The object to be unwrapped. The reference is borrowed.
181 */
182 void* objectUnwrap(PyObject* o);
183
184 /**
185 * A PyObject * for an arbitrary Qt/KDE object using SIP wrapping. Nifty.
186 *
187 * @param o The object to be wrapped.
188 * @param className The full class name of o, e.g. "PyQt4.QtGui.QWidget".
189 * @return @c 0 or a new reference to the object.
190 */
191 PyObject* objectWrap(void* o, const QString& className);
192
193 /**
194 * Add a given path to to the front of \c PYTHONPATH
195 *
196 * @param path A string (path) to be added
197 * @return @c true on success, @c false otherwise.
198 */
199 bool prependPythonPaths(const QString& path);
200
201 /**
202 * Add listed paths to to the front of \c PYTHONPATH
203 *
204 * @param paths A string list (paths) to be added
205 * @return @c true on success, @c false otherwise.
206 */
207 bool prependPythonPaths(const QStringList& paths);
208
209 static const char* PATE_ENGINE;
210
211private:
212 /// @internal Helper function for @c prependPythonPaths overloads
213 bool prependPythonPaths(const QString&, PyObject*);
214 PyGILState_STATE m_state;
215 mutable QString m_traceback;
216
217 /**
218 * Run a handler function supplied by the kate module on another module.
219 *
220 * @return 0 or a new reference to the result.
221 */
222 PyObject* kateHandler(const char* moduleName, const char* handler);
223};
224
225} // namespace Pate
226#endif // __PATE_UTILITIES_H__
227// kate: indent-width 4;
228

Warning: That file was not part of the compilation database. It may have many parsing errors.