blender
/
blender
128
396
Fork 569
Code Issues 6.2k Pull Requests 757 Projects 19 Wiki Activity

PyAPI docs: minor changes to sphinx docs.

This commit is contained in:
Campbell Barton 2015-01-08 03:53:55 +11:00
parent 19169de9f7
commit 7c53c3483c
2 changed files with 87 additions and 123 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

146
doc/python_api/rst/info_quickstart.rst
View File

@ -11,32 +11,22 @@ This API is generally stable but some areas are still being added and improved.
The Blender/Python API can do the following:
* Edit any data the user interface can (Scenes, Meshes, Particles etc.)
* Modify user preferences, keymaps and themes
* Run tools with own settings
* Create user interface elements such as menus, headers and panels
* Create new tools
* Create interactive tools
* Create new rendering engines that integrate with Blender
* Define new settings in existing Blender data
* Draw in the 3D view using OpenGL commands from Python
- Edit any data the user interface can (Scenes, Meshes, Particles etc.)
- Modify user preferences, keymaps and themes
- Run tools with own settings
- Create user interface elements such as menus, headers and panels
- Create new tools
- Create interactive tools
- Create new rendering engines that integrate with Blender
- Define new settings in existing Blender data
- Draw in the 3D view using OpenGL commands from Python
The Blender/Python API **can't** (yet)...
* Create new space types.
* Assign custom properties to every type.
* Define callbacks or listeners to be notified when data is changed.
- Create new space types.
- Assign custom properties to every type.
- Define callbacks or listeners to be notified when data is changed.
Before Starting
@ -47,23 +37,21 @@ This document isn't intended to fully cover each topic. Rather, its purpose is t
A quick list of helpful things to know before starting:
* Blender uses Python 3.x; some 3rd party extensions are not available yet.
- Blender uses Python 3.x; some online documentation still assumes 2.x.
- The interactive console is great for testing one-liners, It also has autocompletion so you can inspect the API quickly.
- Button tool tips show Python attributes and operator names.
- Right clicking on buttons and menu items directly links to API documentation.
- For more examples, the text menu has a templates section where some example operators can be found.
- To examine further scripts distributed with Blender, see:
* The interactive console is great for testing one-liners, It also has autocompletion so you can inspect the api quickly.
* Button tool tips show Python attributes and operator names.
* Right clicking on buttons and menu items directly links to API documentation.
* For more examples, the text menu has a templates section where some example operators can be found.
* To examine further scripts distributed with Blender, see ``~/.blender/scripts/startup/bl_ui`` for the user interface and ``~/.blender/scripts/startup/bl_op`` for operators.
| ``~/.blender/scripts/startup/bl_ui`` for the user interface,
| ``~/.blender/scripts/startup/bl_op`` for operators.
Running Scripts
---------------
The two most common ways to execute python scripts are using the built-in text editor or entering commands in the python console.
The two most common ways to execute Python scripts are using the built-in text editor or entering commands in the Python console.
Both the **Text Editor** and **Python Console** are space types you can select from the view header.
@ -82,7 +70,7 @@ Key Concepts
Data Access
-----------
Accessing datablocks
Accessing DataBlocks
^^^^^^^^^^^^^^^^^^^^
Python accesses Blender's data in the same way as the animation system and user interface; this implies that any setting that can be changed via a button can also be changed from Python.
@ -116,7 +104,7 @@ Unlike Python's dictionaries, both methods are acceptable; however, the index of
bpy.data.objects["Cube"]
Accessing attributes
Accessing Attributes
^^^^^^^^^^^^^^^^^^^^
Once you have a data block, such as a material, object, groups etc., its attributes can be accessed much like you would change a setting using the graphical interface. In fact, the tooltip for each button also displays the Python attribute which can help in finding what settings to change in a script.
@ -144,7 +132,7 @@ Example of a data path that can be quickly found via the console:
Data Creation/Removal
^^^^^^^^^^^^^^^^^^^^^
Those of you familiar with other python api's may be surprised that new datablocks in the bpy api can't be created by calling the class:
Those of you familiar with other Python API's may be surprised that new datablocks in the bpy API can't be created by calling the class:
>>> bpy.types.Mesh()
Traceback (most recent call last):
@ -153,9 +141,9 @@ Those of you familiar with other python api's may be surprised that new databloc
This is an intentional part of the API design.
The blender/python api can't create blender data that exists outside the main blender database (accessed through bpy.data), because this data is managed by blender (save/load/undo/append... etc).
The Blender/Python API can't create Blender data that exists outside the main Blender database (accessed through :mod:`bpy.data`), because this data is managed by Blender (save/load/undo/append... etc).
Data is added and removed via methods on the collections in bpy.data, eg:
Data is added and removed via methods on the collections in :mod:`bpy.data`, eg:
>>> mesh = bpy.data.meshes.new(name="MyMesh")
>>> print(mesh)
@ -167,7 +155,8 @@ Data is added and removed via methods on the collections in bpy.data, eg:
Custom Properties
^^^^^^^^^^^^^^^^^
Python can access properties on any datablock that has an ID (data that can be linked in and accessed from :mod:`bpy.data`. When assigning a property, you can make up your own names, these will be created when needed or overwritten if they exist.
Python can access properties on any datablock that has an ID (data that can be linked in and accessed from :mod:`bpy.data`.
When assigning a property, you can make up your own names, these will be created when needed or overwritten if they exist.
This data is saved with the blend file and copied with objects.
@ -180,7 +169,7 @@ Example:
if "SomeProp" in bpy.context.object:
print("Property found")
# Use the get function like a python dictionary
# Use the get function like a Python dictionary
# which can have a fallback value.
value = bpy.data.scenes["Scene"].get("test_prop", "fallback value")
@ -193,11 +182,9 @@ Example:
Note that these properties can only be assigned basic Python types.
* int, float, string
* array of ints/floats
* dictionary (only string keys are supported, values must be basic types too)
- int, float, string
- array of ints/floats
- dictionary (only string keys are supported, values must be basic types too)
These properties are valid outside of Python. They can be animated by curves or used in driver paths.
@ -205,7 +192,8 @@ These properties are valid outside of Python. They can be animated by curves or
Context
-------
While it's useful to be able to access data directly by name or as a list, it's more common to operate on the user's selection. The context is always available from '''bpy.context''' and can be used to get the active object, scene, tool settings along with many other attributes.
While it's useful to be able to access data directly by name or as a list, it's more common to operate on the user's selection.
The context is always available from ``bpy.context`` and can be used to get the active object, scene, tool settings along with many other attributes.
Common-use cases:
@ -220,9 +208,10 @@ So ``bpy.context.object = obj`` will raise an error.
But ``bpy.context.scene.objects.active = obj`` will work as expected.
The context attributes change depending on where they are accessed. The 3D view has different context members than the console, so take care when accessing context attributes that the user state is known.
The context attributes change depending on where they are accessed.
The 3D view has different context members than the console, so take care when accessing context attributes that the user state is known.
See :mod:`bpy.context` API reference
See :mod:`bpy.context` API reference.
Operators (Tools)
@ -241,16 +230,17 @@ Examples:
.. note::
The menu item: Help -> Operator Cheat Sheet" gives a list of all operators and their default values in Python syntax, along with the generated docs. This is a good way to get an overview of all blender's operators.
The menu item: :menuselection:`Help --> Operator Cheat Sheet` gives a list of all operators and their default values in Python syntax, along with the generated docs.
This is a good way to get an overview of all Blender's operators.
Operator Poll()
^^^^^^^^^^^^^^^
Many operators have a "poll" function which may check that the mouse is in a valid area or that the object is in the correct mode (Edit Mode, Weight Paint etc).
When an operator's poll function fails within python, an exception is raised.
When an operator's poll function fails within Python, an exception is raised.
For example, calling bpy.ops.view3d.render_border() from the console raises the following error:
For example, calling ``bpy.ops.view3d.render_border()`` from the console raises the following error:
.. code-block:: python
@ -271,13 +261,10 @@ Integration
Python scripts can integrate with Blender in the following ways:
* By defining a rendering engine.
* By defining operators.
* By defining menus, headers and panels.
* By inserting new buttons into existing menus, headers and panels
- By defining a rendering engine.
- By defining operators.
- By defining menus, headers and panels.
- By inserting new buttons into existing menus, headers and panels
In Python, this is done by defining a class, which is a subclass of an existing type.
@ -292,24 +279,17 @@ Once this script runs, ``SimpleOperator`` is registered with Blender and can be
To run the script:
#. Highlight the above code then press Ctrl+C to copy it.
#. Highlight the above code then press :kbd:`Ctrl-C` to copy it.
#. Start Blender
#. Press Ctrl+Right twice to change to the Scripting layout.
#. Press :kbd:`Ctrl-Right` twice to change to the Scripting layout.
#. Click the button labeled ``New`` and the confirmation pop up in order to create a new text block.
#. Press Ctrl+V to paste the code into the text panel (the upper left frame).
#. Press :kbd:`Ctrl-V` to paste the code into the text panel (the upper left frame).
#. Click on the button **Run Script**.
#. Move your mouse into the 3D view, press spacebar for the operator search menu, and type "Simple".
#. Click on the "Simple Operator" item found in search.
.. seealso:: The class members with the **bl_** prefix are documented in the API
.. seealso:: The class members with the ``bl_`` prefix are documented in the API
reference :class:`bpy.types.Operator`
.. note:: The output from the ``main`` function is sent to the terminal; in order to see this, be sure to :ref:`use the terminal <use_the_terminal>`.
@ -317,33 +297,25 @@ To run the script:
Example Panel
-------------
Panels register themselves as a class, like an operator. Notice the extra **bl_** variables used to set the context they display in.
Panels register themselves as a class, like an operator. Notice the extra ``bl_`` variables used to set the context they display in.
.. literalinclude:: ../../../release/scripts/templates_py/ui_panel_simple.py
To run the script:
#. Highlight the above code then press Ctrl+C to copy it
#. Highlight the above code then press :kbd:`Ctrl-C` to copy it
#. Start Blender
#. Press Ctrl+Right twice to change to the Scripting layout
#. Press :kbd:`Ctrl-Right` twice to change to the Scripting layout
#. Click the button labeled ``New`` and the confirmation pop up in order to create a new text block.
#. Press Ctrl+V to paste the code into the text panel (the upper left frame)
#. Press :kbd:`Ctrl-V` to paste the code into the text panel (the upper left frame)
#. Click on the button **Run Script**.
To view the results:
#. Select the the default cube.
#. Click on the Object properties icon in the buttons panel (far right; appears as a tiny cube).
#. Scroll down to see a panel named **Hello World Panel**.
#. Changing the object name also updates **Hello World Panel's** Name: field.
Note the row distribution and the label and properties that are available through the code.
@ -362,16 +334,14 @@ Blender's Python API can be split up into 3 categories.
Native Types
------------
In simple cases returning a number or a string as a custom type would be cumbersome, so these are accessed as normal python types.
In simple cases returning a number or a string as a custom type would be cumbersome, so these are accessed as normal Python types.
* blender float/int/boolean -> float/int/boolean
* blender enumerator -> string
- Blender float/int/boolean -> float/int/boolean
- Blender enumerator -> string
>>> C.object.rotation_mode = 'AXIS_ANGLE'
* blender enumerator (multiple) -> set of strings
- Blender enumerator (multiple) -> set of strings
.. code-block:: python
@ -389,7 +359,7 @@ Used for Blender datablocks and collections: :class:`bpy.types.bpy_struct`
For data that contains its own attributes groups/meshes/bones/scenes... etc.
There are 2 main types that wrap Blenders data, one for datablocks (known internally as bpy_struct), another for properties.
There are 2 main types that wrap Blenders data, one for datablocks (known internally as ``bpy_struct``), another for properties.
>>> bpy.context.object
bpy.data.objects['Cube']

64
doc/python_api/rst/info_tutorial_addon.rst
View File

@ -19,21 +19,17 @@ Prerequisites
Before going through the tutorial you should...
* Familiarity with the basics of working in Blender.
* Know how to run a script in Blender's text editor (as documented in the quick-start)
* Have an understanding of Python primitive types (int, boolean, string, list, tuple, dictionary, and set).
* Be familiar with the concept of Python modules.
* Basic understanding of classes (object orientation) in Python.
- Familiarity with the basics of working in Blender.
- Know how to run a script in Blender's text editor (as documented in the quick-start)
- Have an understanding of Python primitive types (int, boolean, string, list, tuple, dictionary, and set).
- Be familiar with the concept of Python modules.
- Basic understanding of classes (object orientation) in Python.
Suggested reading before starting this tutorial.
* `Dive Into Python <http://getpython3.com/diveintopython3/index.html>`_ sections (1, 2, 3, 4, and 7).
* :ref:`Blender API Quickstart <info_quickstart>`
- `Dive Into Python <http://getpython3.com/diveintopython3/index.html>`_ sections (1, 2, 3, 4, and 7).
- :ref:`Blender API Quickstart <info_quickstart>`
to help become familiar with Blender/Python basics.
@ -45,13 +41,11 @@ Documentation Links
While going through the tutorial you may want to look into our reference documentation.
* :ref:`Blender API Overview <info_overview>`. -
- :ref:`Blender API Overview <info_overview>`. -
*This document is rather detailed but helpful if you want to know more on a topic.*
* :mod:`bpy.context` api reference. -
- :mod:`bpy.context` api reference. -
*Handy to have a list of available items your script may operate on.*
* :class:`bpy.types.Operator`. -
- :class:`bpy.types.Operator`. -
*The following addons define operators, these docs give details and more examples of operators.*
@ -78,11 +72,11 @@ To give an example, here is the simplest possible addon.
print("Goodbye World")
* ``bl_info`` is a dictionary containing addon meta-data such as the title, version and author to be displayed in the
- ``bl_info`` is a dictionary containing addon meta-data such as the title, version and author to be displayed in the
user preferences addon list.
* ``register`` is a function which only runs when enabling the addon, this means the module can be loaded without
- ``register`` is a function which only runs when enabling the addon, this means the module can be loaded without
activating the addon.
* ``unregister`` is a function to unload anything setup by ``register``, this is called when the addon is disabled.
- ``unregister`` is a function to unload anything setup by ``register``, this is called when the addon is disabled.
@ -184,12 +178,15 @@ This addon takes the body of the script above, and adds them to an operator's ``
register()
.. note:: ``bl_info`` is split across multiple lines, this is just a style convention used to more easily add items.
.. note::
.. note:: Rather than using ``bpy.context.scene``, we use the ``context.scene`` argument passed to ``execute()``.
In most cases these will be the same however in some cases operators will be passed a custom context
so script authors should prefer the ``context`` argument passed to operators.
``bl_info`` is split across multiple lines, this is just a style convention used to more easily add items.
.. note::
Rather than using ``bpy.context.scene``, we use the ``context.scene`` argument passed to ``execute()``.
In most cases these will be the same however in some cases operators will be passed a custom context
so script authors should prefer the ``context`` argument passed to operators.
To test the script you can copy and paste this into Blender text editor and run it, this will execute the script
directly and call register immediately.
@ -202,8 +199,8 @@ However running the script wont move any objects, for this you need to execute t
:height: 574px
:alt: Spacebar
Do this by pressing ``SpaceBar`` to bring up the operator search dialog and type in "Move X by One" (the ``bl_label``),
then press ``Enter``.
Do this by pressing :kbd:`Spacebar` to bring up the operator search dialog and type in
"Move X by One" (the ``bl_label``), then :kbd:`Enter`.
@ -214,8 +211,8 @@ The objects should move as before.
Install The Addon
-----------------
Once you have your addon within in Blender's text editor, you will want to be able to install it so it can be enabled in
the user preferences to load on startup.
Once you have your addon within in Blender's text editor,
you will want to be able to install it so it can be enabled in the user preferences to load on startup.
Even though the addon above is a test, lets go through the steps anyway so you know how to do it for later.
@ -633,15 +630,12 @@ you want to see example code for, this is a good place to start.
Here are some sites you might like to check on after completing this tutorial.
* :ref:`Blender/Python API Overview <info_overview>` -
- :ref:`Blender/Python API Overview <info_overview>` -
*For more background details on Blender/Python integration.*
* `How to Think Like a Computer Scientist <http://interactivepython.org/courselib/static/thinkcspy/index.html>`_ -
- `How to Think Like a Computer Scientist <http://interactivepython.org/courselib/static/thinkcspy/index.html>`_ -
*Great info for those who are still learning Python.*
* `Blender Development (Wiki) <http://wiki.blender.org/index.php/Dev:Contents>`_ -
- `Blender Development (Wiki) <http://wiki.blender.org/index.php/Dev:Contents>`_ -
*Blender Development, general information and helpful links.*
* `Blender Artists (Coding Section) <http://blenderartists.org/forum/forumdisplay.php?47-Coding>`_ -
- `Blender Artists (Coding Section) <http://blenderartists.org/forum/forumdisplay.php?47-Coding>`_ -
*forum where people ask Python development questions*