<p>
<a href="">
<img src="https://img.shields.io/pypi/v/willump?style=for-the-badge" alt="PyPi">
</a>
<a href="">
<img src="https://img.shields.io/github/license/elliejs/willump?style=for-the-badge" alt="license">
</a>
<a href="">
<img src="https://img.shields.io/pypi/dm/willump?style=for-the-badge" alt="downloads/month">
</a>
</p>
# New in Willump 1.4.0
Nunu got a few new tricks, and now auto generates ssl certificates and keys. Anyone can create nunu apps now without too much network administration pre-requisite information!
# New in Willump 1.3.0
Willump now handles authentication tokens with '=' inside them! Woo!
# New in Willump 1.2.6
## Nunu: The server that translates Yeti to English
Read the [Nunu](https://github.com/elliejs/Willump/blob/main/tutorial/nunu.md) readme and get started with your League of Legends webapp today!
# Willump
Willump is a Python3 helper for the League of Legends LCU API. Willump is asynchronous and can communicate on both HTTPS and WSS channels.
Willump would not exist without [lcu-driver](https://github.com/sousa-andre/lcu-driver), another driver for the League of Legends LCU API. Huge thanks to [Andre Sousa](https://github.com/sousa-andre) for creating the starting point for Willump.
Documentation for the LCU can be found on the [Hextech Docs](https://www.hextechdocs.dev/lol/lcuapi), and a schema of the LCU can be found [here](http://www.mingweisamuel.com/lcu-schema/tool/).
If you have questions about Willump or the Riot API, find me or ask a question at the [Riot Games Third Party Developer Community](https://discord.gg/riotgamesdevrel) Discord.
## Installing Willump
Willump can be installed through pip
```
pip install willump
```
Or `pip3` if using python3 pip
## Starting Willump
There are two ways to start Willump
```py
from willump import Willump #if you want to import the class
wllp = await Willump.start()
```
Or
```py
import willump
wllp = await willump.start()
```
this is generally fine since Willump contains no class methods
This starts Willump's http and websocket clients. Note: `start()` blocks until Willump can connect to the League Client Ux process and server
## Using HTTP methods
Willump can can make http requests to any LCU endpoint
```py
response = await wllp.request('get', '/lol-summoner/v1/current-summoner')
#request can be used to execute 'get', as well as any other http method
print(await response.json())
```
## Subscribing to websocket events
Willump's websocket can subscribe to LCU events. Willump can attach a user defined `default_handler` to an event subscription which will be fired any time Willump receives a websocket message pertaining to the event and the message is not otherwise handled. `default_handler` is a function which accepts json formatted data as its sole argument and returns None, or a disposable value.
```py
async def un_default_handler(data):
print("user defined default event handler")
print(json.dumps(data, indent=4, sort_keys=True))
my_first_subscription = await wllp.subscribe('OnJsonApiEvent',
default_handler=un_default_handler)
```
You can add subscriptions to an event by resubscribing to the same event
```py
new_subscription = await wllp.subscribe('OnJsonApiEvent')
```
If you want to attach an already made subscription to another event, you can pass it to the subscription handler:
```py
same_as_new_subscription = await wllp.subscribe('OnJsonApiEvent_patcher_v1_status',
subscription=new_subscription)
print(same_subscription_as_new_subscription is new_subscription)
#True, subscription is shallow copied
```
You can get the attached subscriptions to an event:
```py
all_subscriptions = wllp.get_subscriptions('OnJsonApiEvent')
```
Willump can also unsubscribe from events to stop listening for them entirely, or can remove a subscription from an event:
```py
await wllp.unsubscribe('OnJsonApiEvent', my_first_subscription) #new_subscription is still active
await wllp.unsubscribe('OnJsonApiEvent')#This removes new_subscription,
#as well as any other subscriptions on 'OnJsonApiEvent'
```
## Attaching endpoint filters to event subscriptions
Willump's subscriptions contain two further kinds of filters on websocket events -- uri filters and path filters. These are collectively known as endpoint filters. An endpoint filter is a function that runs when a certain endpoint is specified by the event response. A subscription can have multiple endpoint handlers attached to it. Path filters end in '/', and run when the specified endpoint is any sub-endpoint of the path. Uri filters run when the endpoint is the same as the filter's uri. You can attach endpoint filters through the subscription itself, or via Willump with the subscription instance. Endpoint handlers take the same signature as `default_handler`. They must take in json formatted data and return None, or a disposable value. Uri handlers and path handlers will both fire if they overlap. If an endpoint filter is fired, the subscription's `default_handler` will not fire. Attaching two endpoint handlers to the same endpoint will overwrite the pre-existing endpoint handler.
```py
async def custom_uri_handler(data):
print('current-summoner uri got triggered. This is custom_uri_handler')
async def custom_path_handler(data):
print('/lol-summoner/ path got triggered. This is custom_path_handler')
print('full triggered uri is:', data['uri'])
#adding uri endpoint filter via subscription instance
my_first_subscription.filter_endpoint('/lol-summoner/v1/current-summoner',
custom_uri_handler)
#adding path endpoint filter via subscription instance through Willump
wllp.subscription_filter_endpoint(my_first_subscription, '/lol-summoner/',
custom_path_handler)
#unfiltering endpoints
wllp.subscription_unfilter_endpoint(my_first_subscription, '/lol-summoner/')
my_first_subscription.unfilter_endpoint('/lol-summoner/v1/current-summoner')
```
## Closing Willump
Closing Willump attempts to close the http and ws connections, gather outstanding subscription tasks, and gracefully exit.
```py
await wllp.close()
```
*Willump isn't endorsed by Riot Games and doesn't reflect the views or opinions of Riot Games or anyone officially involved in producing or managing Riot Games properties. Riot Games, and all associated properties are trademarks or registered trademarks of Riot Games, Inc.*
Raw data
{
"_id": null,
"home_page": "https://github.com/elliejs/Willump",
"name": "willump",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7, <4",
"maintainer_email": "",
"keywords": "api,wamp,rest,websocket,server,ssl",
"author": "elliejs",
"author_email": "ejsilver@wpi.edu",
"download_url": "https://files.pythonhosted.org/packages/e7/6b/ab7586e698713d607a5051ddd165a9595134269296ab95cc2a5964e6f6c9/willump-1.4.0.tar.gz",
"platform": null,
"description": "<p>\r\n<a href=\"\">\r\n <img src=\"https://img.shields.io/pypi/v/willump?style=for-the-badge\" alt=\"PyPi\">\r\n </a>\r\n <a href=\"\">\r\n <img src=\"https://img.shields.io/github/license/elliejs/willump?style=for-the-badge\" alt=\"license\">\r\n </a>\r\n <a href=\"\">\r\n <img src=\"https://img.shields.io/pypi/dm/willump?style=for-the-badge\" alt=\"downloads/month\">\r\n </a>\r\n</p>\r\n\r\n# New in Willump 1.4.0\r\nNunu got a few new tricks, and now auto generates ssl certificates and keys. Anyone can create nunu apps now without too much network administration pre-requisite information!\r\n\r\n# New in Willump 1.3.0\r\nWillump now handles authentication tokens with '=' inside them! Woo!\r\n\r\n# New in Willump 1.2.6\r\n## Nunu: The server that translates Yeti to English\r\nRead the [Nunu](https://github.com/elliejs/Willump/blob/main/tutorial/nunu.md) readme and get started with your League of Legends webapp today!\r\n\r\n# Willump\r\nWillump is a Python3 helper for the League of Legends LCU API. Willump is asynchronous and can communicate on both HTTPS and WSS channels.\r\n\r\nWillump would not exist without [lcu-driver](https://github.com/sousa-andre/lcu-driver), another driver for the League of Legends LCU API. Huge thanks to [Andre Sousa](https://github.com/sousa-andre) for creating the starting point for Willump.\r\n\r\nDocumentation for the LCU can be found on the [Hextech Docs](https://www.hextechdocs.dev/lol/lcuapi), and a schema of the LCU can be found [here](http://www.mingweisamuel.com/lcu-schema/tool/).\r\n\r\nIf you have questions about Willump or the Riot API, find me or ask a question at the [Riot Games Third Party Developer Community](https://discord.gg/riotgamesdevrel) Discord.\r\n\r\n## Installing Willump\r\nWillump can be installed through pip\r\n```\r\npip install willump\r\n```\r\nOr `pip3` if using python3 pip\r\n\r\n## Starting Willump\r\nThere are two ways to start Willump\r\n```py\r\nfrom willump import Willump #if you want to import the class\r\n\r\nwllp = await Willump.start()\r\n```\r\nOr\r\n```py\r\nimport willump\r\n\r\nwllp = await willump.start()\r\n```\r\nthis is generally fine since Willump contains no class methods\r\n\r\nThis starts Willump's http and websocket clients. Note: `start()` blocks until Willump can connect to the League Client Ux process and server\r\n\r\n## Using HTTP methods\r\nWillump can can make http requests to any LCU endpoint\r\n```py\r\nresponse = await wllp.request('get', '/lol-summoner/v1/current-summoner')\r\n#request can be used to execute 'get', as well as any other http method\r\nprint(await response.json())\r\n```\r\n\r\n## Subscribing to websocket events\r\nWillump's websocket can subscribe to LCU events. Willump can attach a user defined `default_handler` to an event subscription which will be fired any time Willump receives a websocket message pertaining to the event and the message is not otherwise handled. `default_handler` is a function which accepts json formatted data as its sole argument and returns None, or a disposable value.\r\n```py\r\nasync def un_default_handler(data):\r\n print(\"user defined default event handler\")\r\n print(json.dumps(data, indent=4, sort_keys=True))\r\n\r\nmy_first_subscription = await wllp.subscribe('OnJsonApiEvent',\r\n default_handler=un_default_handler)\r\n```\r\n\r\nYou can add subscriptions to an event by resubscribing to the same event\r\n```py\r\nnew_subscription = await wllp.subscribe('OnJsonApiEvent')\r\n```\r\n\r\nIf you want to attach an already made subscription to another event, you can pass it to the subscription handler:\r\n```py\r\nsame_as_new_subscription = await wllp.subscribe('OnJsonApiEvent_patcher_v1_status',\r\n subscription=new_subscription)\r\nprint(same_subscription_as_new_subscription is new_subscription)\r\n#True, subscription is shallow copied\r\n```\r\n\r\nYou can get the attached subscriptions to an event:\r\n```py\r\nall_subscriptions = wllp.get_subscriptions('OnJsonApiEvent')\r\n```\r\n\r\nWillump can also unsubscribe from events to stop listening for them entirely, or can remove a subscription from an event:\r\n```py\r\nawait wllp.unsubscribe('OnJsonApiEvent', my_first_subscription) #new_subscription is still active\r\nawait wllp.unsubscribe('OnJsonApiEvent')#This removes new_subscription,\r\n #as well as any other subscriptions on 'OnJsonApiEvent'\r\n```\r\n\r\n## Attaching endpoint filters to event subscriptions\r\nWillump's subscriptions contain two further kinds of filters on websocket events -- uri filters and path filters. These are collectively known as endpoint filters. An endpoint filter is a function that runs when a certain endpoint is specified by the event response. A subscription can have multiple endpoint handlers attached to it. Path filters end in '/', and run when the specified endpoint is any sub-endpoint of the path. Uri filters run when the endpoint is the same as the filter's uri. You can attach endpoint filters through the subscription itself, or via Willump with the subscription instance. Endpoint handlers take the same signature as `default_handler`. They must take in json formatted data and return None, or a disposable value. Uri handlers and path handlers will both fire if they overlap. If an endpoint filter is fired, the subscription's `default_handler` will not fire. Attaching two endpoint handlers to the same endpoint will overwrite the pre-existing endpoint handler.\r\n\r\n```py\r\nasync def custom_uri_handler(data):\r\n print('current-summoner uri got triggered. This is custom_uri_handler')\r\n\r\nasync def custom_path_handler(data):\r\n print('/lol-summoner/ path got triggered. This is custom_path_handler')\r\n print('full triggered uri is:', data['uri'])\r\n\r\n#adding uri endpoint filter via subscription instance\r\nmy_first_subscription.filter_endpoint('/lol-summoner/v1/current-summoner',\r\n custom_uri_handler)\r\n\r\n#adding path endpoint filter via subscription instance through Willump\r\nwllp.subscription_filter_endpoint(my_first_subscription, '/lol-summoner/',\r\n custom_path_handler)\r\n\r\n#unfiltering endpoints\r\nwllp.subscription_unfilter_endpoint(my_first_subscription, '/lol-summoner/')\r\nmy_first_subscription.unfilter_endpoint('/lol-summoner/v1/current-summoner')\r\n```\r\n\r\n## Closing Willump\r\nClosing Willump attempts to close the http and ws connections, gather outstanding subscription tasks, and gracefully exit.\r\n```py\r\nawait wllp.close()\r\n```\r\n\r\n*Willump isn't endorsed by Riot Games and doesn't reflect the views or opinions of Riot Games or anyone officially involved in producing or managing Riot Games properties. Riot Games, and all associated properties are trademarks or registered trademarks of Riot Games, Inc.*\r\n",
"bugtrack_url": null,
"license": "",
"summary": "Willump is a Python3 helper for the League of Legends LCU API",
"version": "1.4.0",
"split_keywords": [
"api",
"wamp",
"rest",
"websocket",
"server",
"ssl"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "77427ce5a54483b236ca0b1458b58d5c4e344569beca49ca0433db90ea05aeea",
"md5": "c7cb9a23cc6e7fe470dabd09da0b738f",
"sha256": "d93fb9274aa7232edbf6038578200489020484182746d55767f5faa15becaeef"
},
"downloads": -1,
"filename": "willump-1.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c7cb9a23cc6e7fe470dabd09da0b738f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7, <4",
"size": 10977,
"upload_time": "2023-04-02T21:47:22",
"upload_time_iso_8601": "2023-04-02T21:47:22.147629Z",
"url": "https://files.pythonhosted.org/packages/77/42/7ce5a54483b236ca0b1458b58d5c4e344569beca49ca0433db90ea05aeea/willump-1.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e76bab7586e698713d607a5051ddd165a9595134269296ab95cc2a5964e6f6c9",
"md5": "54949b7703f506833219594e3df1108d",
"sha256": "1b1ce870673d28da4ddee1a89b693db65c7be7121384adb31045e19bf07e60a8"
},
"downloads": -1,
"filename": "willump-1.4.0.tar.gz",
"has_sig": false,
"md5_digest": "54949b7703f506833219594e3df1108d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7, <4",
"size": 13022,
"upload_time": "2023-04-02T21:47:24",
"upload_time_iso_8601": "2023-04-02T21:47:24.093380Z",
"url": "https://files.pythonhosted.org/packages/e7/6b/ab7586e698713d607a5051ddd165a9595134269296ab95cc2a5964e6f6c9/willump-1.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-02 21:47:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "elliejs",
"github_project": "Willump",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "willump"
}
JSON
