# WOPR Web Framework
A high-performance async web framework built specifically for Granian's RSGI interface. WOPR combines the developer experience of Flask/Quart with the performance benefits of RSGI.
## 🏁 Benchmarks
```
🧪 Testing WOPR Benchmark Endpoints
==================================================
✅ Info 1.98ms application/json
✅ JSON 0.48ms application/json
✅ Plaintext 0.37ms text/plain
✅ Single Query 1.54ms application/json
✅ 5 Queries 1.71ms application/json
✅ 3 Updates 2.92ms application/json
✅ Fortunes 2.76ms text/html; charset=utf-8
✅ 10 Cached 12.31ms application/json
```
## 🚀 Features
- **High Performance**: Built on Granian's RSGI interface for maximum speed
- **Async/Await**: Full async support throughout the framework
- **Background Tasks**: Intelligent task system with DuckDB storage and priorities
- **WebSocket Support**: Real-time communication with room management
- **Template Engine**: Jinja2 integration with async support
- **Middleware System**: Static files, CORS, security, and custom middleware
- **Security First**: CSRF protection, security headers, rate limiting
- **CLI Tools**: Project initialization and management commands
- **Developer Experience**: Clean APIs, helpful error messages, hot reload
## 📦 Installation
```bash
# Basic installation
uv add wopr
# With all features
uv add "wopr[all]"
# Or specific features
uv add "wopr[templates,tasks,cli]"
```
## 🏃 Quick Start
### Create a New Project
```bash
# Install WOPR with CLI tools
uv add "wopr[cli]"
# Create new project
uv run wopr init my_app
# Navigate and run
cd my_app
uv sync
granian --interface rsgi --reload app:app
```
### Simple Example
```python
from wopr import WOPR, Request, jsonify
app = WOPR(__name__)
@app.get("/")
async def hello(request: Request):
return jsonify({"message": "Hello from WOPR!"})
@app.get("/users/<user_id>")
async def get_user(request: Request, user_id: str):
return jsonify({"user_id": user_id, "name": f"User {user_id}"})
# Run with: granian --interface rsgi app:app
```
## 📚 Examples
### 🌟 Interactive Demo (`example_app.py`)
Complete showcase of all framework features with a web UI:
```bash
uv sync --extra all
granian --interface rsgi --reload example_app:app
```
Visit http://localhost:8000 for interactive demos of:
- HTTP endpoints and routing
- Background task processing
- WebSocket communication
- Security features
- Middleware functionality
### 📊 Data Handling (`data_example.py`)
RESTful API demonstrating data operations:
```bash
granian --interface rsgi --reload data_example:app
```
Features:
- CRUD operations with filtering and pagination
- Background data processing
- Real-time analytics
- Task monitoring
### 📈 Benchmarks (`benchmark_simple.py`)
Standard TechEmpower benchmark implementation:
```bash
granian --interface rsgi --workers 4 --threads 2 benchmark_simple:app
```
Benchmark endpoints:
- JSON serialization
- Database queries (simulated)
- Database updates (simulated)
- Plaintext response
- HTML template rendering
- Cached queries
## 🏗️ Architecture
```
src/wopr/
├── core/ # Main WOPR application class
├── http/ # Request/Response handling & routing
├── websocket/ # WebSocket support & room management
├── tasks/ # Background task system with DuckDB
├── templates/ # Jinja2 template engine
├── middleware/ # Static files, CORS, security
├── cli/ # Command-line tools
└── utils/ # Rate limiting and utilities
```
## 🔧 Key Components
### Application
```python
from wopr import WOPR
app = WOPR(__name__)
app.init_templates() # Enable Jinja2 templates
# Route decorators
@app.get("/")
@app.post("/api/data")
@app.websocket("/ws")
# Middleware
from wopr.middleware import CORSMiddleware
app.add_middleware(CORSMiddleware(origins=["*"]))
```
### Background Tasks
```python
@app.task("send_email", "notifications")
async def send_email(to: str, subject: str):
# Task implementation
return {"status": "sent"}
# Queue tasks
task_id = await app.add_background_task(
"send_email", "notifications", TaskPriority.HIGH,
to="user@example.com", subject="Welcome!"
)
# Start workers
await app.start_task_workers("notifications", worker_count=2)
```
### WebSocket
```python
@app.websocket("/ws/chat")
async def chat_handler(websocket):
await websocket.accept()
while True:
message = await websocket.receive()
await websocket.send_text(f"Echo: {message.data}")
```
### Templates
```python
@app.get("/")
async def index(request):
return await app.render_template("index.html",
message="Hello World!")
```
## 🛡️ Security
- **CSRF Protection**: Built-in CSRF token generation and validation
- **Security Headers**: X-Frame-Options, CSP, HSTS, etc.
- **Rate Limiting**: Configurable rate limiting with decorators
- **Input Validation**: Request data validation and sanitization
- **Static File Security**: Path traversal protection
## ⚡ Performance
- **RSGI Interface**: Maximum performance with Granian server
- **Async Throughout**: Non-blocking operations everywhere
- **Background Tasks**: Offload heavy work to background queues
- **Efficient Routing**: Fast path matching with parameter extraction
- **Optional Dependencies**: Load only what you need
## 🧪 Testing
```bash
# Install dev dependencies
uv sync --extra dev
# Run tests (when implemented)
uv run pytest
# Code quality
uv run black . # Format code
uv run ruff check . # Lint code
uv run mypy src/ # Type checking
```
## 📖 Documentation
- **CLAUDE.md**: Comprehensive development guide
- **DATA_EXAMPLE.md**: Data handling tutorial
- **Example Applications**: Fully commented examples
## 🤝 Contributing
WOPR is built with modern Python best practices:
- **Python 3.12+** for latest async improvements
- **Type hints** throughout the codebase
- **Modular architecture** for easy extension
- **Comprehensive error handling**
- **Security-first design**
## 📄 License
MIT License - see LICENSE file for details.
## 🔗 Links
- **GitHub**: https://github.com/wopr-framework/wopr
- **Documentation**: https://wopr-framework.readthedocs.io
- **PyPI**: https://pypi.org/project/wopr
---
**WOPR** - High-performance async web framework for modern Python web applications. 🎮
Raw data
{
"_id": null,
"home_page": null,
"name": "wopr",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "web, framework, async, rsgi, granian, background-tasks",
"author": "War Operations Plan Response Framework Team",
"author_email": null,
"download_url": null,
"platform": null,
"description": "# WOPR Web Framework\n\nA high-performance async web framework built specifically for Granian's RSGI interface. WOPR combines the developer experience of Flask/Quart with the performance benefits of RSGI.\n\n## \ud83c\udfc1 Benchmarks\n\n```\n\ud83e\uddea Testing WOPR Benchmark Endpoints\n==================================================\n\u2705 Info 1.98ms application/json\n\u2705 JSON 0.48ms application/json\n\u2705 Plaintext 0.37ms text/plain\n\u2705 Single Query 1.54ms application/json\n\u2705 5 Queries 1.71ms application/json\n\u2705 3 Updates 2.92ms application/json\n\u2705 Fortunes 2.76ms text/html; charset=utf-8\n\u2705 10 Cached 12.31ms application/json\n```\n\n## \ud83d\ude80 Features\n\n- **High Performance**: Built on Granian's RSGI interface for maximum speed\n- **Async/Await**: Full async support throughout the framework\n- **Background Tasks**: Intelligent task system with DuckDB storage and priorities\n- **WebSocket Support**: Real-time communication with room management\n- **Template Engine**: Jinja2 integration with async support\n- **Middleware System**: Static files, CORS, security, and custom middleware\n- **Security First**: CSRF protection, security headers, rate limiting\n- **CLI Tools**: Project initialization and management commands\n- **Developer Experience**: Clean APIs, helpful error messages, hot reload\n\n## \ud83d\udce6 Installation\n\n```bash\n# Basic installation\nuv add wopr\n\n# With all features\nuv add \"wopr[all]\"\n\n# Or specific features\nuv add \"wopr[templates,tasks,cli]\"\n```\n\n## \ud83c\udfc3 Quick Start\n\n### Create a New Project\n```bash\n# Install WOPR with CLI tools\nuv add \"wopr[cli]\"\n\n# Create new project\nuv run wopr init my_app\n\n# Navigate and run\ncd my_app\nuv sync\ngranian --interface rsgi --reload app:app\n```\n\n### Simple Example\n```python\nfrom wopr import WOPR, Request, jsonify\n\napp = WOPR(__name__)\n\n@app.get(\"/\")\nasync def hello(request: Request):\n return jsonify({\"message\": \"Hello from WOPR!\"})\n\n@app.get(\"/users/<user_id>\")\nasync def get_user(request: Request, user_id: str):\n return jsonify({\"user_id\": user_id, \"name\": f\"User {user_id}\"})\n\n# Run with: granian --interface rsgi app:app\n```\n\n## \ud83d\udcda Examples\n\n### \ud83c\udf1f Interactive Demo (`example_app.py`)\nComplete showcase of all framework features with a web UI:\n```bash\nuv sync --extra all\ngranian --interface rsgi --reload example_app:app\n```\nVisit http://localhost:8000 for interactive demos of:\n- HTTP endpoints and routing\n- Background task processing\n- WebSocket communication\n- Security features\n- Middleware functionality\n\n### \ud83d\udcca Data Handling (`data_example.py`)\nRESTful API demonstrating data operations:\n```bash\ngranian --interface rsgi --reload data_example:app\n```\nFeatures:\n- CRUD operations with filtering and pagination\n- Background data processing\n- Real-time analytics\n- Task monitoring\n\n### \ud83d\udcc8 Benchmarks (`benchmark_simple.py`)\nStandard TechEmpower benchmark implementation:\n```bash\ngranian --interface rsgi --workers 4 --threads 2 benchmark_simple:app\n```\nBenchmark endpoints:\n- JSON serialization\n- Database queries (simulated)\n- Database updates (simulated)\n- Plaintext response\n- HTML template rendering\n- Cached queries\n\n## \ud83c\udfd7\ufe0f Architecture\n\n```\nsrc/wopr/\n\u251c\u2500\u2500 core/ # Main WOPR application class\n\u251c\u2500\u2500 http/ # Request/Response handling & routing \n\u251c\u2500\u2500 websocket/ # WebSocket support & room management\n\u251c\u2500\u2500 tasks/ # Background task system with DuckDB\n\u251c\u2500\u2500 templates/ # Jinja2 template engine\n\u251c\u2500\u2500 middleware/ # Static files, CORS, security\n\u251c\u2500\u2500 cli/ # Command-line tools\n\u2514\u2500\u2500 utils/ # Rate limiting and utilities\n```\n\n## \ud83d\udd27 Key Components\n\n### Application\n```python\nfrom wopr import WOPR\n\napp = WOPR(__name__)\napp.init_templates() # Enable Jinja2 templates\n\n# Route decorators\n@app.get(\"/\")\n@app.post(\"/api/data\") \n@app.websocket(\"/ws\")\n\n# Middleware\nfrom wopr.middleware import CORSMiddleware\napp.add_middleware(CORSMiddleware(origins=[\"*\"]))\n```\n\n### Background Tasks\n```python\n@app.task(\"send_email\", \"notifications\")\nasync def send_email(to: str, subject: str):\n # Task implementation\n return {\"status\": \"sent\"}\n\n# Queue tasks\ntask_id = await app.add_background_task(\n \"send_email\", \"notifications\", TaskPriority.HIGH,\n to=\"user@example.com\", subject=\"Welcome!\"\n)\n\n# Start workers\nawait app.start_task_workers(\"notifications\", worker_count=2)\n```\n\n### WebSocket\n```python\n@app.websocket(\"/ws/chat\")\nasync def chat_handler(websocket):\n await websocket.accept()\n \n while True:\n message = await websocket.receive()\n await websocket.send_text(f\"Echo: {message.data}\")\n```\n\n### Templates\n```python\n@app.get(\"/\")\nasync def index(request):\n return await app.render_template(\"index.html\", \n message=\"Hello World!\")\n```\n\n## \ud83d\udee1\ufe0f Security\n\n- **CSRF Protection**: Built-in CSRF token generation and validation\n- **Security Headers**: X-Frame-Options, CSP, HSTS, etc.\n- **Rate Limiting**: Configurable rate limiting with decorators\n- **Input Validation**: Request data validation and sanitization\n- **Static File Security**: Path traversal protection\n\n## \u26a1 Performance\n\n- **RSGI Interface**: Maximum performance with Granian server\n- **Async Throughout**: Non-blocking operations everywhere\n- **Background Tasks**: Offload heavy work to background queues\n- **Efficient Routing**: Fast path matching with parameter extraction\n- **Optional Dependencies**: Load only what you need\n\n## \ud83e\uddea Testing\n\n```bash\n# Install dev dependencies\nuv sync --extra dev\n\n# Run tests (when implemented)\nuv run pytest\n\n# Code quality\nuv run black . # Format code\nuv run ruff check . # Lint code \nuv run mypy src/ # Type checking\n```\n\n## \ud83d\udcd6 Documentation\n\n- **CLAUDE.md**: Comprehensive development guide\n- **DATA_EXAMPLE.md**: Data handling tutorial\n- **Example Applications**: Fully commented examples\n\n## \ud83e\udd1d Contributing\n\nWOPR is built with modern Python best practices:\n- **Python 3.12+** for latest async improvements\n- **Type hints** throughout the codebase\n- **Modular architecture** for easy extension\n- **Comprehensive error handling**\n- **Security-first design**\n\n## \ud83d\udcc4 License\n\nMIT License - see LICENSE file for details.\n\n## \ud83d\udd17 Links\n\n- **GitHub**: https://github.com/wopr-framework/wopr \n- **Documentation**: https://wopr-framework.readthedocs.io\n- **PyPI**: https://pypi.org/project/wopr\n\n---\n\n**WOPR** - High-performance async web framework for modern Python web applications. \ud83c\udfae\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A high-performance async web framework built on Granian's RSGI interface",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://wopr-framework.readthedocs.io",
"Homepage": "https://github.com/wopr-framework/wopr",
"Issues": "https://github.com/wopr-framework/wopr/issues",
"Repository": "https://github.com/wopr-framework/wopr"
},
"split_keywords": [
"web",
" framework",
" async",
" rsgi",
" granian",
" background-tasks"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "56547cd689d8a0e81d50386bedf62a7c6fc58b505058e7c40cbe81472a40b902",
"md5": "f7c7c2163ae75f54a54f41a85ece787a",
"sha256": "624c4a6449f6c82edc6751e95867e865f5719fd8ba04c59039bfa643afa8f327"
},
"downloads": -1,
"filename": "wopr-0.1.1-cp313-cp313-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "f7c7c2163ae75f54a54f41a85ece787a",
"packagetype": "bdist_wheel",
"python_version": "cp313",
"requires_python": ">=3.12",
"size": 285710,
"upload_time": "2025-08-07T21:00:14",
"upload_time_iso_8601": "2025-08-07T21:00:14.449420Z",
"url": "https://files.pythonhosted.org/packages/56/54/7cd689d8a0e81d50386bedf62a7c6fc58b505058e7c40cbe81472a40b902/wopr-0.1.1-cp313-cp313-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "16366c8d65c2eb587dd4c1ab53bcb5880a08eeef0848378473268fa0ed87886f",
"md5": "a9abd8df536eec071dcbb2c45b14b4d6",
"sha256": "2ff252691000c36c0eac2960dc54afb75579151ef16c62cd8bd1e1bfcb79cd90"
},
"downloads": -1,
"filename": "wopr-0.1.1-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"has_sig": false,
"md5_digest": "a9abd8df536eec071dcbb2c45b14b4d6",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.12",
"size": 320121,
"upload_time": "2025-08-07T21:00:15",
"upload_time_iso_8601": "2025-08-07T21:00:15.825405Z",
"url": "https://files.pythonhosted.org/packages/16/36/6c8d65c2eb587dd4c1ab53bcb5880a08eeef0848378473268fa0ed87886f/wopr-0.1.1-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 21:00:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wopr-framework",
"github_project": "wopr",
"github_not_found": true,
"lcname": "wopr"
}
JSON
