Principle:Groq Groq python Request Option Types
| Knowledge Sources | |
|---|---|
| Domains | SDK_Infrastructure, Type_System |
| Last Updated | 2026-02-15 16:00 GMT |
Overview
Principle governing the definition of sentinel types, request configuration structures, and file upload type unions that form the SDK's type foundation.
Description
Every API SDK needs a type layer that precisely models the possible states of request parameters. Request Option Types defines this foundation through: sentinel types (NotGiven, Omit) that encode the three-state logic of "not provided / provided as None / provided with value"; a RequestOptions TypedDict that allows per-request overrides of client-level defaults (headers, timeouts, retries); and a FileTypes union that captures all valid forms of file upload input (raw bytes, file objects, tuples with optional filename and content-type). This type layer enables both static type checking and runtime behavior that correctly handles parameter absence.
Usage
Apply this principle when designing typed Python SDKs where parameters can be meaningfully absent (not just None), where users need per-request configuration overrides, and where file uploads must accept multiple input formats.
Theoretical Basis
The three-state parameter pattern addresses a fundamental limitation of Python's default parameter system:
# Problem: None is ambiguous
def method(timeout=None): # Is None "no timeout" or "not specified"?
# Solution: Sentinel type
def method(timeout: float | None | NotGiven = NOT_GIVEN):
# NOT_GIVEN -> use client default
# None -> explicitly no timeout
# float -> use this value
The RequestOptions pattern provides a structured way to override client defaults at the request level without polluting the domain-specific API parameters.