c2pa¶

Submodules¶

Exceptions¶

C2paError

Exception raised for C2PA errors.

Classes¶

`Builder`	High-level wrapper for C2PA Builder operations.
`Reader`	High-level wrapper for C2PA Reader operations.
`C2paSigningAlg`	Supported signing algorithms.
`C2paSignerInfo`	Configuration for a Signer.
`Signer`	High-level wrapper for C2PA Signer operations.
`Stream`

Functions¶

`sdk_version`()	Returns the underlying c2pa-rs/c2pa-c-ffi version string
`read_ingredient_file`(path, data_dir)	Read a file as C2PA ingredient (deprecated).

Package Contents¶

class c2pa.Builder(manifest_json)¶

High-level wrapper for C2PA Builder operations.

Parameters:: manifest_json (Any)

classmethod get_supported_mime_types()¶

Get the list of supported MIME types for the Builder. This method retrieves supported MIME types from the native library.

Returns:: List of supported MIME type strings
Raises:: C2paError – If there was an error retrieving the MIME types
Return type:: list[str]

classmethod from_json(manifest_json)¶

Create a new Builder from a JSON manifest.

Parameters:: manifest_json (Any) – The JSON manifest definition
Returns:: A new Builder instance
Raises:: C2paError – If there was an error creating the builder
Return type:: Builder

classmethod from_archive(stream)¶

Create a new Builder from an archive stream.

Parameters:: stream (Any) – The stream containing the archive (any Python stream-like object)
Returns:: A new Builder instance
Raises:: C2paError – If there was an error creating the builder from archive
Return type:: Builder

close()¶

Release the builder resources.

This method ensures all resources are properly cleaned up, even if errors occur during cleanup. Errors during cleanup are logged but not raised to ensure cleanup. Multiple calls to close() are handled gracefully.

set_no_embed()¶

Set the no-embed flag.

When set, the builder will not embed a C2PA manifest store into the asset when signing. This is useful when creating cloud or sidecar manifests.

set_remote_url(remote_url)¶

Set the remote URL.

When set, the builder embeds a remote URL into the asset when signing. This is useful when creating cloud based Manifests.

Parameters:: remote_url (str) – The remote URL to set
Raises:: C2paError – If there was an error setting the remote URL

add_resource(uri, stream)¶

Add a resource to the builder.

Parameters:

uri (str) – The URI to identify the resource
stream (Any) – The stream containing the resource data (any Python stream-like object)

Raises:

C2paError – If there was an error adding the resource

add_ingredient(ingredient_json, format, source)¶

Add an ingredient to the builder (facade method). The added ingredient’s source should be a stream-like object (for instance, a file opened as stream).

Parameters:

ingredient_json (str) – The JSON ingredient definition
format (str) – The MIME type or extension of the ingredient
source (Any) – The stream containing the ingredient data (any Python stream-like object)

Raises:

C2paError – If there was an error adding the ingredient
C2paError.Encoding – If the ingredient JSON contains invalid UTF-8 characters

Example

with open(ingredient_file_path, 'rb') as a_file:
    builder.add_ingredient(ingredient_json, "image/jpeg", a_file)

add_ingredient_from_stream(ingredient_json, format, source)¶

Add an ingredient from a stream to the builder. Explicitly named API requiring a stream as input parameter.

Parameters:

ingredient_json (str) – The JSON ingredient definition
format (str) – The MIME type or extension of the ingredient
source (Any) – The stream containing the ingredient data (any Python stream-like object)

Raises:

C2paError – If there was an error adding the ingredient
C2paError.Encoding – If the ingredient JSON or format contains invalid UTF-8 characters

add_ingredient_from_file_path(ingredient_json, format, filepath)¶

Add an ingredient from a file path to the builder (deprecated). This is a legacy method.

Deprecated since version 0.13.0: This method is deprecated and will be removed in a future version. Use add_ingredient() with a file stream instead.

Parameters:

ingredient_json (str) – The JSON ingredient definition
format (str) – The MIME type or extension of the ingredient
filepath (Union[str, pathlib.Path]) – The path to the file containing the ingredient data (can be a string or Path object)

Raises:

C2paError – If there was an error adding the ingredient
C2paError.Encoding – If the ingredient JSON or format contains invalid UTF-8 characters
FileNotFoundError – If the file at the specified path does not exist

to_archive(stream)¶

Write an archive of the builder to a stream.

Parameters:: stream (Any) – The stream to write the archive to (any Python stream-like object)
Raises:: C2paError – If there was an error writing the archive
Return type:: None

sign(signer, format, source, dest=None)¶

Sign the builder’s content and write to a destination stream.

Parameters:

format (str) – The MIME type or extension of the content
source (Any) – The source stream (any Python stream-like object)
dest (Any) – The destination stream (any Python stream-like object), opened in w+b (write+read binary) mode.
signer (Signer) – The signer to use

Returns:

Manifest bytes

Raises:

C2paError – If there was an error during signing

Return type:

bytes

sign_file(source_path, dest_path, signer)¶

Sign a file and write the signed data to an output file.

Parameters:

source_path (Union[str, pathlib.Path]) – Path to the source file. We will attempt to guess the mimetype of the source file based on the extension.
dest_path (Union[str, pathlib.Path]) – Path to write the signed file to
signer (Signer) – The signer to use

Returns:

Manifest bytes

Raises:

C2paError – If there was an error during signing

Return type:

bytes

exception c2pa.C2paError(message='')¶

Bases: Exception

Exception raised for C2PA errors.

Parameters:: message (str)

message = ''¶

exception Assertion¶

Bases: Exception

Exception raised for assertion errors.

exception AssertionNotFound¶

Bases: Exception

Exception raised when an assertion is not found.

exception Decoding¶

Bases: Exception

Exception raised for decoding errors.

exception Encoding¶

Bases: Exception

Exception raised for encoding errors.

exception FileNotFound¶

Bases: Exception

Exception raised when a file is not found.

exception Io¶

Bases: Exception

Exception raised for IO errors.

exception Json¶

Bases: Exception

Exception raised for JSON errors.

exception Manifest¶

Bases: Exception

Exception raised for manifest errors.

exception ManifestNotFound¶

Bases: Exception

Exception raised when a manifest is not found.

exception NotSupported¶

Bases: Exception

Exception raised for unsupported operations.

exception Other¶

Bases: Exception

Exception raised for other errors.

exception RemoteManifest¶

Bases: Exception

Exception raised for remote manifest errors.

exception ResourceNotFound¶

Bases: Exception

Exception raised when a resource is not found.

exception Signature¶

Bases: Exception

Exception raised for signature errors.

exception Verify¶

Bases: Exception

Exception raised for verification errors.

class c2pa.Reader(format_or_path, stream=None, manifest_data=None)¶

High-level wrapper for C2PA Reader operations.

Example

with Reader("image/jpeg", output) as reader:
    manifest_json = reader.json()

Where output is either an in-memory stream or an opened file.

Parameters:

format_or_path (Union[str, pathlib.Path])
stream (Optional[Any])
manifest_data (Optional[Any])

classmethod get_supported_mime_types()¶

Get the list of supported MIME types for the Reader. This method retrieves supported MIME types from the native library.

Returns:: List of supported MIME type strings
Raises:: C2paError – If there was an error retrieving the MIME types
Return type:: list[str]

close()¶

Release the reader resources.

json()¶

Get the manifest store as a JSON string.

Returns:: The manifest store as a JSON string
Raises:: C2paError – If there was an error getting the JSON
Return type:: str

resource_to_stream(uri, stream)¶

Write a resource to a stream.

Parameters:

uri (str) – The URI of the resource to write
stream (Any) – The stream to write to (any Python stream-like object)

Returns:

The number of bytes written

Raises:

C2paError – If there was an error writing the resource to stream

Return type:

int

class c2pa.C2paSigningAlg¶

Bases: enum.IntEnum

Supported signing algorithms.

ES256 = 0¶

ES384 = 1¶

ES512 = 2¶

PS256 = 3¶

PS384 = 4¶

PS512 = 5¶

ED25519 = 6¶

class c2pa.C2paSignerInfo(alg, sign_cert, private_key, ta_url)¶

Bases: ctypes.Structure

Configuration for a Signer.

class c2pa.Signer(signer_ptr)¶

High-level wrapper for C2PA Signer operations.

Parameters:: signer_ptr (ctypes.POINTER(C2paSigner))

classmethod from_info(signer_info)¶

Create a new Signer from signer information.

Parameters:: signer_info (C2paSignerInfo) – The signer configuration
Returns:: A new Signer instance
Raises:: C2paError – If there was an error creating the signer
Return type:: Signer

classmethod from_callback(callback, alg, certs, tsa_url=None)¶

Create a signer from a callback function.

Parameters:

callback (Callable[[bytes], bytes]) – Function that signs data and returns the signature
alg (C2paSigningAlg) – The signing algorithm to use
certs (str) – Certificate chain in PEM format
tsa_url (Optional[str]) – Optional RFC 3161 timestamp authority URL

Returns:

A new Signer instance

Raises:

C2paError – If there was an error creating the signer
C2paError.Encoding – If the certificate data or TSA URL contains invalid UTF-8 characters

Return type:

Signer

close()¶

Release the signer resources.

This method ensures all resources are properly cleaned up, even if errors occur during cleanup.

Note

Multiple calls to close() are handled gracefully. Errors during cleanup are logged but not raised to ensure cleanup.

reserve_size()¶

Get the size to reserve for signatures from this signer.

Returns:: The size to reserve in bytes
Raises:: C2paError – If there was an error getting the size
Return type:: int

class c2pa.Stream(file_like_stream)¶

close()¶

Release the stream resources.

write_to_target(dest_stream)¶

property closed: bool¶

Check if the stream is closed.

Returns:: True if the stream is closed, False otherwise
Return type:: bool

property initialized: bool¶

Check if the stream is properly initialized.

Returns:: True if the stream is initialized, False otherwise
Return type:: bool

c2pa.sdk_version()¶

Returns the underlying c2pa-rs/c2pa-c-ffi version string

Return type:: str

c2pa.read_ingredient_file(path, data_dir)¶

Read a file as C2PA ingredient (deprecated). This creates the JSON string that would be used as the ingredient JSON.

Deprecated since version 0.11.0: This function is deprecated and will be removed in a future version. To read C2PA metadata, use the c2pa.c2pa.Reader class. To add ingredients to a manifest, use c2pa.c2pa.Builder.add_ingredient().

Parameters:

path (Union[str, pathlib.Path]) – Path to the file to read
data_dir (Union[str, pathlib.Path]) – Directory to write binary resources to

Returns:

The ingredient as a JSON string

Raises:

C2paError – If there was an error reading the file

Return type:

str