Fredrik, here's a simple use case: I've received a file A that I keep under version control, but it's been distributed and modified. I don't know which revision was distributed, so I want to diff A with each of its versions and find the closest match / count the diff lines / display the diff / filter and display parts of the diff. So, I need to compare a disk file against (each of) a range or list of diffs, and receive the results in a form I can process further. (For the output part, I'd suggest matching python's difflib interface.)
Another use case: I need a list of all the files that differ between two specified revisions. I might then ask for a pairwise diff of each file.
And a fancier one: I'm interested in watching how a stretch of code evolved; I can specify it as a line range at a particular revision, and the API should allow me to (somehow) extract the matching window from each version of the file, or show me revisions that affect that range, or whatever. (But I don't see an obvious way to do this with difflib, so maybe it's beyond the scope of the API as well).
I will implement this in two ways; I'll add a hg_diff command that will just give a list of diffs as output. I plan to allow fetching diffs between different versions of a file using difflib (thanks for the pointer, Alexis Dimitriadis), but need to think about the API design for that one.