From 610fca29066560cd16d956270b77fbf684eef4a4 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Sat, 5 May 2007 03:35:12 +0000 Subject: updated epydocs --- source/blender/python/api2_2x/doc/Bpy.py | 286 +----------------------- source/blender/python/api2_2x/doc/Bpy_config.py | 38 ++++ source/blender/python/api2_2x/doc/Bpy_data.py | 281 +++++++++++++++++++++++ 3 files changed, 330 insertions(+), 275 deletions(-) create mode 100644 source/blender/python/api2_2x/doc/Bpy_config.py create mode 100644 source/blender/python/api2_2x/doc/Bpy_data.py (limited to 'source') diff --git a/source/blender/python/api2_2x/doc/Bpy.py b/source/blender/python/api2_2x/doc/Bpy.py index 51b7af3be5d..e5eb751cf04 100644 --- a/source/blender/python/api2_2x/doc/Bpy.py +++ b/source/blender/python/api2_2x/doc/Bpy.py @@ -6,284 +6,20 @@ The bpy module. bpy === -ATTENTION: This module is EXPERIMENTAL. -Features documented here are subject to change. + ATTENTION: This module is EXPERIMENTAL. + Features documented here are subject to change. -The bpy module is intended as a replacement for the Blender module. -It will eventually provide the same features and functionality. + The bpy module is intended as a replacement for the Blender module. + It will eventually provide the same features and functionality. -This module uses a different model for the way data is accessed, added and removed. The various types such as groups, meshes, etc., are unchanged. + This module uses a different model for the way data is accessed, added and removed. The various types such as groups, meshes, etc., are unchanged. -At the moment it provides an alternative way to access data from python. + At the moment it provides an alternative way to access data from python. -Example:: - - # apply the active image to the active mesh - # this script has no error checking to keep it small and readable. - - scn= bpy.scenes.active - ob_act = scn.objects.active # assuming we have an active, might be None - me = ob_act.getData(mesh=1) # assuming a mesh type, could be any - img = bpy.images.active # assuming we have an active image - - for f in me.faces: - f.image = img - - Window.RedrawAll() - -Example:: - - # make a new object from an existing mesh - # and make it active - scn= bpy.scenes.active - me = bpy.meshes['mymesh'] - ob = scn.objects.new(me) # new object from the mesh - scn.objects.active = ob - -Example:: - # print the names of any non local objects - scn= bpy.scenes.active - for ob in scn.objects: - if ob.lib: - print 'external object:', ob.name, ob.lib - -Example:: - # add an empty object at each vertex of the active mesh - scn= bpy.scenes.active - ob_act = scn.objects.active - matrix = ob_act.matrixWorld - me = ob_act.getData(mesh=1) - - for v in me.verts: - ob = scn.objects.new('Empty') - ob.loc = v.co * matrix # transform the vertex location by the objects matrix. - - -Example:: - # load all the wave sound files in a directory - import os - sound_dir = '/home/me/soundfiles/' - sounds_new = [] - for fname in os.listdir(sound_dir): - if fname.lower().endswith('.wav'): - try: - snd = bpy.sounds.new(filename = sound_dir + fname) - except: - snd = None - - if snd: - sounds_new.append(snd) - - # Print the sounds - for snd in sounds_new: - print snd - -Example:: - # apply a new image to each selected mesh object as a texface. - width, height= 512, 512 - scn= bpy.scenes.active - - for ob in scn.objects.context: - if not ob.lib and ob.type == 'Mesh': # object isn't from a library and is a mesh - me = ob.getData(mesh=1) - me.faceUV = True # add UV coords and textures if we don't have them. - - # Make an image named after the mesh - img = bpy.images.new(me.name, width, height) - - for f in me.faces: - f.image = img - - Window.RedrawAll() - -@var scenes: sequence for L{scene} data -@type scenes: L{libBlockSeq} -@var objects: sequence for L{object} data -@type objects: L{libBlockSeq} -@var meshes: sequence for L{mesh} data -@type meshes: L{libBlockSeq} -@var curves: sequence for L{curve} data, used to store Curve, Surface and Text3d data. -@type curves: L{libBlockSeq} -@var metaballs: sequence for L{metaball} data -@type metaballs: L{libBlockSeq} -@var materials: sequence for L{material} data -@type materials: L{libBlockSeq} -@var textures: sequence for L{texture} data -@type textures: L{libBlockSeq} -@var images: sequence for L{image} data -@type images: L{libBlockSeq} -@var lattices: sequence for L{lattice} data -@type lattices: L{libBlockSeq} -@var lamps: sequence for L{lamp} data -@type lamps: L{libBlockSeq} -@var cameras: sequence for L{camera} data -@type cameras: L{libBlockSeq} -@var ipos: sequence for L{ipo} data -@type ipos: L{libBlockSeq} -@var worlds: sequence for L{world} data -@type worlds: L{libBlockSeq} -@var fonts: sequence for L{font} data -@type fonts: L{libBlockSeq} -@var texts: sequence for L{text} data -@type texts: L{libBlockSeq} -@var sounds: sequence for L{sound} data -@type sounds: L{libBlockSeq} -@var groups: sequence for L{group} data -@type groups: L{libBlockSeq} -@var armatures: sequence for L{armature} data -@type armatures: L{libBlockSeq} -@var actions: sequence for L{action} data -@type actions: L{libBlockSeq} -@var libraries: L{librarySeq} submodule -@type libraries: L{librarySeq} + Submodules: + ----------- + - L{data} + - L{libraries} + - L{config} """ - -class libBlockSeq: - """ - Generic Data Access - =================== - This provides a unified way to access and manipulate data types in Blender - (scene, object, mesh, curve, metaball, material, texture, image, lattice, - lamp, camera, ipo, world, font, text, sound, groups, armatures, actions). - - Get Item - ======== - To get a datablock by name you can use dictionary-like syntax. - - >>> ob = bpy.objects['myobject'] - - Note that this can only be used for getting. - - >>> bpy.objects['myobject'] = data # will raise an error - - B{Library distinctions} - - Blender doesn't allow naming collisions within its own data, but it's - possible to run into naming collisions when you have data linked from an external blend file. - - You can specify where the data is from by using a (name, library) pair as the key. - - >>> group = bpy.groups['mygroup', '//mylib.blend'] # only return data linked from mylib - - If you want to get a group from the local data only you can use None - - >>> group = bpy.groups['mygroup', None] # always returns local data - - Sequence - ======== - These generic datablocks are sequence datatypes. They are not lists. They support the dictionary and iterator protocols. This implies the following - - - A B{for} statement allows you to loop through data using the iterator protocol without wasting resources on creating a large list. - - >>> for me in bpy.meshes: - ... print me.name - - - You can also use len() to see how many datablocks exist. - - >>> print len(bpy.scenes) - - - Because the sequences are not lists and the [] operator is used to get items by name, you cannot use indexing to retrieve an item. - - >>> ob = bpy.objects[-1] # will raise an error - - - If you want to access the entire sequence as a list simply use the list() constructor. - - >>> ipo_list = list(bpy.ipos) - - @type tag: Bool - @ivar tag: A fast way to set the tag value of every member of the sequence to True or False - - For example - - >>> bpy.meshes.tag = True - - Is the same as... - - >>> for me in bpy.meshes: me.tag = True - - @type active: Datablock or None - @ivar active: The active member of the datatype - - Applies to: - - L{images} - - L{scenes} - - L{texts} - This can also be used to set the active data. - - >>> bpy.images.active = bpy.images.new(filename = '/home/me/someimage.jpg') - - """ - - def new(name): - """ - fixme: need description for parameters. - This function returns a new datablock containing no data or loaded from a file. - - Most datatypes accept a name for their argument except for L{sounds}, L{fonts}, L{ipos} and L{curves} that need an additional argument. - - The name argument is optional if not given a default name will be assigned. - - The name given may be modified by blender to make it unique. - - Loading From File - ================= - For L{images}, L{texts}, L{sounds}, L{fonts} types you can use the filename keyword to make a new datablock from a file. - - New L{sounds}, L{fonts} can only be made with the a filename given. - - The filename can a keyword or the second argument, use the keyword only for the datablocks new name to be set by the filename. - - >>> sound = bpy.sounds.new('newsound', '~/mysound.wav') # uses the first string given for the name. - - >>> sound = bpy.sounds.new(filename = '~/mysound.wav') # will use the filename to make the name. - - Images - ====== - Images optionally accept extra 2 arguments for width and height, values between 4 and 5000 if no args are given they will be 256. - - >>> img = bpy.images.new(name, 512, 512) - - Curves - ====== - Curves need 2 arguments: bpy.curves.new(name, type) type must be one of the following... - - 'Curve' - - 'Text3d' - - >>> text3d = bpy.curves.new('MyCurve', 'Text3d') - - Ipos - ==== - Ipos need 2 arguments: bpy.ipos.new(name, type) type must be one of the following... - - 'Camera' - - 'World' - - 'Material' - - 'Texture' - - 'Lamp' - - 'Action' - - 'Constraint' - - 'Sequence' - - 'Curve' - - 'Key' - Objects cannot be created from bpy.objects; - objects must be created from the scene. Here are some examples. - - >>> ob = bpy.scenes.active.objects.new('Empty') - - >>> scn = bpy.scenes.active - ... ob = scn.objects.new(bpy.meshes.new('mymesh')) - - @rtype: datablock - """ - - def unlink(datablock): - """ - This function removes a datablock. - applies to: - - L{scenes} - - L{groups} - - L{texts} - Other types will raise an error. - @rtype: None - """ - diff --git a/source/blender/python/api2_2x/doc/Bpy_config.py b/source/blender/python/api2_2x/doc/Bpy_config.py new file mode 100644 index 00000000000..ec3eb261c03 --- /dev/null +++ b/source/blender/python/api2_2x/doc/Bpy_config.py @@ -0,0 +1,38 @@ +# bpy module and the bpy PyType object + +""" +bpy.config +========== + +This module gives you direct access to blenders preferences. + +@var undoSteps: number of undo steps to store. +@type undoSteps: int +@var textureTimeout: free textures from openGL memory if unused after this time. +@type textureTimeout: int +@var textureCollectRate: tag textures as being used at this interval of time. +@type textureCollectRate: int +@var sequenceMemCacheLimit: how much memory to use for a sequencer cache. +@type sequenceMemCacheLimit: int +@var fontSize: display size for fonts in the user interface. +@type fontSize: int +@var yfExportDir: yafray export path. +@type yfExportDir: string +@var fontDir: default font path. +@type fontDir: string +@var renderDir: default render path. +@type renderDir: string +@var textureDir: default texture path. +@type textureDir: string +@var userScriptsDir: path for user scripts. +@type userScriptsDir: string +@var texturePluginsDir: default texture plugin path. +@type texturePluginsDir: string +@var soundDir: default sound path. +@type soundDir: string +@var sequencePluginsDir: default sequencer plugin path. +@type sequencePluginsDir: string +@var tempDir: path where temp files are saved. +@type tempDir: string +""" + diff --git a/source/blender/python/api2_2x/doc/Bpy_data.py b/source/blender/python/api2_2x/doc/Bpy_data.py new file mode 100644 index 00000000000..e228db688d7 --- /dev/null +++ b/source/blender/python/api2_2x/doc/Bpy_data.py @@ -0,0 +1,281 @@ +# bpy module and the bpy PyType object + +""" +The bpy module. + +bpy.data (Generic Data Access) +============================== + +Example:: + + # apply the active image to the active mesh + # this script has no error checking to keep it small and readable. + + sce= bpy.data.scenes.active + ob_act = sce.objects.active # assuming we have an active, might be None + me = ob_act.getData(mesh=1) # assuming a mesh type, could be any + img = bpy.data.images.active # assuming we have an active image + + for f in me.faces: + f.image = img + + Window.RedrawAll() + +Example:: + + # make a new object from an existing mesh + # and make it active + scn= bpy.data.scenes.active + me = bpy.data.meshes['mymesh'] + ob = sce.objects.new(me) # new object from the mesh + sce.objects.active = ob + +Example:: + # print the names of any non local objects + sce= bpy.data.scenes.active + for ob in sce.objects: + if ob.lib: + print 'external object:', ob.name, ob.lib + +Example:: + # add an empty object at each vertex of the active mesh + scn= bpy.data.scenes.active + ob_act = sce.objects.active + matrix = ob_act.matrixWorld + me = ob_act.getData(mesh=1) + + for v in me.verts: + ob = sce.objects.new('Empty') + ob.loc = v.co * matrix # transform the vertex location by the objects matrix. + + +Example:: + # load all the wave sound files in a directory + import os + sound_dir = '/home/me/soundfiles/' + sounds_new = [] + for fname in os.listdir(sound_dir): + if fname.lower().endswith('.wav'): + try: + snd = bpy.data.sounds.new(filename = sound_dir + fname) + except: + snd = None + + if snd: + sounds_new.append(snd) + + # Print the sounds + for snd in sounds_new: + print snd + +Example:: + # apply a new image to each selected mesh object as a texface. + width, height= 512, 512 + scn= bpy.data.scenes.active + + for ob in sce.objects.context: + if not ob.lib and ob.type == 'Mesh': # object isn't from a library and is a mesh + me = ob.getData(mesh=1) + me.faceUV = True # add UV coords and textures if we don't have them. + + # Make an image named after the mesh + img = bpy.data.images.new(me.name, width, height) + + for f in me.faces: + f.image = img + + Window.RedrawAll() + + + +@var scenes: sequence for L{scene} data +@type scenes: L{libBlockSeq} +@var objects: sequence for L{object} data +@type objects: L{libBlockSeq} +@var meshes: sequence for L{mesh} data +@type meshes: L{libBlockSeq} +@var curves: sequence for L{curve} data, used to store Curve, Surface and Text3d data. +@type curves: L{libBlockSeq} +@var metaballs: sequence for L{metaball} data +@type metaballs: L{libBlockSeq} +@var materials: sequence for L{material} data +@type materials: L{libBlockSeq} +@var textures: sequence for L{texture} data +@type textures: L{libBlockSeq} +@var images: sequence for L{image} data +@type images: L{libBlockSeq} +@var lattices: sequence for L{lattice} data +@type lattices: L{libBlockSeq} +@var lamps: sequence for L{lamp} data +@type lamps: L{libBlockSeq} +@var cameras: sequence for L{camera} data +@type cameras: L{libBlockSeq} +@var ipos: sequence for L{ipo} data +@type ipos: L{libBlockSeq} +@var worlds: sequence for L{world} data +@type worlds: L{libBlockSeq} +@var fonts: sequence for L{font} data +@type fonts: L{libBlockSeq} +@var texts: sequence for L{text} data +@type texts: L{libBlockSeq} +@var sounds: sequence for L{sound} data +@type sounds: L{libBlockSeq} +@var groups: sequence for L{group} data +@type groups: L{libBlockSeq} +@var armatures: sequence for L{armature} data +@type armatures: L{libBlockSeq} +@var actions: sequence for L{action} data +@type actions: L{libBlockSeq} +""" + + +class libBlockSeq: + """ + Generic Data Access + =================== + This provides a unified way to access and manipulate data types in Blender + (scene, object, mesh, curve, metaball, material, texture, image, lattice, + lamp, camera, ipo, world, font, text, sound, groups, armatures, actions). + + Get Item + ======== + To get a datablock by name you can use dictionary-like syntax. + + >>> ob = bpy.data.objects['myobject'] + + Note that this can only be used for getting. + + >>> bpy.data.objects['myobject'] = data # will raise an error + + B{Library distinctions} + + Blender doesn't allow naming collisions within its own data, but it's + possible to run into naming collisions when you have data linked from an external blend file. + + You can specify where the data is from by using a (name, library) pair as the key. + + >>> group = bpy.data.groups['mygroup', '//mylib.blend'] # only return data linked from mylib + + If you want to get a group from the local data only you can use None + + >>> group = bpy.data.groups['mygroup', None] # always returns local data + + Sequence + ======== + These generic datablocks are sequence datatypes. They are not lists. They support the dictionary and iterator protocols. This implies the following + + - A B{for} statement allows you to loop through data using the iterator protocol without wasting resources on creating a large list. + + >>> for me in bpy.data.meshes: + ... print me.name + + - You can also use len() to see how many datablocks exist. + + >>> print len(bpy.data.scenes) + + - Because the sequences are not lists and the [] operator is used to get items by name, you cannot use indexing to retrieve an item. + + >>> ob = bpy.data.objects[-1] # will raise an error + + - If you want to access the entire sequence as a list simply use the list() constructor. + + >>> ipo_list = list(bpy.data.ipos) + + @type tag: Bool + @ivar tag: A fast way to set the tag value of every member of the sequence to True or False + + For example + + >>> bpy.data.meshes.tag = True + + Is the same as... + + >>> for me in bpy.data.meshes: me.tag = True + + @type active: Datablock or None + @ivar active: The active member of the datatype + + Applies to: + - L{images} + - L{scenes} + - L{texts} + This can also be used to set the active data. + + >>> bpy.data.images.active = bpy.data.images.new(filename = '/home/me/someimage.jpg') + + """ + + def new(name): + """ + fixme: need description for parameters. + This function returns a new datablock containing no data or loaded from a file. + + Most datatypes accept a name for their argument except for L{sounds}, L{fonts}, L{ipos} and L{curves} that need an additional argument. + + The name argument is optional if not given a default name will be assigned. + + The name given may be modified by blender to make it unique. + + Loading From File + ================= + For L{images}, L{texts}, L{sounds}, L{fonts} types you can use the filename keyword to make a new datablock from a file. + + New L{sounds}, L{fonts} can only be made with the a filename given. + + The filename can a keyword or the second argument, use the keyword only for the datablocks new name to be set by the filename. + + >>> sound = bpy.data.sounds.new('newsound', '~/mysound.wav') # uses the first string given for the name. + + >>> sound = bpy.data.sounds.new(filename = '~/mysound.wav') # will use the filename to make the name. + + Images + ====== + Images optionally accept extra 2 arguments for width and height, values between 4 and 5000 if no args are given they will be 256. + + >>> img = bpy.data.images.new(name, 512, 512) + + Curves + ====== + Curves need 2 arguments: bpy.data.curves.new(name, type) type must be one of the following... + - 'Curve' + - 'Text3d' + + >>> text3d = bpy.data.curves.new('MyCurve', 'Text3d') + + Ipos + ==== + Ipos need 2 arguments: bpy.data.ipos.new(name, type) type must be one of the following... + - 'Camera' + - 'World' + - 'Material' + - 'Texture' + - 'Lamp' + - 'Action' + - 'Constraint' + - 'Sequence' + - 'Curve' + - 'Key' + Objects cannot be created from bpy.data.objects; + objects must be created from the scene. Here are some examples. + + >>> ob = bpy.data.scenes.active.objects.new('Empty') + + >>> scn = bpy.data.scenes.active + ... ob = sce.objects.new(bpy.data.meshes.new('mymesh')) + + @rtype: datablock + """ + + def unlink(datablock): + """ + This function removes a datablock. + applies to: + - L{scenes} + - L{groups} + - L{texts} + Other types will raise an error. + @rtype: None + """ + + + \ No newline at end of file -- cgit v1.2.3