Hybrid package including c2pa_api

Updates README

Author: gpeacock

.gitignore

@@ -21,5 +21,7 @@ __pycache__/
 .pytest_cache/
 dist
 
+c2pa/c2pa/
+
 # Mac OS X files
 .DS_Store

README.md

@@ -4,7 +4,9 @@ Python bindings for the C2PA Content Authenticity Initiative (CAI) library.
 
 This library enables you to read and validate C2PA data in supported media files and add signed manifests to supported media files.
 
-**WARNING**: This is an early prerelease version of this library.  There may be bugs and unimplemented features, and the API is subject to change.
+**NOTE**: This is a completely different API from 0.4.0. Check [Release notes](#release-notes) for changes.
+
+**WARNING**: This is an prerelease version of this library.  There may be bugs and unimplemented features, and the API is subject to change.
 
 ## Installation
 
@@ -28,63 +30,119 @@ pip install --upgrade --force-reinstall c2pa-python
 
 ### Import
 
-Import the C2PA module as follows:
+Import the API as follows:
 
 ```py
-import c2pa
+from c2pa import *
 ```
 
 ### Read and validate C2PA data in a file
 
-Use the `read_file` function to read C2PA data from the specified file:
-
-```py
-json_store = c2pa.read_file("path/to/media_file.jpg", "path/to/data_dir")
-```
-
-This function examines the specified media file for C2PA data and generates a JSON report of any data it finds. If there are validation errors, the report includes a `validation_status` field.  For a summary of supported media types, see [Supported file formats](#supported-file-formats).
+Use the `Reader` to read C2PA data from the specified file.
+This  examines the specified media file for C2PA data and generates a report of any data it finds. If there are validation errors, the report includes a `validation_status` field.  For a summary of supported media types, see [Supported file formats](#supported-file-formats).
 
 A media file may contain many manifests in a manifest store. The most recent manifest is identified by the value of the `active_manifest` field in the manifests map.
 
-If the optional `data_dir` is provided, the function extracts any binary resources, such as thumbnails, icons, and C2PA data into that directory. These files are referenced by the identifier fields in the manifest store report.
+The manifests may contain binary resources such as thumbnails which can be retrieved with `resource_to_stream` or `resource_to_file` using the associated `identifier` field values and a `uri`.
 
 NOTE: For a comprehensive reference to the JSON manifest structure, see the [Manifest store reference](https://opensource.contentauthenticity.org/docs/manifest/manifest-ref).
-
-### Add a signed manifest to a media file
-
-Use the `sign_file` function to add a signed manifest to a media file.
-
 ```py
-result = c2pa.sign_file("path/to/source.jpg", 
-                                        "path/to/dest.jpg", 
-                                        manifest_json, 
-                                        sign_info, 
-                                        data_dir)
-```
+try:
+  reader = c2pa.Reader("path/to/media_file.jpg")
 
-The parameters (in order) are:
-- The source (original) media file.
-- The destination file that will contain a copy of the source file with the manifest data added.
-- `manifest_json`, a JSON-formatted string containing the manifest data you want to add; see [Creating a manifest JSON definition file](#creating-a-manifest-json-definition-file) below.
-- `sign_info`, a `SignerInfo` object instance; see [Generating SignerInfo](#generating-signerinfo) below.
-- `data_dir` optionally specifies a directory path from which to load resource files referenced in the manifest JSON identifier fields; for example, thumbnails, icons, and manifest data for ingredients.
+  # Print the JSON for a manifest. 
+  print("manifest store:", reader.json())
 
-### Create a SignerInfo instance
+  # Get the active manifest.
+  manifest = reader.get_active_manifest()
+  if manifest != None:
 
-A `SignerInfo` object contains information about a signature.  To create an instance of `SignerInfo`, first set up the signer information from the public and private key `.pem` files as follows:
+    # get the uri to the manifest's thumbnail and write it to a file
+    uri = manifest["thumbnail"]["identifier"]
+    reader.resource_to_file(uri, "thumbnail_v2.jpg") 
 
-```py
-certs = open("path/to/public_certs.pem","rb").read()
-prv_key = open("path/to/private_key.pem","rb").read()
+except Exception as err:
+    print(err)
 ```
 
-Then create a new `SignerInfo` instance using the keys as follows, specifying the signing algorithm used and optionally a time stamp authority URL:
+### Add a signed manifest to a media file
 
-```py
-sign_info = c2pa.SignerInfo("es256", certs, priv_key, "http://timestamp.digicert.com")
-```
+Use a `Builder` to add a manifest to an asset.
 
-For the list of supported signing algorithms, see [Creating and using an X.509 certificate](https://opensource.contentauthenticity.org/docs/c2patool/x_509).
+```py
+try:
+  # Define a function to sign the claim bytes
+  # In this case we are using a pre-defined sign_ps256 method, passing in our private cert
+  # Normally this cert would be kept safe in some other location
+  def private_sign(data: bytes) -> bytes:
+    return sign_ps256(data, "tests/fixtures/ps256.pem")
+
+  # read our public certs into memory    
+  certs = open(data_dir + "ps256.pub", "rb").read()
+  
+  # Create a signer from the private signer, certs and a time stamp service url
+  signer = create_signer(private_sign, SigningAlg.PS256, certs, "http://timestamp.digicert.com")
+
+  # Define a manifest with thumbnail and an assertion.
+  manifest_json = {
+      "claim_generator_info": [{
+          "name": "python_test",
+          "version": "0.1"
+      }],
+      "title": "Do Not Train Example",
+      "thumbnail": {
+          "format": "image/jpeg",
+          "identifier": "thumbnail"
+      },
+      "assertions": [
+      {
+        "label": "c2pa.training-mining",
+        "data": {
+          "entries": {
+            "c2pa.ai_generative_training": { "use": "notAllowed" },
+            "c2pa.ai_inference": { "use": "notAllowed" },
+            "c2pa.ai_training": { "use": "notAllowed" },
+            "c2pa.data_mining": { "use": "notAllowed" }
+          }
+        }
+      }
+    ]
+  }
+
+  # Create a builder add a thumbnail resource and an ingredient file.
+  builder = Builder(manifest_json)
+
+  # The uri provided here "thumbnail" must match an identifier in the manifest definition.
+  builder.add_resource_file("thumbnail", "tests/fixtures/A_thumbnail.jpg")
+
+  # Define an ingredient, in this case a parent ingredient named A.jpg, with a thumbnail
+  ingredient_json = {
+    "title": "A.jpg",
+    "relationship": "parentOf", # "parentOf", "componentOf" or "inputTo"
+    "thumbnail": {
+        "identifier": "thumbnail",
+        "format": "image/jpeg"
+    }
+  }
+
+  # Add the ingredient to the builder loading information  from a source file.
+  builder.add_ingredient_file(ingredient_json, "tests/fixtures/A.jpg")
+
+  # At this point we could archive or unarchive our Builder to continue later.
+  # In this example we use a bytearray for the archive stream.
+  # all ingredients and resources will be saved in the archive
+  archive = io.BytesIO(bytearray())
+  builder.to_archive(archive)
+  archive.seek()
+  builder = builder.from_archive(archive)
+
+  # Sign and add our manifest to a source file, writing it to an output file.
+  # This returns the binary manifest data that could be uploaded to cloud storage.
+  c2pa_data = builder.sign_file(signer, "tests/fixtures/A.jpg", "target/out.jpg")
+
+except Exception as err:
+    print(err)
+ ```
 
 ### Creating a manifest JSON definition file
 

c2pa/__init__.py

@@ -0,0 +1,17 @@
+# Copyright 2024 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)
+# or the MIT license (http://opensource.org/licenses/MIT),
+# at your option.
+
+# Unless required by applicable law or agreed to in writing,
+# this software is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR REPRESENTATIONS OF ANY KIND, either express or
+# implied. See the LICENSE-MIT and LICENSE-APACHE files for the
+# specific language governing permissions and limitations under
+# each license.
+
+from .c2pa_api import Reader, Builder, create_signer, sign_ps256
+from .c2pa import Error, SigningAlg, sdk_version, version
+
+__all__ = ['Reader', 'Builder', 'create_signer', 'sign_ps256', 'Error', 'SigningAlg', 'sdk_version', 'version']

c2pa/c2pa_api/__init__.py

@@ -0,0 +1 @@
+from .c2pa_api import *

tests/c2pa_api.py renamed to c2pa/c2pa_api/c2pa_api.py

@@ -21,9 +21,9 @@
 )
 sys.path.append(SOURCE_PATH)
 
-import c2pa;
+import c2pa.c2pa as api
 
-from c2pa import Error, SigningAlg, version, sdk_version
+#from c2pa import Error, SigningAlg, version, sdk_version
 
 # This module provides a simple Python API for the C2PA library.
 
@@ -32,9 +32,9 @@
 # It also supports writing resources to a stream or file.
 #
 # Example:
-# reader = c2pa_api.Reader("image/jpeg", open("test.jpg", "rb"))
+# reader = Reader("image/jpeg", open("test.jpg", "rb"))
 # json = reader.json()
-class Reader(c2pa.Reader):
+class Reader(api.Reader):
     def __init__(self, format, stream):
         super().__init__()
         self.from_stream(format, C2paStream(stream))
@@ -47,6 +47,17 @@ def from_file(cls, path: str, format=None):
             format = os.path.splitext(path)[1][1:]
         return cls(format, file)
 
+    def get_manifest(self, label):
+        manifest_store = json.loads(self.json())
+        return manifest_store["manifests"].get(label)
+        return json.loads(self.json())
+    def get_active_manifest(self):
+        manifest_store = json.loads(self.json())
+        active_label = manifest_store.get("active_manifest")
+        if active_label:
+            return manifest_store["manifests"].get(active_label)
+        return None
+    
     def resource_to_stream(self, uri, stream) -> None:
         return super().resource_to_stream(uri, C2paStream(stream))
 
@@ -72,11 +83,11 @@ def resource_to_file(self, uri, path) -> None:
 #         "identifier": "thumbnail"
 #     }
 # }
-# builder = c2pa_api.Builder(manifest)
+# builder = Builder(manifest)
 # builder.add_resource_file("thumbnail", "thumbnail.jpg")
 # builder.add_ingredient_file({"parentOf": true}, "B.jpg")
 # builder.sign_file(signer, "test.jpg", "signed.jpg")
-class Builder(c2pa.Builder):
+class Builder(api.Builder):
     def __init__(self, manifest):
         super().__init__()
         self.set_manifest(manifest)
@@ -126,19 +137,19 @@ def sign_file(self, signer, sourcePath, outputPath):
 # Implements a C2paStream given a stream handle
 # This is used to pass a file handle to the c2pa library
 # It is used by the Reader and Builder classes internally  
-class C2paStream(c2pa.Stream):
+class C2paStream(api.Stream):
     def __init__(self, stream):
         self.stream = stream
 
     def read_stream(self, length: int) -> bytes:   
         #print("Reading " + str(length) + " bytes")
         return self.stream.read(length)
 
-    def seek_stream(self, pos: int, mode: c2pa.SeekMode) -> int:
+    def seek_stream(self, pos: int, mode: api.SeekMode) -> int:
         whence = 0
-        if mode is c2pa.SeekMode.CURRENT:
+        if mode is api.SeekMode.CURRENT:
             whence = 1
-        elif mode is c2pa.SeekMode.END:
+        elif mode is api.SeekMode.END:
             whence = 2
         #print("Seeking to " + str(pos) + " with whence " + str(whence))
         return self.stream.seek(pos, whence)
@@ -151,12 +162,12 @@ def flush_stream(self) -> None:
         self.stream.flush()
 
     # A shortcut method to open a C2paStream from a path/mode
-    def open_file(path: str, mode: str) -> c2pa.Stream:
+    def open_file(path: str, mode: str) -> api.Stream:
         return C2paStream(open(path, mode))
 
 # Internal class to implement signer callbacks
 # We need this because the callback expects a class with a sign method
-class SignerCallback(c2pa.SignerCallback):
+class SignerCallback(api.SignerCallback):
     def __init__(self, callback):
         self.sign = callback
         super().__init__() 
@@ -179,7 +190,7 @@ def __init__(self, callback):
 # signer = c2pa_api.create_signer(sign_ps256, "ps256", certs, "http://timestamp.digicert.com")
 #
 def create_signer(callback, alg, certs, timestamp_url=None):
-    return c2pa.CallbackSigner(SignerCallback(callback), alg, certs, timestamp_url)  
+    return api.CallbackSigner(SignerCallback(callback), alg, certs, timestamp_url)  
 
 
 

tests/test_api.py

@@ -10,12 +10,11 @@
 # specific language governing permissions and limitations under
 # each license.
 
-
 import json
 import pytest
 import tempfile
 
-from c2pa_api import  Builder, Error,  Reader, SigningAlg, create_signer,  sdk_version, sign_ps256, version
+from c2pa 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
@@ -60,12 +59,16 @@ def test_v2_read():
      #example of reading a manifest store from a file
     try:
         reader = Reader.from_file("tests/fixtures/C.jpg")
-        jsonReport = reader.json()
-        manifest_store = json.loads(jsonReport)
-        manifest = manifest_store["manifests"][manifest_store["active_manifest"]]
+        manifest = reader.get_active_manifest()
+        if manifest is None:
+            print("No active manifest found")
+            exit(1)
+        #jsonReport = reader.json()
+        #manifest_store = json.loads(jsonReport)
+        #manifest = manifest_store["manifests"][manifest_store["active_manifest"]]
         assert "make_test_images" in manifest["claim_generator"]
         assert manifest["title"]== "C.jpg"
-        assert manifest,["format"] == "image/jpeg"
+        assert manifest["format"] == "image/jpeg"
         # There should be no validation status errors
         assert manifest.get("validation_status") == None
         # read creative work assertion (author name)

tests/training.py

@@ -16,7 +16,7 @@
 import os
 import sys
 
-from c2pa_api import Builder, Reader, create_signer, SigningAlg, sign_ps256, version
+from c2pa import *
 
 # set up paths to the files we we are using
 PROJECT_PATH = os.getcwd()

tests/unit_tests.py

@@ -17,7 +17,7 @@
 import unittest
 from unittest.mock import mock_open, patch
 
-from c2pa_api import  Builder, Error,  Reader, SigningAlg, create_signer,  sdk_version, sign_ps256
+from c2pa import  Builder, Error,  Reader, SigningAlg, create_signer,  sdk_version, sign_ps256
 
 PROJECT_PATH = os.getcwd()
 
@@ -26,7 +26,7 @@
 class TestC2paSdk(unittest.TestCase):
 
     def test_version(self):
-        self.assertIn("0.4.0", sdk_version())
+        self.assertIn("0.5.0", sdk_version())
 
 
 class TestReader(unittest.TestCase):
@@ -94,7 +94,7 @@ def sign(data: bytes) -> bytes:
     def test_streams_build(self):
         with open(testPath, "rb") as file:
             builder = Builder(TestBuilder.manifestDefinition)
-            output = byte_array = io.BytesIO(bytearray())
+            output = io.BytesIO(bytearray())
             builder.sign(TestBuilder.signer, "image/jpeg", file, output)
             output.seek(0)
             reader = Reader("image/jpeg", output)