Version 0.5.0

Remove v1 APIs
update tests and README

Author: gpeacock

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "c2pa-python"
-version = "0.4.0"
+version = "0.5.0"
 edition = "2021"
 authors = ["Gavin Peacock <[email protected]"]
 
@@ -9,8 +9,6 @@ authors = ["Gavin Peacock <[email protected]"]
 name = "c2pa"
 crate-type = ["cdylib"]
 
-[features]
-v1 = ["c2pa/file_io"]
 
 [dependencies]
 c2pa = {version = "0.32.0", features = ["unstable_api", "openssl"]}

README.md

@@ -214,6 +214,20 @@ deactivate
 
 ## Release notes
 
+### Version 0.5.0
+
+- This release rewrites the API to be stream based using a Builder and Reader model.
+- The functions now support throwing c2pa.Error values, caught with try/except.
+- Instead of `c2pa.read_file` you now call `c2pa_api.Reader.from_file` and `reader.json`.
+- Read thumbnails and other resources use `reader.resource_to_stream` or `reader.resource.to_file`.
+- Instead of `c2pa.sign_file` use `c2pa_api.Builder.from_json` and `builder.sign` or `builder.sign_file`.
+- Add thumbnails or other resources with `builder.add_resource` or `builder.add_resource_file`.
+- Add Ingredients with `builder.add_ingredient` or `builder.add_ingredient_file`.
+- You can archive a `Builder` using `builder.to_archive` and reconstruct it with `builder.from_archive`.
+- Signers can be constructed with `c2pa_api.create_signer`.
+- The signer now requires a signing function to keep private keys private.
+- Example signing functions are provided in c2pa_api.py
+
 ### Version 0.4.0
 
 This release:

src/c2pa.udl

@@ -2,14 +2,6 @@
 namespace c2pa {
   string version();
   string sdk_version();
- /// [Throws=Error]
- /// CallbackSigner create_signer(SignerCallback callback, SigningAlg alg, bytes certs, string? ta_url);
- /// [Throws=Error]
- /// string read_file([ByRef] string path, string? data_dir);
- /// [Throws=Error]
- /// string read_ingredient_file([ByRef] string path, [ByRef] string data_dir);
- /// [Throws=Error]
- /// sequence<u8> sign_file([ByRef] string source, [ByRef] string dest, [ByRef] string manifest, [ByRef] SignerInfo signer_info, string? data_dir);
 };
 
 [Error]

tests/c2pa_api.py

@@ -23,6 +23,8 @@
 
 import c2pa;
 
+from c2pa import Error, SigningAlg, version, sdk_version
+
 # This module provides a simple Python API for the C2PA library.
 
 # Reader is used to read a manifest store from a stream or file.
@@ -186,9 +188,9 @@ def create_signer(callback, alg, certs, timestamp_url=None):
 def sign_ps256_shell(data: bytes, key_path: str) -> bytes:
     with tempfile.NamedTemporaryFile() as bytes:
         bytes.write(data)
-    signature = tempfile.NamedTemporaryFile()
-    os.system("openssl dgst -sha256 -sign {} -out {} {}".format(key_path, signature.name, bytes.name))
-    return signature.read()
+        signature = tempfile.NamedTemporaryFile()
+        os.system("openssl dgst -sha256 -sign {} -out {} {}".format(key_path, signature.name, bytes.name))
+        return signature.read()
 
 # Example of using python crypto to sign data using openssl with Ps256
 from cryptography.hazmat.primitives import hashes, serialization

tests/test_api.py

@@ -1,4 +1,3 @@
-
 # Copyright 2023 Adobe. All rights reserved.
 # This file is licensed to you under the Apache License,
 # Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0)
@@ -11,16 +10,21 @@
 # specific language governing permissions and limitations under
 # each license.
 
-import c2pa
-import pytest
+
 import json
+import pytest
 import tempfile
-import c2pa_api
+
+from c2pa_api import  Builder, Error,  Reader, SigningAlg, create_signer,  sdk_version, sign_ps256, version
 
 # a little helper function to get a value from a nested dictionary
 from functools import reduce
 import operator
 
+def getitem(d, key):
+    return reduce(operator.getitem, key, d)
+
+# define the manifest we will use for testing
 manifest_def = {
     "claim_generator_info": [{
         "name": "python test",
@@ -46,19 +50,16 @@
     ]
 }
 
-def getitem(d, key):
-    return reduce(operator.getitem, key, d)
-
 def test_version():
-    assert c2pa.version() == "0.4.0"
+    assert version() == "0.5.0"
 
 def test_sdk_version():
-    assert "c2pa-rs/" in c2pa.sdk_version()
+    assert "c2pa-rs/" in sdk_version()
 
 def test_v2_read():
      #example of reading a manifest store from a file
     try:
-        reader = c2pa_api.Reader.from_file("tests/fixtures/C.jpg")
+        reader = Reader.from_file("tests/fixtures/C.jpg")
         jsonReport = reader.json()
         manifest_store = json.loads(jsonReport)
         manifest = manifest_store["manifests"][manifest_store["active_manifest"]]
@@ -86,33 +87,33 @@ def test_v2_read():
         exit(1)
 
 def test_reader_from_file_no_store():
-    with pytest.raises(c2pa.Error.ManifestNotFound) as err:  
-        reader = c2pa_api.Reader.from_file("tests/fixtures/A.jpg")
+    with pytest.raises(Error.ManifestNotFound) as err:  
+        reader = Reader.from_file("tests/fixtures/A.jpg")
 
 def test_v2_sign():
     # define a source folder for any assets we need to read
     data_dir = "tests/fixtures/"
     try:
-        def sign_ps256(data: bytes) -> bytes:
-            return c2pa_api.sign_ps256(data, data_dir+"ps256.pem")
+        def sign(data: bytes) -> bytes:
+            return sign_ps256(data, data_dir+"ps256.pem")
 
         certs = open(data_dir + "ps256.pub", "rb").read()
         # Create a local signer from a certificate pem file
-        signer = c2pa_api.create_signer(sign_ps256, c2pa.SigningAlg.PS256, certs, "http://timestamp.digicert.com")
+        signer = create_signer(sign, SigningAlg.PS256, certs, "http://timestamp.digicert.com")
 
-        builder = c2pa_api.Builder(manifest_def)
+        builder = Builder(manifest_def)
 
         builder.add_resource_file("A.jpg", data_dir + "A.jpg")
 
         builder.to_archive(open("target/archive.zip", "wb"))
 
-        builder = c2pa_api.Builder.from_archive(open("target/archive.zip", "rb"))
+        builder = Builder.from_archive(open("target/archive.zip", "rb"))
 
         with tempfile.TemporaryDirectory() as output_dir:
             c2pa_data = builder.sign_file(signer, data_dir + "A.jpg", output_dir + "out.jpg")
             assert len(c2pa_data) > 0
 
-        reader = c2pa_api.Reader.from_file(output_dir + "out.jpg")
+        reader = Reader.from_file(output_dir + "out.jpg")
         print(reader.json())
         manifest_store = json.loads(reader.json())
         manifest = manifest_store["manifests"][manifest_store["active_manifest"]]

tests/training.py

@@ -15,9 +15,8 @@
 import json
 import os
 import sys
-import c2pa
 
-import c2pa_api
+from c2pa_api import Builder, Reader, create_signer, SigningAlg, sign_ps256, version
 
 # set up paths to the files we we are using
 PROJECT_PATH = os.getcwd()
@@ -32,7 +31,7 @@
 def getitem(d, key):
     return reduce(operator.getitem, key, d)
 
-print("version = " + c2pa.version())
+print("version = " + version())
 
 # first create an asset with a do not train assertion
 
@@ -74,15 +73,15 @@ def getitem(d, key):
 # V2 signing api
 try:
    # This could be implemented on a server using an HSM
-    def sign_ps256(data: bytes) -> bytes:
-        return c2pa_api.sign_ps256(data, "tests/fixtures/ps256.pem")
+    def sign(data: bytes) -> bytes:
+        return sign_ps256(data, "tests/fixtures/ps256.pem")
 
     certs = open("tests/fixtures/ps256.pub","rb").read()
 
     # Create a signer from a certificate pem file
-    signer = c2pa_api.create_signer(sign_ps256, c2pa.SigningAlg.PS256, certs, "http://timestamp.digicert.com")
+    signer = create_signer(sign, SigningAlg.PS256, certs, "http://timestamp.digicert.com")
 
-    builder = c2pa_api.Builder(manifest_json)
+    builder = Builder(manifest_json)
 
     builder.add_resource_file("thumbnail", "tests/fixtures/A_thumbnail.jpg")
 
@@ -100,7 +99,7 @@ def sign_ps256(data: bytes) -> bytes:
 
 allowed = True # opt out model, assume training is ok if the assertion doesn't exist
 try:
-    reader = c2pa_api.Reader.from_file(testOutputFile)
+    reader = Reader.from_file(testOutputFile)
     manifest_store = json.loads(reader.json())
 
     manifest = manifest_store["manifests"][manifest_store["active_manifest"]]

tests/unit_tests.py

@@ -11,51 +11,48 @@
 # specific language governing permissions and limitations under
 # each license.import unittest
 
-import unittest
-from unittest.mock import mock_open, patch
-import c2pa_api
-from c2pa_api import c2pa
 import os
 import io
+import json
+import unittest
+from unittest.mock import mock_open, patch
+
+from c2pa_api import  Builder, Error,  Reader, SigningAlg, create_signer,  sdk_version, sign_ps256
+
 PROJECT_PATH = os.getcwd()
 
 testPath = os.path.join(PROJECT_PATH, "tests", "fixtures", "C.jpg")
 
 class TestC2paSdk(unittest.TestCase):
 
     def test_version(self):
-        self.assertIn("0.4.0",c2pa_api.c2pa.sdk_version())
-
-    #def test_supported_extensions(self):
-    #   self.assertIn("jpeg",c2pa_api.c2pa.supported_extensions())
+        self.assertIn("0.4.0", sdk_version())
 
 
 class TestReader(unittest.TestCase):
 
-    def test_normal_read(self):
+    def test_stream_read(self):
         with open(testPath, "rb") as file:
-            reader = c2pa_api.Reader("image/jpeg",file)
+            reader = Reader("image/jpeg",file)
             json = reader.json()
             self.assertIn("C.jpg", json)
 
-    def test_normal_read_and_parse(self):
+    def test_stream_read_and_parse(self):
         with open(testPath, "rb") as file:
-            reader = c2pa_api.Reader("image/jpeg",file)
-            json = reader.json()
-            self.assertIn("C.jpg", json)
-            #manifest_store = c2pa_api.ManifestStore.from_json(json)
-            #title= manifest_store.manifests[manifest_store.activeManifest].title
-            #self.assertEqual(title, "C.jpg")
+            reader = Reader("image/jpeg",file)
+            manifest_store = json.loads(reader.json())
+            title = manifest = manifest_store["manifests"][manifest_store["active_manifest"]]["title"]
+            self.assertEqual(title, "C.jpg")
+
+    def test_json_decode_err(self):
+        with self.assertRaises(Error.Io):
+            manifest_store = Reader("image/jpeg","foo")
 
-    #def test_json_decode_err(self):
-    #    with self.assertRaises(c2pa_api.json.decoder.JSONDecodeError):
-    #        manifest_store = c2pa_api.ManifestStore.from_json("foo")
+    def test_reader_bad_format(self):
+        with self.assertRaises(Error.NotSupported):
+            with open(testPath, "rb") as file:
+                reader = Reader("badFormat",file)
 
-    #def test_reader_bad_format(self):
-    #    with self.assertRaises(c2pa_api.c2pa.StreamError.Other):
-    #        with open(testPath, "rb") as file:
-    #            manifestStore = c2pa_api.ManifestStoreReader("badFormat",file)
-    #            json = manifestStore.read()
 
 class TestBuilder(unittest.TestCase):
     # Define a manifest as a dictionary
@@ -84,26 +81,36 @@ class TestBuilder(unittest.TestCase):
         ]
     }
 
-    def sign_ps256(data: bytes) -> bytes:
-        return c2pa_api.sign_ps256_shell(data, "tests/fixtures/ps256.pem")
+    # Define a function that signs data with PS256 using a private key
+    def sign(data: bytes) -> bytes:
+        return sign_ps256(data, "tests/fixtures/ps256.pem")
 
     # load the public keys from a pem file
-    pemFile = os.path.join(PROJECT_PATH,"tests","fixtures","ps256.pub")
-    certs = open(pemFile,"rb").read()
+    certs = open("tests/fixtures/ps256.pub","rb").read()
 
-    # Create a local signer from a certificate pem file
-    signer = c2pa_api.create_signer(sign_ps256, c2pa.SigningAlg.PS256, certs, "http://timestamp.digicert.com")
+    # Create a local Ps256 signer with certs and a timestamp server
+    signer = create_signer(sign, SigningAlg.PS256, certs, "http://timestamp.digicert.com")
 
-    def test_normal_build(self):
+    def test_streams_build(self):
         with open(testPath, "rb") as file:
-            builder = c2pa_api.Builder(TestBuilder.manifestDefinition)
+            builder = Builder(TestBuilder.manifestDefinition)
             output = byte_array = io.BytesIO(bytearray())
             builder.sign(TestBuilder.signer, "image/jpeg", file, output)
             output.seek(0)
-            reader = c2pa_api.Reader("image/jpeg", output)
+            reader = Reader("image/jpeg", output)
             self.assertIn("Python Test", reader.json())
 
-
+    def test_streams_build(self):
+        with open(testPath, "rb") as file:
+            builder = Builder(TestBuilder.manifestDefinition)
+            archive = byte_array = io.BytesIO(bytearray())
+            builder.to_archive(archive)
+            builder = Builder.from_archive(archive)
+            output = byte_array = io.BytesIO(bytearray())
+            builder.sign(TestBuilder.signer, "image/jpeg", file, output)
+            output.seek(0)
+            reader = Reader("image/jpeg", output)
+            self.assertIn("Python Test", reader.json())
 
 if __name__ == '__main__':
     unittest.main()