# Reactive structures - data structures with events
Provides several data structures with different events such as reactive list or reactive dict.
**Both ordinary and async functions are supported.**
# Example
```python
from rstructs import rlist
subscriptions = rlist()
@subscriptions.added
def on_user_subscribed(index, user):
if index == 0:
print(f'The first user {user} has just subscribed! ')
else:
print(f'{user} has just subscribed. ')
subscriptions.add('Bob')
subscriptions.add('Alice')
```
> The first user Bob has just subscribed!
>
> Alice has just subscribed.
# How to subscribe to events?
To subscribe to an event just decorate with it event handler.
```python
@subscriptions.added
def on_user_subscribed(index, user):
...
```
Moreover, a time to handle parameter can be used.
```python
@subscriptions.added(2) # handle only for the first two times
def on_user_subscribed(index, user):
...
```
# API
## Common predefined events
`constructed(initial_data)` - The structure was constructed and initialized.
`added(key, item)` - Added new item into the structure.
`before_added(key_or_item)` - Just before added new item into the structure.
`filled(key, item)` - The first item was added to the empty structure.
`before_filled(key_or_item)` - Just before the first item was added to the empty structure.
`changed(key, item)` - Changed existing item.
`before_changed(key, item)` - Just before changed existing item.
`updated(key, item)` - Added new item or changed existing one in the structure.
`before_updated(key_or_item)` - Just before added new item or changed existing one in the structure.
`removed(key, item)` - Removed existing item.
`before_removed(key_or_item)` - Just before removed existing item.
`emptied()` - The last item was removed from the structure.
`before_emptied()` - Just before the last item was removed from the structure.
## Additional predefined rlist events
`sorted()` - The list sorted inplace.
`before_sorted()` - Just before the list sorted inplace.
## Common predefined methods
`key_or_item in ...` - Checks whether key or item is contained by data.
`len(...)` - Returns data length.
`iter(...)` - Returns data iterator if available.
`...[key_or_item]` - alias to `get(key_or_item)`.
`...[key] = value` - alias to `update(key, value)`.
`del ...[key]` - alias to remove_key(key).
`add(key)->key, item` or `add(key, item)->key, item` - Add new item into the structure.
`change(key, item)` - Change existing item.
`update(key)` or `update(key, item)` - Add new item or change existing one in the structure. Firstly tries to change item and in case of ElementError adds as a new one.
`remove_key(key)->key, item` - Remove existing item.
`remove_item(item)->key, item` - Remove existing item.
`get(key_or_item, default=None)` - Get existing item. If default value is defined return it when ElementError occurs.
`clear()` - Remove all items from the structure. Derived classes should use remove methods per each item.
`index(item)->key` - Try to get key of item or rise ElementError.
## Additional predefined rlist methods
`sort(*, key=None, reverse=False)` - This method sorts the list in place, using only < comparisons between items. Exceptions are not suppressed - if any comparison operations fail, the entire sort operation will fail (and the list will likely be left in a partially modified state).
`...[key] = value` - alias to `change(key, value)`.
## Additional predefined rdict methods
`keys()->list[keys]` - get list of keys.
`values()->list[values]` - get list of keys.
`items()->list[tuple[key,value]]` - get list of tuples of keys and values.
# How to create your own reactive structure?
To create new reactive class you need to derive from `IReactiveStructure` and implement abstract methods (and optionally override other predefined methods).
# More details
This library is made on top of [eventsystem](https://pypi.org/project/eventsystem).
Raw data
{
"_id": null,
"home_page": null,
"name": "rstructs",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "reactive,structures,classes,list,dict,event,callback",
"author": null,
"author_email": "baterflyrity <baterflyrity@yandex.ru>",
"download_url": "https://files.pythonhosted.org/packages/36/da/177110aa0578dd51e47c2ed4f9edb22d5a18be84f561f826a7b9201722fb/rstructs-1.0.0.tar.gz",
"platform": null,
"description": "# Reactive structures - data structures with events\n\nProvides several data structures with different events such as reactive list or reactive dict.\n\n**Both ordinary and async functions are supported.**\n\n# Example\n\n```python\nfrom rstructs import rlist\n\nsubscriptions = rlist()\n\n\n@subscriptions.added\ndef on_user_subscribed(index, user):\n\tif index == 0:\n\t\tprint(f'The first user {user} has just subscribed! ')\n\telse:\n\t\tprint(f'{user} has just subscribed. ')\n\n\nsubscriptions.add('Bob')\nsubscriptions.add('Alice')\n\n```\n\n> The first user Bob has just subscribed!\n>\n> Alice has just subscribed.\n\n# How to subscribe to events?\n\nTo subscribe to an event just decorate with it event handler.\n\n```python\n@subscriptions.added\ndef on_user_subscribed(index, user):\n\t...\n```\n\nMoreover, a time to handle parameter can be used.\n\n```python\n@subscriptions.added(2) # handle only for the first two times\ndef on_user_subscribed(index, user):\n\t...\n```\n\n# API\n\n## Common predefined events\n\n`constructed(initial_data)` - The structure was constructed and initialized.\n\n`added(key, item)` - Added new item into the structure.\n\n`before_added(key_or_item)` - Just before added new item into the structure.\n\n`filled(key, item)` - The first item was added to the empty structure.\n\n`before_filled(key_or_item)` - Just before the first item was added to the empty structure.\n\n`changed(key, item)` - Changed existing item.\n\n`before_changed(key, item)` - Just before changed existing item.\n\n`updated(key, item)` - Added new item or changed existing one in the structure.\n\n`before_updated(key_or_item)` - Just before added new item or changed existing one in the structure.\n\n`removed(key, item)` - Removed existing item.\n\n`before_removed(key_or_item)` - Just before removed existing item.\n\n`emptied()` - The last item was removed from the structure.\n\n`before_emptied()` - Just before the last item was removed from the structure.\n\n## Additional predefined rlist events\n\n`sorted()` - The list sorted inplace.\n\n`before_sorted()` - Just before the list sorted inplace.\n\n## Common predefined methods\n\n`key_or_item in ...` - Checks whether key or item is contained by data.\n\n`len(...)` - Returns data length.\n\n`iter(...)` - Returns data iterator if available.\n\n`...[key_or_item]` - alias to `get(key_or_item)`.\n\n`...[key] = value` - alias to `update(key, value)`.\n\n`del ...[key]` - alias to remove_key(key).\n\n`add(key)->key, item` or `add(key, item)->key, item` - Add new item into the structure.\n\n`change(key, item)` - Change existing item.\n\n`update(key)` or `update(key, item)` - Add new item or change existing one in the structure. Firstly tries to change item and in case of ElementError adds as a new one.\n\n`remove_key(key)->key, item` - Remove existing item.\n\n`remove_item(item)->key, item` - Remove existing item.\n\n`get(key_or_item, default=None)` - Get existing item. If default value is defined return it when ElementError occurs.\n\n`clear()` - Remove all items from the structure. Derived classes should use remove methods per each item.\n\n`index(item)->key` - Try to get key of item or rise ElementError.\n\n## Additional predefined rlist methods\n\n`sort(*, key=None, reverse=False)` - This method sorts the list in place, using only < comparisons between items. Exceptions are not suppressed - if any comparison operations fail, the entire sort operation will fail (and the list will likely be left in a partially modified state).\n\n`...[key] = value` - alias to `change(key, value)`.\n\n## Additional predefined rdict methods\n\n`keys()->list[keys]` - get list of keys.\n\n`values()->list[values]` - get list of keys.\n\n`items()->list[tuple[key,value]]` - get list of tuples of keys and values.\n\n# How to create your own reactive structure?\n\nTo create new reactive class you need to derive from `IReactiveStructure` and implement abstract methods (and optionally override other predefined methods).\n\n# More details\n\nThis library is made on top of [eventsystem](https://pypi.org/project/eventsystem).\n",
"bugtrack_url": null,
"license": null,
"summary": "Reactive structures - data structures with events.",
"version": "1.0.0",
"split_keywords": [
"reactive",
"structures",
"classes",
"list",
"dict",
"event",
"callback"
],
"urls": [
{
"comment_text": null,
"digests": {
"md5": "ae73620279f1e66ebaa469a2595ca508",
"sha256": "0349766099bbd7f15c3b580923816ce2a0d0f468e27bb1f7ea5840c0521d8cee"
},
"downloads": -1,
"filename": "rstructs-1.0.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "ae73620279f1e66ebaa469a2595ca508",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 6245,
"upload_time": "2022-12-14T17:14:43",
"upload_time_iso_8601": "2022-12-14T17:14:43.135978Z",
"url": "https://files.pythonhosted.org/packages/8d/bd/18991e3377fca1134d64cfaacf8a1814101c93705799623737831182db01/rstructs-1.0.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"md5": "b8bb470080aecc13afa7bd2fbf381a7b",
"sha256": "087d327d30996c08933795f19af10dcf5f9defd46a814f972f7dfc339b31fb7c"
},
"downloads": -1,
"filename": "rstructs-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "b8bb470080aecc13afa7bd2fbf381a7b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5027,
"upload_time": "2022-12-14T17:14:48",
"upload_time_iso_8601": "2022-12-14T17:14:48.975715Z",
"url": "https://files.pythonhosted.org/packages/36/da/177110aa0578dd51e47c2ed4f9edb22d5a18be84f561f826a7b9201722fb/rstructs-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-14 17:14:48",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "rstructs"
}
JSON