Initial Asyncio Module PR [1/6] #741

yuce · 2025-09-19T16:56:49Z

This is the initial asyncio support.

Added the asyncio module which contains public asyncio API
Added the internal module and internal/asyncio_ modules, which contains the private asyncio API/implementation.
Added asyncio support for the Map proxy. Currently near cache, transactions, and lock releated-methods are not supported. The near cache support will come in another PR. Transactions will likely not be supported. Locks may need a different design.
I didn't include the API docs, in order to make the PR smaller. I'll add them in another PR.
The following tests are ported from the old API, and they work without changes (besides making them compatible with async/await syntax):
- tests/integration/asyncio/authentication_tests
- tests/integration/asyncio/backup_acks_tests
- tests/integration/asyncio/client_test (one test is not ported, due to its Topic DDS dependency)
- tests/integration/asyncio/proxy/map_test

Most of the code in this PR was duplicated to the internal module by prefixing them with asyncio_. For example ROOT/cluster.py was duplicated/modifed as internal/asyncio_cluster.py

Here is the diff between modules in this PR vs their counterparts in the old API:
https://gist.github.com/yuce/56e79a29a1d4d1d996788381d489c0a4

codecov-commenter · 2025-09-19T17:09:09Z

Codecov Report

❌ Patch coverage is 76.65837% with 563 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.48%. Comparing base (5c7a4d5) to head (a87a5c6).

Files with missing lines	Patch %	Lines
hazelcast/internal/asyncio_connection.py	76.16%	149 Missing ⚠️
hazelcast/internal/asyncio_proxy/map.py	78.26%	125 Missing ⚠️
hazelcast/internal/asyncio_invocation.py	72.41%	80 Missing ⚠️
hazelcast/internal/asyncio_cluster.py	63.88%	65 Missing ⚠️
hazelcast/internal/asyncio_compact.py	32.89%	51 Missing ⚠️
hazelcast/internal/asyncio_listener.py	79.23%	38 Missing ⚠️
hazelcast/asyncio/client.py	84.36%	33 Missing ⚠️
hazelcast/internal/asyncio_proxy/base.py	87.50%	14 Missing ⚠️
hazelcast/internal/asyncio_proxy/manager.py	90.00%	4 Missing ⚠️
hazelcast/internal/asyncio_reactor.py	96.49%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #741      +/-   ##
==========================================
- Coverage   95.33%   93.48%   -1.86%     
==========================================
  Files         378      389      +11     
  Lines       21992    24404    +2412     
==========================================
+ Hits        20967    22815    +1848     
- Misses       1025     1589     +564

☔ View full report in Codecov by Sentry.
📢 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.

yuce · 2025-09-26T10:42:46Z

I've added the diff between modules in this PR vs their counterparts in the old API to the PR description.

gbarnett-hz

Had a quick look.

For others: probably easier to use https://difftastic.wilfred.me.uk/introduction.html to make life easier.

Haven't studied the reactor in-detail and associated logic in detail. From the diff it looked like the changes were relatively minor, albeit many of them.

I can review those in-depth if needed (or you cannot find people).

gbarnett-hz · 2025-09-29T09:46:52Z

hazelcast/asyncio/client.py

+    _CLIENT_ID = AtomicInteger()
+
+    @classmethod
+    async def create_and_start(cls, config: Config = None, **kwargs) -> "HazelcastClient":


General note -- I'm sure there are others.

If we're trying to get this API nice w.r.t. typing as well then this will probably show some error by default as None is not applicable for Config. Might be more prominent here as I think this is entry point into client creation.

Same for __init__ -- config: Config | None.

Might be missing something in the diff: in client.py there's a load of documentation -- is it elsewhere, or why omit it for this one? (most likely doc applicable from __init__)

re: Docs, I mentioned that in the PR description:

I didn't include the API docs, in order to make the PR smaller. I'll add them in another PR.

If you use better diff tool it doesn't make a difference. Give that one I mentioned a go.

I can review those in-depth if needed (or you cannot find people).

Yes, please.

At least with PyCharm, the user gets the correct type annotation.
There is this project in case you'd like to try the asyncio module:
https://github.com/yuce/hazelcast-asyncio-sample

In any case, I pushed a PR that adds explicit |None:
baa3bc1

PyCharm may be more forgiving -- I've never used it. pyright or pyrefly are good tools to use to determine compliance to the type invariants specified using type annotations.

We check the typings with mypy.

gbarnett-hz · 2025-09-29T10:07:14Z

hazelcast/asyncio/client.py

+            raise
+        _logger.info("Client started")
+
+    async def get_map(self, name: str) -> Map[KeyType, ValueType]:


Intention is only to support also VC in near (immediate) term?

Map is the only proxy included, in order to make the PR small. Other proxies, except VC, may be excluded from the beta release.

gbarnett-hz · 2025-09-29T10:19:35Z

hazelcast/internal/asyncio_proxy/manager.py

+}
+
+
+class ProxyManager:


Note to others: is in proxy/__init__.py

In the diff that I provided in the description I've shown that, but maybe it wasn't easy to notice.

The diff was not good.

gbarnett-hz · 2025-09-29T10:33:09Z

hazelcast/internal/asyncio_reactor.py

+from hazelcast.internal.asyncio_connection import Connection
+from hazelcast.core import Address
+
+_BUFFER_SIZE = 128000


Best to define centrally if possible given it's used across reactors.

I think they should be independent with each other.

The other constant hasn't been changed for ~4 years, same value.

There's not a big probability that it will change.
But I would either have to import it from hazelcast.reactor, or refactor the code so both the asyncore and the asyncio reactor imported it from a common module.
That either introduces a dependency between those reactor modules, or require changes in the "old" Python code, which I tried to avoid.

gbarnett-hz · 2025-09-29T10:36:50Z

hazelcast/internal/asyncio_reactor.py

+    def shutdown(self):
+        if not self._is_live:
+            return
+        # TODO: cancel tasks


compared to reactor.py is this correct?

start, shutdown are not necessary for the AsyncioReactor.
Removed them in the 3rd PR with this commit:
58783dc

hazelcast/internal/asyncio_connection.py

ihsandemir · 2025-11-14T12:45:13Z

hazelcast/asyncio/client.py

+    _CLIENT_ID = AtomicInteger()
+
+    @classmethod
+    async def create_and_start(cls, config: Config | None = None, **kwargs) -> "HazelcastClient":


At Java this method is named as this:

HazelcastClient.newHazelcastClient()

At C++, I used this:

hazelcast::new_client()

Now for python, it will be yet another different name:

HazelcastClient.create_and_start()

Are these too confusing?

It's also StartNewClientAsync in .net. Also, it's initialized over a factory class.

i would choose the name as new_hazelcast_client to be more consistent and easily understandable by any existing Hazelcast users.

#741 (comment)

gbarnett-hz · 2025-11-20T16:04:27Z

hazelcast/internal/asyncio_connection.py

+            self._cluster_connect_timeout_text,
+            self._max_backoff,
+        )
+        time.sleep(sleep_time)


asyncio.sleep ? called on line 550

I've fixed the WaitStrategy in 91bf1d1

gbarnett-hz · 2025-11-20T16:20:40Z

hazelcast/internal/asyncio_invocation.py

+
+        def callback(future):
+            try:
+                schema = future.result()


does .result() block if it's not ready? is it not something like await future, then future.result() or schema = await future?

No it doesn't block.
Trying to get the result when !future.done() raises an exception.
The fetch_schema_future.add_done_callback(callback) a few lines below makes sure that callback receives a done future.

ihsandemir

will continue to review.

ihsandemir · 2025-11-21T09:04:03Z

hazelcast/asyncio/__init__.py

@@ -0,0 +1,2 @@
+from hazelcast.asyncio.client import HazelcastClient


if you will follow on this way of exposing the API, no need to keep the client.py under this folder but put under internal, right?

ihsandemir · 2025-11-21T09:13:57Z

hazelcast/asyncio/client.py

+    _CLIENT_ID = AtomicInteger()
+
+    @classmethod
+    async def create_and_start(cls, config: Config | None = None, **kwargs) -> "HazelcastClient":


i would choose the name as new_hazelcast_client to be more consistent and easily understandable by any existing Hazelcast users.

ihsandemir · 2025-11-21T09:15:20Z

hazelcast/asyncio/client.py

+        await client._start()
+        return client
+
+    def __init__(self, config: Config | None = None, **kwargs):


There is documentation at the hazelcast/client.py, would you like to duplicate it here as well?

"""The client can be configured either by: - providing a configuration object as the first parameter of the constructor .. code:: python from hazelcast import HazelcastClient from hazelcast.config import Config config = Config() config.cluster_name = "a-cluster" client = HazelcastClient(config) - passing configuration options as keyword arguments .. code:: python from hazelcast import HazelcastClient client = HazelcastClient( cluster_name="a-cluster", ) See the :class:`hazelcast.config.Config` documentation for the possible configuration options. Args: config: Optional configuration object. **kwargs: Optional keyword arguments of the client configuration. """

I removed all documentation intentionally to keep the size of the PR smaller.
I'll put all the docs back in a separate PR.

Actually this made the review worse since I compare the 2 files and I see a lot of diff due to the documentations. Why not just put them in here. The PR is already over certain number of lines, it should not matter if that is 5K vs 7k :) and it will ease the review by comparison of the files.

The documentation will be added in a separate PR, and will be reviewed by the docs team.

yuce · 2025-11-21T09:29:18Z

@ihsandemir #741 (comment) Let's discuss about that on the TDD.

emreyigit · 2025-11-20T13:22:03Z

hazelcast/asyncio/client.py

+            self._cluster_view_listener.start()
+            await self._connection_manager.start(self._load_balancer)
+            sync_start = not self._config.async_start
+            if sync_start:


What does sync_start mean in this context? Didn't we seperated the client already?

sync_start controls whether the client returns the control to the user after connecting to all members, or not. It's not related to asyncio. Async start with the asyncio client is currently not supported.

emreyigit · 2025-11-20T13:27:49Z

hazelcast/asyncio/client.py

+
+    @property
+    def name(self) -> str:
+        return self._name


If I remember correctly, the missing docs will be part of next PRs to reduce line of changes here.

emreyigit · 2025-11-20T13:41:27Z

hazelcast/internal/asyncio_proxy/base.py

+        )
+
+
+class TopicMessage(typing.Generic[MessageType]):


Does it have any support?

No, it doesn't yet.
Removed unnecessary code from that file at: 2128f5e

emreyigit · 2025-11-20T13:59:02Z

hazelcast/internal/asyncio_proxy/map.py

+        )
+        return await self._invoke(request, handler)
+
+    async def flush(self) -> None:


Why force_unlock and lock are removed?

emreyigit · 2025-11-20T14:03:49Z

hazelcast/internal/asyncio_proxy/map.py

+            for partition_id, entry_list in partition_map.items():
+                request = map_put_all_codec.encode_request(
+                    self.name, entry_list, False
+                )  # TODO trigger map loader


Nit: While put_all triggers map loader, set_all doesn't trigger that.

The comment is from the old API.

ihsandemir · 2025-11-21T12:05:39Z

hazelcast/internal/asyncio_proxy/base.py

+    def __repr__(self) -> str:
+        return '%s(name="%s")' % (type(self).__name__, self.name)
+
+    def _invoke(self, request, response_handler=_no_op_response_handler) -> asyncio.Future:


why not put async def but return future? i thought you would not need to use futures when you have asyncio.

This is asyncio.Future, not hazelcast.future.Future.

ihsandemir · 2025-11-21T12:08:20Z

hazelcast/internal/asyncio_proxy/base.py

+        self._invocation_service.invoke(invocation)
+        return invocation.future
+
+    async def _ainvoke_on_partition(


why have this function and also have _invoke_on_partition?

It's a helper.

ihsandemir · 2025-11-21T12:19:56Z

hazelcast/internal/asyncio_connection.py

+_CLIENT_PUBLIC_ENDPOINT_QUALIFIER = EndpointQualifier(ProtocolType.CLIENT, "public")
+
+
+class WaitStrategy:


why change from internal to public access?

It's in the hazelcast.internal package, so it is internal.

ihsandemir · 2025-11-21T12:43:21Z

hazelcast/internal/asyncio_connection.py

+                    try:
+                        # TODO: creating the task may not throw the exception
+                        # TODO: protect the loop against exceptions, so all handlers run
+                        maybe_coro = on_connection_opened(connection)


why was this? Which path it returns as non-coroutine?

For example: https://github.com/yuce/hazelcast-python-client/blob/2128f5e6f0865600c5703a9e2304fb721f565a02/hazelcast/internal/asyncio_cluster.py#L94

ihsandemir · 2025-11-21T12:48:35Z

tests/integration/asyncio/authentication_tests/authentication_test.py

+@unittest.skipIf(
+    compare_client_version("4.2.1") < 0, "Tests the features added in 4.2.1 version of the client"
+)
+class AuthenticationTest(unittest.IsolatedAsyncioTestCase, HazelcastTestCase):


what was the reason for IsolatedAsyncioTestCase?

Otherwise async code cannot be used in tests.

ihsandemir

Looking at code coverage report #741 (comment), new code is around 76% covered. Will you complete it to 100%?

yuce · 2025-11-24T08:25:19Z

@ihsandemir

Looking at code coverage report #741 (comment), new code is around 76% covered. Will you complete it to 100%?

There are 5 more PRs that port more tests.

yuce added 5 commits September 19, 2025 18:17

Initial asyncio commit

cbe98dc

Updates

162fd17

Updates

9931956

Merge branch 'master' into asyncio-module

856e3df

Black

35384bf

yuce added 3 commits September 19, 2025 20:12

Updates

fdda120

Updates

fee5b45

Updates

fc2c38b

yuce requested review from anthony-griffin-dev, emreyigit, gbarnett-hz and ihsandemir September 19, 2025 17:30

yuce added 7 commits September 19, 2025 20:39

Removed docs, include HazelcastClient/Map in public API

1772031

Updates

170cf89

Merge branch 'master' into asyncio-module

539c904

black

22449a8

Ignore incorrect mypy errors

5406bc6

Updates

a417a4a

Updates

d00c480

yuce added this to the 5.6.0 milestone Sep 25, 2025

gbarnett-hz reviewed Sep 29, 2025

View reviewed changes

yuce added 6 commits September 29, 2025 14:42

Annotate optional params

baa3bc1

black

ebfc9e2

Remove update to test util

6928837

black

3e03cbf

black

51ced7a

update

e635b94

yuce changed the title ~~Initial Asyncio Module PR~~ Initial Asyncio Module PR [1/3] Oct 1, 2025

yuce added 2 commits October 2, 2025 12:06

Merge branch 'master' into asyncio-module

a630706

Merge branch 'master' into asyncio-module

6ced889

ihsandemir reviewed Nov 14, 2025

View reviewed changes

yuce changed the title ~~Initial Asyncio Module PR [1/3]~~ Initial Asyncio Module PR [1/4] Nov 17, 2025

yuce changed the title ~~Initial Asyncio Module PR [1/4]~~ Initial Asyncio Module PR [1/5] Nov 19, 2025

yuce changed the title ~~Initial Asyncio Module PR [1/5]~~ Initial Asyncio Module PR [1/6] Nov 20, 2025

gbarnett-hz reviewed Nov 20, 2025

View reviewed changes

Addressed review comment

91bf1d1

ihsandemir reviewed Nov 21, 2025

View reviewed changes

emreyigit reviewed Nov 21, 2025

View reviewed changes

Removed unnecessary code

2128f5e

ihsandemir reviewed Nov 21, 2025

View reviewed changes

yuce added 2 commits November 21, 2025 17:10

Add BETA warning

62697e3

Black

a87a5c6

ihsandemir reviewed Nov 24, 2025

View reviewed changes

		@@ -0,0 +1,2 @@
		from hazelcast.asyncio.client import HazelcastClient

		_CLIENT_PUBLIC_ENDPOINT_QUALIFIER = EndpointQualifier(ProtocolType.CLIENT, "public")


		class WaitStrategy:

Initial Asyncio Module PR [1/6] #741

Are you sure you want to change the base?

Initial Asyncio Module PR [1/6] #741

Uh oh!

Conversation

yuce commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov-commenter commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

yuce commented Sep 26, 2025

Uh oh!

gbarnett-hz left a comment • 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!

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

emreyigit Nov 20, 2025 • 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!

gbarnett-hz Nov 20, 2025 • 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!

ihsandemir left a comment

Choose a reason for hiding this comment

Uh oh!

yuce commented Sep 19, 2025 •

edited

Loading

codecov-commenter commented Sep 19, 2025 •

edited

Loading

gbarnett-hz left a comment •

edited

Loading

emreyigit Nov 20, 2025 •

edited

Loading

gbarnett-hz Nov 20, 2025 •

edited

Loading