Doc string for `checkurl()` incomplete/incorrect

[mih]

I have no comprehensive view of the situation, hence only reporting here, rather than providing a patch...

checkurl() documentation says:

In order to provide additional information, a list of dictionaries can be returned.
The dictionaries can have 3 keys: {'url': str, 'size': int, 'filename': str}. All of them are optional.

It seems that the "all of them are optional" part is not correct. When I return dicts with just url and size, git-annex addurl will not attempt a download (but will also not fail).

Looking at the git-annex docs:

CHECKURL-MULTI Url1 Size1|UNKNOWN Filename1 Url2 Size2|UNKNOWN Filename2 ...

... Each triplet of url, size, and filename should be listed, one after the other

It only talks about triplets, but AnnexRemote will return only two values with CHECKURL-MULTI, when filename is omitted.

[Lykos153]

Thank you for reporting this!

It only talks about triplets, but AnnexRemote will return only two values with CHECKURL-MULTI, when filename is omitted.

In case the filename is empty, three values are still returned, just that one if them is empty. Note the two consecutive spaces after UNKNOWN. This is in accordance with

Each protocol line starts with a command, which is followed by the command's parameters (a fixed number per command), each separated by a single space. The last parameter may contain spaces. Parameters may be empty, but the separating spaces are still required in that case.

However, you are probably right. I seem to have interpreted the above statement as "any parameter may be empty", while it was meant more like "parameters may be marked as optional in their description, in which case they can be empty".