[Chandler-dev] loadItemByUUID( ) is being deprecated

[Morgen Sagen]

The replacement for translator.loadItemByUUID( ) is  
translator.withItemForUUID( ).  The new method takes the same  
arguments as the old one, but can be used in two ways:

1) non-decorator: simply call withItemForUUID( ) as you called  
loadItemByUUID( ) before, but it won't return the item

    For example, in the NoteRecord.importer, what was:

	self.loadItemByUUID(record.uuid, pim.Note, icalUID=icalUID, body=body)

    becomes:

	self.withItemForUUID(record.uuid, pim.Note, icalUID=icalUID, body=body)


2) decorator: if your importer actually needs access to the item  
being loaded/created, you'll need to write a nested method which  
accepts the item as its argument, and decorate that method with  
self.withItemForUUID( )

    For example, in the ItemRecord.importer, what was:

	item = self.loadItemByUUID(record.uuid, pim.ContentItem,  
displayName=record.title, createdOn=createdOn)
	if record.triage != "" and record.triage not in emptyValues:
		[... snip ...]
		item.doAutoTriageOnDateChange = (auto == "1")

    becomes:

	@self.loadItemByUUID(record.uuid, pim.ContentItem,  
displayName=record.title, createdOn=createdOn)
	def do(item):
		if record.triage != "" and record.triage not in emptyValues:
			[... snip ...]
			item.doAutoTriageOnDateChange = (auto == "1")


Why do this?  It turns out that in the case of multiple-inheritance,  
it's not always possible to upgrade the type of an item right away  
and it needs to be delayed.  Changing the behavior in this way allows  
the underlying translator to delay the execution of the decorated  
nested methods until it's safe for them to run.  If I've  
mischaracterized the problem and solution, I'm sure pje will let me  
know.  :-)

~morgen