navigator-api
Advanced tools
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.
# Using uv (recommended)
uv add navigator-api[uvloop,locale]
# Using pip
pip install navigator-api[uvloop,locale]
# Create a new Navigator project
nav init
# Create an application
nav app create myapp
# Run the development server
nav run --debug --reload
# 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())
Navigator provides powerful class-based views for building APIs:
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
Navigator uses NavConfig for unified configuration management:
# 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
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
# apps/users/__init__.py
from navigator.applications import AppConfig
class UsersConfig(AppConfig):
name = 'users'
path = '/api/users'
def ready(self):
# App initialization code
pass
Navigator integrates seamlessly with AsyncDB for database operations:
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
Real-time features with built-in WebSocket support:
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)
Navigator's extension system allows you to add powerful features:
# 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
})
# 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')
Navigator includes powerful CLI tools for development:
# Project management
nav init # Create new project
nav app create myapp # Create new application
# Development
nav run # Start development server
nav shell # Interactive shell
Navigator supports various optional dependencies:
# 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
Navigator includes built-in support for AWS App Runner deployment:
# 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
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"]
# Install development dependencies
uv add --dev pytest pytest-asyncio coverage
# Run tests
pytest
# Run with coverage
pytest --cov=navigator tests/
We welcome contributions! Please see our Contributing Guide for details.
# 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
Navigator is licensed under the BSD 3-Clause License. See LICENSE for details.
Navigator is built on top of these amazing projects:
Made with ❤️ by the Navigator team. Built for the async future of web development.
FAQs
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket CEO Feross Aboukhadijeh joins Software Engineering Daily to discuss modern software supply chain attacks and rising AI-driven security risks.
Security News
GitHub has revoked npm classic tokens for publishing; maintainers must migrate, but OpenJS warns OIDC trusted publishing still has risky gaps for critical projects.
Security News
Rust’s crates.io team is advancing an RFC to add a Security tab that surfaces RustSec vulnerability and unsoundness advisories directly on crate pages.