google / google/flatbuffers

[Python] Generated type stubs don't work

Open
#9,224 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
C++
Stars
26.5k
Forks
3.7k
PR merge metrics
No merged PRs in 30d

Description

Given a very simple FlatBuffer definition:

```fbs
table Foo {
bar: string;
baz: int64;
}

root_type Foo;
```

The generated type stubs (`flatc --python --python-typing foo.fbs`) include an incorrect alias to `uoffset`:

```py
from __future__ import annotations

import flatbuffers
import numpy as np

import typing

uoffset: typing.TypeAlias = flatbuffers.number_types.UOffsetTFlags.py_type
```

1. The corresponding `Foo.py` file does not define an `uoffset` alias.
```py
>>> from Foo import uoffset
Traceback (most recent call last):
File "", line 1, in
from Foo import uoffset
ImportError: cannot import name 'uoffset' from 'Foo' (/.../Foo.py)
```
2. `flatbuffers.number_types` is not accessible with a simple `import flatbuffers`, as [flatbuffers/\_\_init\_\_.py](https://github.com/google/flatbuffers/blob/master/python/flatbuffers/__init__.py) doesn't re-export `number_types`. An explicit `import flatbuffers.number_types` is needed.
3. The stub adds an unconditional `import numpy as np`, which breaks type checking when numpy is not installed.

Tested with Python 3.14.7, Pyright 1.1.411 and flatbuffers/flatc 25.12.19.

Contributor guide

Open the contributing guide

Research direction

Start by reproducing the output from `flatc --python --python-typing` with the minimal `Foo` schema, then compare the generated stub with `Foo.py` and inspect `python/flatbuffers/__init__.py`. Check the generated imports and aliases under type checking without numpy installed; done means the stub matches the generated module and works with the stated dependencies.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp, python
Domain
tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.