patx/micropie
update readme.md
Commit f3fcd4b · patx · 2025-01-28T11:24:39-05:00
Comments
No comments yet.
Diff
diff --git a/README.md b/README.md
index b157eb7..65e485b 100644
--- a/README.md
+++ b/README.md
@@ -2,54 +2,161 @@
## **Introduction**
-**MicroPie** is a lightweight Python web framework that makes building web applications simple and efficient. It includes features such as routing, session management, ASGI support, and Jinja2 template rendering.
+**MicroPie ASGI** is a lightweight, modern Python web framework that supports both synchronous and asynchronous web applications. Designed with flexibility and simplicity in mind, MicroPie ASGI enables you to handle high-concurrency HTTP applications with ease while allowing easy and natural integration with external tools like Socket.IO for real-time communication.
### **Key Features**
-*"Fast, efficient, and deliciously simple."*
+*"Fast, flexible, and future-ready."*
-- 🚀 **Easy Setup:** Minimal configuration required. Our setup is so simple, you’ll have time for dessert.
-- 🔄 **Routing:** Class based routing. Maps URLs to functions automatically. So easy, even your grandma could do it (probably).
-- 🔐 **Sessions:** Simple session management using cookies.
-- 🎨 **Templates:** Jinja2 for dynamic HTML pages.
-- ⚡ **Fast & Lightweight:** No unnecessary dependencies. Life’s too short for bloated frameworks.
-- 🖥️ **ASGI support:** Deploy with any ASGI server, like **uvicorn** making web development easy as... pie!
+- 🚀 **Async & Sync Support:** Define routes as asynchronous or synchronous functions to suit your application needs.
+- 🔄 **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 for modern web servers like Uvicorn and Daphne, enabling high concurrency.
+- 🛠️ **Lightweight Design:** Minimal dependencies for faster development and deployment.
+## **Installing MicroPie ASGI**
-## **Install**
-To install MicroPie [from the PyPI](https://pypi.org/project/MicroPie/) run the following command:
+### **Installation**
+Install MicroPie ASGI via pip:
```bash
pip install micropie
```
-This will install MicroPie along with `jinja2` as a dependency, enabling the built-in `render_template` method. This is the recommended way to install this framework.
+This will install MicroPie along with `jinja2` for template rendering. Jinja2 is optional but recommended for using the `render_template` method.
-To run your application you need an ASGI web server, like **uvicorn**. Install it with:
+### **Minimal Setup**
+For an ultra-minimalistic approach, download the standalone script:
+
+[MicroPie.py](https://raw.githubusercontent.com/patx/micropie/refs/heads/main/MicroPie.py)
+
+Place it in your project directory, and your good to go. Note that Jinja2 must be installed separately to use templates:
```bash
-pip install uvicorn
+pip install jinja2
```
-MicroPie will work with any ASGI server of your choice!
+### **Install an ASGI Web Server**
+In oder to test and deply your apps you will need a ASGI web server like uvicorn or Daphne. Install uvicorn with:
+```bash
+pip install uvicorn
+```
## **Getting Started**
-Create a basic MicroPie app in `app.py`:
+### **Create Your First ASGI App**
+Save the following as `app.py`:
```python
from MicroPie import Server
class MyApp(Server):
- async def index(self, name="Guest"):
- return f"Hello, {name}!"
+ async def index(self):
+ return "Welcome to MicroPie ASGI."
app = MyApp()
```
-
-Run the server:
-
+Run the server with:
```bash
uvicorn app:app
```
+Access your app at [http://127.0.0.1:8000](http://127.0.0.1:8000).
+
+## **Core Features**
+
+### **1. Flexible Routing**
+MicroPie automatically maps URLs to methods within your `Server` class. Routes can be defined as either synchronous or asynchronous functions, offering unparalleled flexibility.
+
+#### **Basic Routing**
+```python
+class MyApp(Server):
+ def hello(self):
+ return "Hello, world!"
+
+ async def async_hello(self):
+ return "Hello from an async route!"
+```
+**Access:**
+- Sync route: [http://127.0.0.1:8000/hello](http://127.0.0.1:8000/hello)
+- Async route: [http://127.0.0.1:8000/async_hello](http://127.0.0.1:8000/async_hello)
+
+### **2. Query and Path Parameters**
+Pass data through query strings or URL path segments, automatically mapped to method arguments.
+```python
+class MyApp(Server):
+ def greet(self, name="Guest"):
+ return f"Hello, {name}!"
+```
+
+**Access:**
+- [http://127.0.0.1:8000/greet?name=Alice](http://127.0.0.1:8000/greet?name=Alice) returns `Hello, Alice!`
+- [http://127.0.0.1:8000/greet/Alice](http://127.0.0.1:8000/greet/Alice) returns `Hello, Alice!`
+
+### **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 ASGI does not natively support WebSockets, you can easily integrate Socket.IO alongside Uvicorn to handle real-time, bidirectional communication. Check out [examples/socketio](https://github.com/patx/micropie/tree/development/examples/socketio) to see this in action.
+
+
+### **4. Jinja2 Template Rendering**
+Dynamic HTML generation is supported via Jinja2.
+
+#### **`app.py`**
+```python
+class MyApp(Server):
+ def index(self):
+ return self.render_template("index.html", title="Welcome", message="Hello from MicroPie!")
+```
-Visit your app at [http://127.0.0.1:8000](http://127.0.0.1:8000). In MicroPie your application code can look just like the WSGI code you are used to writing!
+#### **`templates/index.html`**
+```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**
+Serve static files such as CSS, JS, and images from a `static` directory.
+
+```python
+class MyApp(Server):
+ def static(self, filename):
+ return self.serve_static(filename)
+```
+Place your files in the `static` directory and access them via `/static/<filename>`.
+
+### **6. Streaming Responses**
+Support for streaming responses makes it easy to send data in chunks.
+
+```python
+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:
+
+```python
+class MyApp(Server):
+ def index(self):
+ if "visits" not in self.session:
+ self.session["visits"] = 1
+ else:
+ self.session["visits"] += 1
+ return f"You have visited {self.session['visits']} times."
+```
+
+### **8. Deployment**
+MicroPie ASGI apps can be deployed using any ASGI server. For example, using Uvicorn:
+```bash
+uvicorn app:MyApp --workers 4 --port 8000
+```
## **Learn by Examples**
@@ -57,35 +164,34 @@ Check out the [examples folder](https://github.com/patx/micropie/tree/developmen
- Template rendering
- Custom HTTP request handling
- File uploads
+- Serving static content
- Session usage
- Websockets with Socket.io
- Async Streaming
- Form handling
-## **Notes on WebSockets**
-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. If you need WebSocket functionality, you’ll need to either:
-
-- Write or integrate your own custom ASGI WebSocket handler, or
-- Use a dedicated library such as Socket.IO or channels with your ASGI server alongside MicroPie.
+## **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.
-Check out [examples/socketio](https://github.com/patx/micropie/tree/development/examples/socketio) to see Socket.io integration.
+MicroPie ASGI allows you to take full advantage of these benefits while maintaining simplicity and ease of use your used to with your WSGI apps.
## **Feature Comparison**
-| 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 | Jinja2 | None | SimpleTpl | Django Templating | Jinja2 |
-| **Session Handling**| Built-in | Extension | Built-in | Plugin | Built-in | Extension |
-| **Request Handling**| Simple | Flexible | Advanced | Simple | Advanced | Advanced |
-| **Performance** | High | High | Moderate | High | Moderate | Very High |
-| **WSGI Support** | No (ASGI) | Yes | Yes | Yes | Yes | No (ASGI) |
-| **Async Support** | Yes | No (Quart) | No | No | Limited | Yes |
-| **Deployment** | Simple | Moderate | Moderate | Simple | Complex | Moderate |
-| **Built-in Server** | No | No | Yes | Yes | Yes | No |
+| 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 | No (Quart) | No | No | Limited | Yes |
+| **Performance** | Very High | High | Moderate | High | Moderate | Extremely High |
+| **Built-in Server** | No | No | Yes | Yes | Yes | No |
+
## **Suggestions or Feedback?**