snowflake-connector-python 4.8.0__cp313-cp313-macosx_15_0_arm64.whl

snowflake/connector/__init__.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python
+# Python Db API v2
+#
+from __future__ import annotations
+
+from functools import wraps
+
+from ._utils import _core_loader
+
+apilevel = "2.0"
+threadsafety = 2
+paramstyle = "pyformat"
+
+import logging
+from logging import NullHandler
+
+from snowflake.connector.externals_utils.externals_setup import setup_external_libraries
+
+from .connection import SnowflakeConnection
+from .cursor import DictCursor
+from .dbapi import (
+    BINARY,
+    DATETIME,
+    NUMBER,
+    ROWID,
+    STRING,
+    Binary,
+    Date,
+    DateFromTicks,
+    Time,
+    TimeFromTicks,
+    Timestamp,
+    TimestampFromTicks,
+)
+from .errors import (
+    DatabaseError,
+    DataError,
+    Error,
+    IntegrityError,
+    InterfaceError,
+    InternalError,
+    NotSupportedError,
+    OperationalError,
+    ProgrammingError,
+    _Warning,
+)
+from .log_configuration import EasyLoggingConfigPython
+from .version import VERSION
+
+# Load the core library - failures are captured in core_loader and don't prevent module loading
+try:
+    _core_loader.load()
+except Exception:
+    # Silently continue if core loading fails - the error is already captured in core_loader
+    # This ensures the connector module loads even if the minicore library is unavailable
+    pass
+
+logging.getLogger(__name__).addHandler(NullHandler())
+setup_external_libraries()
+
+
+@wraps(SnowflakeConnection.__init__)
+def Connect(**kwargs) -> SnowflakeConnection:
+    return SnowflakeConnection(**kwargs)
+
+
+connect = Connect
+
+SNOWFLAKE_CONNECTOR_VERSION = ".".join(str(v) for v in VERSION[0:3])
+__version__ = SNOWFLAKE_CONNECTOR_VERSION
+
+__all__ = [
+    "SnowflakeConnection",
+    # Error handling
+    "Error",
+    "_Warning",
+    "InterfaceError",
+    "DatabaseError",
+    "NotSupportedError",
+    "DataError",
+    "IntegrityError",
+    "ProgrammingError",
+    "OperationalError",
+    "InternalError",
+    # Extended cursor
+    "DictCursor",
+    # DBAPI PEP 249 required exports
+    "connect",
+    "apilevel",
+    "threadsafety",
+    "paramstyle",
+    "Date",
+    "Time",
+    "Timestamp",
+    "Binary",
+    "DateFromTicks",
+    "TimeFromTicks",
+    "TimestampFromTicks",
+    "STRING",
+    "BINARY",
+    "NUMBER",
+    "DATETIME",
+    "ROWID",
+    # Extended data type (experimental)
+    "EasyLoggingConfigPython",
+]

snowflake/connector/_connection_identifier_shape.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python
+"""Capture user-supplied connection-identifier provenance for in-band telemetry.
+
+The shape captured here is consumed by ``SnowflakeConnection._log_connection_identifier_shape``
+and emitted as a single ``client_connection_identifier_shape`` telemetry event
+per successful login. The capture function inspects the raw kwargs passed to
+``SnowflakeConnection.__config`` before any normalization (host inference,
+account stripping of ``.global``, region extraction from dotted account) runs,
+so the shape reflects user intent rather than the final post-normalization
+state of the connection.
+
+Removal of this module and the emission it backs is tracked in SNOW-3548350
+(target: 2026-11-30).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from .telemetry import TelemetryField
+
+
+@dataclass(frozen=True)
+class ConnectionIdentifierShape:
+    """Provenance of connection-identifier fields the user supplied.
+
+    All fields describe what the user supplied at the moment of input — they
+    reflect intent, not the final post-normalization state of the connection.
+
+    - ``account_provided``: the user explicitly set the ``account`` parameter
+      (via ``connect(account=...)``, kwargs, or ``connections.toml`` merged
+      into kwargs before ``__config`` runs).
+    - ``account_with_region``: the raw account string the user typed contained
+      a dot (e.g. ``"myacct.us-east-1"``), signaling the deprecated
+      ``account.region`` embedded form. Set only on the raw input.
+    - ``account_org_provided``: the raw account string carried a dash in its
+      account portion (e.g. ``"myorg-myacct"``), signaling the org-prefixed
+      form. Region-portion dashes (e.g. the ``-east-`` in
+      ``"myacct.us-east-1"``) are intentionally not counted; only the portion
+      before the first ``.`` is examined.
+    - ``region_provided``: the user explicitly set the ``region`` parameter as
+      a distinct kwarg. A region embedded inside a dotted account string is
+      NOT ``region_provided``; that's ``account_with_region``.
+    - ``host_provided``: the user explicitly set the ``host`` parameter.
+    """
+
+    account_provided: bool = False
+    account_with_region: bool = False
+    account_org_provided: bool = False
+    region_provided: bool = False
+    host_provided: bool = False
+
+
+def _is_user_supplied_string(value: Any) -> bool:
+    """A kwarg counts as user-supplied iff it's a non-empty string. Non-string
+    truthy values (e.g. an accidentally-passed ``True`` / ``int``) are not
+    treated as provided here — the regular ``__config`` validation will warn
+    or error on them later, and shape capture is best kept conservative."""
+    return isinstance(value, str) and value != ""
+
+
+def record_input_shape(kwargs: Mapping[str, Any]) -> ConnectionIdentifierShape:
+    """Capture the connection-identifier shape from the raw kwargs that
+    ``SnowflakeConnection.__config`` receives.
+
+    Must be invoked before any normalization (the ``setattr`` loop in
+    ``__config``, the ``construct_hostname`` call for host inference, or any
+    ``parse_account`` stripping) — otherwise inferred values are
+    indistinguishable from user-supplied ones and ``host_provided`` /
+    ``account_provided`` are no longer trustworthy.
+    """
+    account = kwargs.get("account")
+    region = kwargs.get("region")
+    host = kwargs.get("host")
+
+    account_provided = _is_user_supplied_string(account)
+    account_with_region = False
+    account_org_provided = False
+    if account_provided:
+        # Only a dot at position > 0 splits the string into account / region;
+        # a leading dot (pathological input like ``.us-east-1``) leaves the
+        # whole string as the account portion. Mirrors gosnowflake's
+        # ``recordAccountShape`` (internal/config/dsn.go), which gates on
+        # ``i > 0`` so the dash search runs against the full raw value when
+        # there is no real account/region split.
+        dot_index = account.find(".")
+        if dot_index > 0:
+            account_with_region = True
+            account_portion = account[:dot_index]
+        else:
+            account_portion = account
+        # ``Contains(accountPortion, "-")`` in Go — any dash anywhere in the
+        # account portion (including position 0) flips the flag. The
+        # region-tail dashes are excluded by virtue of being outside
+        # ``account_portion``, not by a position check.
+        account_org_provided = "-" in account_portion
+
+    return ConnectionIdentifierShape(
+        account_provided=account_provided,
+        account_with_region=account_with_region,
+        account_org_provided=account_org_provided,
+        region_provided=_is_user_supplied_string(region),
+        host_provided=_is_user_supplied_string(host),
+    )
+
+
+def build_shape_telemetry_message(shape: ConnectionIdentifierShape) -> dict[str, str]:
+    """Build the wire-format payload for the ``client_connection_identifier_shape``
+    in-band telemetry event from a captured ``ConnectionIdentifierShape``.
+
+    Hoisted out of the sync / async ``_log_connection_identifier_shape``
+    emitters so both branches stay in lockstep — the five payload keys
+    (``account_provided``, ``account_with_region``, ``account_org_provided``,
+    ``region_provided``, ``host_provided``) and their stringified-lowercase
+    boolean values are byte-identical across sibling drivers and must remain
+    so. Changing this builder is the only place that affects the wire format.
+
+    Booleans are stringified as lowercase ``"true"`` / ``"false"`` (matching
+    JSON-style boolean text) for cross-driver parity with gosnowflake's
+    ``strconv.FormatBool`` and the JDBC / Node.js siblings.
+
+    TODO(SNOW-3548350): remove with the telemetry emission
+    (target: 2026-11-30).
+    """
+    return {
+        TelemetryField.KEY_TYPE.value: TelemetryField.CONNECTION_IDENTIFIER_SHAPE.value,
+        TelemetryField.KEY_ACCOUNT_PROVIDED.value: str(shape.account_provided).lower(),
+        TelemetryField.KEY_ACCOUNT_WITH_REGION.value: str(
+            shape.account_with_region
+        ).lower(),
+        TelemetryField.KEY_ACCOUNT_ORG_PROVIDED.value: str(
+            shape.account_org_provided
+        ).lower(),
+        TelemetryField.KEY_REGION_PROVIDED.value: str(shape.region_provided).lower(),
+        TelemetryField.KEY_HOST_PROVIDED.value: str(shape.host_provided).lower(),
+    }

snowflake/connector/_host_util.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python
+#
+# Copyright (c) 2012-2023 Snowflake Computing Inc. All rights reserved.
+#
+
+"""Host normalization and recognition shared by every subsystem that turns a
+connection host into the authority of a URL the connector builds itself.
+
+Kept subsystem-agnostic so that WORKLOAD_IDENTITY attestation and OCSP cache-URL
+derivation match hosts identically; a second, slightly different rule in either
+place is what this module exists to prevent. The suffix list itself lives in
+``constants`` so the data stays next to the connector's other TLD constants.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from .constants import _SNOWFLAKE_ALLOWED_HOST_SUFFIXES
+
+# Maps only ASCII A-Z to a-z.
+#
+# Deliberately not str.lower(): full Unicode case folding maps some characters
+# into ASCII, so a host containing U+212A KELVIN SIGN folds
+# "snowfla<U+212A>ecomputing.com" into "snowflakecomputing.com" and would match a
+# recognized suffix while DNS still resolves the original, unrelated name.
+# Leaving non-ASCII untouched lets is_ldh_host reject it instead.
+_ASCII_LOWERCASE_TABLE = str.maketrans(
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZ", "abcdefghijklmnopqrstuvwxyz"
+)
+
+# Characters legal in a DNS hostname label, plus '_': account labels
+# legitimately contain one.
+_LDH_CHARACTERS = frozenset("abcdefghijklmnopqrstuvwxyz0123456789-_")
+
+
+def normalize_host(host: str | None) -> str:
+    """Normalizes a host (or a configured host suffix) into the single string that
+    every subsequent check and every derived URL must use.
+
+    Trims, lower-cases ASCII only, drops everything from the first ':' onward,
+    then strips exactly one trailing '.' (FQDN form).
+
+    The port must be dropped before the trailing dot: a host in FQDN form
+    carrying an explicit port ("acct.snowflakecomputing.com.:443") still has the
+    dot immediately before the colon, and removing the dot first would leave it
+    attached to the label and match no suffix.
+    """
+    if not host:
+        return ""
+    normalized = host.strip().translate(_ASCII_LOWERCASE_TABLE)
+    if ":" in normalized:
+        normalized = normalized.split(":", 1)[0]
+    if normalized.endswith("."):
+        normalized = normalized[:-1]
+    return normalized
+
+
+def is_ldh_host(normalized_host: str) -> bool:
+    """Whether an already-normalized host is made only of characters legal in a
+    DNS hostname: every dot-separated label non-empty and drawn from
+    ``[a-z0-9_-]``.
+
+    This is an allow-list, not a list of forbidden delimiters, and that
+    distinction is load-bearing. A host is only safe to interpolate into a URL
+    authority if it cannot carry a character that some URL parser treats as
+    ending the host, and enumerating such characters does not work: parsers
+    variously terminate the authority at a space, ';', "'", a percent-escape, or
+    a full-width look-alike of '.', '#' or '?'. Since a host whose trailing
+    labels are a recognized Snowflake domain can still begin with an unrelated
+    name, a parser that stops early resolves that unrelated name instead.
+
+    Args:
+        normalized_host: output of :func:`normalize_host`.
+    """
+    if not normalized_host:
+        return False
+    return all(
+        label and _LDH_CHARACTERS.issuperset(label)
+        for label in normalized_host.split(".")
+    )
+
+
+def has_recognized_snowflake_suffix(
+    normalized_host: str,
+    extra_suffixes: Iterable[str] | None = None,
+) -> bool:
+    """Whether an already-normalized host ends at one of the recognized Snowflake
+    suffixes, matched on a label boundary so that only a listed suffix and its
+    subdomains qualify. The bare apex is accepted by the equality branch.
+
+    Args:
+        normalized_host: output of :func:`normalize_host`.
+        extra_suffixes: additional already-normalized suffixes to accept.
+            Additive only: callers cannot use this to disable the built-in list.
+    """
+    if not normalized_host:
+        return False
+    suffixes: tuple[str, ...] = _SNOWFLAKE_ALLOWED_HOST_SUFFIXES
+    if extra_suffixes:
+        suffixes = (*suffixes, *extra_suffixes)
+    return any(
+        normalized_host == suffix or normalized_host.endswith(f".{suffix}")
+        for suffix in suffixes
+        if suffix
+    )

snowflake/connector/_ocsp_mode.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Collection
+
+from .constants import OCSPMode
+
+# ocsp_fail_open True/False opts into OCSP. None is the stored default and
+# is not an opt-in. disable_ocsp_checks / insecure_mode only turn OCSP off
+# when True; their stored False default is not an opt-in. Cache/timeout
+# knobs never enable OCSP.
+OCSP_MODE_PARAMS = frozenset({"disable_ocsp_checks", "ocsp_fail_open", "insecure_mode"})
+OCSP_SUPPORT_PARAMS = frozenset(
+    {"ocsp_response_cache_filename", "ocsp_root_certs_dict_lock_timeout"}
+)
+OCSP_EXPLICIT_PARAMS = OCSP_MODE_PARAMS | OCSP_SUPPORT_PARAMS
+
+IGNORED_OCSP_SUPPORT_PARAMS_WARNING = (
+    "OCSP is disabled unless you opt in. The following OCSP setting(s) will be "
+    "ignored because none of ocsp_fail_open, disable_ocsp_checks, or "
+    "insecure_mode was set: {params}. Set ocsp_fail_open=True or "
+    "ocsp_fail_open=False to enable OCSP."
+)
+
+
+def snapshot_ocsp_explicit_params(params: Mapping[str, Any]) -> frozenset[str]:
+    return frozenset(name for name in OCSP_EXPLICIT_PARAMS if name in params)
+
+
+def resolve_ocsp_mode(
+    *,
+    explicit: Collection[str],
+    disable_ocsp_checks: bool,
+    ocsp_fail_open: bool | None,
+    insecure_mode: bool | None = None,
+) -> OCSPMode:
+    """Resolve OCSP mode from explicit user/toml presence plus stored values.
+
+    ``ocsp_fail_open`` is the only opt-in: True = fail-open, False =
+    fail-closed. None is the stored default and does not enable OCSP, even
+    when the key is present (a caller forwarding DEFAULT_CONFIGURATION).
+
+    Connection-property disable (``disable_ocsp_checks=True`` or
+    ``insecure_mode=True``) always turns OCSP off, including when
+    ``ocsp_fail_open`` is True/False. Presence of
+    ``disable_ocsp_checks=False`` or ``insecure_mode=False`` is not an
+    opt-in; those are the stored defaults.
+    """
+    if "disable_ocsp_checks" in explicit:
+        disable_value = disable_ocsp_checks
+    elif "insecure_mode" in explicit:
+        disable_value = (
+            insecure_mode if insecure_mode is not None else disable_ocsp_checks
+        )
+    else:
+        disable_value = False
+
+    if disable_value:
+        return OCSPMode.DISABLE_OCSP_CHECKS
+    if ocsp_fail_open is not None:
+        return OCSPMode.FAIL_OPEN if ocsp_fail_open else OCSPMode.FAIL_CLOSED
+    return OCSPMode.DISABLE_OCSP_CHECKS
+
+
+def ignored_ocsp_support_params(explicit: Collection[str]) -> tuple[str, ...]:
+    if any(name in explicit for name in OCSP_MODE_PARAMS):
+        return ()
+    return tuple(sorted(name for name in OCSP_SUPPORT_PARAMS if name in explicit))

snowflake/connector/_query_context_cache.py

@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+from functools import total_ordering
+from hashlib import md5
+from logging import getLogger
+from threading import Lock
+from typing import Any, Iterable
+
+from sortedcontainers import SortedSet
+
+logger = getLogger(__name__)
+
+
+@total_ordering
+class QueryContextElement:
+    def __init__(
+        self, id: int, read_timestamp: int, priority: int, context: str
+    ) -> None:
+        # entry with id = 0 is the main entry
+        self.id = id
+        self.read_timestamp = read_timestamp
+        # priority values are 0..N with 0 being the highest priority
+        self.priority = priority
+        # OpaqueContext field will be base64 encoded in GS, but it is opaque to client side. Client side should not do decoding/encoding and just store the raw data.
+        self.context = context
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, QueryContextElement):
+            return False
+        return (
+            self.id == other.id
+            and self.read_timestamp == other.read_timestamp
+            and self.priority == other.priority
+            and self.context == other.context
+        )
+
+    def __lt__(self, other: Any) -> bool:
+        if not isinstance(other, QueryContextElement):
+            raise TypeError(
+                f"cannot compare QueryContextElement with object of type {type(other)}"
+            )
+        return self.priority < other.priority
+
+    def __hash__(self) -> int:
+        _hash = 31
+
+        _hash = _hash * 31 + self.id
+        _hash += (_hash * 31) + self.read_timestamp
+        _hash += (_hash * 31) + self.priority
+        if self.context:
+            _hash += (_hash * 31) + int.from_bytes(
+                md5(self.context.encode("utf-8")).digest(), "big"
+            )
+        return _hash
+
+    def __str__(self) -> str:
+        return f"({self.id}, {self.read_timestamp}, {self.priority})"
+
+
+class QueryContextCache:
+    def __init__(self, capacity: int) -> None:
+        self.capacity = capacity
+        self._id_map: dict[int, QueryContextElement] = {}
+        self._priority_map: dict[int, QueryContextElement] = {}
+        self._intermediate_priority_map: dict[int, QueryContextElement] = {}
+
+        # stores elements sorted by priority. Element with
+        # least priority value has the highest priority
+        self._tree_set: set[QueryContextElement] = SortedSet()
+        self._lock = Lock()
+        self._data: str = None
+
+    def _add_qce(self, qce: QueryContextElement) -> None:
+        """Adds qce element in tree_set, id_map and intermediate_priority_map.
+        We still need to add _sync_priority_map after all the new qce have been merged
+        into the cache.
+        """
+        self._tree_set.add(qce)
+        self._id_map[qce.id] = qce
+        self._intermediate_priority_map[qce.priority] = qce
+
+    def _remove_qce(self, qce: QueryContextElement) -> None:
+        self._id_map.pop(qce.id)
+        self._priority_map.pop(qce.priority)
+        self._tree_set.remove(qce)
+
+    def _replace_qce(
+        self, old_qce: QueryContextElement, new_qce: QueryContextElement
+    ) -> None:
+        """This is just a convenience function to call a remove and add operation back-to-back"""
+        self._remove_qce(old_qce)
+        self._add_qce(new_qce)
+
+    def _sync_priority_map(self):
+        """
+        Sync the _intermediate_priority_map with the _priority_map at the end of the current round of inserts.
+        """
+        logger.debug(
+            f"sync_priority_map called priority_map size = {len(self._priority_map)}, new_priority_map size = {len(self._intermediate_priority_map)}"
+        )
+
+        self._priority_map.update(self._intermediate_priority_map)
+        # Clear the _intermediate_priority_map for the next round of QCC insert (a round consists of multiple entries)
+        self._intermediate_priority_map.clear()
+
+    def insert(self, id: int, read_timestamp: int, priority: int, context: str) -> None:
+        if id in self._id_map:
+            qce = self._id_map[id]
+            if (read_timestamp > qce.read_timestamp) or (
+                read_timestamp == qce.read_timestamp and priority != qce.priority
+            ):
+                # when id if found in cache and we are operating on a more recent timestamp. We do not update in-place here.
+                new_qce = QueryContextElement(id, read_timestamp, priority, context)
+                self._replace_qce(qce, new_qce)
+        else:
+            new_qce = QueryContextElement(id, read_timestamp, priority, context)
+            if priority in self._priority_map:
+                old_qce = self._priority_map[priority]
+                self._replace_qce(old_qce, new_qce)
+            else:
+                self._add_qce(new_qce)
+
+    def trim_cache(self) -> None:
+        logger.debug(
+            f"trim_cache() called. treeSet size is {len(self._tree_set)} and cache capacity is {self.capacity}"
+        )
+
+        while len(self) > self.capacity:
+            # remove the qce with highest priority value => element with least priority
+            qce = self._last()
+            self._remove_qce(qce)
+
+        logger.debug(
+            f"trim_cache() returns. treeSet size is {len(self._tree_set)} and cache capacity is {self.capacity}"
+        )
+
+    def clear_cache(self) -> None:
+        logger.debug("clear_cache() called")
+        self._id_map.clear()
+        self._priority_map.clear()
+        self._tree_set.clear()
+        self._intermediate_priority_map.clear()
+
+    def _get_elements(self) -> Iterable[QueryContextElement]:
+        return self._tree_set
+
+    def _last(self) -> QueryContextElement:
+        return self._tree_set[-1]
+
+    def serialize_to_dict(self) -> dict:
+        with self._lock:
+            logger.debug("serialize_to_dict() called")
+            self.log_cache_entries()
+
+            if len(self._tree_set) == 0:
+                return {}  # we should return an empty dict
+
+            try:
+                data = {
+                    "entries": [
+                        {
+                            "id": qce.id,
+                            "timestamp": qce.read_timestamp,
+                            "priority": qce.priority,
+                            "context": (
+                                {"base64Data": qce.context}
+                                if qce.context is not None
+                                else {}
+                            ),
+                        }
+                        for qce in self._tree_set
+                    ]
+                }
+                # Because on GS side, `context` field is an object with `base64Data`  string member variable,
+                # we should serialize `context` field to an object instead of string directly to stay consistent with GS side.
+
+                logger.debug(f"serialize_to_dict(): data to send to server {data}")
+
+                # query context shoule be an object field of the HTTP request body JSON and on GS side. here we should only return a dict
+                # and let the outer HTTP request body to convert the entire big dict to a single JSON.
+                return data
+            except Exception as e:
+                logger.debug(f"serialize_to_dict(): Exception {e}")
+                return {}
+
+    def deserialize_json_dict(self, data: dict) -> None:
+        with self._lock:
+            logger.debug(f"deserialize_json_dict() called: data from server: {data}")
+            self.log_cache_entries()
+
+            if data is None or len(data) == 0:
+                self.clear_cache()
+                logger.debug("deserialize_json_dict() returns")
+                self.log_cache_entries()
+                return
+
+            try:
+                # Deserialize the entries. The first entry with priority 0 is the main entry. On python
+                # connector side, we save all entries into one list to simplify the logic. When python
+                # connector receives HTTP response, the data["queryContext"] field has been converted
+                # from JSON to dict type automatically, so for this function we deserialize from python
+                # dict directly. Below is an example QueryContext dict.
+                # {
+                #   "entries": [
+                #    {
+                #     "id": 0,
+                #     "read_timestamp": 123456789,
+                #     "priority": 0,
+                #     "context": "base64 encoded context"
+                #    },
+                #     {
+                #       "id": 1,
+                #       "read_timestamp": 123456789,
+                #       "priority": 1,
+                #       "context": "base64 encoded context"
+                #     },
+                #     {
+                #       "id": 2,
+                #       "read_timestamp": 123456789,
+                #       "priority": 2,
+                #       "context": "base64 encoded context"
+                #     }
+                #   ]
+                # }
+
+                # Deserialize entries
+                entries = data.get("entries", list())
+                for entry in entries:
+                    logger.debug(f"deserialize {entry}")
+                    if not isinstance(entry.get("id"), int):
+                        logger.debug("id type error")
+                        raise TypeError(
+                            f"Invalid type for 'id' field: Expected int, got {type(entry['id'])}"
+                        )
+                    if not isinstance(entry.get("timestamp"), int):
+                        logger.debug("timestamp type error")
+                        raise TypeError(
+                            f"Invalid type for 'timestamp' field: Expected int, got {type(entry['timestamp'])}"
+                        )
+                    if not isinstance(entry.get("priority"), int):
+                        logger.debug("priority type error")
+                        raise TypeError(
+                            f"Invalid type for 'priority' field: Expected int, got {type(entry['priority'])}"
+                        )
+
+                    # OpaqueContext field currently is empty from GS side.
+                    context = entry.get("context", None)
+                    if context and not isinstance(entry.get("context"), str):
+                        logger.debug("context type error")
+                        raise TypeError(
+                            f"Invalid type for 'context' field: Expected str, got {type(entry['context'])}"
+                        )
+                    self.insert(
+                        entry.get("id"),
+                        entry.get("timestamp"),
+                        entry.get("priority"),
+                        context,
+                    )
+
+                # Sync the priority map at the end of for loop insert.
+                self._sync_priority_map()
+            except Exception as e:
+                logger.debug(f"deserialize_json_dict: Exception = {e}")
+                # clear cache due to incomplete insert
+                self.clear_cache()
+
+            self.trim_cache()
+            logger.debug("deserialize_json_dict() returns")
+            self.log_cache_entries()
+
+    def log_cache_entries(self) -> None:
+        for qce in self._tree_set:
+            logger.debug(f"Cache Entry: {str(qce)}")
+
+    def __len__(self) -> int:
+        return len(self._tree_set)