Added data_dir to verify and add_manifest

removed sidecar and remote_url options
Updated Readme
Updated c2pa-rs version

Author: gpeacock

.gitignore

@@ -4,6 +4,7 @@ debug/
 target/
 
 venv/
+.venv/
 
 # Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
 # More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "c2pa-python"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2021"
 authors = ["Gavin Peacock <[email protected]"]
 
@@ -10,7 +10,7 @@ name = "c2pa_python"
 crate-type = ["cdylib"]
 
 [dependencies]
-c2pa = {version="0.25.0", features = ["file_io", "add_thumbnails", "fetch_remote_manifests"]}
+c2pa = {version="0.26.0", features = ["file_io", "add_thumbnails", "fetch_remote_manifests"]}
 serde = { version = "1.0", features = ["derive"] }
 serde_derive = "1.0"
 serde_json = "1.0"

README.md

@@ -1,33 +1,102 @@
-# C2PA Python Package
+# C2PA Python
 
-This Package is contributed as part of the [Content Authenticity Initiative](https://contentauthenticity.org) and [released it to open source](https://contentauthenticity.org/blog/cai-releases-suite-of-open-source-tools-to-advance-digital-content-provenance) in Sept, 2023.
+Python bindings for the C2PA Content Authenticity Initiative (CAI) library
 
-## Key features
+This library allows you to read and validate c2pa data in supported media files
+And to add signed manifests to supported media files.
 
-The SDK enables Python applications to:
-* Create and sign C2PA manifests.
-* Embed manifests in certain file formats.
-* Parse and validate manifests found in certain file formats.
+## Installation
 
-## State of the project
+```pip install c2pa-python```
 
-This is a beta release (version 0.x.x) of the project. The minor version number (0.x.0) is incremented when there are breaking API changes, which may happen frequently.
+## Usage
 
-### Contributions and feedback
+### Import
 
-We welcome contributions to this project.  For information on contributing, providing feedback, and about ongoing work, see [Contributing](https://github.com/contentauth/c2pa-js/blob/main/CONTRIBUTING.md).
+```import c2pa-python as c2pa```
+
+### Reading and Validating C2PA data in a file
+
+Read any C2PA data from a given file 
+
+```json_store = c2pa.verify_from_file_json("path/to/media_file.jpg", data_dir)```
+
+This will examine any supported media file for c2pa data and generate
+a JSON report of any data it finds. The report will include a validation_status field if any validation errors were found.
+
+A media file may contain many manifests in a manifest store. The most recent manifest can be accessed by looking up the active_manifest field value in the manifests map.
+
+If the optional data_dir is provided, any binary resources, such as thumbnails, icons and c2pa_data will be extracted into that directory.
+These files will be referenced by the identifier fields in the manifest store report.
+
+
+### Adding a Signed Manifest to a media file
+The source is the media file which should receive new c2pa data.
+The destination will have a copy of the source with the data added.
+The manifest Json is a a JSON formatted string containing the data you want to add.
+(see: [Generating SignerInfo](#generating-signerinfo) for how to construct SignerInfo)
+The optional data_dir allows you to load resource files referenced from manifest_json identifiers.
+When building your manifest, any files referenced by identifier fields will be loaded relative to this path.
+This allows you to load thumbnails, icons and manifest data for ingredients
+
+```result = c2pa.add_manifest_to_file_json("path/to/source.jpg", "path/to/dest.jpg", manifest_json, sign_info, data_dir)```
+
+### Generating SignerInfo
+
+Set up the signer info from pem and key files.
+
+```certs = open("path/to/public_certs.pem","rb").read()```
+```prv_key = open("path/to/private_key.pem","rb").read()```
+
+Then create a new SignerInfo instance using those keys.
+You must specify the signing algorithm used and may optionally add a time stamp authority URL. 
+
+```sign_info = c2pa.SignerInfo(certs, priv_key, "es256", "http://timestamp.digicert.com") ```
+
+
+### Creating a Manifest Json Definition File
+
+The manifest json string defines the c2pa to add to the file.
+
+```
+manifest_json = json.dumps({
+    "claim_generator": "python_test/0.1",
+    "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" }
+        }
+      }
+    }
+  ]
+ })
+ ```
+## Development
+
+It is best to set up a virtual environment for development and testing
+https://virtualenv.pypa.io/en/latest/installation.html
+
+We use maturin for packaging Rust in Python. It can can be installed with pip
+
+```pip install maturin```
+
+You will also need to install uniffi bindgen and pytest for testing
 
-## Requirements
+``pip install uniffi_bindgen`` 
 
-The SDK requires **Python version ???** or newer.
+``pip install -U pytest`` 
 
-### Supported platforms
+``pip install <path to.whl> --force-reinstall``
 
-The SDK has been tested on the following operating systems:
+### Testing
+
+```pytest```
 
-* Windows (Intel only)
-* MacOS (Intel and Apple silicon)
-* Ubuntu Linux (64-bit Intel and ARM v8)
 
 ## Supported file formats
 
@@ -49,29 +118,14 @@ The SDK has been tested on the following operating systems:
  | `wav`         | `audio/x-wav`                                       |
  | `webp`        | `image/webp`                                        |
 
-## Distribution
-
-This package can be installed with :
-
-```pip install c2pa-python```
-
-## Building
-
-This uses maturin for packaging Rust in Python. It can can be installed with pip
-
-```pip install maturin```
-
-You will also need to install uniffi bindgen and pytest for testing
-
-``pip install uniffi_bindgen`` 
-
-``pip install -U pytest`` 
-
-``pip install <path to.whl> --force-reinstall``
-
 ## License
 
 This package is distributed under the terms of both the [MIT license](https://github.com/contentauth/c2pa-rs/blob/main/LICENSE-MIT) and the [Apache License (Version 2.0)](https://github.com/contentauth/c2pa-rs/blob/main/LICENSE-APACHE).
 
 Note that some components and dependent crates are licensed under different terms; please check the license terms for each crate and component for details.
 
+### Contributions and feedback
+
+We welcome contributions to this project.  For information on contributing, providing feedback, and about ongoing work, see [Contributing](https://github.com/contentauth/c2pa-js/blob/main/CONTRIBUTING.md).
+
+

pyproject.toml

@@ -5,10 +5,25 @@ build-backend = "maturin"
 [project]
 name = "c2pa-python"
 requires-python = ">=3.7"
+description = "Python bindings for the C2PA Content Authenticity Initiative (CAI) library"
+readme = { file = "README.md", content-type = "text/markdown" }
+license = {file = "LICENSE-MIT"}
+keywords = ["C2PA", "CAI", "content credentials", "metadata", "provenance"]
 classifiers = [
+    "Development Status :: 3 - Alpha",
     "Programming Language :: Rust",
     "Programming Language :: Python :: Implementation :: CPython",
     "Programming Language :: Python :: Implementation :: PyPy",
 ]
+authors = [
+  {name = "Gavin Peacock", email = "[email protected]"}
+]
+maintainers = [
+  {name = "Gavin Peacock", email = "[email protected]"}
+]
+urls = {homepage = "contentauthenticity.org", repository = "github.com/contentauth/c2pa-python"}
 
-
+[project.optional-dependencies]
+test = [
+  "pytest < 5.0.0"
+]

src/c2pa.udl

@@ -3,11 +3,11 @@ namespace c2pa {
   string version();
   string sdk_version();
   [Throws=Error]
-  string verify_from_file_json([ByRef] string path);
+  string verify_from_file_json([ByRef] string path, string? data_dir);
   [Throws=Error]
   string ingredient_from_file_json([ByRef] string path, [ByRef] string data_dir);
   [Throws=Error]
-  sequence<u8> add_manifest_to_file_json([ByRef] string source, [ByRef] string dest, [ByRef] string manifest, SignerInfo signer_info, boolean side_car, string? remote_url);
+  sequence<u8> add_manifest_to_file_json([ByRef] string source, [ByRef] string dest, [ByRef] string manifest, SignerInfo signer_info, string? data_dir);
 };
 
 [Error]

src/json_api.rs

@@ -10,25 +10,27 @@
 // specific language governing permissions and limitations under
 // each license.
 
-use std::path::PathBuf;
-
 use c2pa::{Ingredient, Manifest, ManifestStore};
 
 use crate::{Error, Result, SignerInfo};
 
 /// Returns ManifestStore JSON string from a file path.
 ///
+/// If data_dir is provided, any thumbnail or c2pa data will be written to that folder.
 /// Any Validation errors will be reported in the validation_status field.
 ///
-pub fn verify_from_file_json(path: &str) -> Result<String> {
-    Ok(ManifestStore::from_file(path)
-        .map_err(Error::Sdk)?
-        .to_string())
+pub fn verify_from_file_json(path: &str, data_dir: Option<String>) -> Result<String> {
+    Ok(match data_dir {
+        Some(dir) => ManifestStore::from_file_with_resources(path, &dir),
+        None => ManifestStore::from_file(path),
+    }
+    .map_err(Error::Sdk)?
+    .to_string())
 }
 
 /// Returns an Ingredient JSON string from a file path.
 ///
-/// Thumbnail and c2pa data written to data_dir if provided
+/// Any thumbnail or c2pa data will be written to data_dir if provided
 pub fn ingredient_from_file_json(path: &str, data_dir: &str) -> Result<String> {
     Ok(Ingredient::from_file_with_folder(path, data_dir)
         .map_err(Error::Sdk)?
@@ -46,31 +48,13 @@ pub fn add_manifest_to_file_json(
     dest: &str,
     manifest_info: &str,
     signer_info: SignerInfo,
-    side_car: bool,
-    remote_url: Option<String>,
+    data_dir: Option<String>,
 ) -> Result<Vec<u8>> {
     let mut manifest = Manifest::from_json(manifest_info).map_err(Error::Sdk)?;
 
-    // read any manifest referenced files from the source path
-    // or current folder if no path available
-    if let Some(path) = PathBuf::from(source).parent() {
+    // if data_dir is provided, set the base path for the manifest
+    if let Some(path) = data_dir {
         manifest.with_base_path(path).map_err(Error::Sdk)?;
-    } else if let Ok(path) = std::env::current_dir() {
-        manifest.with_base_path(&path).map_err(Error::Sdk)?;
-    }
-
-    // if side_car then don't embed the manifest
-    if side_car {
-        manifest.set_sidecar_manifest();
-    }
-
-    // add the remote url if provided
-    if let Some(url) = remote_url {
-        if side_car {
-            manifest.set_remote_manifest(url);
-        } else {
-            manifest.set_embedded_manifest_with_remote_ref(url);
-        }
     }
 
     // If the source file has a manifest store, and no parent is specified, treat the source's manifest store as the parent.
@@ -88,6 +72,7 @@ pub fn add_manifest_to_file_json(
 #[cfg(test)]
 mod tests {
     use super::*;
+    use std::{fs::remove_dir_all, path::PathBuf};
 
     /// returns a path to a file in the fixtures folder
     pub fn test_path(path: &str) -> String {
@@ -96,13 +81,27 @@ mod tests {
     }
 
     #[test]
-    fn test_verify_from_file() {
+    fn test_verify_from_file_no_base() {
         let path = test_path("tests/fixtures/C.jpg");
-        let result = verify_from_file_json(&path);
+        let result = verify_from_file_json(&path, None);
         assert!(result.is_ok());
         let json_report = result.unwrap();
         println!("{}", json_report);
         assert!(json_report.contains("C.jpg"));
         //assert!(!json_report.contains("validation_status"));
     }
+
+    #[test]
+    fn test_verify_from_file_with_base() {
+        let path = test_path("tests/fixtures/C.jpg");
+        let data_dir = "target/data_dir";
+        remove_dir_all(data_dir).unwrap();
+        let result = verify_from_file_json(&path, Some(data_dir.to_owned()));
+        assert!(result.is_ok());
+        let json_report = result.unwrap();
+        println!("{}", json_report);
+        assert!(json_report.contains("C.jpg"));
+        assert!(PathBuf::from(data_dir).exists());
+        assert!(json_report.contains("thumbnail"));
+    }
 }

tests/test_c2pa.py

@@ -15,18 +15,18 @@
 import pytest
 
 def test_version():
-    assert c2pa.version() == "0.1.0"
+    assert c2pa.version() == "0.1.1"
 
 def test_sdk_version():
-    assert c2pa.sdk_version() == "0.25.2"
+    assert c2pa.sdk_version() == "0.26.0"
 
 
-#def test_verify_from_file():
-#    json_store = c2pa.verify_from_file_json("tests/fixtures/A.jpg") 
-#    assert not "validation_status" in json_store
+def test_verify_from_file():
+    json_store = c2pa.verify_from_file_json("tests/fixtures/C.jpg", None) 
+    assert not "validation_status" in json_store
 
 def test_verify_from_file_no_store():
     with pytest.raises(c2pa.Error.Sdk) as err:  
-        json_store = c2pa.verify_from_file_json("tests/fixtures/A.jpg") 
+        json_store = c2pa.verify_from_file_json("tests/fixtures/A.jpg", None) 
     assert str(err.value) == "no JUMBF data found"  
 

tests/training.py

@@ -57,7 +57,7 @@ def getitem(d, key):
     test_key = open(keyFile,"rb").read()
     sign_info = c2pa.SignerInfo(test_pem, test_key, "es256", "http://timestamp.digicert.com")
 
-    result = c2pa.add_manifest_to_file_json(testFile, testOutputFile, manifest_json, sign_info, False, None)
+    result = c2pa.add_manifest_to_file_json(testFile, testOutputFile, manifest_json, sign_info, None)
 
 except Exception as err:
     sys.exit(err)
@@ -69,7 +69,7 @@ def getitem(d, key):
 
 allowed = True # opt out model, assume training is ok if the assertion doesn't exist
 try:
-    json_store = c2pa.verify_from_file_json(testOutputFile)
+    json_store = c2pa.verify_from_file_json(testOutputFile, None)
     manifest_store = json.loads(json_store)
 
     manifest = manifest_store["manifests"][manifest_store["active_manifest"]]