⭐️ If you find Panther useful, please give it a star!
================================================
FILE: SECURITY.md
================================================
# Security Policy
## Supported Versions
Use this section to tell people about which versions of your project are
currently being supported with security updates.
| Version | Supported |
| ------- | ------------------ |
| > 1.7.x | :white_check_mark: |
| < 1.7 | :x: |
## Reporting a Vulnerability
It is an open-source project and we would be happy if you report an issue if you found any vulnerabilities 😃🖐️
================================================
FILE: benchmark.txt
================================================
"""
Checkout profiler.py for more information
"""
Clock type: CPU
Ordered by: totaltime, desc
name ncall tsub ttot tavg
/home/ali/dev/panther/panther/main.py:78 Panther.__call__ 1001 0.012665 0.811156 0.000810
/home/ali/dev/panther/panther/main.py:161 Panther.handle_http 1000 0.035138 0.798476 0.000798
/home/ali/dev/panther/panther/response.py:167 Response.send 1000 0.009427 0.473242 0.000473
/home/ali/dev/panther/panther/response.py:161 Response.send_headers 1000 0.012985 0.287794 0.000288
/home/ali/dev/panther/panther/middlewares/base.py:15 TestMiddleware.__call__ 1000 0.005173 0.239159 0.000239
/home/ali/dev/panther/panther/main.py:142 handle_http_endpoint 1000 0.021648 0.233986 0.000234
/home/ali/dev/panther/panther/response.py:164 Response.send_body 1000 0.009923 0.176022 0.000176
/home/ali/dev/panther/panther/app.py:120 wrapper 1000 0.008120 0.133374 0.000133
/home/ali/dev/panther/panther/app.py:136 API.handle_endpoint 1000 0.042525 0.125255 0.000125
/home/ali/dev/panther/panther/response.py:124 Response.bytes_headers 1000 0.024477 0.062525 0.000063
/home/ali/dev/panther/panther/response.py:67 Response.__init__ 1000 0.019294 0.059479 0.000059
/home/ali/dev/panther/panther/routings.py:133 find_endpoint 1000 0.026393 0.043979 0.000044
/home/ali/dev/panther/panther/request.py:40 Request.read_body 1000 0.011115 0.036803 0.000037
/home/ali/dev/panther/panther/response.py:135 prepare_data 2000/1000 0.023992 0.031797 0.000016
/home/ali/dev/panther/panther/base_request.py:129 Request.collect_path_variables 1000 0.019701 0.031360 0.000031
/home/ali/dev/panther/panther/response.py:116 Response.headers 1000 0.009755 0.025101 0.000025
/home/ali/dev/panther/panther/response.py:107 Response.body 2000 0.011792 0.024099 0.000012
/home/ali/dev/panther/panther/base_request.py:139 Request.clean_parameters 1000 0.007809 0.011867 0.000012
/home/ali/dev/panther/panther/request.py:14 Request.__init__ 1000 0.008140 0.010023 0.000010
/home/ali/dev/panther/panther/response.py:154 check_status_code 1000 0.003490 0.004959 0.000005
/home/ali/dev/panther/panther/request.py:19 Request.method 3000 0.004952 0.004952 0.000002
/home/ali/dev/panther/panther/middlewares/base.py:12 TestMiddleware.__init__ 1000 0.004111 0.004111 0.000004
/home/ali/dev/panther/panther/base_request.py:109 Request.path 2000 0.003424 0.003424 0.000002
/home/ali/dev/panther/panther/base_request.py:88 Request.__init__ 1000 0.001883 0.001883 0.000002
/home/ali/dev/panther/panther/app.py:189 API.handle_authentication 1000 0.001752 0.001752 0.000002
/home/ali/dev/panther/panther/response.py:131 Response.headers 1000 0.001583 0.001583 0.000002
/home/ali/dev/panther/panther/events.py:27 run_startups 1 0.000001 0.000001 0.000001
================================================
FILE: docs/docs/admin_panel.md
================================================
> **⚠️ WARNING: The Panther Admin Panel is currently in development. Do NOT use it in production environments!**
>
> **Contributions, feedback, and ideas are welcome!**
# Panther Admin Panel
Panther provides a built-in admin panel that allows you to easily manage your database models through a web interface.
## Enabling the Admin Panel
To enable the admin panel in your project, follow these steps:
### 1. Add the Admin Panel URLs
First, ensure your main URL configuration includes the admin panel routes. e.g. open your `core/urls.py` and add the following:
```python title="core/urls.py"
from panther.panel.urls import url_routing as panel_url_routing
url_routing = {
'panel/': panel_url_routing,
# ... other routes ...
}
```
> **Note:** If you are using a different file for your URL routing, adjust the import and assignment accordingly.
### 2. Update Your Configs (if needed)
If your project uses a custom configuration file for URLs, make sure it points to your updated URL routing. For example, in `core/configs.py`:
```python title="core/configs.py"
URLs = 'core.urls.url_routing'
```
### 3. Run Your Application
Start your Panther application as usual:
```bash
panther run main:app
```
### 4. Access the Admin Panel
Open your browser and navigate to:
[http://127.0.0.1:8000/panel/](http://127.0.0.1:8000/panel/)
You should see the Panther Admin Panel interface, where you can manage your database models.
### 5. Create an Admin User
To access the admin panel, you need at least one user account. You can create a user using the following command:
```bash
panther createuser main.py
```
Replace `main.py` with the path to your main application file if it is different. This command will create a new user based on your `USER_MODEL` (by default, `panther.db.models.BaseUser`).
Once the user is created, you can log in to the admin panel using the credentials you set during user creation.
================================================
FILE: docs/docs/api.md
================================================
# Panther API Guide
This guide assumes you have successfully set up your project and created your first CRUD following the [First CRUD](first_crud.md) guide.
In this guide, we discuss the features and structure of Panther's API system, including authentication, permissions, caching, throttling, middlewares, and more.
---
## API Request Flow
The typical flow of an API request in Panther is as follows:
```
Middlewares
├── Method
├── Authentication
├── Permissions
├── Throttling
├── Validate Input
├── Get Response From Cache
├── Call Endpoint
├── Set Response To Cache
Middlewares
```
---
## Input Model
You can validate incoming data using the `input_model` parameter. Pass a serializer to it, and Panther will send `request.data` to this serializer, placing the validated data in `request.validated_data`. As a result, `request.validated_data` will be an instance of your serializer.
> Note: `request.data` is validated only for 'POST', 'PUT', and 'PATCH' methods.
??? question "How do serializers work in Panther?"
Refer to [Serializer](serializer.md) to learn more about serializers.
```python title="app/serializers.py" linenums="1"
from panther.serializer import ModelSerializer
class UserInputSerializer(ModelSerializer):
...
```
=== "Function-Base API"
```python title="app/apis.py" linenums="1"
from panther import status
from panther.app import API
from panther.request import Request
from panther.response import Response
from app.serializers import UserInputSerializer
@API(input_model=UserInputSerializer)
async def user_api(request: Request):
request.validated_data # This is now available
...
```
=== "Class-Base API"
```python title="app/apis.py" linenums="1"
from panther import status
from panther.app import GenericAPI
from panther.response import Response
from app.serializers import UserInputSerializer
class UserAPI(GenericAPI):
input_model = UserInputSerializer
async def get(self, request: Request):
request.validated_data # This is now available
...
```
---
## Output Model
Use the `output_model` parameter to automatically serialize your API response data using a specified serializer. This ensures that the response structure is consistent and validated.
**Example Serializer:**
```python title="app/serializers.py" linenums="1"
from panther.serializer import ModelSerializer
class UserSerializer(ModelSerializer):
...
```
=== "Function-Base API"
```python title="app/apis.py" linenums="1"
from panther.app import API
from app.serializers import UserSerializer
@API(output_model=UserSerializer)
async def user_api():
...
```
=== "Class-Base API"
```python title="app/apis.py" linenums="1"
from panther.app import GenericAPI
from app.serializers import UserSerializer
class UserAPI(GenericAPI):
output_model = UserSerializer
...
```
> **Tip:** Use `output_model` to ensure your API always returns data in the expected format. For OpenAPI documentation, see the `output_schema` section.
---
## Authentication
To ensure that each request contains a valid authentication header, use the `auth` parameter.
- The `auth` parameter can be an any async function or a class with an async `__call__` method.
- If you set `auth`, Panther will use your specified authentication class or function.
- If you do not set `auth`, Panther will use the default `AUTHENTICATION` from your config **only if the request contains an authorization header**.
- If there is no authorization header in the request, authentication is bypassed, `request.user` will be `None` and you must rely on permissions to check the user and their authorization.
??? question "How do authentications work in Panther?"
Refer to [Authentications](authentications.md) to learn more about authentications.
=== "Function-Base API"
```python title="app/apis.py" linenums="1"
from panther import status
from panther.app import API
from panther.request import Request
from panther.response import Response
from app.authentications import MyAuthenticationClass
@API(auth=MyAuthenticationClass) # You can also use a function
async def user_api(request: Request):
user = request.user
return Response(data=user, status_code=status.HTTP_200_OK)
```
=== "Class-Base API"
```python title="app/apis.py" linenums="1"
from panther import status
from panther.app import GenericAPI
from panther.response import Response
from app.authentications import MyAuthenticationClass
class UserAPI(GenericAPI):
auth = MyAuthenticationClass # You can also use a function
async def get(self, request: Request):
user = request.user
return Response(data=user, status_code=status.HTTP_200_OK)
```
---
## Method
You can specify which HTTP methods are allowed for an endpoint by setting `methods` in function-based APIs. Only the following methods are supported: `['GET', 'POST', 'PUT', 'PATCH', 'DELETE']`.
> If a method is not allowed, a 405 status code will be returned.
=== "Function-Base API"
```python title="app/apis.py" linenums="1"
from panther.app import API
from panther.request import Request
@API(methods=['GET', 'POST'])
async def user_api(request: Request):
match request.method:
case 'GET':
...
case 'POST':
...
```
=== "Class-Base API"
```python title="app/apis.py" linenums="1"
from panther.app import GenericAPI
class UserAPI(GenericAPI): # (1)!
async def get(self):
...
async def post(self):
...
```
1. Now this class only accepts `GET` and `POST` requests.
---
## Permissions
You can implement your authorization logic using permission classes or functions. Any async function or class with an async `__call__` method can be used as a permission. Panther will call each permission (asynchronously).
Pass a list of permission callables to your API using the `permissions` parameter. If you pass a single permission, it will be automatically wrapped in a list.
> Each permission must be async (either an async function or a class with an async `__call__`).
**Example Permission Function:**
```python title="app/permissions.py" linenums="1"
from panther.request import Request
async def custom_permission(request: Request) -> bool:
return True
```
**Example Permission Class:**
```python title="app/permissions.py" linenums="1"
from panther.permissions import BasePermission
from panther.request import Request
class CustomPermission(BasePermission):
async def __call__(self, request: Request) -> bool:
return True
```
=== "Function-Base API"
```python title="app/apis.py" linenums="1"
from panther.app import API
from app.permissions import custom_permission, CustomPermission
@API(permissions=[custom_permission, CustomPermission])
async def user_api():
...
```
Or, if you have only one permission:
```python title="app/apis.py" linenums="1"
from panther.app import API
from app.permissions import custom_permission
@API(permissions=custom_permission)
async def user_api():
...
```
Panther will treat it as a list internally.
=== "Class-Base API"
```python title="app/apis.py" linenums="1"
from panther.app import GenericAPI
from app.permissions import CustomPermission
class UserAPI(GenericAPI):
permissions = [CustomPermission]
...
```
Or, if you have only one permission:
```python title="app/apis.py" linenums="1"
from panther.app import GenericAPI
from app.permissions import custom_permission
class UserAPI(GenericAPI):
permissions = custom_permission
...
```
Panther will treat it as a list internally.
---
## Cache
Responses can be cached for a specific amount of time per request or IP. Caching is only applied to `GET` requests. The response's headers, data, and status code will be cached.
The cache is stored in Redis (if connected) or in memory. The cache key is based on the user ID or IP, request path, query parameters, and validated data:
```
'user_id or ip - request.path - hash of query param - request.validated_data'
```
The value of `cache` should be an instance of `datetime.timedelta()`.
=== "Function-Base API"
```python title="app/apis.py" linenums="1"
from datetime import timedelta
from panther.app import API
@API(cache=timedelta(minutes=10))
async def user_api():
...
```
=== "Class-Base API"
```python title="app/apis.py" linenums="1"
from datetime import timedelta
from panther.app import GenericAPI
class UserAPI(GenericAPI):
cache = timedelta(minutes=10)
...
```
---
## Throttling
You can throttle requests using the `Throttle` class, either globally via the `THROTTLING` config or per API. The `Throttle` class has two fields: `rate` and `duration`.
If a user exceeds the allowed number of requests (`rate`) within the specified `duration`, they will receive a `429 Too Many Requests` response and be banned for the duration.
> When you set `throttling` on your API, it takes precedence over the default `THROTTLING`, and the default `THROTTLING` will not be executed.
### Setting Default Throttling
```python
from datetime import timedelta
from panther.throttling import Throttle
# Users can only make 5 requests every minute
THROTTLING = Throttle(rate=5, duration=timedelta(minutes=1))
```
### Throttling Per API
=== "Function-Base API"
```python title="app/apis.py" linenums="1"
from datetime import timedelta
from panther.app import API
from panther.throttling import Throttle
@API(throttling=Throttle(rate=5, duration=timedelta(minutes=1)))
async def user_api():
...
```
=== "Class-Base API"
```python title="app/apis.py" linenums="1"
from datetime import timedelta
from panther.app import GenericAPI
from panther.throttling import Throttle
class UserAPI(GenericAPI):
throttling = Throttle(rate=5, duration=timedelta(minutes=1))
...
```
### Customization
Throttling works with `request.user.id` or `request.client.ip`. You can customize its behavior by overriding `build_cache_key()`:
```python title="app/throttlings.py" linenums="1"
from panther.request import Request
from panther.throttling import Throttle
class CustomThrottle(Throttle):
def build_cache_key(self, request: Request) -> str:
...
```
---
## Middlewares
You can pass custom middlewares to specific APIs.
**Example Middleware:**
```python title="app/middlewares.py" linenums="1"
from panther.middlewares.base import HTTPMiddleware
from panther.request import Request
from panther.response import Response
class CustomMiddleware(HTTPMiddleware):
async def __call__(self, request: Request) -> Response:
print('Hi')
response = await self.dispatch(request=request)
print('Bye')
return response
```
=== "Function-Base API"
```python title="app/apis.py" linenums="1"
from panther.app import API
from app.middlewares import CustomMiddleware
@API(middlewares=[CustomMiddleware])
async def user_api():
...
```
=== "Class-Base API"
```python title="app/apis.py" linenums="1"
from panther.app import GenericAPI
from app.middlewares import CustomMiddleware
class UserAPI(GenericAPI):
middlewares = [CustomMiddleware]
...
```
??? question "How do middlewares work in Panther?"
Refer to [Middlewares](middlewares.md) to learn more about middlewares.
---
## Output Schema
The `output_schema` attribute is used when generating OpenAPI (Swagger) documentation.
It should be an instance of `panther.openapi.OutputSchema`, which specifies the desired response data structure and status code.
**Example Serializer:**
```python title="app/serializers.py" linenums="1"
from panther.serializer import ModelSerializer
class UserSerializer(ModelSerializer):
...
```
=== "Function-Base API"
```python title="app/apis.py" linenums="1"
from panther import status
from panther.app import API
from panther.openapi import OutputSchema
from app.serializers import UserSerializer
@API(output_schema=OutputSchema(status_code=status.HTTP_201_CREATED, model=UserSerializer))
async def user_api():
...
```
=== "Class-Base API"
```python title="app/apis.py" linenums="1"
from panther.app import GenericAPI
from panther.openapi import OutputSchema
from app.serializers import UserSerializer
class UserAPI(GenericAPI):
output_schema = OutputSchema(status_code=status.HTTP_201_CREATED, model=UserSerializer)
...
```
??? question "How does OpenAPI work in Panther?"
Refer to [OpenAPI](open_api.md) to learn more about OpenAPI.
---
## File Handling
Panther provides built-in support for file uploads through the `File` and `Image` classes.
!!! tip "Comprehensive File Handling Guide"
For detailed information about file handling, including advanced features, best practices, and troubleshooting, see the dedicated [File Handling](file_handling.md) documentation.
```python title="app/apis.py" linenums="1"
from panther.app import API
from panther.db import Model
from panther.file_handler import File
from panther.request import Request
from panther.response import Response
from panther.serializer import ModelSerializer
class FileUpload(Model):
file: File
description: str
class FileUploadSerializer(ModelSerializer):
class Config:
model = FileUpload
fields = '*'
@API(input_model=FileUploadSerializer)
async def upload_file(request: Request):
file_data = request.validated_data
file = file_data.file
# Save file to disk
saved_path = file.save("uploads/")
return Response(data={
"message": "File uploaded successfully",
"saved_path": saved_path
})
```
================================================
FILE: docs/docs/authentications.md
================================================
# Authentication in Panther
Authentication in Panther ensures that only authorized users can access your APIs and WebSocket connections. You can configure which authentication class to use in your `configs`.
---
## How Authentication Works
- The `auth` parameter for an API or WebSocket should be an async function or a class with an async `__call__` method. Panther will use this callable to verify the user.
- If you do not set `auth`, Panther will use the default `AUTHENTICATION` from your config **only if the request contains an authorization header**. If there is no authorization header, authentication is bypassed and `request.user` will be `None`.
- If authentication fails, Panther raises `HTTP_401_UNAUTHORIZED`.
- The authenticated user is available as:
- `request.user` in API views
- `self.user` in WebSocket connections
> **Note:** When authentication is bypassed (no authorization header), `request.user` will be `None` and you must rely on permissions to check the user and their authorization.
---
## Built-in Authentication Classes
Panther provides three built-in authentication classes, all based on JWT (JSON Web Token):
### 1. JWT Authentication
- Retrieves the JWT token from the `Authorization` header in the request.
- Expects the header format: `Authorization: Bearer 
# Panther
**A Fast & Friendly Web Framework for Building Async APIs with Python 3.10+**
[📚 Documentation](https://pantherpy.github.io)
