Overview
Concrete tool for internal data manipulation, type narrowing, and request preparation provided by the Groq Python SDK's utility module.
Description
The _utils module provides foundational helper functions used throughout the Groq SDK. Key capabilities include: extract_files() for pulling file objects out of nested request dictionaries for multipart uploads; is_given() as a TypeGuard to detect whether a parameter was explicitly provided; a suite of type-narrowing guards (is_dict, is_list, is_mapping, etc.); strip_not_given() for cleaning NotGiven sentinel values from request data; required_args() as a decorator to enforce runtime argument validation for overloaded functions; and json_safe() for recursive JSON serialization of Python objects.
Usage
These utilities are consumed internally by the SDK's resource classes, client, and model layer. is_given() and strip_not_given() are the most relevant to SDK extension or customization. extract_files() is called automatically by resource methods that handle file uploads (transcriptions, translations, batch files).
Code Reference
Source Location
Signature
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 strip_not_given(obj: object | None) -> object: ...
def required_args(*variants: Sequence[str]) -> Callable[[CallableT], CallableT]: ...
def deepcopy_minimal(item: _T) -> _T: ...
def get_required_header(headers: HeadersLike, header: str) -> str: ...
def lru_cache(*, maxsize: int | None = 128) -> Callable[[CallableT], CallableT]: ...
def json_safe(data: object) -> object: ...
Import
from groq._utils import (
extract_files,
is_given,
is_list,
is_dict,
is_mapping,
strip_not_given,
required_args,
deepcopy_minimal,
json_safe,
lru_cache,
)
I/O Contract
| Name |
Type |
Required |
Description
|
| query |
Mapping[str, object] |
Yes |
Request body dictionary to extract files from (mutated in-place)
|
| paths |
Sequence[Sequence[str]] |
Yes |
Dot-path sequences to file fields (e.g. "file")
|
| Name |
Type |
Description
|
| return |
list[tuple[str, FileTypes]] |
List of (field_name, file_content) tuples for multipart upload
|
Inputs (is_given)
| Name |
Type |
Required |
Description
|
| obj |
_T or NotGiven or Omit |
Yes |
Value to check
|
Outputs (is_given)
| Name |
Type |
Description
|
| return |
TypeGuard[_T] |
True if the value was explicitly provided
|
Usage Examples
Checking if a Parameter Was Provided
from groq._utils import is_given
from groq._types import NotGiven, NOT_GIVEN
timeout = NOT_GIVEN # user did not pass a timeout
if is_given(timeout):
print(f"Using custom timeout: {timeout}")
else:
print("Using default timeout")
Stripping NotGiven Values
from groq._utils import strip_not_given
from groq._types import NOT_GIVEN
params = {
"model": "llama-3.3-70b-versatile",
"temperature": NOT_GIVEN,
"max_tokens": 100,
}
cleaned = strip_not_given(params)
# {"model": "llama-3.3-70b-versatile", "max_tokens": 100}
Related Pages
