Nexios

Appearance

Getting Started with Nexios ​

Welcome to Nexios! This comprehensive guide will walk you through everything you need to know to get started with Nexios, a modern, async-first Python web framework designed for high-performance applications.

What is Nexios? ​

Nexios is a cutting-edge Python web framework that combines the best of modern web development practices with exceptional performance. Built on ASGI (Asynchronous Server Gateway Interface), Nexios provides a clean, intuitive API that makes building scalable web applications straightforward and enjoyable.

Key Features ​

  • 🚀 High Performance: Built on ASGI for exceptional speed and concurrency
  • 🔄 Async-First: Native async/await support throughout the framework
  • 🛡️ Type Safe: Full type hint support for better development experience
  • 📚 Developer Friendly: Intuitive API with excellent documentation
  • 🔧 Production Ready: Built-in security, testing, and deployment features
  • 🎯 Flexible: Extensive customization options for any use case
  • 📖 OpenAPI Ready: Automatic API documentation generation
  • 🔌 Extensible: Easy to add custom functionality and middleware

Why Choose Nexios? ​

Nexios stands out from other Python web frameworks for several reasons:

Performance: Unlike traditional WSGI frameworks, Nexios leverages ASGI to handle thousands of concurrent connections efficiently. This means your application can serve more users with fewer resources.

Simplicity: The API is designed to be intuitive and easy to learn. You can start building applications quickly without getting lost in complex abstractions.

Modern Python: Nexios fully embraces modern Python features like type hints, async/await, and dataclasses, making your code more maintainable and less error-prone.

Production Features: Built-in support for authentication, CORS, rate limiting, and other production-ready features means you can focus on your business logic rather than infrastructure concerns.

Prerequisites ​

Before you begin with Nexios, ensure you have the following:

System Requirements ​

  • Python 3.9 or higher - Nexios requires modern Python features
  • pip, poetry, or uv - For package management
  • Basic understanding of async/await - While not strictly required, it helps

Python Version Requirements

Nexios requires Python 3.9+ because it leverages several modern Python features:

  • Type annotations with generics (Python 3.9+)
  • Async context managers (Python 3.7+)
  • Pattern matching (Python 3.10+)
  • Union types and other type system improvements (Python 3.9+)
  • Better async/await support (Python 3.7+)

If you're using an older Python version, consider upgrading to take advantage of these features.

Async/Await Fundamentals

If you're new to async/await in Python, here are the key concepts you'll encounter:

  • async def: Defines an asynchronous function that can be awaited
  • await: Waits for an async operation to complete without blocking
  • async with: Asynchronous context manager for resource management
  • async for: Asynchronous iteration over async iterables

Nexios uses async/await extensively for handling concurrent requests efficiently. Don't worry if this is new to you - we'll cover it in detail throughout the documentation.

Installation ​

Nexios can be installed using any Python package manager. We recommend using uv for the fastest and most reliable experience.

uv is a modern Python package manager that's significantly faster than traditional tools. It's a drop-in replacement for pip, pip-tools, and virtualenv.

bash
# Install uv globally
pip install uv

# Create a new project directory
mkdir my-nexios-app
cd my-nexios-app

# Create a virtual environment and install Nexios
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install nexios
bash
# Install uv and Nexios in one command
uv init my-nexios-app
cd my-nexios-app
uv add nexios

Alternative Package Managers ​

bash
# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install Nexios
pip install nexios
bash
# Create a new project
poetry new my-nexios-app
cd my-nexios-app

# Add Nexios
poetry add nexios

# Activate environment
poetry shell
bash
# Create a new project directory
mkdir my-nexios-app
cd my-nexios-app

# Initialize project
pipenv install nexios

# Activate environment
pipenv shell

Package Manager Comparison

uv (Recommended):

  • ⚡ Fastest installation and dependency resolution
  • 🔧 Built-in virtual environment management
  • 🔄 Compatible with pip and pip-tools
  • 📦 Excellent for both development and production
  • 🚀 Written in Rust for maximum performance

pip:

  • 📚 Standard Python package manager
  • 🔧 Widely supported and documented
  • ✅ Good for simple projects
  • 🐌 Slower than modern alternatives

poetry:

  • 🎯 Advanced dependency management
  • 📁 Built-in project scaffolding
  • 🔒 Lock file for reproducible builds
  • 🏗️ Good for complex projects

pipenv:

  • 🔗 Combines pip and virtualenv
  • 🔄 Automatic dependency resolution
  • 🛠️ Good for development workflows

Virtual Environments

Always use virtual environments to isolate your project dependencies. This prevents conflicts between different projects and keeps your system Python clean.

Benefits of virtual environments:

  • 🛡️ Isolate project dependencies
  • 🚫 Avoid version conflicts
  • 📤 Easy project sharing and deployment
  • 🧹 Clean system Python installation
  • 🔄 Reproducible builds

Creating virtual environments:

bash
# With uv (recommended)
uv venv

# With venv (built-in)
python -m venv venv

# With virtualenv
virtualenv venv

Your First Nexios Application ​

Now that you have Nexios installed, let's create your first application. We'll start with a simple example and gradually build up to more complex features.

Basic Application ​

Create a file named main.py:

python
from nexios import NexiosApp
import uvicorn 

# Create a new Nexios application
app = NexiosApp()

# Define a simple route
@app.get("/")
async def hello_world(request, response):
    return response.json({
        "message": "Hello from Nexios!",
        "status": "success"
    })

# If you forget to use async def for your handler, Nexios will raise an error at startup.

# If you define two routes with the same path and method, Nexios will raise a conflict error at startup.

# Run the application
if __name__ == "__main__":
    uvicorn.run("main:app")

Running Your Application ​

You can run your Nexios application in several ways:

bash
python main.py
bash
uvicorn main:app --reload --host 127.0.0.1 --port 8000
bash
hypercorn main:app --reload --bind 127.0.0.1:8000

Development Server

For development, we recommend using uvicorn with the --reload flag. This will automatically restart your application when you make changes to your code.

Benefits of uvicorn:

  • 🔄 Auto-reload on code changes
  • ⚡ Fast startup time
  • 🐛 Good error reporting
  • 📊 Built-in logging
  • 🔧 Easy configuration

Testing Your Application ​

Once your application is running, you can test it:

bash
# Test with curl
curl http://localhost:8000/

# Expected response:
# {"message": "Hello from Nexios!", "status": "success"}

# If the server is not running or the port is wrong, you'll get a connection error.

Or simply open your browser and navigate to http://localhost:8000/.

Understanding the Code ​

Let's break down what's happening in our first application:

1. Application Creation ​

python
from nexios import NexiosApp

app = NexiosApp()
  • NexiosApp() creates a new web application instance
  • This instance will handle all incoming HTTP requests
  • It's configured with sensible defaults for development

2. Route Definition ​

python
@app.get("/")
async def hello_world(request, response):
    return response.json({
        "message": "Hello from Nexios!",
        "status": "success"
    })

# If you forget to return a response, Nexios will raise an error indicating the handler did not return a response object.
  • @app.get("/") decorates a function to handle GET requests to the root path
  • The function must be async - this is a strict requirement in Nexios
  • request and response are automatically provided by Nexios
  • response.json() creates a JSON response with the specified data

3. Application Execution ​

python
if __name__ == "__main__":
    app.run()

# If you run this in production, make sure to use uvicorn or another ASGI server for better performance and reliability.

Next Steps ​

Congratulations! You've successfully created and run your first Nexios application. Here's what you can explore next:

1. Routing Fundamentals ​

Learn how to create different types of routes and handle various HTTP methods:

2. Request and Response Handling ​

Understand how to work with incoming requests and outgoing responses:

3. Core Concepts ​

Dive deeper into Nexios architecture and concepts:

4. Advanced Features ​

Explore more advanced features as you become comfortable with the basics:

Common Questions ​

Why do all handlers need to be async? ​

Nexios is built on ASGI, which requires async handlers for optimal performance. Async handlers allow Nexios to handle multiple requests concurrently without blocking, leading to better performance and scalability.

Can I use synchronous code in my handlers? ​

While handlers themselves must be async, you can call synchronous functions within them. However, for I/O operations (database queries, HTTP requests, file operations), you should use async alternatives for better performance.

If you call a blocking (sync) function in an async handler, your app may hang or perform poorly. Use run_in_executor for heavy sync work:

python
import asyncio

def blocking_task():
    # Some CPU-bound or blocking code
    ...

@app.get("/heavy")
async def heavy_route(request, response):
    result = await asyncio.get_running_loop().run_in_executor(None, blocking_task)
    return response.json({"result": result})

What happens if I pass invalid input or miss a required parameter? ​

If a required parameter is missing or invalid, Nexios will return a 422 error:

python
@app.get("/items/{item_id}")
async def get_item(request, response, item_id: int):
    return response.json({"item_id": item_id})

# GET /items/abc will return a 422 Unprocessable Entity

What if my middleware fails? ​

If your middleware raises an exception, it will interrupt the request and return a 500 error. Use try/except in middleware for graceful error handling:

python
from nexios.middleware import BaseMiddleware


async def FailingMiddleware(self, request, response, call_next):
    try:
        # Your logic here
        return await call_next()
    except Exception as exc:
        return response.json({"error": str(exc)}, status_code=500)

app.add_middleware(FailingMiddleware)

What if I try to dynamically import a handler that doesn't exist? ​

If a dynamically imported handler does not exist or fails to import, Nexios will raise an ImportError at startup.

What if my custom path converter fails? ​

If your custom converter raises a ValueError, Nexios will return a 422 error with your message.

How does Nexios compare to FastAPI/Django/Flask? ​

Nexios offers a unique combination of simplicity and performance:

  • vs FastAPI: Simpler API, less boilerplate, easier learning curve
  • vs Django: Lighter weight, more flexible, better for APIs
  • vs Flask: Async-first, better performance, modern Python features

What's the difference between app.run() and using uvicorn directly? ​

app.run() is a convenience method that starts a development server. For production, you should use uvicorn, hypercorn, or another ASGI server directly for better control and performance.

Getting Help ​

If you run into issues or have questions:

  1. Check the documentation - This guide and the other documentation pages
  2. Look at examples - The examples/ directory contains working code
  3. Search existing issues - Check the GitHub repository for similar problems
  4. Ask the community - Join discussions on GitHub or other forums

Remember, everyone starts somewhere! Don't hesitate to ask questions and experiment with the code. The Nexios community is here to help you succeed.

Now that you have the basics down, let's explore more advanced features. Start with the Routing Guide to learn how to create more complex applications, or jump into Core Concepts to understand how Nexios works under the hood.