From f40f4436f0321abdcfa54f44946e24e5b2bac1a8 Mon Sep 17 00:00:00 2001
From: AliRn <alirn76@yahoo.com>
Date: Thu, 31 Aug 2023 17:52:15 +0330
Subject: [PATCH] Update URLs example

---
 search/search_index.json |   2 +-
 sitemap.xml.gz           | Bin 348 -> 348 bytes
 urls/index.html          |  10 +++++-----
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/search/search_index.json b/search/search_index.json
index 8ddbf03..9270101 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Introduction","text":""},{"location":"#panther","title":"Panther","text":"<p>Is A Fast &amp;  Friendly Web Framework For Building Async APIs With Python 3.11+ </p> <p> </p> <p> Supported by JetBrains </p> <p> <p> </p> <p></p>"},{"location":"#why-use-panther","title":"Why Use Panther ?","text":"<ul> <li>Document-oriented Databases ODM (PantherDB, MongoDB)</li> <li>Visual API Monitoring (In Terminal)</li> <li>Cache APIs (In Memory, In Redis)</li> <li>Built-in Authentication Classes (Customizable)</li> <li>Built-in Permission Classes (Customizable)</li> <li>Handle Custom Middlewares</li> <li>Handle Custom Throttling </li> </ul>"},{"location":"#installation","title":"Installation","text":"<ul> <li> Create a Virtual Environment <pre>$ python3 -m venv .venv</pre> <ul> <li> Active The Environment<ul> <li>Linux &amp; Mac   <pre>$ source .venv/bin/activate</pre></li> <li>Windows   <pre>$ .\\.venv\\Scripts\\activate</pre></li> </ul> <ul> <li> Install Panther<ul> <li>Normal   <pre>$ pip install panther</pre></li> <li>Include MongoDB Requirements   <pre>$ pip install panther[full]</pre> </li> </ul>"},{"location":"#usage","title":"Usage","text":""},{"location":"#create-project","title":"Create Project","text":"<pre><code>$ panther create &lt;project_name&gt; &lt;directory&gt;\n</code></pre>"},{"location":"#run-project","title":"Run Project","text":"<p>Panther uses Uvicorn as ASGI (Asynchronous Server Gateway Interface)</p> <pre><code>$ panther run </code></pre>"},{"location":"#monitoring-requests","title":"Monitoring Requests","text":"<pre><code>$ panther monitor </code></pre>"},{"location":"#python-shell","title":"Python Shell","text":"<p>Panther Uses bpython for shell</p> <pre><code>$ panther shell </code></pre>"},{"location":"#example","title":"Example","text":"<ul> <li> <p>Then run the project:</p> </li> <li> <p><code>$ cd myproject</code></p> </li> <li><code>$ panther run</code> or <code>$ panther run --reload</code> </li> </ul> <p>now you can see these two urls:</p> <ul> <li> <p>http://127.0.0.1:8000/</p> </li> <li> <p>http://127.0.0.1:8000/info/</p> </li> </ul> <p>Writing Your First CRUD: First CRUD</p>"},{"location":"#you-can-create-project-with","title":"You can create project with","text":"<pre><code>$ panther create myproject\n</code></pre>"},{"location":"#or-create-it-yourself","title":"or create it yourself:","text":"<p>core/configs.py:</p> <pre><code>URLs = 'core.urls.url_routing'\n</code></pre> <p>core/urls.py:</p> <pre><code>from app.urls import urls as app_urls\n\nurl_routing = {\n    '/': app_urls,\n}\n</code></pre> <p>app/urls.py:</p> <pre><code>from app.apis import hello_world, info\n\nurls = {\n    '': hello_world,\n    'info/': info,\n}\n</code></pre> <p>app/apis.py:</p> <pre><code>from datetime import datetime, timedelta\n\nfrom panther.app import API\nfrom panther.configs import config\nfrom panther import version, status\nfrom panther.request import Request\nfrom panther.response import Response\nfrom panther.throttling import Throttling\n\n\nInfoThrottling = Throttling(rate=5, duration=timedelta(minutes=1))\n\n@API()\nasync def hello_world():\n    return {'detail': 'Hello World'}\n\n\n@API(cache=True, throttling=InfoThrottling)\nasync def info(request: Request):\n    data = {\n        'version': version(),\n        'datetime_now': datetime.now().isoformat(),\n        'user_agent': request.headers.user_agent,\n        'db_engine': config['db_engine'],\n    }\n    return Response(data=data, status_code=status.HTTP_202_ACCEPTED)\n</code></pre>"},{"location":"authentications/","title":"Authentications","text":"<p>Variable: <code>AUTHENTICATION</code> </p> <p>Type: <code>str</code></p> <p>Default: <code>None</code></p> <p>You can set your Authentication class in <code>core/configs.py</code>, then Panther will use this class for authentication in every <code>API</code>, if you set <code>auth=True</code> in <code>@API()</code>, and put the <code>user</code> in <code>request.user</code> or <code>raise HTTP_401_UNAUTHORIZED</code> </p> <p>We already have one built-in authentication class which is used <code>JWT</code> for authentication.</p> <p>You can write your own authentication class too (we are going to discuss it)</p>"},{"location":"authentications/#jwtauthentication","title":"JWTAuthentication","text":"<p>This class will </p> <ul> <li>Get the <code>token</code> from <code>Authorization</code> header of request with keyword of <code>Bearer</code></li> <li><code>decode</code> it </li> <li>Find the match <code>user</code> in <code>USER_MODEL</code> you have already set</li> </ul> <p><code>JWTAuthentication</code> is going to use <code>panther.db.models.BaseUser</code> if you didn't set the <code>USER_MODEL</code> in your <code>core/configs.py</code></p> <p>You can customize these 3 variables for <code>JWTAuthentication</code> in your <code>core/configs.py</code> as <code>JWTConfig</code> like below (<code>JWTConfig</code> is optional):</p> <pre><code>...\nfrom datetime import timedelta\nfrom panther.utils import load_env  \nfrom pathlib import Path\n\nBASE_DIR = Path(__name__).resolve().parent  \nenv = load_env(BASE_DIR / '.env')\n\nSECRET_KEY = env['SECRET_KEY']\n\nJWTConfig = {  \n    'key': SECRET_KEY,  \n    'algorithm': 'HS256',  \n    'life_time': timedelta(days=2),  \n}\n</code></pre> <p>key \u2003\u2003\u2003\u2003--&gt; default is <code>SECRET_KEY</code></p> <p>algorithm \u2003 --&gt; default is <code>HS256</code></p> <p>life_time\u2003\u2003--&gt; default is <code>timedelta(days=1)</code> </p>"},{"location":"authentications/#custom-authentication","title":"Custom Authentication","text":"<ul> <li> <p>Create a class and inherits it from <code>panther.authentications.BaseAuthentication</code></p> </li> <li> <p>Implement <code>authentication(cls, request: Request)</code> method</p> <ul> <li>Process the <code>request.headers.authorization</code> or ...</li> <li>Return Instance of <code>USER_MODEL</code></li> <li>Or raise <code>panther.exceptions.AuthenticationException</code> </li> </ul> </li> <li> <p>Address it in <code>core/configs.py</code></p> </li> <li><code>AUTHENTICATION = 'project_name.core.authentications.CustomAuthentication'</code></li> </ul> <p>You can look at the source code of JWTAuthentication for </p>"},{"location":"benchmarks/","title":"Benchmarks","text":""},{"location":"benchmarks/#benchmark","title":"Benchmark","text":"Framework Throughput Request Handled Max Latencies Sanic 23,326 233,842 268.8ms Panther 14,719 147,595 113.1ms FastAPI 14,573 146,467 155.1ms Tornado 4,969 50.585 426.5ms Flask 3,555 36,396 1.2s Django 2,188 22,814 526.3ms Bottle 1,226 39,650 30.0s Pyramid 1,023 30,912 30.0s Cherrypy 639 24,944 30.0s"},{"location":"benchmarks/#all-tests-happen-in","title":"All tests happen in","text":"<ul> <li>CPU: AMD Ryzen 9 5900HX with Radeon Graphics (16) @ 3.300GHz</li> <li>OS: Arch Linux x86_64</li> <li>KERNEL: 6.2.2-arch1-1</li> </ul>"},{"location":"benchmarks/#results","title":"Results","text":""},{"location":"benchmarks/#sanic","title":"Sanic","text":"<p>[Test Source Code]</p> <p></p>"},{"location":"benchmarks/#panther","title":"Panther","text":"<p>[Test Source Code]</p> <p></p>"},{"location":"benchmarks/#fastapi","title":"FastAPI","text":"<p>[Test Source Code]</p> <p></p>"},{"location":"benchmarks/#tornado","title":"Tornado","text":"<p>[Test Source Code]</p> <p></p>"},{"location":"benchmarks/#flask","title":"Flask","text":"<p>[Test Source Code]</p> <p></p>"},{"location":"benchmarks/#django","title":"Django","text":"<p>[Test Source Code]</p> <p></p>"},{"location":"benchmarks/#bottle","title":"Bottle","text":"<p>[Test Source Code]</p> <p></p>"},{"location":"benchmarks/#pyramid","title":"Pyramid","text":"<p>[Test Source Code]</p> <p></p>"},{"location":"benchmarks/#cherrypy","title":"Cherrypy","text":"<p>[Test Source Code]</p> <p></p>"},{"location":"class_first_crud/","title":"Class Base","text":"<p>We assume you could run the project with Introduction</p> <p>Now let's write custom API <code>Create</code>, <code>Retrieve</code>, <code>Update</code> and <code>Delete</code> for a <code>Book</code>:</p>"},{"location":"class_first_crud/#structure-requirements","title":"Structure &amp; Requirements","text":""},{"location":"class_first_crud/#create-model","title":"Create Model","text":"<p>Create a model named <code>Book</code> in <code>app/models.py</code>:</p> <pre><code>from panther.db import Model\n\n\nclass Book(Model):\n    name: str\n    author: str\n    pages_count: int\n</code></pre>"},{"location":"class_first_crud/#create-api-class","title":"Create API Class","text":"<p>Create the <code>BookAPI()</code> in <code>app/apis.py</code>:</p> <pre><code>from panther.app import GenericAPI\n\n\nclass BookAPI(GenericAPI):\n    ... \n</code></pre> <p>We are going to complete it later ...</p>"},{"location":"class_first_crud/#update-urls","title":"Update URLs","text":"<p>Add the <code>BookAPI</code> in <code>app/urls.py</code>:</p> <pre><code>from app.apis import BookAPI\n\n\nurls = {\n    'book/': BookAPI,\n}\n</code></pre> <p>We assume that the <code>urls</code> in <code>core/urls.py</code> pointing to <code>app/urls.py</code>, like below:</p> <pre><code>from app.urls import urls as app_urls\n\n\nurls = {\n    '/': app_urls,\n}\n</code></pre>"},{"location":"class_first_crud/#add-database-middleware","title":"Add Database Middleware","text":"<p>Add one database middleware in <code>core/configs.py</code> <code>MIDDLEWARES</code>, we are going to add <code>pantherdb</code></p> <p>PantherDB is a Simple, FileBase and Document Oriented database:</p> <pre><code>...\n\nMIDDLEWARES = [\n    ('panther.middlewares.db.Middleware', {'url': f'pantherdb://{BASE_DIR}/{DB_NAME}.pdb'}),\n]\n</code></pre>"},{"location":"class_first_crud/#apis","title":"APIs","text":""},{"location":"class_first_crud/#api-create-a-book","title":"API - Create a Book","text":"<p>Now we are going to create a book on <code>post</code> request, We need to:</p> <ol> <li> <p>Declare <code>post</code> method in <code>BookAPI</code>:     <pre><code>from panther.app import GenericAPI\n\n\nclass BookAPI(GenericAPI):\n\n    def post(self):\n        ...\n</code></pre></p> </li> <li> <p>Declare <code>request: Request</code> in <code>BookAPI.post()</code> function:     <pre><code>from panther.app import GenericAPI\nfrom panther.request import Request\n\n\nclass BookAPI(GenericAPI):\n\n    def post(self, request: Request):\n        ...\n</code></pre></p> </li> <li> <p>Create serializer in <code>app/serializers.py</code>, we used <code>pydantic</code> for the <code>validation</code> of <code>request.data</code> :     <pre><code>from pydantic import BaseModel\n\n\nclass BookSerializer(BaseModel):\n    name: str\n    author: str\n    pages_count: int\n</code></pre></p> </li> <li> <p>Pass the created serializer to our <code>BookAPI</code> as <code>input_model</code> so the incoming data will be validated and cleaned automatically:</p> <p><pre><code>from panther.app import GenericAPI\nfrom panther.request import Request\n\nfrom app.serializers import BookSerializer\n\n\nclass BookAPI(GenericAPI):\n    input_model = BookSerializer\n\n    def post(self, request: Request):\n        ...\n</code></pre>    Now we have access to <code>request.data</code>, We are going to use it like the below for ease of use, so the auto-suggest helps us in development:</p> <pre><code>from panther.app import GenericAPI\nfrom panther.request import Request\n\nfrom app.serializers import BookSerializer\n\n\nclass BookAPI(GenericAPI):\n    input_model = BookSerializer\n\n    def post(self, request: Request):\n        body: BookSerializer = request.data\n        ...\n</code></pre> </li> <li> <p>Now we have access to the validated data, and we can create our first book:</p> <pre><code>from panther.app import GenericAPI\nfrom panther.request import Request\n\nfrom app.serializers import BookSerializer\nfrom app.models import Book\n\n\nclass BookAPI(GenericAPI):\n    input_model = BookSerializer\n\n    def post(self, request: Request):\n        body: BookSerializer = request.data\n        Book.insert_one(\n            name=body.name,\n            author=body.author,\n            pages_count=body.pages_count,\n        )\n        ...\n</code></pre> </li> <li> <p>And finally we return <code>201 Created</code> status_code as response of <code>post</code>:     <pre><code>from panther import status\nfrom panther.app import GenericAPI\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.serializers import BookSerializer\nfrom app.models import Book\n\n\nclass BookAPI(GenericAPI):\n    input_model = BookSerializer\n\n    def post(self, request: Request):\n        body: BookSerializer = request.data\n        book = Book.insert_one(\n            name=body.name,\n            author=body.author,\n            pages_count=body.pages_count,\n        )\n        return Response(data=book, status_code=status.HTTP_201_CREATED)\n</code></pre></p> </li> </ol> <p>The response.data can be <code>Instance of Models</code>, <code>dict</code>, <code>str</code>, <code>tuple</code>, <code>list</code>, <code>str</code> or <code>None</code></p> <p>Panther will return <code>None</code> if you don't return anything as response.</p>"},{"location":"class_first_crud/#api-list-of-books","title":"API - List of Books","text":"<p>We just need to add another method for <code>GET</code> method and return the lists of books:</p> <pre><code>from panther import status\nfrom panther.app import GenericAPI\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.serializers import BookSerializer\nfrom app.models import Book\n\n\nclass BookAPI(GenericAPI):\n    input_model = BookSerializer\n\n    def post(self, request: Request):\n        ...\n\n    def get(self):\n        books: list[Book] = Book.find()\n        return Response(data=books, status_code=status.HTTP_200_OK)\n</code></pre> <p>Panther validate input with <code>input_model</code>, only in <code>POST</code>, <code>PUT</code>, <code>PATCH</code> methods.</p>"},{"location":"class_first_crud/#filter-response-fields","title":"Filter Response Fields","text":"<p>Assume we don't want to return field <code>author</code> in response:</p> <ol> <li> <p>Create new serializer in <code>app/serializers.py</code>:</p> <pre><code>from pydantic import BaseModel\n\n\nclass BookOutputSerializer(BaseModel):\n    name: str\n    pages_count: int\n</code></pre> </li> <li> <p>Add the <code>BookOutputSerializer</code> as <code>output_model</code> to your <code>class</code></p> <pre><code>from panther import status\nfrom panther.app import GenericAPI\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.serializers import BookSerializer, BookOutputSerializer\nfrom app.models import Book\n\n\nclass BookAPI(GenericAPI):\n    input_model = BookSerializer\n    output_model = BookOutputSerializer\n\n    def post(self, request: Request):\n        ...\n\n    def get(self):\n        books: list[Book] = Book.find()\n        return Response(data=books, status_code=status.HTTP_200_OK)\n</code></pre> </li> </ol> <p>Panther use the <code>output_model</code>, in all methods.</p>"},{"location":"class_first_crud/#cache-the-response","title":"Cache The Response","text":"<p>For caching the response, we should add <code>cache=True</code> in <code>API()</code>. And it will return the cached response every time till <code>cache_exp_time</code></p> <p>For setting a custom expiration time for API we need to add <code>cache_exp_time</code> to <code>API()</code>:</p> <pre><code>from datetime import timedelta\n\nfrom panther import status\nfrom panther.app import GenericAPI\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.serializers import BookSerializer, BookOutputSerializer\nfrom app.models import Book\n\n\nclass BookAPI(GenericAPI):\n    input_model = BookSerializer\n    output_model = BookOutputSerializer\n    cache = True\n    cache_exp_time = timedelta(seconds=10)\n\n    def post(self, request: Request):\n        ...\n\n    def get(self):\n        books: list[Book] = Book.find()\n        return Response(data=books, status_code=status.HTTP_200_OK)\n</code></pre> <p>Panther is going to use the <code>DEFAULT_CACHE_EXP</code> from <code>core/configs.py</code> if <code>cache_exp_time</code> has not been set.</p>"},{"location":"class_first_crud/#throttle-the-request","title":"Throttle The Request","text":"<p>For setting rate limit for requests, we can add throttling to <code>BookAPI</code>, it should be the instance of <code>panther.throttling.Throttling</code>, something like below (in the below example user can't request more than 10 times in a minutes):</p> <pre><code>from datetime import timedelta\n\nfrom panther import status\nfrom panther.app import GenericAPI\nfrom panther.request import Request\nfrom panther.response import Response\nfrom panther.throttling import Throttling\n\nfrom app.serializers import BookSerializer, BookOutputSerializer\nfrom app.models import Book\n\n\nclass BookAPI(GenericAPI):\n    input_model = BookSerializer\n    output_model = BookOutputSerializer\n    cache = True\n    cache_exp_time = timedelta(seconds=10)\n    throttling = Throttling(rate=10, duration=timedelta(minutes=1))\n\n    def post(self, request: Request):\n        ...\n\n    def get(self):\n        books: list[Book] = Book.find()\n        return Response(data=books, status_code=status.HTTP_200_OK)\n</code></pre>"},{"location":"class_first_crud/#api-retrieve-a-book","title":"API - Retrieve a Book","text":"<p>For <code>retrieve</code>, <code>update</code> and <code>delete</code> API, we are going to</p> <ol> <li> <p>Create another class named <code>SingleBookAPI</code> in <code>app/apis.py</code>:</p> <pre><code>from panther.app import GenericAPI\n\n\nclass SingleBookAPI(GenericAPI):\n    ...\n</code></pre> </li> <li> <p>Add it in <code>app/urls.py</code>:</p> <pre><code>from app.apis import BookAPI, SingleBookAPI\n\n\nurls = {\n    'book/': BookAPI,\n    'book/&lt;book_id&gt;/': SingleBookAPI,\n}\n</code></pre> </li> </ol> <p>You should write the Path Variable in <code>&lt;</code> and <code>&gt;</code></p> <p>You should have the parameter with the same name of <code>path variable</code> in you <code>api</code> with normal <code>type hints</code></p> <p>Panther will convert type of the <code>path variable</code> to your parameter type, then pass it</p> <ol> <li> <p>Complete the api:</p> <pre><code>from panther import status\nfrom panther.app import GenericAPI\nfrom panther.response import Response\n\nfrom app.models import Book\n\n\nclass SingleBookAPI(GenericAPI):\n\n    def get(self, book_id: int):\n        if book := Book.find_one(id=book_id):\n            return Response(data=book, status_code=status.HTTP_200_OK)\n        else:\n            return Response(status_code=status.HTTP_404_NOT_FOUND)\n</code></pre> </li> </ol>"},{"location":"class_first_crud/#api-update-a-book","title":"API - Update a Book","text":"<ul> <li> <p>We can update in several ways:</p> <ol> <li> <p>Update a document</p> <pre><code>from panther import status\nfrom panther.app import GenericAPI\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.models import Book\nfrom app.serializers import BookSerializer\n\n\nclass SingleBookAPI(GenericAPI):\n    input_model = BookSerializer\n\n    def get(self, book_id: int):\n        ...\n\n    def put(self, request: Request, book_id: int):\n        body: BookSerializer = request.data\n\n        book: Book = Book.find_one(id=book_id)\n        book.update(\n            name=body.name, \n            author=body.author, \n            pages_count=body.pages_count\n        )\n        return Response(status_code=status.HTTP_202_ACCEPTED)\n</code></pre> </li> <li> <p>Update with <code>update_one</code> query</p> <pre><code>from panther import status\nfrom panther.app import GenericAPI\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.models import Book\nfrom app.serializers import BookSerializer\n\n\nclass SingleBookAPI(GenericAPI):\n    input_model = BookSerializer\n\n    def get(self, book_id: int):\n        ...\n\n    def put(self, request: Request, book_id: int):\n        is_updated: bool = Book.update_one({'id': book_id}, request.data.dict())\n        data = {'is_updated': is_updated}\n        return Response(data=data, status_code=status.HTTP_202_ACCEPTED)\n</code></pre> </li> <li> <p>Update with <code>update_many</code> query</p> <pre><code>from panther import status\nfrom panther.app import GenericAPI\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.models import Book\nfrom app.serializers import BookSerializer\n\n\nclass SingleBookAPI(GenericAPI):\n    input_model = BookSerializer\n\n    def get(self, book_id: int):\n        ...\n\n    def put(self, request: Request, book_id: int):\n        updated_count: int = Book.update_many({'id': book_id}, request.data.dict())\n        data = {'updated_count': updated_count}\n        return Response(data=data, status_code=status.HTTP_202_ACCEPTED)\n</code></pre> </li> </ol> <p>You can handle the PATCH the same way as PUT</p> </li> </ul>"},{"location":"class_first_crud/#api-delete-a-book","title":"API - Delete a Book","text":"<ul> <li> <p>We can delete in several ways too:</p> <ol> <li> <p>Delete a document</p> <p><pre><code>    from panther import status\n    from panther.app import GenericAPI\n    from panther.request import Request\n    from panther.response import Response\n\n    from app.models import Book\n\n    class SingleBookAPI(GenericAPI):\n        input_model = BookSerializer\n\n        def get(self, book_id: int):\n            ...\n\n        def put(self, request: Request, book_id: int):\n            ...\n\n        def delete(self, book_id: int):\n            is_deleted: bool = Book.delete_one(id=book_id)\n            if is_deleted:\n                return Response(status_code=status.HTTP_204_NO_CONTENT)\n            else:\n                return Response(status_code=status.HTTP_400_BAD_REQUEST)\n</code></pre>     2. Delete with <code>delete_one</code> query</p> <pre><code>    from panther import status\n    from panther.app import GenericAPI\n    from panther.request import Request\n    from panther.response import Response\n\n    from app.models import Book\n\n\n    class SingleBookAPI(GenericAPI):\n        input_model = BookSerializer\n\n        def get(self, book_id: int):\n            ...\n\n        def put(self, request: Request, book_id: int):\n            ...\n\n        def delete(self, book_id: int):\n            is_deleted: bool = Book.delete_one(id=book_id)\n            return Response(status_code=status.HTTP_204_NO_CONTENT)\n</code></pre> </li> <li> <p>Delete with <code>delete_many</code> query</p> <pre><code>    from panther import status\n    from panther.app import GenericAPI\n    from panther.request import Request\n    from panther.response import Response\n\n    from app.models import Book\n\n\n    class SingleBookAPI(GenericAPI):\n        input_model = BookSerializer\n\n        def get(self, book_id: int):\n            ...\n\n        def put(self, request: Request, book_id: int):\n            ...\n\n        def delete(self, book_id: int):\n            deleted_count: int = Book.delete_many(id=book_id)\n            return Response(status_code=status.HTTP_204_NO_CONTENT)\n</code></pre> </li> </ol> </li> </ul>"},{"location":"configs/","title":"Configs","text":"<p>Panther  stores all the configs in the <code>core/configs.py</code></p>"},{"location":"configs/#monitoring","title":"MONITORING","text":"<p>Type: <code>bool</code> (Default: <code>False</code>)</p> <p>It should be <code>True</code> if you want to use <code>panther monitor</code> command and see the monitoring logs</p> <p>If <code>True</code> it will:</p> <ul> <li>Log every request in <code>logs/monitoring.log</code></li> </ul>"},{"location":"configs/#log_queries","title":"LOG_QUERIES","text":"<p>Type: <code>bool</code> (Default: <code>False</code>)</p> <p>If <code>True</code> it will:</p> <ul> <li>Calculate every query perf time &amp; Log them in <code>logs/query.log</code></li> </ul>"},{"location":"configs/#middlewares","title":"MIDDLEWARES","text":"<p>Type: <code>list</code> (Default: <code>[ ]</code>)</p> <p>List of middlewares you want to use</p>"},{"location":"configs/#authentication","title":"AUTHENTICATION","text":"<p>Type: <code>str | None</code> (Default: <code>None</code>)</p> <p>Every request goes through <code>authentication()</code> method of this <code>class</code></p> <p>Example: <code>AUTHENTICATION = 'panther.authentications.JWTAuthentication'</code></p>"},{"location":"configs/#urls","title":"URLs","text":"<p>Type: <code>str</code> (Required)</p> <p>It should be the address of your <code>urls</code> <code>dict</code></p> <p>Example: <code>URLS = 'configs.urls.url_routing'</code></p>"},{"location":"configs/#default_cache_exp","title":"DEFAULT_CACHE_EXP","text":"<p>Type: <code>timedelta| None</code> (Default: <code>None</code>)</p> <p>We use it as default <code>cache_exp_time</code> you can overwrite it in your <code>@API</code> too</p> <p>It is used when you set <code>cache=True</code> in <code>@API</code> decorator</p> <p>Example: <code>DEFAULT_CACHE_EXP = timedelta(seconds=10)</code></p>"},{"location":"configs/#throttling","title":"THROTTLING","text":"<p>Type: <code>Throttling | None</code> (Default: <code>None</code>)</p> <p>We use it as default <code>throttling</code> you can overwrite it in your <code>@API</code> too</p> <p>Example: <code>THROTTLING = Throttling(rate=10, duration=timedelta(seconds=10))</code></p>"},{"location":"configs/#user_model","title":"USER_MODEL","text":"<p>Type: <code>str | None</code> (Default: <code>'panther.db.models.BaseUser'</code>)</p> <p>It is used for authentication</p> <p>Example: <code>USER_MODEL = 'panther.db.models.User'</code></p>"},{"location":"configs/#jwtconfig","title":"JWTConfig","text":"<p>Type: <code>dict | None</code> (Default: <code>JWTConfig = {'key': SECRET_KEY}</code>)</p> <p>We use it when you set <code>panther.authentications.JWTAuthentication</code> as <code>AUTHENTICATION</code></p>"},{"location":"function_first_crud/","title":"Function Base","text":"<p>We assume you could run the project with Introduction</p> <p>Now let's write custom API <code>Create</code>, <code>Retrieve</code>, <code>Update</code> and <code>Delete</code> for a <code>Book</code>:</p>"},{"location":"function_first_crud/#structure-requirements","title":"Structure &amp; Requirements","text":""},{"location":"function_first_crud/#create-model","title":"Create Model","text":"<p>Create a model named <code>Book</code> in <code>app/models.py</code>:</p> <pre><code>from panther.db import Model\n\n\nclass Book(Model):\n    name: str\n    author: str\n    pages_count: int\n</code></pre>"},{"location":"function_first_crud/#create-api-function","title":"Create API Function","text":"<p>Create the <code>book_api()</code> in <code>app/apis.py</code>:</p> <pre><code>from panther.app import API\n\n\n@API()\nasync def book_api():\n    ... \n</code></pre> <p>We are going to complete it later ...</p>"},{"location":"function_first_crud/#update-urls","title":"Update URLs","text":"<p>Add the <code>book_api</code> in <code>app/urls.py</code>:</p> <pre><code>from app.apis import book_api\n\n\nurls = {\n    'book/': book_api,\n}\n</code></pre> <p>We assume that the <code>urls</code> in <code>core/urls.py</code> pointing to <code>app/urls.py</code>, like below:</p> <pre><code>from app.urls import urls as app_urls\n\n\nurls = {\n    '/': app_urls,\n}\n</code></pre>"},{"location":"function_first_crud/#add-database-middleware","title":"Add Database Middleware","text":"<p>Add one database middleware in <code>core/configs.py</code> <code>MIDDLEWARES</code>, we are going to add <code>pantherdb</code></p> <p>PantherDB is a Simple, FileBase and Document Oriented database:</p> <pre><code>...\n\nMIDDLEWARES = [\n    ('panther.middlewares.db.Middleware', {'url': f'pantherdb://{BASE_DIR}/{DB_NAME}.pdb'}),\n]\n</code></pre>"},{"location":"function_first_crud/#apis","title":"APIs","text":""},{"location":"function_first_crud/#api-create-a-book","title":"API - Create a Book","text":"<p>Now we are going to create a book on <code>post</code> request, We need to:</p> <ol> <li> <p>Declare <code>request: Request</code> in <code>book_api</code> function:     <pre><code>from panther.app import API\nfrom panther.request import Request\n\n\n@API()\nasync def book_api(request: Request):\n    ...\n</code></pre></p> </li> <li> <p>Create serializer in <code>app/serializers.py</code>, we used <code>pydantic</code> for the <code>validation</code> of <code>request.data</code> :     <pre><code>from pydantic import BaseModel\n\n\nclass BookSerializer(BaseModel):\n    name: str\n    author: str\n    pages_count: int\n</code></pre></p> </li> <li> <p>Pass the created serializer to our <code>book_api</code> as <code>input_model</code> so the incoming data will be validated and cleaned automatically:</p> <p><pre><code>from panther.app import API\nfrom panther.request import Request\n\nfrom app.serializers import BookSerializer\n\n\n@API(input_model=BookSerializer)\nasync def book_api(request: Request):\n    ...\n</code></pre>    Now we have access to <code>request.data</code>, We are going to use it like the below for ease of use, so the auto-suggest helps us in development:</p> <pre><code>from panther.app import API\nfrom panther.request import Request\n\nfrom app.serializers import BookSerializer\n\n\n@API(input_model=BookSerializer)\nasync def book_api(request: Request):\n    body: BookSerializer = request.data\n    ...\n</code></pre> </li> <li> <p>Now we have access to the validated data, and we can create our first book:</p> <pre><code>from panther.app import API\nfrom panther.request import Request\n\nfrom app.serializers import BookSerializer\nfrom app.models import Book\n\n\n@API(input_model=BookSerializer)\nasync def book_api(request: Request):\n    body: BookSerializer = request.data\n\n    Book.insert_one(\n        name=body.name,\n        author=body.author,\n        pages_count=body.pages_count,\n    )\n    ...\n</code></pre> </li> <li> <p>But we only want this happens in <code>post</code> requests, so we add this <code>condition</code>:</p> <pre><code>from panther.app import API\nfrom panther.request import Request\n\nfrom app.serializers import BookSerializer\nfrom app.models import Book\n\n\n@API(input_model=BookSerializer)\nasync def book_api(request: Request):\n    if request.method == 'POST':\n        body: BookSerializer = request.data\n\n        Book.create(\n            name=body.name,\n            author=body.author,\n            pages_count=body.pages_count,\n        )\n        ...\n</code></pre> </li> <li> <p>And finally we return <code>201 Created</code> status_code as response of <code>post</code> and <code>501 Not Implemented</code> for other methods:     <pre><code>from panther import status\nfrom panther.app import API\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.serializers import BookSerializer\nfrom app.models import Book\n\n\n@API(input_model=BookSerializer)\nasync def book_api(request: Request):\n    if request.method == 'POST':\n        body: BookSerializer = request.data\n\n        book: Book = Book.create(\n            name=body.name,\n            author=body.author,\n            pages_count=body.pages_count,\n        )\n        return Response(data=book, status_code=status.HTTP_201_CREATED)\n\n    return Response(status_code=status.HTTP_501_NOT_IMPLEMENTED)\n</code></pre></p> </li> </ol> <p>The response.data can be <code>Instance of Models</code>, <code>dict</code>, <code>str</code>, <code>tuple</code>, <code>list</code>, <code>str</code> or <code>None</code></p> <p>Panther will return <code>None</code> if you don't return anything as response.</p>"},{"location":"function_first_crud/#api-list-of-books","title":"API - List of Books","text":"<p>We just need to add another condition on <code>GET</code> methods and return the lists of books:</p> <pre><code>from panther import status\nfrom panther.app import API\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.serializers import BookSerializer\nfrom app.models import Book\n\n\n@API(input_model=BookSerializer)\nasync def book_api(request: Request):\n    if request.method == 'POST':\n        ...\n\n    elif request.method == 'GET':\n        books: list[Book] = Book.find()\n        return Response(data=books, status_code=status.HTTP_200_OK)\n\n    return Response(status_code=status.HTTP_501_NOT_IMPLEMENTED)\n</code></pre> <p>Panther validate input with <code>input_model</code>, only in <code>POST</code>, <code>PUT</code>, <code>PATCH</code> methods.</p>"},{"location":"function_first_crud/#filter-response-fields","title":"Filter Response Fields","text":"<p>Assume we don't want to return field <code>author</code> in response:</p> <ol> <li> <p>Create new serializer in <code>app/serializers.py</code>:</p> <pre><code>from pydantic import BaseModel\n\n\nclass BookOutputSerializer(BaseModel):\n    name: str\n    pages_count: int\n</code></pre> </li> <li> <p>Add the <code>BookOutputSerializer</code> as <code>output_model</code> to your <code>API()</code> <pre><code>from panther import status\nfrom panther.app import API\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.serializers import BookSerializer, BookOutputSerializer\nfrom app.models import Book\n\n\n@API(input_model=BookSerializer, output_model=BookOutputSerializer)\nasync def book_api(request: Request):\n    if request.method == 'POST':\n        ...\n\n    elif request.method == 'GET':\n        books: list[Book] = Book.find()\n        return Response(data=books, status_code=status.HTTP_200_OK)\n\n    return Response(status_code=status.HTTP_501_NOT_IMPLEMENTED)\n</code></pre></p> </li> </ol> <p>Panther use the <code>output_model</code>, in all methods.</p>"},{"location":"function_first_crud/#cache-the-response","title":"Cache The Response","text":"<p>For caching the response, we should add <code>cache=True</code> in <code>API()</code>. And it will return the cached response every time till <code>cache_exp_time</code></p> <p>For setting a custom expiration time for API we need to add <code>cache_exp_time</code> to <code>API()</code>:</p> <pre><code>from datetime import timedelta\n\nfrom panther import status\nfrom panther.app import API\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.serializers import BookSerializer, BookOutputSerializer\nfrom app.models import Book\n\n\n@API(input_model=BookSerializer, output_model=BookOutputSerializer, cache=True, cache_exp_time=timedelta(seconds=10))\nasync def book_api(request: Request):\n    if request.method == 'POST':\n        ...\n\n    elif request.method == 'GET':\n        books: list[Book] = Book.find()\n        return Response(data=books, status_code=status.HTTP_200_OK)\n\n    return Response(status_code=status.HTTP_501_NOT_IMPLEMENTED)\n</code></pre> <p>Panther is going to use the <code>DEFAULT_CACHE_EXP</code> from <code>core/configs.py</code> if <code>cache_exp_time</code> has not been set.</p>"},{"location":"function_first_crud/#throttle-the-request","title":"Throttle The Request","text":"<p>For setting rate limit for requests, we can add throttling to <code>API()</code>, it should be the instance of <code>panther.throttling.Throttling</code>, something like below (in the below example user can't request more than 10 times in a minutes):</p> <pre><code>from datetime import timedelta\n\nfrom panther import status\nfrom panther.app import API\nfrom panther.request import Request\nfrom panther.response import Response\nfrom panther.throttling import Throttling\n\nfrom app.serializers import BookSerializer, BookOutputSerializer\nfrom app.models import Book\n\n\n@API(\n    input_model=BookSerializer, \n    output_model=BookOutputSerializer, \n    cache=True, \n    cache_exp_time=timedelta(seconds=10),\n    throttling=Throttling(rate=10, duration=timedelta(minutes=1))\n)\nasync def book_api(request: Request):\n    if request.method == 'POST':\n        ...\n\n    elif request.method == 'GET':\n        books: list[Book] = Book.find()\n        return Response(data=books, status_code=status.HTTP_200_OK)\n\n    return Response(status_code=status.HTTP_501_NOT_IMPLEMENTED)\n</code></pre>"},{"location":"function_first_crud/#api-retrieve-a-book","title":"API - Retrieve a Book","text":"<p>For <code>retrieve</code>, <code>update</code> and <code>delete</code> API, we are going to</p> <ol> <li> <p>Create another api named <code>single_book_api</code> in <code>app/apis.py</code>:</p> <pre><code>from panther.app import API\nfrom panther.request import Request\n\n\n@API()\nasync def single_book_api(request: Request):\n    ...\n</code></pre> </li> <li> <p>Add it in <code>app/urls.py</code>:</p> <pre><code>from app.apis import book_api, single_book_api\n\n\nurls = {\n    'book/': book_api,\n    'book/&lt;book_id&gt;/': single_book_api,\n}\n</code></pre> </li> </ol> <p>You should write the Path Variable in <code>&lt;</code> and <code>&gt;</code></p> <p>You should have the parameter with the same name of <code>path variable</code> in you <code>api</code> with normal <code>type hints</code></p> <p>Panther will convert type of the <code>path variable</code> to your parameter type, then pass it</p> <ol> <li> <p>Complete the api:</p> <pre><code>from panther import status\nfrom panther.app import API\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.models import Book\n\n\n@API()\nasync def single_book_api(request: Request, book_id: int):\n    if request.method == 'GET':\n        if book := Book.find_one(id=book_id):\n            return Response(data=book, status_code=status.HTTP_200_OK)\n        else:\n            return Response(status_code=status.HTTP_404_NOT_FOUND)\n</code></pre> </li> </ol>"},{"location":"function_first_crud/#api-update-a-book","title":"API - Update a Book","text":"<ul> <li> <p>We can update in several ways:</p> <ol> <li> <p>Update a document</p> <pre><code>from panther import status\nfrom panther.app import API\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.models import Book\nfrom app.serializers import BookSerializer\n\n\n@API(input_model=BookSerializer)\nasync def single_book_api(request: Request, book_id: int):\n    body: BookSerializer = request.data\n    if request.method == 'GET':\n        ...\n    elif request.method == 'PUT':\n        book: Book = Book.find_one(id=book_id)\n        book.update(\n            name=body.name, \n            author=body.author, \n            pages_count=body.pages_count\n            )\n        return Response(status_code=status.HTTP_202_ACCEPTED)\n</code></pre> </li> <li> <p>Update with <code>update_one</code> query</p> <pre><code>from panther import status\nfrom panther.app import API\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.models import Book\nfrom app.serializers import BookSerializer\n\n\n@API(input_model=BookSerializer)\nasync def single_book_api(request: Request, book_id: int):\n    if request.method == 'GET':\n        ...\n    elif request.method == 'PUT':\n        is_updated: bool = Book.update_one({'id': book_id}, request.data.dict())\n        data = {'is_updated': is_updated}\n        return Response(data=data, status_code=status.HTTP_202_ACCEPTED)\n</code></pre> </li> <li> <p>Update with <code>update_many</code> query</p> <pre><code>from panther import status\nfrom panther.app import API\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.models import Book\nfrom app.serializers import BookSerializer\n\n\n@API(input_model=BookSerializer)\nasync def single_book_api(request: Request, book_id: int):\n    if request.method == 'GET':\n        ...\n    elif request.method == 'PUT':\n        updated_count: int = Book.update_many({'id': book_id}, request.data.dict())\n        data = {'updated_count': updated_count}\n        return Response(data=data, status_code=status.HTTP_202_ACCEPTED)\n</code></pre> </li> </ol> <p>You can handle the PATCH the same way as PUT</p> </li> </ul>"},{"location":"function_first_crud/#api-delete-a-book","title":"API - Delete a Book","text":"<ul> <li> <p>We can delete in several ways too:</p> <ol> <li> <p>Delete a document</p> <p><pre><code>    from panther import status\n    from panther.app import API\n    from panther.request import Request\n    from panther.response import Response\n\n    from app.models import Book\n\n\n    @API()\n    async def single_book_api(request: Request, book_id: int):\n        if request.method == 'GET':\n            ...\n        elif request.method == 'PUT':\n            ...\n        elif request.method == 'DELETE':\n            is_deleted: bool = Book.delete_one(id=book_id)\n            if is_deleted:\n                return Response(status_code=status.HTTP_204_NO_CONTENT)\n            else:\n                return Response(status_code=status.HTTP_400_BAD_REQUEST)\n</code></pre>     2. Delete with <code>delete_one</code> query</p> <pre><code>    from panther import status\n    from panther.app import API\n    from panther.request import Request\n    from panther.response import Response\n\n    from app.models import Book\n\n\n    @API()\n    async def single_book_api(request: Request, book_id: int):\n        if request.method == 'GET':\n            ...\n        elif request.method == 'PUT':\n            ...\n        elif request.method == 'DELETE':\n            is_deleted: bool = Book.delete_one(id=book_id)\n            return Response(status_code=status.HTTP_204_NO_CONTENT)\n</code></pre> </li> <li> <p>Delete with <code>delete_many</code> query</p> <pre><code>    from panther import status\n    from panther.app import API\n    from panther.request import Request\n    from panther.response import Response\n\n    from app.models import Book\n\n\n    @API()\n    async def single_book_api(request: Request, book_id: int):\n        if request.method == 'GET':\n            ...\n        elif request.method == 'PUT':\n            ...\n        elif request.method == 'DELETE':\n            deleted_count: int = Book.delete_many(id=book_id)\n            return Response(status_code=status.HTTP_204_NO_CONTENT)\n</code></pre> </li> </ol> </li> </ul>"},{"location":"log_queries/","title":"Log Queries","text":"<p>Variable: <code>LOG_QUERIES</code> </p> <p>Type: <code>bool</code> </p> <p>Default: <code>False</code></p> <p>Panther has a <code>log_query</code> decorator on queries that process the <code>perf_time</code> of every query</p> <p>Make sure it is <code>False</code> on production for better performance</p>"},{"location":"log_queries/#log-example","title":"Log Example:","text":"<pre><code>INFO:     | 2023-03-19 20:37:27 | Query --&gt;  User.insert_one() --&gt; 1.6 ms\n</code></pre>"},{"location":"log_queries/#the-log-query-decorator-is-something-like-this","title":"The Log Query Decorator Is Something Like This","text":"<pre><code>def log_query(func):\n    def log(*args, **kwargs):\n        if config['log_queries'] is False:\n            return func(*args, **kwargs)\n\n        start = perf_counter()\n        response = func(*args, **kwargs)\n        end = perf_counter()\n        class_name = ...\n        query_logger.info(f'Query --&gt;  {class_name}.{func.__name__}() --&gt; {(end - start) * 1_000:.2} ms')\n        return response\n    return log\n</code></pre>"},{"location":"middlewares/","title":"Middlewares","text":"<p>Variable: <code>MIDDLEWARES</code> </p> <p>Type: <code>list</code> </p> <p>Default: <code>[]</code></p> <p>Panther has several <code>built-in</code> middleware:</p> <ul> <li> <p>Database Middleware</p> </li> <li> <p>Redis Middleware</p> </li> </ul> <p>And you can write your own custom middlewares too</p>"},{"location":"middlewares/#structure-of-middlewares","title":"Structure of middlewares","text":"<p><code>MIDDLEWARES</code> itself is a <code>list</code> of <code>tuples</code> which each <code>tuple</code> is like below:</p> <p>(<code>Address of Middleware Class</code>, <code>kwargs as dict</code>)</p>"},{"location":"middlewares/#database-middleware","title":"Database Middleware","text":"<p>This middleware will create a <code>db</code> connection that uses in <code>ODM</code> or you can use it manually from: <pre><code>from panther.db.connection import db\n</code></pre></p> <p>We only support 2 database: <code>PantherDB</code> &amp; <code>MongoDB</code></p> <ul> <li>Address of Middleware: <code>panther.middlewares.db.Middleware</code></li> <li> <p>kwargs:</p> <ul> <li> <p><code>{'url': f'pantherdb://{BASE_DIR}/{DB_NAME}.pdb'}</code></p> </li> <li> <p><code>{'url': f'mongodb://{DB_HOST}:27017/{DB_NAME}'}</code></p> </li> </ul> </li> <li> <p>Example of <code>PantherDB</code> (<code>Built-in Local Storage</code>):   <pre><code>MIDDLEWARES = [\n    ('panther.middlewares.db.Middleware', {'url': f'pantherdb://{BASE_DIR}/{DB_NAME}.pdb'}),\n]\n</code></pre></p> </li> <li>Example of <code>MongoDB</code>:   <pre><code>MIDDLEWARES = [\n    ('panther.middlewares.db.Middleware', {'url': f'mongodb://{DB_HOST}:27017/{DB_NAME}'}),\n]\n</code></pre></li> </ul>"},{"location":"middlewares/#redis-middleware","title":"Redis Middleware","text":"<ul> <li>Address of Middleware: <code>panther.middlewares.redis.Middleware</code></li> <li> <p>kwargs:      <pre><code>{'host': '127.0.0.1', 'port': 6379, ...}\n</code></pre></p> </li> <li> <p>Example   <pre><code>MIDDLEWARES = [\n    ('panther.middlewares.redis.Middleware', {'host': '127.0.0.1', 'port': 6379}),\n]\n</code></pre></p> </li> </ul>"},{"location":"middlewares/#custom-middleware","title":"Custom Middleware","text":"<p>Write a <code>class</code> and inherit from <pre><code>from panther.middlewares.base import BaseMiddleware\n</code></pre></p> <p>Then you can write your custom <code>before()</code> and <code>after()</code> methods</p> <ul> <li>The <code>methods</code> should be <code>async</code></li> <li><code>before()</code> should have <code>request</code> parameter</li> <li><code>after()</code> should have <code>response</code> parameter</li> <li>overwriting the <code>before()</code> and <code>after()</code> are optional</li> <li>The <code>methods</code> can get <code>kwargs</code> from their <code>__init__</code></li> </ul>"},{"location":"middlewares/#custom-middleware-example","title":"Custom Middleware Example","text":"<p>core/middlewares.py <pre><code>from panther.request import Request\nfrom panther.response import Response\nfrom panther.middlewares.base import BaseMiddleware\n\n\nclass CustomMiddleware(BaseMiddleware):\n\n    def __init__(self, something):\n        self.something = something\n\n    async def before(self, request: Request) -&gt; Request:\n        print('Before Endpoint', self.something)\n        return request\n\n    async def after(self, response: Response) -&gt; Response:\n        print('After Endpoint', self.something)\n        return response\n</code></pre> core/configs.py <pre><code>  MIDDLEWARES = [\n      ('core.middlewares.CustomMiddleware', {'something': 'hello-world'}),\n  ]\n</code></pre></p>"},{"location":"monitoring/","title":"Monitoring","text":"<p>Variable: <code>MONITORING</code> </p> <p>Type: <code>bool</code> </p> <p>Default: <code>False</code></p> <p>Panther has a <code>Monitoring</code> middleware that process the <code>perf_time</code> of every request</p> <p>It will create a <code>monitoring.log</code> file and log the records</p> <p>Then you can watch them live with: <code>panther monitor</code></p>"},{"location":"monitoring/#the-monitoring-middleware","title":"The Monitoring Middleware:","text":"<pre><code>    async def before(self, request: Request) -&gt; Request:\n        ip, port = request.client\n        self.log = f'{request.method} | {request.path} | {ip}:{port}'\n        self.start_time = perf_counter()\n        return request\n</code></pre> <pre><code>    async def after(self, status_code: int):\n        response_time = (perf_counter() - self.start_time) * 1_000\n        monitoring_logger.info(f'{self.log} | {response_time: .3} ms | {status_code}')\n</code></pre>"},{"location":"panther_odm/","title":"Panther ODM","text":""},{"location":"panther_odm/#find_one","title":"find_one","text":"<ul> <li>Find the first match document  </li> <li> <p>Example:  </p> <pre><code>user: User = User.find_one(id=1, name='Ali')  \n\nuser: User = User.find_one({'id': 1, 'name': 'Ali'})  \n\nuser: User = User.find_one({'id': 1}, name='Ali')  \n</code></pre> </li> </ul>"},{"location":"panther_odm/#find","title":"find","text":"<ul> <li>Find all the matches documents  </li> <li> <p>Example:  </p> <pre><code>users: list[User] = User.find(id=1, name='Ali')  \n\nusers: list[User] = User.find({'id': 1, 'name': 'Ali'})  \n\nusers: list[User] = User.find({'id': 1}, name='Ali')  \n</code></pre> </li> </ul>"},{"location":"panther_odm/#insert_one","title":"insert_one","text":"<ul> <li>Insert only one document into database  </li> <li> <p>Example:  </p> <pre><code>User.insert_one(id=1, name='Ali')  \n\nUser.insert_one({'id': 1, 'name': 'Ali'})  \n\nUser.insert_one({'id': 1}, name='Ali')  \n</code></pre> </li> </ul>"},{"location":"panther_odm/#delete","title":"delete","text":"<ul> <li>Delete the selected document from database</li> <li> <p>Example:  </p> <pre><code>user: User = User.find_one(name='Ali')\nuser.delete()\n</code></pre> </li> </ul>"},{"location":"panther_odm/#delete_one","title":"delete_one","text":"<ul> <li>Delete the first match document  from database</li> <li> <p>Example:  </p> <pre><code>is_deleted: bool = User.delete_one(id=1, name='Ali')\n</code></pre> </li> </ul>"},{"location":"panther_odm/#delete_many","title":"delete_many","text":"<ul> <li>Delete all the matches document  from database</li> <li> <p>Example:  </p> <pre><code>deleted_count: int = User.delete_many(id=1, name='Ali')\n\ndeleted_count: int = User.delete_many({'id': 1}, name='Ali')\n\ndeleted_count: int = User.delete_many({'id': 1, 'name': 'Ali'})\n</code></pre> </li> </ul>"},{"location":"panther_odm/#update","title":"update","text":"<ul> <li>Update the selected document in database</li> <li> <p>Example:  </p> <pre><code>user = User.find_one(name='Ali')\nuser.update(name='Saba')\n</code></pre> </li> </ul>"},{"location":"panther_odm/#update_one","title":"update_one","text":"<ul> <li>Update the first match document in database</li> <li>You should filter with <code>dictionary</code> as <code>first parameter</code>  and pass the fields you want to update as <code>kwargs</code> or another <code>dictionary</code> as <code>second parameter</code></li> <li> <p>Example:  </p> <pre><code>is_updated: bool = User.update_one({'id': 1, 'name': 'Ali'}, name='Saba', age=26)\n\nis_updated: bool = User.update_one({'id': 1, 'name': 'Ali'}, {'name': 'Saba', 'age': 26})\n\nis_updated: bool = User.update_one({'id': 1, 'name': 'Ali'}, {'name': 'Saba'}, age=26)\n</code></pre> </li> </ul>"},{"location":"panther_odm/#update_many","title":"update_many","text":"<ul> <li>Update all the matches document in database</li> <li>You should filter with <code>dictionary</code> as <code>first parameter</code>  and pass the fields you want to update as <code>kwargs</code> or another <code>dictionary</code> as <code>second parameter</code></li> <li> <p>Example:  </p> <pre><code>updated_count: int = User.update_many({'name': 'Ali'}, name='Saba', age=26)\n\nupdated_count: int = User.update_many({'name': 'Ali'}, {'name': 'Saba', 'age': 26})\n\nupdated_count: int = User.update_many({'name': 'Ali'}, {'name': 'Saba'}, age=26)\n</code></pre> </li> </ul>"},{"location":"panther_odm/#last","title":"last","text":"<ul> <li>Find the last match document</li> <li> <p>Example:  </p> <pre><code>user: User = User.last(name='Ali', age=26)  \n\nuser: User = User.last({'name': 'Ali', 'age': 26})  \n\nuser: User = User.last({'name': 'Ali'}, age=26)  \n</code></pre> </li> </ul>"},{"location":"panther_odm/#count","title":"count","text":"<ul> <li>Count of the matches documents</li> <li> <p>Example:  </p> <pre><code>users_count: int = User.count(name='Ali')\n</code></pre> </li> </ul>"},{"location":"panther_odm/#find_or_insert","title":"find_or_insert","text":"<ul> <li>Find the match document or Create one if none exists</li> <li> <p>Example:  </p> <pre><code>user: User = User.find_or_insert(name='Ali')\n</code></pre> </li> </ul>"},{"location":"release_notes/","title":"Release Notes","text":""},{"location":"release_notes/#240","title":"2.4.0","text":"<ul> <li>Handle Complex Multipart-FormData</li> </ul>"},{"location":"release_notes/#233","title":"2.3.3","text":"<ul> <li>Fix a bug in response headers</li> </ul>"},{"location":"release_notes/#232","title":"2.3.2","text":"<ul> <li>Fix a bug in Template</li> </ul>"},{"location":"release_notes/#231","title":"2.3.1","text":"<ul> <li>Handle PlainTextResponse</li> <li>Handle Custom Header in Response</li> <li>Change the way of accepting 'URLs' in configs (relative -&gt; dotted)</li> <li>Fix an issue in collect_all_models()</li> </ul>"},{"location":"release_notes/#230","title":"2.3.0","text":"<ul> <li>Handle HTMLResponse</li> </ul>"},{"location":"release_notes/#220","title":"2.2.0","text":"<ul> <li>Supporting File </li> </ul>"},{"location":"release_notes/#216","title":"2.1.6","text":"<ul> <li>Fix validation errors on nested inputs</li> </ul>"},{"location":"release_notes/#215","title":"2.1.5","text":"<ul> <li>Fix response of nested Models in _panel//"},{"location":"release_notes/#214","title":"2.1.4","text":"<ul> <li>Add access-control-allow-origin to response header</li> </ul>"},{"location":"release_notes/#213","title":"2.1.3","text":"<ul> <li>Upgrade greenlet version in requirements for python3.12</li> </ul>"},{"location":"release_notes/#212","title":"2.1.2","text":"<ul> <li>Add ruff.toml</li> <li>Add Coverage to workflows</li> <li>Fix a bug for running in Windows</li> </ul>"},{"location":"release_notes/#211","title":"2.1.1","text":"<ul> <li>Fix a bug in main.py imports</li> </ul>"},{"location":"release_notes/#210","title":"2.1.0","text":"<ul> <li>Support Sync APIs</li> </ul>"},{"location":"release_notes/#200","title":"2.0.0","text":"<ul> <li>Supporting class-base APIs</li> </ul>"},{"location":"release_notes/#1720","title":"1.7.20","text":"<ul> <li>Fix an issue in find_endpoint()</li> </ul>"},{"location":"release_notes/#1719","title":"1.7.19","text":"<ul> <li>Fix an issue in routing</li> <li>Fix an issue on return complex dict Response</li> </ul>"},{"location":"release_notes/#1718","title":"1.7.18","text":"<ul> <li>Remove uvloop from requirements for now (we had issue in windows)</li> </ul>"},{"location":"release_notes/#1716","title":"1.7.16","text":"<ul> <li>Trying to fix requirements for windows</li> <li>Minor improvement in BaseMongoDBQuery</li> </ul>"},{"location":"release_notes/#1715","title":"1.7.15","text":"<ul> <li>Fix an issue in handling form-data</li> </ul>"},{"location":"release_notes/#1714","title":"1.7.14","text":"<ul> <li>Add Cache and Throttling doc to FirstCrud</li> <li>Fix an issue in BasePantherDBQuery._merge() </li> </ul>"},{"location":"release_notes/#1713","title":"1.7.13","text":"<ul> <li>Hotfix validation of _id in Model()</li> </ul>"},{"location":"release_notes/#1712","title":"1.7.12","text":"<ul> <li>Fix a bug in routing</li> </ul>"},{"location":"release_notes/#1711","title":"1.7.11","text":"<ul> <li>Fix an issue in template</li> </ul>"},{"location":"release_notes/#1710","title":"1.7.10","text":"<ul> <li>Fix a bug in <code>collect_urls</code> and rename it to <code>flatten_urls</code></li> <li>Add General Tests</li> <li>Compatible with python3.10 (Not Tested)</li> <li>Working on docs</li> </ul>"},{"location":"release_notes/#179","title":"1.7.9","text":"<ul> <li>Working on doc</li> </ul>"},{"location":"release_notes/#178","title":"1.7.8","text":"<ul> <li>Fix a bug</li> <li>Update docs</li> </ul>"},{"location":"release_notes/#178_1","title":"1.7.8","text":"<ul> <li>Fix a bug</li> <li>Update docs</li> </ul>"},{"location":"release_notes/#177","title":"1.7.7","text":"<ul> <li>Fix a bug</li> </ul>"},{"location":"release_notes/#175","title":"1.7.5","text":"<ul> <li>Change the way of raising exception in JWTAuthentication</li> <li>Rename User model to BaseUser</li> <li>Fix template</li> </ul>"},{"location":"release_notes/#174","title":"1.7.4","text":"<ul> <li>Crop Logo</li> </ul>"},{"location":"release_notes/#173","title":"1.7.3","text":"<ul> <li>Add Throttling Doc</li> <li>Fix some issue in Doc</li> </ul>"},{"location":"release_notes/#172","title":"1.7.2","text":"<ul> <li>Add Throttling to example</li> <li>Customize install_requires in setup.py</li> <li>Improve monitoring cli command</li> </ul>"},{"location":"release_notes/#171","title":"1.7.1","text":"<ul> <li>Rename db BaseModel to Model </li> <li>Add more docs</li> </ul>"},{"location":"release_notes/#170","title":"1.7.0","text":"<ul> <li>Add Throttling</li> </ul>"},{"location":"release_notes/#161","title":"1.6.1","text":"<ul> <li>Add AdminPermission</li> </ul>"},{"location":"release_notes/#160","title":"1.6.0","text":"<ul> <li>Handle Permissions</li> </ul>"},{"location":"release_notes/#152","title":"1.5.2","text":"<ul> <li>Improve Response data serialization</li> <li>Fix a bug in JWTAuthentication</li> </ul>"},{"location":"release_notes/#151","title":"1.5.1","text":"<ul> <li>Fix error messages</li> </ul>"},{"location":"release_notes/#150","title":"1.5.0","text":"<ul> <li>Refactor Mongodb ODM</li> <li>Minor Improvement</li> </ul>"},{"location":"release_notes/#140","title":"1.4.0","text":"<ul> <li>Add QUERY_LOG</li> </ul>"},{"location":"release_notes/#132","title":"1.3.2","text":"<ul> <li>Add Uvicorn to the setup requirements</li> <li>Update Readme</li> </ul>"},{"location":"release_notes/#131","title":"1.3.1","text":"<ul> <li>Fix a bug in project creation template</li> <li>Fix a bug in caching</li> </ul>"},{"location":"release_notes/#130","title":"1.3.0","text":"<ul> <li>Add PantherDB to Panther</li> <li>Remove tinydb</li> </ul>"},{"location":"release_notes/#127","title":"1.2.7","text":"<ul> <li>Fix a bug while using tinydb</li> </ul>"},{"location":"release_notes/#126","title":"1.2.6","text":"<ul> <li>Update Readme</li> </ul>"},{"location":"release_notes/#125","title":"1.2.5","text":"<ul> <li>Fix install_requires issue</li> <li>Add benchmarks to docs</li> </ul>"},{"location":"release_notes/#124","title":"1.2.4","text":"<ul> <li>Remove Uvicorn From install_requires</li> <li>Working on Docs</li> </ul>"},{"location":"release_notes/#123","title":"1.2.3","text":"<ul> <li>Fix URL Routing</li> </ul>"},{"location":"release_notes/#121","title":"1.2.1","text":"<ul> <li>Path Variable Handled Successfully</li> </ul>"},{"location":"release_notes/#120","title":"1.2.0","text":"<ul> <li>Read multipart/form-data with Regex</li> </ul>"},{"location":"release_notes/#119","title":"1.1.9","text":"<ul> <li>Refactoring code style with ruff </li> <li>Add asyncio.TaskGroup() </li> </ul>"},{"location":"release_notes/#118","title":"1.1.8","text":"<ul> <li>Refactor cli run command </li> </ul>"},{"location":"release_notes/#117","title":"1.1.7","text":"<ul> <li>Add benchmark pictures to doc </li> </ul>"},{"location":"release_notes/#115","title":"1.1.5","text":"<ul> <li>Clean Readme</li> <li>Clean main.py </li> </ul>"},{"location":"release_notes/#114","title":"1.1.4","text":"<ul> <li>Update Readme </li> </ul>"},{"location":"release_notes/#113","title":"1.1.3","text":"<ul> <li>Fix a query in TinyDB </li> </ul>"},{"location":"release_notes/#112","title":"1.1.2","text":"<ul> <li>Add delete_many query to TinyDB </li> </ul>"},{"location":"release_notes/#111","title":"1.1.1","text":"<ul> <li>Add TinyDB</li> </ul>"},{"location":"release_notes/#110","title":"1.1.0","text":"<ul> <li>Debug the Template </li> </ul>"},{"location":"release_notes/#109","title":"1.0.9","text":"<ul> <li>Handle string exceptions (raise them as detail: error) </li> <li>Little debug on MongoQueries</li> </ul>"},{"location":"release_notes/#107","title":"1.0.7","text":"<ul> <li>Working on queries</li> <li>Fix a bug in query methods </li> </ul>"},{"location":"release_notes/#106","title":"1.0.6","text":"<ul> <li>Update the Template </li> </ul>"},{"location":"release_notes/#104","title":"1.0.4","text":"<ul> <li>Debug template </li> </ul>"},{"location":"release_notes/#102","title":"1.0.2","text":"<ul> <li>Add global config</li> <li>Split the BaseModels</li> <li>Worked on MongoQuery</li> <li>Set Mongo as default database while creating project </li> <li>Minor Improvement</li> </ul>"},{"location":"release_notes/#101","title":"1.0.1","text":"<ul> <li>Add alembic To Project </li> </ul>"},{"location":"release_notes/#10","title":"1.0.","text":"<ul> <li>Refactor &amp; Complete the CLI </li> </ul>"},{"location":"release_notes/#019","title":"0.1.9","text":"<ul> <li>Fix install_requires</li> </ul>"},{"location":"release_notes/#018","title":"0.1.8","text":"<ul> <li>Update Readme</li> </ul>"},{"location":"release_notes/#017","title":"0.1.7","text":"<ul> <li>Update Readme</li> </ul>"},{"location":"release_notes/#016","title":"0.1.6","text":"<ul> <li>Handle Most Types as Data in Response</li> </ul>"},{"location":"release_notes/#014","title":"0.1.4","text":"<ul> <li>Working On DB Connection </li> </ul>"},{"location":"release_notes/#001","title":"0.0.1","text":"<ul> <li>Make It Ready For PyPI </li> </ul>"},{"location":"throttling/","title":"Throttling","text":"<p>Variable: <code>THROTTLING</code> </p> <p>Type: <code>str</code> </p> <p>In Panther, you can use <code>Throttling</code> for all APIs at once in <code>core/configs.py</code> or per API in its <code>@API</code> decorator</p> <p>The <code>Throttling</code> class has 2 field <code>rate</code> &amp; <code>duration</code></p> <p>rate: int</p> <p>duration: datetime.timedelta</p> <p>It will return <code>Too Many Request</code> <code>status_code: 429</code> if user try to request in the <code>duration</code> more than <code>rate</code> And user will baned( get<code>Too Many Request</code> ) for <code>duration</code></p> <p>And keep that in mind if you have <code>Throttling</code> in <code>@API()</code>, the <code>Throttling</code> of <code>core/configs.py</code> will be ignored.</p>"},{"location":"throttling/#for-all-apis-example","title":"For All APIs Example:","text":"<p>core/configs.py <pre><code>from datetime import timedelta\n\nfrom panther.throttling import Throttling\n\n\n# User only can request 5 times in every minute\nTHROTTLING = Throttling(rate=5, duration=timedelta(minutes=1))\n</code></pre></p>"},{"location":"throttling/#for-single-api-example","title":"For Single API Example:","text":"<p>apis.py <pre><code>from datetime import timedelta\n\nfrom panther.throttling import Throttling\nfrom panther.app import API\n\n\n# User only can request 5 times in every minute\nInfoThrottling = Throttling(rate=5, duration=timedelta(minutes=1))\n\n\n@API(throttling=InfoThrottling)\nasync def info_api():\n    pass\n</code></pre></p>"},{"location":"todos/","title":"TODOs","text":""},{"location":"todos/#base","title":"Base","text":"<ul> <li>\u2705 Start with Uvicorn </li> <li>\u2705 Fix URL Routing </li> <li>\u2705 Read Configs </li> <li>\u2705 Handle Exceptions </li> <li>\u2705 Add Custom Logger </li> <li>\u2705 Request Class </li> <li>\u2705 Response Class </li> <li>\u2705 Validate Input </li> <li>\u2705 Custom Output Model </li> <li>\u2705 Log Queries</li> <li>\u2705 Add Package Requirements</li> <li>\u2705 Custom Logging</li> <li>\u2705 Caching</li> <li>\u2705 Handle Path Variable</li> <li>\u2705 Handle Simple Multipart-FormData</li> <li>\u2705 Handle Throttling</li> <li>\u2705 Handle ClassBase APIs</li> <li>\u2705 Handle File </li> <li>\u2705 Handle Complex Multipart-FormData</li> <li>\u2610 Handle Cookie</li> <li>\u2610 Handle WS </li> <li>\u2610 Handle GraphQL</li> <li>\u2610 Handle Testing</li> <li>\u2610 Generate Swagger For APIs</li> </ul>"},{"location":"todos/#database","title":"Database:","text":"<ul> <li>\u2705 Structure Of DB Connection</li> <li>\u2705 PantherDB Connection</li> <li>\u2705 MongoDB Connection</li> <li>\u2705 Create Custom BaseModel For All Type Of Databases</li> <li>\u2705 Set PantherDB As Default</li> </ul>"},{"location":"todos/#custom-odm","title":"Custom ODM","text":"<ul> <li>\u2705 Find One</li> <li>\u2705 Find </li> <li>\u2705 Last</li> <li>\u2705 Count</li> <li>\u2705 Insert One </li> <li>\u2705 Insert Many </li> <li>\u2705 Delete One</li> <li>\u2705 Delete Many</li> <li>\u2705 Delete Itself</li> <li>\u2705 Update One</li> <li>\u2705 Update Many</li> <li>\u2705 Update Itself</li> <li>\u2705 Find or Insert</li> <li>\u2705 Save</li> <li>\u2610 Find or Raise</li> <li>\u2610 Find with Pagination</li> <li>\u2610 Aggregation</li> <li>\u2610 Complex Pipelines</li> <li>\u2610 ...</li> </ul>"},{"location":"todos/#middleware","title":"Middleware","text":"<ul> <li>\u2705 Add Middlewares To Structure</li> <li>\u2705 Create BaseMiddleware</li> <li>\u2705 Pass Custom Parameters To Middlewares</li> <li>\u2705 Handle Custom Middlewares</li> </ul>"},{"location":"todos/#authentication","title":"Authentication","text":"<ul> <li>\u2705 JWT Authentication</li> <li>\u2705 Separate Auth For Every API</li> <li>\u2705 Handle Permissions </li> <li>\u2610 Token Storage Authentication</li> <li>\u2610 Cookie Authentication</li> <li>\u2610 Query Param Authentication</li> <li>\u2610 Store JWT After Logout In Redis/ Memory</li> </ul>"},{"location":"todos/#cache","title":"Cache","text":"<ul> <li>\u2705 Add Redis To Structure</li> <li>\u2705 Create Cache Decorator</li> <li>\u2705 Handle In Memory Caching </li> <li>\u2705 Handle In Redis Caching </li> <li>\u2610 Write Async LRU_Caching With TTL (Replace it with in memory ...)</li> </ul>"},{"location":"todos/#cli","title":"CLI","text":"<ul> <li>\u2705 Create Project </li> <li>\u2705 Run Project </li> <li>\u2705 Create Project with Options</li> <li>\u2705 Monitoring With Textual</li> <li>\u2705 Monitor Requests, Response &amp; Time</li> </ul>"},{"location":"todos/#documentation","title":"Documentation","text":"<ul> <li>\u2705 Create MkDocs For Project </li> <li>\u2705 Benchmarks</li> <li>\u2705 Release Notes</li> <li>\u2705 Features</li> <li>\u2610 Complete The MkDoc</li> </ul>"},{"location":"todos/#tests","title":"Tests","text":"<ul> <li>\u2705 Start Writing Tests For Panther </li> <li>\u2610 Test Client</li> </ul>"},{"location":"urls/","title":"URLs","text":"<p>Variable: <code>URLs</code> </p> <p>Type: <code>str</code> </p> <p>Required: <code>True</code></p> <ul> <li><code>URLs</code> should point to the root of your <code>urls</code> file, and in that file you should have a <code>dict</code> name <code>urls</code></li> <li> <p><code>key</code> of urls dict is <code>path</code> &amp; value is <code>endpoint</code> or another <code>dict</code></p> </li> <li> </li> </ul>"},{"location":"urls/#path-variables-are-handled-like-below","title":"Path Variables are handled like below:","text":"<ul> <li>&lt;<code>variable_name</code>&gt;</li> <li>Example: <code>user/&lt;user_id&gt;/blog/&lt;title&gt;/</code></li> <li>The <code>endpoint</code> should have parameters with those names too</li> <li>Example: <code>async def profile_api(user_id: int, title: str):</code></li> </ul>"},{"location":"urls/#example","title":"Example","text":"<ul> <li>core/configs.py     <pre><code>`URLs = 'configs/urls.py'`\n</code></pre></li> <li>core/urls.py     <pre><code>from app.urls import app_urls\n\nurls = {\n    'user/': app_urls,\n}\n</code></pre></li> <li> <p>app/urls.py     <pre><code>from app.apis import *\n\nurls = {\n    'login/': login_api,\n    'logout/': logout_api,\n    'profile/&lt;user_id&gt;/': profile_api,\n}\n</code></pre></p> </li> <li> <p>app/apis.py     <pre><code>...\n\n@API()\nasync def profile_api(user_id: int):\n    return User.find_one(id=user_id)\n</code></pre></p> </li> </ul>"},{"location":"working_with_db/","title":"Working With Database","text":"<p>Panther create a database connection depends on database middleware you are using on <code>core/configs.py</code>  and you can access to this connection from your <code>models</code>  or direct access from <code>from panther.db.connection import db</code></p> <p>Now we are going to create a new API which uses our default database(<code>PantherDB</code>) and creating a <code>Book</code></p> <ol> <li> <p>Create <code>Book</code> model in <code>app/models.py</code> <pre><code>from panther.db import Model\n\n\nclass Book(Model):\n    title: str\n    description: str\n    pages_count: int\n</code></pre></p> </li> <li> <p>Add <code>book</code> url in <code>app/urls.py</code> that points to <code>book_api()</code></p> <pre><code>...\nfrom app.apis import time_api, book_api\n\n\nurls = {\n    '': hello_world,\n    'info/': info,\n    'time/': time_api,\n    'book/': book_api,\n}\n</code></pre> </li> <li> <p>Create <code>book_api()</code> in <code>app/apis.py</code></p> <pre><code>from panther import status\nfrom panther.app import API\nfrom panther.response import Response\n\n\n@API()\nasync def book_api():\n    ...\n    return Response(status_code=status.HTTP_201_CREATED)  \n</code></pre> </li> <li> <p>Now we should use the Panther ODM to create a book, it's based on mongo queries, for creation we use <code>insert_one</code> like this:</p> <pre><code>from panther import status\nfrom panther.app import API\nfrom panther.response import Response\nfrom app.models import Book\n\n\n@API()\nasync def book_api():\n    Book.insert_one(\n        title='Python',\n        description='Python is good.',\n        pages_count=10\n    )\n    return Response(status_code=status.HTTP_201_CREATED)  \n</code></pre> </li> </ol> <p>In next step we are going to explain more about <code>Panther ODM</code></p>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Introduction","text":""},{"location":"#panther","title":"Panther","text":"<p>Is A Fast &amp;  Friendly Web Framework For Building Async APIs With Python 3.11+ </p> <p> </p> <p> Supported by JetBrains </p> <p> <p> </p> <p></p>"},{"location":"#why-use-panther","title":"Why Use Panther ?","text":"<ul> <li>Document-oriented Databases ODM (PantherDB, MongoDB)</li> <li>Visual API Monitoring (In Terminal)</li> <li>Cache APIs (In Memory, In Redis)</li> <li>Built-in Authentication Classes (Customizable)</li> <li>Built-in Permission Classes (Customizable)</li> <li>Handle Custom Middlewares</li> <li>Handle Custom Throttling </li> </ul>"},{"location":"#installation","title":"Installation","text":"<ul> <li> Create a Virtual Environment <pre>$ python3 -m venv .venv</pre> <ul> <li> Active The Environment<ul> <li>Linux &amp; Mac   <pre>$ source .venv/bin/activate</pre></li> <li>Windows   <pre>$ .\\.venv\\Scripts\\activate</pre></li> </ul> <ul> <li> Install Panther<ul> <li>Normal   <pre>$ pip install panther</pre></li> <li>Include MongoDB Requirements   <pre>$ pip install panther[full]</pre> </li> </ul>"},{"location":"#usage","title":"Usage","text":""},{"location":"#create-project","title":"Create Project","text":"<pre><code>$ panther create &lt;project_name&gt; &lt;directory&gt;\n</code></pre>"},{"location":"#run-project","title":"Run Project","text":"<p>Panther uses Uvicorn as ASGI (Asynchronous Server Gateway Interface)</p> <pre><code>$ panther run </code></pre>"},{"location":"#monitoring-requests","title":"Monitoring Requests","text":"<pre><code>$ panther monitor </code></pre>"},{"location":"#python-shell","title":"Python Shell","text":"<p>Panther Uses bpython for shell</p> <pre><code>$ panther shell </code></pre>"},{"location":"#example","title":"Example","text":"<ul> <li> <p>Then run the project:</p> </li> <li> <p><code>$ cd myproject</code></p> </li> <li><code>$ panther run</code> or <code>$ panther run --reload</code> </li> </ul> <p>now you can see these two urls:</p> <ul> <li> <p>http://127.0.0.1:8000/</p> </li> <li> <p>http://127.0.0.1:8000/info/</p> </li> </ul> <p>Writing Your First CRUD: First CRUD</p>"},{"location":"#you-can-create-project-with","title":"You can create project with","text":"<pre><code>$ panther create myproject\n</code></pre>"},{"location":"#or-create-it-yourself","title":"or create it yourself:","text":"<p>core/configs.py:</p> <pre><code>URLs = 'core.urls.url_routing'\n</code></pre> <p>core/urls.py:</p> <pre><code>from app.urls import urls as app_urls\n\nurl_routing = {\n    '/': app_urls,\n}\n</code></pre> <p>app/urls.py:</p> <pre><code>from app.apis import hello_world, info\n\nurls = {\n    '': hello_world,\n    'info/': info,\n}\n</code></pre> <p>app/apis.py:</p> <pre><code>from datetime import datetime, timedelta\n\nfrom panther.app import API\nfrom panther.configs import config\nfrom panther import version, status\nfrom panther.request import Request\nfrom panther.response import Response\nfrom panther.throttling import Throttling\n\n\nInfoThrottling = Throttling(rate=5, duration=timedelta(minutes=1))\n\n@API()\nasync def hello_world():\n    return {'detail': 'Hello World'}\n\n\n@API(cache=True, throttling=InfoThrottling)\nasync def info(request: Request):\n    data = {\n        'version': version(),\n        'datetime_now': datetime.now().isoformat(),\n        'user_agent': request.headers.user_agent,\n        'db_engine': config['db_engine'],\n    }\n    return Response(data=data, status_code=status.HTTP_202_ACCEPTED)\n</code></pre>"},{"location":"authentications/","title":"Authentications","text":"<p>Variable: <code>AUTHENTICATION</code> </p> <p>Type: <code>str</code></p> <p>Default: <code>None</code></p> <p>You can set your Authentication class in <code>core/configs.py</code>, then Panther will use this class for authentication in every <code>API</code>, if you set <code>auth=True</code> in <code>@API()</code>, and put the <code>user</code> in <code>request.user</code> or <code>raise HTTP_401_UNAUTHORIZED</code> </p> <p>We already have one built-in authentication class which is used <code>JWT</code> for authentication.</p> <p>You can write your own authentication class too (we are going to discuss it)</p>"},{"location":"authentications/#jwtauthentication","title":"JWTAuthentication","text":"<p>This class will </p> <ul> <li>Get the <code>token</code> from <code>Authorization</code> header of request with keyword of <code>Bearer</code></li> <li><code>decode</code> it </li> <li>Find the match <code>user</code> in <code>USER_MODEL</code> you have already set</li> </ul> <p><code>JWTAuthentication</code> is going to use <code>panther.db.models.BaseUser</code> if you didn't set the <code>USER_MODEL</code> in your <code>core/configs.py</code></p> <p>You can customize these 3 variables for <code>JWTAuthentication</code> in your <code>core/configs.py</code> as <code>JWTConfig</code> like below (<code>JWTConfig</code> is optional):</p> <pre><code>...\nfrom datetime import timedelta\nfrom panther.utils import load_env  \nfrom pathlib import Path\n\nBASE_DIR = Path(__name__).resolve().parent  \nenv = load_env(BASE_DIR / '.env')\n\nSECRET_KEY = env['SECRET_KEY']\n\nJWTConfig = {  \n    'key': SECRET_KEY,  \n    'algorithm': 'HS256',  \n    'life_time': timedelta(days=2),  \n}\n</code></pre> <p>key \u2003\u2003\u2003\u2003--&gt; default is <code>SECRET_KEY</code></p> <p>algorithm \u2003 --&gt; default is <code>HS256</code></p> <p>life_time\u2003\u2003--&gt; default is <code>timedelta(days=1)</code> </p>"},{"location":"authentications/#custom-authentication","title":"Custom Authentication","text":"<ul> <li> <p>Create a class and inherits it from <code>panther.authentications.BaseAuthentication</code></p> </li> <li> <p>Implement <code>authentication(cls, request: Request)</code> method</p> <ul> <li>Process the <code>request.headers.authorization</code> or ...</li> <li>Return Instance of <code>USER_MODEL</code></li> <li>Or raise <code>panther.exceptions.AuthenticationException</code> </li> </ul> </li> <li> <p>Address it in <code>core/configs.py</code></p> </li> <li><code>AUTHENTICATION = 'project_name.core.authentications.CustomAuthentication'</code></li> </ul> <p>You can look at the source code of JWTAuthentication for </p>"},{"location":"benchmarks/","title":"Benchmarks","text":""},{"location":"benchmarks/#benchmark","title":"Benchmark","text":"Framework Throughput Request Handled Max Latencies Sanic 23,326 233,842 268.8ms Panther 14,719 147,595 113.1ms FastAPI 14,573 146,467 155.1ms Tornado 4,969 50.585 426.5ms Flask 3,555 36,396 1.2s Django 2,188 22,814 526.3ms Bottle 1,226 39,650 30.0s Pyramid 1,023 30,912 30.0s Cherrypy 639 24,944 30.0s"},{"location":"benchmarks/#all-tests-happen-in","title":"All tests happen in","text":"<ul> <li>CPU: AMD Ryzen 9 5900HX with Radeon Graphics (16) @ 3.300GHz</li> <li>OS: Arch Linux x86_64</li> <li>KERNEL: 6.2.2-arch1-1</li> </ul>"},{"location":"benchmarks/#results","title":"Results","text":""},{"location":"benchmarks/#sanic","title":"Sanic","text":"<p>[Test Source Code]</p> <p></p>"},{"location":"benchmarks/#panther","title":"Panther","text":"<p>[Test Source Code]</p> <p></p>"},{"location":"benchmarks/#fastapi","title":"FastAPI","text":"<p>[Test Source Code]</p> <p></p>"},{"location":"benchmarks/#tornado","title":"Tornado","text":"<p>[Test Source Code]</p> <p></p>"},{"location":"benchmarks/#flask","title":"Flask","text":"<p>[Test Source Code]</p> <p></p>"},{"location":"benchmarks/#django","title":"Django","text":"<p>[Test Source Code]</p> <p></p>"},{"location":"benchmarks/#bottle","title":"Bottle","text":"<p>[Test Source Code]</p> <p></p>"},{"location":"benchmarks/#pyramid","title":"Pyramid","text":"<p>[Test Source Code]</p> <p></p>"},{"location":"benchmarks/#cherrypy","title":"Cherrypy","text":"<p>[Test Source Code]</p> <p></p>"},{"location":"class_first_crud/","title":"Class Base","text":"<p>We assume you could run the project with Introduction</p> <p>Now let's write custom API <code>Create</code>, <code>Retrieve</code>, <code>Update</code> and <code>Delete</code> for a <code>Book</code>:</p>"},{"location":"class_first_crud/#structure-requirements","title":"Structure &amp; Requirements","text":""},{"location":"class_first_crud/#create-model","title":"Create Model","text":"<p>Create a model named <code>Book</code> in <code>app/models.py</code>:</p> <pre><code>from panther.db import Model\n\n\nclass Book(Model):\n    name: str\n    author: str\n    pages_count: int\n</code></pre>"},{"location":"class_first_crud/#create-api-class","title":"Create API Class","text":"<p>Create the <code>BookAPI()</code> in <code>app/apis.py</code>:</p> <pre><code>from panther.app import GenericAPI\n\n\nclass BookAPI(GenericAPI):\n    ... \n</code></pre> <p>We are going to complete it later ...</p>"},{"location":"class_first_crud/#update-urls","title":"Update URLs","text":"<p>Add the <code>BookAPI</code> in <code>app/urls.py</code>:</p> <pre><code>from app.apis import BookAPI\n\n\nurls = {\n    'book/': BookAPI,\n}\n</code></pre> <p>We assume that the <code>urls</code> in <code>core/urls.py</code> pointing to <code>app/urls.py</code>, like below:</p> <pre><code>from app.urls import urls as app_urls\n\n\nurls = {\n    '/': app_urls,\n}\n</code></pre>"},{"location":"class_first_crud/#add-database-middleware","title":"Add Database Middleware","text":"<p>Add one database middleware in <code>core/configs.py</code> <code>MIDDLEWARES</code>, we are going to add <code>pantherdb</code></p> <p>PantherDB is a Simple, FileBase and Document Oriented database:</p> <pre><code>...\n\nMIDDLEWARES = [\n    ('panther.middlewares.db.Middleware', {'url': f'pantherdb://{BASE_DIR}/{DB_NAME}.pdb'}),\n]\n</code></pre>"},{"location":"class_first_crud/#apis","title":"APIs","text":""},{"location":"class_first_crud/#api-create-a-book","title":"API - Create a Book","text":"<p>Now we are going to create a book on <code>post</code> request, We need to:</p> <ol> <li> <p>Declare <code>post</code> method in <code>BookAPI</code>:     <pre><code>from panther.app import GenericAPI\n\n\nclass BookAPI(GenericAPI):\n\n    def post(self):\n        ...\n</code></pre></p> </li> <li> <p>Declare <code>request: Request</code> in <code>BookAPI.post()</code> function:     <pre><code>from panther.app import GenericAPI\nfrom panther.request import Request\n\n\nclass BookAPI(GenericAPI):\n\n    def post(self, request: Request):\n        ...\n</code></pre></p> </li> <li> <p>Create serializer in <code>app/serializers.py</code>, we used <code>pydantic</code> for the <code>validation</code> of <code>request.data</code> :     <pre><code>from pydantic import BaseModel\n\n\nclass BookSerializer(BaseModel):\n    name: str\n    author: str\n    pages_count: int\n</code></pre></p> </li> <li> <p>Pass the created serializer to our <code>BookAPI</code> as <code>input_model</code> so the incoming data will be validated and cleaned automatically:</p> <p><pre><code>from panther.app import GenericAPI\nfrom panther.request import Request\n\nfrom app.serializers import BookSerializer\n\n\nclass BookAPI(GenericAPI):\n    input_model = BookSerializer\n\n    def post(self, request: Request):\n        ...\n</code></pre>    Now we have access to <code>request.data</code>, We are going to use it like the below for ease of use, so the auto-suggest helps us in development:</p> <pre><code>from panther.app import GenericAPI\nfrom panther.request import Request\n\nfrom app.serializers import BookSerializer\n\n\nclass BookAPI(GenericAPI):\n    input_model = BookSerializer\n\n    def post(self, request: Request):\n        body: BookSerializer = request.data\n        ...\n</code></pre> </li> <li> <p>Now we have access to the validated data, and we can create our first book:</p> <pre><code>from panther.app import GenericAPI\nfrom panther.request import Request\n\nfrom app.serializers import BookSerializer\nfrom app.models import Book\n\n\nclass BookAPI(GenericAPI):\n    input_model = BookSerializer\n\n    def post(self, request: Request):\n        body: BookSerializer = request.data\n        Book.insert_one(\n            name=body.name,\n            author=body.author,\n            pages_count=body.pages_count,\n        )\n        ...\n</code></pre> </li> <li> <p>And finally we return <code>201 Created</code> status_code as response of <code>post</code>:     <pre><code>from panther import status\nfrom panther.app import GenericAPI\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.serializers import BookSerializer\nfrom app.models import Book\n\n\nclass BookAPI(GenericAPI):\n    input_model = BookSerializer\n\n    def post(self, request: Request):\n        body: BookSerializer = request.data\n        book = Book.insert_one(\n            name=body.name,\n            author=body.author,\n            pages_count=body.pages_count,\n        )\n        return Response(data=book, status_code=status.HTTP_201_CREATED)\n</code></pre></p> </li> </ol> <p>The response.data can be <code>Instance of Models</code>, <code>dict</code>, <code>str</code>, <code>tuple</code>, <code>list</code>, <code>str</code> or <code>None</code></p> <p>Panther will return <code>None</code> if you don't return anything as response.</p>"},{"location":"class_first_crud/#api-list-of-books","title":"API - List of Books","text":"<p>We just need to add another method for <code>GET</code> method and return the lists of books:</p> <pre><code>from panther import status\nfrom panther.app import GenericAPI\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.serializers import BookSerializer\nfrom app.models import Book\n\n\nclass BookAPI(GenericAPI):\n    input_model = BookSerializer\n\n    def post(self, request: Request):\n        ...\n\n    def get(self):\n        books: list[Book] = Book.find()\n        return Response(data=books, status_code=status.HTTP_200_OK)\n</code></pre> <p>Panther validate input with <code>input_model</code>, only in <code>POST</code>, <code>PUT</code>, <code>PATCH</code> methods.</p>"},{"location":"class_first_crud/#filter-response-fields","title":"Filter Response Fields","text":"<p>Assume we don't want to return field <code>author</code> in response:</p> <ol> <li> <p>Create new serializer in <code>app/serializers.py</code>:</p> <pre><code>from pydantic import BaseModel\n\n\nclass BookOutputSerializer(BaseModel):\n    name: str\n    pages_count: int\n</code></pre> </li> <li> <p>Add the <code>BookOutputSerializer</code> as <code>output_model</code> to your <code>class</code></p> <pre><code>from panther import status\nfrom panther.app import GenericAPI\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.serializers import BookSerializer, BookOutputSerializer\nfrom app.models import Book\n\n\nclass BookAPI(GenericAPI):\n    input_model = BookSerializer\n    output_model = BookOutputSerializer\n\n    def post(self, request: Request):\n        ...\n\n    def get(self):\n        books: list[Book] = Book.find()\n        return Response(data=books, status_code=status.HTTP_200_OK)\n</code></pre> </li> </ol> <p>Panther use the <code>output_model</code>, in all methods.</p>"},{"location":"class_first_crud/#cache-the-response","title":"Cache The Response","text":"<p>For caching the response, we should add <code>cache=True</code> in <code>API()</code>. And it will return the cached response every time till <code>cache_exp_time</code></p> <p>For setting a custom expiration time for API we need to add <code>cache_exp_time</code> to <code>API()</code>:</p> <pre><code>from datetime import timedelta\n\nfrom panther import status\nfrom panther.app import GenericAPI\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.serializers import BookSerializer, BookOutputSerializer\nfrom app.models import Book\n\n\nclass BookAPI(GenericAPI):\n    input_model = BookSerializer\n    output_model = BookOutputSerializer\n    cache = True\n    cache_exp_time = timedelta(seconds=10)\n\n    def post(self, request: Request):\n        ...\n\n    def get(self):\n        books: list[Book] = Book.find()\n        return Response(data=books, status_code=status.HTTP_200_OK)\n</code></pre> <p>Panther is going to use the <code>DEFAULT_CACHE_EXP</code> from <code>core/configs.py</code> if <code>cache_exp_time</code> has not been set.</p>"},{"location":"class_first_crud/#throttle-the-request","title":"Throttle The Request","text":"<p>For setting rate limit for requests, we can add throttling to <code>BookAPI</code>, it should be the instance of <code>panther.throttling.Throttling</code>, something like below (in the below example user can't request more than 10 times in a minutes):</p> <pre><code>from datetime import timedelta\n\nfrom panther import status\nfrom panther.app import GenericAPI\nfrom panther.request import Request\nfrom panther.response import Response\nfrom panther.throttling import Throttling\n\nfrom app.serializers import BookSerializer, BookOutputSerializer\nfrom app.models import Book\n\n\nclass BookAPI(GenericAPI):\n    input_model = BookSerializer\n    output_model = BookOutputSerializer\n    cache = True\n    cache_exp_time = timedelta(seconds=10)\n    throttling = Throttling(rate=10, duration=timedelta(minutes=1))\n\n    def post(self, request: Request):\n        ...\n\n    def get(self):\n        books: list[Book] = Book.find()\n        return Response(data=books, status_code=status.HTTP_200_OK)\n</code></pre>"},{"location":"class_first_crud/#api-retrieve-a-book","title":"API - Retrieve a Book","text":"<p>For <code>retrieve</code>, <code>update</code> and <code>delete</code> API, we are going to</p> <ol> <li> <p>Create another class named <code>SingleBookAPI</code> in <code>app/apis.py</code>:</p> <pre><code>from panther.app import GenericAPI\n\n\nclass SingleBookAPI(GenericAPI):\n    ...\n</code></pre> </li> <li> <p>Add it in <code>app/urls.py</code>:</p> <pre><code>from app.apis import BookAPI, SingleBookAPI\n\n\nurls = {\n    'book/': BookAPI,\n    'book/&lt;book_id&gt;/': SingleBookAPI,\n}\n</code></pre> </li> </ol> <p>You should write the Path Variable in <code>&lt;</code> and <code>&gt;</code></p> <p>You should have the parameter with the same name of <code>path variable</code> in you <code>api</code> with normal <code>type hints</code></p> <p>Panther will convert type of the <code>path variable</code> to your parameter type, then pass it</p> <ol> <li> <p>Complete the api:</p> <pre><code>from panther import status\nfrom panther.app import GenericAPI\nfrom panther.response import Response\n\nfrom app.models import Book\n\n\nclass SingleBookAPI(GenericAPI):\n\n    def get(self, book_id: int):\n        if book := Book.find_one(id=book_id):\n            return Response(data=book, status_code=status.HTTP_200_OK)\n        else:\n            return Response(status_code=status.HTTP_404_NOT_FOUND)\n</code></pre> </li> </ol>"},{"location":"class_first_crud/#api-update-a-book","title":"API - Update a Book","text":"<ul> <li> <p>We can update in several ways:</p> <ol> <li> <p>Update a document</p> <pre><code>from panther import status\nfrom panther.app import GenericAPI\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.models import Book\nfrom app.serializers import BookSerializer\n\n\nclass SingleBookAPI(GenericAPI):\n    input_model = BookSerializer\n\n    def get(self, book_id: int):\n        ...\n\n    def put(self, request: Request, book_id: int):\n        body: BookSerializer = request.data\n\n        book: Book = Book.find_one(id=book_id)\n        book.update(\n            name=body.name, \n            author=body.author, \n            pages_count=body.pages_count\n        )\n        return Response(status_code=status.HTTP_202_ACCEPTED)\n</code></pre> </li> <li> <p>Update with <code>update_one</code> query</p> <pre><code>from panther import status\nfrom panther.app import GenericAPI\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.models import Book\nfrom app.serializers import BookSerializer\n\n\nclass SingleBookAPI(GenericAPI):\n    input_model = BookSerializer\n\n    def get(self, book_id: int):\n        ...\n\n    def put(self, request: Request, book_id: int):\n        is_updated: bool = Book.update_one({'id': book_id}, request.data.dict())\n        data = {'is_updated': is_updated}\n        return Response(data=data, status_code=status.HTTP_202_ACCEPTED)\n</code></pre> </li> <li> <p>Update with <code>update_many</code> query</p> <pre><code>from panther import status\nfrom panther.app import GenericAPI\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.models import Book\nfrom app.serializers import BookSerializer\n\n\nclass SingleBookAPI(GenericAPI):\n    input_model = BookSerializer\n\n    def get(self, book_id: int):\n        ...\n\n    def put(self, request: Request, book_id: int):\n        updated_count: int = Book.update_many({'id': book_id}, request.data.dict())\n        data = {'updated_count': updated_count}\n        return Response(data=data, status_code=status.HTTP_202_ACCEPTED)\n</code></pre> </li> </ol> <p>You can handle the PATCH the same way as PUT</p> </li> </ul>"},{"location":"class_first_crud/#api-delete-a-book","title":"API - Delete a Book","text":"<ul> <li> <p>We can delete in several ways too:</p> <ol> <li> <p>Delete a document</p> <p><pre><code>    from panther import status\n    from panther.app import GenericAPI\n    from panther.request import Request\n    from panther.response import Response\n\n    from app.models import Book\n\n    class SingleBookAPI(GenericAPI):\n        input_model = BookSerializer\n\n        def get(self, book_id: int):\n            ...\n\n        def put(self, request: Request, book_id: int):\n            ...\n\n        def delete(self, book_id: int):\n            is_deleted: bool = Book.delete_one(id=book_id)\n            if is_deleted:\n                return Response(status_code=status.HTTP_204_NO_CONTENT)\n            else:\n                return Response(status_code=status.HTTP_400_BAD_REQUEST)\n</code></pre>     2. Delete with <code>delete_one</code> query</p> <pre><code>    from panther import status\n    from panther.app import GenericAPI\n    from panther.request import Request\n    from panther.response import Response\n\n    from app.models import Book\n\n\n    class SingleBookAPI(GenericAPI):\n        input_model = BookSerializer\n\n        def get(self, book_id: int):\n            ...\n\n        def put(self, request: Request, book_id: int):\n            ...\n\n        def delete(self, book_id: int):\n            is_deleted: bool = Book.delete_one(id=book_id)\n            return Response(status_code=status.HTTP_204_NO_CONTENT)\n</code></pre> </li> <li> <p>Delete with <code>delete_many</code> query</p> <pre><code>    from panther import status\n    from panther.app import GenericAPI\n    from panther.request import Request\n    from panther.response import Response\n\n    from app.models import Book\n\n\n    class SingleBookAPI(GenericAPI):\n        input_model = BookSerializer\n\n        def get(self, book_id: int):\n            ...\n\n        def put(self, request: Request, book_id: int):\n            ...\n\n        def delete(self, book_id: int):\n            deleted_count: int = Book.delete_many(id=book_id)\n            return Response(status_code=status.HTTP_204_NO_CONTENT)\n</code></pre> </li> </ol> </li> </ul>"},{"location":"configs/","title":"Configs","text":"<p>Panther  stores all the configs in the <code>core/configs.py</code></p>"},{"location":"configs/#monitoring","title":"MONITORING","text":"<p>Type: <code>bool</code> (Default: <code>False</code>)</p> <p>It should be <code>True</code> if you want to use <code>panther monitor</code> command and see the monitoring logs</p> <p>If <code>True</code> it will:</p> <ul> <li>Log every request in <code>logs/monitoring.log</code></li> </ul>"},{"location":"configs/#log_queries","title":"LOG_QUERIES","text":"<p>Type: <code>bool</code> (Default: <code>False</code>)</p> <p>If <code>True</code> it will:</p> <ul> <li>Calculate every query perf time &amp; Log them in <code>logs/query.log</code></li> </ul>"},{"location":"configs/#middlewares","title":"MIDDLEWARES","text":"<p>Type: <code>list</code> (Default: <code>[ ]</code>)</p> <p>List of middlewares you want to use</p>"},{"location":"configs/#authentication","title":"AUTHENTICATION","text":"<p>Type: <code>str | None</code> (Default: <code>None</code>)</p> <p>Every request goes through <code>authentication()</code> method of this <code>class</code></p> <p>Example: <code>AUTHENTICATION = 'panther.authentications.JWTAuthentication'</code></p>"},{"location":"configs/#urls","title":"URLs","text":"<p>Type: <code>str</code> (Required)</p> <p>It should be the address of your <code>urls</code> <code>dict</code></p> <p>Example: <code>URLS = 'configs.urls.url_routing'</code></p>"},{"location":"configs/#default_cache_exp","title":"DEFAULT_CACHE_EXP","text":"<p>Type: <code>timedelta| None</code> (Default: <code>None</code>)</p> <p>We use it as default <code>cache_exp_time</code> you can overwrite it in your <code>@API</code> too</p> <p>It is used when you set <code>cache=True</code> in <code>@API</code> decorator</p> <p>Example: <code>DEFAULT_CACHE_EXP = timedelta(seconds=10)</code></p>"},{"location":"configs/#throttling","title":"THROTTLING","text":"<p>Type: <code>Throttling | None</code> (Default: <code>None</code>)</p> <p>We use it as default <code>throttling</code> you can overwrite it in your <code>@API</code> too</p> <p>Example: <code>THROTTLING = Throttling(rate=10, duration=timedelta(seconds=10))</code></p>"},{"location":"configs/#user_model","title":"USER_MODEL","text":"<p>Type: <code>str | None</code> (Default: <code>'panther.db.models.BaseUser'</code>)</p> <p>It is used for authentication</p> <p>Example: <code>USER_MODEL = 'panther.db.models.User'</code></p>"},{"location":"configs/#jwtconfig","title":"JWTConfig","text":"<p>Type: <code>dict | None</code> (Default: <code>JWTConfig = {'key': SECRET_KEY}</code>)</p> <p>We use it when you set <code>panther.authentications.JWTAuthentication</code> as <code>AUTHENTICATION</code></p>"},{"location":"function_first_crud/","title":"Function Base","text":"<p>We assume you could run the project with Introduction</p> <p>Now let's write custom API <code>Create</code>, <code>Retrieve</code>, <code>Update</code> and <code>Delete</code> for a <code>Book</code>:</p>"},{"location":"function_first_crud/#structure-requirements","title":"Structure &amp; Requirements","text":""},{"location":"function_first_crud/#create-model","title":"Create Model","text":"<p>Create a model named <code>Book</code> in <code>app/models.py</code>:</p> <pre><code>from panther.db import Model\n\n\nclass Book(Model):\n    name: str\n    author: str\n    pages_count: int\n</code></pre>"},{"location":"function_first_crud/#create-api-function","title":"Create API Function","text":"<p>Create the <code>book_api()</code> in <code>app/apis.py</code>:</p> <pre><code>from panther.app import API\n\n\n@API()\nasync def book_api():\n    ... \n</code></pre> <p>We are going to complete it later ...</p>"},{"location":"function_first_crud/#update-urls","title":"Update URLs","text":"<p>Add the <code>book_api</code> in <code>app/urls.py</code>:</p> <pre><code>from app.apis import book_api\n\n\nurls = {\n    'book/': book_api,\n}\n</code></pre> <p>We assume that the <code>urls</code> in <code>core/urls.py</code> pointing to <code>app/urls.py</code>, like below:</p> <pre><code>from app.urls import urls as app_urls\n\n\nurls = {\n    '/': app_urls,\n}\n</code></pre>"},{"location":"function_first_crud/#add-database-middleware","title":"Add Database Middleware","text":"<p>Add one database middleware in <code>core/configs.py</code> <code>MIDDLEWARES</code>, we are going to add <code>pantherdb</code></p> <p>PantherDB is a Simple, FileBase and Document Oriented database:</p> <pre><code>...\n\nMIDDLEWARES = [\n    ('panther.middlewares.db.Middleware', {'url': f'pantherdb://{BASE_DIR}/{DB_NAME}.pdb'}),\n]\n</code></pre>"},{"location":"function_first_crud/#apis","title":"APIs","text":""},{"location":"function_first_crud/#api-create-a-book","title":"API - Create a Book","text":"<p>Now we are going to create a book on <code>post</code> request, We need to:</p> <ol> <li> <p>Declare <code>request: Request</code> in <code>book_api</code> function:     <pre><code>from panther.app import API\nfrom panther.request import Request\n\n\n@API()\nasync def book_api(request: Request):\n    ...\n</code></pre></p> </li> <li> <p>Create serializer in <code>app/serializers.py</code>, we used <code>pydantic</code> for the <code>validation</code> of <code>request.data</code> :     <pre><code>from pydantic import BaseModel\n\n\nclass BookSerializer(BaseModel):\n    name: str\n    author: str\n    pages_count: int\n</code></pre></p> </li> <li> <p>Pass the created serializer to our <code>book_api</code> as <code>input_model</code> so the incoming data will be validated and cleaned automatically:</p> <p><pre><code>from panther.app import API\nfrom panther.request import Request\n\nfrom app.serializers import BookSerializer\n\n\n@API(input_model=BookSerializer)\nasync def book_api(request: Request):\n    ...\n</code></pre>    Now we have access to <code>request.data</code>, We are going to use it like the below for ease of use, so the auto-suggest helps us in development:</p> <pre><code>from panther.app import API\nfrom panther.request import Request\n\nfrom app.serializers import BookSerializer\n\n\n@API(input_model=BookSerializer)\nasync def book_api(request: Request):\n    body: BookSerializer = request.data\n    ...\n</code></pre> </li> <li> <p>Now we have access to the validated data, and we can create our first book:</p> <pre><code>from panther.app import API\nfrom panther.request import Request\n\nfrom app.serializers import BookSerializer\nfrom app.models import Book\n\n\n@API(input_model=BookSerializer)\nasync def book_api(request: Request):\n    body: BookSerializer = request.data\n\n    Book.insert_one(\n        name=body.name,\n        author=body.author,\n        pages_count=body.pages_count,\n    )\n    ...\n</code></pre> </li> <li> <p>But we only want this happens in <code>post</code> requests, so we add this <code>condition</code>:</p> <pre><code>from panther.app import API\nfrom panther.request import Request\n\nfrom app.serializers import BookSerializer\nfrom app.models import Book\n\n\n@API(input_model=BookSerializer)\nasync def book_api(request: Request):\n    if request.method == 'POST':\n        body: BookSerializer = request.data\n\n        Book.create(\n            name=body.name,\n            author=body.author,\n            pages_count=body.pages_count,\n        )\n        ...\n</code></pre> </li> <li> <p>And finally we return <code>201 Created</code> status_code as response of <code>post</code> and <code>501 Not Implemented</code> for other methods:     <pre><code>from panther import status\nfrom panther.app import API\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.serializers import BookSerializer\nfrom app.models import Book\n\n\n@API(input_model=BookSerializer)\nasync def book_api(request: Request):\n    if request.method == 'POST':\n        body: BookSerializer = request.data\n\n        book: Book = Book.create(\n            name=body.name,\n            author=body.author,\n            pages_count=body.pages_count,\n        )\n        return Response(data=book, status_code=status.HTTP_201_CREATED)\n\n    return Response(status_code=status.HTTP_501_NOT_IMPLEMENTED)\n</code></pre></p> </li> </ol> <p>The response.data can be <code>Instance of Models</code>, <code>dict</code>, <code>str</code>, <code>tuple</code>, <code>list</code>, <code>str</code> or <code>None</code></p> <p>Panther will return <code>None</code> if you don't return anything as response.</p>"},{"location":"function_first_crud/#api-list-of-books","title":"API - List of Books","text":"<p>We just need to add another condition on <code>GET</code> methods and return the lists of books:</p> <pre><code>from panther import status\nfrom panther.app import API\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.serializers import BookSerializer\nfrom app.models import Book\n\n\n@API(input_model=BookSerializer)\nasync def book_api(request: Request):\n    if request.method == 'POST':\n        ...\n\n    elif request.method == 'GET':\n        books: list[Book] = Book.find()\n        return Response(data=books, status_code=status.HTTP_200_OK)\n\n    return Response(status_code=status.HTTP_501_NOT_IMPLEMENTED)\n</code></pre> <p>Panther validate input with <code>input_model</code>, only in <code>POST</code>, <code>PUT</code>, <code>PATCH</code> methods.</p>"},{"location":"function_first_crud/#filter-response-fields","title":"Filter Response Fields","text":"<p>Assume we don't want to return field <code>author</code> in response:</p> <ol> <li> <p>Create new serializer in <code>app/serializers.py</code>:</p> <pre><code>from pydantic import BaseModel\n\n\nclass BookOutputSerializer(BaseModel):\n    name: str\n    pages_count: int\n</code></pre> </li> <li> <p>Add the <code>BookOutputSerializer</code> as <code>output_model</code> to your <code>API()</code> <pre><code>from panther import status\nfrom panther.app import API\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.serializers import BookSerializer, BookOutputSerializer\nfrom app.models import Book\n\n\n@API(input_model=BookSerializer, output_model=BookOutputSerializer)\nasync def book_api(request: Request):\n    if request.method == 'POST':\n        ...\n\n    elif request.method == 'GET':\n        books: list[Book] = Book.find()\n        return Response(data=books, status_code=status.HTTP_200_OK)\n\n    return Response(status_code=status.HTTP_501_NOT_IMPLEMENTED)\n</code></pre></p> </li> </ol> <p>Panther use the <code>output_model</code>, in all methods.</p>"},{"location":"function_first_crud/#cache-the-response","title":"Cache The Response","text":"<p>For caching the response, we should add <code>cache=True</code> in <code>API()</code>. And it will return the cached response every time till <code>cache_exp_time</code></p> <p>For setting a custom expiration time for API we need to add <code>cache_exp_time</code> to <code>API()</code>:</p> <pre><code>from datetime import timedelta\n\nfrom panther import status\nfrom panther.app import API\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.serializers import BookSerializer, BookOutputSerializer\nfrom app.models import Book\n\n\n@API(input_model=BookSerializer, output_model=BookOutputSerializer, cache=True, cache_exp_time=timedelta(seconds=10))\nasync def book_api(request: Request):\n    if request.method == 'POST':\n        ...\n\n    elif request.method == 'GET':\n        books: list[Book] = Book.find()\n        return Response(data=books, status_code=status.HTTP_200_OK)\n\n    return Response(status_code=status.HTTP_501_NOT_IMPLEMENTED)\n</code></pre> <p>Panther is going to use the <code>DEFAULT_CACHE_EXP</code> from <code>core/configs.py</code> if <code>cache_exp_time</code> has not been set.</p>"},{"location":"function_first_crud/#throttle-the-request","title":"Throttle The Request","text":"<p>For setting rate limit for requests, we can add throttling to <code>API()</code>, it should be the instance of <code>panther.throttling.Throttling</code>, something like below (in the below example user can't request more than 10 times in a minutes):</p> <pre><code>from datetime import timedelta\n\nfrom panther import status\nfrom panther.app import API\nfrom panther.request import Request\nfrom panther.response import Response\nfrom panther.throttling import Throttling\n\nfrom app.serializers import BookSerializer, BookOutputSerializer\nfrom app.models import Book\n\n\n@API(\n    input_model=BookSerializer, \n    output_model=BookOutputSerializer, \n    cache=True, \n    cache_exp_time=timedelta(seconds=10),\n    throttling=Throttling(rate=10, duration=timedelta(minutes=1))\n)\nasync def book_api(request: Request):\n    if request.method == 'POST':\n        ...\n\n    elif request.method == 'GET':\n        books: list[Book] = Book.find()\n        return Response(data=books, status_code=status.HTTP_200_OK)\n\n    return Response(status_code=status.HTTP_501_NOT_IMPLEMENTED)\n</code></pre>"},{"location":"function_first_crud/#api-retrieve-a-book","title":"API - Retrieve a Book","text":"<p>For <code>retrieve</code>, <code>update</code> and <code>delete</code> API, we are going to</p> <ol> <li> <p>Create another api named <code>single_book_api</code> in <code>app/apis.py</code>:</p> <pre><code>from panther.app import API\nfrom panther.request import Request\n\n\n@API()\nasync def single_book_api(request: Request):\n    ...\n</code></pre> </li> <li> <p>Add it in <code>app/urls.py</code>:</p> <pre><code>from app.apis import book_api, single_book_api\n\n\nurls = {\n    'book/': book_api,\n    'book/&lt;book_id&gt;/': single_book_api,\n}\n</code></pre> </li> </ol> <p>You should write the Path Variable in <code>&lt;</code> and <code>&gt;</code></p> <p>You should have the parameter with the same name of <code>path variable</code> in you <code>api</code> with normal <code>type hints</code></p> <p>Panther will convert type of the <code>path variable</code> to your parameter type, then pass it</p> <ol> <li> <p>Complete the api:</p> <pre><code>from panther import status\nfrom panther.app import API\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.models import Book\n\n\n@API()\nasync def single_book_api(request: Request, book_id: int):\n    if request.method == 'GET':\n        if book := Book.find_one(id=book_id):\n            return Response(data=book, status_code=status.HTTP_200_OK)\n        else:\n            return Response(status_code=status.HTTP_404_NOT_FOUND)\n</code></pre> </li> </ol>"},{"location":"function_first_crud/#api-update-a-book","title":"API - Update a Book","text":"<ul> <li> <p>We can update in several ways:</p> <ol> <li> <p>Update a document</p> <pre><code>from panther import status\nfrom panther.app import API\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.models import Book\nfrom app.serializers import BookSerializer\n\n\n@API(input_model=BookSerializer)\nasync def single_book_api(request: Request, book_id: int):\n    body: BookSerializer = request.data\n    if request.method == 'GET':\n        ...\n    elif request.method == 'PUT':\n        book: Book = Book.find_one(id=book_id)\n        book.update(\n            name=body.name, \n            author=body.author, \n            pages_count=body.pages_count\n            )\n        return Response(status_code=status.HTTP_202_ACCEPTED)\n</code></pre> </li> <li> <p>Update with <code>update_one</code> query</p> <pre><code>from panther import status\nfrom panther.app import API\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.models import Book\nfrom app.serializers import BookSerializer\n\n\n@API(input_model=BookSerializer)\nasync def single_book_api(request: Request, book_id: int):\n    if request.method == 'GET':\n        ...\n    elif request.method == 'PUT':\n        is_updated: bool = Book.update_one({'id': book_id}, request.data.dict())\n        data = {'is_updated': is_updated}\n        return Response(data=data, status_code=status.HTTP_202_ACCEPTED)\n</code></pre> </li> <li> <p>Update with <code>update_many</code> query</p> <pre><code>from panther import status\nfrom panther.app import API\nfrom panther.request import Request\nfrom panther.response import Response\n\nfrom app.models import Book\nfrom app.serializers import BookSerializer\n\n\n@API(input_model=BookSerializer)\nasync def single_book_api(request: Request, book_id: int):\n    if request.method == 'GET':\n        ...\n    elif request.method == 'PUT':\n        updated_count: int = Book.update_many({'id': book_id}, request.data.dict())\n        data = {'updated_count': updated_count}\n        return Response(data=data, status_code=status.HTTP_202_ACCEPTED)\n</code></pre> </li> </ol> <p>You can handle the PATCH the same way as PUT</p> </li> </ul>"},{"location":"function_first_crud/#api-delete-a-book","title":"API - Delete a Book","text":"<ul> <li> <p>We can delete in several ways too:</p> <ol> <li> <p>Delete a document</p> <p><pre><code>    from panther import status\n    from panther.app import API\n    from panther.request import Request\n    from panther.response import Response\n\n    from app.models import Book\n\n\n    @API()\n    async def single_book_api(request: Request, book_id: int):\n        if request.method == 'GET':\n            ...\n        elif request.method == 'PUT':\n            ...\n        elif request.method == 'DELETE':\n            is_deleted: bool = Book.delete_one(id=book_id)\n            if is_deleted:\n                return Response(status_code=status.HTTP_204_NO_CONTENT)\n            else:\n                return Response(status_code=status.HTTP_400_BAD_REQUEST)\n</code></pre>     2. Delete with <code>delete_one</code> query</p> <pre><code>    from panther import status\n    from panther.app import API\n    from panther.request import Request\n    from panther.response import Response\n\n    from app.models import Book\n\n\n    @API()\n    async def single_book_api(request: Request, book_id: int):\n        if request.method == 'GET':\n            ...\n        elif request.method == 'PUT':\n            ...\n        elif request.method == 'DELETE':\n            is_deleted: bool = Book.delete_one(id=book_id)\n            return Response(status_code=status.HTTP_204_NO_CONTENT)\n</code></pre> </li> <li> <p>Delete with <code>delete_many</code> query</p> <pre><code>    from panther import status\n    from panther.app import API\n    from panther.request import Request\n    from panther.response import Response\n\n    from app.models import Book\n\n\n    @API()\n    async def single_book_api(request: Request, book_id: int):\n        if request.method == 'GET':\n            ...\n        elif request.method == 'PUT':\n            ...\n        elif request.method == 'DELETE':\n            deleted_count: int = Book.delete_many(id=book_id)\n            return Response(status_code=status.HTTP_204_NO_CONTENT)\n</code></pre> </li> </ol> </li> </ul>"},{"location":"log_queries/","title":"Log Queries","text":"<p>Variable: <code>LOG_QUERIES</code> </p> <p>Type: <code>bool</code> </p> <p>Default: <code>False</code></p> <p>Panther has a <code>log_query</code> decorator on queries that process the <code>perf_time</code> of every query</p> <p>Make sure it is <code>False</code> on production for better performance</p>"},{"location":"log_queries/#log-example","title":"Log Example:","text":"<pre><code>INFO:     | 2023-03-19 20:37:27 | Query --&gt;  User.insert_one() --&gt; 1.6 ms\n</code></pre>"},{"location":"log_queries/#the-log-query-decorator-is-something-like-this","title":"The Log Query Decorator Is Something Like This","text":"<pre><code>def log_query(func):\n    def log(*args, **kwargs):\n        if config['log_queries'] is False:\n            return func(*args, **kwargs)\n\n        start = perf_counter()\n        response = func(*args, **kwargs)\n        end = perf_counter()\n        class_name = ...\n        query_logger.info(f'Query --&gt;  {class_name}.{func.__name__}() --&gt; {(end - start) * 1_000:.2} ms')\n        return response\n    return log\n</code></pre>"},{"location":"middlewares/","title":"Middlewares","text":"<p>Variable: <code>MIDDLEWARES</code> </p> <p>Type: <code>list</code> </p> <p>Default: <code>[]</code></p> <p>Panther has several <code>built-in</code> middleware:</p> <ul> <li> <p>Database Middleware</p> </li> <li> <p>Redis Middleware</p> </li> </ul> <p>And you can write your own custom middlewares too</p>"},{"location":"middlewares/#structure-of-middlewares","title":"Structure of middlewares","text":"<p><code>MIDDLEWARES</code> itself is a <code>list</code> of <code>tuples</code> which each <code>tuple</code> is like below:</p> <p>(<code>Address of Middleware Class</code>, <code>kwargs as dict</code>)</p>"},{"location":"middlewares/#database-middleware","title":"Database Middleware","text":"<p>This middleware will create a <code>db</code> connection that uses in <code>ODM</code> or you can use it manually from: <pre><code>from panther.db.connection import db\n</code></pre></p> <p>We only support 2 database: <code>PantherDB</code> &amp; <code>MongoDB</code></p> <ul> <li>Address of Middleware: <code>panther.middlewares.db.Middleware</code></li> <li> <p>kwargs:</p> <ul> <li> <p><code>{'url': f'pantherdb://{BASE_DIR}/{DB_NAME}.pdb'}</code></p> </li> <li> <p><code>{'url': f'mongodb://{DB_HOST}:27017/{DB_NAME}'}</code></p> </li> </ul> </li> <li> <p>Example of <code>PantherDB</code> (<code>Built-in Local Storage</code>):   <pre><code>MIDDLEWARES = [\n    ('panther.middlewares.db.Middleware', {'url': f'pantherdb://{BASE_DIR}/{DB_NAME}.pdb'}),\n]\n</code></pre></p> </li> <li>Example of <code>MongoDB</code>:   <pre><code>MIDDLEWARES = [\n    ('panther.middlewares.db.Middleware', {'url': f'mongodb://{DB_HOST}:27017/{DB_NAME}'}),\n]\n</code></pre></li> </ul>"},{"location":"middlewares/#redis-middleware","title":"Redis Middleware","text":"<ul> <li>Address of Middleware: <code>panther.middlewares.redis.Middleware</code></li> <li> <p>kwargs:      <pre><code>{'host': '127.0.0.1', 'port': 6379, ...}\n</code></pre></p> </li> <li> <p>Example   <pre><code>MIDDLEWARES = [\n    ('panther.middlewares.redis.Middleware', {'host': '127.0.0.1', 'port': 6379}),\n]\n</code></pre></p> </li> </ul>"},{"location":"middlewares/#custom-middleware","title":"Custom Middleware","text":"<p>Write a <code>class</code> and inherit from <pre><code>from panther.middlewares.base import BaseMiddleware\n</code></pre></p> <p>Then you can write your custom <code>before()</code> and <code>after()</code> methods</p> <ul> <li>The <code>methods</code> should be <code>async</code></li> <li><code>before()</code> should have <code>request</code> parameter</li> <li><code>after()</code> should have <code>response</code> parameter</li> <li>overwriting the <code>before()</code> and <code>after()</code> are optional</li> <li>The <code>methods</code> can get <code>kwargs</code> from their <code>__init__</code></li> </ul>"},{"location":"middlewares/#custom-middleware-example","title":"Custom Middleware Example","text":"<p>core/middlewares.py <pre><code>from panther.request import Request\nfrom panther.response import Response\nfrom panther.middlewares.base import BaseMiddleware\n\n\nclass CustomMiddleware(BaseMiddleware):\n\n    def __init__(self, something):\n        self.something = something\n\n    async def before(self, request: Request) -&gt; Request:\n        print('Before Endpoint', self.something)\n        return request\n\n    async def after(self, response: Response) -&gt; Response:\n        print('After Endpoint', self.something)\n        return response\n</code></pre> core/configs.py <pre><code>  MIDDLEWARES = [\n      ('core.middlewares.CustomMiddleware', {'something': 'hello-world'}),\n  ]\n</code></pre></p>"},{"location":"monitoring/","title":"Monitoring","text":"<p>Variable: <code>MONITORING</code> </p> <p>Type: <code>bool</code> </p> <p>Default: <code>False</code></p> <p>Panther has a <code>Monitoring</code> middleware that process the <code>perf_time</code> of every request</p> <p>It will create a <code>monitoring.log</code> file and log the records</p> <p>Then you can watch them live with: <code>panther monitor</code></p>"},{"location":"monitoring/#the-monitoring-middleware","title":"The Monitoring Middleware:","text":"<pre><code>    async def before(self, request: Request) -&gt; Request:\n        ip, port = request.client\n        self.log = f'{request.method} | {request.path} | {ip}:{port}'\n        self.start_time = perf_counter()\n        return request\n</code></pre> <pre><code>    async def after(self, status_code: int):\n        response_time = (perf_counter() - self.start_time) * 1_000\n        monitoring_logger.info(f'{self.log} | {response_time: .3} ms | {status_code}')\n</code></pre>"},{"location":"panther_odm/","title":"Panther ODM","text":""},{"location":"panther_odm/#find_one","title":"find_one","text":"<ul> <li>Find the first match document  </li> <li> <p>Example:  </p> <pre><code>user: User = User.find_one(id=1, name='Ali')  \n\nuser: User = User.find_one({'id': 1, 'name': 'Ali'})  \n\nuser: User = User.find_one({'id': 1}, name='Ali')  \n</code></pre> </li> </ul>"},{"location":"panther_odm/#find","title":"find","text":"<ul> <li>Find all the matches documents  </li> <li> <p>Example:  </p> <pre><code>users: list[User] = User.find(id=1, name='Ali')  \n\nusers: list[User] = User.find({'id': 1, 'name': 'Ali'})  \n\nusers: list[User] = User.find({'id': 1}, name='Ali')  \n</code></pre> </li> </ul>"},{"location":"panther_odm/#insert_one","title":"insert_one","text":"<ul> <li>Insert only one document into database  </li> <li> <p>Example:  </p> <pre><code>User.insert_one(id=1, name='Ali')  \n\nUser.insert_one({'id': 1, 'name': 'Ali'})  \n\nUser.insert_one({'id': 1}, name='Ali')  \n</code></pre> </li> </ul>"},{"location":"panther_odm/#delete","title":"delete","text":"<ul> <li>Delete the selected document from database</li> <li> <p>Example:  </p> <pre><code>user: User = User.find_one(name='Ali')\nuser.delete()\n</code></pre> </li> </ul>"},{"location":"panther_odm/#delete_one","title":"delete_one","text":"<ul> <li>Delete the first match document  from database</li> <li> <p>Example:  </p> <pre><code>is_deleted: bool = User.delete_one(id=1, name='Ali')\n</code></pre> </li> </ul>"},{"location":"panther_odm/#delete_many","title":"delete_many","text":"<ul> <li>Delete all the matches document  from database</li> <li> <p>Example:  </p> <pre><code>deleted_count: int = User.delete_many(id=1, name='Ali')\n\ndeleted_count: int = User.delete_many({'id': 1}, name='Ali')\n\ndeleted_count: int = User.delete_many({'id': 1, 'name': 'Ali'})\n</code></pre> </li> </ul>"},{"location":"panther_odm/#update","title":"update","text":"<ul> <li>Update the selected document in database</li> <li> <p>Example:  </p> <pre><code>user = User.find_one(name='Ali')\nuser.update(name='Saba')\n</code></pre> </li> </ul>"},{"location":"panther_odm/#update_one","title":"update_one","text":"<ul> <li>Update the first match document in database</li> <li>You should filter with <code>dictionary</code> as <code>first parameter</code>  and pass the fields you want to update as <code>kwargs</code> or another <code>dictionary</code> as <code>second parameter</code></li> <li> <p>Example:  </p> <pre><code>is_updated: bool = User.update_one({'id': 1, 'name': 'Ali'}, name='Saba', age=26)\n\nis_updated: bool = User.update_one({'id': 1, 'name': 'Ali'}, {'name': 'Saba', 'age': 26})\n\nis_updated: bool = User.update_one({'id': 1, 'name': 'Ali'}, {'name': 'Saba'}, age=26)\n</code></pre> </li> </ul>"},{"location":"panther_odm/#update_many","title":"update_many","text":"<ul> <li>Update all the matches document in database</li> <li>You should filter with <code>dictionary</code> as <code>first parameter</code>  and pass the fields you want to update as <code>kwargs</code> or another <code>dictionary</code> as <code>second parameter</code></li> <li> <p>Example:  </p> <pre><code>updated_count: int = User.update_many({'name': 'Ali'}, name='Saba', age=26)\n\nupdated_count: int = User.update_many({'name': 'Ali'}, {'name': 'Saba', 'age': 26})\n\nupdated_count: int = User.update_many({'name': 'Ali'}, {'name': 'Saba'}, age=26)\n</code></pre> </li> </ul>"},{"location":"panther_odm/#last","title":"last","text":"<ul> <li>Find the last match document</li> <li> <p>Example:  </p> <pre><code>user: User = User.last(name='Ali', age=26)  \n\nuser: User = User.last({'name': 'Ali', 'age': 26})  \n\nuser: User = User.last({'name': 'Ali'}, age=26)  \n</code></pre> </li> </ul>"},{"location":"panther_odm/#count","title":"count","text":"<ul> <li>Count of the matches documents</li> <li> <p>Example:  </p> <pre><code>users_count: int = User.count(name='Ali')\n</code></pre> </li> </ul>"},{"location":"panther_odm/#find_or_insert","title":"find_or_insert","text":"<ul> <li>Find the match document or Create one if none exists</li> <li> <p>Example:  </p> <pre><code>user: User = User.find_or_insert(name='Ali')\n</code></pre> </li> </ul>"},{"location":"release_notes/","title":"Release Notes","text":""},{"location":"release_notes/#240","title":"2.4.0","text":"<ul> <li>Handle Complex Multipart-FormData</li> </ul>"},{"location":"release_notes/#233","title":"2.3.3","text":"<ul> <li>Fix a bug in response headers</li> </ul>"},{"location":"release_notes/#232","title":"2.3.2","text":"<ul> <li>Fix a bug in Template</li> </ul>"},{"location":"release_notes/#231","title":"2.3.1","text":"<ul> <li>Handle PlainTextResponse</li> <li>Handle Custom Header in Response</li> <li>Change the way of accepting 'URLs' in configs (relative -&gt; dotted)</li> <li>Fix an issue in collect_all_models()</li> </ul>"},{"location":"release_notes/#230","title":"2.3.0","text":"<ul> <li>Handle HTMLResponse</li> </ul>"},{"location":"release_notes/#220","title":"2.2.0","text":"<ul> <li>Supporting File </li> </ul>"},{"location":"release_notes/#216","title":"2.1.6","text":"<ul> <li>Fix validation errors on nested inputs</li> </ul>"},{"location":"release_notes/#215","title":"2.1.5","text":"<ul> <li>Fix response of nested Models in _panel//"},{"location":"release_notes/#214","title":"2.1.4","text":"<ul> <li>Add access-control-allow-origin to response header</li> </ul>"},{"location":"release_notes/#213","title":"2.1.3","text":"<ul> <li>Upgrade greenlet version in requirements for python3.12</li> </ul>"},{"location":"release_notes/#212","title":"2.1.2","text":"<ul> <li>Add ruff.toml</li> <li>Add Coverage to workflows</li> <li>Fix a bug for running in Windows</li> </ul>"},{"location":"release_notes/#211","title":"2.1.1","text":"<ul> <li>Fix a bug in main.py imports</li> </ul>"},{"location":"release_notes/#210","title":"2.1.0","text":"<ul> <li>Support Sync APIs</li> </ul>"},{"location":"release_notes/#200","title":"2.0.0","text":"<ul> <li>Supporting class-base APIs</li> </ul>"},{"location":"release_notes/#1720","title":"1.7.20","text":"<ul> <li>Fix an issue in find_endpoint()</li> </ul>"},{"location":"release_notes/#1719","title":"1.7.19","text":"<ul> <li>Fix an issue in routing</li> <li>Fix an issue on return complex dict Response</li> </ul>"},{"location":"release_notes/#1718","title":"1.7.18","text":"<ul> <li>Remove uvloop from requirements for now (we had issue in windows)</li> </ul>"},{"location":"release_notes/#1716","title":"1.7.16","text":"<ul> <li>Trying to fix requirements for windows</li> <li>Minor improvement in BaseMongoDBQuery</li> </ul>"},{"location":"release_notes/#1715","title":"1.7.15","text":"<ul> <li>Fix an issue in handling form-data</li> </ul>"},{"location":"release_notes/#1714","title":"1.7.14","text":"<ul> <li>Add Cache and Throttling doc to FirstCrud</li> <li>Fix an issue in BasePantherDBQuery._merge() </li> </ul>"},{"location":"release_notes/#1713","title":"1.7.13","text":"<ul> <li>Hotfix validation of _id in Model()</li> </ul>"},{"location":"release_notes/#1712","title":"1.7.12","text":"<ul> <li>Fix a bug in routing</li> </ul>"},{"location":"release_notes/#1711","title":"1.7.11","text":"<ul> <li>Fix an issue in template</li> </ul>"},{"location":"release_notes/#1710","title":"1.7.10","text":"<ul> <li>Fix a bug in <code>collect_urls</code> and rename it to <code>flatten_urls</code></li> <li>Add General Tests</li> <li>Compatible with python3.10 (Not Tested)</li> <li>Working on docs</li> </ul>"},{"location":"release_notes/#179","title":"1.7.9","text":"<ul> <li>Working on doc</li> </ul>"},{"location":"release_notes/#178","title":"1.7.8","text":"<ul> <li>Fix a bug</li> <li>Update docs</li> </ul>"},{"location":"release_notes/#178_1","title":"1.7.8","text":"<ul> <li>Fix a bug</li> <li>Update docs</li> </ul>"},{"location":"release_notes/#177","title":"1.7.7","text":"<ul> <li>Fix a bug</li> </ul>"},{"location":"release_notes/#175","title":"1.7.5","text":"<ul> <li>Change the way of raising exception in JWTAuthentication</li> <li>Rename User model to BaseUser</li> <li>Fix template</li> </ul>"},{"location":"release_notes/#174","title":"1.7.4","text":"<ul> <li>Crop Logo</li> </ul>"},{"location":"release_notes/#173","title":"1.7.3","text":"<ul> <li>Add Throttling Doc</li> <li>Fix some issue in Doc</li> </ul>"},{"location":"release_notes/#172","title":"1.7.2","text":"<ul> <li>Add Throttling to example</li> <li>Customize install_requires in setup.py</li> <li>Improve monitoring cli command</li> </ul>"},{"location":"release_notes/#171","title":"1.7.1","text":"<ul> <li>Rename db BaseModel to Model </li> <li>Add more docs</li> </ul>"},{"location":"release_notes/#170","title":"1.7.0","text":"<ul> <li>Add Throttling</li> </ul>"},{"location":"release_notes/#161","title":"1.6.1","text":"<ul> <li>Add AdminPermission</li> </ul>"},{"location":"release_notes/#160","title":"1.6.0","text":"<ul> <li>Handle Permissions</li> </ul>"},{"location":"release_notes/#152","title":"1.5.2","text":"<ul> <li>Improve Response data serialization</li> <li>Fix a bug in JWTAuthentication</li> </ul>"},{"location":"release_notes/#151","title":"1.5.1","text":"<ul> <li>Fix error messages</li> </ul>"},{"location":"release_notes/#150","title":"1.5.0","text":"<ul> <li>Refactor Mongodb ODM</li> <li>Minor Improvement</li> </ul>"},{"location":"release_notes/#140","title":"1.4.0","text":"<ul> <li>Add QUERY_LOG</li> </ul>"},{"location":"release_notes/#132","title":"1.3.2","text":"<ul> <li>Add Uvicorn to the setup requirements</li> <li>Update Readme</li> </ul>"},{"location":"release_notes/#131","title":"1.3.1","text":"<ul> <li>Fix a bug in project creation template</li> <li>Fix a bug in caching</li> </ul>"},{"location":"release_notes/#130","title":"1.3.0","text":"<ul> <li>Add PantherDB to Panther</li> <li>Remove tinydb</li> </ul>"},{"location":"release_notes/#127","title":"1.2.7","text":"<ul> <li>Fix a bug while using tinydb</li> </ul>"},{"location":"release_notes/#126","title":"1.2.6","text":"<ul> <li>Update Readme</li> </ul>"},{"location":"release_notes/#125","title":"1.2.5","text":"<ul> <li>Fix install_requires issue</li> <li>Add benchmarks to docs</li> </ul>"},{"location":"release_notes/#124","title":"1.2.4","text":"<ul> <li>Remove Uvicorn From install_requires</li> <li>Working on Docs</li> </ul>"},{"location":"release_notes/#123","title":"1.2.3","text":"<ul> <li>Fix URL Routing</li> </ul>"},{"location":"release_notes/#121","title":"1.2.1","text":"<ul> <li>Path Variable Handled Successfully</li> </ul>"},{"location":"release_notes/#120","title":"1.2.0","text":"<ul> <li>Read multipart/form-data with Regex</li> </ul>"},{"location":"release_notes/#119","title":"1.1.9","text":"<ul> <li>Refactoring code style with ruff </li> <li>Add asyncio.TaskGroup() </li> </ul>"},{"location":"release_notes/#118","title":"1.1.8","text":"<ul> <li>Refactor cli run command </li> </ul>"},{"location":"release_notes/#117","title":"1.1.7","text":"<ul> <li>Add benchmark pictures to doc </li> </ul>"},{"location":"release_notes/#115","title":"1.1.5","text":"<ul> <li>Clean Readme</li> <li>Clean main.py </li> </ul>"},{"location":"release_notes/#114","title":"1.1.4","text":"<ul> <li>Update Readme </li> </ul>"},{"location":"release_notes/#113","title":"1.1.3","text":"<ul> <li>Fix a query in TinyDB </li> </ul>"},{"location":"release_notes/#112","title":"1.1.2","text":"<ul> <li>Add delete_many query to TinyDB </li> </ul>"},{"location":"release_notes/#111","title":"1.1.1","text":"<ul> <li>Add TinyDB</li> </ul>"},{"location":"release_notes/#110","title":"1.1.0","text":"<ul> <li>Debug the Template </li> </ul>"},{"location":"release_notes/#109","title":"1.0.9","text":"<ul> <li>Handle string exceptions (raise them as detail: error) </li> <li>Little debug on MongoQueries</li> </ul>"},{"location":"release_notes/#107","title":"1.0.7","text":"<ul> <li>Working on queries</li> <li>Fix a bug in query methods </li> </ul>"},{"location":"release_notes/#106","title":"1.0.6","text":"<ul> <li>Update the Template </li> </ul>"},{"location":"release_notes/#104","title":"1.0.4","text":"<ul> <li>Debug template </li> </ul>"},{"location":"release_notes/#102","title":"1.0.2","text":"<ul> <li>Add global config</li> <li>Split the BaseModels</li> <li>Worked on MongoQuery</li> <li>Set Mongo as default database while creating project </li> <li>Minor Improvement</li> </ul>"},{"location":"release_notes/#101","title":"1.0.1","text":"<ul> <li>Add alembic To Project </li> </ul>"},{"location":"release_notes/#10","title":"1.0.","text":"<ul> <li>Refactor &amp; Complete the CLI </li> </ul>"},{"location":"release_notes/#019","title":"0.1.9","text":"<ul> <li>Fix install_requires</li> </ul>"},{"location":"release_notes/#018","title":"0.1.8","text":"<ul> <li>Update Readme</li> </ul>"},{"location":"release_notes/#017","title":"0.1.7","text":"<ul> <li>Update Readme</li> </ul>"},{"location":"release_notes/#016","title":"0.1.6","text":"<ul> <li>Handle Most Types as Data in Response</li> </ul>"},{"location":"release_notes/#014","title":"0.1.4","text":"<ul> <li>Working On DB Connection </li> </ul>"},{"location":"release_notes/#001","title":"0.0.1","text":"<ul> <li>Make It Ready For PyPI </li> </ul>"},{"location":"throttling/","title":"Throttling","text":"<p>Variable: <code>THROTTLING</code> </p> <p>Type: <code>str</code> </p> <p>In Panther, you can use <code>Throttling</code> for all APIs at once in <code>core/configs.py</code> or per API in its <code>@API</code> decorator</p> <p>The <code>Throttling</code> class has 2 field <code>rate</code> &amp; <code>duration</code></p> <p>rate: int</p> <p>duration: datetime.timedelta</p> <p>It will return <code>Too Many Request</code> <code>status_code: 429</code> if user try to request in the <code>duration</code> more than <code>rate</code> And user will baned( get<code>Too Many Request</code> ) for <code>duration</code></p> <p>And keep that in mind if you have <code>Throttling</code> in <code>@API()</code>, the <code>Throttling</code> of <code>core/configs.py</code> will be ignored.</p>"},{"location":"throttling/#for-all-apis-example","title":"For All APIs Example:","text":"<p>core/configs.py <pre><code>from datetime import timedelta\n\nfrom panther.throttling import Throttling\n\n\n# User only can request 5 times in every minute\nTHROTTLING = Throttling(rate=5, duration=timedelta(minutes=1))\n</code></pre></p>"},{"location":"throttling/#for-single-api-example","title":"For Single API Example:","text":"<p>apis.py <pre><code>from datetime import timedelta\n\nfrom panther.throttling import Throttling\nfrom panther.app import API\n\n\n# User only can request 5 times in every minute\nInfoThrottling = Throttling(rate=5, duration=timedelta(minutes=1))\n\n\n@API(throttling=InfoThrottling)\nasync def info_api():\n    pass\n</code></pre></p>"},{"location":"todos/","title":"TODOs","text":""},{"location":"todos/#base","title":"Base","text":"<ul> <li>\u2705 Start with Uvicorn </li> <li>\u2705 Fix URL Routing </li> <li>\u2705 Read Configs </li> <li>\u2705 Handle Exceptions </li> <li>\u2705 Add Custom Logger </li> <li>\u2705 Request Class </li> <li>\u2705 Response Class </li> <li>\u2705 Validate Input </li> <li>\u2705 Custom Output Model </li> <li>\u2705 Log Queries</li> <li>\u2705 Add Package Requirements</li> <li>\u2705 Custom Logging</li> <li>\u2705 Caching</li> <li>\u2705 Handle Path Variable</li> <li>\u2705 Handle Simple Multipart-FormData</li> <li>\u2705 Handle Throttling</li> <li>\u2705 Handle ClassBase APIs</li> <li>\u2705 Handle File </li> <li>\u2705 Handle Complex Multipart-FormData</li> <li>\u2610 Handle Cookie</li> <li>\u2610 Handle WS </li> <li>\u2610 Handle GraphQL</li> <li>\u2610 Handle Testing</li> <li>\u2610 Generate Swagger For APIs</li> </ul>"},{"location":"todos/#database","title":"Database:","text":"<ul> <li>\u2705 Structure Of DB Connection</li> <li>\u2705 PantherDB Connection</li> <li>\u2705 MongoDB Connection</li> <li>\u2705 Create Custom BaseModel For All Type Of Databases</li> <li>\u2705 Set PantherDB As Default</li> </ul>"},{"location":"todos/#custom-odm","title":"Custom ODM","text":"<ul> <li>\u2705 Find One</li> <li>\u2705 Find </li> <li>\u2705 Last</li> <li>\u2705 Count</li> <li>\u2705 Insert One </li> <li>\u2705 Insert Many </li> <li>\u2705 Delete One</li> <li>\u2705 Delete Many</li> <li>\u2705 Delete Itself</li> <li>\u2705 Update One</li> <li>\u2705 Update Many</li> <li>\u2705 Update Itself</li> <li>\u2705 Find or Insert</li> <li>\u2705 Save</li> <li>\u2610 Find or Raise</li> <li>\u2610 Find with Pagination</li> <li>\u2610 Aggregation</li> <li>\u2610 Complex Pipelines</li> <li>\u2610 ...</li> </ul>"},{"location":"todos/#middleware","title":"Middleware","text":"<ul> <li>\u2705 Add Middlewares To Structure</li> <li>\u2705 Create BaseMiddleware</li> <li>\u2705 Pass Custom Parameters To Middlewares</li> <li>\u2705 Handle Custom Middlewares</li> </ul>"},{"location":"todos/#authentication","title":"Authentication","text":"<ul> <li>\u2705 JWT Authentication</li> <li>\u2705 Separate Auth For Every API</li> <li>\u2705 Handle Permissions </li> <li>\u2610 Token Storage Authentication</li> <li>\u2610 Cookie Authentication</li> <li>\u2610 Query Param Authentication</li> <li>\u2610 Store JWT After Logout In Redis/ Memory</li> </ul>"},{"location":"todos/#cache","title":"Cache","text":"<ul> <li>\u2705 Add Redis To Structure</li> <li>\u2705 Create Cache Decorator</li> <li>\u2705 Handle In Memory Caching </li> <li>\u2705 Handle In Redis Caching </li> <li>\u2610 Write Async LRU_Caching With TTL (Replace it with in memory ...)</li> </ul>"},{"location":"todos/#cli","title":"CLI","text":"<ul> <li>\u2705 Create Project </li> <li>\u2705 Run Project </li> <li>\u2705 Create Project with Options</li> <li>\u2705 Monitoring With Textual</li> <li>\u2705 Monitor Requests, Response &amp; Time</li> </ul>"},{"location":"todos/#documentation","title":"Documentation","text":"<ul> <li>\u2705 Create MkDocs For Project </li> <li>\u2705 Benchmarks</li> <li>\u2705 Release Notes</li> <li>\u2705 Features</li> <li>\u2610 Complete The MkDoc</li> </ul>"},{"location":"todos/#tests","title":"Tests","text":"<ul> <li>\u2705 Start Writing Tests For Panther </li> <li>\u2610 Test Client</li> </ul>"},{"location":"urls/","title":"URLs","text":"<p>Variable: <code>URLs</code> </p> <p>Type: <code>str</code> </p> <p>Required: <code>True</code></p> <ul> <li><code>URLs</code> should point to your root <code>urls</code> with dotted address (<code>path.module.url_dict</code>), and it should be <code>dict</code>.</li> <li> <p><code>key</code> of url_routing dict is <code>path</code> &amp; value is <code>endpoint</code> or another <code>dict</code></p> </li> <li> </li> </ul>"},{"location":"urls/#path-variables-are-handled-like-below","title":"Path Variables are handled like below:","text":"<ul> <li>&lt;<code>variable_name</code>&gt;</li> <li>Example: <code>user/&lt;user_id&gt;/blog/&lt;title&gt;/</code></li> <li>The <code>endpoint</code> should have parameters with those names too</li> <li>Example: <code>async def profile_api(user_id: int, title: str):</code></li> </ul>"},{"location":"urls/#example","title":"Example","text":"<ul> <li>core/configs.py     <pre><code>`URLs = 'core.urls.url_routing`\n</code></pre></li> <li>core/urls.py     <pre><code>from app.urls import app_urls\n\nurl_routing = {\n    'user/': app_urls,\n}\n</code></pre></li> <li> <p>app/urls.py     <pre><code>from app.apis import *\n\nurls = {\n    'login/': login_api,\n    'logout/': logout_api,\n    'profile/&lt;user_id&gt;/': profile_api,\n}\n</code></pre></p> </li> <li> <p>app/apis.py     <pre><code>...\n\n@API()\nasync def profile_api(user_id: int):\n    return User.find_one(id=user_id)\n</code></pre></p> </li> </ul>"},{"location":"working_with_db/","title":"Working With Database","text":"<p>Panther create a database connection depends on database middleware you are using on <code>core/configs.py</code>  and you can access to this connection from your <code>models</code>  or direct access from <code>from panther.db.connection import db</code></p> <p>Now we are going to create a new API which uses our default database(<code>PantherDB</code>) and creating a <code>Book</code></p> <ol> <li> <p>Create <code>Book</code> model in <code>app/models.py</code> <pre><code>from panther.db import Model\n\n\nclass Book(Model):\n    title: str\n    description: str\n    pages_count: int\n</code></pre></p> </li> <li> <p>Add <code>book</code> url in <code>app/urls.py</code> that points to <code>book_api()</code></p> <pre><code>...\nfrom app.apis import time_api, book_api\n\n\nurls = {\n    '': hello_world,\n    'info/': info,\n    'time/': time_api,\n    'book/': book_api,\n}\n</code></pre> </li> <li> <p>Create <code>book_api()</code> in <code>app/apis.py</code></p> <pre><code>from panther import status\nfrom panther.app import API\nfrom panther.response import Response\n\n\n@API()\nasync def book_api():\n    ...\n    return Response(status_code=status.HTTP_201_CREATED)  \n</code></pre> </li> <li> <p>Now we should use the Panther ODM to create a book, it's based on mongo queries, for creation we use <code>insert_one</code> like this:</p> <pre><code>from panther import status\nfrom panther.app import API\nfrom panther.response import Response\nfrom app.models import Book\n\n\n@API()\nasync def book_api():\n    Book.insert_one(\n        title='Python',\n        description='Python is good.',\n        pages_count=10\n    )\n    return Response(status_code=status.HTTP_201_CREATED)  \n</code></pre> </li> </ol> <p>In next step we are going to explain more about <code>Panther ODM</code></p>"}]}
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index 7c7e9d9ff2ea1b08768cdd7c2ebefb03041eb9cc..d4e5e26f8b4a5b4a1c29721afa53e7175c3afc76 100644
GIT binary patch
delta 15
Wcmcb^bccyezMF&N$-<3nVT=GPCIt`x

delta 15
Wcmcb^bccyezMF&N=$wsgVT=GOQv~b)

diff --git a/urls/index.html b/urls/index.html
index f52a5cc..5033d9e 100644
--- a/urls/index.html
+++ b/urls/index.html
@@ -612,10 +612,10 @@ <h1>URLs</h1>
 <p><b>Required:</b> <code>True</code></p>
 </blockquote>
 <ul>
-<li><code>URLs</code> should point to the root of your <code>urls</code> file,
-and in that file you should have a <code>dict</code> name <code>urls</code></li>
+<li><code>URLs</code> should point to your root <code>urls</code> with dotted address (<code>path.module.url_dict</code>),
+and it should be <code>dict</code>.</li>
 <li>
-<p><code>key</code> of urls dict is <code>path</code> &amp; value is <code>endpoint</code> or another <code>dict</code></p>
+<p><code>key</code> of url_routing dict is <code>path</code> &amp; value is <code>endpoint</code> or another <code>dict</code></p>
 </li>
 <li>
 <h4 id="path-variables-are-handled-like-below">Path Variables are handled like below:<a class="headerlink" href="#path-variables-are-handled-like-below" title="Permanent link">#</a></h4>
@@ -630,12 +630,12 @@ <h4 id="path-variables-are-handled-like-below">Path Variables are handled like b
 <h2 id="example">Example<a class="headerlink" href="#example" title="Permanent link">#</a></h2>
 <ul>
 <li>core/configs.py
-    <div class="highlight"><pre><span></span><code><span class="err">`</span><span class="n">URLs</span> <span class="o">=</span> <span class="s1">&#39;configs/urls.py&#39;</span><span class="err">`</span>
+    <div class="highlight"><pre><span></span><code><span class="err">`</span><span class="n">URLs</span> <span class="o">=</span> <span class="s1">&#39;core.urls.url_routing`</span>
 </code></pre></div></li>
 <li>core/urls.py
     <div class="highlight"><pre><span></span><code><span class="kn">from</span> <span class="nn">app.urls</span> <span class="kn">import</span> <span class="n">app_urls</span>
 
-<span class="n">urls</span> <span class="o">=</span> <span class="p">{</span>
+<span class="n">url_routing</span> <span class="o">=</span> <span class="p">{</span>
     <span class="s1">&#39;user/&#39;</span><span class="p">:</span> <span class="n">app_urls</span><span class="p">,</span>
 <span class="p">}</span>
 </code></pre></div></li>