# Flask-Status
[](LICENSE)
The Flask Status Extension is a simple Flask extension that adds a status ping route to your Flask application. It allows you to easily check the health and status of your application or services by accessing a designated endpoint.
## Features
- **Status Endpoint**: Adds a status ping endpoint (`/api/status` by default) to your Flask application.
- **Custom Status Message**: Set a custom status message to provide more specific information about the health of your application.
- **Add more fields/data to status ping payload**: you can add more fields to the payload. This is helpful in cases where you want to add more info to the returned payload, for example, the state of the database.
- **Authenticated Ping route**: With `FlaskStatus`, you can now set the status ping route to be only accessed by authenticated users or requests.
See [below](#usage) for more info.
## Installation
To install the Flask Status Extension, you can use `pip`:
```bash
pip install flask-status
```
## Usage
Here's how to use the Flask-Status extension in your Flask application
- Install the package using pip
- create a file `main.py`
- Add the following to `main.py`
```python
from flask import Flask
from flask_status import FlaskStatus
app = Flask(__name__)
FlaskStatus(app)
if __name__ == "__main__":
app.run(host="0.0.0.0", port=5000)
```
- run the `main.py` file
```bash
python3 main.py
```
- Now go to [http://localhost:5000/api/status](http://localhost:5000/api/status)
- You should see the following
```json
{
"status": "OK"
}
```
You can also set the route for the status ping, and also the payload returned:
```python
app = Flask(__name__)
FlaskStatus(app, url="/api/ping", message={"message": "show my status"})
if __name__ == "__main__":
app.run(host="0.0.0.0", port=5000)
```
payload from [`http://localhost:5000/api/ping`](http://localhost:5000/api/ping):
```json
{
"message": "show my status"
}
```
If the message is just a string and not a dictionary, example:
```python
FlaskStatus(app, message="Running")
```
It'd be converted to a JSON object payload by putting it in a `message` field as follows follows:
```json
{
"message": "Running"
}
```
### Add more data
As said above, you can add more data to the status ping payload by using the `.add_field(key, value)` method. Example:
```python
flask_status = FlaskStatus(app)
flask_status.add_field("error", False)
# you can also add functions to run on request of the status route
def check_database():
# check if database is running
return True
flask_status.add_field("database", check_database)
```
The result payload of the above code is as follows:
```json
{
"status": "OK",
"error": false,
"database": true
}
```
### Authenticate status route
You can now also set the status ping route to be for only authenticated users of the API by passing an `authenticator` function which should be a decorator function to the flask route function. Example:
```python
from functools import wraps
# define an authenticator decorator function
def login_required(func):
@wraps(func)
def wrapper(*args, **kwargs):
token = request.cookies.get(AUTH_TOKEN_HEADER)
if not token:
return abort(401)
if not verify_token(token):
return abort(403)
return func(*args, **kwargs)
return wrapper
# define FlaskStatus with this authenticator function
FlaskStatus(app, authenticator=login_required)
```
The logic in the `authenticator` function would be run before returning the status payload in this manner:
```python
@app.route("/api/status")
@authenticator
def status_ping():
return jsonify({"status": "OK"})
```
## Issues
If you encounter any issues with this extension or have suggestions for improvements, please create an issue on the [GitHub Issues page](https://github.com/Emmo00/flask-status/issues).
You are also welcome to contributing to this project.
Special thanks to the Flask community
## Author
- [Emmanuel Nwafor](https://github.com/Emmo00)
## Contributors
<a href="https://github.com/emmo00/flask-status/graphs/contributors">
<p align="center">
<img src="https://contrib.rocks/image?repo=emmo00/flask-status" />
</p>
</a>
Raw data
{
"_id": null,
"home_page": "https://github.com/Emmo00/flask-status",
"name": "Flask-Status",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "flask ping,status ping,status,ping,flask",
"author": "Nwafor Emmanuel",
"author_email": "nwaforemmanuel005@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e4/77/807d672910686c3c7273c69ca7d8df72489317d068fab30e28fb921c5705/Flask-Status-1.0.1.tar.gz",
"platform": null,
"description": "# Flask-Status\n\n[](LICENSE)\n\nThe Flask Status Extension is a simple Flask extension that adds a status ping route to your Flask application. It allows you to easily check the health and status of your application or services by accessing a designated endpoint.\n\n## Features\n\n- **Status Endpoint**: Adds a status ping endpoint (`/api/status` by default) to your Flask application.\n- **Custom Status Message**: Set a custom status message to provide more specific information about the health of your application.\n- **Add more fields/data to status ping payload**: you can add more fields to the payload. This is helpful in cases where you want to add more info to the returned payload, for example, the state of the database.\n- **Authenticated Ping route**: With `FlaskStatus`, you can now set the status ping route to be only accessed by authenticated users or requests.\n\nSee [below](#usage) for more info.\n\n## Installation\n\nTo install the Flask Status Extension, you can use `pip`:\n\n```bash\npip install flask-status\n```\n\n## Usage\n\nHere's how to use the Flask-Status extension in your Flask application\n\n- Install the package using pip\n\n- create a file `main.py`\n\n- Add the following to `main.py`\n\n```python\nfrom flask import Flask\nfrom flask_status import FlaskStatus\n\napp = Flask(__name__)\nFlaskStatus(app)\n\nif __name__ == \"__main__\":\n app.run(host=\"0.0.0.0\", port=5000)\n```\n\n- run the `main.py` file\n\n```bash\npython3 main.py\n```\n\n- Now go to [http://localhost:5000/api/status](http://localhost:5000/api/status)\n\n- You should see the following\n\n```json\n{\n \"status\": \"OK\"\n}\n```\n\nYou can also set the route for the status ping, and also the payload returned:\n\n```python\napp = Flask(__name__)\nFlaskStatus(app, url=\"/api/ping\", message={\"message\": \"show my status\"})\n\nif __name__ == \"__main__\":\n app.run(host=\"0.0.0.0\", port=5000)\n```\n\npayload from [`http://localhost:5000/api/ping`](http://localhost:5000/api/ping):\n\n```json\n{\n \"message\": \"show my status\"\n}\n```\n\nIf the message is just a string and not a dictionary, example:\n\n```python\nFlaskStatus(app, message=\"Running\")\n```\n\nIt'd be converted to a JSON object payload by putting it in a `message` field as follows follows:\n\n```json\n{\n \"message\": \"Running\"\n}\n```\n\n### Add more data\n\nAs said above, you can add more data to the status ping payload by using the `.add_field(key, value)` method. Example:\n\n```python\nflask_status = FlaskStatus(app)\n\nflask_status.add_field(\"error\", False)\n\n# you can also add functions to run on request of the status route\ndef check_database():\n # check if database is running\n return True\n\nflask_status.add_field(\"database\", check_database)\n```\n\nThe result payload of the above code is as follows:\n\n```json\n{\n \"status\": \"OK\",\n \"error\": false,\n \"database\": true\n}\n```\n\n### Authenticate status route\n\nYou can now also set the status ping route to be for only authenticated users of the API by passing an `authenticator` function which should be a decorator function to the flask route function. Example:\n\n```python\nfrom functools import wraps\n\n# define an authenticator decorator function\ndef login_required(func):\n @wraps(func)\n def wrapper(*args, **kwargs):\n token = request.cookies.get(AUTH_TOKEN_HEADER)\n if not token:\n return abort(401)\n if not verify_token(token):\n return abort(403)\n return func(*args, **kwargs)\n return wrapper\n\n# define FlaskStatus with this authenticator function\nFlaskStatus(app, authenticator=login_required)\n```\n\nThe logic in the `authenticator` function would be run before returning the status payload in this manner:\n\n```python\n@app.route(\"/api/status\")\n@authenticator\ndef status_ping():\n return jsonify({\"status\": \"OK\"})\n```\n\n## Issues\n\nIf you encounter any issues with this extension or have suggestions for improvements, please create an issue on the [GitHub Issues page](https://github.com/Emmo00/flask-status/issues).\n\nYou are also welcome to contributing to this project.\n\nSpecial thanks to the Flask community\n\n## Author\n\n- [Emmanuel Nwafor](https://github.com/Emmo00)\n\n## Contributors\n\n<a href=\"https://github.com/emmo00/flask-status/graphs/contributors\">\n\t<p align=\"center\">\n \t\t<img src=\"https://contrib.rocks/image?repo=emmo00/flask-status\" />\n\t</p>\n</a>\n",
"bugtrack_url": null,
"license": "",
"summary": "Add status ping route to your Flask Server",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/Emmo00/flask-status"
},
"split_keywords": [
"flask ping",
"status ping",
"status",
"ping",
"flask"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a8b49b5e709661adcd18ee816605eb13b097bbf0fe0a94f49a89ccdfb5e111ec",
"md5": "433b521253eed083da35270e62991aa8",
"sha256": "5b2c65ebf0b7384edf7e2dc734ee76e219e774613d76dc0d261cbd2b418dbdf4"
},
"downloads": -1,
"filename": "Flask_Status-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "433b521253eed083da35270e62991aa8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 4854,
"upload_time": "2023-12-25T21:47:01",
"upload_time_iso_8601": "2023-12-25T21:47:01.326371Z",
"url": "https://files.pythonhosted.org/packages/a8/b4/9b5e709661adcd18ee816605eb13b097bbf0fe0a94f49a89ccdfb5e111ec/Flask_Status-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e477807d672910686c3c7273c69ca7d8df72489317d068fab30e28fb921c5705",
"md5": "70103c7779a301275ba314ea57600e91",
"sha256": "375fb9cb8184973c40eb74aaa34d6d60c48b219bc48da9ae3afb490ebc44e792"
},
"downloads": -1,
"filename": "Flask-Status-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "70103c7779a301275ba314ea57600e91",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 4527,
"upload_time": "2023-12-25T21:47:02",
"upload_time_iso_8601": "2023-12-25T21:47:02.953112Z",
"url": "https://files.pythonhosted.org/packages/e4/77/807d672910686c3c7273c69ca7d8df72489317d068fab30e28fb921c5705/Flask-Status-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-25 21:47:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Emmo00",
"github_project": "flask-status",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "flask-status"
}
JSON
