Implementation:Eventual Inc Daft Api Annotations
| Knowledge Sources | |
|---|---|
| Domains | API_Design, Type_Safety |
| Last Updated | 2026-02-08 14:00 GMT |
Overview
Concrete tool for marking and protecting Daft public API boundaries with runtime type checking and clean traceback management.
Description
The api_annotations module provides two decorator functions, PublicAPI and DataframePublicAPI, that wrap public-facing functions with runtime type checking against their type annotations. It also defines type_check_function, which introspects function signatures and validates argument types at call time, supporting Union types, Literal types, generic containers, Callable types, and variadic arguments. The decorators also clean up tracebacks for better user-facing error messages.
Usage
Apply `@PublicAPI` or `@DataframePublicAPI` to any function that is part of the Daft public API surface. These decorators enforce that callers pass correctly-typed arguments, raising `APITypeError` on mismatch.
Code Reference
Source Location
- Repository: Eventual_Inc_Daft
- File: daft/api_annotations.py
- Lines: 1-154
Signature
def PublicAPI(func: Callable[P, T]) -> Callable[P, T]:
"""A decorator to mark a function as part of the Daft public API."""
def DataframePublicAPI(func: Callable[P, T]) -> Callable[P, T]:
"""A decorator to mark a function as part of the Daft DataFrame's public API."""
def type_check_function(func: Callable[..., Any], *args: Any, **kwargs: Any) -> None:
"""Runtime type checking of function arguments against annotations."""
class APITypeError(TypeError):
"""Raised when a public API receives incorrectly typed arguments."""
Import
from daft.api_annotations import PublicAPI, DataframePublicAPI, APITypeError
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| func | Callable | Yes | The function to decorate with runtime type checking |
Outputs
| Name | Type | Description |
|---|---|---|
| decorated function | Callable | Same function signature, with added type validation on each call |
| APITypeError | Exception | Raised when argument types do not match annotations |
Usage Examples
Applying the Decorator
from daft.api_annotations import PublicAPI
@PublicAPI
def read_data(path: str, limit: int = 100) -> list:
"""Example public API function."""
return []
# Valid call
read_data("/data/file.parquet", limit=50)
# Invalid call - raises APITypeError
try:
read_data(123) # path must be str
except TypeError as e:
print(e)