https://github.com/phenobarbital/navigator
Python Framework for build Asynchronous APIs but using friendly syntax.
https://github.com/phenobarbital/navigator
aiohttp aiolibs asyncio asyncpg python uvloop
Last synced: 17 days ago
JSON representation
Python Framework for build Asynchronous APIs but using friendly syntax.
- Host: GitHub
- URL: https://github.com/phenobarbital/navigator
- Owner: phenobarbital
- License: other
- Created: 2020-07-27T01:38:02.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2025-10-07T21:32:47.000Z (4 months ago)
- Last Synced: 2025-10-07T23:32:29.389Z (4 months ago)
- Topics: aiohttp, aiolibs, asyncio, asyncpg, python, uvloop
- Language: Python
- Homepage:
- Size: 2.07 MB
- Stars: 9
- Watchers: 4
- Forks: 8
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# ⚡ Navigator Framework
[](https://pypi.org/project/navigator-api/)
[](https://pypi.org/project/navigator-api/)
[](https://github.com/phenobarbital/navigator/blob/main/LICENSE)
[](https://pepy.tech/project/navigator-api)
> **A batteries-included async web framework built on aiohttp** 🚀
Navigator is a next-generation Python framework designed for building high-performance asynchronous APIs and web applications. Built on top of aiohttp and asyncio, it provides enterprise-grade features out of the box with a focus on developer productivity and application scalability.
## ✨ Key Features
- **⚡ Lightning Fast**: Built on aiohttp + uvloop for maximum performance
- **🔋 Batteries Included**: Authentication, WebSockets, templates, database connections, and more
- **🏗️ Django-style Apps**: Organize code with modular, reusable application components
- **🌐 Multi-tenant Ready**: Built-in sub-domain support for SaaS applications
- **🔧 Centralized Config**: Unified configuration management with NavConfig
- **🔌 Auto-Connections**: Automatic database connection handling with AsyncDB
- **📝 Class-based Views**: Powerful CRUD operations with ModelViews
- **🎯 Extensible**: Plugin architecture for adding custom features
## 🚀 Quick Start
### Installation
```bash
# Using uv (recommended)
uv add navigator-api[uvloop,locale]
# Using pip
pip install navigator-api[uvloop,locale]
```
### Create Your First App
```bash
# Create a new Navigator project
nav init
# Create an application
nav app create myapp
# Run the development server
nav run --debug --reload
```
### Hello Navigator
```python
# app.py
import asyncio
import uvloop
from navigator import Application
from aiohttp import web
async def hello(request):
return web.Response(text="Hello Navigator! 🚀")
async def main():
# Set uvloop as the event loop policy
asyncio.set_event_loop_policy(uvloop.EventLoopPolicy())
# Create Navigator application
app = Application(enable_jinja2=True)
# Add routes
app.router.add_get('/', hello)
# Enable WebSocket support
app.add_websockets()
# Setup and run
return app.setup()
if __name__ == '__main__':
asyncio.run(main())
```
## 🏗️ Architecture
### Class-based Views
Navigator provides powerful class-based views for building APIs:
```python
from navigator.views import BaseView, ModelView
from aiohttp import web
from datamodel import BaseModel
class UserView(BaseView):
async def get(self):
return web.json_response({"users": []})
async def post(self):
data = await self.request.json()
# Process user creation
return web.json_response({"status": "created"})
# Model-based CRUD operations
class User(BaseModel):
name: str
email: str
age: int
class UserModelView(ModelView):
model = User
path = '/api/users'
# Automatic CRUD operations:
# GET /api/users - List all users
# GET /api/users/{id} - Get specific user
# POST /api/users - Create user
# PUT /api/users/{id} - Update user
# DELETE /api/users/{id} - Delete user
```
### Centralized Configuration
Navigator uses [NavConfig](https://github.com/phenobarbital/navconfig) for unified configuration management:
```python
# settings/settings.py
from navconfig import config
# Database configuration
DATABASE_URL = config.get('DATABASE_URL', 'postgresql://user:pass@localhost/db')
# Cache configuration
REDIS_URL = config.get('REDIS_URL', 'redis://localhost:6379')
# App configuration
DEBUG = config.getboolean('DEBUG', False)
SECRET_KEY = config.get('SECRET_KEY', required=True)
# Multiple environment support
ENV = config.get('ENV', 'development') # development, staging, production
```
### Django-style Applications
Organize your code with modular applications:
```
myproject/
├── apps/
│ ├── users/
│ │ ├── __init__.py
│ │ ├── views.py
│ │ ├── models.py
│ │ ├── urls.py
│ │ └── templates/
│ └── products/
│ ├── __init__.py
│ ├── views.py
│ └── models.py
├── settings/
│ └── settings.py
└── main.py
```
```python
# apps/users/__init__.py
from navigator.applications import AppConfig
class UsersConfig(AppConfig):
name = 'users'
path = '/api/users'
def ready(self):
# App initialization code
pass
```
### Database Integration
Navigator integrates seamlessly with [AsyncDB](https://github.com/phenobarbital/asyncdb) for database operations:
```python
from navigator.views import ModelView
from asyncdb.models import Model
# Define your model
class User(Model):
name: str
email: str
created_at: datetime
class Meta:
name = 'users'
schema = 'public'
# Create CRUD API automatically
class UserAPI(ModelView):
model = User
path = '/api/users'
# Optional: Add custom validation
async def validate_payload(self, data):
if 'email' not in data:
raise ValueError("Email is required")
return data
# Optional: Add custom callbacks
async def _post_callback(self, response, model):
# Send welcome email, log activity, etc.
pass
```
### WebSocket Support
Real-time features with built-in WebSocket support:
```python
from navigator import Application
from navigator.services.ws import WebSocketHandler
class ChatHandler(WebSocketHandler):
async def on_message(self, message):
# Broadcast message to all connected clients
await self.broadcast(message)
app = Application()
app.add_websockets()
app.router.add_websocket('/ws/chat', ChatHandler)
```
## 🔌 Extensions
Navigator's extension system allows you to add powerful features:
### Authentication Extension
```python
# Install: pip install navigator-auth
from navigator_auth import AuthConfig
class MyApp(Application):
def configure(self):
# Add JWT authentication
self.add_extension(AuthConfig, {
'secret_key': 'your-secret-key',
'algorithm': 'HS256',
'token_expiration': 3600
})
```
### Admin Interface
```python
# Coming soon: Django-style admin interface
from navigator.admin import admin_site
from .models import User, Product
admin_site.register(User)
admin_site.register(Product)
app.include_router(admin_site.router, prefix='/admin')
```
## 🛠️ CLI Tools
Navigator includes powerful CLI tools for development:
```bash
# Project management
nav init # Create new project
nav app create myapp # Create new application
# Development
nav run # Start development server
nav shell # Interactive shell
```
## 📦 Available Extensions
Navigator supports various optional dependencies:
```bash
# Performance optimizations
navigator-api[uvloop] # uvloop for better async performance
# Internationalization
navigator-api[locale] # Babel for i18n support
# Caching
navigator-api[memcache] # Memcached support
# Production deployment
navigator-api[gunicorn] # Gunicorn WSGI server
# All features
navigator-api[all] # Install all optional dependencies
```
## 🚀 Deployment
### AWS App Runner
Navigator includes built-in support for AWS App Runner deployment:
```yaml
# apprunner.yaml
version: 1.0
runtime: python3
build:
commands:
build:
- pip install -r requirements.txt
- python setup.py build_ext --inplace
run:
runtime-version: '3.11'
command: 'nav run --port 8080'
network:
port: 8080
env: PORT
```
### Docker
```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
RUN python setup.py build_ext --inplace
EXPOSE 8000
CMD ["nav", "run", "--port", "8000"]
```
## 📋 Requirements
- **Python**: 3.9+ (3.11+ recommended)
- **Dependencies**:
- aiohttp >= 3.10.0
- asyncio (built-in)
- uvloop >= 0.21.0 (optional, recommended)
## 🧪 Testing
```bash
# Install development dependencies
uv add --dev pytest pytest-asyncio coverage
# Run tests
pytest
# Run with coverage
pytest --cov=navigator tests/
```
## 📚 Documentation
- **Official Documentation**: [navigator-api.readthedocs.io](https://navigator-api.readthedocs.io) *(coming soon)*
- **API Reference**: Available in source code docstrings
- **Examples**: Check the [examples/](examples/) directory
- **Tutorial**: See [Quick Start](#-quick-start) section above
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Setup
```bash
# Clone the repository
git clone https://github.com/phenobarbital/navigator.git
cd navigator
# Create development environment
uv venv --python 3.11 .venv
source .venv/bin/activate
# Install development dependencies
uv sync --dev
# Install pre-commit hooks
pre-commit install
# Run tests
pytest
```
## 📜 License
Navigator is licensed under the **BSD 3-Clause License**. See [LICENSE](LICENSE) for details.
## 🙏 Credits
Navigator is built on top of these amazing projects:
- [aiohttp](https://docs.aiohttp.org/) - Async HTTP client/server framework
- [asyncio](https://docs.python.org/3/library/asyncio.html) - Asynchronous I/O framework
- [uvloop](https://github.com/MagicStack/uvloop) - Fast asyncio event loop
- [Jinja2](https://jinja.palletsprojects.com/) - Template engine
- [AsyncDB](https://github.com/phenobarbital/asyncdb) - Database connectivity
- [NavConfig](https://github.com/phenobarbital/navconfig) - Configuration management
## 🔗 Links
- **PyPI**: https://pypi.org/project/navigator-api/
- **GitHub**: https://github.com/phenobarbital/navigator
- **Issues**: https://github.com/phenobarbital/navigator/issues
- **Discussions**: https://github.com/phenobarbital/navigator/discussions
---
Made with ❤️ by the Navigator team. Built for the async future of web development.