Source code for vcon.extensions.base

"""
Base classes for vCon extensions.

This module provides the foundational classes and interfaces for implementing
vCon extensions according to the IETF draft specifications.
"""

from abc import ABC, abstractmethod
from enum import Enum
from typing import Dict, List, Any, Optional, Union
from datetime import datetime
import logging

logger = logging.getLogger(__name__)


[docs]class ExtensionType(Enum): """Types of vCon extensions.""" COMPATIBLE = "compatible" # Safe to ignore, no breaking changes INCOMPATIBLE = "incompatible" # Must be supported, breaking changes EXPERIMENTAL = "experimental" # Development/testing only
[docs]class ValidationResult: """Result of extension validation.""" def __init__(self, is_valid: bool, errors: List[str] = None, warnings: List[str] = None): self.is_valid = is_valid self.errors = errors or [] self.warnings = warnings or []
[docs] def add_error(self, error: str): """Add a validation error.""" self.errors.append(error) self.is_valid = False
[docs] def add_warning(self, warning: str): """Add a validation warning.""" self.warnings.append(warning)
def __bool__(self): return self.is_valid
[docs]class ProcessingResult: """Result of extension processing.""" def __init__(self, success: bool, data: Dict[str, Any] = None, errors: List[str] = None): self.success = success self.data = data or {} self.errors = errors or []
[docs] def add_error(self, error: str): """Add a processing error.""" self.errors.append(error) self.success = False
[docs]class ExtensionValidator(ABC): """Base class for extension validators."""
[docs] @abstractmethod def validate_attachment(self, attachment: Dict[str, Any]) -> ValidationResult: """Validate an extension attachment.""" pass
[docs] @abstractmethod def validate_extension_usage(self, vcon_dict: Dict[str, Any]) -> ValidationResult: """Validate extension usage in a vCon.""" pass
[docs]class ExtensionProcessor(ABC): """Base class for extension processors."""
[docs] @abstractmethod def process(self, vcon_dict: Dict[str, Any]) -> ProcessingResult: """Process extension data in a vCon.""" pass
[docs] @abstractmethod def can_process(self, extension_name: str) -> bool: """Check if this processor can handle the given extension.""" pass
[docs]class ExtensionInfo: """Information about a vCon extension.""" def __init__( self, name: str, extension_type: ExtensionType, version: str, description: str, attachment_types: List[str] = None, validator: Optional[ExtensionValidator] = None, processor: Optional[ExtensionProcessor] = None ): self.name = name self.type = extension_type self.version = version self.description = description self.attachment_types = attachment_types or [] self.validator = validator self.processor = processor
[docs] def to_dict(self) -> Dict[str, Any]: """Convert to dictionary representation.""" return { "name": self.name, "type": self.type.value, "version": self.version, "description": self.description, "attachment_types": self.attachment_types }
[docs]class ExtensionAttachment: """Base class for extension attachments.""" def __init__( self, attachment_purpose: str, body: Dict[str, Any], start: Optional[Union[str, datetime]] = None, party: Optional[int] = None, dialog: Optional[int] = None, encoding: str = "json", meta: Optional[Dict[str, Any]] = None ): self.purpose = attachment_purpose self.body = body self.start = self._normalize_timestamp(start) if start else None self.party = party self.dialog = dialog self.encoding = encoding self.meta = meta or {} def _normalize_timestamp(self, timestamp: Union[str, datetime]) -> str: """Normalize timestamp to ISO 8601 string.""" if isinstance(timestamp, datetime): return timestamp.isoformat() return timestamp
[docs] def to_dict(self) -> Dict[str, Any]: """Convert to dictionary representation.""" result = { "purpose": self.purpose, "body": self.body, "encoding": self.encoding } if self.start: result["start"] = self.start if self.party is not None: result["party"] = self.party if self.dialog is not None: result["dialog"] = self.dialog if self.meta: result["meta"] = self.meta return result
[docs] @classmethod def from_dict(cls, data: Dict[str, Any]) -> 'ExtensionAttachment': """Create from dictionary representation.""" from ..body import decode_body return cls( attachment_purpose=data["purpose"], body=decode_body(data), start=data.get("start"), party=data.get("party"), dialog=data.get("dialog"), encoding=data.get("encoding", "json"), meta=data.get("meta") )