documentation - brief descriptions for bpy api files.
authorCampbell Barton <ideasman42@gmail.com>
Sat, 5 Nov 2011 08:21:12 +0000 (08:21 +0000)
committerCampbell Barton <ideasman42@gmail.com>
Sat, 5 Nov 2011 08:21:12 +0000 (08:21 +0000)
18 files changed:
source/blender/python/intern/bpy.c
source/blender/python/intern/bpy_app.c
source/blender/python/intern/bpy_app_handlers.c
source/blender/python/intern/bpy_driver.c
source/blender/python/intern/bpy_interface.c
source/blender/python/intern/bpy_interface_atexit.c
source/blender/python/intern/bpy_intern_string.c
source/blender/python/intern/bpy_library.c
source/blender/python/intern/bpy_operator.c
source/blender/python/intern/bpy_operator_wrap.c
source/blender/python/intern/bpy_props.c
source/blender/python/intern/bpy_rna.c
source/blender/python/intern/bpy_rna_anim.c
source/blender/python/intern/bpy_rna_array.c
source/blender/python/intern/bpy_rna_callback.c
source/blender/python/intern/bpy_traceback.c
source/blender/python/intern/bpy_util.c
source/blender/python/intern/gpu.c

index dfb7a1e8f75dc3d96d78a695d119ac8e059da394..2df907f3a12cc70b6839d2dacfb4c0983d380518 100644 (file)
 
 /** \file blender/python/intern/bpy.c
  *  \ingroup pythonintern
+ *
+ * This file defines the '_bpy' module which is used by python's 'bpy' package
+ * to access C defined builtin functions.
+ * A script writer should never directly access this module.
  */
-
-/* This file defines the '_bpy' module which is used by python's 'bpy' package.
- * a script writer should never directly access this module */
  
 #define WITH_PYTHON /* for AUD_PyInit.h, possibly others */
 
index cc3b88722b6f564d024afc3a23a2e6bebb2553f6..b5ae225fda7c61ed68b47089b0db22beba0ab5a2 100644 (file)
 
 /** \file blender/python/intern/bpy_app.c
  *  \ingroup pythonintern
+ *
+ * This file defines a 'PyStructSequence' accessed via 'bpy.app', mostly
+ * exposing static applications variables such as version and buildinfo
+ * however some writable variables have been added such as 'debug' and 'tempdir'
  */
 
 
index f130a4bcc5c2e543b306d44bd9ca209a65bea193..edab92b295beea7d1304af215a687c7f77c7e4c6 100644 (file)
 
 /** \file blender/python/intern/bpy_app_handlers.c
  *  \ingroup pythonintern
+ *
+ * This file defines a 'PyStructSequence' accessed via 'bpy.app.handlers',
+ * which exposes various lists that the script author can add callback
+ * functions into (called via blenders generic BLI_cb api)
  */
 
 #include <Python.h>
index 0fe1d2d26ba35559b4b1624a13ebf5e267b80fd2..98b4786607ff15df3b022e97a559db1d9cc9808b 100644 (file)
 
 /** \file blender/python/intern/bpy_driver.c
  *  \ingroup pythonintern
+ *
+ * This file defines the 'BPY_driver_exec' to execute python drivers,
+ * called by the animation system, there are also some utility functions
+ * to deal with the namespace used for driver execution.
  */
 
 /* ****************************************** */
index ea2266c99b4d90d1d691b2161b34a40254b9557d..ffa9e5cc27c99f719efebe980f5a0cc7bf49867e 100644 (file)
 
 /** \file blender/python/intern/bpy_interface.c
  *  \ingroup pythonintern
+ *
+ * This file deals with embedding the python interpreter within blender,
+ * starting and stopping python and exposing blender/python modules so they can
+ * be accesses from scripts.
  */
 
  
index aa5b934891c439ae7d65df4cdda20c21225e6beb..a0cf3c385030f35a8af24dc37971017afd8f7944 100644 (file)
 
 /** \file blender/python/intern/bpy_interface_atexit.c
  *  \ingroup pythonintern
+ *
+ * This file inserts an exit callback into pythons 'atexit' module.
+ * Without this sys.exit() can crash because blender is not properly closing
+ * resources.
  */
 
 
index 32d329e11b3694d78015aa4082ab4c97614f942d..4f206c4c365533a593552b059c78054110a0c296 100644 (file)
 
 /** \file blender/python/intern/bpy_intern_string.c
  *  \ingroup pythonintern
+ *
+ * Store python versions of strings frequently used for python lookups
+ * to avoid converting, creating the hash and freeing every time as
+ * PyDict_GetItemString and PyObject_GetAttrString do.
  */
 
 #include <Python.h>
index 382a513f40af2c5b9257db53a25bae4a20fa135a..54398f75a1d78e34894dcb1c1cb37ba0ca30de3e 100644 (file)
 
 /** \file blender/python/intern/bpy_library.c
  *  \ingroup pythonintern
+ *
+ * This file exposed blend file library appending/linking to python, typically
+ * this would be done via RNA api but in this case a hand written python api
+ * allows us to use pythons context manager (__enter__ and __exit__).
+ *
+ * Everything here is exposed via bpy.data.libraries.load(...) context manager.
  */
 
 /* nifty feature. swap out strings for RNA data */
index 70a5d79e9ac22e662ef02c3bba65c9cdb3206178..3fd4e8a128b40f1f2ef52c660fd19112bec6fd88 100644 (file)
@@ -1,6 +1,4 @@
-
 /*
- *
  * ***** BEGIN GPL LICENSE BLOCK *****
  *
  * This program is free software; you can redistribute it and/or
 
 /** \file blender/python/intern/bpy_operator.c
  *  \ingroup pythonintern
+ *
+ * This file defines '_bpy.ops', an internal python module which gives python
+ * the ability to inspect and call both C and Python defined operators.
+ *
+ * \note
+ * This module is exposed to the user via 'release/scripts/modules/bpy/ops.py'
+ * which fakes exposing operators as modules/functions using its own classes.
  */
 
 
index cb460f2fa08e9d5778c5081dd5ddef65094d19d5..aa45892520220735c8149600f386e091c588c49a 100644 (file)
 
 /** \file blender/python/intern/bpy_operator_wrap.c
  *  \ingroup pythonintern
+ *
+ * This file is so python can define operators that C can call into.
+ * The generic callback functions for python operators are defines in
+ * 'rna_wm.c', some calling into functions here to do python specific
+ * functionality.
  */
 
 
index cfd2e5556a1a5ca827176011e5d2258e3e645fb2..4dbaf5db4a4303c69c8b18a2a6cfe1f3e8422ccc 100644 (file)
 
 /** \file blender/python/intern/bpy_props.c
  *  \ingroup pythonintern
+ *
+ * This file defines 'bpy.props' module used so scripts can define their own
+ * rna properties for use with python operators or adding new properties to
+ * existing blender types.
  */
 
 
@@ -254,7 +258,7 @@ static int bpy_prop_callback_assign(struct PropertyRNA *prop, PyObject *update_c
 {
        /* assume this is already checked for type and arg length */
        if (update_cb) {
-               PyObject **py_data= MEM_callocN(sizeof(PyObject *) * BPY_DATA_CB_SLOT_SIZE, "bpy_prop_callback_assign");
+               PyObject **py_data= MEM_callocN(sizeof(PyObject *) * BPY_DATA_CB_SLOT_SIZE, __func__);
                RNA_def_property_update_runtime(prop, (void *)bpy_prop_update_cb);
                py_data[BPY_DATA_CB_SLOT_UPDATE]= update_cb;
                RNA_def_py_data(prop, py_data);
index 3411bceda69cc9830f77a501be5f8b39db72ce7a..44e26a56db64decde5df1008071da7ed1cd0dcb4 100644 (file)
 
 /** \file blender/python/intern/bpy_rna.c
  *  \ingroup pythonintern
+ *
+ * This file is the main interface between python and blenders data api (RNA),
+ * exposing RNA to python so blender data can be accessed in a python like way.
+ *
+ * The two main types are 'BPy_StructRNA' and 'BPy_PropertyRNA' - the base
+ * classes for most of the data python accesses in blender.
  */
 
-
 #include <Python.h>
 
 #include <stddef.h>
@@ -6470,7 +6475,9 @@ static int bpy_class_call(bContext *C, PointerRNA *ptr, FunctionRNA *func, Param
        const int is_operator= RNA_struct_is_a(ptr->type, &RNA_Operator);
        const char *func_id= RNA_function_identifier(func);
        /* testing, for correctness, not operator and not draw function */
-       const short is_readonly= strstr("draw", func_id) || /*strstr("render", func_id) ||*/ !is_operator;
+       const short is_readonly= ((strncmp("draw", func_id, 4) ==0) || /* draw or draw_header */
+                                                        /*strstr("render", func_id) ||*/
+                                                        !is_operator);
 #endif
 
        py_class= RNA_struct_py_type_get(ptr->type);
index 4ebb407f4d67ee3f3be23a3d5c503a98d5bd1b2f..edc6e672238ca55031c808a20c15858812085056 100644 (file)
@@ -22,6 +22,8 @@
 
 /** \file blender/python/intern/bpy_rna_anim.c
  *  \ingroup pythonintern
+ *
+ * This file defines the animation related methods used in bpy_rna.c
  */
 
 #include <Python.h>
index eda2511a1873d0bdc9047a4f85f89fd02d52119e..73e9e0a44d9ec7c8b1075ab2dca58d50ee6904aa 100644 (file)
  * along with this program; if not, write to the Free Software Foundation,
  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  *
- * Contributor(s): Arystanbek Dyussenov
+ * Contributor(s): Arystanbek Dyussenov, Campbell Barton
  *
  * ***** END GPL LICENSE BLOCK *****
  */
 
 /** \file blender/python/intern/bpy_rna_array.c
  *  \ingroup pythonintern
+ *
+ * This file deals with array access for 'BPy_PropertyArrayRNA' from bpy_rna.c
  */
 
 #include <Python.h>
index af6fc88097b7927302296a9150276f69e1d9c963..85f950947a79435f522805ed0c155b528af9b2d6 100644 (file)
@@ -22,6 +22,9 @@
 
 /** \file blender/python/intern/bpy_rna_callback.c
  *  \ingroup pythonintern
+ *
+ * This file currently exposes callbacks for interface regions but may be
+ * extended later.
  */
 
 
index aa21627a27911d818de119b7ef026b2b54dbbef7..5045f6708b517d4908f52fb5fce9a8fbac88962e 100644 (file)
@@ -20,6 +20,9 @@
 
 /** \file blender/python/intern/bpy_traceback.c
  *  \ingroup pythonintern
+ *
+ * This file contains utility functions for getting data from a python stack
+ * trace.
  */
 
 
index bec3a07d32a30618e3b95dff709f2fc4fe1737f2..43ca4da7ae22e43dddfd275b22fb91f419b7eb39 100644 (file)
@@ -22,6 +22,9 @@
 
 /** \file blender/python/intern/bpy_util.c
  *  \ingroup pythonintern
+ *
+ * This file contains blender/python utility functions for the api's internal
+ * use (unrelated to 'bpy.utils')
  */
 
 
index 1162491ee2679144dbb0c06c9d87d1592b27a740..57ce7b59067fca510cd926ab92da7ac5a4d8d4d1 100644 (file)
@@ -27,6 +27,9 @@
 
 /** \file blender/python/intern/gpu.c
  *  \ingroup pythonintern
+ *
+ * This file defines the 'gpu' module, used to get GLSL shader code and data
+ * from blender materials.
  */
 
 /* python redefines */