Feat: Add AsyncClient, search API, and streaming bulk export by Chocapikk · Pull Request #28 · LeakIX/LeakIXClient-Python

Chocapikk · 2026-02-07T23:46:20Z

Summary

This PR enhances the LeakIX Python client with async support, reduced code duplication, and improved developer experience.

New Features

AsyncClient: Full async/await support using httpx, mirrors the sync Client API
BaseClient: Shared logic between sync and async clients (headers, parsing, query serialization)
Simple search() API: Intuitive method accepting raw query strings (same syntax as the website)
Domain lookup: get_domain() method for domain-level service/leak queries
Streaming bulk export: Memory-efficient bulk_export_stream() generator

Code Quality

Extracted BaseClient to eliminate duplication between sync and async clients
AsyncClient returns AbstractResponse (not raw lists/dicts), consistent with sync client
Uses Scope enum instead of raw strings for type safety
Added serialize_queries() helper to centralize query serialization
All methods have return type annotations
No silent error swallowing

API Examples

# Sync client
from leakix import Client, Scope
client = Client(api_key="...")
results = client.search("+plugin:GitConfigHttpPlugin", scope=Scope.LEAK)

# Async client
from leakix import AsyncClient, Scope
async with AsyncClient(api_key="...") as client:
    results = await client.search("+country:FR +port:22", scope=Scope.SERVICE)

Changes

Add leakix/base.py with BaseClient shared logic
Add leakix/async_client.py with full async implementation
Add search(), get_domain(), bulk_export_stream() to both clients
Add serialize_queries() helper in query.py
Add httpx dependency
Export AsyncClient from package root
Version bump to 0.2.0

Recreated from #27 as an internal branch for CI.

dannywillems · 2026-03-16T15:41:39Z


+## Quick Start
+
+```python


It is a good practice to never leave code in README, because it can be outdated very quickly. A more maintainable way to add code from files that is tested in the CI.

dannywillems · 2026-03-16T15:42:43Z

 Each object can be transformed back into a Python dictionary/JSON using the method `to_dict()`.
 For instance, for the response of the subdomains endpoint, you can get back individual JSON by using:

 ```python


We will remove this, based on https://github.com/LeakIX/LeakIXClient-Python/pull/28/changes#r2941216156

dannywillems

This patch does many things, which should be in individual commits and individual patches.
Can you split in individual patches please?

Additionnaly, the async and sync code are duplicated. There should be an elegant way to share code between both.

Finally, the async client does not follow the same pattern as the sync client (AbstractResponse). The class AbstractResponse with its implementation SuccessResponse and ErrorResponse abstract LeakIX backend.

With the async client, the user does not know what actually happened.

dannywillems · 2026-03-16T18:15:39Z

+        )
+        if status == 200 and isinstance(data, list):
+            return [l9format.L9Event.from_dict(item) for item in data]
+        return []


This motivates my comment regarding using AbstractResponse. In this case, the user does not know what actually happened (an error happened?).

dannywillems · 2026-03-16T18:15:59Z

+    async def search(
+        self,
+        query: str,
+        scope: str = "leak",


You could use an enum instead.

dannywillems · 2026-03-16T18:17:05Z

+            }
+        return {"services": [], "leaks": []}
+
+    def _parse_events(self, items: list) -> list:


We want to have an homogenenous list. l9format should never fail. And if it fails, the user must know, and we should get a report for it.

dannywillems · 2026-03-16T18:19:02Z

+            return self.get_service(queries=queries, page=page)
+        return self.get_leak(queries=queries, page=page)
+
+    def bulk_export_stream(self, queries: list[Query] | None = None):


What is the returned type?

dannywillems · 2026-03-17T09:26:36Z

+        if page < 0:
+            raise ValueError("Page argument must be a positive integer")
+        url = f"{self.base_url}/search"
+        r = self.__get(


Why do you introduce __get instead of _get? Having a uniform API would be better. Keep one of them.

__get is already on main, it's the existing sync client code (client.py:53). I didn't change that. The async client uses _get since it's called from subclasses via BaseClient.

Why do you introduce __get instead of _get?

I meant why do you introduce _get instead of __get.

The async client uses _get since it's called from subclasses via BaseClient.

Wdym?

dannywillems

See comments

dannywillems · 2026-03-17T09:44:43Z


 class Client(BaseClient):
-    def __get(self, url: str, params: dict[str, Any] | None) -> AbstractResponse:
+    def _get(self, url: str, params: dict[str, Any] | None) -> AbstractResponse:


Why do you use _get instead of __get?

You asked for a uniform API. Both clients now use _get

This does not answer the question. Can you explain why you picked _get instead of __get?

Here some useful documentation: https://docs.python.org/3/tutorial/classes.html#private-variables.

dannywillems · 2026-03-17T09:54:04Z

Remove 3d2cf4e and d159e3b. This is out of the scope of this patch. It is in a follow-up.

dannywillems · 2026-03-17T09:58:06Z

Can you clean this history please? You introduce a commit that changes __get to _get, and after that revert the changes.
Also, it would be better to have a commit for each individual change, as discussed on mattermost.

dannywillems · 2026-03-17T10:54:02Z

This should be removed, as requested in #28 (comment).
I will go further with this change.

dannywillems

See comments

dannywillems force-pushed the feat/async-client-search-api branch 2 times, most recently from 716aaeb to 702b65e Compare February 10, 2026 01:16

dannywillems reviewed Mar 16, 2026

View reviewed changes

Chocapikk force-pushed the feat/async-client-search-api branch from 5f44186 to aa7e53a Compare March 16, 2026 15:47

dannywillems requested changes Mar 16, 2026

View reviewed changes

dannywillems reviewed Mar 16, 2026

View reviewed changes

Chocapikk force-pushed the feat/async-client-search-api branch from e848685 to 362ce2b Compare March 17, 2026 08:37

Chocapikk changed the title ~~Feat: Add AsyncClient, search API, and Pro detection~~ Feat: Add AsyncClient, search API, and streaming bulk export Mar 17, 2026

Chocapikk force-pushed the feat/async-client-search-api branch from 010ea80 to e547391 Compare March 17, 2026 08:47

dannywillems reviewed Mar 17, 2026

View reviewed changes

Comment thread leakix/async_client.py Outdated

dannywillems reviewed Mar 17, 2026

View reviewed changes

dannywillems requested changes Mar 17, 2026

View reviewed changes

dannywillems mentioned this pull request Mar 17, 2026

Use SuccessResponse instead of ErrorResponse for 204 #73

Closed

dannywillems reviewed Mar 17, 2026

View reviewed changes

Chocapikk force-pushed the feat/async-client-search-api branch from d05e130 to c29ab56 Compare March 17, 2026 10:26

Chocapikk added 7 commits March 17, 2026 11:29

Refactor: Extract BaseClient from Client to share logic between clients

7585abb

Feat: Add serialize_queries helper and widen Query to AbstractQuery

7c8ca1a

Fix: Return SuccessResponse for 204 No Content instead of ErrorResponse

fe51f15

Feat: Add search(), get_domain(), and streaming bulk_export_stream()

91c65ab

Feat: Add AsyncClient with httpx for async API access

0ec6884

Docs: Add async examples and update sync examples

76d84cc

Docs: Update CHANGELOG for v0.2.0

44b55b6

Chocapikk force-pushed the feat/async-client-search-api branch from c29ab56 to 44b55b6 Compare March 17, 2026 10:35

Fix: Sort imports in async example

9e5468f

dannywillems approved these changes Mar 17, 2026

View reviewed changes

dannywillems merged commit 1afe155 into main Mar 17, 2026
15 checks passed

Conversation

Chocapikk commented Feb 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

New Features

Code Quality

API Examples

Changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dannywillems 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!

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!

dannywillems 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!

dannywillems commented Mar 17, 2026

Uh oh!

dannywillems commented Mar 17, 2026

Uh oh!

dannywillems commented Mar 17, 2026

Uh oh!

dannywillems left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Chocapikk commented Feb 7, 2026 •

edited

Loading