Implementation:Googleapis Python genai Interactions Utils

Knowledge Sources	Googleapis_Python_genai
Domains	Utilities, SDK_Infrastructure
Last Updated	2026-02-15 14:00 GMT

Overview

Concrete tool for general-purpose utility functions including type guards, JSON safety, file extraction, and argument validation for the _interactions subsystem.

Description

The _utils module provides a broad collection of utilities: type narrowing guards (is_given, is_mapping, is_list), file extraction from nested dicts (extract_files), human-readable list formatting (human_join), runtime argument validation (required_args decorator), JSON-safe conversion (json_safe), and async library detection.

Usage

Internal infrastructure. These utilities are used throughout the _interactions package for request construction and validation.

Code Reference

Source Location

• Repository: Googleapis_Python_genai
• File: google/genai/_interactions/_utils/_utils.py
• Lines: 1-437

Signature

def flatten(t: Iterable[Iterable[_T]]) -> list[_T]: ...
def extract_files(query: Mapping[str, object], *, paths: Sequence[Sequence[str]]) -> list[tuple[str, FileTypes]]: ...
def is_given(obj: _T | NotGiven | Omit) -> TypeGuard[_T]: ...
def is_mapping(obj: object) -> TypeGuard[Mapping[str, object]]: ...
def deepcopy_minimal(item: _T) -> _T: ...
def human_join(seq: Sequence[str], *, delim: str = ", ", final: str = "or") -> str: ...
def required_args(*variants: Sequence[str]) -> Callable[[CallableT], CallableT]: ...
def strip_not_given(obj: object | None) -> object: ...
def json_safe(data: object) -> object: ...
def get_required_header(headers: HeadersLike, header: str) -> str: ...

Import

from google.genai._interactions._utils._utils import is_given, extract_files, json_safe

I/O Contract

Inputs

Name	Type	Required	Description
obj	Any	Yes (for type guards)	Value to test
query	Mapping	Yes (for extract_files)	Nested dict containing file references
paths	Sequence[Sequence[str]]	Yes (for extract_files)	Paths to file locations in the dict

Outputs

Name	Type	Description
is_given returns	bool (TypeGuard)	Whether the value was explicitly provided
extract_files returns	list[tuple[str, FileTypes]]	Extracted file objects with their keys
json_safe returns	object	JSON-serializable version of the input

Usage Examples

# Internal usage patterns
from google.genai._interactions._utils._utils import is_given, human_join

# Type guard for optional parameters
if is_given(timeout):
    options.timeout = timeout

# Human-readable list formatting
human_join(["a", "b", "c"], final="and")  # "a, b, and c"

Related Pages

• Environment:Googleapis_Python_genai_Python_3_10_SDK_Runtime