Add type annotations to fdb Python bindings (PEP 561) by sah-rohan · Pull Request #13241 · apple/foundationdb

sah-rohan · 2026-05-19T16:04:37Z

Problem

Addresses issue #11331. The fdb Python bindings ship without type annotations and without a py.typed marker. Downstream users get no help from mypy, pyright, or IDEs when calling the public API, and even if annotations existed they would be ignored by PEP 561-compliant type checkers (which require an explicit py.typed file to trust inline annotations from a third-party package).

Solution

Add an empty fdb/py.typed marker file and wire it into the sdist/wheel via [tool.setuptools.package-data] in pyproject.toml (PEP 561).
Annotate the public surface of fdb/impl.py, fdb/tuple.py, fdb/subspace_impl.py, and fdb/locality.py.
Introduce a TupleElement type alias in fdb/tuple.py covering the values the tuple layer can pack (None | bytes | str | int | float | bool | uuid.UUID | SingleFloat | Versionstamp | nested tuple/list), and use it in pack, pack_with_versionstamp, unpack, range, has_incomplete_versionstamp, compare, and across Subspace.
Use from __future__ import annotations so all annotations are strings at runtime — zero runtime cost, no import-order issues.

Where `Any` is intentionally retained

A few annotations remain Any on purpose:

Future.wait() / Future.result() return type — Future is a generic base class; concrete subclasses (FutureInt64, FutureString, FutureKeyValueArray, …) already return narrower types.
keyToBytes(k) / valueToBytes(v) parameters — duck-typed via the as_foundationdb_key / as_foundationdb_value protocol. Tightening these would require introducing a typing.Protocol; happy to do that in a follow-up.
tpointer / fpointer / dpointer constructor params on TransactionRead, Transaction, Future, Database — the codebase passes a mix of int, Optional[int] (from c_void_p().value), and raw ctypes.c_void_p to these. A single accurate type would require touching call sites, which expands scope.
*args: Any, **kwargs: Any in Transaction.get_range_startswith — pure forwarding to get_range.

Testing

Ran mypy against both main and this branch using:

…tion

…l, drop unused imports

xis19

Thanks for the implementation!

xis19 · 2026-05-20T19:35:54Z

        )

-    def set(self, key, value):
+    def set(self, key: Any, value: Any) -> None:


I would feel bringing a Protocol might be helpful, e.g.

class IFoundationDBKey: def as_foundationdb_key(self) -> bytes: pass

and key: Union[IFoundationDBKey, bytes]

Not sure if IFoundationDBKey is good but not a native English speaker, so do not know if there is any better choices.

I've introduced IFoundationDBKey and IFoundationDBValue as @runtime_checkable Protocols so the type reflects the actual duck-typing contract the code uses. All key/value parameters now use KeyType = Union[bytes, IFoundationDBKey] and ValueType = Union[bytes, IFoundationDBValue].

xis19 · 2026-05-20T19:38:21Z


-    def __init__(self, fpointer):
+    def __init__(self, fpointer: Any) -> None:
        # print("Creating future 0x%x" % fpointer)


Maybe help removing those debugging prints? Or use logging.Logger?

the commented-out debug prints in Future.init and del have been removed.

xis19 · 2026-05-20T19:39:10Z

-    def on_ready(self, callback):
-        def cb_and_delref(ignore):
+    def on_ready(self, callback: Callable[[Future], None]) -> None:
+        def cb_and_delref(ignore: object) -> None:


object to Any?

Oh, maybe just _ignore: Any?

as a matter of fact I guess this depends on type safety as stated in docs:

Use object to indicate that a value could be any type in a typesafe manner. Use Any to indicate that a value is dynamically typed.

Not sure here the ignore is type safe though.

Changed _ignore: Any → _ignore: object in both cb_and_delref and wait_for_any's closure

xis19 · 2026-05-20T19:44:38Z

        for i, f in enumerate(futures):

-            def cb(ignore, i=i):
+            def cb(ignore: object, i: int = i) -> None:


maybe rename the arg i to something else? should be better than shadowing variable

renamed to idx

xis19 · 2026-05-20T19:45:08Z

        self.on_ready(lambda f: self.call_soon_threadsafe(fn, f))

-    def remove_done_callback(self, fn):
+    def remove_done_callback(self, fn: Callable[[Future], None]) -> None:


@abc.abstractmethod?

Yes, it should be and I marked it @abc.abstractmethod to match wait(). It always raises NotImplementedError and none of the concrete subclasses (FutureVoid, FutureInt64, etc.) implement it, so making it abstract is the right signal."

xis19 · 2026-05-20T19:50:11Z


 class KeySelector(object):
-    def __init__(self, key, or_equal, offset):
+    key: bytes


I am confused about this...

That was a class-level instance variable annotation (PEP 526) that I had added above init, which the diff view made look like it was inside the method body. It was actually redundant as type checkers already infer self.key: bytes from the init parameter annotation, so I've removed the class-level declarations and kept only the init parameter annotations. Sorry for the confusion in the diff!

xis19 · 2026-05-20T20:08:08Z

 import fdb

+# Type alias for values that can be packed into a tuple
+TupleElement = Union[


TupleElement: TypeAlias = Union[ ...

Used TupleElement: TypeAlias = Union[...] directly. Since TypeAlias was added in Python 3.10 and we support 3.8+, I added a sys.version_info guard with a fallback to typing_extensions, and added typing_extensions>=4.0 as a conditional dependency in pyproject.toml

xis19 · 2026-05-20T20:11:37Z

    _UNSET_TR_VERSION = 10 * int2byte(0xFF)
    _STRUCT_FORMAT_STRING = ">" + str(_TR_VERSION_LEN) + "sH"

+    tr_version: Optional[bytes]


Not sure we need classvar?

The class-level constants (LENGTH, _TR_VERSION_LEN, _MAX_USER_VERSION, etc.) are now annotated with ClassVar[int]/ClassVar[bytes]/ClassVar[str] as appropriate. The tr_version and user_version fields are instance variables (set in init) so they do not use ClassVar, They're declared as plain instance variable annotations in the class body.

xis19 · 2026-06-02T02:02:17Z

lgtm

sah-rohan · 2026-06-02T21:39:39Z

Hi @xis19 — thanks for the review! Would you be able to submit a formal approval?

sah-rohan added 14 commits May 19, 2026 10:16

import typing

e30e755

typing on impl

29c7d09

typing on locality.py

48ec97b

typing on subspace_imp.py

a3fd14c

typing on typle.py

646b52f

Any to TupleElement type

375602b

restrict py-modules from cmake build directory to avoid misidentifica…

2a59bbf

…tion

Fixed any types to int

a25dce5

Any to TupleElement

5e9be2e

tpointer => back to Any

7c8f1c2

add py.typed

9b42c01

Address review: widen Any on duck-typed key/value params, fix Optiona…

e76b042

…l, drop unused imports

formatting changes

8a84178

formatting

94982e0

xis19 reviewed May 20, 2026

View reviewed changes

sah-rohan added 7 commits May 20, 2026 21:37

remove python del funcion

fbdcbfa

Add type annotations to FDB Python bindings

0d73a6a

type rawPrefit

0fc065b

typedalias

5f3b005

added type extension dependency

61ee990

IFoundation protocols+typing

e2e5e73

TypeAlias + Instance variables

f19f4ff

Conversation

sah-rohan commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

Where Any is intentionally retained

Testing

Uh oh!

xis19 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sah-rohan May 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sah-rohan May 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sah-rohan May 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sah-rohan May 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xis19 commented Jun 2, 2026

Uh oh!

sah-rohan commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sah-rohan commented May 19, 2026 •

edited

Loading

Where `Any` is intentionally retained

sah-rohan May 23, 2026 •

edited

Loading

sah-rohan May 23, 2026 •

edited

Loading

sah-rohan May 23, 2026 •

edited

Loading

sah-rohan May 23, 2026 •

edited

Loading

sah-rohan commented Jun 2, 2026 •

edited

Loading