# sag_py_web_common
[![Maintainability][codeclimate-image]][codeclimate-url]
[![Coverage Status][coveralls-image]][coveralls-url]
[![Known Vulnerabilities][snyk-image]][snyk-url]
This contains samhammer specific and internally used helper functions for web projects.
Requirements for code to be added here:
- It's sag/project specific and not of general/public use, so that it does not make sense to create a individual lib
- It's nothing private either, that should not be publically on the internet
- It has no, or very little dependencies
(because the deps are in all projects using the lib, even if the feaute isn't required)
Note: See this as last option and try to create individual libs as much as possible.
### Installation
pip install sag-py-web-common
## How to use
### Default routing
All requests to the main route / are redirected to /swagger if nothing specified.
```python
from sag_py_web_common.default_route import build_default_route
app: FastAPI = FastAPI(...)
app.include_router(build_default_route(ingress_base_path=config.ingress_base_path))
```
- ingress_base_path: Empty or a path starting with / if proxy hosting like kubernetes is used
- default_redirect_path: Per default /swagger but can be configured to an alternative route
### Filtered access logging
Extends the asgi-logger and adds a log entry for received requests.
Furthermore the requests are filtered, so that health checks don't spam the logs.
For requests to be filtered, they need to have the header "healthcheck" with one of these values:
"livenessprobe", "readinessprobe", "startupprobe", "prtg"
```python
from sag_py_web_common.filtered_access_logger import FilteredAccessLoggerMiddleware
app: FastAPI = FastAPI(...)
app.add_middleware(
FilteredAccessLoggerMiddleware,
format="Completed: %(R)s - %(st)s - %(L)s",
logger=logging.getLogger("access"),
)
```
Also see this page for further configuration details: https://github.com/Kludex/asgi-logger
### Json exception handler
Per default fastapi falls back to text responses if there are unknown exceptions.
That's not the desired behaviour for json api's.
This handler ensures that a json is returned. It contains the field "detail" with the exception message.
```python
from sag_py_web_common.json_exception_handler import handle_unknown_exception
app.add_exception_handler(Exception, handle_unknown_exception)
```
For logging any HHTP-Exception use the **log_exception** function.
```python
from starlette.exceptions import HTTPException as StarletteHTTPException
from sag_py_web_common.json_exception_handler import log_exception
app.add_exception_handler(StarletteHTTPException, log_exception)
```
Json Exception handler uses logger "http_error_logger", which could be used for reporting concepts.
## How to start developing
### With vscode
Just install vscode with dev containers extension. All required extensions and configurations are prepared automatically.
### With pycharm
* Install latest pycharm
* Install pycharm plugin BlackConnect
* Install pycharm plugin Mypy
* Configure the python interpreter/venv
* pip install requirements-dev.txt
* pip install black[d]
* Ctl+Alt+S => Check Tools => BlackConnect => Trigger when saving changed files
* Ctl+Alt+S => Check Tools => BlackConnect => Trigger on code reformat
* Ctl+Alt+S => Click Tools => BlackConnect => "Load from pyproject.yaml" (ensure line length is 120)
* Ctl+Alt+S => Click Tools => BlackConnect => Configure path to the blackd.exe at the "local instance" config (e.g. C:\Python310\Scripts\blackd.exe)
* Ctl+Alt+S => Click Tools => Actions on save => Reformat code
* Restart pycharm
## How to publish
* Update the version in setup.py and commit your change
* Create a tag with the same version number
* Let github do the rest
## How to test
To avoid publishing to pypi unnecessarily you can do as follows
* Tag your branch however you like
* Use the chosen tag in the requirements.txt-file of the project you want to test this library in, eg. `sag_py_web_common==<your tag>`
* Rebuild/redeploy your project
[codeclimate-image]:https://api.codeclimate.com/v1/badges/533686a1f4d644151adb/maintainability
[codeclimate-url]:https://codeclimate.com/github/SamhammerAG/sag_py_web_common/maintainability
[coveralls-image]:https://coveralls.io/repos/github/SamhammerAG/sag_py_web_common/badge.svg?branch=master
[coveralls-url]:https://coveralls.io/github/SamhammerAG/sag_py_web_common?branch=master
[snyk-image]:https://snyk.io/test/github/SamhammerAG/sag_py_web_common/badge.svg
[snyk-url]:https://snyk.io/test/github/SamhammerAG/sag_py_web_common
Raw data
{
"_id": null,
"home_page": "https://github.com/SamhammerAG/sag_py_web_common",
"name": "sag-py-web-common",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "fastapi, web, helper, common",
"author": "Samhammer AG",
"author_email": "support@samhammer.de",
"download_url": "https://files.pythonhosted.org/packages/81/99/6f73a87c64a885e48d622d6f57c7f89ce6b750f379357b9930acd7d9f41f/sag_py_web_common-1.0.0.tar.gz",
"platform": null,
"description": "# sag_py_web_common\n[![Maintainability][codeclimate-image]][codeclimate-url]\n[![Coverage Status][coveralls-image]][coveralls-url]\n[![Known Vulnerabilities][snyk-image]][snyk-url]\n\nThis contains samhammer specific and internally used helper functions for web projects.\n\nRequirements for code to be added here:\n- It's sag/project specific and not of general/public use, so that it does not make sense to create a individual lib\n- It's nothing private either, that should not be publically on the internet\n- It has no, or very little dependencies\n (because the deps are in all projects using the lib, even if the feaute isn't required)\n\nNote: See this as last option and try to create individual libs as much as possible.\n\n### Installation\npip install sag-py-web-common\n\n## How to use\n### Default routing\n\nAll requests to the main route / are redirected to /swagger if nothing specified.\n\n```python\nfrom sag_py_web_common.default_route import build_default_route\n\napp: FastAPI = FastAPI(...)\n\napp.include_router(build_default_route(ingress_base_path=config.ingress_base_path))\n```\n\n- ingress_base_path: Empty or a path starting with / if proxy hosting like kubernetes is used\n- default_redirect_path: Per default /swagger but can be configured to an alternative route\n\n### Filtered access logging\n\nExtends the asgi-logger and adds a log entry for received requests.\nFurthermore the requests are filtered, so that health checks don't spam the logs.\n\nFor requests to be filtered, they need to have the header \"healthcheck\" with one of these values:\n\"livenessprobe\", \"readinessprobe\", \"startupprobe\", \"prtg\"\n\n```python\nfrom sag_py_web_common.filtered_access_logger import FilteredAccessLoggerMiddleware\n\napp: FastAPI = FastAPI(...)\n\napp.add_middleware(\n FilteredAccessLoggerMiddleware,\n format=\"Completed: %(R)s - %(st)s - %(L)s\",\n logger=logging.getLogger(\"access\"),\n)\n```\n\nAlso see this page for further configuration details: https://github.com/Kludex/asgi-logger\n\n### Json exception handler\n\nPer default fastapi falls back to text responses if there are unknown exceptions.\nThat's not the desired behaviour for json api's.\n\nThis handler ensures that a json is returned. It contains the field \"detail\" with the exception message.\n\n```python\nfrom sag_py_web_common.json_exception_handler import handle_unknown_exception\n\napp.add_exception_handler(Exception, handle_unknown_exception)\n```\nFor logging any HHTP-Exception use the **log_exception** function.\n\n```python\nfrom starlette.exceptions import HTTPException as StarletteHTTPException\nfrom sag_py_web_common.json_exception_handler import log_exception\n\napp.add_exception_handler(StarletteHTTPException, log_exception)\n```\n\nJson Exception handler uses logger \"http_error_logger\", which could be used for reporting concepts.\n\n## How to start developing\n\n### With vscode\n\nJust install vscode with dev containers extension. All required extensions and configurations are prepared automatically.\n\n### With pycharm\n\n* Install latest pycharm\n* Install pycharm plugin BlackConnect\n* Install pycharm plugin Mypy\n* Configure the python interpreter/venv\n* pip install requirements-dev.txt\n* pip install black[d]\n* Ctl+Alt+S => Check Tools => BlackConnect => Trigger when saving changed files\n* Ctl+Alt+S => Check Tools => BlackConnect => Trigger on code reformat\n* Ctl+Alt+S => Click Tools => BlackConnect => \"Load from pyproject.yaml\" (ensure line length is 120)\n* Ctl+Alt+S => Click Tools => BlackConnect => Configure path to the blackd.exe at the \"local instance\" config (e.g. C:\\Python310\\Scripts\\blackd.exe)\n* Ctl+Alt+S => Click Tools => Actions on save => Reformat code\n* Restart pycharm\n\n## How to publish\n* Update the version in setup.py and commit your change\n* Create a tag with the same version number\n* Let github do the rest\n\n## How to test\n\nTo avoid publishing to pypi unnecessarily you can do as follows\n\n* Tag your branch however you like\n* Use the chosen tag in the requirements.txt-file of the project you want to test this library in, eg. `sag_py_web_common==<your tag>`\n* Rebuild/redeploy your project\n\n[codeclimate-image]:https://api.codeclimate.com/v1/badges/533686a1f4d644151adb/maintainability\n[codeclimate-url]:https://codeclimate.com/github/SamhammerAG/sag_py_web_common/maintainability\n[coveralls-image]:https://coveralls.io/repos/github/SamhammerAG/sag_py_web_common/badge.svg?branch=master\n[coveralls-url]:https://coveralls.io/github/SamhammerAG/sag_py_web_common?branch=master\n[snyk-image]:https://snyk.io/test/github/SamhammerAG/sag_py_web_common/badge.svg\n[snyk-url]:https://snyk.io/test/github/SamhammerAG/sag_py_web_common\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Small helper functions for web projects",
"version": "1.0.0",
"project_urls": {
"Bug Reports": "https://github.com/SamhammerAG/sag_py_web_common/issues",
"Documentation": "https://github.com/SamhammerAG/sag_py_web_common",
"Homepage": "https://github.com/SamhammerAG/sag_py_web_common",
"Source": "https://github.com/SamhammerAG/sag_py_web_common"
},
"split_keywords": [
"fastapi",
" web",
" helper",
" common"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6660465b516b4f21e6945eeb312853a8f751111757195c21e028fc083791d2b8",
"md5": "7ec283acf23bf889a27911d53780dae8",
"sha256": "3163aecba2d6bdb1ccbdcfad0c87f75e4c17076a4f5b928de7665d4a6c1af264"
},
"downloads": -1,
"filename": "sag_py_web_common-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7ec283acf23bf889a27911d53780dae8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 6951,
"upload_time": "2024-09-18T14:55:46",
"upload_time_iso_8601": "2024-09-18T14:55:46.280161Z",
"url": "https://files.pythonhosted.org/packages/66/60/465b516b4f21e6945eeb312853a8f751111757195c21e028fc083791d2b8/sag_py_web_common-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "81996f73a87c64a885e48d622d6f57c7f89ce6b750f379357b9930acd7d9f41f",
"md5": "c14ed03380a511aa74c3fcb944925794",
"sha256": "b9a348e2426a0c7e614c2e4cd8c575afd6a6991ee2539b6957f4393747a88c57"
},
"downloads": -1,
"filename": "sag_py_web_common-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "c14ed03380a511aa74c3fcb944925794",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 6950,
"upload_time": "2024-09-18T14:55:47",
"upload_time_iso_8601": "2024-09-18T14:55:47.751390Z",
"url": "https://files.pythonhosted.org/packages/81/99/6f73a87c64a885e48d622d6f57c7f89ce6b750f379357b9930acd7d9f41f/sag_py_web_common-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-18 14:55:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SamhammerAG",
"github_project": "sag_py_web_common",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "sag-py-web-common"
}
JSON
