{"id":15686271,"url":"https://github.com/phenobarbital/navigator","last_synced_at":"2026-04-29T23:09:00.280Z","repository":{"id":37051534,"uuid":"282766883","full_name":"phenobarbital/navigator","owner":"phenobarbital","description":"Python Framework for build Asynchronous APIs but using friendly syntax.","archived":false,"fork":false,"pushed_at":"2025-10-07T21:32:47.000Z","size":2172,"stargazers_count":9,"open_issues_count":0,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-10-07T23:32:29.389Z","etag":null,"topics":["aiohttp","aiolibs","asyncio","asyncpg","python","uvloop"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phenobarbital.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-07-27T01:38:02.000Z","updated_at":"2025-10-07T21:32:29.000Z","dependencies_parsed_at":"2023-12-16T01:26:58.150Z","dependency_job_id":"752bf211-56ea-4d82-bfd9-9e32da2c6926","html_url":"https://github.com/phenobarbital/navigator","commit_stats":{"total_commits":996,"total_committers":7,"mean_commits":"142.28571428571428","dds":0.07530120481927716,"last_synced_commit":"c5ac7322f66826e4871bdf9898ef54f380dcfc9f"},"previous_names":[],"tags_count":287,"template":false,"template_full_name":null,"purl":"pkg:github/phenobarbital/navigator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenobarbital%2Fnavigator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenobarbital%2Fnavigator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenobarbital%2Fnavigator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenobarbital%2Fnavigator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phenobarbital","download_url":"https://codeload.github.com/phenobarbital/navigator/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phenobarbital%2Fnavigator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28796962,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T01:07:07.743Z","status":"online","status_checked_at":"2026-01-27T02:00:07.755Z","response_time":168,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aiohttp","aiolibs","asyncio","asyncpg","python","uvloop"],"created_at":"2024-10-03T17:37:14.357Z","updated_at":"2026-01-27T02:10:10.429Z","avatar_url":"https://github.com/phenobarbital.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ⚡ Navigator Framework\n\n[![PyPI version](https://badge.fury.io/py/navigator-api.svg)](https://pypi.org/project/navigator-api/)\n[![Python](https://img.shields.io/pypi/pyversions/navigator-api.svg)](https://pypi.org/project/navigator-api/)\n[![License](https://img.shields.io/badge/license-BSD-blue.svg)](https://github.com/phenobarbital/navigator/blob/main/LICENSE)\n[![Downloads](https://pepy.tech/badge/navigator-api)](https://pepy.tech/project/navigator-api)\n\n\u003e **A batteries-included async web framework built on aiohttp** 🚀\n\nNavigator 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.\n\n## ✨ Key Features\n\n- **⚡ Lightning Fast**: Built on aiohttp + uvloop for maximum performance\n- **🔋 Batteries Included**: Authentication, WebSockets, templates, database connections, and more\n- **🏗️ Django-style Apps**: Organize code with modular, reusable application components\n- **🌐 Multi-tenant Ready**: Built-in sub-domain support for SaaS applications\n- **🔧 Centralized Config**: Unified configuration management with NavConfig\n- **🔌 Auto-Connections**: Automatic database connection handling with AsyncDB\n- **📝 Class-based Views**: Powerful CRUD operations with ModelViews\n- **🎯 Extensible**: Plugin architecture for adding custom features\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\n# Using uv (recommended)\nuv add navigator-api[uvloop,locale]\n\n# Using pip\npip install navigator-api[uvloop,locale]\n```\n\n### Create Your First App\n\n```bash\n# Create a new Navigator project\nnav init\n\n# Create an application\nnav app create myapp\n\n# Run the development server\nnav run --debug --reload\n```\n\n### Hello Navigator\n\n```python\n# app.py\nimport asyncio\nimport uvloop\nfrom navigator import Application\nfrom aiohttp import web\n\nasync def hello(request):\n    return web.Response(text=\"Hello Navigator! 🚀\")\n\nasync def main():\n    # Set uvloop as the event loop policy\n    asyncio.set_event_loop_policy(uvloop.EventLoopPolicy())\n\n    # Create Navigator application\n    app = Application(enable_jinja2=True)\n\n    # Add routes\n    app.router.add_get('/', hello)\n\n    # Enable WebSocket support\n    app.add_websockets()\n\n    # Setup and run\n    return app.setup()\n\nif __name__ == '__main__':\n    asyncio.run(main())\n```\n\n## 🏗️ Architecture\n\n### Class-based Views\n\nNavigator provides powerful class-based views for building APIs:\n\n```python\nfrom navigator.views import BaseView, ModelView\nfrom aiohttp import web\nfrom datamodel import BaseModel\n\nclass UserView(BaseView):\n    async def get(self):\n        return web.json_response({\"users\": []})\n\n    async def post(self):\n        data = await self.request.json()\n        # Process user creation\n        return web.json_response({\"status\": \"created\"})\n\n# Model-based CRUD operations\nclass User(BaseModel):\n    name: str\n    email: str\n    age: int\n\nclass UserModelView(ModelView):\n    model = User\n    path = '/api/users'\n\n    # Automatic CRUD operations:\n    # GET /api/users - List all users\n    # GET /api/users/{id} - Get specific user\n    # POST /api/users - Create user\n    # PUT /api/users/{id} - Update user\n    # DELETE /api/users/{id} - Delete user\n```\n\n### Centralized Configuration\n\nNavigator uses [NavConfig](https://github.com/phenobarbital/navconfig) for unified configuration management:\n\n```python\n# settings/settings.py\nfrom navconfig import config\n\n# Database configuration\nDATABASE_URL = config.get('DATABASE_URL', 'postgresql://user:pass@localhost/db')\n\n# Cache configuration\nREDIS_URL = config.get('REDIS_URL', 'redis://localhost:6379')\n\n# App configuration\nDEBUG = config.getboolean('DEBUG', False)\nSECRET_KEY = config.get('SECRET_KEY', required=True)\n\n# Multiple environment support\nENV = config.get('ENV', 'development')  # development, staging, production\n```\n\n### Django-style Applications\n\nOrganize your code with modular applications:\n\n```\nmyproject/\n├── apps/\n│   ├── users/\n│   │   ├── __init__.py\n│   │   ├── views.py\n│   │   ├── models.py\n│   │   ├── urls.py\n│   │   └── templates/\n│   └── products/\n│       ├── __init__.py\n│       ├── views.py\n│       └── models.py\n├── settings/\n│   └── settings.py\n└── main.py\n```\n\n```python\n# apps/users/__init__.py\nfrom navigator.applications import AppConfig\n\nclass UsersConfig(AppConfig):\n    name = 'users'\n    path = '/api/users'\n\n    def ready(self):\n        # App initialization code\n        pass\n```\n\n### Database Integration\n\nNavigator integrates seamlessly with [AsyncDB](https://github.com/phenobarbital/asyncdb) for database operations:\n\n```python\nfrom navigator.views import ModelView\nfrom asyncdb.models import Model\n\n# Define your model\nclass User(Model):\n    name: str\n    email: str\n    created_at: datetime\n\n    class Meta:\n        name = 'users'\n        schema = 'public'\n\n# Create CRUD API automatically\nclass UserAPI(ModelView):\n    model = User\n    path = '/api/users'\n\n    # Optional: Add custom validation\n    async def validate_payload(self, data):\n        if 'email' not in data:\n            raise ValueError(\"Email is required\")\n        return data\n\n    # Optional: Add custom callbacks\n    async def _post_callback(self, response, model):\n        # Send welcome email, log activity, etc.\n        pass\n```\n\n### WebSocket Support\n\nReal-time features with built-in WebSocket support:\n\n```python\nfrom navigator import Application\nfrom navigator.services.ws import WebSocketHandler\n\nclass ChatHandler(WebSocketHandler):\n    async def on_message(self, message):\n        # Broadcast message to all connected clients\n        await self.broadcast(message)\n\napp = Application()\napp.add_websockets()\napp.router.add_websocket('/ws/chat', ChatHandler)\n```\n\n## 🔌 Extensions\n\nNavigator's extension system allows you to add powerful features:\n\n### Authentication Extension\n\n```python\n# Install: pip install navigator-auth\nfrom navigator_auth import AuthConfig\n\nclass MyApp(Application):\n    def configure(self):\n        # Add JWT authentication\n        self.add_extension(AuthConfig, {\n            'secret_key': 'your-secret-key',\n            'algorithm': 'HS256',\n            'token_expiration': 3600\n        })\n```\n\n### Admin Interface\n\n```python\n# Coming soon: Django-style admin interface\nfrom navigator.admin import admin_site\nfrom .models import User, Product\n\nadmin_site.register(User)\nadmin_site.register(Product)\n\napp.include_router(admin_site.router, prefix='/admin')\n```\n\n## 🛠️ CLI Tools\n\nNavigator includes powerful CLI tools for development:\n\n```bash\n# Project management\nnav init                        # Create new project\nnav app create myapp            # Create new application\n\n# Development\nnav run                       # Start development server\nnav shell                     # Interactive shell\n\n```\n\n## 📦 Available Extensions\n\nNavigator supports various optional dependencies:\n\n```bash\n# Performance optimizations\nnavigator-api[uvloop]         # uvloop for better async performance\n\n# Internationalization\nnavigator-api[locale]         # Babel for i18n support\n\n# Caching\nnavigator-api[memcache]       # Memcached support\n\n# Production deployment\nnavigator-api[gunicorn]       # Gunicorn WSGI server\n\n# All features\nnavigator-api[all]            # Install all optional dependencies\n```\n\n## 🚀 Deployment\n\n### AWS App Runner\n\nNavigator includes built-in support for AWS App Runner deployment:\n\n```yaml\n# apprunner.yaml\nversion: 1.0\nruntime: python3\nbuild:\n  commands:\n    build:\n      - pip install -r requirements.txt\n      - python setup.py build_ext --inplace\nrun:\n  runtime-version: '3.11'\n  command: 'nav run --port 8080'\n  network:\n    port: 8080\n    env: PORT\n```\n\n### Docker\n\n```dockerfile\nFROM python:3.11-slim\n\nWORKDIR /app\nCOPY requirements.txt .\nRUN pip install -r requirements.txt\n\nCOPY . .\nRUN python setup.py build_ext --inplace\n\nEXPOSE 8000\nCMD [\"nav\", \"run\", \"--port\", \"8000\"]\n```\n\n## 📋 Requirements\n\n- **Python**: 3.9+ (3.11+ recommended)\n- **Dependencies**:\n  - aiohttp \u003e= 3.10.0\n  - asyncio (built-in)\n  - uvloop \u003e= 0.21.0 (optional, recommended)\n\n## 🧪 Testing\n\n```bash\n# Install development dependencies\nuv add --dev pytest pytest-asyncio coverage\n\n# Run tests\npytest\n\n# Run with coverage\npytest --cov=navigator tests/\n```\n\n## 📚 Documentation\n\n- **Official Documentation**: [navigator-api.readthedocs.io](https://navigator-api.readthedocs.io) *(coming soon)*\n- **API Reference**: Available in source code docstrings\n- **Examples**: Check the [examples/](examples/) directory\n- **Tutorial**: See [Quick Start](#-quick-start) section above\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/phenobarbital/navigator.git\ncd navigator\n\n# Create development environment\nuv venv --python 3.11 .venv\nsource .venv/bin/activate\n\n# Install development dependencies\nuv sync --dev\n\n# Install pre-commit hooks\npre-commit install\n\n# Run tests\npytest\n```\n\n## 📜 License\n\nNavigator is licensed under the **BSD 3-Clause License**. See [LICENSE](LICENSE) for details.\n\n## 🙏 Credits\n\nNavigator is built on top of these amazing projects:\n\n- [aiohttp](https://docs.aiohttp.org/) - Async HTTP client/server framework\n- [asyncio](https://docs.python.org/3/library/asyncio.html) - Asynchronous I/O framework\n- [uvloop](https://github.com/MagicStack/uvloop) - Fast asyncio event loop\n- [Jinja2](https://jinja.palletsprojects.com/) - Template engine\n- [AsyncDB](https://github.com/phenobarbital/asyncdb) - Database connectivity\n- [NavConfig](https://github.com/phenobarbital/navconfig) - Configuration management\n\n## 🔗 Links\n\n- **PyPI**: https://pypi.org/project/navigator-api/\n- **GitHub**: https://github.com/phenobarbital/navigator\n- **Issues**: https://github.com/phenobarbital/navigator/issues\n- **Discussions**: https://github.com/phenobarbital/navigator/discussions\n\n---\n\nMade with ❤️ by the Navigator team. Built for the async future of web development.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphenobarbital%2Fnavigator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphenobarbital%2Fnavigator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphenobarbital%2Fnavigator/lists"}