Skip to content

Latest commit

 

History

History
193 lines (152 loc) · 8.68 KB

README.md

File metadata and controls

193 lines (152 loc) · 8.68 KB

Logo

Introduction

MicroPie is a fast, lightweight, modern Python web framework that supports asynchronous web applications. Designed with flexibility and simplicity in mind, MicroPie enables you to handle high-concurrency applications with ease while allowing natural integration with external tools like Socket.IO for real-time communication.

Key Features

  • 🔄 Routing: Automatic mapping of URLs to functions with support for dynamic and query parameters.
  • 🔒 Sessions: Simple session management using cookies.
  • 🎨 Templates: Jinja2, if installed, for rendering dynamic HTML pages.
  • ✨ ASGI-Powered: Built w/ asynchronous support for modern web servers like Uvicorn and Daphne, enabling high concurrency.
  • 🛠️ Lightweight Design: Minimal dependencies for faster development and deployment.
  • ⚡ Blazing Fast: Check out how MicroPie compares to other popular ASGI frameworks below!

Installing MicroPie

Installation

Install MicroPie via pip:

pip install micropie

This will install MicroPie along with jinja2 for template rendering. Jinja2 is optional but recommended for using the render_template method.

Minimal Setup

For an ultra-minimalistic approach, download the standalone script:

MicroPie.py

Place it in your project directory, and you are good to go. Note that Jinja2 must be installed separately to use templates, but this is optional:

pip install jinja2

Install an ASGI Web Server

In order to test and deploy your apps you will need a ASGI web server like Uvicorn, Hypercorn or Daphne. Install uvicorn with:

pip install uvicorn

Getting Started

Create Your First ASGI App

Save the following as app.py:

from MicroPie import Server

class MyApp(Server):
    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

1. Flexible HTTP Routing for GET Requests

MicroPie automatically maps URLs to methods within your Server class. Routes can be defined as either synchronous or asynchronous functions, offering good flexibility.

For GET requests, pass data through query strings or URL path segments, automatically mapped to method arguments.

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

    async def hello(self):
        name = self.request.query_params.get("name", None)
        return f"Hello {name}!"

Access:

2. Flexible HTTP POST Request Handling

MicroPie also supports handling form data submitted via HTTP POST requests. Form data is automatically mapped to method arguments. It is able to handle default values and raw POST data:

class MyApp(Server):
    async def submit_default_values(self, username="Anonymous"):
        return f"Form submitted by: {username}"

    async def submit_catch_all(self):
        username = self.request.body_params.get("username", ["Anonymous"])[0]
        return f"Submitted by: {username}"

By default, MicroPie's route handlers can accept any request method, it's up to you how to handle any incoming requests! You can check the request method (and an number of other things specific to the current request state) in the handler withself.request.method.

3. Real-Time Communication with Socket.IO

Because of its designed simplicity, MicroPie does not handle WebSockets out of the box. While the underlying ASGI interface can theoretically handle WebSocket connections, MicroPie’s routing and request-handling logic is designed primarily for HTTP. While MicroPie does not natively support WebSockets, you can easily integrate dedicated Websockets libraries like Socket.IO alongside Uvicorn to handle real-time, bidirectional communication. Check out examples/socketio to see this in action.

4. Jinja2 Template Rendering

Dynamic HTML generation is supported via Jinja2. This happens asynchronously using Pythons asyncio library, so make sure to use the async and await with this method.

app.py

class MyApp(Server):
    async def index(self):
        return await self.render_template("index.html", title="Welcome", message="Hello from MicroPie!")

templates/index.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>{{ title }}</title>
</head>
<body>
    <h1>{{ message }}</h1>
</body>
</html>

5. Static File Serving

Here again, like Websockets, MiroPie does not have a built in static file method. While MicroPie does not natively support static files, if you need them, you can easily integrate dedicated libraries like ServeStatic or Starlette’s StaticFiles alongside Uvicorn to handle async static file serving. Check out examples/serve_static to see this in action.

6. Streaming Responses

Support for streaming responses makes it easy to send data in chunks.

class MyApp(Server):
    async def stream(self):
        async def generator():
            for i in range(1, 6):
                yield f"Chunk {i}\n"
        return generator()

7. Sessions and Cookies

Built-in session handling simplifies state management:

class MyApp(Server):
    async def index(self):
        if "visits" not in self.session:
            self.request.session["visits"] = 1
        else:
            self.request.session["visits"] += 1
        return f"You have visited {self.request.session['visits']} times."

8. Deployment

MicroPie apps can be deployed using any ASGI server. For example, using Uvicorn if our application is saved as app.py and our Server subclass is assigned to the app variable we can run it with:

uvicorn app:app --workers 4 --port 8000

Learn by Examples

The best way to get an idea of how MicroPie works is to see it in action! Check out the examples folder for more advanced usage, including:

  • Template rendering
  • Custom HTTP request handling
  • File uploads
  • Serving static content with ServeStatic
  • Session usage
  • Websockets with Socket.io
  • Async Streaming
  • Form handling and POST requests
  • And more

Please note these are examples, showing the MicroPie API and routing, they are not meant for producton!

Why ASGI?

ASGI is the future of Python web development, offering:

  • Concurrency: Handle thousands of simultaneous connections efficiently.
  • WebSockets: Use tools like Socket.IO for real-time communication.
  • Scalability: Ideal for modern, high-traffic applications.

MicroPie allows you to take full advantage of these benefits while maintaining simplicity and ease of use you're used to with your WSGI apps and it lets you choose what libraries you want to work with instead of forcing our ideas onto you!

Comparisons

Features vs Other Popular Frameworks

Feature MicroPie Flask CherryPy Bottle Django FastAPI
Ease of Use Very Easy Easy Easy Easy Moderate Moderate
Routing Automatic Manual Manual Manual Automatic Automatic
Template Engine Jinja2 (Opt.) Jinja2 None SimpleTpl Django Templating Jinja2
Session Handling Simple Extension Built-in Plugin Built-in Extension
Async Support Yes (ASGI) No (Quart) No No Limited Yes (ASGI)
Built-in Server No No Yes Yes Yes No

Suggestions or Feedback?

We welcome suggestions, bug reports, and pull requests!

  • File issues or feature requests here.