ci: Merge remote-tracking branch 'refs/remotes/origin/mathern/context' into mathern/context

Author: tmathern

c2pa-native-version.txt

@@ -1 +1 @@
-c2pa-v0.77.0
+c2pa-v0.77.1

docs/native-resources-management.md

@@ -54,14 +54,13 @@ classDiagram
     ManagedResource <|-- Signer
 
     ContextProvider <|-- Context
-    ContextProvider <|-- Settings
 ```
 
-`Context` and `Settings` inherit from both `ManagedResource` and `ContextProvider` (Python supports multiple inheritance). `ContextProvider` is an ABC that requires two properties: `is_valid` and `execution_context`. The `is_valid` implementation lives on `ManagedResource`, so `Context` and `Settings` satisfy the `ContextProvider` contract without duplicating the property.
+`Context` inherits from both `ManagedResource` and `ContextProvider` (Python supports multiple inheritance). `Settings` inherits from `ManagedResource` only. `ContextProvider` is an ABC that requires two properties: `is_valid` and `execution_context`. The `is_valid` implementation lives on `ManagedResource`, so `Context` satisfies that part of the `ContextProvider` contract without duplicating the property.
 
 ## Guarantees provided by ManagedResource
 
-`ManagedResource` provides the following guarantees. Subclasses and callers can rely on them. These guarantees invariants must be maintained when subclassing the `ManagedResource` class in new implementation/new native resources handlers.
+`ManagedResource` provides the following guarantees. Subclasses and callers can rely on them. These invariants must be maintained when subclassing the `ManagedResource` class in new implementation/new native resources handlers.
 
 | Guarantee | Description |
 | --------- | ----------- |
@@ -280,7 +279,7 @@ The reason is that ownership runs in the opposite direction. A `Reader` or `Buil
 To wrap a new native resource, inherit from `ManagedResource` and follow these rules:
 
 ```python
-class MyResource(ManagedResource):
+class NativeResource(ManagedResource):
     def __init__(self, arg):
         super().__init__()
 
@@ -304,8 +303,14 @@ class MyResource(ManagedResource):
 
     def _release(self):
         # 4. Clean up class-specific resources.
-        #    Never let this method raise. Use try/except with
-        #    logging if needed.
+        #    Never let this method raise. Must be idempotent.
+        #
+        #    Consider defining a simple lifecycle for native resources
+        #    so _release() can check whether they are releasable
+        #    before attempting cleanup. The if-guard below
+        #    verifies the stream exists and has not
+        #    already been released. The try/except is a fallback
+        #    that silences unexpected errors from .close().
         if self._my_stream:
             try:
                 self._my_stream.close()
@@ -327,7 +332,7 @@ class MyResource(ManagedResource):
 
 - If `_lifecycle_state = ACTIVE` is set before the FFI call and the call fails, cleanup will try to free a null or invalid pointer. Activation should happen only after a valid handle exists.
 
-- If `_release()` raises, the exception is silently swallowed by `_cleanup_resources()`. It will not be visible unless logs are checked. Wrap risky operations in try/except.
+- If `_release()` raises, the exception is silently swallowed by `_cleanup_resources()`. It will not be visible unless logs are checked. Define a lifecycle for managed resources so `_release()` can check whether they need releasing. Wrap the actual release call in try/except as a fallback for unexpected failures.
 
 - `_release()` can be called more than once (via `close()` then `__del__`, or multiple `close()` calls). Make sure it handles being called on an already-cleaned-up object. Setting attributes to `None` after closing them is the standard pattern.
 

docs/usage.md

@@ -318,6 +318,27 @@ ctx = Context.builder().with_settings(settings).build()
 ctx = Context.builder().build()
 ```
 
+You can call `with_settings()` multiple times. This is useful when different code paths each need to configure settings before the context is built. Each call replaces the previous `Settings` object entirely (the last one wins):
+
+```py
+# Only settings_b is used, settings_a is replaced
+ctx = (
+    Context.builder()
+    .with_settings(settings_a)
+    .with_settings(settings_b)
+    .build()
+)
+```
+
+To merge multiple configurations into one, use `Settings.update()` on a single `Settings` object, and then pass the built Settings object to the context:
+
+```py
+settings = Settings.from_dict({"builder": {"thumbnail": {"enabled": False}}})
+settings.update({"verify": {"remote_manifest_fetch": True}})
+
+ctx = Context.builder().with_settings(settings).build()
+```
+
 ### Context with a Signer
 
 When a `Signer` is passed to `Context`, the `Signer` object is consumed and must not be reused directly. The `Context` takes ownership of the underlying native signer. This allows signing without passing an explicit signer to `Builder.sign()`.
@@ -353,16 +374,47 @@ manifest_bytes = builder.sign(explicit_signer, "image/jpeg", source, dest)
 
 ### ContextProvider (abstract base class)
 
-`ContextProvider` is an abstract base class (ABC) that allows third-party implementations of custom context providers. Any class that implements the `is_valid` and `execution_context` properties satisfies the interface and can be passed to `Reader` or `Builder` as `context`.
+`ContextProvider` is an abstract base class (ABC) that defines the interface `Reader` and `Builder` use to access a context. It requires two properties:
+
+- `is_valid` (bool): Whether the provider is in a usable state. `Reader` and `Builder` check this before every operation.
+- `execution_context`: The raw native context pointer (`C2paContext` handle). `Reader` and `Builder` pass this to the native library for FFI calls.
+
+The built-in `Context` class is the standard implementation to provide context:
 
 ```py
 from c2pa import ContextProvider, Context
 
-# The built-in Context satisfies ContextProvider
 ctx = Context()
 assert isinstance(ctx, ContextProvider)
 ```
 
+Any class can become a `ContextProvider` by inheriting from `ContextProvider` and implementing both properties. The two properties can live on any object through multiple inheritance, but a dedicated context class (as done in the SDK with `Context`) is preferred because it handles native memory management, lifecycle states, and signer ownership.
+
+In practice, `execution_context` must return a pointer that the native C2PA library understands, so custom providers will likely wrap a compatible native resource, rather than constructing native pointers independently:
+
+```py
+from c2pa import ContextProvider, Context, Settings
+
+class MyContextProvider(ContextProvider):
+    """Custom provider that wraps a Context with application-specific logic."""
+
+    def __init__(self, config: dict):
+        self._ctx = Context(settings=Settings.from_dict(config))
+
+    @property
+    def is_valid(self) -> bool:
+        return self._ctx.is_valid
+
+    @property
+    def execution_context(self):
+        return self._ctx.execution_context
+
+    def close(self):
+        self._ctx.close()
+```
+
+`Settings` is not a `ContextProvider`. It inherits from `ManagedResource` only and cannot be passed directly as the `context` parameter to `Reader` or `Builder`.
+
 ### Migrating from load_settings
 
 The `load_settings()` function that set settings in a thread-local fashion is deprecated.

src/c2pa/c2pa.py

@@ -52,6 +52,7 @@
     'c2pa_reader_from_context',
     'c2pa_reader_with_stream',
     'c2pa_reader_with_fragment',
+    'c2pa_reader_with_manifest_data_and_stream',
     'c2pa_reader_is_embedded',
     'c2pa_reader_remote_url',
     'c2pa_reader_supported_mime_types',
@@ -102,7 +103,7 @@ def _validate_library_exports(lib):
     This validation is crucial for several security and reliability reasons:
 
     1. Security:
-       - Prevents loading of lmibraries that might be missing critical functions
+       - Prevents loading of libraries that might be missing critical functions
        - Ensures the library has expected functionality before code execution
        - Helps detect tampered or incomplete libraries
 
@@ -708,6 +709,13 @@ def _setup_function(func, argtypes, restype=None):
      ctypes.POINTER(C2paStream)],
     ctypes.POINTER(C2paReader)
 )
+_setup_function(
+    _lib.c2pa_reader_with_manifest_data_and_stream,
+    [ctypes.POINTER(C2paReader), ctypes.c_char_p,
+     ctypes.POINTER(C2paStream),
+     ctypes.POINTER(ctypes.c_ubyte), ctypes.c_size_t],
+    ctypes.POINTER(C2paReader),
+)
 _setup_function(
     _lib.c2pa_reader_with_fragment,
     [ctypes.POINTER(C2paReader), ctypes.c_char_p,
@@ -1028,30 +1036,34 @@ def _check_ffi_operation_result(result, fallback_msg, *, check=lambda r: not r):
     return result
 
 
-def _to_utf8_bytes(data, error_context="input") -> bytes:
+def _to_utf8_bytes(data: Union[str, dict], error_context: str = "input") -> bytes:
     """Convert a string or dict to UTF-8 bytes.
 
     If data is a dict, it is serialized to JSON first.
 
     Args:
-        data: String or dict to encode
-        error_context: Description for error messages
+        data: String or dict to encode.
+        error_context: Description for error messages.
 
     Returns:
-        UTF-8 encoded bytes
+        UTF-8 encoded bytes.
 
     Raises:
-        C2paError.Json: If dict serialization fails
-        C2paError.Encoding: If UTF-8 encoding fails
+        C2paError.Json: If dict serialization fails.
+        C2paError.Encoding: If UTF-8 encoding fails or data is not a supported type.
     """
     if isinstance(data, dict):
         try:
             data = json.dumps(data)
         except (TypeError, ValueError) as e:
             raise C2paError.Json(f"Failed to serialize {error_context}: {e}")
+    if not isinstance(data, str):
+        raise C2paError.Encoding(
+            f"Expected str or dict for {error_context}, got {type(data).__name__}"
+        )
     try:
         return data.encode('utf-8')
-    except (UnicodeError, AttributeError) as e:
+    except UnicodeError as e:
         raise C2paError.Encoding(f"Invalid UTF-8 in {error_context}: {e}")
 
 
@@ -1375,11 +1387,29 @@ class ContextProvider(ABC):
 
     @property
     @abstractmethod
-    def is_valid(self) -> bool: ...
+    def is_valid(self) -> 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.
+        """
+        ...
 
     @property
     @abstractmethod
-    def execution_context(self): ...
+    def execution_context(self):
+        """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.
+        """
+        ...
 
 
 class Settings(ManagedResource):
@@ -1453,6 +1483,8 @@ def update(
         self, data: Union[str, dict],
     ) -> 'Settings':
         """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.
 
         Args:
             data: A JSON string or dict with configuration to merge.
@@ -1493,7 +1525,19 @@ def __init__(self):
     def with_settings(
         self, settings: 'Settings',
     ) -> 'ContextBuilder':
-        """Attach Settings to the Context being built."""
+        """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.
+
+        Args:
+            settings: The Settings instance to use.
+
+        Returns:
+            self, for method chaining.
+        """
         self._settings = settings
         return self
 
@@ -2244,6 +2288,7 @@ def __init__(
         if context is not None:
             self._init_from_context(
                 context, format_or_path, stream,
+                manifest_data,
             )
             return
 
@@ -2334,7 +2379,7 @@ def _init_from_file(self, path, format_bytes,
                 Reader._ERROR_MESSAGES['io_error'].format(str(e)))
 
     def _init_from_context(self, context, format_or_path,
-                           stream):
+                           stream, manifest_data=None):
         """Initialize Reader from a Context object implementing
         the ContextProvider interface/abstract base class.
         """
@@ -2365,7 +2410,7 @@ def _init_from_context(self, context, format_or_path,
             self._own_stream = Stream(stream)
 
         try:
-            # Create base reader from context
+            # Create reader from context
             reader_ptr = _lib.c2pa_reader_from_context(
                 context.execution_context,
             )
@@ -2375,13 +2420,35 @@ def _init_from_context(self, context, format_or_path,
                 ].format("Unknown error")
             )
 
-            # Consume-and-return: reader_ptr is consumed,
-            # new_ptr is the valid pointer going forward
-            new_ptr = _lib.c2pa_reader_with_stream(
-                reader_ptr, format_bytes,
-                self._own_stream._stream,
-            )
-            # reader_ptr has been invalidated(consumed)
+            if manifest_data is not None:
+                if not isinstance(manifest_data, bytes):
+                    raise TypeError(
+                        Reader._ERROR_MESSAGES[
+                            'manifest_error'])
+                manifest_array = (
+                    ctypes.c_ubyte *
+                    len(manifest_data))(
+                    *manifest_data)
+                # Consume current reader,
+                # with manifest data and stream (C FFI pattern),
+                # to create a new one (switch out)
+                new_ptr = (
+                    _lib.c2pa_reader_with_manifest_data_and_stream(
+                        reader_ptr,
+                        format_bytes,
+                        self._own_stream._stream,
+                        manifest_array,
+                        len(manifest_data),
+                    )
+                )
+                # reader_ptr has been invalidated(consumed)
+            else:
+                # Consume reader with stream
+                new_ptr = _lib.c2pa_reader_with_stream(
+                    reader_ptr, format_bytes,
+                    self._own_stream._stream,
+                )
+                # reader_ptr has been invalidated(consumed)
 
             _check_ffi_operation_result(new_ptr,
                 Reader._ERROR_MESSAGES[