Add Image.repo_digests and clarify id/short_id docs

docker/models/images.py

@@ -13,6 +13,9 @@
 class Image(Model):
     """
     An image on the server.
+    Note that :py:attr:`id` and :py:attr:`short_id` refer to the local image
+    ID (the digest of the image config), which is not the same as the digest
+    of the image in a registry. Use :py:attr:`repo_digests` to get the latter.
     """
     def __repr__(self):
         tag_str = "', '".join(self.tags)
@@ -46,6 +49,16 @@ def tags(self):
             tags = []
         return [tag for tag in tags if tag != '<none>:<none>']
 
+    @property
+    def repo_digests(self):
+        """
+        The image's repository digests, as a list of strings in the form
+        ``repository@sha256:...``. These are the digests the image is known
+        by in a registry. The list is empty for images that have never been
+        pushed to or pulled from a registry.
+        """
+        return list(self.attrs.get('RepoDigests') or [])
+
     def history(self):
         """
         Show the history of an image.

tests/unit/models_images_test.py

@@ -144,6 +144,27 @@ def test_tags(self):
         })
         assert image.tags == []
 
+    def test_repo_digests(self):
+        image = Image(attrs={
+            'RepoDigests': [
+                'busybox@sha256:abc123',
+                'example.com/busybox@sha256:def456',
+            ],
+        })
+        assert image.repo_digests == [
+            'busybox@sha256:abc123',
+            'example.com/busybox@sha256:def456',
+        ]
+
+    def test_repo_digests_empty(self):
+        assert Image(attrs={'RepoDigests': []}).repo_digests == []
+
+    def test_repo_digests_none(self):
+        assert Image(attrs={'RepoDigests': None}).repo_digests == []
+
+    def test_repo_digests_missing(self):
+        assert Image(attrs={}).repo_digests == []
+
     def test_history(self):
         client = make_fake_client()
         image = client.images.get(FAKE_IMAGE_ID)