Introduction

MicroPie is a fast, lightweight, modern Python web framework built on ASGI for asynchronous web applications. Designed for flexibility and simplicity, it enables high-concurrency web apps with built-in WebSockets, session management, middleware, lifecycle event handling, and optional template rendering. Extensible for integration with ASGI-compatible tools like python-socketio and ServeStatic, it’s inspired by CherryPy and licensed under the BSD 3-Clause License.

Key Features

📬 Routing: Automatic mapping of URLs to functions with support for dynamic and query parameters.
🔑 Sessions: Simple, pluggable session management using cookies.
🎨 Templates: Jinja2, if installed, for rendering dynamic HTML pages.
🚧 Middleware: Support for custom request middleware enabling functions like rate limiting, authentication, logging, and more.
💨 Real-Time Communication: Built-in WebSocket support for real-time, bidirectional communication.
☀️ ASGI-Powered: Built with asynchronous support for modern web servers like Uvicorn, Hypercorn, and Daphne, enabling high concurrency.
☁️ Lightweight Design: Only optional dependencies for flexibility and faster development/deployment.
👶 Lifecycle Events: ASGI lifespan event handling for startup and shutdown tasks (e.g., database initialization).
🏁 Competitive Performance: Check out how MicroPie compares to other popular ASGI frameworks below!

Useful Links

Homepage: patx.github.io/micropie
Official Documentation: micropie.readthedocs.io
PyPI Page: pypi.org/project/MicroPie
GitHub Project: github.com/patx/micropie
File Issue/Request: github.com/patx/micropie/issues
Example Applications: github.com/patx/micropie/tree/main/examples
Introduction Lightning Talk: Introduction to MicroPie on YouTube

Latest Release Notes

View the latest release notes here. It is useful to check release notes each time a new version of MicroPie is published. Any breaking changes (rare, but do happen) also appear here.

Installing MicroPie
Getting Started
Core Features
Learn by Examples
Comparisons
Benchmark Results
Suggestions or Feedback?

Documentation Roadmap

Tutorials: quick start, routing, and websockets.
How-to Guides: Practical recipes for sessions, middleware, streaming, and more.
Reference: Full API docs for App, Request, WebSocket, and related classes.
What’s New: Version-by-version highlights at What's new in MicroPie.

Installing MicroPie

Installation Profiles

Install whichever profile fits your use case:

| Profile | Command | Includes | |---------|---------|----------| | Minimal | pip install micropie | Core framework only | | Standard | pip install micropie[standard] | Core + jinja2 + multipart | | All | pip install micropie[all] | Standard + orjson + uvicorn |

If you are just getting started, use standard:

pip install micropie[standard]

For an ultra-minimal setup, you can also use the standalone script (development version):

micropie.py

Place it in your project directory and you are ready to go. Install optional packages only if needed:

pip install jinja2 multipart

Use jinja2 for _render_template and multipart for multipart file/form parsing.

By default MicroPie will use the json library from Python's standard library. If you need faster performance you can use orjson. MicroPie will use orjson if installed by default. If it is not installed, MicroPie will fallback to json. This means with or without orjson installed MicroPie will still handle JSON requests/responses the same. To install orjson and take advantage of its performance, use:

pip install orjson

Install an ASGI Web Server

In order to test and deploy your apps you will need an ASGI web server like Uvicorn, Hypercorn, or Daphne.

If you installed micropie[all] Uvicorn should be ready to use. If you didn't install all of MicroPie's optional dependencies, use:

pip install uvicorn

Getting Started

Create Your First ASGI App

Save the following as app.py:

from micropie import App

class MyApp(App):
    async def index(self):
        return "Welcome to MicroPie ASGI."

app = MyApp()

Run the server with:

uvicorn app:app

Access your app at http://127.0.0.1:8000.

Core Features

Route Handlers

MicroPie's route handlers map URLs to methods in your App subclass. Handler input can come from automatic argument binding or request helper methods.

Key Points

Automatic Mapping: URLs map to method names (e.g., /greet → greet, / → index).
Private Methods: Methods starting with _ (e.g., _private_method) are private and inaccessible via URLs, returning 404. Security Note: Use _ for sensitive methods to prevent external access.
Automatic Argument Binding: Handler args are populated from path/query/body data by parameter name.
Request Helpers:
- self.request.query(name, default) for query-string values.
- self.request.form(name, default) for form/body values.
- self.request.json() for full JSON payloads, or self.request.json(name, default) for a key lookup.
HTTP Methods: Handlers support all methods (GET, POST, etc.). Check self.request.method to handle specific methods.
Responses:
- String, bytes, or JSON-serializable object.
- Tuple: (status_code, body) or (status_code, body, headers).
- Sync/async generator for streaming.

Advanced Usage

Custom Routing: Use middleware for explicit routing (see examples/middleware and examples/explicit_routing).
Errors: Auto-handled 404/400; customize via middleware.
Dynamic Params: Use *args for multiple path parameters.

Automatic Argument Binding

MicroPie can bind handler parameters directly from incoming request data:

class MyApp(App):
    async def greet(self, name="Guest"):
        return f"Hello, {name}!"

    async def submit(self, username="Anonymous"):
        return f"Submitted by: {username}"

Access:

http://127.0.0.1:8000/greet/Alice returns Hello, Alice!.
http://127.0.0.1:8000/greet?name=Alice also returns Hello, Alice!.
POST application/x-www-form-urlencoded to /submit with username=bob returns Submitted by: bob.
POST application/json to /submit with {"username": "bob"} also returns Submitted by: bob.

Helper-Based Request Access

Use helper methods for query, form, and JSON payload access:

class MyApp(App):
    async def greet(self):
        name = self.request.query("name", "Guest")
        return f"Hello, {name}!"

    async def submit(self):
        username = self.request.form("username", "Anonymous")
        return f"Submitted by: {username}"

    async def submit_json(self):
        data = self.request.json()
        username = self.request.json("username", "Anonymous")
        return {"submitted_by": username, "raw": data}