Yamyam: 1版をインポートしました

2018-06-28T17:51:13Z

1版をインポートしました

wiki>Mindrones: moved Dev:Source/BPython/API/bpy api to Dev:2.4/Source/Python/API/bpy api

2010-02-19T00:35:31Z

moved Dev:Source/BPython/API/bpy api to Dev:2.4/Source/Python/API/bpy api

新規ページ

= New developments in the Blender Python API =

{{Note|Note|The previous version of this page was moved to its discussion page (click on the "discussion" button above). Please check it for the actual discussions and much more info than found here. - [[User:ianwill|Willian]]}}

In this page (and its discussion page) we are considering additions for BPython. Below, we list the main specific points, mentioning their current state (implemented/under discussion).

== Investigating ==

== Decided ==

Topics here have either not been discussed enough yet or we didn't reach an agreement and are still researching what to do. In a future meeting we can decide about them.

=== Integrating Other Modules - part II ===
{{Note|Decision: bpy module|We will develop a new module alongside the existing 'Blender' module called bpy.
the existing bpy module will go into bpy.data and we will be able to have bpy.config and bpy.classes.

We will have a new directory for these called 'bpy'
}}

We have the old Blender module and its submodules and now we have the bpy module.

Since it was decided "bpy" will only be a representation of the database in Blender (bpy.meshes, bpy.scenes, etc.), we have now two "root" modules, Blender and bpy and won't include new submodules like Classes, Config, etc. in bpy.

So our alternatives for structuring (module hierarchy) are:

# Have Blender and bpy separated, add new submodules to Blender: Blender.Classes, Blender.Config, etc.
# Put bpy inside Blender: Blender.bpy (so ending with: Blender.bpy.meshes, etc.)
# Create a new "blender" module (jumping on the lowercase modules bandwagon): blender.bpy, blender.classes, blender.config, maybe blender.constants, someday blender.gui, etc.
# Something else?

=== Classes module ===
{{Note|Decision: Classes|Classes will be in their own submodule bpy.classes.Mesh for example}}

We still didn't define where the classes module will be. It was decided that it shouldn't be bpy.classes and that Blender.Classes was a good candidate. See previous topic for other possibilities...

Also, is "classes" the best name?

=== Constants ===
{{Note|Decision: Constants|Constants will be under their respective classes - bpy.classes.Mesh.TWOSIDE

}}

At the moment bpy.* has no access to constants. These are some favored possibilities:

# Class.constant
# dataseq.constants.* -- example: <code>bpy.meshes.constants.MODE_TWOSIDED</code>.
# A new module to group all constants.

'''Status''': still investigating / discussing.

The decisions here are based on voting during a meeting on Sunday (March 25, 2007).

[[User:Khughes|Khughes]] has written [http://wiki.blender.org/index.php?title=BlenderDev/Bitfields a proposal ] for a special PyType for Constants and has implemented it in prototype, but until then we will use what is there.

{{Note|[http://members.optusnet.com.au/cjbarton/BPY_API/Bpy-module.html Current API documentation]|generated and hosted by [[User:ideasman42|Ideasman42]].}}

=== Automatic importing ===

Adding important names (modules, variables, functions) to the builtin Python dictionary on startup.

Pros:
* simplicity: more results with less typing.

Cons:
* namespace pollution;
* could bring issues in the future (e.g. if it ever becomes possible to run such scripts from a standalone Python interpreter).

{{Note|Decision: No automatic importing|We will try other ways to achieve simplicity and less verbose scripts:
* A simple wrapper API on top of BPython, written in Python;
* Text templates for scripts in Blender's Text Editor.
}}

'''Status''': implemented by [[User:ideasman42|Ideasman42]].

=== The bpy module ===

{{Note|Decision: bpy|this new module is, like [[User:theeth|Theeth]] mentioned: a "representation of the current state in Blender" (of the "database", as [[User:Stivs|Stivs]] complemented. We should not add arbitrary modules or variables to it.
}}

Related decision: we will make bpy, etc. replace the old object data modules (Mesh, Lamp, Camera, etc. etc.) completely, no need for them anymore.

'''Status''': bpy implemented by [[User:ideasman42|Ideasman42]]. Rest of the work requires more investigation about sceneRender, etc. (where / how will these be reimplemented).

=== dataseq.load() VS dataseq.new() ===

All object types can be created with a dataseq.new() method. But some object types can be created from data loaded from disk: texts, images, sounds. Do we need a separate .load() method for these or is it ok to add the option for loading directly in their .new() methods?

{{Note|Decision: No need for .load() methods|We can add a "filename" parameter to dataseq.new to be used by those objects where it is needed.
}}

'''Status''': implemented by [[User:ideasman42|Ideasman42]].

=== Integrating Other Modules - part I ===

At the moment bpy has support for all datatypes (bpy.meshes, bpy.scenes etc)
as well as bpy.libraries and bpy.config. But how should we go about adding less data centric modules like Blender.Window, Draw, BGL, sys etc.

{{Note|Decision: we still need these old modules|Draw, BGL and Window should stay as they are, for now, in the Blender module.
}}

=== Constructors VS dataseq.new() ===

Example:<code>something.Mesh(name) VS bpy.meshes.new(name)</code>

A key point here is to avoid troubles we've had with the older BPython ways, like being able to create objects without data or not linked to any scene.

{{Note|Decision: It's desirable to have both alternatives|During the meeting we agreed that constructors are needed, but that the current dataseq.new() way could stay as alternative.
}}

[[User:Ascotan|Ascotan]] suggested a module named classes as a place for the constructors. Blender.Classes was mentioned by [[User:theeth|Theeth]] during the meeting. No decision yet.

'''Status''': still investigating / discussing.

=== Documentation ===

==== Deprecation ====

Since we're remodeling the API, it may be a good idea, only this time, to simply remove *from the documentation* all parts we decide to deprecate in the old API.

{{Note|Decision: remove deprecated parts the docs|To favor the new API developments, we plan to remove from our main documentation references to deprecated parts of the API. An older version of the reference guide will be kept so users can still find information about those parts, since they won't be removed from the API itself for now.
}}

'''Status''': We can only do this once we finish our current work. So it's not clear now if we will do this for 2.44 or later.

==== Focus ====

Our main document is an API Reference Guide. Its purpose is to list everything available in the BPython API, but it also contains many code samples and we try to explain things well.

Still, many users complain that it is not user-friendly enough, that it needs more examples, a more gentle introduction, whatever.

{{Note|Decision: reference guide separated from user manual|In the meeting we decided to split our documentation in ref guide + user manual. Details will be discussed / defined later.
}}

=== Programming Model For Error Handling ===

Programming models for error handling come in two basic flavors:
One is based on return codes, the other on exceptions.

* Return Codes - Each function call returns a status code or special value to indicate whether the call succeeded. Programming in this environment is like a mountain climber negotiating a glacier where each step is carefully tested. This style is well suited for systems programming or system integration where the return types are not uniform. Passing values back up thru layers of calls is difficult however.

* Exceptions - Programming with exceptions is more like a walk in the park where everything is assumed to be OK all the time. Functions always return useful values or they raise an exception. This style is more suited for a scripting language. The scripter does not need to remember details like whether a return value of zero means success or failure. It is never necessary to check if a returned value is valid.
It also makes it easier to pass errors back up thru a chain of function calls.

{{Note|Decision: We favor '''exceptions'''|being a guideline, we'll follow this on future developments and "fix" parts of the current API where this is not happening.
}}

'''Status''': We need to list our guidelines somewhere :) .

← 古い版	2018年6月28日 (木) 17:51時点における版
(相違点なし)

Dev:2.4/Source/Python/API/bpy api - 版の履歴

Yamyam: 1版 をインポートしました

wiki>Mindrones: moved Dev:Source/BPython/API/bpy api to Dev:2.4/Source/Python/API/bpy api

Yamyam: 1版をインポートしました