EricRollei-AAA_Metadata_System/documentation/ReadMe Docs/API_Reference.md

API Reference

This document provides a comprehensive API reference for the Metadata System for ComfyUI.

Table of Contents

• MetadataService
• Handlers
  • BaseHandler
  • EmbeddedMetadataHandler
  • XMPSidecarHandler
  • TxtFileHandler
  • DatabaseHandler
• Utilities
  • FormatHandler
  • NamespaceManager
  • ErrorRecovery
  • XMLTools
  • WorkflowMetadataProcessor

MetadataService

The main interface for all metadata operations.

Constructor

MetadataService(debug=False, human_readable_text=True)

• debug (bool): Whether to enable debug logging
• human_readable_text (bool): Whether to use human-readable text format

Methods

write_metadata

write_metadata(filepath, metadata, targets=None) -> Dict[str, bool]

Writes metadata to specified targets.

• filepath (str): Path to the image file
• metadata (dict): Metadata to write
• targets (list, optional): List of targets ('embedded', 'xmp', 'txt', 'db')
• Returns: Dictionary mapping targets to success status

read_metadata

read_metadata(filepath, source='embedded', fallback=True) -> Dict[str, Any]

Reads metadata from specified source.

• filepath (str): Path to the image file
• source (str): Source to read from ('embedded', 'xmp', 'txt', 'db')
• fallback (bool): Whether to try other sources if primary fails
• Returns: Metadata dictionary

merge_metadata

merge_metadata(filepath, metadata, targets=None) -> Dict[str, bool]

Merges new metadata with existing metadata and writes the result.

• filepath (str): Path to the image file
• metadata (dict): New metadata to merge
• targets (list, optional): List of targets to update
• Returns: Dictionary mapping targets to success status

set_resource_identifier

set_resource_identifier(resource_uri) -> None

Sets resource identifier for all handlers.

• resource_uri (str): Resource identifier for XMP

set_text_format

set_text_format(human_readable) -> None

Sets the text output format.

• human_readable (bool): Whether to use human-readable format

get_handler_for_format

get_handler_for_format(filepath) -> Tuple[str, BaseHandler]

Gets appropriate handler for file format.

• filepath (str): Path to the file
• Returns: Tuple of (handler_type, handler)

cleanup

cleanup() -> None

Cleans up resources used by handlers.

Handlers

BaseHandler

Abstract base class for all handlers.

Constructor

BaseHandler(debug=False)

• debug (bool): Whether to enable debug logging

Methods

write_metadata

write_metadata(filepath, metadata) -> bool

Abstract method to write metadata to a file.

• filepath (str): Path to the file
• metadata (dict): Metadata to write
• Returns: Success status

read_metadata

read_metadata(filepath) -> Dict[str, Any]

Abstract method to read metadata from a file.

• filepath (str): Path to the file
• Returns: Metadata dictionary

log

log(message, level="INFO", error=None) -> None

Logs a message with appropriate level.

• message (str): The message to log
• level (str): Log level (INFO, DEBUG, WARNING, ERROR)
• error (Exception, optional): Optional exception to include in log

get_timestamp

get_timestamp() -> str

Gets current timestamp in ISO 8601 format.

• Returns: Timestamp string

cleanup

cleanup() -> None

Cleans up any resources used by the handler.

_safely_execute

_safely_execute(operation_name, callback, *args, **kwargs) -> Any

Executes operation with proper locking and error handling.

• operation_name (str): Name of the operation for logging
• callback (callable): Function to execute
• *args, **kwargs: Arguments to pass to the callback
• Returns: Result from the callback or None on error

EmbeddedMetadataHandler

Handler for embedded metadata in image files.

Constructor

EmbeddedMetadataHandler(debug=False)

• debug (bool): Whether to enable debug logging

Methods

write_metadata

write_metadata(filepath, metadata) -> bool

Writes metadata to image file.

• filepath (str): Path to the image file
• metadata (dict): Metadata to write
• Returns: Success status

read_metadata

read_metadata(filepath) -> Dict[str, Any]

Reads metadata from image file.

• filepath (str): Path to the image file
• Returns: Metadata dictionary

set_resource_identifier

set_resource_identifier(about_uri) -> None

Sets the resource identifier for XMP metadata.

• about_uri (str): The resource URI to use

XMPSidecarHandler

Handler for XMP sidecar files.

Constructor

XMPSidecarHandler(debug=False)

• debug (bool): Whether to enable debug logging

Methods

write_metadata

write_metadata(filepath, metadata) -> bool

Writes metadata to XMP sidecar file.

• filepath (str): Path to the original file
• metadata (dict): Metadata to write
• Returns: Success status

read_metadata

read_metadata(filepath) -> Dict[str, Any]

Reads metadata from XMP sidecar file.

• filepath (str): Path to the original file
• Returns: Metadata dictionary

set_resource_identifier

set_resource_identifier(about_uri) -> None

Sets the resource identifier for XMP metadata.

• about_uri (str): The resource URI to use

TxtFileHandler

Handler for text file metadata.

Constructor

TxtFileHandler(debug=False, human_readable=False)

• debug (bool): Whether to enable debug logging
• human_readable (bool): Whether to use human-readable format by default

Methods

write_metadata

write_metadata(filepath, metadata) -> bool

Writes metadata to text file using appropriate format.

• filepath (str): Path to the original file
• metadata (dict): Metadata to write
• Returns: Success status

read_metadata

read_metadata(filepath) -> Dict[str, Any]

Reads metadata from text file.

• filepath (str): Path to the original file
• Returns: Metadata dictionary

append_metadata

append_metadata(filepath, metadata) -> bool

Appends new metadata to existing text file.

• filepath (str): Path to the original file
• metadata (dict): Metadata to append
• Returns: Success status

write_formatted_text

write_formatted_text(filepath, metadata) -> bool

Writes metadata to text file with markdown-style formatting.

• filepath (str): Path to the original file
• metadata (dict): Metadata to write
• Returns: Success status

write_human_readable_text

write_human_readable_text(filepath, metadata) -> bool

Writes metadata to text file in human-readable format.

• filepath (str): Path to the original file
• metadata (dict): Metadata to write
• Returns: Success status

set_output_format

set_output_format(human_readable) -> None

Sets the output format.

• human_readable (bool): Whether to use human-readable format

DatabaseHandler

Handler for database storage of metadata.

Constructor

DatabaseHandler(debug=False, db_path=None)

• debug (bool): Whether to enable debug logging
• db_path (str, optional): Path to the database file

Methods

write_metadata

write_metadata(filepath, metadata) -> bool

Writes metadata to database.

• filepath (str): Path to the file
• metadata (dict): Metadata to write
• Returns: Success status

read_metadata

read_metadata(filepath) -> Dict[str, Any]

Reads metadata from database.

• filepath (str): Path to the file
• Returns: Metadata dictionary

search_images

search_images(query) -> List[Dict[str, Any]]

Searches images based on query criteria.

• query (dict): Dictionary of search criteria
• Returns: List of matching image records

batch_operation

batch_operation(operation, filepaths, data=None) -> Dict[str, bool]

Performs batch operation on multiple files.

• operation (str): Operation type ('read', 'write', 'delete')
• filepaths (list): List of file paths
• data (dict, optional): Data for write operation
• Returns: Status for each file

Utilities

FormatHandler

Utility for detecting file formats and capabilities.

Methods

get_file_info

@staticmethod
get_file_info(filepath) -> Dict[str, Any]

Gets format information for a file.

• filepath (str): Path to the file
• Returns: Dictionary with format information

NamespaceManager

Manages XMP namespaces.

Attributes

• NAMESPACES (dict): Dictionary mapping namespace prefixes to URIs

Methods

register_with_pyexiv2

@staticmethod
register_with_pyexiv2(debug=False) -> bool

Registers namespaces with PyExiv2.

• debug (bool): Whether to enable debug logging
• Returns: Success status

create_exiftool_config

@staticmethod
create_exiftool_config() -> str

Creates ExifTool configuration file.

• Returns: Path to configuration file

ErrorRecovery

Provides recovery strategies for errors.

Methods

recover_write_error

@staticmethod
recover_write_error(handler, context) -> bool

Recovers from write error.

• handler (BaseHandler): Handler that encountered the error
• context (dict): Error context
• Returns: Success status

recover_read_error

@staticmethod
recover_read_error(handler, context) -> Dict[str, Any]

Recovers from read error.

• handler (BaseHandler): Handler that encountered the error
• context (dict): Error context
• Returns: Recovered metadata or empty dictionary

XMLTools

Utilities for XML handling.

Methods

xmp_to_dict

@staticmethod
xmp_to_dict(xmp_content) -> Dict[str, Any]

Parses XMP content to dictionary.

• xmp_content (str): XMP content
• Returns: Dictionary representation

indent_xml

@staticmethod
indent_xml(elem, level=0) -> None

Adds proper indentation to XML for readability.

• elem (Element): XML element
• level (int): Indentation level

is_rdf_container

@staticmethod
is_rdf_container(key) -> Optional[str]

Determines if a key should use a specific RDF container.

• key (str): Key name
• Returns: Container type ('Bag', 'Seq', 'Alt') or None

create_xmp_wrapper

@staticmethod
create_xmp_wrapper() -> Tuple[str, str]

Creates start and end wrappers for XMP packet.

• Returns: Tuple of (start_wrapper, end_wrapper)

WorkflowMetadataProcessor

Processes ComfyUI workflow data.

Constructor

WorkflowMetadataProcessor(debug=False)

• debug (bool): Whether to enable debug logging

Methods

extract_workflow_metadata

extract_workflow_metadata(workflow_data) -> Dict[str, Any]

Extracts metadata from workflow data.

• workflow_data (dict): Workflow data
• Returns: Extracted metadata

extract_generation_parameters

extract_generation_parameters(workflow_data) -> Dict[str, Any]

Extracts generation parameters from workflow data.

• workflow_data (dict): Workflow data
• Returns: Generation parameters

get_model_info

get_model_info(workflow_data) -> Dict[str, Any]

Gets model information from workflow data.

• workflow_data (dict): Workflow data
• Returns: Model information

get_sampler_info

get_sampler_info(workflow_data) -> Dict[str, Any]

Gets sampler information from workflow data.

• workflow_data (dict): Workflow data
• Returns: Sampler information