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 | |
31 | class KConfigBase; |
32 | |
33 | /// Save us some ruddy time when printing out QStrings with UTF-8 |
34 | # define PQ(x) x.toUtf8().constData() |
35 | |
36 | namespace 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 | */ |
53 | class Python |
54 | { |
55 | public: |
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 | |
211 | private: |
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.