aiocallback


Nameaiocallback JSON
Version 0.1.7 PyPI version JSON
download
home_pageNone
SummaryA library for helping configure callbacks with asyncio and aiosignal
upload_time2025-07-14 00:15:42
maintainerNone
docs_urlNone
authorNone
requires_python>=3.9
licenseNone
keywords event callbacks callbacks asyncio
VCS
bugtrack_url
requirements frozenlist typing_extensions
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # aiocallback:
[![PyPI version](https://badge.fury.io/py/aiocallback.svg)](https://badge.fury.io/py/aiocallback)
![PyPI - Downloads](https://img.shields.io/pypi/dm/aiocallback)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)



An asynchronous helper framework for writing custom event wrapper class functions made with good typehinting that is based off [aiosignal](https://github.com/aio-libs/aiosignal) with better modifications added for better typehinting and easier usage with tools such as pyright or mypy allowing for arguments to be properly typehinted at when performing any created callback which ultimately means less confusion and more action.

One of my biggest pet peves of all time is when **static type-checkers don't pick up what functions parameters are being used**. This library aims to fix static typecheckers when send() functions are being used, 
 so that developers aren't second guessing what different paremeters are needed. This is a big advantage over aiosignal and was the main reson behind it's creation.
 
<img src="https://raw.githubusercontent.com/Vizonex/aiocallback/main/Typehinting-Example.png" width="500px"/>






# Usage:
Aiocallback should be used when dealing with creating custom context objects or callbacks. An example might be scraping an api by a given hour 
and calling for that data that can be defined by multiple functions. However, there are many more creative ways to use this library.

## Dependencies
- [frozenlist](https://github.com/aio-libs/frozenlist) we dropped aiosignal in favor of frozenlist temporarly until aiosignal plans to support __ParamSpec__ There isn't much demand for it yet but I did help revive that library recently. 
- [typing-extensions](https://github.com/python/typing_extensions) Typehinting for Python 3.9, plan to drop typing-extensions when 3.9 hits End of Life so that __ParamSpec__ can be utilized to it's fullest potential.


## Installing

The easiest way is to install **aiocallback** is from PyPI using pip:

```sh
pip install aiocallback
```

## Running

First, import the library.

```python
from aiocallback import event, subclassevent, contextevent
import asyncio

class Config:
    """an example of configuring callbacks"""

    # NOTE: Typehinting will be passed to other objects 
    # Thanks in largepart to ParamSpec and Concatenate
    
    # NOTE: @event considers the function to be an abstract method, However you can use a subclassevent to retain typechecking if you need something that isn't so abstract
    @event
    async def on_print(self, cb:str):
        """callbacks for a print method"""

    @subclassevent
    async def on_nonabstract(self, cb:str):
        """a nonabstract method can be called with other events as being part of the signal"""
        print(f"I am callable! \"{cb}\"")




cfg = Config()
# You can also call the append method just like with aiosignal as ours is primarly a subclass of it.
@cfg.on_print
async def test(cb:str):
    print(f"called test {cb}")



async def main():
    # This uses aiosignal under the hood so remeber to freeze the callbacks when your setup is complete
    cfg.on_print.freeze()
    cfg.on_nonabstract.freeze()

    await cfg.on_print.send("Hello world")
    await cfg.on_nonabstract.send("Hello world")

if __name__ == "__main__":
    asyncio.run(main())

```

## Using EventLists
There's an alternative way to use aiocallback where you don't need to freeze many Configurable event descriptors at a time. You should use it if your not planning to use a dataclass although we plan to implement a special EventList for msgspec.

```python
from aiocallback import EventList, event

class MyEvents(EventList):
    @event
    async def on_event(self, item:str):...

events = MyEvents()
# all events get frozen for you and this method is built-in.
events.freeze()

```

## Links
- [Tutorial](https://youtu.be/Ly_G1CstOfA)

## Alternatives
- [aiosignal](https://github.com/aio-libs/aiosignal) I am a contributor over there as well and we're making some intresting imporvements over there so keep your eyes peeled.


# TODOS
- [ ] Trusted Publishing
- [ ] Smaller improvements to aiocallback like documentation for future readthedocs page.

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "aiocallback",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": null,
    "keywords": "event callbacks, callbacks, asyncio",
    "author": null,
    "author_email": "Vizonex <VizonexBusiness@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/ba/5d/df555f3d5f5225093125f09de8be2b9e28325c233ab474e4f76a35c3a08a/aiocallback-0.1.7.tar.gz",
    "platform": null,
    "description": "# aiocallback:\n[![PyPI version](https://badge.fury.io/py/aiocallback.svg)](https://badge.fury.io/py/aiocallback)\n![PyPI - Downloads](https://img.shields.io/pypi/dm/aiocallback)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)\n[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)\n\n\n\nAn asynchronous helper framework for writing custom event wrapper class functions made with good typehinting that is based off [aiosignal](https://github.com/aio-libs/aiosignal) with better modifications added for better typehinting and easier usage with tools such as pyright or mypy allowing for arguments to be properly typehinted at when performing any created callback which ultimately means less confusion and more action.\n\nOne of my biggest pet peves of all time is when **static type-checkers don't pick up what functions parameters are being used**. This library aims to fix static typecheckers when send() functions are being used, \n so that developers aren't second guessing what different paremeters are needed. This is a big advantage over aiosignal and was the main reson behind it's creation.\n \n<img src=\"https://raw.githubusercontent.com/Vizonex/aiocallback/main/Typehinting-Example.png\" width=\"500px\"/>\n\n\n\n\n\n\n# Usage:\nAiocallback should be used when dealing with creating custom context objects or callbacks. An example might be scraping an api by a given hour \nand calling for that data that can be defined by multiple functions. However, there are many more creative ways to use this library.\n\n## Dependencies\n- [frozenlist](https://github.com/aio-libs/frozenlist) we dropped aiosignal in favor of frozenlist temporarly until aiosignal plans to support __ParamSpec__ There isn't much demand for it yet but I did help revive that library recently. \n- [typing-extensions](https://github.com/python/typing_extensions) Typehinting for Python 3.9, plan to drop typing-extensions when 3.9 hits End of Life so that __ParamSpec__ can be utilized to it's fullest potential.\n\n\n## Installing\n\nThe easiest way is to install **aiocallback** is from PyPI using pip:\n\n```sh\npip install aiocallback\n```\n\n## Running\n\nFirst, import the library.\n\n```python\nfrom aiocallback import event, subclassevent, contextevent\nimport asyncio\n\nclass Config:\n    \"\"\"an example of configuring callbacks\"\"\"\n\n    # NOTE: Typehinting will be passed to other objects \n    # Thanks in largepart to ParamSpec and Concatenate\n    \n    # NOTE: @event considers the function to be an abstract method, However you can use a subclassevent to retain typechecking if you need something that isn't so abstract\n    @event\n    async def on_print(self, cb:str):\n        \"\"\"callbacks for a print method\"\"\"\n\n    @subclassevent\n    async def on_nonabstract(self, cb:str):\n        \"\"\"a nonabstract method can be called with other events as being part of the signal\"\"\"\n        print(f\"I am callable! \\\"{cb}\\\"\")\n\n\n\n\ncfg = Config()\n# You can also call the append method just like with aiosignal as ours is primarly a subclass of it.\n@cfg.on_print\nasync def test(cb:str):\n    print(f\"called test {cb}\")\n\n\n\nasync def main():\n    # This uses aiosignal under the hood so remeber to freeze the callbacks when your setup is complete\n    cfg.on_print.freeze()\n    cfg.on_nonabstract.freeze()\n\n    await cfg.on_print.send(\"Hello world\")\n    await cfg.on_nonabstract.send(\"Hello world\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n\n```\n\n## Using EventLists\nThere's an alternative way to use aiocallback where you don't need to freeze many Configurable event descriptors at a time. You should use it if your not planning to use a dataclass although we plan to implement a special EventList for msgspec.\n\n```python\nfrom aiocallback import EventList, event\n\nclass MyEvents(EventList):\n    @event\n    async def on_event(self, item:str):...\n\nevents = MyEvents()\n# all events get frozen for you and this method is built-in.\nevents.freeze()\n\n```\n\n## Links\n- [Tutorial](https://youtu.be/Ly_G1CstOfA)\n\n## Alternatives\n- [aiosignal](https://github.com/aio-libs/aiosignal) I am a contributor over there as well and we're making some intresting imporvements over there so keep your eyes peeled.\n\n\n# TODOS\n- [ ] Trusted Publishing\n- [ ] Smaller improvements to aiocallback like documentation for future readthedocs page.\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "A library for helping configure callbacks with asyncio and aiosignal",
    "version": "0.1.7",
    "project_urls": {
        "homepage": "https://github.com/Vizonex/aiocallback",
        "repository": "https://github.com/Vizonex/aiocallback.git"
    },
    "split_keywords": [
        "event callbacks",
        " callbacks",
        " asyncio"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "3fd756af57aacd27cb84623215dde785242b28a7801b69513a3878cd09afcf66",
                "md5": "fbf2cd831fbb1e484f6715e545f16cba",
                "sha256": "9fc8103fff85f0cf846e4491d704d9f93cdfcaa54e49db5e4cbc8348fc29f56d"
            },
            "downloads": -1,
            "filename": "aiocallback-0.1.7-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "fbf2cd831fbb1e484f6715e545f16cba",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 8223,
            "upload_time": "2025-07-14T00:15:41",
            "upload_time_iso_8601": "2025-07-14T00:15:41.265814Z",
            "url": "https://files.pythonhosted.org/packages/3f/d7/56af57aacd27cb84623215dde785242b28a7801b69513a3878cd09afcf66/aiocallback-0.1.7-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "ba5ddf555f3d5f5225093125f09de8be2b9e28325c233ab474e4f76a35c3a08a",
                "md5": "70251a24b688f72b6d772b9f4c05d565",
                "sha256": "a122fc569d6b58146ae19f5c181bdace5716002f5b7c7a761b1897dd3a53650c"
            },
            "downloads": -1,
            "filename": "aiocallback-0.1.7.tar.gz",
            "has_sig": false,
            "md5_digest": "70251a24b688f72b6d772b9f4c05d565",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.9",
            "size": 10680,
            "upload_time": "2025-07-14T00:15:42",
            "upload_time_iso_8601": "2025-07-14T00:15:42.357473Z",
            "url": "https://files.pythonhosted.org/packages/ba/5d/df555f3d5f5225093125f09de8be2b9e28325c233ab474e4f76a35c3a08a/aiocallback-0.1.7.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-14 00:15:42",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "Vizonex",
    "github_project": "aiocallback",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [
        {
            "name": "frozenlist",
            "specs": []
        },
        {
            "name": "typing_extensions",
            "specs": []
        }
    ],
    "lcname": "aiocallback"
}
        
Elapsed time: 0.46156s