[Python] Improve python API

- Make the Python API similar to Rust and Swift for improved usability
- Make StartVector vector public since it is already being used in
  generated code
- Also fix script path in warning

Author: satur9nine

docs/source/tutorial.md

@@ -1134,12 +1134,8 @@ The Builder provides multiple ways to create `vectors`.
 === "Python"
 
     ```py
-    # Create a FlatBuffer vector and prepend the weapons.
-    # Note: Since we prepend the data, prepend them in reverse order.
-    MyGame.Sample.Monster.StartWeaponsVector(builder, 2)
-    builder.PrependUOffsetTRelative(axe)
-    builder.PrependUOffsetTRelative(sword)
-    weapons = builder.EndVector()
+    # Use the generated helper to create the weapons vector from offsets.
+    weapons = MyGame.Sample.Monster.CreateWeaponsVector(builder, [sword, axe])
     ```
 
 === "Rust"
@@ -1352,16 +1348,13 @@ bit more directly.
     ```py
     # Create a `vector` representing the inventory of the Orc. Each number
     # could correspond to an item that can be claimed after he is slain.
-    # Note: Since we prepend the bytes, this loop iterates in reverse.
-    MyGame.Sample.Monster.StartInventoryVector(builder, 10)
-    for i in reversed(range(0, 10)):
-        builder.PrependByte(i)
-    inv = builder.EndVector()
-
-    MyGame.Sample.Monster.StartPathVector(builder, 2)
-    MyGame.Sample.Vec3.CreateVec3(builder, 1.0, 2.0, 3.0)
-    MyGame.Sample.Vec3.CreateVec3(builder, 4.0, 5.0, 6.0)
-    path = builder.EndVector()
+    inv = MyGame.Sample.Monster.CreateInventoryVector(builder, range(0, 10))
+
+    path_points = [
+        MyGame.Sample.Vec3T(x=1.0, y=2.0, z=3.0),
+        MyGame.Sample.Vec3T(x=4.0, y=5.0, z=6.0),
+    ]
+    path = MyGame.Sample.Monster.CreatePathVector(builder, path_points)
     ```
 
 === "Rust"

python/flatbuffers/builder.py

@@ -415,7 +415,6 @@ def PrependUOffsetTRelative(self, off):
     off2 = self.Offset() - off + N.UOffsetTFlags.bytewidth
     self.PlaceUOffsetT(off2)
 
-  ## @cond FLATBUFFERS_INTERNAL
   def StartVector(self, elemSize, numElems, alignment):
     """StartVector initializes bookkeeping for writing a new vector.
 
@@ -431,8 +430,6 @@ def StartVector(self, elemSize, numElems, alignment):
     self.Prep(alignment, elemSize * numElems)  # In case alignment > int.
     return self.Offset()
 
-  ## @endcond
-
   def EndVector(self, numElems=None):
     """EndVector writes data necessary to finish vector construction."""
 
@@ -550,6 +547,21 @@ def CreateNumpyVector(self, x):
     self.vectorNumElems = x.size
     return self.EndVector()
 
+  def CreateVectorOfTables(self, offsets):
+    """CreateVectorOfTables writes a vector of offsets such as tables or strings.
+
+    Args:
+      offsets: Iterable of offsets returned from previous builder operations.
+               Each element should be an integer compatible with UOffsetT.
+    """
+
+    offsets = list(offsets)
+    self.StartVector(N.UOffsetTFlags.bytewidth, len(offsets),
+                     N.UOffsetTFlags.bytewidth)
+    for off in reversed(offsets):
+      self.PrependUOffsetTRelative(off)
+    return self.EndVector()
+
   ## @cond FLATBUFFERS_INTERNAL
   def assertNested(self):
     """Check that we are in the process of building an object."""

python/flatbuffers/reflection/Enum.py

@@ -155,6 +155,12 @@ def EnumStartValuesVector(builder, numElems):
 def StartValuesVector(builder, numElems):
     return EnumStartValuesVector(builder, numElems)
 
+def EnumCreateValuesVector(builder, data):
+    return builder.CreateVectorOfTables(data)
+
+def CreateValuesVector(builder, data):
+    EnumCreateValuesVector(builder, data)
+
 def EnumAddIsUnion(builder, isUnion):
     builder.PrependBoolSlot(2, isUnion, 0)
 
@@ -179,6 +185,12 @@ def EnumStartAttributesVector(builder, numElems):
 def StartAttributesVector(builder, numElems):
     return EnumStartAttributesVector(builder, numElems)
 
+def EnumCreateAttributesVector(builder, data):
+    return builder.CreateVectorOfTables(data)
+
+def CreateAttributesVector(builder, data):
+    EnumCreateAttributesVector(builder, data)
+
 def EnumAddDocumentation(builder, documentation):
     builder.PrependUOffsetTRelativeSlot(5, flatbuffers.number_types.UOffsetTFlags.py_type(documentation), 0)
 
@@ -191,6 +203,12 @@ def EnumStartDocumentationVector(builder, numElems):
 def StartDocumentationVector(builder, numElems):
     return EnumStartDocumentationVector(builder, numElems)
 
+def EnumCreateDocumentationVector(builder, data):
+    return builder.CreateVectorOfTables(data)
+
+def CreateDocumentationVector(builder, data):
+    EnumCreateDocumentationVector(builder, data)
+
 def EnumAddDeclarationFile(builder, declarationFile):
     builder.PrependUOffsetTRelativeSlot(6, flatbuffers.number_types.UOffsetTFlags.py_type(declarationFile), 0)
 

python/flatbuffers/reflection/EnumVal.py

@@ -134,6 +134,12 @@ def EnumValStartDocumentationVector(builder, numElems):
 def StartDocumentationVector(builder, numElems):
     return EnumValStartDocumentationVector(builder, numElems)
 
+def EnumValCreateDocumentationVector(builder, data):
+    return builder.CreateVectorOfTables(data)
+
+def CreateDocumentationVector(builder, data):
+    EnumValCreateDocumentationVector(builder, data)
+
 def EnumValAddAttributes(builder, attributes):
     builder.PrependUOffsetTRelativeSlot(5, flatbuffers.number_types.UOffsetTFlags.py_type(attributes), 0)
 
@@ -146,6 +152,12 @@ def EnumValStartAttributesVector(builder, numElems):
 def StartAttributesVector(builder, numElems):
     return EnumValStartAttributesVector(builder, numElems)
 
+def EnumValCreateAttributesVector(builder, data):
+    return builder.CreateVectorOfTables(data)
+
+def CreateAttributesVector(builder, data):
+    EnumValCreateAttributesVector(builder, data)
+
 def EnumValEnd(builder):
     return builder.EndObject()
 

python/flatbuffers/reflection/Field.py

@@ -235,6 +235,12 @@ def FieldStartAttributesVector(builder, numElems):
 def StartAttributesVector(builder, numElems):
     return FieldStartAttributesVector(builder, numElems)
 
+def FieldCreateAttributesVector(builder, data):
+    return builder.CreateVectorOfTables(data)
+
+def CreateAttributesVector(builder, data):
+    FieldCreateAttributesVector(builder, data)
+
 def FieldAddDocumentation(builder, documentation):
     builder.PrependUOffsetTRelativeSlot(10, flatbuffers.number_types.UOffsetTFlags.py_type(documentation), 0)
 
@@ -247,6 +253,12 @@ def FieldStartDocumentationVector(builder, numElems):
 def StartDocumentationVector(builder, numElems):
     return FieldStartDocumentationVector(builder, numElems)
 
+def FieldCreateDocumentationVector(builder, data):
+    return builder.CreateVectorOfTables(data)
+
+def CreateDocumentationVector(builder, data):
+    FieldCreateDocumentationVector(builder, data)
+
 def FieldAddOptional(builder, optional):
     builder.PrependBoolSlot(11, optional, 0)
 

python/flatbuffers/reflection/Object.py

@@ -158,6 +158,12 @@ def ObjectStartFieldsVector(builder, numElems):
 def StartFieldsVector(builder, numElems):
     return ObjectStartFieldsVector(builder, numElems)
 
+def ObjectCreateFieldsVector(builder, data):
+    return builder.CreateVectorOfTables(data)
+
+def CreateFieldsVector(builder, data):
+    ObjectCreateFieldsVector(builder, data)
+
 def ObjectAddIsStruct(builder, isStruct):
     builder.PrependBoolSlot(2, isStruct, 0)
 
@@ -188,6 +194,12 @@ def ObjectStartAttributesVector(builder, numElems):
 def StartAttributesVector(builder, numElems):
     return ObjectStartAttributesVector(builder, numElems)
 
+def ObjectCreateAttributesVector(builder, data):
+    return builder.CreateVectorOfTables(data)
+
+def CreateAttributesVector(builder, data):
+    ObjectCreateAttributesVector(builder, data)
+
 def ObjectAddDocumentation(builder, documentation):
     builder.PrependUOffsetTRelativeSlot(6, flatbuffers.number_types.UOffsetTFlags.py_type(documentation), 0)
 
@@ -200,6 +212,12 @@ def ObjectStartDocumentationVector(builder, numElems):
 def StartDocumentationVector(builder, numElems):
     return ObjectStartDocumentationVector(builder, numElems)
 
+def ObjectCreateDocumentationVector(builder, data):
+    return builder.CreateVectorOfTables(data)
+
+def CreateDocumentationVector(builder, data):
+    ObjectCreateDocumentationVector(builder, data)
+
 def ObjectAddDeclarationFile(builder, declarationFile):
     builder.PrependUOffsetTRelativeSlot(7, flatbuffers.number_types.UOffsetTFlags.py_type(declarationFile), 0)
 

python/flatbuffers/reflection/RPCCall.py

@@ -138,6 +138,12 @@ def RPCCallStartAttributesVector(builder, numElems):
 def StartAttributesVector(builder, numElems):
     return RPCCallStartAttributesVector(builder, numElems)
 
+def RPCCallCreateAttributesVector(builder, data):
+    return builder.CreateVectorOfTables(data)
+
+def CreateAttributesVector(builder, data):
+    RPCCallCreateAttributesVector(builder, data)
+
 def RPCCallAddDocumentation(builder, documentation):
     builder.PrependUOffsetTRelativeSlot(4, flatbuffers.number_types.UOffsetTFlags.py_type(documentation), 0)
 
@@ -150,6 +156,12 @@ def RPCCallStartDocumentationVector(builder, numElems):
 def StartDocumentationVector(builder, numElems):
     return RPCCallStartDocumentationVector(builder, numElems)
 
+def RPCCallCreateDocumentationVector(builder, data):
+    return builder.CreateVectorOfTables(data)
+
+def CreateDocumentationVector(builder, data):
+    RPCCallCreateDocumentationVector(builder, data)
+
 def RPCCallEnd(builder):
     return builder.EndObject()
 

python/flatbuffers/reflection/Schema.py

@@ -180,6 +180,12 @@ def SchemaStartObjectsVector(builder, numElems):
 def StartObjectsVector(builder, numElems):
     return SchemaStartObjectsVector(builder, numElems)
 
+def SchemaCreateObjectsVector(builder, data):
+    return builder.CreateVectorOfTables(data)
+
+def CreateObjectsVector(builder, data):
+    SchemaCreateObjectsVector(builder, data)
+
 def SchemaAddEnums(builder, enums):
     builder.PrependUOffsetTRelativeSlot(1, flatbuffers.number_types.UOffsetTFlags.py_type(enums), 0)
 
@@ -192,6 +198,12 @@ def SchemaStartEnumsVector(builder, numElems):
 def StartEnumsVector(builder, numElems):
     return SchemaStartEnumsVector(builder, numElems)
 
+def SchemaCreateEnumsVector(builder, data):
+    return builder.CreateVectorOfTables(data)
+
+def CreateEnumsVector(builder, data):
+    SchemaCreateEnumsVector(builder, data)
+
 def SchemaAddFileIdent(builder, fileIdent):
     builder.PrependUOffsetTRelativeSlot(2, flatbuffers.number_types.UOffsetTFlags.py_type(fileIdent), 0)
 
@@ -222,6 +234,12 @@ def SchemaStartServicesVector(builder, numElems):
 def StartServicesVector(builder, numElems):
     return SchemaStartServicesVector(builder, numElems)
 
+def SchemaCreateServicesVector(builder, data):
+    return builder.CreateVectorOfTables(data)
+
+def CreateServicesVector(builder, data):
+    SchemaCreateServicesVector(builder, data)
+
 def SchemaAddAdvancedFeatures(builder, advancedFeatures):
     builder.PrependUint64Slot(6, advancedFeatures, 0)
 
@@ -240,6 +258,12 @@ def SchemaStartFbsFilesVector(builder, numElems):
 def StartFbsFilesVector(builder, numElems):
     return SchemaStartFbsFilesVector(builder, numElems)
 
+def SchemaCreateFbsFilesVector(builder, data):
+    return builder.CreateVectorOfTables(data)
+
+def CreateFbsFilesVector(builder, data):
+    SchemaCreateFbsFilesVector(builder, data)
+
 def SchemaEnd(builder):
     return builder.EndObject()
 

python/flatbuffers/reflection/SchemaFile.py

@@ -84,6 +84,12 @@ def SchemaFileStartIncludedFilenamesVector(builder, numElems):
 def StartIncludedFilenamesVector(builder, numElems):
     return SchemaFileStartIncludedFilenamesVector(builder, numElems)
 
+def SchemaFileCreateIncludedFilenamesVector(builder, data):
+    return builder.CreateVectorOfTables(data)
+
+def CreateIncludedFilenamesVector(builder, data):
+    SchemaFileCreateIncludedFilenamesVector(builder, data)
+
 def SchemaFileEnd(builder):
     return builder.EndObject()
 

python/flatbuffers/reflection/Service.py

@@ -137,6 +137,12 @@ def ServiceStartCallsVector(builder, numElems):
 def StartCallsVector(builder, numElems):
     return ServiceStartCallsVector(builder, numElems)
 
+def ServiceCreateCallsVector(builder, data):
+    return builder.CreateVectorOfTables(data)
+
+def CreateCallsVector(builder, data):
+    ServiceCreateCallsVector(builder, data)
+
 def ServiceAddAttributes(builder, attributes):
     builder.PrependUOffsetTRelativeSlot(2, flatbuffers.number_types.UOffsetTFlags.py_type(attributes), 0)
 
@@ -149,6 +155,12 @@ def ServiceStartAttributesVector(builder, numElems):
 def StartAttributesVector(builder, numElems):
     return ServiceStartAttributesVector(builder, numElems)
 
+def ServiceCreateAttributesVector(builder, data):
+    return builder.CreateVectorOfTables(data)
+
+def CreateAttributesVector(builder, data):
+    ServiceCreateAttributesVector(builder, data)
+
 def ServiceAddDocumentation(builder, documentation):
     builder.PrependUOffsetTRelativeSlot(3, flatbuffers.number_types.UOffsetTFlags.py_type(documentation), 0)
 
@@ -161,6 +173,12 @@ def ServiceStartDocumentationVector(builder, numElems):
 def StartDocumentationVector(builder, numElems):
     return ServiceStartDocumentationVector(builder, numElems)
 
+def ServiceCreateDocumentationVector(builder, data):
+    return builder.CreateVectorOfTables(data)
+
+def CreateDocumentationVector(builder, data):
+    ServiceCreateDocumentationVector(builder, data)
+
 def ServiceAddDeclarationFile(builder, declarationFile):
     builder.PrependUOffsetTRelativeSlot(4, flatbuffers.number_types.UOffsetTFlags.py_type(declarationFile), 0)