Merge pull request #1 from crandmck/main

Edit README

Author: gpeacock

README.md

@@ -1,64 +1,84 @@
 # C2PA Python
 
-Python bindings for the C2PA Content Authenticity Initiative (CAI) library
+Python bindings for the C2PA Content Authenticity Initiative (CAI) library.
 
-This library allows you to read and validate c2pa data in supported media files
-And to add signed manifests to supported media files.
+This library enables you to read and validate C2PA data in supported media files and add signed manifests to supported media files.
 
 ## Installation
 
-```pip install c2pa-python```
+Install from PyPI by entering this command:
+
+```
+pip install c2pa-python
+```
 
 ## Usage
 
 ### Import
 
-```import c2pa-python as c2pa```
+Import the C2PA module as follows:
+
+```py
+import c2pa-python as c2pa
+```
+
+### Read and validate C2PA data in a file
 
-### Reading and Validating C2PA data in a file
+Use the `verify_from_file_json` function to read C2PA data from the specified file:
 
-Read any C2PA data from a given file 
+```py
+json_store = c2pa.verify_from_file_json("path/to/media_file.jpg", 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).
 
-```json_store = c2pa.verify_from_file_json("path/to/media_file.jpg", data_dir)```
+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.
 
-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.
+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.
 
-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.
+NOTE: For a comprehensive reference to the JSON manifest structure, see the [CAI manifest store reference](https://contentauth.github.io/json-manifest-reference/manifest-reference).
 
-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.
+### Add a signed manifest to a media file
 
+Use the `add_manifest_to_file_json` function to add a signed manifest to a media file.
 
-### 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
+```py
+result = c2pa.add_manifest_to_file_json("path/to/source.jpg", 
+                                        "path/to/dest.jpg", 
+                                        manifest_json, 
+                                        sign_info, 
+                                        data_dir)
+```
 
-```result = c2pa.add_manifest_to_file_json("path/to/source.jpg", "path/to/dest.jpg", manifest_json, sign_info, data_dir)```
+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.
 
 ### Generating SignerInfo
 
-Set up the signer info from pem and key files.
+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:
 
-```certs = open("path/to/public_certs.pem","rb").read()```
-```prv_key = open("path/to/private_key.pem","rb").read()```
+```py
+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. 
+Then create a new `SignerInfo` instance using the keys as follows, specifying the signing algorithm used and optionally a time stamp authority URL:
 
-```sign_info = c2pa.SignerInfo(certs, priv_key, "es256", "http://timestamp.digicert.com") ```
+```py
+sign_info = c2pa.SignerInfo(certs, priv_key, "es256", "http://timestamp.digicert.com")
+```
 
+For the list of supported signing algorithms, see [Creating and using an X.509 certificate](https://opensource.contentauthenticity.org/docs/c2patool/x_509).
 
-### Creating a Manifest Json Definition File
+### Creating a manifest JSON definition file
 
-The manifest json string defines the c2pa to add to the file.
+The manifest JSON string defines the C2PA manifest to add to the file.
 
-```
+```py
 manifest_json = json.dumps({
     "claim_generator": "python_test/0.1",
     "assertions": [
@@ -75,28 +95,35 @@ manifest_json = json.dumps({
     }
   ]
  })
- ```
-## 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
+## Development
 
-```pip install maturin```
+It is best to [set up a virtual environment](https://virtualenv.pypa.io/en/latest/installation.html) for development and testing.
 
-You will also need to install uniffi bindgen and pytest for testing
+We use `maturin` for packaging Rust in Python. Install it as follows: 
 
-``pip install uniffi_bindgen`` 
+```
+pip install maturin
+```
 
-``pip install -U pytest`` 
+You also must install `uniffi`, `bindgen`, and `pytest` for testing
 
-``pip install <path to.whl> --force-reinstall``
+```
+pip install uniffi_bindgen
+pip install -U pytest
+pip install <path-to-whl> --force-reinstall
+```
 
 ### Testing
 
-```pytest```
+We use [PyTest](https://docs.pytest.org/) for testing.
+
+Run tests by entering this command:
 
+```
+pytest
+```
 
 ## Supported file formats