Source code for vcon.vcon

from __future__ import annotations

import copy
from dateutil import parser
import json
from typing import Optional, List, Dict, Union, Any, Tuple
import hashlib
import time
import uuid6
from datetime import datetime
from datetime import timezone
from pydash import get as _get
import base64
from joserfc import jwk, jws
from joserfc.errors import BadSignatureError
from cryptography.hazmat.primitives.asymmetric import rsa
from cryptography.hazmat.primitives import serialization
import requests
import logging
import warnings
from .party import Party
from .dialog import Dialog, b64url_encode
from .body import decode_body
from .session import Session
from .event import Event
from .migration import (
    MigrationError,
    MigrationReport,
    migrate_0_4_0_to_0_5_0 as _migrate_0_4_0_to_0_5_0,
)
from .validation import encrypted_form, signed_form, signed_payload, validate_vcon_dict

# Set up logger
logger = logging.getLogger(__name__)

# Import extension framework
try:
    from .extensions.registry import get_extension_registry
    from .extensions.base import ValidationResult
    EXTENSIONS_AVAILABLE = True
except ImportError:
    EXTENSIONS_AVAILABLE = False
    logger.warning("Extensions not available - install required dependencies")

# Define constants for property handling modes
PROPERTY_HANDLING_DEFAULT = "default"  # Keep non-standard properties
PROPERTY_HANDLING_STRICT = "strict"    # Remove non-standard properties
PROPERTY_HANDLING_META = "meta"        # Move non-standard properties to meta

# Define allowed properties for each object type
_ALLOWED_VCON_PROPERTIES = {
    "uuid", "vcon", "created_at", "updated_at", "redacted_from",
    "group", "parties", "dialog", "attachments", "analysis",
    "signatures", "payload", "meta", "subject", "amended_from",
    "extensions", "critical", "sessions", "events", "redacted_strings"
}

_ALLOWED_SESSION_PROPERTIES = {
    "start", "duration", "parties", "originator", "session_id",
    "sessions", "dialog"
}

_ALLOWED_EVENT_PROPERTIES = {
    "type", "time", "sessions", "party", "dialog", "channel",
    "contributors", "button", "transferee", "transfer_target",
    "consultation", "target_session"
}

_ALLOWED_PARTY_PROPERTIES = {
    "type", "name", "contact", "meta", "external_id", "party_id",
    "tel", "stir", "mailto", "validation", "gmlpos", "civicaddress",
    "uuid", "role", "contact_list", "sip", "did", "jCard", "timezone",
    "org", "dept"
}

_ALLOWED_DIALOG_PROPERTIES = {
    "type", "start", "parties", "duration", "mediatype", "filename",
    "body", "encoding", "url", "content_hash", "disposition",
    "campaign", "interaction", "skill", "meta", "metadata",
    "signaling", "resolution", "frame_rate",
    "codec", "bitrate", "thumbnail", "streaming", "video",
    "session_id", "application", "message_id", "redacted_segments"
}

_ALLOWED_ATTACHMENT_PROPERTIES = {
    "purpose", "body", "encoding", "start", "party", "dialog", "session",
    "mediatype", "filename", "url", "content_hash"
}

_ALLOWED_ANALYSIS_PROPERTIES = {
    "type", "dialog", "sessions", "attachment", "analysis", "vendor",
    "product", "body", "encoding", "schema", "mediatype", "filename",
    "url", "content_hash", "meta"
}

# Configure logging
logger = logging.getLogger(__name__)

_LAST_V8_TIMESTAMP = None

#: JWS algorithms accepted for signing and verifying. "none" is excluded:
#: core-05 section 6.2.2, "The alg parameter MUST NOT have the value none".
PERMITTED_JWS_ALGORITHMS = (
    "RS256", "RS384", "RS512",
    "PS256", "PS384", "PS512",
    "ES256", "ES384", "ES512",
    "EdDSA",
)


def _jwk_key_type(alg: str) -> str:
    """The JWK key type an algorithm needs (RS/PS: RSA, ES: EC, EdDSA: OKP)."""
    if alg.startswith(("RS", "PS")):
        return "RSA"
    if alg.startswith("ES"):
        return "EC"
    return "OKP"


def _import_jwk(key: Any, alg: str, private: bool):
    """Import a cryptography key object or PEM bytes/str as a joserfc key."""
    if hasattr(key, "private_bytes") and private:
        key = key.private_bytes(
            encoding=serialization.Encoding.PEM,
            format=serialization.PrivateFormat.PKCS8,
            encryption_algorithm=serialization.NoEncryption(),
        )
    elif hasattr(key, "public_bytes") and not private:
        key = key.public_bytes(
            encoding=serialization.Encoding.PEM,
            format=serialization.PublicFormat.SubjectPublicKeyInfo,
        )
    return jwk.import_key(key, _jwk_key_type(alg))


[docs]class AlgorithmNotPermittedError(ValueError): """A JWS used ``alg`` "none" (forbidden by core-05) or an unsupported algorithm."""
[docs]class Attachment: """ A class representing an attachment in a vCon. An attachment consists of a purpose, body content, and an encoding format. The encoding format must be one of the supported formats: base64url, json, or none. Attributes: purpose (str): The purpose of the attachment body (Any): The content of the attachment encoding (str): The encoding format used for the body """ VALID_ENCODINGS = ["base64url", "json", "none"]
[docs] def __init__( self, purpose: str, body: Any = None, encoding: str = "none", mediatype: Optional[str] = None, filename: Optional[str] = None, url: Optional[str] = None, content_hash: Optional[str] = None, start: Optional[str] = None, party: Optional[int] = None, dialog: Optional[int] = None, session: Optional[Union[int, List[int]]] = None, ) -> None: """ Initialize an Attachment object. Under core-05 (section 4.6) an attachment needs ``party`` and at least one of ``dialog`` or ``session``. ``party`` defaults to 0. Neither ``dialog`` nor ``session`` is defaulted here, because the right index depends on the vCon; ``Vcon.add_attachment()`` defaults it only when the vCon has exactly one Session. Args: purpose: The purpose of the attachment body: The content of the attachment encoding: The encoding format used for the body (default: "none") Raises: ValueError: If the specified encoding is not supported """ if encoding not in self.VALID_ENCODINGS: logger.error(f"Invalid encoding attempted: {encoding}") raise ValueError(f"Invalid encoding: {encoding}. Must be one of {self.VALID_ENCODINGS}") # Fill in defaults required by the WG JSON schema (every attachment # requires start and party; inline content requires mediatype). # party defaults to 0 (the add_tag() convention). dialog is no longer # defaulted: core-05 allows session in its place. if mediatype is None and encoding == "json": mediatype = "application/json" self.purpose = purpose self.body = body self.encoding = encoding self.mediatype = mediatype self.filename = filename self.url = url self.content_hash = content_hash self.start = start self.party = party if party is not None else 0 self.dialog = dialog self.session = session logger.debug(f"Created new attachment of purpose {purpose} with {encoding} encoding")
[docs] def to_dict(self) -> Dict[str, Any]: """ Convert the attachment to a dictionary representation. Returns: Dict containing the attachment's purpose, body, and encoding """ attachment_dict = { "purpose": self.purpose, "body": self.body, "encoding": self.encoding, "mediatype": self.mediatype, "filename": self.filename, "url": self.url, "content_hash": self.content_hash, "start": self.start, "party": self.party, "dialog": self.dialog, "session": self.session, } return {k: v for k, v in attachment_dict.items() if v is not None}
[docs] @classmethod def from_image(cls, image_path: str, purpose: str = "image") -> 'Attachment': """ Create an Attachment from an image file. Args: image_path: Path to the image file type: The type of the attachment (default: "image") Returns: An Attachment object containing the image Raises: ValueError: If the image format is not supported FileNotFoundError: If the image file cannot be found """ import os import mimetypes # Check if file exists if not os.path.exists(image_path): raise FileNotFoundError(f"Image file not found: {image_path}") # Detect mimetype mimetype, _ = mimetypes.guess_type(image_path) if not mimetype or mimetype not in ["image/jpeg", "image/tiff", "application/pdf"]: raise ValueError(f"Unsupported image format: {mimetype}. Must be JPEG, TIFF, or PDF.") # Read image data with open(image_path, 'rb') as f: image_data = f.read() filename = os.path.basename(image_path) # Create and return attachment return cls( purpose=purpose, body=b64url_encode(image_data), encoding="base64url", mediatype=mimetype, filename=filename, )
[docs]class Vcon: """ A class representing a vCon (Virtual Conversation) object according to the vCon specification. A vCon is a standardized format for representing conversations and related metadata. It includes information about participants (parties), dialog content, attachments, and analysis data. The vCon format supports features such as: - Unique identification via UUID - The ``vcon`` syntax version (written as ``"0.5.0"``) - Timestamps for creation and updates - Party information with contact details (tel, name, sip, did, jCard, timezone) - Dialog content with media types and session information - Attachments for ancillary documents - Analysis data for conversation insights - Digital signatures and encryption - Extensions and critical for extensibility - Civic address information for location data - Sessions (``sessions``) grouping dialog and events, and Events (``events``) for joins, drops, holds, key presses and transfers New in vCon 0.5.0 (draft-ietf-vcon-vcon-core-05): - ``sessions`` and ``events`` arrays; ``Session`` and ``Event`` classes - ``redacted_from`` and ``amended_from`` replace ``redacted`` and ``amended`` - Attachments need ``party`` and ``dialog`` or ``session`` - ``extensions`` MUST list every extension in use; ``alg: "none"`` is rejected - Dialog ``parties`` are contributors only; empty ``{}`` Dialog placeholders - 0.4.0 input is migrated on load (see ``migrate_0_4_0_to_0_5_0``) Attributes: vcon_dict (Dict): The underlying dictionary containing all vCon data property_handling (str): How non-standard properties are handled """
[docs] def __init__( self, vcon_dict: Dict[str, Any] = None, property_handling: str = PROPERTY_HANDLING_DEFAULT, migrate_legacy: bool = True, strict_migration: bool = False, ) -> None: """ Initialize a Vcon object from a dictionary. A dict that declares ``"vcon": "0.4.0"`` is migrated to 0.5.0 here, using ``migrate_0_4_0_to_0_5_0``. The report is kept in ``self.migration_report``. A signed vCon whose payload is 0.4.0 is NOT migrated on load, because migrating drops the signature: verify it, then call ``Vcon.migrate_0_4_0_to_0_5_0()``. An unmigrated 0.4.0 dict (signed, or ``migrate_legacy=False``) is kept as is; ``property_handling`` is not applied to it. A dict with any other (or no) ``vcon`` value is taken as is. Args: vcon_dict: A dictionary representing a vCon. Defaults to an empty dict. property_handling: How to handle non-standard properties. Options are: - "default": Keep non-standard properties (default) - "strict": Remove non-standard properties - "meta": Move non-standard properties to meta object migrate_legacy: Migrate 0.4.0 input to 0.5.0 (default True). When False the 0.4.0 dict is kept untouched and ``is_valid()`` will report it as not 0.5.0. strict_migration: Passed to the migration as ``strict``; raises ``MigrationError`` when a required field has no source. Example: >>> vcon = Vcon({"uuid": "123", "custom_field": "value"}) >>> strict_vcon = Vcon({"uuid": "123", "custom_field": "value"}, property_handling="strict") >>> meta_vcon = Vcon({"uuid": "123", "custom_field": "value"}, property_handling="meta") """ logger.debug("Initializing new Vcon object") # Store property handling mode for later use self.property_handling = property_handling # Initialize with empty dict if none provided if vcon_dict is None: vcon_dict = {} #: MigrationReport when the input was migrated from 0.4.0, else None. self.migration_report: Optional[MigrationReport] = None legacy = self._is_legacy_0_4_0(vcon_dict) signed_legacy = legacy and "vcon" not in vcon_dict if signed_legacy: # Migrating rewrites the payload, which drops the signature. Doing that # implicitly would make verify() impossible and, on a load-and-save # path, overwrite a signed record with an unsigned one. Keep it signed; # migrate explicitly with Vcon.migrate_0_4_0_to_0_5_0() after verifying. logger.warning( "Signed 0.4.0 vCon loaded unmigrated; verify it, then call " "Vcon.migrate_0_4_0_to_0_5_0() (the result must be signed again)" ) elif migrate_legacy and legacy: migrated, self.migration_report = _migrate_0_4_0_to_0_5_0( vcon_dict, strict=strict_migration ) logger.warning( "Migrated vCon %s from 0.4.0 to 0.5.0 on load (%s)", migrated.get("uuid"), self.migration_report.summary(), ) vcon_dict = migrated if legacy and self.migration_report is None: # An unmigrated 0.4.0 (or signed 0.4.0) dict is kept as is: the 0.5.0 # allow-lists of property_handling would strip its legacy parameters # (party_history, originator, redacted, ...), which is silent data loss. if self.property_handling != PROPERTY_HANDLING_DEFAULT: logger.warning( "0.4.0 vCon kept unmigrated: property_handling=%r not applied", self.property_handling ) self.vcon_dict = json.loads(json.dumps(vcon_dict)) return if signed_form(vcon_dict) or encrypted_form(vcon_dict): # A JWS or JWE container (core-05 sections 6.2, 6.3) is kept exactly # as given: adding uuid, created_at or empty arrays would change # (and for JWS, invalidate) the document. is_valid() checks it. self.vcon_dict = json.loads(json.dumps(vcon_dict)) return # Version field is now optional - no version management required # Handle created_at if vcon_dict.get("created_at"): if isinstance(vcon_dict["created_at"], datetime): vcon_dict["created_at"] = vcon_dict["created_at"].isoformat() logger.debug("Converted datetime created_at to ISO format") # A string is kept exactly as written: rewriting it would change # the document (and break a signature over it). An unparseable # value is left for is_valid() to report. else: vcon_dict["created_at"] = datetime.now(timezone.utc).isoformat() logger.debug("Set default created_at timestamp") # Ensure attachments array exists if "attachments" not in vcon_dict: vcon_dict["attachments"] = [] logger.debug("Initialized empty attachments array") # Process the vcon itself for non-standard properties processed_vcon = self._process_properties(vcon_dict, _ALLOWED_VCON_PROPERTIES) # Process embedded objects based on property_handling if "parties" in processed_vcon: processed_vcon["parties"] = [ self._process_properties(party, _ALLOWED_PARTY_PROPERTIES) for party in processed_vcon["parties"] ] if "dialog" in processed_vcon: processed_vcon["dialog"] = [ self._process_properties(dialog, _ALLOWED_DIALOG_PROPERTIES) for dialog in processed_vcon["dialog"] ] if "sessions" in processed_vcon: processed_vcon["sessions"] = [ self._process_properties(sess, _ALLOWED_SESSION_PROPERTIES) for sess in processed_vcon["sessions"] ] if "events" in processed_vcon: processed_vcon["events"] = [ self._process_properties(event, _ALLOWED_EVENT_PROPERTIES) for event in processed_vcon["events"] ] if "attachments" in processed_vcon: processed_vcon["attachments"] = [ self._process_properties(attachment, _ALLOWED_ATTACHMENT_PROPERTIES) for attachment in processed_vcon["attachments"] ] if "analysis" in processed_vcon: processed_vcon["analysis"] = [ self._process_properties(analysis, _ALLOWED_ANALYSIS_PROPERTIES) for analysis in processed_vcon["analysis"] ] self.vcon_dict = json.loads(json.dumps(processed_vcon)) logger.info(f"Vcon object initialized with UUID: {processed_vcon.get('uuid', 'not set')}")
@staticmethod def _is_legacy_0_4_0(vcon_dict: Any) -> bool: """True if the dict declares syntax 0.4.0, directly or in a signed payload.""" if not isinstance(vcon_dict, dict): return False if vcon_dict.get("vcon") == "0.4.0": return True if "vcon" not in vcon_dict and isinstance(vcon_dict.get("payload"), str) and "signatures" in vcon_dict: try: raw = vcon_dict["payload"] payload = json.loads(base64.urlsafe_b64decode(raw + "=" * (-len(raw) % 4))) return isinstance(payload, dict) and payload.get("vcon") == "0.4.0" except Exception: return False return False
[docs] @classmethod def migrate_0_4_0_to_0_5_0( cls, source: Union[str, Dict[str, Any]], strict: bool = False, property_handling: str = PROPERTY_HANDLING_DEFAULT, ) -> "Vcon": """ Explicitly migrate a 0.4.0 vCon (dict or JSON string) and return a Vcon. The migration report is available as ``vcon.migration_report``. Unlike the implicit migration on load, this also accepts input with no ``vcon`` parameter. See :func:`vcon.migration.migrate_0_4_0_to_0_5_0`. """ migrated, report = _migrate_0_4_0_to_0_5_0(source, strict=strict) obj = cls(migrated, property_handling=property_handling, migrate_legacy=False) obj.migration_report = report return obj
[docs] def set_created_at(self, created_at: Union[str, datetime]) -> None: """ Set the created_at field in the vCon. Args: created_at (Union[str, datetime]): The timestamp to set, either as a string in ISO format or as a datetime object. """ if isinstance(created_at, datetime): self.vcon_dict["created_at"] = created_at.isoformat() else: self.vcon_dict["created_at"] = created_at
[docs] def set_updated_at(self, timestamp: Union[str, datetime]) -> None: """ Set the updated_at timestamp. Args: timestamp: The timestamp to set, either as ISO 8601 string or datetime object Example: >>> vcon = Vcon.build_new() >>> vcon.set_updated_at(datetime.now(timezone.utc)) >>> vcon.set_updated_at("2025-02-18T12:00:00Z") """ if isinstance(timestamp, datetime): self.vcon_dict["updated_at"] = timestamp.isoformat() elif isinstance(timestamp, str): # Validate the timestamp format parser.parse(timestamp) # This will raise ValueError if invalid self.vcon_dict["updated_at"] = timestamp else: raise ValueError("Timestamp must be either a datetime object or ISO 8601 string")
def _process_properties(self, obj_dict: Dict[str, Any], allowed_properties: set) -> Dict[str, Any]: """ Process an object dictionary based on the property handling mode. Args: obj_dict: The dictionary to process allowed_properties: Set of allowed property names Returns: The processed dictionary """ if not isinstance(obj_dict, dict): return obj_dict result = {} non_standard = {} # Separate standard and non-standard properties for k, v in obj_dict.items(): if k in allowed_properties: result[k] = v else: non_standard[k] = v # Handle non-standard properties based on mode if self.property_handling == PROPERTY_HANDLING_STRICT: # Ignore non-standard properties pass elif self.property_handling == PROPERTY_HANDLING_META: # Move non-standard properties to meta if non_standard: result.setdefault("meta", {}).update(non_standard) else: # Default: Keep non-standard properties result.update(non_standard) return result
[docs] @classmethod def build_from_json( cls, json_string: str, property_handling: str = PROPERTY_HANDLING_DEFAULT, migrate_legacy: bool = True, strict_migration: bool = False, ) -> "Vcon": """ Initialize a Vcon object from a JSON string. This method parses a JSON string representation of a vCon and creates a new Vcon object from it. Args: json_string: A JSON string representing a vCon property_handling: How to handle non-standard properties. Returns: A new Vcon object initialized with the parsed JSON data Raises: json.JSONDecodeError: If the JSON string is invalid Example: >>> json_str = '{"uuid": "123"}' >>> vcon = Vcon.build_from_json(json_str) """ logger.debug("Building Vcon from JSON string") try: vcon_dict = json.loads(json_string) logger.info("Successfully parsed JSON string") return cls( vcon_dict, property_handling=property_handling, migrate_legacy=migrate_legacy, strict_migration=strict_migration, ) except json.JSONDecodeError as e: logger.error(f"Failed to parse JSON string: {str(e)}") raise
[docs] @classmethod def build_new( cls, created_at: Union[str, datetime] = None, property_handling: str = PROPERTY_HANDLING_DEFAULT, ) -> "Vcon": """ Initialize a new Vcon object with default values. This method creates a new vCon with a generated UUID and initialized with empty arrays for groups, parties, dialog, attachments, and analysis. Args: created_at (Union[str, datetime], optional): The timestamp to set for creation, either as a string in ISO format or as a datetime object. Defaults to current time. property_handling: How to handle non-standard properties. Returns: A new Vcon object with default values Example: >>> vcon = Vcon.build_new() >>> print(vcon.uuid) # Prints a new UUID8 """ logger.debug("Building new Vcon with default values") uuid = cls.uuid8_domain_name("strolid.com") logger.debug(f"Generated UUID8: {uuid}") vcon_dict = { "vcon": "0.5.0", "uuid": uuid, "parties": [], "dialog": [], "attachments": [], "analysis": [], } # Create the Vcon object vcon = cls( vcon_dict, property_handling=property_handling, ) # Set created_at if provided, otherwise it will use the default from __init__ if created_at is not None: vcon.set_created_at(created_at) logger.info("Created new Vcon with default structure") return vcon
@property def tags(self) -> Optional[Dict[str, Any]]: """ Get the tags attachment from the vCon. Returns: The tags attachment dictionary if it exists, None otherwise Example: >>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> vcon.add_tag("category", "meeting") >>> tags = vcon.tags >>> print(tags["body"]) # Prints ["category:meeting"] """ logger.debug("Retrieving tags attachment") tags = self.find_attachment_by_purpose("tags") if tags: logger.debug("Found tags attachment") else: logger.debug("No tags attachment found") return tags
[docs] def get_tag(self, tag_name: str) -> Optional[str]: """ Get the value of a specific tag by name. Args: tag_name: The name of the tag to retrieve Returns: The value of the tag if found, None otherwise Example: >>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> vcon.add_tag("category", "meeting") >>> value = vcon.get_tag("category") >>> print(value) # Prints "meeting" """ logger.debug(f"Retrieving value for tag: {tag_name}") tags_attachment = self.find_attachment_by_purpose("tags") if not tags_attachment: logger.debug("No tags attachment found") return None # Accept both the -04 shape (body is already the list) and legacy # vCons where the tags body was written as a JSON-encoded string. tags = decode_body(tags_attachment) if not isinstance(tags, list): logger.debug("Tags attachment body is not a list") return None tag = next( (t for t in tags if isinstance(t, str) and t.startswith(f"{tag_name}:")), None ) if not tag: logger.debug(f"Tag {tag_name} not found") return None tag_value = tag.split(":")[1] logger.debug(f"Found value for tag {tag_name}: {tag_value}") return tag_value
def _resolve_attachment_scope( self, dialog: Optional[int] = None, session: Optional[Union[int, List[int]]] = None, whole_vcon: bool = False, ) -> Dict[str, Any]: """ Work out the ``dialog`` / ``session`` scope for a new attachment. Core-05 section 4.6 needs at least one of the two. The caller's values are used as given. With neither given, the scope is defaulted only when it is unambiguous: the vCon has exactly one Session, which is then the whole conversation. Otherwise ``ValueError`` is raised, because picking a Session (or adding a placeholder one) would invent the scope. ``whole_vcon=True`` is for library metadata that describes the whole vCon (``add_tag``): every Session is listed, and an empty placeholder Session is added when there is none. """ scope: Dict[str, Any] = {} if dialog is not None: scope["dialog"] = dialog if session is not None: scope["session"] = session if scope: return scope sessions = self.vcon_dict.get("sessions") or [] if whole_vcon: if not sessions: self.vcon_dict.setdefault("sessions", []).append({}) sessions = self.vcon_dict["sessions"] logger.warning("Added an empty placeholder Session to scope the tags attachment") return {"session": list(range(len(sessions)))} if len(sessions) == 1: return {"session": 0} raise ValueError( "An attachment needs dialog or session (core-05 section 4.6). The vCon has " f"{len(sessions)} Sessions, so no default can be chosen; pass dialog= or session= " "(add a Session first with add_session() if the vCon has none)." )
[docs] def add_tag(self, tag_name: str, tag_value: str, party: Optional[int] = None) -> None: """ Add a tag to the vCon. This method adds a tag with the specified name and value to the vCon's tags attachment. If no tags attachment exists, it creates one. Core-05 requires the attachment's ``party`` to be a valid party index (the party that adds the tags). It defaults to 0. On a vCon with no parties this still writes party 0 but warns (DeprecationWarning), because the result fails ``is_valid()``; from vcon 1.1 it will raise. Args: tag_name: The name of the tag tag_value: The value to associate with the tag party: Party index for a new tags attachment (default 0) Raises: ValueError: If ``party`` is given (or the vCon has parties) and it is not a valid party index Example: >>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Acme Corp")) >>> vcon.add_tag("category", "meeting") >>> vcon.add_tag("priority", "high") """ logger.debug(f"Adding tag {tag_name}:{tag_value}") tags_attachment = self.find_attachment_by_purpose("tags") if not tags_attachment: logger.debug("Creating new tags attachment") n_parties = len(self.vcon_dict.get("parties") or []) if party is None and n_parties == 0: # Kept for compatibility: the result fails is_valid() (party 0 # does not exist). Raises ValueError from vcon 1.1. warnings.warn( "add_tag() on a vCon with no parties writes party 0, which does not exist, " "so the vCon fails is_valid(). Add the party that adds the tags first. " "This will raise ValueError in vcon 1.1.", DeprecationWarning, stacklevel=2, ) party = 0 else: party = 0 if party is None else party if not (isinstance(party, int) and not isinstance(party, bool) and 0 <= party < n_parties): raise ValueError( f"add_tag() needs a valid party index for the tags attachment (core-05 section 4.6); " f"got {party!r} but the vCon has {n_parties} parties." ) tags_attachment = { "purpose": "tags", "body": [], "encoding": "json", "mediatype": "application/json", "start": self.vcon_dict.get("created_at"), "party": party, } tags_attachment.update(self._resolve_attachment_scope(whole_vcon=True)) self.vcon_dict.setdefault("attachments", []).append(tags_attachment) else: # Normalize a legacy (pre-0.10.0 / -02 convention) JSON-string # body to the -04 list-valued body in place, preserving # existing tags. current_tags = decode_body(tags_attachment) if not isinstance(current_tags, list): current_tags = [] tags_attachment["body"] = current_tags tags_attachment.setdefault("mediatype", "application/json") tags_attachment.setdefault("start", self.vcon_dict.get("created_at")) tags_attachment["body"].append(f"{tag_name}:{tag_value}") logger.info(f"Added tag {tag_name}:{tag_value}")
[docs] def get_extensions(self) -> List[str]: """ Get the list of extensions used in this vCon. Returns: List of extension names, empty list if none are defined Example: >>> vcon = Vcon.build_new() >>> vcon.add_extension("video") >>> extensions = vcon.get_extensions() >>> print(extensions) # Prints ["video"] """ return self.vcon_dict.get("extensions", [])
[docs] def add_extension(self, extension: str) -> None: """ Add an extension to the vCon. Args: extension: The name of the extension to add Example: >>> vcon = Vcon.build_new() >>> vcon.add_extension("video") >>> vcon.add_extension("encryption") """ if "extensions" not in self.vcon_dict: self.vcon_dict["extensions"] = [] if extension not in self.vcon_dict["extensions"]: self.vcon_dict["extensions"].append(extension) logger.info(f"Added extension: {extension}")
[docs] def remove_extension(self, extension: str) -> None: """ Remove an extension from the vCon. Args: extension: The name of the extension to remove Example: >>> vcon = Vcon.build_new() >>> vcon.add_extension("video") >>> vcon.remove_extension("video") """ if "extensions" in self.vcon_dict and extension in self.vcon_dict["extensions"]: self.vcon_dict["extensions"].remove(extension) logger.info(f"Removed extension: {extension}")
[docs] def get_critical(self) -> List[str]: """ Get the list of critical extensions that must be supported. Returns: List of extension names that must be supported, empty list if none are defined Example: >>> vcon = Vcon.build_new() >>> vcon.add_critical("encryption") >>> critical = vcon.get_critical() >>> print(critical) # Prints ["encryption"] """ return self.vcon_dict.get("critical", [])
[docs] def add_critical(self, extension: str) -> None: """ Add an extension to the critical list. Args: extension: The name of the extension that must be supported Example: >>> vcon = Vcon.build_new() >>> vcon.add_critical("encryption") >>> vcon.add_critical("video") """ if "critical" not in self.vcon_dict: self.vcon_dict["critical"] = [] if extension not in self.vcon_dict["critical"]: self.vcon_dict["critical"].append(extension) logger.info(f"Added critical extension: {extension}")
[docs] def remove_critical(self, extension: str) -> None: """ Remove an extension from the critical list. Args: extension: The name of the extension to remove from critical Example: >>> vcon = Vcon.build_new() >>> vcon.add_critical("encryption") >>> vcon.remove_critical("encryption") """ if "critical" in self.vcon_dict and extension in self.vcon_dict["critical"]: self.vcon_dict["critical"].remove(extension) logger.info(f"Removed critical extension: {extension}")
# Extension-specific methods
[docs] def add_lawful_basis_attachment( self, lawful_basis: str, expiration: str, purpose_grants: list, party_index: Optional[int] = None, dialog_index: Optional[int] = None, session_index: Optional[Union[int, List[int]]] = None, **kwargs ) -> None: """ Add a lawful basis attachment to the vCon. The attachment has ``purpose`` ``"lawful_basis"``. Under core-05 it is scoped with ``party`` plus ``session``: pass ``session_index`` (and ``party_index``, the party that records the basis). The scope is never widened or invented: ``dialog_index`` alone gives a dialog-only scope (a warning is logged, because 0.5.0 scopes a basis to Sessions), and with neither index the only Session is used when the vCon has exactly one; otherwise ``ValueError`` is raised. ``party`` defaults to 0 with a warning. The ``lawful_basis`` extension name is added to ``extensions``. Args: lawful_basis: The lawful basis type (consent, contract, etc.) expiration: ISO 8601 timestamp when the lawful basis expires purpose_grants: List of purpose grant dictionaries party_index: Index of the party that records the basis (default 0) dialog_index: Index of the dialog this applies to (optional) session_index: Session index or list of indices this applies to (optional) **kwargs: Additional lawful basis parameters Example: >>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> vcon.add_lawful_basis_attachment( ... lawful_basis="consent", ... expiration="2026-01-01T00:00:00Z", ... purpose_grants=[ ... {"purpose": "recording", "granted": True, "granted_at": "2025-01-01T00:00:00Z"} ... ] ... ) """ if not EXTENSIONS_AVAILABLE: raise RuntimeError("Extensions not available") try: from .extensions.lawful_basis import LawfulBasisExtension extension = LawfulBasisExtension() attachment = extension.create_lawful_basis_attachment( lawful_basis=lawful_basis, expiration=expiration, purpose_grants=purpose_grants, **kwargs ) # party is required (default 0, add_tag()'s convention); core-05 # also needs dialog or session, and the basis is scoped to Sessions. if party_index is None: logger.warning( "lawful_basis attachment: party_index not given, defaulting to 0; " "it should be the party that records the basis" ) attachment["party"] = party_index if party_index is not None else 0 if session_index is None and dialog_index is not None: logger.warning( "lawful_basis attachment scoped by dialog only; core-05 scopes a basis " "to Sessions, pass session_index" ) attachment.update( self._resolve_attachment_scope(dialog=dialog_index, session=session_index) ) # Fill in mediatype/start, also required by the schema, unless # already set via **kwargs. attachment.setdefault("mediatype", "application/json") attachment.setdefault("start", self.vcon_dict.get("created_at")) self.vcon_dict.setdefault("attachments", []).append(attachment) # Add extension to extensions list if not already present if "lawful_basis" not in self.get_extensions(): self.add_extension("lawful_basis") logger.info("Added lawful basis attachment") except ImportError: raise RuntimeError("Lawful basis extension not available")
[docs] def add_wtf_transcription_attachment( self, transcript: Dict[str, Any], segments: List[Dict[str, Any]], metadata: Dict[str, Any], party_index: Optional[int] = None, dialog_index: Optional[int] = None, session_index: Optional[Union[int, List[int]]] = None, **kwargs ) -> None: """ Add a WTF transcription attachment to the vCon. Deprecated: draft-howe-vcon-wtf-extension stores transcriptions as analysis (section 6.1). Use :meth:`add_wtf_transcription_analysis`. Scoped by ``dialog_index`` and/or ``session_index`` as given; with neither, the only Session when the vCon has exactly one, else ``ValueError`` (see ``add_attachment``). Args: transcript: Transcript information dictionary segments: List of segment dictionaries metadata: Metadata dictionary party_index: Index of the party this applies to (optional) dialog_index: Index of the dialog this applies to (optional) session_index: Session index or list of indices (optional) **kwargs: Additional WTF parameters Example: >>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> vcon.add_wtf_transcription_attachment( ... transcript={"text": "Hello world", "language": "en", "duration": 2.0, "confidence": 0.95}, ... segments=[{"id": 0, "start": 0.0, "end": 2.0, "text": "Hello world", "confidence": 0.95}], ... metadata={"created_at": "2025-01-01T00:00:00Z", "processed_at": "2025-01-01T00:00:01Z", ... "provider": "whisper", "model": "whisper-1"} ... ) """ warnings.warn( "add_wtf_transcription_attachment() is deprecated: draft-howe-vcon-wtf-extension " "stores transcriptions as analysis. Use add_wtf_transcription_analysis().", DeprecationWarning, stacklevel=2, ) if not EXTENSIONS_AVAILABLE: raise RuntimeError("Extensions not available") try: from .extensions.wtf import WTFExtension extension = WTFExtension() attachment = extension.create_wtf_attachment( transcript=transcript, segments=segments, metadata=metadata, **kwargs ) attachment["party"] = party_index if party_index is not None else 0 attachment.update( self._resolve_attachment_scope(dialog=dialog_index, session=session_index) ) # Fill in mediatype/start, also required by the schema, unless # already set via **kwargs. attachment.setdefault("mediatype", "application/json") attachment.setdefault("start", self.vcon_dict.get("created_at")) self.vcon_dict.setdefault("attachments", []).append(attachment) # Add extension to extensions list if not already present if "wtf_transcription" not in self.get_extensions(): self.add_extension("wtf_transcription") logger.info("Added WTF transcription attachment") except ImportError: raise RuntimeError("WTF extension not available")
WTF_SCHEMA_URL = "https://datatracker.ietf.org/doc/html/draft-howe-vcon-wtf-extension"
[docs] def add_wtf_transcription_analysis( self, transcript: Dict[str, Any], segments: List[Dict[str, Any]], metadata: Dict[str, Any], dialog_index: Optional[int] = None, session_index: Optional[Union[int, List[int]]] = None, **kwargs ) -> None: """ Add a WTF transcription as an analysis entry (vs. an attachment). This is the placement draft-howe-vcon-wtf-extension requires (section 6.1: transcription results MUST be stored as analysis). ``add_wtf_transcription_attachment`` writes to attachments[] and is deprecated. Emits the analysis entry defined by draft-howe-vcon-wtf-extension (section 5.3): ``type="wtf_transcription"``, ``vendor`` and ``product`` taken from ``metadata["provider"]`` / ``metadata["model"]``, ``schema`` set to the WTF draft URL, ``encoding="json"``, and ``body`` as the WTF document itself (a JSON value, not a serialized string). Args: transcript: Transcript information dictionary segments: List of segment dictionaries metadata: Metadata dictionary; ``provider`` and ``model`` keys map to ``vendor`` and ``product`` on the analysis entry dialog_index: Index of the dialog this transcription applies to session_index: Session index or indices this transcription applies to **kwargs: Additional WTF parameters (words, speakers, quality, etc.) """ if not EXTENSIONS_AVAILABLE: raise RuntimeError("Extensions not available") try: from .extensions.wtf import WTFExtension extension = WTFExtension() wtf_attachment = extension.create_wtf_attachment( transcript=transcript, segments=segments, metadata=metadata, **kwargs ) wtf_body = wtf_attachment["body"] dialog_ref = [dialog_index] if dialog_index is not None else None self.add_analysis( type="wtf_transcription", dialog=dialog_ref, sessions=session_index, vendor=metadata.get("provider", "unknown"), product=metadata.get("model"), body=wtf_body, encoding="json", schema=self.WTF_SCHEMA_URL, ) if "wtf_transcription" not in self.get_extensions(): self.add_extension("wtf_transcription") logger.info("Added WTF transcription analysis entry") except ImportError: raise RuntimeError("WTF extension not available")
[docs] def find_lawful_basis_attachments(self, party_index: Optional[int] = None) -> List[Dict[str, Any]]: """ Find lawful basis attachments in the vCon. Args: party_index: Filter by party index (optional) Returns: List of lawful basis attachment dictionaries """ attachments = [] for attachment in self.vcon_dict.get("attachments", []): if attachment.get("purpose") == "lawful_basis": if party_index is None or attachment.get("party") == party_index: attachments.append(attachment) return attachments
[docs] def find_wtf_attachments(self, party_index: Optional[int] = None) -> List[Dict[str, Any]]: """ Find WTF transcription attachments in the vCon. Args: party_index: Filter by party index (optional) Returns: List of WTF attachment dictionaries """ attachments = [] for attachment in self.vcon_dict.get("attachments", []): if attachment.get("purpose") == "wtf_transcription": if party_index is None or attachment.get("party") == party_index: attachments.append(attachment) return attachments
[docs] def check_lawful_basis_permission( self, purpose: str, party_index: Optional[int] = None ) -> bool: """ Check if permission is granted for a specific purpose. Args: purpose: The purpose to check permission for party_index: Index of the party to check (optional) Returns: True if permission is granted, False otherwise """ if not EXTENSIONS_AVAILABLE: return False try: from .extensions.lawful_basis import LawfulBasisExtension extension = LawfulBasisExtension() return extension.check_permission(self.vcon_dict, purpose, party_index) except ImportError: return False
[docs] def validate_extensions(self) -> Dict[str, Any]: """ Validate all extensions in the vCon. Returns: Dictionary with validation results for each extension """ if not EXTENSIONS_AVAILABLE: return {"error": "Extensions not available"} try: registry = get_extension_registry() results = {} # Validate each extension for extension_name in self.get_extensions(): result = registry.validate_extension(extension_name, self.vcon_dict) results[extension_name] = { "is_valid": result.is_valid, "errors": result.errors, "warnings": result.warnings } # Validate all attachments attachment_results = [] for attachment in self.vcon_dict.get("attachments", []): result = registry.validate_attachment(attachment) attachment_results.append({ "purpose": attachment.get("purpose"), "is_valid": result.is_valid, "errors": result.errors, "warnings": result.warnings }) results["attachments"] = attachment_results return results except Exception as e: logger.error(f"Error validating extensions: {str(e)}") return {"error": str(e)}
[docs] def process_extensions(self) -> Dict[str, Any]: """ Process all extensions in the vCon. Returns: Dictionary with processing results for each extension """ if not EXTENSIONS_AVAILABLE: return {"error": "Extensions not available"} try: registry = get_extension_registry() return registry.process_extensions(self.vcon_dict) except Exception as e: logger.error(f"Error processing extensions: {str(e)}") return {"error": str(e)}
[docs] @staticmethod def decoded_body(entry: Optional[Dict[str, Any]]) -> Any: """ Return the decoded ``body`` of an attachment, analysis, or dialog entry. Under ``draft-ietf-vcon-vcon-core-04``, a ``"json"``-encoded body is the JSON value itself, not a ``json.dumps`` string. This accepts both that shape and the JSON-string bodies written under -02 conventions (or by this library prior to 0.10.0), so callers don't need to special-case legacy vCons. Args: entry: An attachment, analysis, or dialog dictionary Returns: The decoded body, or None if there is no body Example: >>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> vcon.add_tag("category", "meeting") >>> Vcon.decoded_body(vcon.tags) # ["category:meeting"] """ return decode_body(entry)
[docs] def find_attachment_by_purpose(self, purpose: str) -> Optional[Dict[str, Any]]: """ Find an attachment in the vCon by its purpose. This method searches through the vCon's attachments and returns the first attachment matching the specified type. Args: purpose: The purpose of attachment to find Returns: The matching attachment dictionary if found, None otherwise Example: >>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> vcon.add_attachment("metadata", {"version": "1.0"}) >>> metadata = vcon.find_attachment_by_purpose("metadata") """ logger.debug(f"Searching for attachment of purpose: {purpose}") attachment = next( (a for a in self.vcon_dict.get("attachments") or [] if a.get("purpose") == purpose), None ) if attachment: logger.debug(f"Found attachment of purpose: {purpose}") else: logger.debug(f"No attachment found of purpose: {purpose}") return attachment
[docs] def add_attachment( self, purpose: str, body: Any = None, encoding: str = "none", mediatype: Optional[str] = None, filename: Optional[str] = None, url: Optional[str] = None, content_hash: Optional[str] = None, start: Optional[str] = None, party: Optional[int] = None, dialog: Optional[int] = None, session: Optional[Union[int, List[int]]] = None, ) -> Attachment: """ Add an attachment to the vCon. This method creates a new attachment with the specified type, body, and encoding and adds it to the vCon's attachments list. Core-05 needs ``party`` plus ``dialog`` or ``session``. ``party`` defaults to 0. If neither ``dialog`` nor ``session`` is given, the attachment is scoped to the only Session when the vCon has exactly one; otherwise ``ValueError`` is raised rather than inventing a scope. Args: purpose: The purpose of the attachment body: The content of the attachment encoding: The encoding format for the body (default: "none") mediatype: Optional media type of the attachment filename: Optional file name of the attachment url: Optional URL for external attachments content_hash: Optional content hash for external attachments start: Optional timestamp for the attachment party: Optional party index (default 0) dialog: Optional dialog index session: Optional Session index or list of indices Returns: The created Attachment object Raises: ValueError: If the specified encoding is not supported Example: >>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> attachment = vcon.add_attachment("metadata", {"version": "1.0"}, "json") >>> print(attachment.purpose) # Prints "metadata" """ logger.debug(f"Creating new attachment of purpose {purpose} with {encoding} encoding") # The WG JSON schema requires start on every attachment; default to # this vCon's created_at when the caller doesn't supply one. if start is None: start = self.vcon_dict.get("created_at") if dialog is None and session is None: session = self._resolve_attachment_scope()["session"] attachment = Attachment( purpose=purpose, body=body, encoding=encoding, mediatype=mediatype, filename=filename, url=url, content_hash=content_hash, start=start, party=party, dialog=dialog, session=session, ) attachment_dict = attachment.to_dict() # Process attachment dict according to property handling mode processed_attachment = self._process_properties(attachment_dict, _ALLOWED_ATTACHMENT_PROPERTIES) self.vcon_dict.setdefault("attachments", []).append(processed_attachment) logger.info(f"Added new attachment of purpose {purpose}") return attachment
[docs] def add_image( self, image_path: str, purpose: str = "image", party: Optional[int] = None, dialog: Optional[int] = None, session: Optional[Union[int, List[int]]] = None, ) -> Attachment: """ Add an image attachment to the vCon. This method creates a new attachment with the specified image and adds it to the vCon's attachments list. Args: image_path: Path to the image file purpose: The purpose of the attachment (default: "image") party: Party index (default 0) dialog: Dialog index session: Session index or list of indices. With neither ``dialog`` nor ``session``, the only Session is used when the vCon has exactly one, as in ``add_attachment()``. Returns: The created Attachment object Raises: FileNotFoundError: If the image file cannot be found ValueError: If the image format is not supported, or no ``dialog``/``session`` is given and the vCon does not have exactly one Session Example: >>> vcon = Vcon.build_new() >>> vcon.add_session() >>> attachment = vcon.add_image("document.pdf", "identification") >>> print(attachment.mediatype) # Prints "application/pdf" """ if dialog is None and session is None: session = self._resolve_attachment_scope()["session"] attachment = Attachment.from_image(image_path, purpose) # The WG JSON schema requires start on every attachment; default to # this vCon's created_at. if attachment.start is None: attachment.start = self.vcon_dict.get("created_at") if party is not None: attachment.party = party attachment.dialog = dialog attachment.session = session self.vcon_dict.setdefault("attachments", []).append(attachment.to_dict()) logger.info(f"Added new image attachment of purpose {purpose}") return attachment
[docs] def find_analysis_by_type(self, type: str) -> Optional[Dict[str, Any]]: """ Find an analysis entry in the vCon by its type. This method searches through the vCon's analysis entries and returns the first one matching the specified type. Args: type: The type of analysis to find Returns: The matching analysis dictionary if found, None otherwise Example: >>> vcon = Vcon.build_new() >>> vcon.add_analysis(type="sentiment", dialog=[0], vendor="acme", body={"score": 0.8}) >>> sentiment = vcon.find_analysis_by_type("sentiment") """ logger.debug(f"Searching for analysis of type: {type}") analysis = next( (a for a in self.vcon_dict.get("analysis") or [] if a.get("type") == type), None ) if analysis: logger.debug(f"Found analysis of type: {type}") else: logger.debug(f"No analysis found of type: {type}") return analysis
[docs] def add_analysis( self, *, type: str, vendor: str, body: Union[Dict[str, Any], List[Any], str], dialog: Optional[Union[List[int], int]] = None, sessions: Optional[Union[List[int], int]] = None, attachment: Optional[Union[List[int], int]] = None, analysis: Optional[Union[List[int], int]] = None, encoding: str = "none", mediatype: Optional[str] = None, filename: Optional[str] = None, product: Optional[str] = None, url: Optional[str] = None, content_hash: Optional[str] = None, schema: Optional[Dict[str, Any]] = None, meta: Optional[Dict[str, Any]] = None, **extra, ) -> None: """ Add analysis data to the vCon. This method adds analysis data with the specified parameters to the vCon's analysis list. Analysis data can be associated with one or more dialog entries and includes metadata about the vendor who performed the analysis. Args: type: The type of analysis dialog: Index or list of indices of the associated dialog entries (optional) sessions: Index or list of indices of the Sessions analysed (optional) attachment: Index or list of indices of the attachments analysed (optional) analysis: Index or list of indices of other Analysis Objects used (optional) vendor: The name of the vendor who performed the analysis body: The analysis data encoding: The encoding format of the body (default: "none") mediatype: Optional media type of the analysis content filename: Optional filename for the analysis content product: Optional product name of the vendor url: Optional URL for external analysis content content_hash: Optional content hash for external analysis content schema: Optional schema information about the analysis (default: None) meta: Optional metadata about the analysis (default: None) **extra: Additional key-value pairs to include in the analysis Raises: Exception: If the encoding is invalid or if the body format is invalid for the specified encoding Example: >>> vcon = Vcon.build_new() >>> vcon.add_analysis( ... type="sentiment", ... dialog=[0], ... vendor="acme", ... body={"score": 0.8}, ... encoding="json", ... schema={"version": "1.0"}, ... meta={"confidence": "high"} ... ) """ logger.debug(f"Adding analysis of type {type} from vendor {vendor}") if encoding not in ["json", "none", "base64url"]: logger.error(f"Invalid encoding: {encoding}") raise Exception("Invalid encoding") if encoding == "json" and isinstance(body, str): try: json.loads(body) except Exception as e: logger.error(f"Invalid JSON body: {str(e)}") raise Exception("Invalid JSON body: ", e) if encoding == "base64url" and isinstance(body, str): try: base64.urlsafe_b64decode(body) except Exception as e: logger.error(f"Invalid base64url body: {str(e)}") raise Exception("Invalid base64url body: ", e) # Build the analysis object analysis_obj: Dict[str, Any] = {"type": type} if dialog is not None: analysis_obj["dialog"] = dialog if sessions is not None: analysis_obj["sessions"] = sessions if attachment is not None: analysis_obj["attachment"] = attachment if analysis is not None: analysis_obj["analysis"] = analysis analysis_obj.update({ "vendor": vendor, "body": body, "encoding": encoding, }) analysis = analysis_obj if mediatype is not None: analysis["mediatype"] = mediatype if filename is not None: analysis["filename"] = filename if product is not None: analysis["product"] = product if url is not None: analysis["url"] = url if content_hash is not None: analysis["content_hash"] = content_hash # Add schema if provided if schema is not None: analysis["schema"] = schema # Add meta if provided if meta is not None: analysis["meta"] = meta # Add any additional parameters analysis.update(extra) # Process analysis dict according to property handling mode processed_analysis = self._process_properties(analysis, _ALLOWED_ANALYSIS_PROPERTIES) self.vcon_dict.setdefault("analysis", []).append(processed_analysis) logger.info(f"Added analysis of type {type} from vendor {vendor}")
[docs] def add_party(self, party: Party) -> None: """ Add a party to the vCon. This method adds a party object to the vCon's parties list. A party represents a participant in the conversation. Args: party: The Party object to add Example: >>> vcon = Vcon.build_new() >>> party = Party(type="person", name="John Doe") >>> vcon.add_party(party) """ # Process party dict according to property handling mode party_dict = party.to_dict() processed_party = self._process_properties(party_dict, _ALLOWED_PARTY_PROPERTIES) self.vcon_dict.setdefault("parties", []).append(processed_party) logger.info("Added party")
[docs] def find_party_index(self, by: str, val: str) -> Optional[int]: """ Find the index of a party in the vCon's parties list. This method searches through the parties list and returns the index of the first party that matches the specified key-value pair. Args: by: The key to search by (e.g., "name", "type") val: The value to match Returns: The index of the matching party if found, None otherwise Example: >>> vcon = Vcon.build_new() >>> vcon.add_party(Party(type="person", name="John Doe")) >>> index = vcon.find_party_index("name", "John Doe") >>> print(index) # Prints 0 """ logger.debug(f"Searching for party with {by}={val}") index = next( ( ind for ind, party in enumerate(self.vcon_dict.get("parties") or []) if _get(party, by) == val ), None, ) if index is not None: logger.debug(f"Found party at index {index}") else: logger.debug(f"No party found with {by}={val}") return index
[docs] def find_dialog(self, by: str, val: str) -> Optional[Dialog]: """ Find a dialog entry in the vCon by a key-value pair. This method searches through the dialog list and returns the first dialog entry that matches the specified key-value pair, converted to a Dialog object. Args: by: The key to search by (e.g., "type", "start") val: The value to match Returns: A Dialog object if found, None otherwise Example: >>> vcon = Vcon.build_new() >>> dialog = Dialog(type="text", start="2023-01-01T00:00:00Z", parties=[0]) >>> vcon.add_dialog(dialog) >>> found = vcon.find_dialog("type", "text") >>> print(found.type) # Prints "text" """ logger.debug(f"Searching for dialog with {by}={val}") dialog = next( (dialog for dialog in self.vcon_dict.get("dialog") or [] if dialog and _get(dialog, by) == val), None, ) if dialog: logger.debug(f"Found dialog with {by}={val}") return Dialog(**dialog) logger.debug(f"No dialog found with {by}={val}") return None
[docs] def find_dialogs_by_type(self, type: str) -> List[Dict[str, Any]]: """ Find all dialog entries in the vCon by type. This method searches through the dialog list and returns all dialog entries matching the specified type. Args: type: The type of dialogs to find Returns: A list of matching dialog dictionaries Example: >>> vcon = Vcon.build_new() >>> incomplete = vcon.find_dialogs_by_type("incomplete") """ return [dialog for dialog in self.vcon_dict.get("dialog") or [] if dialog.get("type") == type]
[docs] def add_dialog(self, dialog: Dialog, session: Optional[int] = None) -> int: """ Add a dialog entry to the vCon. This method adds a Dialog object to the vCon's dialog list. A dialog entry represents a segment of the conversation with its associated metadata. Use ``Dialog.placeholder()`` to add an empty Dialog Object (``{}``) that holds an array position. Args: dialog: The Dialog object to add session: Optional index of an existing Session; the new Dialog's index is appended to that Session's ``dialog`` list. Core-05 requires at least one Session when the vCon has Dialogs, so add Sessions with ``add_session()``. Returns: The index of the new Dialog in the ``dialog`` array. Example: >>> vcon = Vcon.build_new() >>> dialog = Dialog(type="text", start="2023-01-01T00:00:00Z", parties=[0]) >>> index = vcon.add_dialog(dialog) """ logger.debug(f"Adding dialog: {dialog.to_dict()}") # Process dialog dict according to property handling mode dialog_dict = dialog.to_dict() processed_dialog = self._process_properties(dialog_dict, _ALLOWED_DIALOG_PROPERTIES) if session is not None: sessions = self.vcon_dict.get("sessions", []) if not isinstance(session, int) or not 0 <= session < len(sessions): raise ValueError(f"Invalid session index: {session}") self.vcon_dict.setdefault("dialog", []).append(processed_dialog) index = len(self.vcon_dict["dialog"]) - 1 if session is not None: self.vcon_dict["sessions"][session].setdefault("dialog", []).append(index) logger.info(f"Added dialog of type {getattr(dialog, 'type', 'placeholder')}") return index
[docs] def add_transfer_dialog(self, *args: Any, **kwargs: Any) -> None: """Removed: core-05 has no transfer Dialog type. Raises ``NotImplementedError`` with the replacement: a transfer is one or two transfer Events (``blind-transfer``, ``consultation-start`` plus ``consultative-transfer``, or ``transfer-abandoned``) added with ``add_event(Event(...))``, whose ``sessions``/``consultation``/ ``target_session`` reference Sessions for the calls involved. """ raise NotImplementedError( "add_transfer_dialog() was removed in vCon 0.5.0: record a transfer as transfer " "Events with add_event(Event(type='blind-transfer', ...)); see vcon.event" )
[docs] def add_session(self, session: Union[Session, Dict[str, Any], None] = None) -> int: """ Add a Session Object and return its index in the ``sessions`` array. With no argument an empty placeholder Session (``{}``) is added, which core-05 permits. Example: >>> vcon = Vcon.build_new() >>> s = vcon.add_session(Session(start="2023-01-01T00:00:00Z", parties=[0, 1])) """ if session is None: session_dict: Dict[str, Any] = {} elif isinstance(session, Session): session_dict = session.to_dict() else: session_dict = dict(session) processed = self._process_properties(session_dict, _ALLOWED_SESSION_PROPERTIES) self.vcon_dict.setdefault("sessions", []).append(processed) logger.info("Added session") return len(self.vcon_dict["sessions"]) - 1
[docs] def add_event(self, event: Union[Event, Dict[str, Any]]) -> int: """ Add an Event Object and return its index in the ``events`` array. An ``Event`` is checked against the per-type parameter table when it is built; a plain dict is checked by ``is_valid()``. Example: >>> vcon = Vcon.build_new() >>> vcon.add_event(Event(type="join", time="2023-01-01T00:00:00Z", sessions=0, party=0)) """ event_dict = event.to_dict() if isinstance(event, Event) else dict(event) processed = self._process_properties(event_dict, _ALLOWED_EVENT_PROPERTIES) self.vcon_dict.setdefault("events", []).append(processed) logger.info(f"Added event of type {processed.get('type')}") return len(self.vcon_dict["events"]) - 1
[docs] def add_incomplete_dialog( self, start: Union[str, datetime], disposition: str, details: Optional[Dict[str, Any]] = None, parties: List[int] = None, metadata: Optional[Dict[str, Any]] = None, session: Optional[int] = None, ) -> int: """ Add an incomplete dialog entry to the vCon. This method creates a dialog entry of type "incomplete" for conversations that failed to be set up. Under core-05 an incomplete Dialog has no content (no body, mediatype, filename, encoding, url or content_hash), and its ``parties`` is the party that attempted the call, the originator. ``details`` is kept under ``metadata["details"]``. Args: start: When the attempt occurred (ISO 8601 string or datetime) disposition: Reason for the incomplete conversation (for example "no-answer") details: Additional details about the failure (optional) parties: The party (or parties) that attempted the conversation (optional) metadata: Additional metadata (optional) session: Optional Session index to add the Dialog to Returns: The index of the new Dialog. Example: >>> vcon = Vcon.build_new() >>> vcon.add_incomplete_dialog( ... start="2023-01-20T14:00:00Z", ... disposition="no-answer", ... details={"ringDuration": 45000}, ... parties=[0] ... ) """ if parties is None: parties = [] meta = dict(metadata) if metadata else {} if details: meta["details"] = details dialog = Dialog( type="incomplete", start=start, parties=parties, disposition=disposition, metadata=meta or None, ) return self.add_dialog(dialog, session=session)
[docs] def to_json(self) -> str: """ Serialize the vCon to a JSON string. This method converts the entire vCon object to a JSON string representation, which can be used for storage or transmission. Returns: A JSON string representation of the vCon Example: >>> vcon = Vcon.build_new() >>> json_str = vcon.to_json() >>> print(type(json_str)) # Prints "<class 'str'>" """ logger.debug("Converting vCon to JSON string") tmp_vcon_dict = copy.copy(self.vcon_dict) json_str = json.dumps(tmp_vcon_dict) logger.debug("Successfully converted vCon to JSON string") return json_str
[docs] def to_dict(self) -> Dict[str, Any]: """ Convert the vCon to a dictionary. This method returns a dictionary representation of the vCon object, which can be used for direct manipulation or inspection. Returns: A dictionary representation of the vCon Example: >>> vcon = Vcon.build_new() >>> vcon_dict = vcon.to_dict() >>> print(vcon_dict["vcon"]) # Prints "0.5.0" """ logger.debug("Converting vCon to dictionary") return json.loads(self.to_json())
[docs] def dumps(self) -> str: """ Alias for to_json(). This method is an alias for to_json() and converts the vCon object to a JSON string representation. Returns: A JSON string representation of the vCon Example: >>> vcon = Vcon.build_new() >>> json_str = vcon.dumps() >>> print(type(json_str)) # Prints "<class 'str'>" """ logger.debug("Dumping vCon to JSON string") return self.to_json()
@property def parties(self) -> List[Dict[str, Any]]: """ Get the list of parties in the vCon. Returns: A list of party dictionaries representing all participants in the conversation. These are mutable references to the internal data structure, allowing in-place modifications. Example: >>> vcon = Vcon.build_new() >>> vcon.add_party(Party(type="person", name="John Doe")) >>> parties = vcon.parties >>> print(parties[0]["name"]) # Prints "John Doe" >>> parties[0]["name"] = "Jane Doe" # In-place modification works >>> print(vcon.parties[0]["name"]) # Prints "Jane Doe" """ return self.vcon_dict.get("parties", [])
[docs] def get_party_objects(self) -> List[Party]: """ Get the list of parties as Party objects. This method creates Party objects from the underlying dictionary data. Use this when you need Party objects instead of raw dictionaries. Returns: A list of Party objects representing all participants in the conversation Example: >>> vcon = Vcon.build_new() >>> vcon.add_party(Party(type="person", name="John Doe")) >>> party_objects = vcon.get_party_objects() >>> print(party_objects[0].name) # Prints "John Doe" """ return [Party(**party) for party in self.vcon_dict.get("parties", [])]
@property def dialog(self) -> List[Dict[str, Any]]: """ Get the list of dialog entries in the vCon. Returns: A list of dialog dictionaries representing the conversation content. These are mutable references to the internal data structure, allowing in-place modifications. Example: >>> vcon = Vcon.build_new() >>> vcon.add_dialog(Dialog(type="text", start="2023-01-01T00:00:00Z", parties=[0])) >>> dialog = vcon.dialog >>> print(dialog[0]["type"]) # Prints "text" >>> dialog[0]["body"] = "Modified content" # In-place modification works >>> print(vcon.dialog[0]["body"]) # Prints "Modified content" """ return self.vcon_dict.get("dialog", []) @property def attachments(self) -> List[Dict[str, Any]]: """ Get the list of attachments in the vCon. Returns: A list of attachment dictionaries Example: >>> vcon = Vcon.build_new() >>> vcon.add_party(Party(name="Alice")) >>> vcon.add_session() >>> vcon.add_attachment("metadata", {"version": "1.0"}) >>> attachments = vcon.attachments >>> print(attachments[0]["purpose"]) # Prints "metadata" """ return self.vcon_dict.get("attachments", []) @property def analysis(self) -> List[Dict[str, Any]]: """ Get the list of analysis entries in the vCon. Returns: A list of analysis dictionaries Example: >>> vcon = Vcon.build_new() >>> vcon.add_analysis(type="sentiment", dialog=[0], vendor="acme", body={"score": 0.8}) >>> analysis = vcon.analysis >>> print(analysis[0]["type"]) # Prints "sentiment" """ return self.vcon_dict.get("analysis", []) @property def uuid(self) -> str: return self.vcon_dict["uuid"] @property def vcon(self) -> Optional[str]: return self.vcon_dict.get("vcon") @property def subject(self) -> Optional[str]: return self.vcon_dict.get("subject") @property def created_at(self): return self.vcon_dict.get("created_at") @property def updated_at(self): return self.vcon_dict.get("updated_at") @property def sessions(self) -> List[Dict[str, Any]]: """The ``sessions`` array (Session Objects).""" return self.vcon_dict.get("sessions", []) @property def events(self) -> List[Dict[str, Any]]: """The ``events`` array (Event Objects).""" return self.vcon_dict.get("events", []) @property def redacted(self): """Deprecated 0.4.0 name; returns ``redacted_from``.""" warnings.warn("Vcon.redacted is deprecated; use Vcon.redacted_from (core-05)", DeprecationWarning, stacklevel=2) return self.redacted_from @property def amended(self): """Deprecated 0.4.0 name; returns ``amended_from``.""" warnings.warn("Vcon.amended is deprecated; use Vcon.amended_from (core-05)", DeprecationWarning, stacklevel=2) return self.amended_from @property def redacted_from(self): return self.vcon_dict.get("redacted_from") @property def amended_from(self): return self.vcon_dict.get("amended_from") @property def redacted_strings(self) -> List[Dict[str, Any]]: return self.vcon_dict.get("redacted_strings", []) @property def group(self): return self.vcon_dict.get("group", []) @property def meta(self): return self.vcon_dict.get("meta", {})
[docs] @staticmethod def uuid8_domain_name(domain_name: str) -> str: sha1_hasher = hashlib.sha1() sha1_hasher.update(bytes(domain_name, "utf-8")) dn_sha1 = sha1_hasher.digest() hash_upper_64 = dn_sha1[0:8] int64 = int.from_bytes(hash_upper_64, byteorder="big") uuid8_domain = Vcon.uuid8_time(int64) return uuid8_domain
[docs] @staticmethod def uuid8_time(custom_c_62_bits: int) -> str: global _LAST_V8_TIMESTAMP ns = time.time_ns() if _LAST_V8_TIMESTAMP is not None and ns <= _LAST_V8_TIMESTAMP: ns = _LAST_V8_TIMESTAMP + 1 _LAST_V8_TIMESTAMP = ns timestamp_ms, timestamp_ns = divmod(ns, 10**6) subsec = uuid6._subsec_encode(timestamp_ns) subsec_a = subsec >> 8 uuid_int = (timestamp_ms & 0xFFFFFFFFFFFF) << 80 uuid_int |= subsec_a << 64 uuid_int |= custom_c_62_bits uuid_str = str(uuid6.UUID(int=uuid_int, version=7)) assert uuid_str[14] == "7" uuid_str = uuid_str[:14] + "8" + uuid_str[15:] return uuid_str
[docs] def sign(self, private_key: Union[rsa.RSAPrivateKey, bytes], alg: str = "RS256") -> None: """ Sign the vCon using JWS (JSON Web Signature). This method signs the vCon using the provided private key, adding the signature information to the vCon. The signature can later be verified using the corresponding public key. Args: private_key: The RSA private key or its PEM representation alg: JWS algorithm (default "RS256", the value core-05 says SHOULD be used). "none" is rejected (6.2.2). Raises: AlgorithmNotPermittedError: If ``alg`` is "none" (any case) or is not a permitted algorithm. Exception: If there is an error during the signing process Example: >>> from cryptography.hazmat.primitives.asymmetric import rsa >>> private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048) >>> vcon = Vcon.build_new() >>> vcon.sign(private_key) """ logger.debug("Signing vCon with JWS") self._check_jws_alg(alg) try: payload = self.to_json() protected = {"alg": alg, "typ": "JWS"} key = _import_jwk(private_key, alg, private=True) signed_str = jws.serialize_compact(protected, payload, key, algorithms=[alg]) header, payload, signature = signed_str.split(".") self.vcon_dict["signatures"] = [{"protected": header, "signature": signature}] self.vcon_dict["payload"] = payload logger.info("Successfully signed vCon") except Exception as e: logger.error(f"Failed to sign vCon: {str(e)}") raise
@staticmethod def _check_jws_alg(alg: Any) -> None: if not isinstance(alg, str) or alg.strip().lower() == "none": raise AlgorithmNotPermittedError( 'JWS alg "none" is not permitted (core-05 section 6.2.2)' ) if alg not in PERMITTED_JWS_ALGORITHMS: raise AlgorithmNotPermittedError( f"JWS alg {alg!r} is not supported; use one of {PERMITTED_JWS_ALGORITHMS}" )
[docs] def verify(self, public_key: Union[rsa.RSAPublicKey, bytes]) -> bool: """ Verify the JWS signature of the vCon. This method verifies the vCon's signature using the provided public key. The vCon must have been previously signed using the corresponding private key. Args: public_key: The RSA public key or its PEM representation Returns: True if the signature is valid, False otherwise Raises: ValueError: If the vCon is not signed AlgorithmNotPermittedError: If the signature declares ``alg`` "none" (in the protected header or the signature's header), which core-05 forbids. Verification is refused rather than skipped. Example: >>> private_key, public_key = Vcon.generate_key_pair() >>> vcon = Vcon.build_new() >>> vcon.sign(private_key) >>> is_valid = vcon.verify(public_key) >>> print(is_valid) # Prints True """ logger.debug("Verifying vCon signature") if "signatures" not in self.vcon_dict or "payload" not in self.vcon_dict: logger.error("Cannot verify: vCon is not signed") raise ValueError("vCon is not signed") # Refuse alg "none" before anything else, from either header location. sig0 = self.vcon_dict["signatures"][0] declared = [] try: hdr = sig0.get("protected") if hdr: declared.append(json.loads(base64.urlsafe_b64decode(hdr + "=" * (-len(hdr) % 4))).get("alg")) except Exception: logger.error("Cannot verify: protected header is not valid base64url JSON") return False if isinstance(sig0.get("header"), dict) and "alg" in sig0["header"]: declared.append(sig0["header"]["alg"]) for declared_alg in declared: if isinstance(declared_alg, str) and declared_alg.strip().lower() == "none": logger.error('Refusing to verify: JWS alg "none" is not permitted') raise AlgorithmNotPermittedError( 'JWS alg "none" is not permitted (core-05 section 6.2.2)' ) if not declared: logger.error("Cannot verify: no alg in the JWS protected header or header") return False alg = declared[0] if alg not in PERMITTED_JWS_ALGORITHMS: logger.error(f"Cannot verify: JWS alg {alg!r} is not supported") return False try: signed_data = f"{self.vcon_dict['signatures'][0]['protected']}.{self.vcon_dict['payload']}.{self.vcon_dict['signatures'][0]['signature']}" key = _import_jwk(public_key, alg, private=False) jws.deserialize_compact(signed_data, key, algorithms=[alg]) logger.info("Successfully verified vCon signature") return True except BadSignatureError: logger.warning("Invalid signature detected") return False except Exception as e: logger.error(f"Error during signature verification: {str(e)}") return False
[docs] @classmethod def generate_key_pair(cls) -> Tuple[rsa.RSAPrivateKey, rsa.RSAPublicKey]: """ Generate a new RSA key pair for signing vCons. This method generates a new RSA key pair that can be used for signing and verifying vCons. Returns: A tuple containing the private key and public key Example: >>> private_key, public_key = Vcon.generate_key_pair() >>> vcon = Vcon.build_new() >>> vcon.sign(private_key) >>> is_valid = vcon.verify(public_key) """ logger.debug("Generating new RSA key pair") private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048) public_key = private_key.public_key() logger.info("Successfully generated RSA key pair") return private_key, public_key
[docs] def is_valid(self) -> Tuple[bool, List[str]]: """ Validate the vCon against the core-05 rules. Checks required fields and types, that ``vcon`` (if present) is "0.5.0", that Sessions, Events, Dialogs, attachments and analysis reference existing objects, the per-event-type parameter table, that at least one Session exists when there are Dialogs or Events, that attachments have ``party`` and ``dialog`` or ``session``, that ``redacted_from`` and ``amended_from`` are exclusive, that ``extensions`` lists every extension in use (and every ``critical`` entry), that every ``__REDACTED_REF_#`` has a ``redacted_strings`` entry, that every ``url`` has a ``content_hash`` and every ``content_hash`` is well formed, and the body of every ``lawful_basis`` attachment. SHOULD-level findings are not errors; see :meth:`get_validation_warnings`. Returns: Tuple[bool, List[str]]: A tuple where the first element is True if the vCon is valid and False otherwise, and the second element is a list of error messages. """ logger.debug("Validating vCon") errors, _warnings = self._validate_all() for error in errors: logger.error(error) if len(errors) == 0: logger.info("vCon validation successful.") else: logger.warning(f"vCon validation failed with {len(errors)} error(s).") return len(errors) == 0, errors
[docs] def get_validation_warnings(self) -> List[str]: """SHOULD-level findings (for example SHOULD NOT parameters on Events).""" _errors, warnings = self._validate_all() return warnings
def _validate_all(self) -> Tuple[List[str], List[str]]: """Core rules plus the body of every lawful_basis attachment.""" errors, warnings = validate_vcon_dict(self.vcon_dict, Dialog.MIME_TYPES) # For a signed vCon the attachments are in the payload; an encrypted # one cannot be read. content = signed_payload(self.vcon_dict) if signed_form(self.vcon_dict) else self.vcon_dict if encrypted_form(self.vcon_dict) or not isinstance(content, dict): content = {} if EXTENSIONS_AVAILABLE: from .extensions.lawful_basis.validation import LawfulBasisValidator validator = LawfulBasisValidator() attachments = content.get("attachments") for i, attachment in enumerate(attachments if isinstance(attachments, list) else []): if not isinstance(attachment, dict) or attachment.get("purpose") != "lawful_basis": continue if isinstance(content.get("redacted_from"), dict) and "body" not in attachment: continue # Scope (party, dialog/session) is checked by the core rules above. try: result = validator.validate_attachment(attachment) except Exception as e: # a malformed body must not make is_valid() raise errors.append(f"Attachment at index {i} (lawful_basis): body could not be checked: {e}") continue errors.extend(f"Attachment at index {i} (lawful_basis): {e}" for e in result.errors) warnings.extend( f"Attachment at index {i} (lawful_basis): {w}" for w in result.warnings if "no party" not in w and "no session" not in w ) return errors, warnings
[docs] @staticmethod def validate_file(file_path: str) -> tuple[bool, list[str]]: """ Validate a vCon file at the given path. :param file_path: Path to the vCon JSON file :type file_path: str :return: A tuple containing (is_valid, list_of_errors) :rtype: tuple[bool, list[str]] """ try: with open(file_path, "r") as f: json_str = f.read() return Vcon.validate_json(json_str) except FileNotFoundError: return False, ["File not found"] except json.JSONDecodeError: return False, ["Invalid JSON format"] except Exception as e: return False, [f"Error reading file: {str(e)}"]
[docs] @staticmethod def validate_json(json_str: str) -> tuple[bool, list[str]]: """ Validate a vCon from a JSON string. :param json_str: JSON string representing a vCon :type json_str: str :return: A tuple containing (is_valid, list_of_errors) :rtype: tuple[bool, list[str]] """ try: vcon = Vcon.build_from_json(json_str) return vcon.is_valid() except json.JSONDecodeError: return False, ["Invalid JSON format"] except Exception as e: return False, [f"Error parsing vCon: {str(e)}"]
[docs] @classmethod def load( cls, source: str, property_handling: str = PROPERTY_HANDLING_DEFAULT, migrate_legacy: bool = True, strict_migration: bool = False, ) -> "Vcon": """ Load a vCon from either a file path or URL. Args: source: File path or URL to load the vCon from property_handling: How to handle non-standard properties. Options are "default", "strict", or "meta" Returns: A Vcon object Raises: ValueError: If the source is invalid or cannot be loaded requests.RequestException: If there is an error fetching from URL json.JSONDecodeError: If the source contains invalid JSON """ if source.startswith(('http://', 'https://')): return cls.load_from_url( source, property_handling=property_handling, migrate_legacy=migrate_legacy, strict_migration=strict_migration, ) else: return cls.load_from_file( source, property_handling=property_handling, migrate_legacy=migrate_legacy, strict_migration=strict_migration, )
[docs] @classmethod def load_from_file( cls, file_path: str, property_handling: str = PROPERTY_HANDLING_DEFAULT, migrate_legacy: bool = True, strict_migration: bool = False, ) -> "Vcon": """ Load a vCon from a file. Args: file_path: Path to the vCon JSON file property_handling: How to handle non-standard properties. Options are "default", "strict", or "meta" Returns: A Vcon object Raises: FileNotFoundError: If the file does not exist json.JSONDecodeError: If the file contains invalid JSON """ try: with open(file_path, 'r') as f: json_str = f.read() return cls.build_from_json( json_str, property_handling=property_handling, migrate_legacy=migrate_legacy, strict_migration=strict_migration, ) except FileNotFoundError: raise FileNotFoundError(f"vCon file not found: {file_path}") except json.JSONDecodeError as e: raise json.JSONDecodeError(f"Invalid JSON in vCon file: {str(e)}", e.doc, e.pos)
[docs] @classmethod def load_from_url( cls, url: str, property_handling: str = PROPERTY_HANDLING_DEFAULT, migrate_legacy: bool = True, strict_migration: bool = False, ) -> "Vcon": """ Load a vCon from a URL. Args: url: URL to fetch the vCon JSON from property_handling: How to handle non-standard properties. Options are "default", "strict", or "meta" Returns: A Vcon object Raises: requests.RequestException: If there is an error fetching from URL json.JSONDecodeError: If the response contains invalid JSON """ response = requests.get(url) response.raise_for_status() # Raise an exception for bad status codes return cls.build_from_json( response.text, property_handling=property_handling, migrate_legacy=migrate_legacy, strict_migration=strict_migration, )
[docs] def save_to_file(self, file_path: str) -> None: """ Save the vCon to a JSON file. :param file_path: Path where the vCon JSON should be saved :type file_path: str :raises IOError: If there is an error writing to the file """ logger.debug(f"Saving vCon to file: {file_path}") try: with open(file_path, 'w') as f: f.write(self.to_json()) logger.info(f"Successfully saved vCon to {file_path}") except IOError as e: logger.error(f"Failed to save vCon to file: {str(e)}") raise
[docs] def post_to_url(self, url: str, headers: Optional[Dict[str, str]] = None) -> requests.Response: """ Post the vCon as JSON to a URL with optional headers. :param url: The URL to post the vCon to :type url: str :param headers: Optional dictionary of HTTP headers (e.g., {'x-conserver-api-token': 'token123'}) :type headers: Optional[Dict[str, str]] :return: The HTTP response from the server :rtype: requests.Response :raises requests.RequestException: If there is an error making the HTTP request Example: >>> vcon = Vcon.build_new() >>> response = vcon.post_to_url( ... 'https://api.example.com/vcons', ... headers={'x-conserver-api-token': 'your-token-here'} ... ) >>> print(response.status_code) # Prints HTTP status code (e.g., 200 for success) """ logger.debug(f"Posting vCon to URL: {url}") # Prepare headers request_headers = { 'Content-Type': 'application/json' } if headers: request_headers.update(headers) try: response = requests.post( url, data=self.to_json(), headers=request_headers ) response.raise_for_status() logger.info(f"Successfully posted vCon to {url}") return response except requests.RequestException as e: logger.error(f"Failed to post vCon to URL: {str(e)}") raise