Expose key_order option on Json5ProtocolWriterOptions

Summary:
Surfaces the C++ `Json5ProtocolWriter::Options::key_order` field through
the thrift-python serializer.

___

Differential Revision: D106566885

fbshipit-source-id: 8c4c37d852c1e9758f6c6aff324fba42dbeecadc

Author: Mizuchi

thrift/lib/python/Serializer.h

@@ -19,6 +19,7 @@
 #include <memory>
 
 #include <folly/io/IOBuf.h>
+#include <thrift/lib/cpp2/protocol/Protocol.h>
 
 #ifdef THRIFT_HAS_JSON5_PROTOCOL
 #include <thrift/lib/cpp2/protocol/detail/Json5ProtocolWriter.h>
@@ -37,6 +38,8 @@ struct Json5ProtocolWriter {
     bool enumAsInteger = false;
     bool binaryAsBase64String = false;
     bool mapPrimitiveKeysAsMemberNames = false;
+    ::apache::thrift::KeyOrder keyOrder =
+        ::apache::thrift::KeyOrder::StableAscending;
   };
 };
 } // namespace apache::thrift::json5::detail

thrift/lib/python/serializer.pxd

@@ -21,6 +21,13 @@ from thrift.python.types cimport cDynamicStructInfo
 from thrift.python.protocol cimport Protocol as cProtocol
 
 
+cdef extern from "<thrift/lib/cpp2/protocol/Protocol.h>" namespace "::apache::thrift":
+    cpdef enum KeyOrder "::apache::thrift::KeyOrder":
+        UNSPECIFIED "::apache::thrift::KeyOrder::Unspecified"
+        NATIVE_ASCENDING "::apache::thrift::KeyOrder::NativeAscending"
+        STABLE_ASCENDING "::apache::thrift::KeyOrder::StableAscending"
+
+
 cdef extern from "<thrift/lib/python/Serializer.h>" namespace "apache::thrift::json5::detail":
     cdef cppclass cJsonWriterOptions "apache::thrift::json5::detail::JsonWriterOptions":
         cbool listTrailingComma
@@ -36,6 +43,7 @@ cdef extern from "<thrift/lib/python/Serializer.h>" namespace "apache::thrift::j
         cbool enumAsInteger
         cbool binaryAsBase64String
         cbool mapPrimitiveKeysAsMemberNames
+        KeyOrder keyOrder
 
 
 cdef extern from "<thrift/lib/python/Serializer.h>" namespace "::apache::thrift::python":

thrift/lib/python/serializer.pyi

@@ -39,18 +39,25 @@ class JsonWriterOptions:
 
 JSON5_MODE: Json5ProtocolWriterOptions
 
+class KeyOrder(Enum):
+    UNSPECIFIED: KeyOrder = ...
+    NATIVE_ASCENDING: KeyOrder = ...
+    STABLE_ASCENDING: KeyOrder = ...
+
 class Json5ProtocolWriterOptions:
     writer: JsonWriterOptions
     enum_as_integer: bool
     binary_as_base64_string: bool
     map_primitive_keys_as_member_names: bool
+    key_order: KeyOrder
     def __init__(
         self,
         *,
         writer: JsonWriterOptions | None = None,
         enum_as_integer: bool = False,
         binary_as_base64_string: bool = False,
         map_primitive_keys_as_member_names: bool = False,
+        key_order: KeyOrder = KeyOrder.STABLE_ASCENDING,
     ) -> None: ...
 
 def serialize_iobuf(

thrift/lib/python/serializer.pyx

@@ -19,7 +19,7 @@ from libcpp.utility cimport move as cmove
 from thrift.python.exceptions cimport Error, GeneratedError
 from thrift.python.types cimport Struct, StructOrUnion, StructInfo, Union, UnionInfo
 from thrift.python.protocol import Protocol
-from thrift.python.serializer cimport cJsonWriterOptions, cJson5ProtocolWriterOptions
+from thrift.python.serializer cimport cJsonWriterOptions, cJson5ProtocolWriterOptions, KeyOrder
 
 cdef extern from *:
     """
@@ -49,23 +49,14 @@ cdef class JsonWriterOptions:
         self._writer_options.allowNanInf = allow_nan_inf
         self._writer_options.indentWidth = indent_width
 
-JSON5_MODE = Json5ProtocolWriterOptions(
-    writer=JsonWriterOptions(
-        list_trailing_comma=True,
-        object_trailing_comma=True,
-        unquote_object_name=True,
-        allow_nan_inf=True,
-        indent_width=2,
-    )
-)
-
 
 cdef class Json5ProtocolWriterOptions:
     """Options for the JSON5 protocol writer that are passed to C++."""
     cdef public JsonWriterOptions writer
     cdef public bint enum_as_integer
     cdef public bint binary_as_base64_string
     cdef public bint map_primitive_keys_as_member_names
+    cdef public object key_order
 
     def __init__(
         self,
@@ -74,11 +65,24 @@ cdef class Json5ProtocolWriterOptions:
         enum_as_integer=False,
         binary_as_base64_string=False,
         map_primitive_keys_as_member_names=False,
+        key_order=KeyOrder.STABLE_ASCENDING,
     ):
         self.writer = writer if writer is not None else JsonWriterOptions()
         self.enum_as_integer = enum_as_integer
         self.binary_as_base64_string = binary_as_base64_string
         self.map_primitive_keys_as_member_names = map_primitive_keys_as_member_names
+        self.key_order = KeyOrder(key_order)
+
+
+JSON5_MODE = Json5ProtocolWriterOptions(
+    writer=JsonWriterOptions(
+        list_trailing_comma=True,
+        object_trailing_comma=True,
+        unquote_object_name=True,
+        allow_nan_inf=True,
+        indent_width=2,
+    )
+)
 
 
 cdef cJson5ProtocolWriterOptions _to_c_options(Json5ProtocolWriterOptions options):
@@ -87,6 +91,7 @@ cdef cJson5ProtocolWriterOptions _to_c_options(Json5ProtocolWriterOptions option
     c_options.enumAsInteger = options.enum_as_integer
     c_options.binaryAsBase64String = options.binary_as_base64_string
     c_options.mapPrimitiveKeysAsMemberNames = options.map_primitive_keys_as_member_names
+    c_options.keyOrder = <KeyOrder>(<int>options.key_order)
     return cmove(c_options)
 
 

thrift/lib/python/test/json5_serializer_test.py

@@ -30,6 +30,7 @@
     JSON5_MODE,
     Json5ProtocolWriterOptions,
     JsonWriterOptions,
+    KeyOrder,
     Protocol,
     serialize,
     serialize_iobuf,
@@ -295,3 +296,19 @@ def test_json5_options_invalid_protocol(self) -> None:
                 Protocol.COMPACT,
                 options=Json5ProtocolWriterOptions(),
             )
+
+    def test_serialize_unspecified_preserves_iteration_order(self) -> None:
+        """With key_order=UNSPECIFIED the C++ writer must not sort: keys
+        appear in the container's iteration order. Python dicts preserve
+        insertion order, so the emitted order must match the Python
+        insertion order.
+        """
+        keys = [3, 1, 2]  # intentionally unsorted insertion order
+        example = test_types.Example(i32AsKey={k: k * 10 for k in keys})
+        options = Json5ProtocolWriterOptions(key_order=KeyOrder.UNSPECIFIED)
+        result = serialize(example, Protocol.JSON5, options=options).decode()
+
+        parsed = json.loads(result)
+        emitted_keys = [entry["key"] for entry in parsed["i32AsKey"]]
+        # No sorting: C++ order must match Python's insertion order.
+        self.assertEqual(emitted_keys, keys)