mirror of
https://github.com/arcan1s/ahriman.git
synced 2025-06-28 06:41:43 +00:00
feat: use split packages (#135)
* move argument parsers to handlers themselves
* use hatchling instead of flit
* Revert "use hatchling instead of flit"
This reverts commit d18d146d79
.
* add package-splitt script
* replace simplify walk method
* split packages
* explicitly install packages
* separate support triggers from main package
* add docs examples
* sort actions
* docs update
* add metapackage
* review fixes
This commit is contained in:
41
docs/advanced-usage/views.rst
Normal file
41
docs/advanced-usage/views.rst
Normal file
@ -0,0 +1,41 @@
|
||||
Writing own API endpoint
|
||||
========================
|
||||
|
||||
The web service loads views dynamically, thus it is possible to add custom API endpoint or even web page. The view must be derived from ``ahriman.web.views.base.BaseView`` and should implement desired HTTP methods. The API specification will be also loaded automatically if available, but optional. The implementation must be saved into the ``ahriman.web.views`` package
|
||||
|
||||
Let's consider example of API endpoint which always returns 204 with no response:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from aiohttp.web import Response, HTTPNoContent
|
||||
|
||||
from ahriman.web.views.base import BaseView
|
||||
|
||||
class PingView(BaseView):
|
||||
|
||||
async def get(self) -> Response:
|
||||
# do nothing, just raise 204 response
|
||||
# check public methods of the BaseView class for all available controls
|
||||
raise HTTPNoContent
|
||||
|
||||
The ``get()`` method can be decorated by ``aiohttp_apispec`` methods, but we will leave it for a self-study, please, consider to check examples of usages in the main package.
|
||||
|
||||
In order to view to be added to the route list correctly, few more properties are required to be set. First of all, it is required to specify ``ROUTES`` (list of strings), which contains list of all available routes, e.g.:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
...
|
||||
|
||||
ROUTES = ["/api/v1/ping"]
|
||||
|
||||
In addition, it is also recommended to specify permission level for using this endpoint. Since this endpoint neither does anything nor returns sensitive information, it can be set to ``UserAccess.Unauthorized``:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
...
|
||||
|
||||
GET_PERMISSION = UserAccess.Unauthorized
|
||||
|
||||
That's all. Just save the file as ``/usr/lib/python3.12/site-packages/ahriman/web/views/ping.py`` (replace ``python3.12`` with actual python version) and restart web server.
|
||||
|
||||
For more examples and details, please check builtin handlers and classes documentations.
|
Reference in New Issue
Block a user