[HZ-5510] Introduced number types and removed the default_int_type config by yuce · Pull Request #837 · hazelcast/hazelcast-python-client

yuce · 2026-08-24T13:41:01Z

Hazelcast has a number of default serializers for numeric types, modeled after the corresponding Java types: signed 8, 16, 32, 64 bit integers, 32 and 64 bit floating point numbers. Go, C++ and .Net clients have corresponding native types, so they are able to serialize numeric values with the intended type. Python and Node.js clients have a different story though.

Python has a single unbounded integer type, and a single floating point type. When a user saves a number using the Python client, it is not immediately apparent which data type is used for storage. Consider the following example:

client = await HazelcastClient.create_and_start( ... )
m = await client.get_map("my-map")
await m.set("key", 123)

A configuration based mechanism was used as a workaround to solve this problem, and ensure a number is stored with the intended type. Python Client has the default_int_type configuration which sets the integer type to be used when storing an integer to the cluster. It must be set during client creation, and cannot be changed later:

client = await HazelcastClient.create_and_start(default_int_type=IntType.SHORT)
m = await client.get_map("my-map")
await m.set("key", 123)

The obvious problem with this approach is, the integer/number setting is global to a client, and can be set only once. If an application uses different number types, there is no way of storing values with different types using the client.

As I’ve shown, serializing number types is problematic using the Python Client. How about deserialization? The values are deserialized to the expected type: int so there’s not a problem, unless the user wants to put the same value back to the cluster. That problem is out of scope for this proposal, and a possible solution will be explained in a future proposal.

This problem can be easily solved by introducing missing number types. For example, the hazelcast.Int16 class can be used to serialize a value as a 16 bit signed integer:

from hazelcast import Int16
m = await client.get_map("my-map")
await m.set("key", Int16(123))

That allows us to remove the default_int_type from configuration and related code. We can keep serializing integers by default as 32 bit signed integers for convenience. So if the user never sets default_int_type other than the default, their code still works as expected.

await m.set("key", 123)  # serialized as 32 bit signed integer
await m.set("key", Int16(123))  # serialized as 16 bit signed integer

This PR:

Removes default_int_type configuration and related code.
Introduces the following number classes: Int8, Int16, Int32, Int64, BigInt, Float32, Float64
Unwrapped integers are stored as 32 bit integers (keeps the previous behavior).
Unwrapped floats are stored as 64 bit floats (keeps the previous behavior).

NOTE: Do not mind the link checker failure, they are due to AI-protection mechanism.

codecov-commenter · 2026-08-24T14:36:47Z

Codecov Report

❌ Patch coverage is 87.64045% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 94.16%. Comparing base (ba315d5) to head (9b459ed).

Files with missing lines	Patch %	Lines
hazelcast/number_types.py	84.05%	11 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #837      +/-   ##
==========================================
- Coverage   94.21%   94.16%   -0.05%     
==========================================
  Files         413      414       +1     
  Lines       27646    27688      +42     
==========================================
+ Hits        26046    26073      +27     
- Misses       1600     1615      +15

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

ihsandemir

What about reader side? Why dont we convert to Int8, Int16, Int64, etc, on the read side?

ihsandemir · 2026-08-26T10:30:12Z

+        return str(self.value)
+
+
+class Float64:


should it be named to Double to be in sync with Java naming?

Double is mostly just meaningful to Java developers.
Float64 communicates that this type is a 64bit float.
Also there is some inconsistency about this even in the Java client, e.g., compact serializer has the writeFloat64 method.

ihsandemir · 2026-08-26T10:35:31Z


    def write(self, out, obj):
-        out.write_short(obj)
+        out.write_short(int(obj))


Suggested change

out.write_short(int(obj))

out.write_short(Int16(obj))

and similar for the other int changes below.

That would be incorrect. We must convert Int16 to Python's int type, since that's what write_short expects.

ihsandemir

Nice cleanup, explicit number types read much better than the old default_int_type config.

I ran the unit tests, mypy and black on the branch and they all pass, and I did not find a functional bug in the change itself. Most comments below are about the new number_types classes: they have no __eq__ / __hash__ and do not subclass int / float, which makes them awkward to use in normal code. There is also a docs gap, and one test that quietly stopped covering three serializers.

ihsandemir · 2026-08-26T10:53:08Z

@@ -0,0 +1,162 @@
+from typing import Self


Self is imported but never used anywhere in the file. Looks like a leftover and can be dropped.

ihsandemir · 2026-08-26T10:53:08Z

+__all__ = "Int8", "Int16", "Int32", "Int64", "Float32", "Float64", "BigInt"
+
+
+class Int8:


These types have no __eq__ / __hash__, so they compare by identity:

Int32(1) == Int32(1) # False Int32(1) == 1 # False

This also affects map.get_all(): it puts the keys in a dict, so get_all([Int32(1), Int32(1)]) cannot dedupe and sends the same key to the member twice.

A simpler fix for the whole file: let Int8..Int64 subclass int, and Float32/Float64 subclass float. Then equality, hashing, arithmetic, indexing and Map[str, int] type hints all work for free. Today Int32(5) + 1 and sum([Int32(1), Int32(2)]) raise TypeError.

Dispatch keeps working, because lookup_default_serializer matches the exact type (obj_type is int), which is the same reason bool works today.

ihsandemir · 2026-08-26T10:53:08Z

+    MIN_VALUE = MIN_BYTE
+    MAX_VALUE = MAX_BYTE
+
+    def __init__(self, value: int):


The range is checked but the type is not, so a wrong value is only caught much later:

Int8(1.5) # accepted here, fails in to_data with "__int__ returned non-int (type float)" Int8("3") # raises TypeError from the comparison, not the intended ValueError

An isinstance(value, int) check before the range check would report it at the call site.

ihsandemir · 2026-08-26T10:53:08Z

+    Corresponds to Java ``float``.
+    """
+
+    def __init__(self, value: float | int):


No range check here, unlike the Int types. Float32(1e300) is accepted and then fails at write time with float too large to pack with f format.

A range check would be good. It may also be worth a docstring note that precision is lost: Float32(1.1) reads back as 1.100000023841858. That is expected for a 32-bit float, but it surprises people.

ihsandemir · 2026-08-26T10:53:08Z

+
+
+class Float64:
+    """Float32 represents a 64-bit floating point number


Typo: should be Float64 represents a 64-bit floating point number. This line shows up in the generated API docs.

ihsandemir · 2026-08-26T10:53:08Z

+        obj = REFERENCE_OBJECTS[name]
+        # bool is an instance of int, so need to exclude that specifically --YT
+        if not isinstance(deserialized, bool) and isinstance(deserialized, int):
+            obj = int(obj)


This does nothing. REFERENCE_OBJECTS holds plain int values for Byte/Short/Integer/Long/BigInteger, so int(obj) never converts anything.

Looks like a leftover from an earlier version where the reference values were wrapped.

ihsandemir · 2026-08-26T10:53:08Z

+        ss = self._create_serialization_service(is_big_endian)
        obj = REFERENCE_OBJECTS[name]
-        data = ss.to_data(obj)
+        if name == "BigInteger":


Only BigInteger is wrapped here, while test_serialize above also wraps Byte, Short and Long. So for those three the reference object stays a plain int and is serialized as Integer.

The test still passes, because REFERENCE_OBJECTS["Long"] is -50992225 and fits into an int32. But that means ByteSerializer, ShortSerializer and LongSerializer round-trips are no longer tested at all, and a real regression in them would go unnoticed.

Could you wrap them here the same way test_serialize does?

ihsandemir · 2026-08-26T10:53:09Z

+from hazelcast import HazelcastClient, Int8, Int16, Int32, Int64, Float32, Float64
 from hazelcast.core import HazelcastJsonValue
+from hazelcast.number_types import BigInt
 from hazelcast.serialization import MAX_BYTE, MAX_SHORT, MAX_INT, MAX_LONG


These are unused now that test_variable_integer is gone.

Minor: BigInt is imported from hazelcast.number_types while the others come from hazelcast. BigInt is in __all__, so it can come from hazelcast too.

ihsandemir · 2026-08-26T10:53:09Z

@@ -0,0 +1,15 @@
+import asyncio


A few small things in this example:

The client is never shut down and there is no if __name__ == "__main__": guard, so the process does not exit cleanly. Other examples, e.g. examples/asyncio/map_basic_example.py, do both.

value_i8 is read from a key "i8" that was written as Int32(10). Int32 is also the one type that needs no wrapper, since a plain int already maps to it, so Int8 would show the feature better.

map shadows the builtin.

ihsandemir · 2026-08-26T10:53:09Z

 .. autoclass:: FlakeIdGeneratorConfig
 .. autoclass:: ReliableTopicConfig
-.. autoclass:: IntType
 .. autoclass:: EvictionPolicy


IntType is removed here, but nothing is added for the new types, and docs/serialization.rst still describes the old behaviour: line 23 maps int to Byte/Short/Integer/Long/BigInteger, and line 37 tells users to configure this with default_int_type. That argument is removed by this PR, so following the docs now raises InvalidConfigurationError: Unrecognized config option: default_int_type.

Could Int8..BigInt get an entry here and a short section in serialization.rst?

yuce · 2026-08-27T08:39:16Z

What about reader side? Why dont we convert to Int8, Int16, Int64, etc, on the read side?

Python has a single integer type.
If we return Int8, etc, the user cannot use them directly, and must convert them to int, which is not convenient.
The only use of returning Int8 etc would be putting it back to the map (e.g., for implementing map copy).
But in our current APIs most of the methods eagerly deserialize, so we need a lazy deserialization mechanism to accomplish that.

yuce added 3 commits August 24, 2026 16:40

Introduced number types and removed the default_int_type config

f56526a

black

3949454

Removed test_variable_integer test

34159dd

yuce changed the title ~~Introduced number types and removed the default_int_type config~~ [HZ-5510] Introduced number types and removed the default_int_type config Aug 24, 2026

test fix

9b459ed

yuce requested a review from ihsandemir August 24, 2026 14:44

ihsandemir reviewed Aug 26, 2026

View reviewed changes

		__all__ = "Int8", "Int16", "Int32", "Int64", "Float32", "Float64", "BigInt"


		class Int8:



		class Float64:
		"""Float32 represents a 64-bit floating point number

Uh oh!

Conversation

yuce commented Aug 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov-commenter commented Aug 24, 2026

Codecov Report

Uh oh!

ihsandemir left a comment

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!

ihsandemir left a comment

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!

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!

yuce commented Aug 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

yuce commented Aug 24, 2026 •

edited

Loading