# bpy module and the bpy PyType object

"""
The bpy module.

bpy
===

This module is imported automatically and eventually should provide all the functionality as the Blender module does now.

This only modifies the way data is accessed, added and removed.  The objects, groups, meshes, etc., are unchanged.

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 filename in os.listdir(sound_dir):
		if filename.lower().endswith('.wav'):
			try:
				snd = bpy.sounds.load(sound_dir + filename)
			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: iterator for L{scene<Scene.Scene>} data
@type scenes: L{dataIterator}
@var objects: iterator for L{object<Object.Object>} data
@type objects: L{dataIterator}
@var meshes: iterator for L{mesh<Mesh.Mesh>} data
@type meshes: L{dataIterator}
@var curves: iterator for L{curve<Curve.Curve>} data
@type curves: L{dataIterator}
@var metaballs: iterator for L{metaball<Metaball.Metaball>} data
@type metaballs: L{dataIterator}
@var materials: iterator for L{material<Material.Material>} data
@type materials: L{dataIterator}
@var textures: iterator for L{texture<Texture.Texture>} data
@type textures: L{dataIterator}
@var images: iterator for L{image<Image.Image>} data
@type images: L{dataIterator}
@var lattices: iterator for L{lattice<Lattice.Lattice>} data
@type lattices: L{dataIterator}
@var lamps: iterator for L{lamp<Lamp.Lamp>} data
@type lamps: L{dataIterator}
@var cameras: iterator for L{camera<Camera.Camera>} data
@type cameras: L{dataIterator}
@var ipos: iterator for L{ipo<Ipo.Ipo>} data
@type ipos: L{dataIterator}
@var worlds: iterator for L{world<World.World>} data
@type worlds: L{dataIterator}
@var fonts: iterator for L{font<Font.Font>} data
@type fonts: L{dataIterator}
@var texts: iterator for L{text<Text.Text>} data
@type texts: L{dataIterator}
@var sounds: iterator for L{sound<Sound.Sound>} data
@type sounds: L{dataIterator}
@var groups: iterator for L{group<Group.Group>} data
@type groups: L{dataIterator}
@var armatures: iterator for L{armature<Armature.Armature>} data
@type armatures: L{dataIterator}
@var actions: iterator for L{action<NLA.Action>} data
@type actions: L{dataIterator}
@var libraries: L{New library<LibData>} submodule
@type libraries: L{New library<LibData>}

"""


class dataIterator:
	"""
	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 pool of data, but it's
		possible to run into naming collisions when you have data linked from an external 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
	
	Iterator
	========
		generic_datablock's are not lists; however they can be used like lists.
		
		An iterator allows you to loop through data, without wasting resources on 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)
		
		You cannot use indexing to retrieve an item.
		
		>>> ob = bpy.objects[-1] # will raise an error
		
		If you want to access data as a list simply use the list() function.
		
		>>> 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.load('/home/me/someimage.jpg')
		
	"""

	def new(name):
		"""
		This function returns a new datablock
		
		Exceptions
		==========

		Images optionally accept 2 extra arguments: bpy.images.new(name, width=256, height=256)
		The width and height must br between 4 and 5000 if no args are given they will be 256.
		
		Ipos need 2 arguments: bpy.ipos.new(name, type) type must be a string can be 
			- '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 load(filename):
		"""
		This function loads a new datablock from a file.
		applies to:
			- L{fonts}
			- L{sounds}
			- L{images}
		Other types will raise an error.
		@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
		"""