.. MicroPie documentation master file, created for the MicroPie ASGI framework.
MicroPie ASGI Web Framework
===========================
MicroPie is a small, asynchronous web framework built on top of the
ASGI specification. It is designed to be simple to learn and easy to
extend while still providing the features necessary to build modern web
applications. MicroPie offers automatic URL routing, pluggable
session back‑ends, middleware hooks, WebSocket support and optional
template rendering. Its focus on minimalism makes it a good choice for
lightweight services, APIs and educational projects.
Core features
-------------
* **Convention over configuration.** Public methods on your
:class:`~micropie.App` subclass automatically become routes so you can
ship a prototype with only a handful of lines of code.
* **Async‑first request handling.** MicroPie speaks ASGI fluently and
embraces ``async``/``await`` for HTTP and WebSocket handlers while
keeping synchronous handlers ergonomic.
* **Built‑in sessions and middleware.** A pluggable session backend and
request/response middleware hooks make it easy to add authentication,
analytics and other cross‑cutting concerns.
* **Optional batteries included.** Extras for templating, fast JSON and
multipart parsing allow you to scale capabilities without bloating the
core package.
Learning path
-------------
New to MicroPie? Follow this recommended progression:
1. :doc:`tutorial/quickstart` – install the framework and serve your
first response.
2. :doc:`tutorial/routing` – understand how method names map to URL
paths and how handler arguments are populated.
3. :doc:`tutorial/websockets` – build a live, bidirectional endpoint.
4. :doc:`howto/index` – explore recipes for common tasks like sessions,
templating and streaming.
5. :doc:`reference/index` – deep dive into class and function
definitions when you need the authoritative contract.
6. :doc:`explanation/index` – read about the philosophy behind the
design to better understand trade‑offs and extension points.
This documentation is organized according to the
Diátaxis documentation framework. That framework separates documentation into
four distinct types:
* **Tutorials** – step‑by‑step introductions that teach you how to
accomplish a task. Tutorials should avoid deep explanations and help
you get started quickly.
* **How‑to guides** – recipes focused on solving a particular problem.
Guides assume you already know the basics and want to apply MicroPie
to a concrete task.
* **Reference** – authoritative descriptions of classes, functions and
modules. These documents are factual and concise.
* **Explanation** – discussions that explore the rationale behind
design choices and deeper concepts in MicroPie.
In addition to these four types, a small glossary collects terminology
used throughout the framework. Quick links to other helpful resources:
* :doc:`glossary` – definitions of common MicroPie and ASGI terms.
* :doc:`whats_new` – highlights from recent releases and upgrade tips.
* `Project README <https://github.com/patx/micropie#readme>`_ – the
high-level project overview from the source repository.
.. _Diátaxis documentation framework: https://diataxis.fr/
Contents
========
.. toctree::
:maxdepth: 2
:caption: Documentation
tutorial/index
howto/index
reference/index
explanation/index
whats_new
glossary
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
