{"id":13737546,"url":"https://github.com/dbrattli/aioreactive","last_synced_at":"2025-04-04T04:13:14.310Z","repository":{"id":39261218,"uuid":"70188493","full_name":"dbrattli/aioreactive","owner":"dbrattli","description":"Async/await reactive tools for Python 3.11+","archived":false,"fork":false,"pushed_at":"2024-04-12T04:28:49.000Z","size":588,"stargazers_count":336,"open_issues_count":14,"forks_count":22,"subscribers_count":21,"default_branch":"master","last_synced_at":"2024-05-19T13:31:21.775Z","etag":null,"topics":["async","asyncio","asynciterator","expression","functional","functional-programming","rxpy","streams"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dbrattli.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-06T20:01:45.000Z","updated_at":"2024-06-19T00:25:04.795Z","dependencies_parsed_at":"2024-02-25T23:21:37.684Z","dependency_job_id":"24fe8ae1-791d-4127-8686-0298cc7bd052","html_url":"https://github.com/dbrattli/aioreactive","commit_stats":{"total_commits":161,"total_committers":7,"mean_commits":23.0,"dds":"0.17391304347826086","last_synced_commit":"ca5a3881d0b546b2ca9725af5ebce00ff6cf95e9"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbrattli%2Faioreactive","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbrattli%2Faioreactive/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbrattli%2Faioreactive/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbrattli%2Faioreactive/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dbrattli","download_url":"https://codeload.github.com/dbrattli/aioreactive/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247117749,"owners_count":20886439,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["async","asyncio","asynciterator","expression","functional","functional-programming","rxpy","streams"],"created_at":"2024-08-03T03:01:52.850Z","updated_at":"2025-04-04T04:13:14.287Z","avatar_url":"https://github.com/dbrattli.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\r\n\u003cimg src=\"logo/logo.jpg\" alt=\"drawing\" width=\"200\"/\u003e\r\n\r\n# aioreactive - ReactiveX for asyncio using async and await\r\n\r\n[![PyPI](https://img.shields.io/pypi/v/aioreactive.svg)](https://pypi.python.org/pypi/aioreactive)\r\n![Python package](https://github.com/dbrattli/aioreactive/workflows/Python%20package/badge.svg)\r\n![Publish Package](https://github.com/dbrattli/aioreactive/actions/workflows/python-publish.yml/badge.svg)\r\n[![codecov](https://codecov.io/gh/dbrattli/aioreactive/branch/master/graph/badge.svg)](https://codecov.io/gh/dbrattli/aioreactive)\r\n\r\n\u003e *NEWS: Project rebooted Nov. 2020. Rebuilt using [Expression](https://github.com/dbrattli/Expression).*\r\n\r\nAioreactive is [RxPY](https://github.com/ReactiveX/RxPY) for asyncio.\r\nIt's an asynchronous and reactive Python library for asyncio using async\r\nand await. Aioreactive is built on the\r\n[Expression](https://github.com/dbrattli/Expression) functional library\r\nand, integrates naturally with the Python language.\r\n\r\n\u003e aioreactive is the unification of RxPY and reactive programming with\r\n\u003e asyncio using async and await.\r\n\r\n## The design goals for aioreactive\r\n\r\n* Python 3.10+ only. We have a hard dependency [Expression v5]([https://www.python.org/dev/peps/pep-0585/](https://github.com/dbrattli/Expression)).\r\n* All operators and tools are implemented as plain old functions.\r\n* Everything is `async`. Sending values is async, subscribing to\r\n  observables is async. Disposing subscriptions is async.\r\n* One scheduler to rule them all. Everything runs on the asyncio base\r\n  event-loop.\r\n* No multi-threading. Only async and await with concurrency using\r\n  asyncio. Threads are hard, and in many cases it doesn’t make sense to\r\n  use multi-threading in Python applications. If you need to use threads\r\n  you may wrap them with\r\n  [`concurrent.futures`](https://docs.python.org/3/library/concurrent.futures.html#module-concurrent.futures)\r\n  and compose them into the chain with `flat_map()` or similar. See\r\n  [`parallel.py`](https://github.com/dbrattli/aioreactive/blob/master/examples/parallel/parallel.py)\r\n  for an example.\r\n* Simple, clean and use few abstractions. Try to align with the\r\n  itertools package, and reuse as much from the Python standard library\r\n  as possible.\r\n* Support type hints and static type checking using [Pylance](https://devblogs.microsoft.com/python/announcing-pylance-fast-feature-rich-language-support-for-python-in-visual-studio-code/).\r\n* Implicit synchronous back-pressure \u0026trade;. Producers of events will\r\n  simply be awaited until the event can be processed by the down-stream\r\n  consumers.\r\n\r\n## AsyncObservable and AsyncObserver\r\n\r\nWith aioreactive you subscribe observers to observables, and the key\r\nabstractions of aioreactive can be seen in this single line of code:\r\n\r\n```python\r\nsubscription = await observable.subscribe_async(observer)\r\n```\r\n\r\nThe difference from RxPY can be seen with the `await` expression.\r\nAioreactive is built around the asynchronous duals, or opposites of the\r\nAsyncIterable and AsyncIterator abstract base classes. These async\r\nclasses are called AsyncObservable and AsyncObserver.\r\n\r\nAsyncObservable is a producer of events. It may be seen as the dual or\r\nopposite of AsyncIterable and provides a single setter method called\r\n`subscribe_async()` that is the dual of the `__aiter__()` getter method:\r\n\r\n```python\r\nfrom abc import ABC, abstractmethod\r\n\r\nclass AsyncObservable(ABC):\r\n    @abstractmethod\r\n    async def subscribe_async(self, observer):\r\n        return NotImplemented\r\n```\r\n\r\nAsyncObserver is a consumer of events and is modeled after the\r\nso-called [consumer interface](http://effbot.org/zone/consumer.htm), the\r\nenhanced generator interface in\r\n[PEP-342](https://www.python.org/dev/peps/pep-0342/) and async\r\ngenerators in [PEP-525](https://www.python.org/dev/peps/pep-0525/). It\r\nis the dual of the AsyncIterator `__anext__()` method, and expands to\r\nthree async methods `asend()`, that is the opposite of `__anext__()`,\r\n`athrow()` that is the opposite of an `raise Exception()` and `aclose()`\r\nthat is the opposite of `raise StopAsyncIteration`:\r\n\r\n```python\r\nfrom abc import ABC, abstractmethod\r\n\r\nclass AsyncObserver(ABC):\r\n    @abstractmethod\r\n    async def asend(self, value):\r\n        return NotImplemented\r\n\r\n    @abstractmethod\r\n    async def athrow(self, error):\r\n        return NotImplemented\r\n\r\n    @abstractmethod\r\n    async def aclose(self):\r\n        return NotImplemented\r\n```\r\n\r\n## Subscribing to observables\r\n\r\nAn observable becomes hot and starts streaming items by using the\r\n`subscribe_async()` method. The `subscribe_async()` method takes an\r\nobservable and returns a disposable subscription. So the\r\n`subscribe_async()` method is used to attach a observer to the\r\nobservable.\r\n\r\n```python\r\nasync def asend(value):\r\n    print(value)\r\n\r\ndisposable = await subscribe_async(source, AsyncAnonymousObserver(asend))\r\n```\r\n\r\n`AsyncAnonymousObserver` is an anonymous observer that constructs an\r\n`AsyncObserver` out of plain async functions, so you don't have to\r\nimplement a new named observer every time you need one.\r\n\r\nThe subscription returned by `subscribe_async()` is disposable, so to\r\nunsubscribe you need to await the `dispose_async()` method on the\r\nsubscription.\r\n\r\n```python\r\nawait subscription.dispose_async()\r\n```\r\n\r\n## Asynchronous iteration\r\n\r\nEven more interesting, with `to_async_iterable` you can flip around from\r\n`AsyncObservable` to an `AsyncIterable` and use `async-for` to consume\r\nthe stream of events.\r\n\r\n```python\r\nimport aioreactive as rx\r\n\r\nxs = rx.from_iterable([1, 2, 3])\r\nasync for x in xs:\r\n    print(x)\r\n```\r\n\r\nThey effectively transform us from an async push model to an async pull\r\nmodel, and lets us use the awesome new language features such as `async\r\nfor` and `async-with`. We do this without any queueing, as a push by the\r\n`AsyncObservable` will await the pull by the `AsyncIterator.  This\r\neffectively applies so-called \"back-pressure\" up the subscription as the\r\nproducer will await the iterator to pick up the item send.\r\n\r\nThe for-loop may be wrapped with async-with to control the lifetime of\r\nthe subscription:\r\n\r\n```python\r\nimport aioreactive as rx\r\n\r\nxs = rx.from_iterable([1, 2, 3])\r\nresult = []\r\n\r\nobv = rx.AsyncIteratorObserver(xs)\r\nasync with await xs.subscribe_async(obv) as subscription:\r\n    async for x in obv:\r\n        result.append(x)\r\n\r\nassert result == [1, 2, 3]\r\n```\r\n\r\n## Async streams\r\n\r\nAn async stream is both an async observer and an async observable.\r\nAioreactive lets you create streams explicitly.\r\n\r\n```python\r\nimport aioreactive as rx\r\n\r\nstream = AsyncSubject()  # Alias for AsyncMultiStream\r\n\r\nsink = rx.AsyncAnonymousObserver()\r\nawait stream.subscribe_async(sink)\r\nawait stream.asend(42)\r\n```\r\n\r\nYou can create streams directly from `AsyncMultiStream` or\r\n`AsyncSingleStream`. `AsyncMultiStream` supports multiple observers, and\r\nis hot in the sense that it will drop any event that is sent if there\r\nare currently no observers attached. `AsyncSingleStream` on the other\r\nhand supports a single observer, and is cold in the sense that it will\r\nawait any producer until there is an observer attached.\r\n\r\n## Operators\r\n\r\nThe Rx operators in aioreactive are all plain old functions. You can\r\napply them to an observable and compose it into a transformed, filtered,\r\naggregated or combined observable. This transformed observable can be\r\nstreamed into an observer.\r\n\r\n    Observable -\u003e Operator -\u003e Operator -\u003e Operator -\u003e Observer\r\n\r\nAioreactive contains many of the same operators as you know from RxPY.\r\nOur goal is not to implement them all, but to provide the most essential\r\nones.\r\n\r\n* **concat** -- Concatenates two or more observables.\r\n* **choose** -- Filters and/or transforms the observable.\r\n* **choose_asnc** -- Asynchronously filters and/or transforms the observable.\r\n* **debounce** -- Throttles an observable.\r\n* **delay** -- delays the items within an observable.\r\n* **distinct_until_changed** -- an observable with continuously distinct values.\r\n* **filter** -- filters an observable.\r\n* **filteri** -- filters an observable with index.\r\n* **flat_map** -- transforms an observable into a stream of observables and flattens the resulting observable.\r\n* **flat_map_latest** -- transforms an observable into a stream of\r\n  observables and flattens the resulting observable by producing values\r\n  from the latest observable.\r\n* **from_iterable** -- Create an observable from an (async) iterable.\r\n* **subscribe** -- Subscribes an observer to an observable. Returns a subscription.\r\n* **map** -- transforms an observable.\r\n* **mapi** -- transforms an observable with index.\r\n* **map_async** -- transforms an observable asynchronously.\r\n* **mapi_async** -- transforms an observable asynchronously with index.\r\n* **merge_inner** -- Merges an observable of observables.\r\n* **merge** -- Merge one observable with another observable.\r\n* **merge_seq** -- Merge a sequence of observables.\r\n* **run** -- Awaits the future returned by subscribe. Returns when the subscription closes.\r\n* **slice** -- Slices an observable.\r\n* **skip** -- Skip items from the start of the observable stream.\r\n* **skip_last** -- Skip items from the end of the observable stream.\r\n* **starfilter** -- Filters an observable with a predicate and spreads the arguments.\r\n* **starmap** -- Transforms and async observable and spreads the arguments to the mapper.\r\n* **switch_latest** -- Merges the latest stream in an observable of streams.\r\n* **take** -- Take a number of items from the start of the observable stream.\r\n* **take_last** -- Take a number of items from the end of the observable stream.\r\n* **unit** -- Converts a value or future to an observable.\r\n* **with_latest_from** -- Combines two observables into one.\r\n\r\n# Functional or object-oriented, reactive or interactive\r\n\r\nWith aioreactive you can choose to program functionally with plain old\r\nfunctions, or object-oriented with classes and methods. Aioreactive\r\nsupports both method chaining or forward pipe programming styles.\r\n\r\n## Pipe forward programming style\r\n\r\n`AsyncObservable` may compose operators using forward pipelining with\r\nthe `pipe` operator provided by the amazing\r\n[Expression](https://github.com/dbrattli/Expression) library. This works\r\nby having the operators partially applied with their arguments before\r\nbeing given the source stream as the last curried argument.\r\n\r\n```python\r\nys = pipe(xs, filter(predicate), map(mapper), flat_map(request))\r\n```\r\n\r\nLonger pipelines may break lines as for binary operators:\r\n\r\n```python\r\nimport aioreactve as rx\r\n\r\nasync def main():\r\n    stream = rx.AsyncSubject()\r\n    obv = rx.AsyncIteratorObserver()\r\n\r\n    xs = pipe(\r\n        stream,\r\n        rx.map(lambda x: x[\"term\"]),\r\n        rx.filter(lambda text: len(text) \u003e 2),\r\n        rx.debounce(0.75),\r\n        rx.distinct_until_changed(),\r\n        rx.map(search_wikipedia),\r\n        rx.switch_latest(),\r\n    )\r\n\r\n    async with xs.subscribe_async(obv) as ys\r\n        async for value in obv:\r\n            print(value)\r\n```\r\n\r\nAsyncObservable also supports slicing using the Python slice notation.\r\n\r\n```python\r\n@pytest.mark.asyncio\r\nasync def test_slice_special():\r\n    xs = rx.from_iterable([1, 2, 3, 4, 5])\r\n    values = []\r\n\r\n    async def asend(value):\r\n        values.append(value)\r\n\r\n    ys = xs[1:-1]\r\n\r\n    result = await run(ys, AsyncAnonymousObserver(asend))\r\n\r\n    assert result == 4\r\n    assert values == [2, 3, 4]\r\n```\r\n\r\n# Fluent and chained programming style\r\n\r\nAn alternative to pipelining is to use the classic and fluent method\r\nchaining as we know from [ReactiveX](http://reactivex.io).\r\n\r\nAn `AsyncObservable` created from class methods such as\r\n`AsyncRx.from_iterable()` returns a `AsyncChainedObservable`.\r\nwhere we may use methods such as `.filter()` and `.map()`.\r\n\r\n```python\r\nfrom aioreactive import AsyncRx\r\n\r\n@pytest.mark.asyncio\r\nasync def test_observable_simple_pipe():\r\n    xs = AsyncRx.from_iterable([1, 2, 3])\r\n    result = []\r\n\r\n    async def mapper(value):\r\n        await asyncio.sleep(0.1)\r\n        return value * 10\r\n\r\n    async def predicate(value):\r\n        await asyncio.sleep(0.1)\r\n        return value \u003e 1\r\n\r\n    ys = xs.filter(predicate).map(mapper)\r\n\r\n    async def on_next(value):\r\n        result.append(value)\r\n\r\n    subscription = await ys.subscribe_async(AsyncAnonymousObserver(on_next))\r\n    await subsubscription\r\n    assert result == [20, 30]\r\n```\r\n\r\n# Virtual time testing\r\n\r\nAioreactive also provides a virtual time event loop\r\n(`VirtualTimeEventLoop`) that enables you to write asyncio unit-tests\r\nthat run in virtual time. Virtual time means that time is emulated, so\r\ntests run as quickly as possible even if they sleep or awaits long-lived\r\noperations. A test using virtual time still gives the same result as it\r\nwould have done if it had been run in real-time.\r\n\r\nFor example the following test still gives the correct result even if it\r\ntakes 0 seconds to run:\r\n\r\n```python\r\n@pytest.fixture()\r\ndef event_loop():\r\n    loop = VirtualTimeEventLoop()\r\n    yield loop\r\n    loop.close()\r\n\r\n@pytest.mark.asyncio\r\nasync def test_call_later():\r\n    result = []\r\n\r\n    def action(value):\r\n        result.append(value)\r\n\r\n    loop = asyncio.get_event_loop()\r\n    loop.call_later(10, partial(action, 1))\r\n    loop.call_later(1, partial(action, 2))\r\n    loop.call_later(5, partial(action, 3))\r\n    await asyncio.sleep(10)\r\n    assert result == [2, 3, 1]\r\n```\r\n\r\nThe aioreactive testing module provides a test `AsyncSubject` that may\r\ndelay sending values, and a test `AsyncTestObserver` that records all\r\nevents. These two classes helps you with testing in virtual time.\r\n\r\n```python\r\n@pytest.fixture()\r\ndef event_loop():\r\n    loop = VirtualTimeEventLoop()\r\n    yield loop\r\n    loop.close()\r\n\r\n@pytest.mark.asyncio\r\nasync def test_delay_done():\r\n    xs = AsyncTestSubject()  # Test stream\r\n\r\n    ys = pipe(xs, rx.delay(1.0))\r\n    obv = AsyncTestObserver()  # Test AsyncAnonymousObserver\r\n    async with await ys.subscribe_async(obv):\r\n        await xs.asend_later(0, 10)\r\n        await xs.asend_later(1.0, 20)\r\n        await xs.aclose_later(1.0)\r\n        await obv\r\n\r\n    assert obv.values == [\r\n        (ca(1), OnNext(10)),\r\n        (ca(2), OnNext(20)),\r\n        (ca(3), OnCompleted()),\r\n    ]\r\n```\r\n\r\n# Why not use AsyncIterable for everything?\r\n\r\n`AsyncIterable` and `AsyncObservable` are closely related (in fact they\r\nare duals). `AsyncIterable` is an async iterable (pull) world, while\r\n`AsyncObservable` is an async reactive (push) based world. There are\r\nmany operations such as `map()` and `filter()` that may be simpler to\r\nimplement using `AsyncIterable`, but once we start to include time, then\r\n`AsyncObservable` really starts to shine. Operators such as `delay()`\r\nmakes much more sense for `AsyncObservable` than for `AsyncIterable`.\r\n\r\nHowever, aioreactive makes it easy for you to flip-around to async\r\niterable just before you need to consume the stream, thus giving you the\r\nbest of both worlds.\r\n\r\n# Will aioreactive replace RxPY?\r\n\r\nAioreactive will not replace [RxPY](https://github.com/ReactiveX/RxPY).\r\nRxPY is an implementation of `Observable`. Aioreactive is an\r\nimplementation of `AsyncObservable`.\r\n\r\nRx and RxPY has hundreds of different query operators, and we currently\r\nhave no plans to implementing all of them for aioreactive.\r\n\r\nMany ideas from aioreactive have already been ported back into \"classic\" RxPY.\r\n\r\n# References\r\n\r\nAioreactive was inspired by:\r\n\r\n* [AsyncRx](https://github.com/dbrattli/asyncrx) - Aioreactive is a direct port of AsyncRx from F#.\r\n* [Expression](https://github.com/dbrattli/Expression) - Functional programming for Python.\r\n* [Is it really Pythonic to continue using LINQ operators instead of plain old functions?](https://github.com/ReactiveX/RxPY/issues/94)\r\n* [Reactive Extensions (Rx)](http://reactivex.io) and [RxPY](https://github.com/ReactiveX/RxPY).\r\n* [Dart Streams](https://www.dartlang.org/tutorials/language/streams)\r\n* [Underscore.js](http://underscorejs.org).\r\n* [itertools](https://docs.python.org/3/library/itertools.html) and [functools](https://docs.python.org/3/library/functools.html).\r\n* [dbrattli/OSlash](https://github.com/dbrattli/OSlash)\r\n* [kriskowal/q](https://github.com/kriskowal/q).\r\n\r\n# License\r\n\r\nThe MIT License (MIT)\r\nCopyright (c) 2016 Børge Lanes, Dag Brattli.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbrattli%2Faioreactive","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdbrattli%2Faioreactive","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbrattli%2Faioreactive/lists"}