Cleanup: misc spelling fixes
[blender.git] / source / blender / python / intern / bpy.c
1 /*
2  * This program is free software; you can redistribute it and/or
3  * modify it under the terms of the GNU General Public License
4  * as published by the Free Software Foundation; either version 2
5  * of the License, or (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program; if not, write to the Free Software Foundation,
14  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
15  */
16
17 /** \file
18  * \ingroup pythonintern
19  *
20  * This file defines the '_bpy' module which is used by python's 'bpy' package
21  * to access C defined builtin functions.
22  * A script writer should never directly access this module.
23  */
24
25 #include <Python.h>
26
27 #include "BLI_utildefines.h"
28 #include "BLI_string.h"
29
30 #include "BKE_appdir.h"
31 #include "BKE_global.h" /* XXX, G_MAIN only */
32 #include "BKE_blender_version.h"
33 #include "BKE_bpath.h"
34
35 #include "RNA_types.h"
36 #include "RNA_access.h"
37
38 #include "bpy.h"
39 #include "bpy_capi_utils.h"
40 #include "bpy_rna.h"
41 #include "bpy_app.h"
42 #include "bpy_rna_id_collection.h"
43 #include "bpy_rna_gizmo.h"
44 #include "bpy_props.h"
45 #include "bpy_library.h"
46 #include "bpy_operator.h"
47 #include "bpy_utils_previews.h"
48 #include "bpy_utils_units.h"
49
50 #include "../generic/py_capi_utils.h"
51 #include "../generic/python_utildefines.h"
52
53 /* external util modules */
54 #include "../generic/idprop_py_api.h"
55 #include "bpy_msgbus.h"
56
57 #ifdef WITH_FREESTYLE
58 #  include "BPy_Freestyle.h"
59 #endif
60
61 PyObject *bpy_package_py = NULL;
62
63 PyDoc_STRVAR(bpy_script_paths_doc,
64              ".. function:: script_paths()\n"
65              "\n"
66              "   Return 2 paths to blender scripts directories.\n"
67              "\n"
68              "   :return: (system, user) strings will be empty when not found.\n"
69              "   :rtype: tuple of strings\n");
70 static PyObject *bpy_script_paths(PyObject *UNUSED(self))
71 {
72   PyObject *ret = PyTuple_New(2);
73   PyObject *item;
74   const char *path;
75
76   path = BKE_appdir_folder_id(BLENDER_SYSTEM_SCRIPTS, NULL);
77   item = PyC_UnicodeFromByte(path ? path : "");
78   BLI_assert(item != NULL);
79   PyTuple_SET_ITEM(ret, 0, item);
80   path = BKE_appdir_folder_id(BLENDER_USER_SCRIPTS, NULL);
81   item = PyC_UnicodeFromByte(path ? path : "");
82   BLI_assert(item != NULL);
83   PyTuple_SET_ITEM(ret, 1, item);
84
85   return ret;
86 }
87
88 static bool bpy_blend_paths_visit_cb(void *userdata, char *UNUSED(path_dst), const char *path_src)
89 {
90   PyList_APPEND((PyObject *)userdata, PyC_UnicodeFromByte(path_src));
91   return false; /* never edits the path */
92 }
93
94 PyDoc_STRVAR(bpy_blend_paths_doc,
95              ".. function:: blend_paths(absolute=False, packed=False, local=False)\n"
96              "\n"
97              "   Returns a list of paths to external files referenced by the loaded .blend file.\n"
98              "\n"
99              "   :arg absolute: When true the paths returned are made absolute.\n"
100              "   :type absolute: boolean\n"
101              "   :arg packed: When true skip file paths for packed data.\n"
102              "   :type packed: boolean\n"
103              "   :arg local: When true skip linked library paths.\n"
104              "   :type local: boolean\n"
105              "   :return: path list.\n"
106              "   :rtype: list of strings\n");
107 static PyObject *bpy_blend_paths(PyObject *UNUSED(self), PyObject *args, PyObject *kw)
108 {
109   int flag = 0;
110   PyObject *list;
111
112   bool absolute = false;
113   bool packed = false;
114   bool local = false;
115
116   static const char *_keywords[] = {"absolute", "packed", "local", NULL};
117   static _PyArg_Parser _parser = {"|O&O&O&:blend_paths", _keywords, 0};
118   if (!_PyArg_ParseTupleAndKeywordsFast(args,
119                                         kw,
120                                         &_parser,
121                                         PyC_ParseBool,
122                                         &absolute,
123                                         PyC_ParseBool,
124                                         &packed,
125                                         PyC_ParseBool,
126                                         &local)) {
127     return NULL;
128   }
129
130   if (absolute) {
131     flag |= BKE_BPATH_TRAVERSE_ABS;
132   }
133   if (!packed) {
134     flag |= BKE_BPATH_TRAVERSE_SKIP_PACKED;
135   }
136   if (local) {
137     flag |= BKE_BPATH_TRAVERSE_SKIP_LIBRARY;
138   }
139
140   list = PyList_New(0);
141
142   BKE_bpath_traverse_main(G_MAIN, bpy_blend_paths_visit_cb, flag, (void *)list);
143
144   return list;
145 }
146
147 // PyDoc_STRVAR(bpy_user_resource_doc[] = // now in bpy/utils.py
148 static PyObject *bpy_user_resource(PyObject *UNUSED(self), PyObject *args, PyObject *kw)
149 {
150   const char *type;
151   const char *subdir = NULL;
152   int folder_id;
153
154   const char *path;
155
156   static const char *_keywords[] = {"type", "subdir", NULL};
157   static _PyArg_Parser _parser = {"s|s:user_resource", _keywords, 0};
158   if (!_PyArg_ParseTupleAndKeywordsFast(args, kw, &_parser, &type, &subdir)) {
159     return NULL;
160   }
161
162   /* stupid string compare */
163   if (STREQ(type, "DATAFILES")) {
164     folder_id = BLENDER_USER_DATAFILES;
165   }
166   else if (STREQ(type, "CONFIG")) {
167     folder_id = BLENDER_USER_CONFIG;
168   }
169   else if (STREQ(type, "SCRIPTS")) {
170     folder_id = BLENDER_USER_SCRIPTS;
171   }
172   else if (STREQ(type, "AUTOSAVE")) {
173     folder_id = BLENDER_USER_AUTOSAVE;
174   }
175   else {
176     PyErr_SetString(PyExc_ValueError, "invalid resource argument");
177     return NULL;
178   }
179
180   /* same logic as BKE_appdir_folder_id_create(),
181    * but best leave it up to the script author to create */
182   path = BKE_appdir_folder_id_user_notest(folder_id, subdir);
183
184   return PyC_UnicodeFromByte(path ? path : "");
185 }
186
187 PyDoc_STRVAR(bpy_system_resource_doc,
188              ".. function:: system_resource(type, path=\"\")\n"
189              "\n"
190              "   Return a system resource path.\n"
191              "\n"
192              "   :arg type: string in ['DATAFILES', 'SCRIPTS', 'PYTHON'].\n"
193              "   :type type: string\n"
194              "   :arg path: Optional subdirectory.\n"
195              "   :type path: string\n");
196 static PyObject *bpy_system_resource(PyObject *UNUSED(self), PyObject *args, PyObject *kw)
197 {
198   const char *type;
199   const char *subdir = NULL;
200   int folder_id;
201
202   const char *path;
203
204   static const char *_keywords[] = {"type", "path", NULL};
205   static _PyArg_Parser _parser = {"s|s:system_resource", _keywords, 0};
206   if (!_PyArg_ParseTupleAndKeywordsFast(args, kw, &_parser, &type, &subdir)) {
207     return NULL;
208   }
209
210   /* stupid string compare */
211   if (STREQ(type, "DATAFILES")) {
212     folder_id = BLENDER_SYSTEM_DATAFILES;
213   }
214   else if (STREQ(type, "SCRIPTS")) {
215     folder_id = BLENDER_SYSTEM_SCRIPTS;
216   }
217   else if (STREQ(type, "PYTHON")) {
218     folder_id = BLENDER_SYSTEM_PYTHON;
219   }
220   else {
221     PyErr_SetString(PyExc_ValueError, "invalid resource argument");
222     return NULL;
223   }
224
225   path = BKE_appdir_folder_id(folder_id, subdir);
226
227   return PyC_UnicodeFromByte(path ? path : "");
228 }
229
230 PyDoc_STRVAR(
231     bpy_resource_path_doc,
232     ".. function:: resource_path(type, major=bpy.app.version[0], minor=bpy.app.version[1])\n"
233     "\n"
234     "   Return the base path for storing system files.\n"
235     "\n"
236     "   :arg type: string in ['USER', 'LOCAL', 'SYSTEM'].\n"
237     "   :type type: string\n"
238     "   :arg major: major version, defaults to current.\n"
239     "   :type major: int\n"
240     "   :arg minor: minor version, defaults to current.\n"
241     "   :type minor: string\n"
242     "   :return: the resource path (not necessarily existing).\n"
243     "   :rtype: string\n");
244 static PyObject *bpy_resource_path(PyObject *UNUSED(self), PyObject *args, PyObject *kw)
245 {
246   const char *type;
247   int major = BLENDER_VERSION / 100, minor = BLENDER_VERSION % 100;
248   int folder_id;
249   const char *path;
250
251   static const char *_keywords[] = {"type", "major", "minor", NULL};
252   static _PyArg_Parser _parser = {"s|ii:resource_path", _keywords, 0};
253   if (!_PyArg_ParseTupleAndKeywordsFast(args, kw, &_parser, &type, &major, &minor)) {
254     return NULL;
255   }
256
257   /* stupid string compare */
258   if (STREQ(type, "USER")) {
259     folder_id = BLENDER_RESOURCE_PATH_USER;
260   }
261   else if (STREQ(type, "LOCAL")) {
262     folder_id = BLENDER_RESOURCE_PATH_LOCAL;
263   }
264   else if (STREQ(type, "SYSTEM")) {
265     folder_id = BLENDER_RESOURCE_PATH_SYSTEM;
266   }
267   else {
268     PyErr_SetString(PyExc_ValueError, "invalid resource argument");
269     return NULL;
270   }
271
272   path = BKE_appdir_folder_id_version(folder_id, (major * 100) + minor, false);
273
274   return PyC_UnicodeFromByte(path ? path : "");
275 }
276
277 PyDoc_STRVAR(bpy_escape_identifier_doc,
278              ".. function:: escape_identifier(string)\n"
279              "\n"
280              "   Simple string escaping function used for animation paths.\n"
281              "\n"
282              "   :arg string: text\n"
283              "   :type string: string\n"
284              "   :return: The escaped string.\n"
285              "   :rtype: string\n");
286 static PyObject *bpy_escape_identifier(PyObject *UNUSED(self), PyObject *value)
287 {
288   const char *value_str;
289   Py_ssize_t value_str_len;
290
291   char *value_escape_str;
292   Py_ssize_t value_escape_str_len;
293   PyObject *value_escape;
294   size_t size;
295
296   value_str = _PyUnicode_AsStringAndSize(value, &value_str_len);
297
298   if (value_str == NULL) {
299     PyErr_SetString(PyExc_TypeError, "expected a string");
300     return NULL;
301   }
302
303   size = (value_str_len * 2) + 1;
304   value_escape_str = PyMem_MALLOC(size);
305   value_escape_str_len = BLI_strescape(value_escape_str, value_str, size);
306
307   if (value_escape_str_len == value_str_len) {
308     Py_INCREF(value);
309     value_escape = value;
310   }
311   else {
312     value_escape = PyUnicode_FromStringAndSize(value_escape_str, value_escape_str_len);
313   }
314
315   PyMem_FREE(value_escape_str);
316
317   return value_escape;
318 }
319
320 static PyMethodDef meth_bpy_script_paths = {
321     "script_paths",
322     (PyCFunction)bpy_script_paths,
323     METH_NOARGS,
324     bpy_script_paths_doc,
325 };
326 static PyMethodDef meth_bpy_blend_paths = {
327     "blend_paths",
328     (PyCFunction)bpy_blend_paths,
329     METH_VARARGS | METH_KEYWORDS,
330     bpy_blend_paths_doc,
331 };
332 static PyMethodDef meth_bpy_user_resource = {
333     "user_resource",
334     (PyCFunction)bpy_user_resource,
335     METH_VARARGS | METH_KEYWORDS,
336     NULL,
337 };
338 static PyMethodDef meth_bpy_system_resource = {
339     "system_resource",
340     (PyCFunction)bpy_system_resource,
341     METH_VARARGS | METH_KEYWORDS,
342     bpy_system_resource_doc,
343 };
344 static PyMethodDef meth_bpy_resource_path = {
345     "resource_path",
346     (PyCFunction)bpy_resource_path,
347     METH_VARARGS | METH_KEYWORDS,
348     bpy_resource_path_doc,
349 };
350 static PyMethodDef meth_bpy_escape_identifier = {
351     "escape_identifier",
352     (PyCFunction)bpy_escape_identifier,
353     METH_O,
354     bpy_escape_identifier_doc,
355 };
356
357 static PyObject *bpy_import_test(const char *modname)
358 {
359   PyObject *mod = PyImport_ImportModuleLevel(modname, NULL, NULL, NULL, 0);
360   if (mod) {
361     Py_DECREF(mod);
362   }
363   else {
364     PyErr_Print();
365     PyErr_Clear();
366   }
367
368   return mod;
369 }
370
371 /******************************************************************************
372  * Description: Creates the bpy module and adds it to sys.modules for importing
373  ******************************************************************************/
374 void BPy_init_modules(void)
375 {
376   PointerRNA ctx_ptr;
377   PyObject *mod;
378
379   /* Needs to be first since this dir is needed for future modules */
380   const char *const modpath = BKE_appdir_folder_id(BLENDER_SYSTEM_SCRIPTS, "modules");
381   if (modpath) {
382     // printf("bpy: found module path '%s'.\n", modpath);
383     PyObject *sys_path = PySys_GetObject("path"); /* borrow */
384     PyObject *py_modpath = PyUnicode_FromString(modpath);
385     PyList_Insert(sys_path, 0, py_modpath); /* add first */
386     Py_DECREF(py_modpath);
387   }
388   else {
389     printf("bpy: couldn't find 'scripts/modules', blender probably wont start.\n");
390   }
391   /* stand alone utility modules not related to blender directly */
392   IDProp_Init_Types(); /* not actually a submodule, just types */
393 #ifdef WITH_FREESTYLE
394   Freestyle_Init();
395 #endif
396
397   mod = PyModule_New("_bpy");
398
399   /* add the module so we can import it */
400   PyDict_SetItemString(PyImport_GetModuleDict(), "_bpy", mod);
401   Py_DECREF(mod);
402
403   /* run first, initializes rna types */
404   BPY_rna_init();
405
406   /* needs to be first so bpy_types can run */
407   PyModule_AddObject(mod, "types", BPY_rna_types());
408
409   /* needs to be first so bpy_types can run */
410   BPY_library_load_module(mod);
411   BPY_library_write_module(mod);
412
413   BPY_rna_id_collection_module(mod);
414
415   BPY_rna_gizmo_module(mod);
416
417   bpy_import_test("bpy_types");
418   PyModule_AddObject(mod, "data", BPY_rna_module()); /* imports bpy_types by running this */
419   bpy_import_test("bpy_types");
420   PyModule_AddObject(mod, "props", BPY_rna_props());
421   /* ops is now a python module that does the conversion from SOME_OT_foo -> some.foo */
422   PyModule_AddObject(mod, "ops", BPY_operator_module());
423   PyModule_AddObject(mod, "app", BPY_app_struct());
424   PyModule_AddObject(mod, "_utils_units", BPY_utils_units());
425   PyModule_AddObject(mod, "_utils_previews", BPY_utils_previews_module());
426   PyModule_AddObject(mod, "msgbus", BPY_msgbus_module());
427
428   /* bpy context */
429   RNA_pointer_create(NULL, &RNA_Context, (void *)BPy_GetContext(), &ctx_ptr);
430   bpy_context_module = (BPy_StructRNA *)pyrna_struct_CreatePyObject(&ctx_ptr);
431   /* odd that this is needed, 1 ref on creation and another for the module
432    * but without we get a crash on exit */
433   Py_INCREF(bpy_context_module);
434
435   PyModule_AddObject(mod, "context", (PyObject *)bpy_context_module);
436
437   /* register bpy/rna classmethod callbacks */
438   BPY_rna_register_cb();
439
440   /* utility func's that have nowhere else to go */
441   PyModule_AddObject(mod,
442                      meth_bpy_script_paths.ml_name,
443                      (PyObject *)PyCFunction_New(&meth_bpy_script_paths, NULL));
444   PyModule_AddObject(
445       mod, meth_bpy_blend_paths.ml_name, (PyObject *)PyCFunction_New(&meth_bpy_blend_paths, NULL));
446   PyModule_AddObject(mod,
447                      meth_bpy_user_resource.ml_name,
448                      (PyObject *)PyCFunction_New(&meth_bpy_user_resource, NULL));
449   PyModule_AddObject(mod,
450                      meth_bpy_system_resource.ml_name,
451                      (PyObject *)PyCFunction_New(&meth_bpy_system_resource, NULL));
452   PyModule_AddObject(mod,
453                      meth_bpy_resource_path.ml_name,
454                      (PyObject *)PyCFunction_New(&meth_bpy_resource_path, NULL));
455   PyModule_AddObject(mod,
456                      meth_bpy_escape_identifier.ml_name,
457                      (PyObject *)PyCFunction_New(&meth_bpy_escape_identifier, NULL));
458
459   /* register funcs (bpy_rna.c) */
460   PyModule_AddObject(mod,
461                      meth_bpy_register_class.ml_name,
462                      (PyObject *)PyCFunction_New(&meth_bpy_register_class, NULL));
463   PyModule_AddObject(mod,
464                      meth_bpy_unregister_class.ml_name,
465                      (PyObject *)PyCFunction_New(&meth_bpy_unregister_class, NULL));
466
467   PyModule_AddObject(mod,
468                      meth_bpy_owner_id_get.ml_name,
469                      (PyObject *)PyCFunction_New(&meth_bpy_owner_id_get, NULL));
470   PyModule_AddObject(mod,
471                      meth_bpy_owner_id_set.ml_name,
472                      (PyObject *)PyCFunction_New(&meth_bpy_owner_id_set, NULL));
473
474   /* add our own modules dir, this is a python package */
475   bpy_package_py = bpy_import_test("bpy");
476 }