salimfadhley/jenkinsapi — pull request #311 by imsardine (2014-09-17 00:56:20+00:00)
Title: To parameterize the level of fingerprint validation

As mentioned in issue #303, I find the log entry `Local copy of ... is already up to date.` is sometimes misleading. That is, if there exists a broken local copy before invoking `Artifact.save()` or `Artifact.save_to_dir()`, the broken copy will still be considered as valid (or up to date).

```
DEBUG:requests.packages.urllib3.connectionpool:"GET /fingerprint/9fb189f24862ce8b96468df4ebc50629/api/python HTTP/1.1" 404 None
ERROR:root:Failed request at https:///fingerprint/9fb189f24862ce8b96468df4ebc50629/api/python with params: None
INFO:jenkinsapi.artifact:Local copy of is already up to date.
```

It is confused, at least from the viewpoint of API users. The dostrings and comments of `Fingerprint.valid()` explain the why:

> Return True / False if valid. If returns True, self.unknown is set to either True or False, and can be checked if we have positive validity (fingerprint known at server) or negative validity (fingerprint not known at server, but not really an error).

> We can’t really say anything about the validity of fingerprints not found — but the artifact can still exist, so it is not possible to definitely say they are valid or not.

It is crucial to ensure artifacts' integrity prior to doing subsequent tasks against them, especially for those who have enabled file fingerprinting on the server side and want to STRICTLY validate fingerprints. Here is my opinion:

> If we cannot definitely say negative validity (404 Not Found) is an error or not, why don't we ask the user?

I think we can add another parameter `strict_validation` to `Artifact.save()`, `Artifact.save_to_dir()` and User API (`grab_artifact()` and `install_artifacts()`). The parameter indicates if negative validity (fingerprint is not known on the server side) should be considered invalid or not, and it defaults to `False` for backward compatibility.