googleapis / googleapis/python-genai

Missing optional dependency group for pillow causes static analysis failures on PartUnion

Open
#1,761 1 comment 0 reactions 1 assignee Assigned to @kkorpal View on GitHub
priority: p2 type: feature request
Dominant language
Python
Stars
4k
Forks
1k
Avg merge
2d 11h
Merged PRs (30d)
40

Description

## Summary

In version 0.7.0, `pillow` was removed as a mandatory dependency to lighten the package footprint. However, it was not added back as an optional dependency group in `pyproject.toml`.

This causes significant issues for consumers using strict static type checking (Pyright/MyPy). Because `types.py` imports `PIL.Image` inside a `if typing.TYPE_CHECKING:` block, type checkers attempt to resolve it regardless of runtime installation. If `pillow` is missing from the environment, `PIL.Image` resolves to `Unknown`, causing `PartUnion` to become "tainted" (e.g., `Union[str, Unknown, File, Part]`), leading to cascading type errors in consumer code.

## The Problem

1. `pyproject.toml` currently defines `aiohttp` and `local-tokenizer` in `[project.optional-dependencies]`, but lacks a group for images.

2. There is no programmatic way (standard dependency group) to signal to a dev environment that `pillow` should be installed to satisfy the type hints in `types.py`.

3. Users are left debugging cryptic "Unknown type" errors until they manually discover that `pillow` is required for type safety, even if they don't use image features at runtime.

**Relevant Code** In `google/genai/types.py`:

Python

```
if typing.TYPE_CHECKING:
from ._api_client import BaseApiClient
import PIL.Image # <--- Type checker sees this and fails if not installed
```

And `pyproject.toml` (missing the group):

```
[project.optional-dependencies]
aiohttp = ["aiohttp<4.0.0"]
local-tokenizer = ["sentencepiece>=0.2.0", "protobuf"]
# Missing: images = ["pillow"]
```

**Proposed Solution** Please add an optional dependency group for `pillow` in `pyproject.toml`. This is standard practice for optional features and allows users to install `pip install google-genai[images]` to resolve type checking issues and ensure their environments are set up correctly.

**Suggested Change to `pyproject.toml`**

```
[project.optional-dependencies]
aiohttp = ["aiohttp<4.0.0"]
local-tokenizer = ["sentencepiece>=0.2.0", "protobuf"]
images = ["pillow"]
```

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.