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.

Recommended: Using uv

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.

Install uvAlternative: Direct installation

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

pippoetrypipenv

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"
    })

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

Running Your Application

You can run your Nexios application in several ways:

Direct executionWith uvicorn (recommended)With hypercorn

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"}

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"
    })

@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()

app.run() starts the development server
This is equivalent to running with uvicorn directly

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:

Routing Guide - Complete routing system overview
HTTP Methods - GET, POST, PUT, DELETE, etc.
Path Parameters - Dynamic URL segments

2. Request and Response Handling

Understand how to work with incoming requests and outgoing responses:

Request Information - Accessing request data
Sending Responses - Different response types
Request Inputs - Query parameters, headers, etc.

3. Core Concepts

Dive deeper into Nexios architecture and concepts:

Core Concepts - Framework architecture overview
Async Python - Understanding async/await
Configuration - Application configuration

4. Advanced Features

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

Middleware - Request/response processing
Authentication - User authentication and authorization
WebSockets - Real-time communication
Templating - HTML template rendering

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.

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:

Check the documentation - This guide and the other documentation pages
Look at examples - The examples/ directory contains working code
Search existing issues - Check the GitHub repository for similar problems
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.

Getting Started with Nexios ​

What is Nexios? ​

Key Features ​

Why Choose Nexios? ​

Prerequisites ​

System Requirements ​

Installation ​

Recommended: Using uv ​

Alternative Package Managers ​

Your First Nexios Application ​

Basic Application ​

Running Your Application ​

Testing Your Application ​

Understanding the Code ​

1. Application Creation ​

2. Route Definition ​

3. Application Execution ​

Next Steps ​

1. Routing Fundamentals ​

2. Request and Response Handling ​

3. Core Concepts ​

4. Advanced Features ​

Common Questions ​

Why do all handlers need to be async? ​

Can I use synchronous code in my handlers? ​

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

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

Getting Help ​

Getting Started with Nexios

What is Nexios?

Key Features

Why Choose Nexios?

Prerequisites

System Requirements

Installation

Recommended: Using uv

Alternative Package Managers

Your First Nexios Application

Basic Application

Running Your Application

Testing Your Application

Understanding the Code

1. Application Creation

2. Route Definition

3. Application Execution

Next Steps

1. Routing Fundamentals

2. Request and Response Handling

3. Core Concepts

4. Advanced Features

Common Questions

Why do all handlers need to be async?

Can I use synchronous code in my handlers?

How does Nexios compare to FastAPI/Django/Flask?

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

Getting Help