Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lsfratel/restcraft
RestCraft is a lightweight WSGI framework for Python.
https://github.com/lsfratel/restcraft
bottlepy django flask python restcraft web-framework wsgi wsgi-framework
Last synced: 17 days ago
JSON representation
RestCraft is a lightweight WSGI framework for Python.
- Host: GitHub
- URL: https://github.com/lsfratel/restcraft
- Owner: lsfratel
- License: mit
- Created: 2024-04-09T16:25:28.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-11-28T03:50:52.000Z (2 months ago)
- Last Synced: 2025-01-14T20:37:11.676Z (18 days ago)
- Topics: bottlepy, django, flask, python, restcraft, web-framework, wsgi, wsgi-framework
- Language: Python
- Homepage:
- Size: 186 KB
- Stars: 0
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# RestCraft
RestCraft is a lightweight, modular framework designed to build modern web applications in Python. It provides essential tools and components to manage HTTP requests, responses, routing, and middleware, allowing you to focus on building features without being overwhelmed by boilerplate code.
### Key Features
- **Zero External Dependencies**: RestCraft is built entirely with Python's standard library, ensuring a minimal footprint and maximum compatibility.
- **Powerful Routing System**: Support for dynamic and static routes, route merging, and modular blueprints for better organization.
- **Request and Response Handling**: A clean and extensible API to manage HTTP requests, responses, cookies, and headers.
- **Pluggable Architecture**: Add plugins to extend functionality with fine-grained control over their application.
- **Built-in Middleware for CORS**: Enable Cross-Origin Resource Sharing with a simple plugin.
- **Exception Handling**: Centralized error handling with customizable exception responses.
Whether you're building a simple API or a large-scale application, RestCraft gives you the flexibility and control you need while staying lightweight and dependency-free.
## Installation
To install **RestCraft**, just pip install:
```bash
pip install restcraft
```
## Getting Started
Here’s a quick example to set up and run a simple **RestCraft** application:
```python
from restcraft import RestCraft, Router, JSONResponse
from restcraft.views import metadata
from .config import configuration
# Define your views
class HelloWorldView:
@metadata(methods=["GET"])
def get(self):
return JSONResponse({"message": "Hello, World!"})
# Set up the application
app = RestCraft(config=configuration)
# Set up the router
router = Router()
router.add_route("/hello", HelloWorldView())
app.register_router(router)
# Run the application using a WSGI server
if __name__ == "__main__":
from wsgiref.simple_server import make_server
server = make_server("127.0.0.1", 8000, app)
print("Serving on http://127.0.0.1:8000")
server.serve_forever()
```
## Core Concepts
### Routes
RestCraft provides a powerful routing system to map URL paths to specific views. The `Router` class allows you to register routes, handle dynamic parameters, and merge routers for modular and reusable routing logic.
#### Adding Routes
To add a route, use the `add_route` method. Specify the path and the corresponding view object or class:
```python
from restcraft.http.router import Router
from restcraft.http.response import JSONResponse
from restcraft.views import metadata
class MyView:
@metadata(methods=["GET"])
def hello(self):
return JSONResponse({"message": "Hello, World!"})
router = Router()
router.add_route("/hello", MyView())
```
#### Dynamic Routes
Dynamic segments in paths are defined with a `<` prefix and `>` suffix. Dynamic routes allow you to capture parts of the URL and pass them as parameters to the handler:
```python
class UserView:
@metadata(methods=["GET"])
def get_user(self, id):
return JSONResponse({"user_id": id})
router.add_route("/user/", UserView())
router.add_route(r"/user/", UserView())
# Example:
# GET /user/42 -> {"user_id": "42"}
```
#### Merging Routers
The `merge` function allows you to combine multiple routers into a single router. This enables modular routing, similar to blueprints in other frameworks, making it easy to organize your application by grouping related routes.
```python
# Define a "users" module
users_router = Router(prefix="/users")
class UserView:
@metadata(methods=["GET"])
def list_users(self):
return JSONResponse({"users": []})
@metadata(methods=["POST"])
def create_user(self):
return JSONResponse({"message": "User created"})
users_router.add_route("/", UserView())
# Define a "products" module
products_router = Router(prefix="/products")
class ProductView:
@metadata(methods=["GET"])
def list_products(self):
return JSONResponse({"products": []})
products_router.add_route("/", ProductView())
# Merge modules into the main router
app_router = Router()
app_router.merge(users_router)
app_router.merge(products_router)
# Example:
# GET /users -> {"users": []}
# GET /products -> {"products": []}
```
### Request Handling
Access request properties like headers, query parameters, JSON payloads, forms, and file uploads:
```python
from restcraft.http import request
class UserView:
@metadata(methods=["POST"])
def create(self):
data = request.json
return JSONResponse({"received": data})
```
### Plugins
Extend functionality using plugins. Plugins in RestCraft are middleware-like components that can modify the behavior of request handlers. Each plugin can be selectively applied to specific methods by using the `metadata` decorator.
#### Using Plugins
To register a plugin, use the `register_plugin` method of the `RestCraft` application:
```python
from restcraft.contrib.plugins.cors_plugin import CORSPlugin
plugin = CORSPlugin(allow_origins=["http://example.com"])
app.register_plugin(plugin)
```
#### Controlling Plugin Execution with Metadata
The `metadata` decorator allows you to specify which plugins should run (or be excluded) for a particular method. By default, all plugins run on all methods unless specified otherwise.
- **Include Plugins**: List plugin names to explicitly allow them.
- **Exclude Plugins**: Prefix the plugin name with `-` to exclude it.
Here’s an example:
```python
from restcraft.http.response import JSONResponse
from restcraft.views import metadata
class MyView:
# Allow all plugins (default behavior)
@metadata(methods=["GET"])
def all_plugins_allowed(self):
return JSONResponse({"message": "All plugins are allowed"})
# Only allow 'cors_plugin' to run
@metadata(methods=["POST"], plugins=["cors_plugin"])
def only_cors_plugin(self):
return JSONResponse({"message": "Only CORS plugin will run"})
# Exclude 'auth_plugin'
@metadata(methods=["DELETE"], plugins=["...", "-auth_plugin"])
def exclude_auth_plugin(self):
return JSONResponse({"message": "All plugins except 'auth_plugin' will run"})
```
#### Writing Your Own Plugin
To create a custom plugin, subclass the `Plugin` class and implement the `before_handler` or `before_route` method:
```python
from restcraft.plugin import Plugin
class CustomHeaderPlugin(Plugin):
name = "custom_header_plugin"
def before_handler(self, handler, metadata):
def wrapper(*args, **kwargs):
response = handler(*args, **kwargs)
response.headers["X-Custom-Header"] = "My Custom Value"
return response
return wrapper
```
Register your plugin with the application:
```python
plugin = CustomHeaderPlugin()
app.register_plugin(plugin)
```
#### Plugin Execution Order
Plugins are applied in the order they are registered in the application. To control execution order, register plugins in the desired sequence:
```python
app.register_plugin(PluginA())
app.register_plugin(PluginB())
```
## File Uploads
RestCraft handles file uploads efficiently, writing large files to disk-backed temporary storage. Here's how you can access uploaded files:
```python
class FileUploadView:
@metadata(methods=["POST"])
def upload(self):
file_data = request.files.get("file")
return JSONResponse({
"filename": file_data["filename"],
"content_type": file_data["content_type"],
})
```
## Cookies
RestCraft includes a powerful and flexible cookie management system inspired by [Remix.run](https://remix.run). With RestCraft, you can easily create, parse, sign, and validate cookies, enabling secure state management for your web applications.
### Key Features
- **Serialization and Parsing**: Effortlessly serialize Python objects into cookies and parse them back into Python objects.
- **Signed Cookies**: Use secret keys to sign cookies, ensuring their integrity and protecting against tampering.
- **Expiration and Max-Age**: Automatically manage cookie expiration with built-in support for `Expires` and `Max-Age` attributes.
- **Secure Defaults**: Cookies are configured to be `HttpOnly` and `Secure` by default, ensuring they are protected from client-side scripts and transmitted only over HTTPS.
### Example Usage
#### Creating and Serializing a Cookie
```python
from restcraft.http import Cookie
# Create a new cookie with secure options
cookie = Cookie("user_session", options={"secrets": ["my_secret_key"], "secure": True})
class MyView:
@metadata(methods=["GET"])
def list(self):
# read
user_info = cookie.parse(request.headers["cookie"])
# set
return JSONResponse(data, headers={"Set-Cookie": cookie.serialize(user_info, overrides={"max_age": 60})})
```
## Custom Exception Handling
Define custom exception handlers for your application:
```python
from restcraft.exceptions import RestCraftException
@app.register_exception(RestCraftException)
def handle_restcraft_exception(exc):
return JSONResponse({"error": exc.message}, status=exc.status)
```
## Contributing
Contributions are welcome! If you'd like to improve RestCraft, follow these steps:
1. Fork the repository.
2. Create a new branch.
3. Make your changes and write tests.
4. Submit a pull request.
## License
This project is licensed under the MIT License. See the `LICENSE` file for details.
## Acknowledgements
Special thanks to all contributors and the Python community for inspiring this project.