# Lumi 💧 <a href="https://hits.seeyoufarm.com"><img src="https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fgithub.com%2FTanmoy741127%2Flumi&count_bg=%2379C83D&title_bg=%23555555&icon=&icon_color=%23E7E7E7&title=hits&edge_flat=false"/></a>
<img align="right" src="https://raw.githubusercontent.com/Tanmoy741127/cdn/main/lumi/lumi-logo.png" height="100px"/>
Lumi is a nano framework to convert your python functions into a REST API without any extra headache.
* This library is created by taking the concept of **RPC** and blended with **REST API** specs.
* We need to just register the function and it will be available as a REST API.
* Web-server written with **Gunicorn**
* Local development server provided for rapid development and prototyping.
## Installation
```bash
pip install lumi
```
## Function <--> API mapping
## How to use 🤔
Let's create a simple function to add two numbers.
```python
def add(a, b):
return a + b
def subtract(a, b):
return a - b
```
Now, we want to expose this function as a REST API. We can do this by registering the function with Lumi.
```python
# app.py
from lumi import Lumi
app = Lumi()
app.register(add) # Registering the function
app.register(subtract)
app.runServer(host="127.0.0.1", port=8080)
```
Noice 🎉🎉 API has been generated
Run the sever by
```
python app.py
```
You are going to see this in your terminal
```
[2022-11-24 17:32:08 +0530] [10490] [INFO] Starting gunicorn 20.1.0
[2022-11-24 17:32:08 +0530] [10490] [INFO] Listening at: http://127.0.0.1:8080 (10490)
[2022-11-24 17:32:08 +0530] [10490] [INFO] Using worker: sync
[2022-11-24 17:32:08 +0530] [10492] [INFO] Booting worker with pid: 10492
...
...
[2022-11-24 17:32:08 +0530] [10500] [INFO] Booting worker with pid: 10500
```
Congratulations 👏. Our Server is online.
The above code will generate a REST API with the following details.
- Endpoint : `127.0.0.1:8080`
- Route : `/add`
- Method : `POST`
- Sample Request Body : `{"a": 1, "b": 2}`
Let's run the API and test it.
```curl
curl -X POST -H "Content-Type: application/json" -d '{"a": 1, "b": 2}' http://127.0.0.1:8080/add
```
Output
```json
{
"exit_code": 0,
"status_code": 200,
"result": 3,
"error": ""
}
```
## Custom Routing
Now you may think, the function name will be always same as the route. But, you can change the route by passing the route parameter.
```python
app.register(add, route="/addition")
```
## Custom Request Method
By default, the request method is `POST`. But, you can change it by passing the method parameter. Currently, it supports `GET`, `POST`, `PUT` and `PATCH` methods.
```python
from lumi import Lumi, RequestMethod
app = Lumi()
def add(a, b):
return a+b
# Default : Register function for POST method
app.register(add)
# Register function for GET method
app.register(add, request_method=RequestMethod.GET)
# Register function for POST method
app.register(add, request_method=RequestMethod.POST)
# Register function for PUT method
app.register(add, request_method=RequestMethod.PUT)
# Register function for PATCH method
app.register(add, request_method=RequestMethod.PATCH)
app.runServer()
```
🟡 **Pay attention before using GET request :** If you are using `GET` method
- You need to pass the parameters in the query string, as `GET` dont support request body.
- All those arguments, that will be passed to function will be in **String** format. So take care to convert them to the desired type in your function.
## Send File
Send file to user by returning the file object.
```python
from lumi import Lumi, RequestMethod
app = Lumi()
def download_file():
return open("file.txt", "rb") # Return file object
app.register(download_file)
```
## Debug Mode
By default, the debug mode is `True`. But, you can change it by passing the debug parameter.
```python
# app.py
from lumi import Lumi
app = Lumi(debug=False)
...
```
## Status Codes
| Status Code | Description |
| --- | --- |
| 200 | Request successfully executed and No Error happened during function execution |
| 500 | Request was received but there was an error during function execution |
| 400 | Bad Request (Possible Reason - The required parameters for the function has not provided) |
| 405 | Method Not Allowed (Lumi only supports **POST** request) |
| 404 | The route has no function associated with that |
## Exit Codes
| Exit Code | Description |
| --- | --- |
| 0 | No Error |
| 1 | Error |
> Note : If the function has some error , you can expect the exit code to be 1 and the error message in the response.
## Task Lists
- [x] Base System
- [x] Add support for default parameters that is provided in the function
- [x] Debug mode and logging support
- [x] Make available GET request for the function
- [x] Provide option to override POST with PUT if the user wants
- [x] Add support to send file directly to user
- [ ] Add support to serve files through a public folder [Customizable]
- [ ] Add suport for middleware integration
- [ ] Support nested routing of urls
- [ ] For local development, create an file observer that can automatically reload the server when the file is changed.
- [ ] Add support for object serialization and deserialization based on argument types of function
## Contributing
Contributions are always welcome!
## Our community
<!-- readme: contributors -start -->
<table>
<tr>
<td align="center">
<a href="https://github.com/Tanmoy741127">
<img src="https://avatars.githubusercontent.com/u/57363826?v=4" width="100;" alt="Tanmoy741127"/>
<br />
<sub><b>Tanmoy Sarkar</b></sub>
</a>
</td>
<td align="center">
<a href="https://github.com/AmirMGhanem">
<img src="https://avatars.githubusercontent.com/u/55459991?v=4" width="100;" alt="AmirMGhanem"/>
<br />
<sub><b>Amir M. Ghanem</b></sub>
</a>
</td>
<td align="center">
<a href="https://github.com/matheusfelipeog">
<img src="https://avatars.githubusercontent.com/u/50463866?v=4" width="100;" alt="matheusfelipeog"/>
<br />
<sub><b>Matheus Felipe</b></sub>
</a>
</td>
<td align="center">
<a href="https://github.com/0xflotus">
<img src="https://avatars.githubusercontent.com/u/26602940?v=4" width="100;" alt="0xflotus"/>
<br />
<sub><b>0xflotus</b></sub>
</a>
</td></tr>
</table>
<!-- readme: contributors -end -->
## Support
<a href="https://www.buymeacoffee.com/tanmoysarkar" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
Raw data
{
"_id": null,
"home_page": "https://github.com/Tanmoy741127/lumi",
"name": "lumi",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "rpc rest api web backend framework",
"author": "Tanmoy Sarkar",
"author_email": "ts741127@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/17/35/47c0f69ad029a069cece516ac2e4cc9503f908e729c31503d0a30b81cbad/lumi-1.0.11.tar.gz",
"platform": null,
"description": "# Lumi \ud83d\udca7 <a href=\"https://hits.seeyoufarm.com\"><img src=\"https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fgithub.com%2FTanmoy741127%2Flumi&count_bg=%2379C83D&title_bg=%23555555&icon=&icon_color=%23E7E7E7&title=hits&edge_flat=false\"/></a>\n\n<img align=\"right\" src=\"https://raw.githubusercontent.com/Tanmoy741127/cdn/main/lumi/lumi-logo.png\" height=\"100px\"/>\n\nLumi is a nano framework to convert your python functions into a REST API without any extra headache.\n\n* This library is created by taking the concept of **RPC** and blended with **REST API** specs. \n* We need to just register the function and it will be available as a REST API. \n* Web-server written with **Gunicorn**\n* Local development server provided for rapid development and prototyping.\n\n## Installation\n\n```bash\npip install lumi\n```\n\n## Function <--> API mapping\n\n\n\n## How to use \ud83e\udd14\n\nLet's create a simple function to add two numbers.\n\n```python\ndef add(a, b):\n return a + b\n\ndef subtract(a, b):\n return a - b\n```\n\nNow, we want to expose this function as a REST API. We can do this by registering the function with Lumi.\n\n```python\n# app.py\n\nfrom lumi import Lumi\n\napp = Lumi()\n\napp.register(add) # Registering the function\napp.register(subtract)\n\napp.runServer(host=\"127.0.0.1\", port=8080)\n```\n\nNoice \ud83c\udf89\ud83c\udf89 API has been generated\n\nRun the sever by\n```\npython app.py\n```\nYou are going to see this in your terminal \n```\n[2022-11-24 17:32:08 +0530] [10490] [INFO] Starting gunicorn 20.1.0\n[2022-11-24 17:32:08 +0530] [10490] [INFO] Listening at: http://127.0.0.1:8080 (10490)\n[2022-11-24 17:32:08 +0530] [10490] [INFO] Using worker: sync\n[2022-11-24 17:32:08 +0530] [10492] [INFO] Booting worker with pid: 10492\n...\n...\n[2022-11-24 17:32:08 +0530] [10500] [INFO] Booting worker with pid: 10500\n```\n\nCongratulations \ud83d\udc4f. Our Server is online. \n\n\nThe above code will generate a REST API with the following details.\n\n- Endpoint : `127.0.0.1:8080`\n- Route : `/add`\n- Method : `POST`\n- Sample Request Body : `{\"a\": 1, \"b\": 2}`\n\nLet's run the API and test it.\n\n```curl\ncurl -X POST -H \"Content-Type: application/json\" -d '{\"a\": 1, \"b\": 2}' http://127.0.0.1:8080/add\n```\n\nOutput\n\n```json\n{\n \"exit_code\": 0, \n \"status_code\": 200, \n \"result\": 3, \n \"error\": \"\"\n}\n```\n\n## Custom Routing\nNow you may think, the function name will be always same as the route. But, you can change the route by passing the route parameter.\n\n```python\napp.register(add, route=\"/addition\")\n```\n## Custom Request Method\nBy default, the request method is `POST`. But, you can change it by passing the method parameter. Currently, it supports `GET`, `POST`, `PUT` and `PATCH` methods.\n\n```python\nfrom lumi import Lumi, RequestMethod\n\napp = Lumi()\n\ndef add(a, b):\n return a+b\n\n# Default : Register function for POST method\napp.register(add)\n# Register function for GET method\napp.register(add, request_method=RequestMethod.GET)\n# Register function for POST method\napp.register(add, request_method=RequestMethod.POST)\n# Register function for PUT method\napp.register(add, request_method=RequestMethod.PUT)\n# Register function for PATCH method\napp.register(add, request_method=RequestMethod.PATCH)\n\napp.runServer()\n```\n\n\ud83d\udfe1 **Pay attention before using GET request :** If you are using `GET` method\n- You need to pass the parameters in the query string, as `GET` dont support request body.\n- All those arguments, that will be passed to function will be in **String** format. So take care to convert them to the desired type in your function.\n\n\n## Send File\nSend file to user by returning the file object.\n\n```python\nfrom lumi import Lumi, RequestMethod\napp = Lumi()\n\ndef download_file():\n return open(\"file.txt\", \"rb\") # Return file object\n\napp.register(download_file) \n```\n\n## Debug Mode\nBy default, the debug mode is `True`. But, you can change it by passing the debug parameter.\n\n```python\n# app.py\n\nfrom lumi import Lumi\n\napp = Lumi(debug=False)\n...\n```\n\n## Status Codes\n\n| Status Code | Description |\n| --- | --- |\n| 200 | Request successfully executed and No Error happened during function execution |\n| 500 | Request was received but there was an error during function execution |\n| 400 | Bad Request (Possible Reason - The required parameters for the function has not provided) |\n| 405 | Method Not Allowed (Lumi only supports **POST** request) |\n| 404 | The route has no function associated with that |\n\n\n## Exit Codes\n| Exit Code | Description |\n| --- | --- |\n| 0 | No Error |\n| 1 | Error |\n\n> Note : If the function has some error , you can expect the exit code to be 1 and the error message in the response.\n\n## Task Lists\n- [x] Base System\n- [x] Add support for default parameters that is provided in the function\n- [x] Debug mode and logging support\n- [x] Make available GET request for the function\n- [x] Provide option to override POST with PUT if the user wants\n- [x] Add support to send file directly to user\n- [ ] Add support to serve files through a public folder [Customizable]\n- [ ] Add suport for middleware integration\n- [ ] Support nested routing of urls\n- [ ] For local development, create an file observer that can automatically reload the server when the file is changed.\n- [ ] Add support for object serialization and deserialization based on argument types of function\n\n## Contributing\n\nContributions are always welcome!\n## Our community\n\n<!-- readme: contributors -start -->\n<table>\n<tr>\n <td align=\"center\">\n <a href=\"https://github.com/Tanmoy741127\">\n <img src=\"https://avatars.githubusercontent.com/u/57363826?v=4\" width=\"100;\" alt=\"Tanmoy741127\"/>\n <br />\n <sub><b>Tanmoy Sarkar</b></sub>\n </a>\n </td>\n <td align=\"center\">\n <a href=\"https://github.com/AmirMGhanem\">\n <img src=\"https://avatars.githubusercontent.com/u/55459991?v=4\" width=\"100;\" alt=\"AmirMGhanem\"/>\n <br />\n <sub><b>Amir M. Ghanem</b></sub>\n </a>\n </td>\n <td align=\"center\">\n <a href=\"https://github.com/matheusfelipeog\">\n <img src=\"https://avatars.githubusercontent.com/u/50463866?v=4\" width=\"100;\" alt=\"matheusfelipeog\"/>\n <br />\n <sub><b>Matheus Felipe</b></sub>\n </a>\n </td>\n <td align=\"center\">\n <a href=\"https://github.com/0xflotus\">\n <img src=\"https://avatars.githubusercontent.com/u/26602940?v=4\" width=\"100;\" alt=\"0xflotus\"/>\n <br />\n <sub><b>0xflotus</b></sub>\n </a>\n </td></tr>\n</table>\n<!-- readme: contributors -end -->\n\n## Support\n<a href=\"https://www.buymeacoffee.com/tanmoysarkar\" target=\"_blank\"><img src=\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\" alt=\"Buy Me A Coffee\" style=\"height: 60px !important;width: 217px !important;\" ></a>\n\n\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "Convert your Python functions into REST API without any extra effort \ud83d\udd25",
"version": "1.0.11",
"split_keywords": [
"rpc",
"rest",
"api",
"web",
"backend",
"framework"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "189e02868a75a9a1c4c29c0e2f15c4e8",
"sha256": "b4d7ad8da620dd94fefa78d70ad93dfc02d7cf38b3622911e1f6d7987ed63fe2"
},
"downloads": -1,
"filename": "lumi-1.0.11-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "189e02868a75a9a1c4c29c0e2f15c4e8",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 8982,
"upload_time": "2022-12-22T08:45:56",
"upload_time_iso_8601": "2022-12-22T08:45:56.377802Z",
"url": "https://files.pythonhosted.org/packages/8b/c1/2fe3a2ef259ebe8298ecf8e731037bbd24f57df55b218310718428695e8b/lumi-1.0.11-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "9f1e1307d6e37d356987c97b026b676a",
"sha256": "3f1a3936fe7298a2d69778e83343bd39d7319e7cc88e1288b7c12ecbac7f7c1d"
},
"downloads": -1,
"filename": "lumi-1.0.11.tar.gz",
"has_sig": false,
"md5_digest": "9f1e1307d6e37d356987c97b026b676a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 10385,
"upload_time": "2022-12-22T08:45:58",
"upload_time_iso_8601": "2022-12-22T08:45:58.385375Z",
"url": "https://files.pythonhosted.org/packages/17/35/47c0f69ad029a069cece516ac2e4cc9503f908e729c31503d0a30b81cbad/lumi-1.0.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-22 08:45:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "Tanmoy741127",
"github_project": "lumi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "nanoid",
"specs": [
[
"==",
"2.0.0"
]
]
},
{
"name": "waitress",
"specs": [
[
"==",
"2.1.2"
]
]
}
],
"lcname": "lumi"
}
JSON
