aiolocust 0.1.0__tar.gz

aiolocust-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.3
+Name: aiolocust
+Version: 0.1.0
+Summary: Add your description here
+Author: Lars Holmberg
+Author-email: Lars Holmberg <lars.holmberg@redshirt.se>
+Requires-Dist: aiohttp>=3.13.3
+Requires-Dist: rich>=14.2.0
+Requires-Dist: uvloop>=0.22.1 ; sys_platform == 'linux'
+Requires-Dist: uvloop>=0.22.1 ; sys_platform == 'darwin'
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# AIOLocust
+
+This is a 2026 reimagining of [Locust](https://github.com/locustio/locust/). It is possible that we may merge the projects at some point, but for now it is a separate library.
+
+## Simpler and more consistent syntax than Locust, leveraging asyncio
+
+```python
+import asyncio
+from aiolocust import LocustClientSession
+
+async def user(client: LocustClientSession):
+    async with client.get("http://example.com/") as resp:
+        assert resp.status == 200
+    asyncio.sleep(0.1)
+```
+
+Locust was created in 2011, and while it has gone through several major overhauls, it still has a fair amount of legacy style code, and has accumulated a lot of non-core functionality that make it very hard to maintain and improve. It's 10000+ lines of code using a mix of procedural, object oriented and functional programming, with several confusing abstractions.
+
+AIOLocust is built to be smaller in scope, but capture the learnings from Locust. It uses modern, explicitly asyncronous, Python code (instead of gevent/monkey patching).
+
+It also further emphasizes the "It's just Python"-approach. If you, for example, want to take precise control of the ramp up and ramp down of a test, you shouldn't need to read the documentation, you should only need to know how to write code. We'll still provide the option of using prebuilt features too of course, but we'll try not to "build our users into a box".
+
+## High performance
+
+aiolocust is more performant than "regular" Locust because has a smaller footprint/complexity, but it's two main gains come from:
+
+### Using [asyncio](https://docs.python.org/3/library/asyncio.html) together with [aiohttp](https://docs.aiohttp.org/en/stable/)
+
+aiolocust's performance is *much* better than HttpUser (based on Requests), and even slightly better than FastHttpUser (based on geventhttpclient). Because it uses async programming instead of monkey patching it is more useful on modern Python and more future-proof. Specifically it allows your locustfile to easily use asyncio libraries (like Playwright), which are becoming more and more common.
+
+### Leveraging Python in its [freethreading/no-GIL](https://docs.python.org/3/howto/free-threading-python.html) form
+
+This means that you dont need to launch one locust process per core! Even if your load tests are doing some heavy computations, they are unlikely to impact eachother, as one thread will not block Python from running another one.
+
+In fact, you can still use syncronous libraries, (without gevent monkey patching), just increase the number of threads.
+
+Users/threads can also communicate easily with eachother, as they share memory with eachother, unlike in the old Locust implementation where you were forced to use zmq messaging between master and worker processes.
+
+### Some actual numbers
+
+For example, aiolocust can do almost 70k requests/s on a MacBook Pro M3. It is also much faster to start than regular Locust, and has no issues spawning a lot of new users in a short interval.
+
+```text
+  Name                   ┃   Count ┃ Failures ┃     Avg ┃        Max ┃       Rate
+ ━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━
+  http://localhost:8080/ │ 2032741 │ 0 (0.0%) │   2.8ms │     35.8ms │ 67659.22/s
+ ────────────────────────┼─────────┼──────────┼─────────┼────────────┼────────────
+  Total                  │   2.8ms │   35.8ms │ 2032741 │ 67659.22/s │
+```
+
+## Things this doesn't have compared do Locust (at least not yet)
+
+* A WebUI
+* Support for distributed tests
+* Polish. This is not ready for production use yet.
+
+## How to run the example
+
+```text
+git clone https://github.com/cyberw/aiolocust.git
+cd aiolocust
+uv run python locustfile.py
+```

aiolocust-0.1.0/README.md

@@ -0,0 +1,63 @@
+# AIOLocust
+
+This is a 2026 reimagining of [Locust](https://github.com/locustio/locust/). It is possible that we may merge the projects at some point, but for now it is a separate library.
+
+## Simpler and more consistent syntax than Locust, leveraging asyncio
+
+```python
+import asyncio
+from aiolocust import LocustClientSession
+
+async def user(client: LocustClientSession):
+    async with client.get("http://example.com/") as resp:
+        assert resp.status == 200
+    asyncio.sleep(0.1)
+```
+
+Locust was created in 2011, and while it has gone through several major overhauls, it still has a fair amount of legacy style code, and has accumulated a lot of non-core functionality that make it very hard to maintain and improve. It's 10000+ lines of code using a mix of procedural, object oriented and functional programming, with several confusing abstractions.
+
+AIOLocust is built to be smaller in scope, but capture the learnings from Locust. It uses modern, explicitly asyncronous, Python code (instead of gevent/monkey patching).
+
+It also further emphasizes the "It's just Python"-approach. If you, for example, want to take precise control of the ramp up and ramp down of a test, you shouldn't need to read the documentation, you should only need to know how to write code. We'll still provide the option of using prebuilt features too of course, but we'll try not to "build our users into a box".
+
+## High performance
+
+aiolocust is more performant than "regular" Locust because has a smaller footprint/complexity, but it's two main gains come from:
+
+### Using [asyncio](https://docs.python.org/3/library/asyncio.html) together with [aiohttp](https://docs.aiohttp.org/en/stable/)
+
+aiolocust's performance is *much* better than HttpUser (based on Requests), and even slightly better than FastHttpUser (based on geventhttpclient). Because it uses async programming instead of monkey patching it is more useful on modern Python and more future-proof. Specifically it allows your locustfile to easily use asyncio libraries (like Playwright), which are becoming more and more common.
+
+### Leveraging Python in its [freethreading/no-GIL](https://docs.python.org/3/howto/free-threading-python.html) form
+
+This means that you dont need to launch one locust process per core! Even if your load tests are doing some heavy computations, they are unlikely to impact eachother, as one thread will not block Python from running another one.
+
+In fact, you can still use syncronous libraries, (without gevent monkey patching), just increase the number of threads.
+
+Users/threads can also communicate easily with eachother, as they share memory with eachother, unlike in the old Locust implementation where you were forced to use zmq messaging between master and worker processes.
+
+### Some actual numbers
+
+For example, aiolocust can do almost 70k requests/s on a MacBook Pro M3. It is also much faster to start than regular Locust, and has no issues spawning a lot of new users in a short interval.
+
+```text
+  Name                   ┃   Count ┃ Failures ┃     Avg ┃        Max ┃       Rate
+ ━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━
+  http://localhost:8080/ │ 2032741 │ 0 (0.0%) │   2.8ms │     35.8ms │ 67659.22/s
+ ────────────────────────┼─────────┼──────────┼─────────┼────────────┼────────────
+  Total                  │   2.8ms │   35.8ms │ 2032741 │ 67659.22/s │
+```
+
+## Things this doesn't have compared do Locust (at least not yet)
+
+* A WebUI
+* Support for distributed tests
+* Polish. This is not ready for production use yet.
+
+## How to run the example
+
+```text
+git clone https://github.com/cyberw/aiolocust.git
+cd aiolocust
+uv run python locustfile.py
+```

aiolocust-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "aiolocust"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "Lars Holmberg", email = "lars.holmberg@redshirt.se" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "aiohttp>=3.13.3",
+    "rich>=14.2.0",
+    "uvloop>=0.22.1 ; sys_platform == 'linux'",
+    "uvloop>=0.22.1 ; sys_platform == 'darwin'",
+]
+
+[tool.uv]
+package = true
+
+[build-system]
+requires = ["uv_build>=0.9.7,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+target-version = "py314"
+line-length = 110
+# lint.ignore = ["E402", "E501", "E713", "E731"]
+lint.select = ["E", "F", "W", "UP", "I", "ARG001"]
+lint.dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?)|resp)$"
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.408",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "pytest-httpserver>=1.1.3",
+    "ruff>=0.14.10",
+]
+

aiolocust-0.1.0/src/aiolocust/__init__.py

@@ -0,0 +1,239 @@
+import asyncio
+import os
+import signal
+import sys
+import threading
+import time
+import warnings
+from collections.abc import Callable
+from typing import cast
+
+from aiohttp import ClientConnectorError, ClientResponse, ClientResponseError, ClientSession
+from aiohttp.client import _RequestContextManager
+from rich.console import Console
+from rich.table import Table
+
+from . import event_handlers
+from .datatypes import Request, RequestEntry
+
+# uvloop is faster than the default pure-python asyncio event loop
+# so if it is installed, we're going to be using that one
+try:
+    import uvloop
+
+    new_event_loop = uvloop.new_event_loop
+except ImportError:
+    new_event_loop = None
+
+# We're going to inherit from ClientSession, even though it is considered internal,
+# Because we dont want to take the performance hit and typing issues of wrapping every method
+warnings.filterwarnings(
+    action="ignore",
+    message=".*Inheritance .* from ClientSession is discouraged.*",
+    category=DeprecationWarning,
+    module="aiolocust",
+)
+
+if sys._is_gil_enabled():
+    raise RuntimeError("aiolocust requires a freethreading Python build")
+
+
+running = True
+console = Console()
+
+
+original_sigint_handler = signal.getsignal(signal.SIGINT)
+
+
+def signal_handler(_sig, _frame):
+    print("Stopping...")
+    global running
+    running = False
+    # stop everything immediately on second Ctrl-C
+    signal.signal(signal.SIGINT, original_sigint_handler)
+
+
+signal.signal(signal.SIGINT, signal_handler)
+
+
+async def stats_printer():
+    global running
+    start_time = time.perf_counter()
+    while running:
+        await asyncio.sleep(2)
+        requests_copy: dict[str, RequestEntry] = event_handlers.requests.copy()  # avoid mutation during print
+        elapsed = time.perf_counter() - start_time
+        total_ttlb = 0
+        total_max_ttlb = 0
+        total_count = 0
+        total_errorcount = 0
+        table = Table(show_edge=False)
+        table.add_column("Name", max_width=30)
+        table.add_column("Count", justify="right")
+        table.add_column("Failures", justify="right")
+        table.add_column("Avg", justify="right")
+        table.add_column("Max", justify="right")
+        table.add_column("Rate", justify="right")
+
+        for url, re in requests_copy.items():
+            table.add_row(
+                url,
+                str(re.count),
+                f"{re.errorcount} ({100 * re.errorcount / re.count:2.1f}%)",
+                f"{1000 * re.sum_ttlb / re.count:4.1f}ms",
+                f"{1000 * re.max_ttlb:4.1f}ms",
+                f"{re.count / elapsed:.2f}/s",
+            )
+            total_ttlb += re.sum_ttlb
+            total_max_ttlb = max(total_max_ttlb, re.max_ttlb)
+            total_count += re.count
+            total_errorcount += re.errorcount
+        table.add_section()
+        table.add_row(
+            "Total",
+            str(total_count),
+            f"{total_errorcount} ({100 * total_errorcount / total_count:2.1f}%)",
+            f"{1000 * total_ttlb / total_count:4.1f}ms",
+            f"{1000 * total_max_ttlb:4.1f}ms",
+            f"{total_count / elapsed:.2f}/s",
+        )
+        print()
+        console.print(table)
+
+        if elapsed > 30:
+            running = False
+
+
+class LocustResponse(ClientResponse):
+    error: Exception | bool | None = None
+
+    def __init__(self, *args, **kwargs):
+        raise NotImplementedError()  # use wrap_response
+
+    @classmethod
+    def wrap_response(cls, resp: ClientResponse) -> LocustResponse:
+        new = cast(LocustResponse, resp)
+        new.error = None
+        return new
+
+
+class LocustRequestContextManager(_RequestContextManager):
+    def __init__(self, request_handler: Callable, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        # slightly hacky way to get the URL, but passing it explicitly would be a mess
+        # and it is only used for connection errors where the exception doesn't contain URL
+        self.str_or_url = args[0]._coro.cr_frame.f_locals["str_or_url"]
+        self.request_handler = request_handler
+        self._resp: LocustResponse  # type: ignore
+
+    async def __aenter__(self) -> LocustResponse:
+        self.start_time = time.perf_counter()
+        try:
+            await super().__aenter__()
+        except ClientConnectorError as e:
+            elapsed = self.ttlb = time.perf_counter() - self.start_time
+            if request_info := getattr(e, "request_info", None):
+                url = request_info.url
+            else:
+                url = self.str_or_url
+            self.request_handler(Request(url, elapsed, elapsed, e))
+            raise
+        except ClientResponseError as e:
+            elapsed = self.ttlb = time.perf_counter() - self.start_time
+            self.request_handler(Request(str(e.request_info.url), elapsed, elapsed, e))
+            raise
+        else:
+            self.url = super()._resp.url
+            self.ttfb = time.perf_counter() - self.start_time
+            await self._resp.read()
+            self.ttlb = time.perf_counter() - self.start_time
+        return LocustResponse.wrap_response(self._resp)
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await super().__aexit__(exc_type, exc_val, exc_tb)
+        if self._resp.error is None:  # no explicit value set in with-block
+            self._resp.error = exc_val or self._resp.status >= 400
+        self.request_handler(
+            Request(
+                str(self.url),
+                self.ttfb,
+                self.ttlb,
+                self._resp.error,
+            )
+        )
+
+
+class LocustClientSession(ClientSession):
+    iteration = 0
+
+    def __init__(self, base_url=None, request_handler: Callable | None = None, **kwargs):
+        super().__init__(base_url=base_url, **kwargs)
+        self.request_handler = request_handler or event_handlers.request
+
+    # explicitly declare this to get the correct return type and enter session
+    async def __aenter__(self) -> LocustClientSession:
+        return self
+
+    def get(self, url, **kwargs) -> LocustRequestContextManager:
+        return LocustRequestContextManager(self.request_handler, super().get(url, **kwargs))
+
+    def post(self, url, **kwargs) -> LocustRequestContextManager:
+        return LocustRequestContextManager(self.request_handler, super().post(url, **kwargs))
+
+
+async def user_loop(user):
+    async with LocustClientSession() as client:
+        while running:
+            try:
+                await user(client)
+            except (ClientResponseError, AssertionError):
+                pass
+            client.iteration += 1
+
+
+async def user_runner(user, count, printer):
+    event_handlers.requests = {}
+    async with asyncio.TaskGroup() as tg:
+        if printer:
+            tg.create_task(stats_printer())
+        for _ in range(count):
+            tg.create_task(user_loop(user))
+
+
+def thread_worker(user, count, printer):
+    return asyncio.run(user_runner(user, count, printer), loop_factory=new_event_loop)
+
+
+def distribute_evenly(total, num_buckets):
+    # Calculate the base amount for every bucket
+    base = total // num_buckets
+    # Calculate how many buckets need an extra +1
+    remainder = total % num_buckets
+    # Create the list: add 1 to the first 'remainder' buckets
+    return [base + 1 if i < remainder else base for i in range(num_buckets)]
+
+
+async def main(user: Callable, user_count: int, event_loops: int | None = None):
+    if event_loops is None:
+        if cpu_count := os.cpu_count():
+            # for heavy calculations this may need to be increased,
+            # but for I/O bound tasks 1/2 of CPU cores seems to be the most efficient
+            event_loops = max(cpu_count // 2, 1)
+        else:
+            event_loops = 1
+
+    threads = []
+    for i in distribute_evenly(user_count, event_loops):
+        t = threading.Thread(
+            target=thread_worker,
+            args=(
+                user,
+                i,
+                not threads,  # first thread prints stats
+            ),
+        )
+        threads.append(t)
+        t.start()
+
+    for t in threads:
+        t.join()

aiolocust-0.1.0/src/aiolocust/datatypes.py

@@ -0,0 +1,18 @@
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class Request:
+    url: str
+    ttfb: float
+    ttlb: float
+    error: Exception | bool | None
+
+
+@dataclass(slots=True)
+class RequestEntry:
+    count: int
+    errorcount: int
+    sum_ttfb: float
+    sum_ttlb: float
+    max_ttlb: float

aiolocust-0.1.0/src/aiolocust/event_handlers.py

@@ -0,0 +1,16 @@
+from .datatypes import Request, RequestEntry
+
+requests: dict[str, RequestEntry] = {}
+
+
+def request(req: Request):
+    if req.url not in requests:
+        requests[req.url] = RequestEntry(1, 1 if req.error else 0, req.ttfb, req.ttlb, req.ttlb)
+    else:
+        re = requests[req.url]
+        re.count += 1
+        if req.error:
+            re.errorcount += 1
+        re.sum_ttfb += req.ttfb
+        re.sum_ttlb += req.ttlb
+        re.max_ttlb = max(re.max_ttlb, req.ttlb)