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.
`C2paDigitalSourceType`	List of possible digital source types.
`C2paBuilderIntent`	Builder intent enumeration.
`C2paSignerInfo`	Configuration for a Signer.
`Signer`	High-level wrapper for C2PA Signer operations.
`Stream`
`Settings`	Configuration for C2PA operations.
`Context`	Per-instance context for C2PA operations.
`ContextBuilder`	Fluent builder for Context.
`ContextProvider`	Abstract base class for types that provide a C2PA context.

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).
`load_settings`(…)	Load C2PA settings into thread-local storage from a string or dict.

Package Contents¶

class c2pa.Builder(manifest_json: Any)¶

class c2pa.Builder(manifest_json, context)

Bases: ManagedResource

High-level wrapper for C2PA Builder operations.

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: Any) → Builder¶

classmethod from_json(manifest_json: Any, context: ContextProvider) → Builder

Create a new Builder from a JSON manifest.

Parameters:

manifest_json – The JSON manifest definition
context – Optional ContextProvider for settings

Returns:

A new Builder instance

Raises:

C2paError – If there was an error creating the builder

classmethod from_archive(stream)¶

Create a new Builder from an archive stream.

This creates builder without a context. To use a context, create a Builder with a context first, then call with_archive() on it.

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

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

set_intent(intent, digital_source_type=C2paDigitalSourceType.EMPTY)¶

Set the intent for the manifest.

The intent specifies what kind of manifest to create: - CREATE: New with specified digital source type.

Must not have a parent ingredient.

EDIT: Edit of a pre-existing parent asset.
Must have a parent ingredient.
UPDATE: Restricted version of Edit for non-editorial changes.
Must have only one ingredient, as a parent.

Parameters:

intent (C2paBuilderIntent) – The builder intent (C2paBuilderIntent enum value)
digital_source_type (C2paDigitalSourceType) – The digital source type (required for CREATE intent). Defaults to C2paDigitalSourceType.EMPTY (for all other cases).

Raises:

C2paError – If there was an error setting the intent

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 (Union[str, dict]) – The JSON ingredient definition (either a JSON string or a dictionary)
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 (Union[str, dict]) – The JSON ingredient definition (either a JSON string or a dictionary)
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 (Union[str, dict]) – The JSON ingredient definition (either a JSON string or a dictionary)
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

add_action(action_json)¶

Add an action to the builder, that will be placed in the actions assertion array in the generated manifest.

Parameters:

action_json (Union[str, dict]) – The JSON action definition (either a JSON string or a dictionary)

Raises:

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

Return type:

None

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

with_archive(stream)¶

Load an archive into this Builder instance, replacing its manifest definition. The archive carries only the definition, not settings. Settings come from the context that was configured to be used with this Builder instance.

Parameters:: stream (Any) – The stream containing the archive
Returns:: This builder instance, for method chaining.
Raises:: C2paError – If there was an error loading the archive
Return type:: Builder

sign(signer: Signer, format: str, source: Any, dest: Any = None) → bytes¶

sign(format: str, source: Any, dest: Any = None) → bytes

Sign the builder’s content.

Can be called with or without an explicit signer. If no signer is provided, the context’s signer is used (builder must have been created with a Context that has a signer).

Parameters:

signer – The signer to use. If not provided, the context’s signer is used.
format – The MIME type of the content.
source – The source stream.
dest – The destination stream (optional).

Returns:

Manifest bytes

Raises:

C2paError – If there was an error during signing

sign_file(source_path: str | pathlib.Path, dest_path: str | pathlib.Path, signer: Signer) → bytes¶

sign_file(source_path: str | pathlib.Path, dest_path: str | pathlib.Path) → bytes

Sign a file and write signed data to output.

Can be called with or without an explicit signer. If no signer is provided, the context’s signer is used (builder must have been created with a Context that has a signer).

Parameters:

source_path – Path to the source file.
dest_path – Path to write the signed file to.
signer – The signer to use. If None, the context’s signer is used.

Returns:

Manifest bytes

Raises:

C2paError – If there was an error during signing

exception c2pa.C2paError(message='')¶

Bases: Exception

Exception raised for C2PA errors.

This is the base class for all C2PA exceptions. Catching C2paError will catch all typed C2PA exceptions (e.g., C2paError.ManifestNotFound).

Parameters:: message (str)

message = ''¶

class c2pa.Reader(format_or_path: str | pathlib.Path, stream: Any | None = None, manifest_data: Any | None = None)¶

class c2pa.Reader(format_or_path, stream, manifest_data, context)

Bases: ManagedResource

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.

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]

classmethod try_create(format_or_path: str | pathlib.Path, stream: Any | None = None, manifest_data: Any | None = None) → Reader | None¶

classmethod try_create(format_or_path: str | pathlib.Path, stream: Any | None, manifest_data: Any | None, context: ContextProvider) → Reader | None

This is a factory method to create a new Reader, returning None if no manifest/c2pa data/JUMBF data could be read (instead of raising a ManifestNotFound: no JUMBF data found exception).

Returns None instead of raising C2paError.ManifestNotFound if no C2PA manifest data is found in the asset. This is useful when you want to check if an asset contains C2PA data without handling exceptions for the expected case of no manifest.

Parameters:

format_or_path – The format or path to read from
stream – Optional stream to read from (Python stream-like object)
manifest_data – Optional manifest data in bytes
context – Optional ContextProvider for settings

Returns:

Reader instance if the asset contains C2PA data, None if no manifest found (ManifestNotFound: no JUMBF data found)

Raises:

C2paError – If there was an error other than ManifestNotFound

with_fragment(format, stream, fragment_stream)¶

Process a BMFF fragment stream with this reader.

Used for fragmented BMFF media (DASH/HLS streaming) where content is split into init segments and fragment files.

Parameters:

format (str) – MIME type of the media (e.g., “video/mp4”)
stream – Stream-like object with the main/init segment data
fragment_stream – Stream-like object with the fragment data

Returns:

This reader instance, for method chaining.

Raises:

C2paError – If there was an error processing the fragment

Return type:

Reader

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

detailed_json()¶

Get the detailed JSON representation of the C2PA manifest store.

This method returns a more detailed JSON string than Reader.json(), providing additional information about the manifest structure. Note that the returned JSON by this method has a slightly different structure than the one returned by Reader.json().

Returns:: A JSON string containing the detailed manifest store data.
Raises:: C2paError – If there is an error reading the manifest data or if the Reader has been closed.
Return type:: str

get_active_manifest()¶

Get the active manifest from the manifest store.

This method retrieves the full manifest JSON and extracts the active manifest based on the active_manifest key.

Returns:: A dictionary containing the active manifest data, including claims, assertions, ingredients, and signature information, or None if no manifest is found or if there was an error parsing the JSON.
Raises:: KeyError – If the active_manifest key is missing from the JSON
Return type:: Optional[dict]

get_manifest(label)¶

Get a specific manifest from the manifest store by its label.

This method retrieves the manifest JSON and extracts the manifest that corresponds to the provided manifest label/ID.

Parameters:: label (str) – The manifest label/ID to look up in the manifest store
Returns:: A dictionary containing the manifest data for the specified label, or None if no manifest is found or if there was an error parsing the JSON.
Raises:: KeyError – If the manifests key is missing from the JSON
Return type:: Optional[dict]

get_validation_state()¶

Get the validation state of the manifest store.

This method retrieves the full manifest JSON and extracts the validation_state field, which indicates the overall validation status of the C2PA manifest.

Returns:: The validation state as a string, or None if the validation_state field is not present or if no manifest is found or if there was an error parsing the JSON.
Return type:: Optional[str]

get_validation_results()¶

Get the validation results of the manifest store.

This method retrieves the full manifest JSON and extracts the validation_results object, which contains detailed validation information.

Returns:: The validation results as a dictionary containing validation details, or None if the validation_results field is not present or if no manifest is found or if there was an error parsing the JSON.
Return type:: Optional[dict]

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

is_embedded()¶

Check if the reader was created from an embedded manifest. This method determines whether the C2PA manifest is embedded directly in the asset file or stored remotely. :returns: True if the reader was created from an embedded manifest,

False if it was created from a remote manifest

Raises:: C2paError – If there was an error checking the embedded status
Return type:: bool

get_remote_url()¶

Get the remote URL of the manifest if it was obtained remotely. This method returns the URL from which the C2PA manifest was fetched if the reader was created from a remote manifest. If the manifest is embedded in the asset, this will return None. :returns: The remote URL as a string if the manifest was obtained remotely,

None if the manifest is embedded or no remote URL is available

Raises:: C2paError – If there was an error getting the remote URL
Return type:: Optional[str]

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.C2paDigitalSourceType¶

Bases: enum.IntEnum

List of possible digital source types.

EMPTY = 0¶

TRAINED_ALGORITHMIC_DATA = 1¶

DIGITAL_CAPTURE = 2¶

COMPUTATIONAL_CAPTURE = 3¶

NEGATIVE_FILM = 4¶

POSITIVE_FILM = 5¶

PRINT = 6¶

HUMAN_EDITS = 7¶

COMPOSITE_WITH_TRAINED_ALGORITHMIC_MEDIA = 8¶

ALGORITHMICALLY_ENHANCED = 9¶

DIGITAL_CREATION = 10¶

DATA_DRIVEN_MEDIA = 11¶

TRAINED_ALGORITHMIC_MEDIA = 12¶

ALGORITHMIC_MEDIA = 13¶

SCREEN_CAPTURE = 14¶

VIRTUAL_RECORDING = 15¶

COMPOSITE = 16¶

COMPOSITE_CAPTURE = 17¶

COMPOSITE_SYNTHETIC = 18¶

class c2pa.C2paBuilderIntent¶

Bases: enum.IntEnum

Builder intent enumeration.

CREATE = 0¶

EDIT = 1¶

UPDATE = 2¶

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

Bases: ctypes.Structure

Configuration for a Signer.

class c2pa.Signer(signer_ptr)¶

Bases: ManagedResource

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

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.

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.

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

class c2pa.Settings¶

Bases: ManagedResource

Configuration for C2PA operations.

Settings configure SDK behavior. Use with Context class to apply settings to Reader/Builder operations.

classmethod from_json(json_str)¶

Create Settings from a serialized JSON configuration string.

Parameters:: json_str (str) – JSON string with settings configuration.
Returns:: A new Settings instance with the given configuration.
Return type:: Settings

classmethod from_dict(config)¶

Create Settings from a (JSON-based)dictionary.

Parameters:: config (dict) – Dictionary with settings configuration.
Returns:: A new Settings instance with the given configuration.
Return type:: Settings

set(path, value)¶

Set a configuration value by dot-notation path.

Parameters:

path (str) – Dot-notation path (e.g. “builder.thumbnail.enabled”).
value (str) – The value to set.

Returns:

self, for method chaining.

Return type:

Settings

update(data)¶

Update current configuration from a JSON string or dict. If the updated string overwrite an existing settings value, the last setting value set for that property wins.

Parameters:: data (Union[str, dict]) – A JSON string or dict with configuration to merge.
Returns:: self, for method chaining.
Return type:: Settings

class c2pa.Context(settings=None, signer=None)¶

Bases: ManagedResource, ContextProvider

Per-instance context for C2PA operations.

A Context may carry Settings and a Signer, and is passed to Reader or Builder to control their behavior, thus propagating settings and configurations by passing the Context object (+settings on it) as parameter.

When a Signer is provided, the Signer object is consumed, as it becomes included into the Context, and must not be used directly again after that.

Parameters:

settings (Optional[Settings])
signer (Optional[Signer])

classmethod builder()¶

Return a fluent ContextBuilder.

Return type:: ContextBuilder

classmethod from_json(json_str, signer=None)¶

Create Context from a JSON configuration string.

Parameters:

json_str (str) – JSON string with settings config.
signer (Optional[Signer]) – Optional Signer (consumed if provided).

Returns:

A new Context instance.

Return type:

Context

classmethod from_dict(config, signer=None)¶

Create Context from a dictionary.

Parameters:

config (dict) – Dictionary with settings configuration.
signer (Optional[Signer]) – Optional Signer (consumed if provided).

Returns:

A new Context instance.

Return type:

Context

property has_signer: bool¶

Whether this context was created with a signer.

Return type:: bool

property execution_context¶: Return the raw C2paContext pointer.

class c2pa.ContextBuilder¶

Fluent builder for Context.

Use Context.builder() to create an instance.

with_settings(settings)¶

Attach Settings to the Context being built.

Can be called multiple times, but each call replaces the previous Settings object entirely (the last one wins). To merge multiple configurations, use Settings.update() on a single Settings instance before passing it in.

Parameters:: settings (Settings) – The Settings instance to use.
Returns:: self, for method chaining.
Return type:: ContextBuilder

with_signer(signer)¶

Attach a Signer (will be consumed on build).

Parameters:: signer (Signer)
Return type:: ContextBuilder

build()¶

Build and return a configured Context.

Return type:: Context

class c2pa.ContextProvider¶

Bases: abc.ABC

Abstract base class for types that provide a C2PA context.

Subclass to implement a custom context provider. The built-in Context class is the standard implementation.

property is_valid: bool¶

Abstractmethod:
Return type:: bool

Whether this provider is in a usable state.

Return True when the underlying native context is active and its handle has not been freed or consumed. Return False after the provider has been closed or invalidated.

The ManagedResource base class provides a standard implementation that checks lifecycle state and handle presence.

abstract property execution_context¶

Return the raw native C2paContext pointer.

The returned pointer must be valid for the duration of any FFI call that uses it. Callers should check is_valid before accessing this property.

c2pa.sdk_version()¶

Returns the underlying c2pa-rs/c2pa-c-ffi version string c2pa-rs and c2pa-c-ffi versions are in lockstep release, so the version string is the same for both and we return the shared semantic version number.

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() instead.

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

c2pa.load_settings(settings: str, format: str = 'json') → None¶

c2pa.load_settings(settings: dict) → None

Load C2PA settings into thread-local storage from a string or dict.

Deprecated since version Use: Settings and Context for per-instance configuration instead. Settings and Context will propagate configurations through object instances, no thread-local configurations. Avoid mixing Context APIs and legacy load_settings usage.

Parameters:

settings – The settings string or dict to load
format – The format of the settings string (default: “json”). Ignored when settings is a dict.

Raises:

C2paError – If there was an error loading the settings