[Python] Generate .pyi stub files when --python-typing is on. (#8312)

* [Python] Generate `.pyi` stub files when `--python-typing` is on.

To support this change, the following modifications were made:

-  added a new option to disable `numpy` helpers generation;
-  added a new flag to control the target Python version:

   `--python-version` can be one of the following:

   - `0.x.x` – compatible with any Python version;
   - `2.x.x` – compatible with Python 2;
   - `3.x.x` – compatible with Python 3.
-  added codegen utilities for Python;
-  added a note that the generated .py file is empty.

* [Python] Update Bazel build rules.

* [Python] Update Bazel build rules.

* [Python] Run buildifier on BUILD.bazel files.

---------

Co-authored-by: Derek Bailey <derekbailey@google.com>

tests/FromInclude.py

@@ -2,3 +2,4 @@
 
 # namespace: OtherNameSpace
 
+# NOTE FromInclude.py does not declare any structs or enums

tests/MyGame/Example/ArrayStruct.pyi

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import flatbuffers
+import numpy as np
+
+import flatbuffers
+import typing
+from MyGame.Example.ArrayStruct import ArrayStruct
+from MyGame.Example.NestedStruct import NestedStruct, NestedStructT
+from MyGame.Example.TestEnum import TestEnum
+
+uoffset: typing.TypeAlias = flatbuffers.number_types.UOffsetTFlags.py_type
+
+class ArrayStruct(object):
+  @classmethod
+  def SizeOf(cls) -> int: ...
+
+  def Init(self, buf: bytes, pos: int) -> None: ...
+  def A(self) -> float: ...
+  def B(self, i: int) -> typing.List[int]: ...
+  def BAsNumpy(self) -> np.ndarray: ...
+  def BLength(self) -> int: ...
+  def BIsNone(self) -> bool: ...
+  def C(self) -> int: ...
+  def D(self, i: int) -> NestedStruct | None: ...
+  def DLength(self) -> int: ...
+  def DIsNone(self) -> bool: ...
+  def E(self) -> int: ...
+  def F(self, i: int) -> typing.List[int]: ...
+  def FAsNumpy(self) -> np.ndarray: ...
+  def FLength(self) -> int: ...
+  def FIsNone(self) -> bool: ...
+class ArrayStructT(object):
+  a: float
+  b: typing.List[int]
+  c: int
+  d: typing.List[NestedStructT]
+  e: int
+  f: typing.List[int]
+  @classmethod
+  def InitFromBuf(cls, buf: bytes, pos: int) -> ArrayStructT: ...
+  @classmethod
+  def InitFromPackedBuf(cls, buf: bytes, pos: int = 0) -> ArrayStructT: ...
+  @classmethod
+  def InitFromObj(cls, arrayStruct: ArrayStruct) -> ArrayStructT: ...
+  def _UnPack(self, arrayStruct: ArrayStruct) -> None: ...
+  def Pack(self, builder: flatbuffers.Builder) -> None: ...
+
+def CreateArrayStruct(builder: flatbuffers.Builder, a: float, b: int, c: int, d_a: int, d_b: typing.Literal[TestEnum.A, TestEnum.B, TestEnum.C], d_c: typing.Literal[TestEnum.A, TestEnum.B, TestEnum.C], d_d: int, e: int, f: int) -> uoffset: ...
+

tests/MyGame/Example/ArrayTable.pyi

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import flatbuffers
+import numpy as np
+
+import flatbuffers
+import typing
+from MyGame.Example.ArrayStruct import ArrayStruct, ArrayStructT
+from MyGame.Example.ArrayTable import ArrayTable
+
+uoffset: typing.TypeAlias = flatbuffers.number_types.UOffsetTFlags.py_type
+
+class ArrayTable(object):
+  @classmethod
+  def GetRootAs(cls, buf: bytes, offset: int) -> ArrayTable: ...
+  @classmethod
+  def GetRootAsArrayTable(cls, buf: bytes, offset: int) -> ArrayTable: ...
+  @classmethod
+  def ArrayTableBufferHasIdentifier(cls, buf: bytes, offset: int, size_prefixed: bool) -> bool: ...
+  def Init(self, buf: bytes, pos: int) -> None: ...
+  def A(self) -> ArrayStruct | None: ...
+class ArrayTableT(object):
+  a: ArrayStructT | None
+  @classmethod
+  def InitFromBuf(cls, buf: bytes, pos: int) -> ArrayTableT: ...
+  @classmethod
+  def InitFromPackedBuf(cls, buf: bytes, pos: int = 0) -> ArrayTableT: ...
+  @classmethod
+  def InitFromObj(cls, arrayTable: ArrayTable) -> ArrayTableT: ...
+  def _UnPack(self, arrayTable: ArrayTable) -> None: ...
+  def Pack(self, builder: flatbuffers.Builder) -> None: ...
+def ArrayTableStart(builder: flatbuffers.Builder) -> None: ...
+def Start(builder: flatbuffers.Builder) -> None: ...
+def ArrayTableAddA(builder: flatbuffers.Builder, a: uoffset) -> None: ...
+def ArrayTableEnd(builder: flatbuffers.Builder) -> uoffset: ...
+def End(builder: flatbuffers.Builder) -> uoffset: ...
+

tests/MyGame/Example/NestedStruct.pyi

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import flatbuffers
+import numpy as np
+
+import flatbuffers
+import typing
+from MyGame.Example.NestedStruct import NestedStruct
+from MyGame.Example.TestEnum import TestEnum
+
+uoffset: typing.TypeAlias = flatbuffers.number_types.UOffsetTFlags.py_type
+
+class NestedStruct(object):
+  @classmethod
+  def SizeOf(cls) -> int: ...
+
+  def Init(self, buf: bytes, pos: int) -> None: ...
+  def A(self, i: int) -> typing.List[int]: ...
+  def AAsNumpy(self) -> np.ndarray: ...
+  def ALength(self) -> int: ...
+  def AIsNone(self) -> bool: ...
+  def B(self) -> typing.Literal[TestEnum.A, TestEnum.B, TestEnum.C]: ...
+  def C(self, i: int) -> typing.Literal[TestEnum.A, TestEnum.B, TestEnum.C]: ...
+  def CAsNumpy(self) -> np.ndarray: ...
+  def CLength(self) -> int: ...
+  def CIsNone(self) -> bool: ...
+  def D(self, i: int) -> typing.List[int]: ...
+  def DAsNumpy(self) -> np.ndarray: ...
+  def DLength(self) -> int: ...
+  def DIsNone(self) -> bool: ...
+class NestedStructT(object):
+  a: typing.List[int]
+  b: typing.Literal[TestEnum.A, TestEnum.B, TestEnum.C]
+  c: typing.List[typing.Literal[TestEnum.A, TestEnum.B, TestEnum.C]]
+  d: typing.List[int]
+  @classmethod
+  def InitFromBuf(cls, buf: bytes, pos: int) -> NestedStructT: ...
+  @classmethod
+  def InitFromPackedBuf(cls, buf: bytes, pos: int = 0) -> NestedStructT: ...
+  @classmethod
+  def InitFromObj(cls, nestedStruct: NestedStruct) -> NestedStructT: ...
+  def _UnPack(self, nestedStruct: NestedStruct) -> None: ...
+  def Pack(self, builder: flatbuffers.Builder) -> None: ...
+
+def CreateNestedStruct(builder: flatbuffers.Builder, a: int, b: typing.Literal[TestEnum.A, TestEnum.B, TestEnum.C], c: typing.Literal[TestEnum.A, TestEnum.B, TestEnum.C], d: int) -> uoffset: ...
+

tests/MyGame/Example/NestedUnion/Any.pyi

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import flatbuffers
+import numpy as np
+
+import flatbuffers
+import typing
+from MyGame.Example.NestedUnion.Any import Any
+from MyGame.Example.NestedUnion.TestSimpleTableWithEnum import TestSimpleTableWithEnum
+from MyGame.Example.NestedUnion.Vec3 import Vec3
+from flatbuffers import table
+
+uoffset: typing.TypeAlias = flatbuffers.number_types.UOffsetTFlags.py_type
+
+class Any(object):
+  NONE: int
+  Vec3: int
+  TestSimpleTableWithEnum: int
+def AnyCreator(union_type: typing.Literal[Any.NONE, Any.Vec3, Any.TestSimpleTableWithEnum], table: table.Table) -> typing.Union[None, Vec3, TestSimpleTableWithEnum]: ...
+

tests/MyGame/Example/NestedUnion/Color.pyi

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import flatbuffers
+import numpy as np
+
+import flatbuffers
+import typing
+
+uoffset: typing.TypeAlias = flatbuffers.number_types.UOffsetTFlags.py_type
+
+class Color(object):
+  Red: int
+  Green: int
+  Blue: int
+

tests/MyGame/Example/NestedUnion/NestedUnionTest.pyi

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import flatbuffers
+import numpy as np
+
+import flatbuffers
+import typing
+from MyGame.Example.NestedUnion.Any import Any
+from MyGame.Example.NestedUnion.NestedUnionTest import NestedUnionTest
+from MyGame.Example.NestedUnion.TestSimpleTableWithEnum import TestSimpleTableWithEnumT
+from MyGame.Example.NestedUnion.Vec3 import Vec3T
+from flatbuffers import table
+
+uoffset: typing.TypeAlias = flatbuffers.number_types.UOffsetTFlags.py_type
+
+class NestedUnionTest(object):
+  @classmethod
+  def GetRootAs(cls, buf: bytes, offset: int) -> NestedUnionTest: ...
+  @classmethod
+  def GetRootAsNestedUnionTest(cls, buf: bytes, offset: int) -> NestedUnionTest: ...
+  def Init(self, buf: bytes, pos: int) -> None: ...
+  def Name(self) -> str | None: ...
+  def DataType(self) -> typing.Literal[Any.NONE, Any.Vec3, Any.TestSimpleTableWithEnum]: ...
+  def Data(self) -> table.Table | None: ...
+  def Id(self) -> int: ...
+class NestedUnionTestT(object):
+  name: str | None
+  dataType: typing.Literal[Any.NONE, Any.Vec3, Any.TestSimpleTableWithEnum]
+  data: typing.Union[None, Vec3T, TestSimpleTableWithEnumT]
+  id: int
+  @classmethod
+  def InitFromBuf(cls, buf: bytes, pos: int) -> NestedUnionTestT: ...
+  @classmethod
+  def InitFromPackedBuf(cls, buf: bytes, pos: int = 0) -> NestedUnionTestT: ...
+  @classmethod
+  def InitFromObj(cls, nestedUnionTest: NestedUnionTest) -> NestedUnionTestT: ...
+  def _UnPack(self, nestedUnionTest: NestedUnionTest) -> None: ...
+  def Pack(self, builder: flatbuffers.Builder) -> None: ...
+def NestedUnionTestStart(builder: flatbuffers.Builder) -> None: ...
+def Start(builder: flatbuffers.Builder) -> None: ...
+def NestedUnionTestAddName(builder: flatbuffers.Builder, name: uoffset) -> None: ...
+def NestedUnionTestAddDataType(builder: flatbuffers.Builder, dataType: typing.Literal[Any.NONE, Any.Vec3, Any.TestSimpleTableWithEnum]) -> None: ...
+def NestedUnionTestAddData(builder: flatbuffers.Builder, data: uoffset) -> None: ...
+def NestedUnionTestAddId(builder: flatbuffers.Builder, id: int) -> None: ...
+def NestedUnionTestEnd(builder: flatbuffers.Builder) -> uoffset: ...
+def End(builder: flatbuffers.Builder) -> uoffset: ...
+

tests/MyGame/Example/NestedUnion/Test.pyi

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import flatbuffers
+import numpy as np
+
+import flatbuffers
+import typing
+from MyGame.Example.NestedUnion.Test import Test
+
+uoffset: typing.TypeAlias = flatbuffers.number_types.UOffsetTFlags.py_type
+
+class Test(object):
+  @classmethod
+  def SizeOf(cls) -> int: ...
+
+  def Init(self, buf: bytes, pos: int) -> None: ...
+  def A(self) -> int: ...
+  def B(self) -> int: ...
+class TestT(object):
+  a: int
+  b: int
+  @classmethod
+  def InitFromBuf(cls, buf: bytes, pos: int) -> TestT: ...
+  @classmethod
+  def InitFromPackedBuf(cls, buf: bytes, pos: int = 0) -> TestT: ...
+  @classmethod
+  def InitFromObj(cls, test: Test) -> TestT: ...
+  def _UnPack(self, test: Test) -> None: ...
+  def Pack(self, builder: flatbuffers.Builder) -> None: ...
+
+def CreateTest(builder: flatbuffers.Builder, a: int, b: int) -> uoffset: ...
+

tests/MyGame/Example/NestedUnion/TestSimpleTableWithEnum.pyi

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import flatbuffers
+import numpy as np
+
+import flatbuffers
+import typing
+from MyGame.Example.NestedUnion.Color import Color
+from MyGame.Example.NestedUnion.TestSimpleTableWithEnum import TestSimpleTableWithEnum
+
+uoffset: typing.TypeAlias = flatbuffers.number_types.UOffsetTFlags.py_type
+
+class TestSimpleTableWithEnum(object):
+  @classmethod
+  def GetRootAs(cls, buf: bytes, offset: int) -> TestSimpleTableWithEnum: ...
+  @classmethod
+  def GetRootAsTestSimpleTableWithEnum(cls, buf: bytes, offset: int) -> TestSimpleTableWithEnum: ...
+  def Init(self, buf: bytes, pos: int) -> None: ...
+  def Color(self) -> typing.Literal[Color.Red, Color.Green, Color.Blue]: ...
+class TestSimpleTableWithEnumT(object):
+  color: typing.Literal[Color.Red, Color.Green, Color.Blue]
+  @classmethod
+  def InitFromBuf(cls, buf: bytes, pos: int) -> TestSimpleTableWithEnumT: ...
+  @classmethod
+  def InitFromPackedBuf(cls, buf: bytes, pos: int = 0) -> TestSimpleTableWithEnumT: ...
+  @classmethod
+  def InitFromObj(cls, testSimpleTableWithEnum: TestSimpleTableWithEnum) -> TestSimpleTableWithEnumT: ...
+  def _UnPack(self, testSimpleTableWithEnum: TestSimpleTableWithEnum) -> None: ...
+  def Pack(self, builder: flatbuffers.Builder) -> None: ...
+def TestSimpleTableWithEnumStart(builder: flatbuffers.Builder) -> None: ...
+def Start(builder: flatbuffers.Builder) -> None: ...
+def TestSimpleTableWithEnumAddColor(builder: flatbuffers.Builder, color: typing.Literal[Color.Red, Color.Green, Color.Blue]) -> None: ...
+def TestSimpleTableWithEnumEnd(builder: flatbuffers.Builder) -> uoffset: ...
+def End(builder: flatbuffers.Builder) -> uoffset: ...
+

tests/MyGame/Example/NestedUnion/Vec3.pyi

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import flatbuffers
+import numpy as np
+
+import flatbuffers
+import typing
+from MyGame.Example.NestedUnion.Color import Color
+from MyGame.Example.NestedUnion.Test import Test, TestT
+from MyGame.Example.NestedUnion.Vec3 import Vec3
+
+uoffset: typing.TypeAlias = flatbuffers.number_types.UOffsetTFlags.py_type
+
+class Vec3(object):
+  @classmethod
+  def GetRootAs(cls, buf: bytes, offset: int) -> Vec3: ...
+  @classmethod
+  def GetRootAsVec3(cls, buf: bytes, offset: int) -> Vec3: ...
+  def Init(self, buf: bytes, pos: int) -> None: ...
+  def X(self) -> float: ...
+  def Y(self) -> float: ...
+  def Z(self) -> float: ...
+  def Test1(self) -> float: ...
+  def Test2(self) -> typing.Literal[Color.Red, Color.Green, Color.Blue]: ...
+  def Test3(self) -> Test | None: ...
+class Vec3T(object):
+  x: float
+  y: float
+  z: float
+  test1: float
+  test2: typing.Literal[Color.Red, Color.Green, Color.Blue]
+  test3: TestT | None
+  @classmethod
+  def InitFromBuf(cls, buf: bytes, pos: int) -> Vec3T: ...
+  @classmethod
+  def InitFromPackedBuf(cls, buf: bytes, pos: int = 0) -> Vec3T: ...
+  @classmethod
+  def InitFromObj(cls, vec3: Vec3) -> Vec3T: ...
+  def _UnPack(self, vec3: Vec3) -> None: ...
+  def Pack(self, builder: flatbuffers.Builder) -> None: ...
+def Vec3Start(builder: flatbuffers.Builder) -> None: ...
+def Start(builder: flatbuffers.Builder) -> None: ...
+def Vec3AddX(builder: flatbuffers.Builder, x: float) -> None: ...
+def Vec3AddY(builder: flatbuffers.Builder, y: float) -> None: ...
+def Vec3AddZ(builder: flatbuffers.Builder, z: float) -> None: ...
+def Vec3AddTest1(builder: flatbuffers.Builder, test1: float) -> None: ...
+def Vec3AddTest2(builder: flatbuffers.Builder, test2: typing.Literal[Color.Red, Color.Green, Color.Blue]) -> None: ...
+def Vec3AddTest3(builder: flatbuffers.Builder, test3: uoffset) -> None: ...
+def Vec3End(builder: flatbuffers.Builder) -> uoffset: ...
+def End(builder: flatbuffers.Builder) -> uoffset: ...
+

tests/MyGame/Example/TestEnum.pyi

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import flatbuffers
+import numpy as np
+
+import flatbuffers
+import typing
+
+uoffset: typing.TypeAlias = flatbuffers.number_types.UOffsetTFlags.py_type
+
+class TestEnum(object):
+  A: int
+  B: int
+  C: int
+

tests/MyGame/MonsterExtra.pyi

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import flatbuffers
+import numpy as np
+
+import flatbuffers
+import typing
+from MyGame.MonsterExtra import MonsterExtra
+
+uoffset: typing.TypeAlias = flatbuffers.number_types.UOffsetTFlags.py_type
+
+class MonsterExtra(object):
+  @classmethod
+  def GetRootAs(cls, buf: bytes, offset: int) -> MonsterExtra: ...
+  @classmethod
+  def GetRootAsMonsterExtra(cls, buf: bytes, offset: int) -> MonsterExtra: ...
+  @classmethod
+  def MonsterExtraBufferHasIdentifier(cls, buf: bytes, offset: int, size_prefixed: bool) -> bool: ...
+  def Init(self, buf: bytes, pos: int) -> None: ...
+  def D0(self) -> float: ...
+  def D1(self) -> float: ...
+  def D2(self) -> float: ...
+  def D3(self) -> float: ...
+  def F0(self) -> float: ...
+  def F1(self) -> float: ...
+  def F2(self) -> float: ...
+  def F3(self) -> float: ...
+  def Dvec(self, i: int) -> typing.List[float]: ...
+  def DvecAsNumpy(self) -> np.ndarray: ...
+  def DvecLength(self) -> int: ...
+  def DvecIsNone(self) -> bool: ...
+  def Fvec(self, i: int) -> typing.List[float]: ...
+  def FvecAsNumpy(self) -> np.ndarray: ...
+  def FvecLength(self) -> int: ...
+  def FvecIsNone(self) -> bool: ...
+class MonsterExtraT(object):
+  d0: float
+  d1: float
+  d2: float
+  d3: float
+  f0: float
+  f1: float
+  f2: float
+  f3: float
+  dvec: typing.List[float]
+  fvec: typing.List[float]
+  @classmethod
+  def InitFromBuf(cls, buf: bytes, pos: int) -> MonsterExtraT: ...
+  @classmethod
+  def InitFromPackedBuf(cls, buf: bytes, pos: int = 0) -> MonsterExtraT: ...
+  @classmethod
+  def InitFromObj(cls, monsterExtra: MonsterExtra) -> MonsterExtraT: ...
+  def _UnPack(self, monsterExtra: MonsterExtra) -> None: ...
+  def Pack(self, builder: flatbuffers.Builder) -> None: ...
+  def __eq__(self, other: MonsterExtraT) -> bool: ...
+def MonsterExtraStart(builder: flatbuffers.Builder) -> None: ...
+def Start(builder: flatbuffers.Builder) -> None: ...
+def MonsterExtraAddD0(builder: flatbuffers.Builder, d0: float) -> None: ...
+def MonsterExtraAddD1(builder: flatbuffers.Builder, d1: float) -> None: ...
+def MonsterExtraAddD2(builder: flatbuffers.Builder, d2: float) -> None: ...
+def MonsterExtraAddD3(builder: flatbuffers.Builder, d3: float) -> None: ...
+def MonsterExtraAddF0(builder: flatbuffers.Builder, f0: float) -> None: ...
+def MonsterExtraAddF1(builder: flatbuffers.Builder, f1: float) -> None: ...
+def MonsterExtraAddF2(builder: flatbuffers.Builder, f2: float) -> None: ...
+def MonsterExtraAddF3(builder: flatbuffers.Builder, f3: float) -> None: ...
+def MonsterExtraAddDvec(builder: flatbuffers.Builder, dvec: uoffset) -> None: ...
+def MonsterExtraStartDvecVector(builder: flatbuffers.Builder, num_elems: int) -> uoffset: ...
+def StartDvecVector(builder: flatbuffers.Builder, num_elems: int) -> uoffset: ...
+def MonsterExtraAddFvec(builder: flatbuffers.Builder, fvec: uoffset) -> None: ...
+def MonsterExtraStartFvecVector(builder: flatbuffers.Builder, num_elems: int) -> uoffset: ...
+def StartFvecVector(builder: flatbuffers.Builder, num_elems: int) -> uoffset: ...
+def MonsterExtraEnd(builder: flatbuffers.Builder) -> uoffset: ...
+def End(builder: flatbuffers.Builder) -> uoffset: ...
+

tests/MyGame/OtherNameSpace/FromInclude.py

@@ -2,3 +2,4 @@
 
 # namespace: OtherNameSpace
 
+# NOTE FromInclude.py does not declare any structs or enums

tests/MyGame/OtherNameSpace/TableB.py

@@ -2,3 +2,4 @@
 
 # namespace: OtherNameSpace
 
+# NOTE TableB.py does not declare any structs or enums

tests/MyGame/OtherNameSpace/Unused.py

@@ -2,3 +2,4 @@
 
 # namespace: OtherNameSpace
 
+# NOTE Unused.py does not declare any structs or enums

tests/TableA.py

@@ -2,3 +2,4 @@
 
 # namespace: 
 
+# NOTE TableA.py does not declare any structs or enums