Metadata-Version: 2.4
Name: navigator-api
Version: 2.14.10
Summary: Navigator: a batteries-included Web Framework based on aiohttp
Author-email: "Jesus Lara G." <jesuslarag@gmail.com>
Maintainer-email: "Jesus Lara G." <jesuslarag@gmail.com>
License: BSD-3-Clause
Project-URL: Homepage, https://github.com/phenobarbital/navigator
Project-URL: Documentation, https://navigator-api.readthedocs.io
Project-URL: Repository, https://github.com/phenobarbital/navigator.git
Project-URL: Bug Tracker, https://github.com/phenobarbital/navigator/issues
Project-URL: Changelog, https://github.com/phenobarbital/navigator/blob/main/CHANGELOG.md
Project-URL: Funding, https://paypal.me/phenobarbital
Keywords: framework,asyncio,uvloop,aiohttp,navigator,web,async
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: License :: OSI Approved :: BSD License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Cython>=3.0.11
Requires-Dist: aiohttp[speedups]>=3.10.0
Requires-Dist: PySocks>=1.7.1
Requires-Dist: asn1crypto>=1.4.0
Requires-Dist: jinja2>=3.1.6
Requires-Dist: psycopg2-binary>=2.9.9
Requires-Dist: aiosocks>=0.2.6
Requires-Dist: python-slugify>=8.0.1
Requires-Dist: proxylists>=0.12.4
Requires-Dist: httpx<=0.28.1,>=0.25.0
Requires-Dist: beautifulsoup4>=4.12.3
Requires-Dist: polyline>=2.0.1
Requires-Dist: cartopy>=0.22.0
Requires-Dist: matplotlib>=3.8.3
Requires-Dist: sockjs>=0.11.0
Requires-Dist: aiohttp-sse>=2.2.0
Requires-Dist: asyncdb[boto3,default,uvloop]>=2.13.1
Requires-Dist: pyarrow<21.0.0,>=17.0.0
Requires-Dist: navconfig[default]>=1.7.10
Requires-Dist: aiohttp-cors==0.8.1
Requires-Dist: brotli>=1.1.0
Requires-Dist: brotlicffi>=1.1.0.0
Requires-Dist: aiofile>=3.9.0
Requires-Dist: psutil>=6.0.0
Requires-Dist: aiormq>=6.8.1
Requires-Dist: Faker>=22.2.0
Requires-Dist: google-cloud-core<=2.4.3,>=2.4.0
Requires-Dist: google-cloud-storage<=3.1.0,>=2.19.0
Requires-Dist: cloudpickle>=3.0.0
Requires-Dist: async-timeout>=4.0.3
Requires-Dist: msgpack>=1.1.0
Requires-Dist: babel<=2.17.0,>=2.9.1
Requires-Dist: watchdog>=6.0.0
Requires-Dist: navigator-session>=0.6.5
Requires-Dist: navigator-auth>=0.15.8
Requires-Dist: python-datamodel>=0.10.19
Provides-Extra: locale
Requires-Dist: Babel<=2.17.0,>=2.9.1; extra == "locale"
Provides-Extra: memcache
Requires-Dist: aiomcache>=0.8.2; extra == "memcache"
Provides-Extra: uvloop
Requires-Dist: uvloop>=0.21.0; extra == "uvloop"
Provides-Extra: gunicorn
Requires-Dist: gunicorn>=23.0.0; extra == "gunicorn"
Provides-Extra: production
Requires-Dist: uvloop>=0.21.0; extra == "production"
Requires-Dist: gunicorn>=23.0.0; extra == "production"
Provides-Extra: dev
Requires-Dist: pytest>=5.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-xdist>=2.5.0; extra == "dev"
Requires-Dist: pytest-assume>=2.4.0; extra == "dev"
Requires-Dist: coverage>=6.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: pylint>=2.17.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Provides-Extra: build
Requires-Dist: setuptools>=67.6.1; extra == "build"
Requires-Dist: Cython==3.0.11; extra == "build"
Requires-Dist: wheel>=0.44.0; extra == "build"
Requires-Dist: build>=0.10.0; extra == "build"
Requires-Dist: setuptools_scm[toml]>=6.0; extra == "build"
Provides-Extra: test
Requires-Dist: pytest>=5.4.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Requires-Dist: pytest-xdist>=2.5.0; extra == "test"
Requires-Dist: pytest-assume>=2.4.0; extra == "test"
Requires-Dist: coverage>=6.0; extra == "test"
Requires-Dist: aioresponses>=0.7.4; extra == "test"
Requires-Dist: asynctest>=0.13.0; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx>=6.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "docs"
Requires-Dist: myst-parser>=1.0.0; extra == "docs"
Provides-Extra: all
Requires-Dist: navigator-api[gunicorn,locale,memcache,uvloop]; extra == "all"
Dynamic: license-file

# ⚡ Navigator Framework

[![PyPI version](https://badge.fury.io/py/navigator-api.svg)](https://pypi.org/project/navigator-api/)
[![Python](https://img.shields.io/pypi/pyversions/navigator-api.svg)](https://pypi.org/project/navigator-api/)
[![License](https://img.shields.io/badge/license-BSD-blue.svg)](https://github.com/phenobarbital/navigator/blob/main/LICENSE)
[![Downloads](https://pepy.tech/badge/navigator-api)](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.
