Source code for vcon.session

"""Session Object and Session_Reference Object (core-05 sections 4.2 and 4.2.8).

A Session groups the Dialog and Event Objects of one conversation (or part of
one) and records its receivers. A Session Object with no parameters is allowed.
"""

from __future__ import annotations

from datetime import datetime
from typing import Any, Dict, List, Optional, Tuple, Union

from dateutil import parser

#: Session_Reference ``type`` tokens defined by core-05 (4.2.8.2). Values
#: defined by a vCon extension are also allowed.
SESSION_REFERENCE_TYPES = ("child", "peer", "precursor", "breakout")

SESSION_PARAMETERS = (
    "start",
    "duration",
    "parties",
    "originator",
    "session_id",
    "sessions",
    "dialog",
)


def _is_index(value: Any) -> bool:
    return isinstance(value, int) and not isinstance(value, bool) and value >= 0


[docs]class SessionReference: """Session_Reference Object: how another Session relates to this one.""" def __init__(self, session: int, type: str, description: Optional[str] = None) -> None: if not _is_index(session): raise ValueError("Session_Reference 'session' must be a non-negative integer") if not isinstance(type, str) or not type: raise ValueError("Session_Reference 'type' is required") self.session = session self.type = type self.description = description
[docs] def to_dict(self) -> Dict[str, Any]: out: Dict[str, Any] = {"session": self.session, "type": self.type} if self.description is not None: out["description"] = self.description return out
[docs]class Session: """A Session Object. Args: start: Session start (``datetime`` or ISO 8601 string). SHOULD be present. duration: Session duration in seconds. Absent means the session has no end. parties: Indices of the receivers. The first one is the implied originator. originator: Index of the originator, only when it is not the first party. session_id: A SessionId Object (``{"local": ..., "remote": ...}``). sessions: Relationships to other Sessions (``SessionReference`` or dicts). dialog: Indices of the Dialog Objects that are part of the session. """ def __init__( self, start: Optional[Union[datetime, str]] = None, duration: Optional[Union[int, float]] = None, parties: Optional[List[int]] = None, originator: Optional[int] = None, session_id: Optional[Dict[str, str]] = None, sessions: Optional[List[Union[SessionReference, Dict[str, Any]]]] = None, dialog: Optional[List[int]] = None, ) -> None: if isinstance(start, datetime): start = start.isoformat() elif isinstance(start, str): start = parser.parse(start).isoformat() self.start = start self.duration = duration self.parties = list(parties) if parties is not None else None self.originator = originator self.session_id = session_id self.sessions = list(sessions) if sessions is not None else None self.dialog = list(dialog) if dialog is not None else None
[docs] def to_dict(self) -> Dict[str, Any]: """Serialize, omitting parameters that are ``None``. An empty Session is ``{}``.""" out: Dict[str, Any] = {} for name in SESSION_PARAMETERS: value = getattr(self, name) if value is None: continue if name == "sessions": value = [v.to_dict() if isinstance(v, SessionReference) else v for v in value] out[name] = value return out
[docs]def validate_session( session: Any, *, party_count: Optional[int] = None, dialog_count: Optional[int] = None, session_count: Optional[int] = None, label: str = "Session", ) -> Tuple[List[str], List[str]]: """Validate one Session Object dict. Returns ``(errors, warnings)``.""" errors: List[str] = [] warnings: List[str] = [] if not isinstance(session, dict): return [f"{label} must be a dictionary."], warnings if not session: return errors, warnings # an empty placeholder Session is permitted if "start" in session: try: if not isinstance(session["start"], str): raise ValueError("not a string") parser.parse(session["start"]) except Exception: errors.append(f"{label} has an invalid 'start' format. Must be an ISO 8601 datetime string.") else: warnings.append(f"{label} should have a start parameter.") if "duration" in session: d = session["duration"] if isinstance(d, bool) or not isinstance(d, (int, float)) or d < 0: errors.append(f"{label} field 'duration' must be a non-negative number.") if "parties" in session: p = session["parties"] if not isinstance(p, list): errors.append(f"{label} field 'parties' must be a list.") else: for idx in p: if not _is_index(idx) or (party_count is not None and idx >= party_count): errors.append(f"{label} references invalid party index: {idx}") else: warnings.append(f"{label} should have a parties parameter.") if "originator" in session: o = session["originator"] if not _is_index(o) or (party_count is not None and o >= party_count): errors.append(f"{label} references invalid party index: {o}") if "session_id" in session and not isinstance(session["session_id"], dict): errors.append(f"{label} field 'session_id' must be a SessionId Object.") if "dialog" in session: dl = session["dialog"] if not isinstance(dl, list): errors.append(f"{label} field 'dialog' must be a list.") else: for idx in dl: if not _is_index(idx) or (dialog_count is not None and idx >= dialog_count): errors.append(f"{label} references invalid dialog index: {idx}") if "sessions" in session: refs = session["sessions"] if not isinstance(refs, list): errors.append(f"{label} field 'sessions' must be a list.") else: for n, ref in enumerate(refs): if not isinstance(ref, dict): errors.append(f"{label} sessions[{n}] must be a dictionary.") continue for req in ("session", "type"): if req not in ref: errors.append(f"{label} sessions[{n}] is missing required field: {req}") if "session" in ref: if not _is_index(ref["session"]) or ( session_count is not None and ref["session"] >= session_count ): errors.append(f"{label} references invalid session index: {ref['session']}") if "type" in ref and not isinstance(ref["type"], str): errors.append(f"{label} sessions[{n}] field 'type' must be a string.") return errors, warnings