feat: simplify how subjects are created from existing manifest

Signed-off-by: Tomas Coufal <tcoufal@redhat.com>

Author: tumido

docs/getting_started/user-guide.md

@@ -489,6 +489,28 @@ def push(uri, root):
 
 </details>
 
+<details>
+
+<summary>Example of basic artifact attachment</summary>
+
+We are assuming an `derived-artifact.txt` in the present working directory and that there's already a `localhost:5000/dinosaur/artifact:v1` artifact present in the registry. Here is an example of how to [attach](https://oras.land/docs/concepts/reftypes/) a derived artifact to the existing artifact.
+
+```python
+import oras.client
+import oras.provider
+
+client = oras.client.OrasClient(insecure=True)
+
+manifest = client.remote.get_manifest(f"localhost:5000/dinosaur/artifact:v1")
+subject = oras.provider.Subject.from_manifest(manifest)
+
+client.push(files=["derived-artifact.txt"], target="localhost:5000/dinosaur/artifact:v1-derived", subject=subject)
+Successfully pushed localhost:5000/dinosaur/artifact:v1
+Out[4]: <Response [201]>
+```
+
+</details>
+
 The above examples are just a start! See our [examples](https://github.com/oras-project/oras-py/tree/main/examples)
 folder alongside the repository for more code examples and clients. If you would like help
 for an example, or to contribute an example, [you know what to do](https://github.com/oras-project/oras-py/issues)!

oras/provider.py

@@ -3,6 +3,8 @@
 __license__ = "Apache-2.0"
 
 import copy
+import hashlib
+import json
 import os
 import urllib
 from contextlib import contextmanager, nullcontext
@@ -17,6 +19,7 @@
 import oras.auth
 import oras.container
 import oras.decorator as decorator
+import oras.defaults
 import oras.oci
 import oras.schemas
 import oras.utils
@@ -41,6 +44,23 @@ class Subject:
     digest: str
     size: int
 
+    @classmethod
+    def from_manifest(cls, manifest: dict) -> "Subject":
+        """
+        Create a new Subject from a Manifest
+
+        :param manifest: manifest to convert to subject
+        """
+        manifest_string = json.dumps(manifest).encode("utf-8")
+        digest = "sha256:" + hashlib.sha256(manifest_string).hexdigest()
+        size = len(manifest_string)
+
+        return cls(
+            manifest["mediaType"] or oras.defaults.default_manifest_media_type,
+            digest,
+            size,
+        )
+
 
 class Registry:
     """

oras/tests/test_provider.py

@@ -9,6 +9,7 @@
 
 import oras.client
 import oras.defaults
+import oras.oci
 import oras.provider
 import oras.utils
 
@@ -132,3 +133,19 @@ def test_sanitize_path():
         str(e.value)
         == f"Filename {Path(os.path.join(os.getcwd(), '..', '..')).resolve()} is not in {Path('../').resolve()} directory"
     )
+
+
+@pytest.mark.with_auth(False)
+def test_create_subject_from_manifest():
+    """
+    Basic tests for oras Subject creation from empty manifest
+    """
+    manifest = oras.oci.NewManifest()
+    subject = oras.provider.Subject.from_manifest(manifest)
+
+    assert subject.mediaType == oras.defaults.default_manifest_media_type
+    assert (
+        subject.digest
+        == "sha256:7a6f84d8c73a71bf9417c13f721ed102f74afac9e481f89e5a72d28954e7d0c5"
+    )
+    assert subject.size == 126