patx/micropie
change docs file structure
Commit eaf67a5 · patx · 2025-08-15T02:33:21-04:00
Comments
No comments yet.
Diff
diff --git a/docs/docs/.buildinfo b/docs/docs/.buildinfo
new file mode 100644
index 0000000..14addd4
--- /dev/null
+++ b/docs/docs/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 1692f2bbb7ef8d168c169aefd48e27a4
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/docs/docs/.doctrees/environment.pickle b/docs/docs/.doctrees/environment.pickle
new file mode 100644
index 0000000..512b693
Binary files /dev/null and b/docs/docs/.doctrees/environment.pickle differ
diff --git a/docs/docs/.doctrees/explanation/architecture.doctree b/docs/docs/.doctrees/explanation/architecture.doctree
new file mode 100644
index 0000000..e1d2c7d
Binary files /dev/null and b/docs/docs/.doctrees/explanation/architecture.doctree differ
diff --git a/docs/docs/.doctrees/explanation/index.doctree b/docs/docs/.doctrees/explanation/index.doctree
new file mode 100644
index 0000000..6275ba2
Binary files /dev/null and b/docs/docs/.doctrees/explanation/index.doctree differ
diff --git a/docs/docs/.doctrees/glossary.doctree b/docs/docs/.doctrees/glossary.doctree
new file mode 100644
index 0000000..4669693
Binary files /dev/null and b/docs/docs/.doctrees/glossary.doctree differ
diff --git a/docs/docs/.doctrees/howto/index.doctree b/docs/docs/.doctrees/howto/index.doctree
new file mode 100644
index 0000000..496b51b
Binary files /dev/null and b/docs/docs/.doctrees/howto/index.doctree differ
diff --git a/docs/docs/.doctrees/howto/middleware.doctree b/docs/docs/.doctrees/howto/middleware.doctree
new file mode 100644
index 0000000..15e3d0b
Binary files /dev/null and b/docs/docs/.doctrees/howto/middleware.doctree differ
diff --git a/docs/docs/.doctrees/howto/sessions.doctree b/docs/docs/.doctrees/howto/sessions.doctree
new file mode 100644
index 0000000..9d03f92
Binary files /dev/null and b/docs/docs/.doctrees/howto/sessions.doctree differ
diff --git a/docs/docs/.doctrees/howto/socketio.doctree b/docs/docs/.doctrees/howto/socketio.doctree
new file mode 100644
index 0000000..f963fda
Binary files /dev/null and b/docs/docs/.doctrees/howto/socketio.doctree differ
diff --git a/docs/docs/.doctrees/howto/static_files.doctree b/docs/docs/.doctrees/howto/static_files.doctree
new file mode 100644
index 0000000..f35d2e1
Binary files /dev/null and b/docs/docs/.doctrees/howto/static_files.doctree differ
diff --git a/docs/docs/.doctrees/howto/streaming.doctree b/docs/docs/.doctrees/howto/streaming.doctree
new file mode 100644
index 0000000..2cfd044
Binary files /dev/null and b/docs/docs/.doctrees/howto/streaming.doctree differ
diff --git a/docs/docs/.doctrees/howto/templates.doctree b/docs/docs/.doctrees/howto/templates.doctree
new file mode 100644
index 0000000..903586b
Binary files /dev/null and b/docs/docs/.doctrees/howto/templates.doctree differ
diff --git a/docs/docs/.doctrees/index.doctree b/docs/docs/.doctrees/index.doctree
new file mode 100644
index 0000000..ddc3455
Binary files /dev/null and b/docs/docs/.doctrees/index.doctree differ
diff --git a/docs/docs/.doctrees/reference/app.doctree b/docs/docs/.doctrees/reference/app.doctree
new file mode 100644
index 0000000..c4794fb
Binary files /dev/null and b/docs/docs/.doctrees/reference/app.doctree differ
diff --git a/docs/docs/.doctrees/reference/exceptions.doctree b/docs/docs/.doctrees/reference/exceptions.doctree
new file mode 100644
index 0000000..db847ac
Binary files /dev/null and b/docs/docs/.doctrees/reference/exceptions.doctree differ
diff --git a/docs/docs/.doctrees/reference/index.doctree b/docs/docs/.doctrees/reference/index.doctree
new file mode 100644
index 0000000..2404f50
Binary files /dev/null and b/docs/docs/.doctrees/reference/index.doctree differ
diff --git a/docs/docs/.doctrees/reference/middleware.doctree b/docs/docs/.doctrees/reference/middleware.doctree
new file mode 100644
index 0000000..6a5378f
Binary files /dev/null and b/docs/docs/.doctrees/reference/middleware.doctree differ
diff --git a/docs/docs/.doctrees/reference/request.doctree b/docs/docs/.doctrees/reference/request.doctree
new file mode 100644
index 0000000..f4180db
Binary files /dev/null and b/docs/docs/.doctrees/reference/request.doctree differ
diff --git a/docs/docs/.doctrees/reference/session.doctree b/docs/docs/.doctrees/reference/session.doctree
new file mode 100644
index 0000000..aaf304a
Binary files /dev/null and b/docs/docs/.doctrees/reference/session.doctree differ
diff --git a/docs/docs/.doctrees/reference/websocket.doctree b/docs/docs/.doctrees/reference/websocket.doctree
new file mode 100644
index 0000000..5b1cfdc
Binary files /dev/null and b/docs/docs/.doctrees/reference/websocket.doctree differ
diff --git a/docs/docs/.doctrees/tutorial/index.doctree b/docs/docs/.doctrees/tutorial/index.doctree
new file mode 100644
index 0000000..56973e5
Binary files /dev/null and b/docs/docs/.doctrees/tutorial/index.doctree differ
diff --git a/docs/docs/.doctrees/tutorial/quickstart.doctree b/docs/docs/.doctrees/tutorial/quickstart.doctree
new file mode 100644
index 0000000..21dea0c
Binary files /dev/null and b/docs/docs/.doctrees/tutorial/quickstart.doctree differ
diff --git a/docs/docs/.doctrees/tutorial/routing.doctree b/docs/docs/.doctrees/tutorial/routing.doctree
new file mode 100644
index 0000000..cdbd233
Binary files /dev/null and b/docs/docs/.doctrees/tutorial/routing.doctree differ
diff --git a/docs/docs/.doctrees/tutorial/websockets.doctree b/docs/docs/.doctrees/tutorial/websockets.doctree
new file mode 100644
index 0000000..3bf0205
Binary files /dev/null and b/docs/docs/.doctrees/tutorial/websockets.doctree differ
diff --git a/docs/docs/_sources/explanation/architecture.rst.txt b/docs/docs/_sources/explanation/architecture.rst.txt
new file mode 100644
index 0000000..a55c720
--- /dev/null
+++ b/docs/docs/_sources/explanation/architecture.rst.txt
@@ -0,0 +1,95 @@
+Architecture and design
+=======================
+
+MicroPie is intentionally small. Its goal is to provide just enough
+functionality to build asynchronous web applications without locking
+you into a rigid structure. This section discusses some of the key
+design choices and how they influence the API.
+
+ASGI application
+----------------
+
+MicroPie is built on top of the `ASGI`_ specification, which defines
+how Python applications communicate with asynchronous servers. Your
+application subclass inherits from :class:`~micropie.App` and
+implements the ASGI call interface via the ``__call__`` method. The
+framework inspects the ``scope['type']`` field to dispatch to HTTP,
+WebSocket or lifespan handling code.
+
+Routing by naming
+-----------------
+
+Unlike frameworks that require you to declare routes in advance,
+MicroPie derives routing information from the names of your methods.
+The first segment of the path becomes the handler name. This allows
+you to add new endpoints simply by defining a new method on your
+application subclass. The remaining path segments, query string
+parameters and form data are mapped to arguments via function
+signature inspection. This approach reduces boilerplate but may
+surprise users expecting explicit routing. You can always regain
+control by writing a custom middleware to map paths to handlers or by
+checking ``self.request.method`` and ``self.request.path_params`` inside
+your handlers.
+
+Context‑local request
+---------------------
+
+MicroPie stores the current request in a :mod:`contextvars`
+ContextVar. This allows you to access ``self.request`` within your
+handler as well as from deeper helper functions without passing the
+request around explicitly. The context variable is reset at the end
+of each request to avoid leaking state.
+
+Session management
+------------------
+
+Sessions are stored in a pluggable back‑end and identified by a
+random ``session_id`` cookie. The default in‑memory back‑end keeps
+session data in dictionaries keyed by session ID and updates a last
+access timestamp to implement expiration. You can customise the
+back‑end by providing your own implementation of
+:class:`~micropie.SessionBackend`. MicroPie saves sessions after a
+handler returns, only if ``self.request.session`` is non‑empty, to
+avoid creating unnecessary cookies.
+
+Middleware pipeline
+-------------------
+
+The middleware hooks allow you to intercept requests before and after
+handlers. Middleware can modify the request object, provide early
+responses (useful for authentication), and alter the final response.
+For WebSockets, separate middleware hooks run before the connection
+handler starts and after it finishes.
+
+Streaming and SSE support
+-------------------------
+
+Handlers may return an iterator or asynchronous generator to stream
+data to the client. MicroPie detects such responses and iterates
+over them, sending each chunk to the client. When using server‑sent
+events (SSE) there is an additional challenge: if the client
+disconnects, the iterator must be cancelled. MicroPie wraps SSE
+responses in a small loop that listens for disconnect events and
+cancels the generator accordingly. Remember to include a
+``Content‑Type: text/event-stream`` header when sending SSE.
+
+Error handling
+--------------
+
+MicroPie automatically handles common error cases. Requests for
+unknown routes result in a ``404 Not Found``. If a required
+parameter is missing, MicroPie responds with ``400 Bad Request``.
+Unhandled exceptions inside handlers produce a ``500 Internal Server
+Error`` and are printed to standard error. You can override these
+behaviours via middleware.
+
+Extensibility
+-------------
+
+The minimalist core is designed to be extended. You can mount your
+application behind other ASGI middleware, integrate additional
+protocols like Socket.IO, or implement your own session storage. The
+framework imposes few constraints so that you remain in control of
+your stack.
+
+.. _ASGI: https://asgi.readthedocs.io/
\ No newline at end of file
diff --git a/docs/docs/_sources/explanation/index.rst.txt b/docs/docs/_sources/explanation/index.rst.txt
new file mode 100644
index 0000000..0d3ac07
--- /dev/null
+++ b/docs/docs/_sources/explanation/index.rst.txt
@@ -0,0 +1,13 @@
+Explanations
+============
+
+The explanation section explores concepts and design decisions behind
+MicroPie. It answers “why” questions and provides deeper context.
+For hands‑on instructions see the tutorials and how‑to guides; for
+precise definitions consult the reference.
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Explanations
+
+ architecture
\ No newline at end of file
diff --git a/docs/docs/_sources/glossary.rst.txt b/docs/docs/_sources/glossary.rst.txt
new file mode 100644
index 0000000..c02a776
--- /dev/null
+++ b/docs/docs/_sources/glossary.rst.txt
@@ -0,0 +1,44 @@
+Glossary
+========
+
+This glossary defines terms used throughout the MicroPie documentation.
+
+.. glossary::
+
+ ASGI
+ The Asynchronous Server Gateway Interface. A standard for
+ asynchronous communication between Python applications and
+ servers. MicroPie applications implement the ASGI call
+ interface. See the `ASGI specification <https://asgi.readthedocs.io>`_.
+
+ route handler
+ A method on your :class:`~micropie.App` subclass that handles an
+ incoming HTTP request. The first segment of the URL path maps to
+ the handler name, and remaining segments or query parameters map
+ to arguments. Handlers may be synchronous or asynchronous.
+
+ session
+ A dictionary of data associated with a client across multiple
+ requests. MicroPie stores the session in a pluggable back‑end
+ and identifies it using a ``session_id`` cookie. See
+ :doc:`howto/sessions`.
+
+ middleware
+ Code that runs before and/or after a request handler. Middleware
+ can short‑circuit requests, modify responses, enforce security
+ policies or implement custom routing. MicroPie defines
+ :class:`~micropie.HttpMiddleware` and
+ :class:`~micropie.WebSocketMiddleware` base classes.
+
+ WebSocket
+ A persistent, bidirectional communication channel over TCP. In
+ MicroPie, WebSocket handlers are methods prefixed with ``ws_``.
+ They receive an instance of :class:`~micropie.WebSocket` and
+ optionally additional parameters. See :doc:`tutorial/websockets`.
+
+ context variable
+ An object from the :mod:`contextvars` module that stores data
+ local to the current asynchronous context. MicroPie stores the
+ current request in a context variable so it is accessible via
+ :meth:`~micropie.App.request` without passing it through your
+ function calls.
\ No newline at end of file
diff --git a/docs/docs/_sources/howto/index.rst.txt b/docs/docs/_sources/howto/index.rst.txt
new file mode 100644
index 0000000..6d3e1a2
--- /dev/null
+++ b/docs/docs/_sources/howto/index.rst.txt
@@ -0,0 +1,19 @@
+How‑to guides
+=============
+
+How‑to guides provide short recipes for solving a specific problem with
+MicroPie. They assume that you already know the basics covered in
+the tutorials. Each guide focuses on performing a single task. See
+the :doc:`tutorials <../tutorial/index>` for a more gentle
+introduction.
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Guides
+
+ sessions
+ middleware
+ templates
+ streaming
+ static_files
+ socketio
\ No newline at end of file
diff --git a/docs/docs/_sources/howto/middleware.rst.txt b/docs/docs/_sources/howto/middleware.rst.txt
new file mode 100644
index 0000000..a815318
--- /dev/null
+++ b/docs/docs/_sources/howto/middleware.rst.txt
@@ -0,0 +1,93 @@
+Writing middleware
+==================
+
+Middleware allows you to insert code that runs before and after your
+handlers. It is useful for cross‑cutting concerns such as logging,
+authentication, rate limiting or explicit routing. MicroPie defines
+separate middleware classes for HTTP and WebSocket connections.
+
+HTTP middleware
+---------------
+
+To create HTTP middleware, subclass :class:`~micropie.HttpMiddleware`
+and implement two asynchronous methods:
+
+* :meth:`~micropie.HttpMiddleware.before_request` – called before the
+ handler is executed. If this method returns a dictionary with
+ ``status_code`` and ``body`` keys, MicroPie immediately sends that
+ response and skips calling the handler. You can also provide
+ additional headers via a ``headers`` key.
+
+* :meth:`~micropie.HttpMiddleware.after_request` – called after the
+ handler has returned a response but before it is sent to the client.
+ You can modify the status code, body or headers by returning a
+ dictionary with updated values.
+
+Register your middleware by appending an instance to
+:attr:`~micropie.App.middlewares` on your application:
+
+.. code-block:: python
+
+ from micropie import App, HttpMiddleware
+
+ class LoggingMiddleware(HttpMiddleware):
+ async def before_request(self, request):
+ print(f"Incoming request: {request.method} {request.scope['path']}")
+ # returning None continues processing
+
+ async def after_request(self, request, status_code, body, headers):
+ print(f"Response status: {status_code}")
+ # returning None uses the original response
+
+ class MyApp(App):
+ async def index(self):
+ return "Hello, world!"
+
+ app = MyApp()
+ app.middlewares.append(LoggingMiddleware())
+
+WebSocket middleware
+--------------------
+
+WebSocket middleware must subclass :class:`~micropie.WebSocketMiddleware`
+and implement two methods:
+
+* :meth:`~micropie.WebSocketMiddleware.before_websocket` – called
+ before a WebSocket handler runs. If this method returns a
+ dictionary with ``code`` and ``reason``, MicroPie closes the
+ connection with the given code and reason.
+
+* :meth:`~micropie.WebSocketMiddleware.after_websocket` – called after
+ the WebSocket handler completes. Use this to perform cleanup.
+
+Example:
+
+.. code-block:: python
+
+ from micropie import App, WebSocketMiddleware
+
+ class RejectAnonymous(WebSocketMiddleware):
+ async def before_websocket(self, request):
+ # Reject connections without a "user" query parameter
+ if "user" not in request.query_params:
+ return {"code": 1008, "reason": "User name required"}
+
+ async def after_websocket(self, request):
+ print("WebSocket closed")
+
+ class MyApp(App):
+ async def ws_chat(self, ws, user):
+ await ws.accept()
+ await ws.send_text(f"Welcome, {user}!")
+ await ws.close()
+
+ app = MyApp()
+ app.ws_middlewares.append(RejectAnonymous())
+
+Explicit routing and other patterns
+----------------------------------
+
+You can implement custom routing schemes by writing middleware that
+parses the incoming path and sets ``request._route_handler`` or
+``request._ws_route_handler`` accordingly. See the examples in the
+``examples/middleware`` directory for a complete implementation.
\ No newline at end of file
diff --git a/docs/docs/_sources/howto/sessions.rst.txt b/docs/docs/_sources/howto/sessions.rst.txt
new file mode 100644
index 0000000..b29f6de
--- /dev/null
+++ b/docs/docs/_sources/howto/sessions.rst.txt
@@ -0,0 +1,84 @@
+Managing sessions
+=================
+
+MicroPie includes simple session management built on top of cookies. A
+session stores data associated with a client across multiple requests.
+Sessions are useful for keeping track of login state, counters and
+temporary information.
+
+Enabling sessions
+-----------------
+
+By default, MicroPie uses an in‑memory session back‑end implemented by
+:class:`~micropie.InMemorySessionBackend`. Each session is identified
+by a ``session_id`` cookie. When the client makes a request, the
+cookie is read and the session data is loaded from the back‑end. When
+you modify the session dictionary, MicroPie writes the updated
+session back at the end of the request and issues a ``Set‑Cookie``
+header if needed.
+
+In order to use sessions, simply read and write the
+:attr:`~micropie.Request.session` dictionary in your handler. The
+following example counts the number of visits for each client:
+
+.. code-block:: python
+
+ from micropie import App
+
+ class MyApp(App):
+ async def index(self):
+ if "visits" not in self.request.session:
+ self.request.session["visits"] = 1
+ else:
+ self.request.session["visits"] += 1
+ return f"You have visited {self.request.session['visits']} times."
+
+ app = MyApp()
+
+Custom session back‑ends
+------------------------
+
+The in‑memory back‑end stores all sessions in a Python dictionary. It
+is suitable for development but will lose data when the process
+terminates and cannot be shared across worker processes. To persist
+sessions in a database or cache, implement the abstract
+:class:`~micropie.SessionBackend` interface:
+
+.. code-block:: python
+
+ from micropie import SessionBackend
+
+ class DatabaseSessionBackend(SessionBackend):
+ async def load(self, session_id: str) -> dict:
+ # fetch the session from your database or cache
+ data = await get_session_from_db(session_id)
+ return data or {}
+
+ async def save(self, session_id: str, data: dict, timeout: int) -> None:
+ # store the session with an expiration timeout
+ await save_session_to_db(session_id, data, timeout)
+
+Assign your back‑end when constructing your application:
+
+.. code-block:: python
+
+ backend = DatabaseSessionBackend()
+ app = MyApp(session_backend=backend)
+
+Expiring sessions
+-----------------
+
+The global constant :data:`micropie.SESSION_TIMEOUT` controls how long
+a session remains valid (in seconds). The default is eight hours.
+Back‑ends may choose to enforce this timeout in whatever manner makes
+sense for their storage layer.
+
+Security considerations
+-----------------------
+
+Sessions are sent to the client as cookies and should be treated as
+untrusted input. Avoid storing sensitive information directly in the
+session. If you implement your own back‑end, ensure that session
+identifiers are random, unique and that the cookie includes the
+``HttpOnly``, ``Secure`` and ``SameSite=Lax`` directives. The
+in‑memory back‑end provided by MicroPie already issues these flags.
\ No newline at end of file
diff --git a/docs/docs/_sources/howto/socketio.rst.txt b/docs/docs/_sources/howto/socketio.rst.txt
new file mode 100644
index 0000000..02b5bbe
--- /dev/null
+++ b/docs/docs/_sources/howto/socketio.rst.txt
@@ -0,0 +1,54 @@
+Integrating Socket.IO
+=====================
+
+MicroPie’s built‑in WebSocket support provides a simple API for
+bidirectional communication. If you require advanced features such
+as automatic reconnection, broadcasting to rooms, namespaces, or
+fallback transports for browsers that do not support WebSockets, you
+can integrate `python‑socketio <https://python-socketio.readthedocs.io>`_.
+
+Socket.IO runs as an ASGI application, so you can mount it
+alongside your MicroPie app and serve both under the same Uvicorn
+server. The following example shows how to set up a basic chat
+application using Socket.IO with MicroPie.
+
+.. code-block:: python
+
+ import socketio
+ from micropie import App
+
+ # Create a Socket.IO server instance (ASGI compatible)
+ sio = socketio.AsyncServer(async_mode="asgi")
+ socket_app = socketio.ASGIApp(sio)
+
+ # Create your MicroPie application
+ class MyApp(App):
+ async def index(self):
+ # Serve an HTML page with Socket.IO client code (omitted)
+ return await self._render_template("chat.html")
+
+ app = MyApp()
+
+ # Uvicorn accepts a single callable; wrap both apps in a simple
+ # dispatcher that routes to Socket.IO on the /socket.io path
+ async def application(scope, receive, send):
+ if scope["path"].startswith("/socket.io"):
+ await socket_app(scope, receive, send)
+ else:
+ await app(scope, receive, send)
+
+Run the dispatcher with Uvicorn:
+
+.. code-block:: console
+
+ $ uvicorn app:application
+
+On the client side, connect to ``/socket.io`` as usual using the
+Socket.IO JavaScript client. All other paths are handled by your
+MicroPie routes. See the ``examples/socketio`` directory in the
+MicroPie source distribution for a more complete implementation that
+includes HTML and JavaScript code.
+
+Note that python‑socketio may install its own dependencies. Consult
+the Socket.IO documentation for configuration options such as
+message queue back‑ends and authentication.
\ No newline at end of file
diff --git a/docs/docs/_sources/howto/static_files.rst.txt b/docs/docs/_sources/howto/static_files.rst.txt
new file mode 100644
index 0000000..38933cd
--- /dev/null
+++ b/docs/docs/_sources/howto/static_files.rst.txt
@@ -0,0 +1,45 @@
+Serving static files
+====================
+
+MicroPie deliberately avoids bundling a static file server. Serving
+static content such as images, CSS and JavaScript can be delegated to
+a specialised middleware or a separate web server. This approach
+keeps the core framework small and flexible.
+
+Using a static file middleware
+------------------------------
+
+To serve static files from within your MicroPie application, you can
+use third‑party libraries such as
+`ServeStatic <https://archmonger.github.io/ServeStatic/latest/>`_ or
+Starlette’s `StaticFiles` class. The example below uses
+ServeStatic to serve files from a ``static`` directory:
+
+.. code-block:: python
+
+ from micropie import App
+ from servestatic import ServeStatic
+
+ class MyApp(App):
+ async def index(self):
+ return "Hello, world!"
+
+ app = MyApp()
+
+ # Mount the static file handler at the /static path
+ app_with_static = ServeStatic(app, directory="static", path_prefix="/static")
+
+When running your application, pass ``app_with_static`` to your ASGI
+server instead of ``app``. Requests to paths under ``/static`` will
+be served from your ``static`` directory, while all other requests
+fall through to your MicroPie routes.
+
+Using a reverse proxy
+---------------------
+
+Alternatively, you can serve static files via a dedicated HTTP server
+such as Nginx or Caddy. In production deployments this is often the
+preferred option, as a dedicated server can handle caching and
+compression. Configure your web server to serve the ``/static``
+prefix directly from the filesystem and forward all other requests to
+your ASGI server running MicroPie.
\ No newline at end of file
diff --git a/docs/docs/_sources/howto/streaming.rst.txt b/docs/docs/_sources/howto/streaming.rst.txt
new file mode 100644
index 0000000..b231ce3
--- /dev/null
+++ b/docs/docs/_sources/howto/streaming.rst.txt
@@ -0,0 +1,66 @@
+Streaming responses
+===================
+
+For long‑running tasks or large responses it is often desirable to
+stream data to the client in chunks rather than return a single
+buffer. MicroPie supports streaming by allowing your handler to
+return an iterator or asynchronous generator. Each chunk yielded by
+the generator is sent as part of the response body. When the
+generator finishes, MicroPie automatically sends an empty chunk to
+signal completion.
+
+Example: number stream
+----------------------
+
+The following handler streams a sequence of numbers to the client one
+per second:
+
+.. code-block:: python
+
+ from micropie import App
+ import asyncio
+
+ class MyApp(App):
+ async def numbers(self):
+ async def generator():
+ for i in range(5):
+ yield f"Number: {i}\n"
+ await asyncio.sleep(1)
+ return generator()
+
+ app = MyApp()
+
+Visiting ``/numbers`` will produce output like:
+
+.. code-block:: text
+
+ Number: 0
+ Number: 1
+ Number: 2
+ Number: 3
+ Number: 4
+
+MicroPie automatically sets ``Content‑Type`` to ``text/html`` if you
+do not specify a content type. You can override or add headers by
+returning a tuple ``(status_code, body, headers)`` and making the
+generator the body.
+
+Handling client disconnects
+---------------------------
+
+If the client disconnects while a generator is running, MicroPie
+cancels the generator and closes the underlying response. This
+behaviour is important for long‑lived streams such as server‑sent
+events (SSE). When writing a generator, use ``try``/``finally`` or
+``async with`` to perform cleanup when the stream is cancelled.
+
+Server‑sent events
+------------------
+
+MicroPie treats any iterable response body as a general stream.
+Implementing true server‑sent events requires you to set the
+``Content‑Type`` header to ``text/event-stream`` and send
+properly‑formatted SSE messages (``data: ...\n\n``). Additionally,
+MicroPie includes a patch that handles early disconnection of SSE
+clients in its HTTP handling code. For a full example, see the
+``examples/sse`` directory in the MicroPie source distribution.
\ No newline at end of file
diff --git a/docs/docs/_sources/howto/templates.rst.txt b/docs/docs/_sources/howto/templates.rst.txt
new file mode 100644
index 0000000..57b5176
--- /dev/null
+++ b/docs/docs/_sources/howto/templates.rst.txt
@@ -0,0 +1,71 @@
+Rendering templates
+==================
+
+MicroPie can render HTML templates using the Jinja2 template engine.
+Templates allow you to separate presentation from code by placing
+HTML in separate files. Template rendering is optional; you can use
+MicroPie without Jinja2 installed, but the
+:meth:`~micropie.App._render_template` method will not be available.
+
+Installing Jinja2
+-----------------
+
+If you installed MicroPie with the ``[standard]`` extra, Jinja2 is
+already available. Otherwise install it with pip:
+
+.. code-block:: console
+
+ $ pip install jinja2
+
+Creating templates
+------------------
+
+MicroPie looks for templates in a directory called ``templates`` in
+your current working directory. Use normal Jinja2 syntax in your
+templates. Here is a simple ``templates/index.html`` file:
+
+.. code-block:: html
+
+ <!DOCTYPE html>
+ <html lang="en">
+ <head>
+ <meta charset="UTF-8">
+ <title>{{ title }}</title>
+ </head>
+ <body>
+ <h1>{{ message }}</h1>
+ </body>
+ </html>
+
+Rendering a template
+--------------------
+
+To render a template, call :meth:`~micropie.App._render_template` from
+within an asynchronous handler. The method returns a string containing
+the rendered HTML. Because template loading and rendering may block,
+MicroPie runs it in a background thread using ``asyncio.to_thread``.
+
+.. code-block:: python
+
+ from micropie import App
+
+ class MyApp(App):
+ async def index(self):
+ return await self._render_template(
+ "index.html",
+ title="Welcome",
+ message="Hello from MicroPie!",
+ )
+
+ app = MyApp()
+
+When you visit ``/`` in your browser, MicroPie returns the rendered
+HTML with a ``Content‑Type`` of ``text/html; charset=utf‑8``.
+
+Template variables
+------------------
+
+You can pass arbitrary keyword arguments to `_render_template`. These
+become variables in the Jinja2 template. For more information on
+creating complex templates, including inheritance and control flow,
+refer to the `Jinja2 documentation <https://jinja.palletsprojects.com>`_.
\ No newline at end of file
diff --git a/docs/docs/_sources/index.rst.txt b/docs/docs/_sources/index.rst.txt
new file mode 100644
index 0000000..3ab55be
--- /dev/null
+++ b/docs/docs/_sources/index.rst.txt
@@ -0,0 +1,56 @@
+.. 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.
+
+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. If you are new to
+MicroPie, start with the tutorial. If you want to accomplish a
+specific task, head to the how‑to guides. If you need to look up a
+particular method or class, consult the reference manual. For
+background and design considerations, see the explanation section.
+
+.. _Diátaxis documentation framework: https://diataxis.fr/
+
+Contents
+========
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Documentation
+
+ tutorial/index
+ howto/index
+ reference/index
+ explanation/index
+ glossary
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/docs/docs/_sources/reference/app.rst.txt b/docs/docs/_sources/reference/app.rst.txt
new file mode 100644
index 0000000..7fbad67
--- /dev/null
+++ b/docs/docs/_sources/reference/app.rst.txt
@@ -0,0 +1,78 @@
+App class
+=========
+
+.. _app-class:
+
+The :class:`~micropie.App` class is the core of a MicroPie application.
+It implements the ASGI call interface and dispatches HTTP, WebSocket
+and lifespan events to your handlers. Subclass :class:`~micropie.App`
+and add public methods to create route handlers. Instantiate your
+subclass and pass the resulting object to an ASGI server such as
+Uvicorn.
+
+Constructor
+-----------
+
+.. class:: App(session_backend=None)
+
+ Create a new application. If *session_backend* is provided it must
+ be an instance of :class:`~micropie.SessionBackend`. When omitted,
+ MicroPie uses an in‑memory back‑end.
+
+Attributes
+----------
+
+.. attribute:: middlewares
+
+ A list of :class:`~micropie.HttpMiddleware` instances. Middlewares
+ run before and after every HTTP request. Append a middleware
+ instance to enable it. See :doc:`../howto/middleware` for examples.
+
+.. attribute:: ws_middlewares
+
+ A list of :class:`~micropie.WebSocketMiddleware` instances used for
+ WebSocket connections.
+
+.. attribute:: startup_handlers
+
+ A list of asynchronous callables that run during the ASGI
+ ``lifespan.startup`` event. Use this to set up resources such as
+ database connections. See :doc:`../tutorial/quickstart` for an
+ example.
+
+.. attribute:: shutdown_handlers
+
+ A list of asynchronous callables that run during the ASGI
+ ``lifespan.shutdown`` event. Use this to clean up resources.
+
+Methods
+-------
+
+.. method:: __call__(scope, receive, send)
+
+ The ASGI entry point. Dispatches to HTTP, WebSocket or lifespan
+ handlers based on ``scope['type']``. You normally do not call this
+ directly; the ASGI server calls it for you.
+
+.. method:: request
+
+ Return the current :class:`~micropie.Request` object. This is
+ stored in a context variable so that it is available throughout
+ asynchronous callbacks.
+
+.. method:: _redirect(location, extra_headers=None)
+
+ Return a tuple ``(302, '', headers)`` representing an HTTP redirect
+ to *location*. Use this helper in your handlers to redirect the
+ client.
+
+.. method:: _render_template(name, **kwargs)
+
+ Render a Jinja2 template asynchronously. Returns a string
+ containing the rendered output. Requires Jinja2 to be installed.
+ See :doc:`../howto/templates` for details.
+
+Additionally, MicroPie defines several private helper methods such as
+``_parse_cookies`` and ``_send_response``. These are considered
+internal and not part of the public API. They may change without
+notice.
\ No newline at end of file
diff --git a/docs/docs/_sources/reference/exceptions.rst.txt b/docs/docs/_sources/reference/exceptions.rst.txt
new file mode 100644
index 0000000..fd1454c
--- /dev/null
+++ b/docs/docs/_sources/reference/exceptions.rst.txt
@@ -0,0 +1,18 @@
+Exceptions
+==========
+
+MicroPie defines a small number of exceptions. The most commonly
+encountered is :class:`~micropie.ConnectionClosed`, used for WebSocket
+disconnections.
+
+ConnectionClosed
+----------------
+
+.. class:: ConnectionClosed
+
+ Raised by :meth:`~micropie.WebSocket.receive_text` and
+ :meth:`~micropie.WebSocket.receive_bytes` when the client closes
+ the WebSocket connection. Catch this exception to detect
+ disconnection and exit your handler gracefully. The exception does
+ not carry any attributes; the WebSocket connection has already been
+ closed when it is raised.
\ No newline at end of file
diff --git a/docs/docs/_sources/reference/index.rst.txt b/docs/docs/_sources/reference/index.rst.txt
new file mode 100644
index 0000000..40095d3
--- /dev/null
+++ b/docs/docs/_sources/reference/index.rst.txt
@@ -0,0 +1,18 @@
+API reference
+=============
+
+The reference manual provides detailed descriptions of the classes and
+functions exposed by MicroPie. These documents are factual and
+succinct【730263613588085†L336-L339】. For tutorials and recipes, see the
+:doc:`../tutorial/index` and :doc:`../howto/index` sections.
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Reference
+
+ app
+ request
+ websocket
+ middleware
+ session
+ exceptions
\ No newline at end of file
diff --git a/docs/docs/_sources/reference/middleware.rst.txt b/docs/docs/_sources/reference/middleware.rst.txt
new file mode 100644
index 0000000..4754f9e
--- /dev/null
+++ b/docs/docs/_sources/reference/middleware.rst.txt
@@ -0,0 +1,51 @@
+Middleware classes
+==================
+
+MicroPie defines abstract base classes for writing middleware. Use
+these classes to intercept requests, implement custom routing,
+authentication, logging and other cross‑cutting concerns. See the
+:doc:`../howto/middleware` guide for practical examples.
+
+HttpMiddleware
+--------------
+
+.. class:: HttpMiddleware
+
+ Base class for HTTP middleware. Subclasses must implement two
+ asynchronous methods:
+
+ .. method:: before_request(request)
+
+ Called before the HTTP handler runs. *request* is the
+ :class:`~micropie.Request` object. Return a dictionary
+ ``{"status_code": status, "body": body, "headers": headers}``
+ to short‑circuit the request and send a response immediately. To
+ continue processing, return ``None``.
+
+ .. method:: after_request(request, status_code, response_body, extra_headers)
+
+ Called after the handler has completed but before the response
+ is sent. You may return a dictionary with updated
+ ``status_code``, ``body`` and ``headers``. Return ``None`` to
+ leave the response unchanged.
+
+WebSocketMiddleware
+-------------------
+
+.. class:: WebSocketMiddleware
+
+ Base class for WebSocket middleware. Subclasses must implement
+ these methods:
+
+ .. method:: before_websocket(request)
+
+ Called before a WebSocket handler runs. *request* is a
+ :class:`~micropie.WebSocketRequest` object. Return a dictionary
+ ``{"code": code, "reason": reason}`` to reject the connection
+ with the given close code and reason. Return ``None`` to allow
+ the connection.
+
+ .. method:: after_websocket(request)
+
+ Called after the WebSocket handler completes. Use this to
+ release resources or log activity. Return value is ignored.
\ No newline at end of file
diff --git a/docs/docs/_sources/reference/request.rst.txt b/docs/docs/_sources/reference/request.rst.txt
new file mode 100644
index 0000000..332b8e7
--- /dev/null
+++ b/docs/docs/_sources/reference/request.rst.txt
@@ -0,0 +1,80 @@
+Request objects
+===============
+
+.. _request-object:
+
+MicroPie provides two request classes: :class:`~micropie.Request` for
+HTTP requests and :class:`~micropie.WebSocketRequest` for WebSocket
+connections. You access the current request via
+:meth:`~micropie.App.request` on your application instance or by using
+the context variable in lower‑level code.
+
+Request class
+-------------
+
+.. class:: Request(scope)
+
+ Represents an incoming HTTP request. The *scope* argument is the
+ ASGI scope dictionary provided by the server. You should not
+ instantiate this class yourself. MicroPie creates one per
+ request and stores it in a context variable.
+
+ .. attribute:: scope
+
+ The original ASGI scope for the request.
+
+ .. attribute:: method
+
+ The HTTP method, such as ``GET`` or ``POST``.
+
+ .. attribute:: path_params
+
+ A list of positional path parameters. See
+ :doc:`../tutorial/routing` for details on parameter mapping.
+
+ .. attribute:: query_params
+
+ A ``dict`` mapping each query parameter to a list of values.
+ For convenience, use ``self.request.query_params['name'][0]`` to
+ obtain the first value.
+
+ .. attribute:: body_params
+
+ A ``dict`` mapping form field names to lists of values. For
+ JSON requests, body parameters are derived from the top‑level
+ object; for ``application/x-www-form-urlencoded`` forms they are
+ parsed using :func:`urllib.parse.parse_qs`.
+
+ .. attribute:: get_json
+
+ The JSON body parsed into a Python object. Only populated when
+ the request contains valid JSON with content type
+ ``application/json``.
+
+ .. attribute:: session
+
+ A ``dict`` for storing per‑client data across requests. See
+ :doc:`../howto/sessions`.
+
+ .. attribute:: files
+
+ A ``dict`` of uploaded files for multipart/form‑data requests.
+ Each entry is a mapping containing keys ``filename``,
+ ``content_type`` and ``content``, where ``content`` is an
+ ``asyncio.Queue`` yielding file chunks as bytes. See
+ :doc:`../tutorial/routing` for information on awaiting file fields.
+
+ .. attribute:: headers
+
+ A case‑insensitive mapping of header names to values, decoded as
+ UTF‑8 with invalid bytes replaced. Header names are lowercased.
+
+WebSocketRequest class
+----------------------
+
+.. class:: WebSocketRequest(scope)
+
+ Inherits from :class:`~micropie.Request` and represents a WebSocket
+ connection request. All attributes of :class:`~micropie.Request`
+ apply. For WebSocket handlers the request is accessible via
+ ``self.request`` inside the handler or via the context variable.
\ No newline at end of file
diff --git a/docs/docs/_sources/reference/session.rst.txt b/docs/docs/_sources/reference/session.rst.txt
new file mode 100644
index 0000000..1804ae2
--- /dev/null
+++ b/docs/docs/_sources/reference/session.rst.txt
@@ -0,0 +1,63 @@
+Session back‑ends
+=================
+
+MicroPie abstracts session storage behind the :class:`~micropie.SessionBackend`
+interface. Different back‑ends may store session data in memory,
+databases, caches or external services. A session is a dictionary of
+key/value pairs associated with a ``session_id`` cookie.
+
+SessionBackend
+--------------
+
+.. class:: SessionBackend
+
+ Abstract base class for session storage. Implementations must
+ provide the following asynchronous methods:
+
+ .. method:: load(session_id)
+
+ Load session data for the given *session_id*. Return a
+ dictionary of session data or an empty dictionary if the session
+ does not exist or has expired.
+
+ .. method:: save(session_id, data, timeout)
+
+ Persist the *data* dictionary for the given *session_id* with
+ an expiry time of *timeout* seconds.
+
+InMemorySessionBackend
+----------------------
+
+.. class:: InMemorySessionBackend
+
+ Concrete implementation of :class:`SessionBackend` that stores
+ sessions in memory. This back‑end is appropriate for development
+ and testing but does not persist data across process restarts and
+ cannot be shared among worker processes.
+
+ .. method:: __init__()
+
+ Create an empty in‑memory session store.
+
+ .. method:: load(session_id)
+
+ Return the session dictionary if it exists and has not expired
+ according to :data:`micropie.SESSION_TIMEOUT`, otherwise return
+ an empty dictionary.
+
+ .. method:: save(session_id, data, timeout)
+
+ Store *data* under *session_id* and update the last access time.
+
+SESSION_TIMEOUT
+---------------
+
+.. data:: SESSION_TIMEOUT
+
+ The default session expiration time in seconds (eight hours). You
+ can override this constant in your own code before importing
+ MicroPie or by passing a different timeout when saving sessions in
+ a custom back‑end.
+
+See also the :doc:`../howto/sessions` guide for examples of using and
+implementing session back‑ends.
\ No newline at end of file
diff --git a/docs/docs/_sources/reference/websocket.rst.txt b/docs/docs/_sources/reference/websocket.rst.txt
new file mode 100644
index 0000000..78b84a2
--- /dev/null
+++ b/docs/docs/_sources/reference/websocket.rst.txt
@@ -0,0 +1,74 @@
+WebSocket class
+===============
+
+.. _websocket-reference:
+
+The :class:`~micropie.WebSocket` class encapsulates a WebSocket
+connection. MicroPie constructs an instance for each WebSocket
+request and passes it as the first argument to your WebSocket handler.
+
+Constructor
+-----------
+
+.. class:: WebSocket(receive, send)
+
+ Create a new WebSocket wrapper around the ASGI ``receive`` and
+ ``send`` callables. You do not instantiate this class yourself;
+ MicroPie does so internally.
+
+Methods
+-------
+
+.. method:: accept(subprotocol=None, session_id=None)
+
+ Accept the WebSocket connection. You must call this method before
+ sending or receiving messages. If you provide a *session_id*,
+ MicroPie sets a ``session_id`` cookie during the handshake. The
+ optional *subprotocol* argument specifies a negotiated subprotocol.
+
+.. method:: receive_text()
+
+ Await a text message from the client. Returns a string. Raises
+ :class:`~micropie.ConnectionClosed` if the client has disconnected or
+ ``ValueError`` if a binary message is received.
+
+.. method:: receive_bytes()
+
+ Await a binary message from the client. Returns bytes. Raises
+ :class:`~micropie.ConnectionClosed` if the client has disconnected or
+ ``ValueError`` if a text message is received.
+
+.. method:: send_text(data)
+
+ Send a text message to the client. Raises ``RuntimeError`` if you
+ have not called :meth:`accept`.
+
+.. method:: send_bytes(data)
+
+ Send a binary message to the client. Raises ``RuntimeError`` if
+ the connection has not been accepted.
+
+.. method:: close(code=1000, reason=None)
+
+ Close the WebSocket connection. By default uses code 1000
+ (normal closure). The optional *reason* is sent to the client.
+
+Attributes
+----------
+
+.. attribute:: accepted
+
+ ``True`` if the WebSocket has been accepted.
+
+.. attribute:: session_id
+
+ The session ID set during the handshake, or ``None`` if not set.
+
+Exceptions
+----------
+
+.. class:: ConnectionClosed
+
+ Raised by :meth:`receive_text` and :meth:`receive_bytes` when the
+ client has closed the connection. Catch this exception in your
+ handlers to perform cleanup after a disconnect.
\ No newline at end of file
diff --git a/docs/docs/_sources/tutorial/index.rst.txt b/docs/docs/_sources/tutorial/index.rst.txt
new file mode 100644
index 0000000..93f2c06
--- /dev/null
+++ b/docs/docs/_sources/tutorial/index.rst.txt
@@ -0,0 +1,16 @@
+Tutorials
+=========
+
+The tutorials walk you through the basics of writing a MicroPie
+application. They are intended for readers who have never used
+MicroPie before. Each tutorial builds upon the previous one and
+demonstrates a specific aspect of the framework. Tutorials should
+present clear, logical steps and avoid long theoretical discussions.
+
+.. toctree::
+ :maxdepth: 1
+ :caption: Tutorials
+
+ quickstart
+ routing
+ websockets
diff --git a/docs/docs/_sources/tutorial/quickstart.rst.txt b/docs/docs/_sources/tutorial/quickstart.rst.txt
new file mode 100644
index 0000000..9531525
--- /dev/null
+++ b/docs/docs/_sources/tutorial/quickstart.rst.txt
@@ -0,0 +1,80 @@
+Quick start
+===========
+
+This tutorial shows you how to install MicroPie and run a very simple
+application. By the end you will be able to serve an HTTP
+endpoint that returns plain text. This section assumes that you
+already have Python 3.8 or later installed.
+
+Installation
+------------
+
+MicroPie is distributed on the Python Package Index (PyPI). The
+recommended way to install it is via ``pip`` with the standard
+optional dependencies:
+
+.. code-block:: console
+
+ $ pip install micropie[standard]
+
+This command installs MicroPie along with the Jinja2 template engine
+and the ``multipart`` parser for handling file uploads. If you want
+the fastest JSON parsing and a preconfigured ASGI server, you can
+install all optional extras:
+
+.. code-block:: console
+
+ $ pip install micropie[all]
+
+See :ref:`reference/session` for details about session back‑ends and
+the :ref:`howto/templates` guide for information on templates.
+
+Writing your first application
+------------------------------
+
+Create a file called ``app.py`` with the following contents:
+
+.. code-block:: python
+
+ from micropie import App
+
+ class MyApp(App):
+ async def index(self):
+ return "Welcome to MicroPie ASGI."
+
+ app = MyApp()
+
+MicroPie applications are defined by subclassing :class:`~micropie.App`.
+Each public method of your subclass becomes a potential route handler
+automatically mapped to an HTTP path. The special method ``index``
+handles requests to the root path ``/``. Handlers may be asynchronous
+(``async def``) or synchronous functions and can return strings,
+bytes, JSON‑serialisable objects, tuples of status and body, or an
+async generator for streaming responses.
+
+Running the application
+-----------------------
+
+MicroPie itself is not a web server; it is an ASGI application. To
+run it you will need an ASGI server such as Uvicorn, Hypercorn or
+Daphne. Install Uvicorn if you have not already:
+
+.. code-block:: console
+
+ $ pip install uvicorn
+
+Start your application with Uvicorn:
+
+.. code-block:: console
+
+ $ uvicorn app:app
+
+By default Uvicorn listens on ``http://127.0.0.1:8000``. Open that URL
+in your browser and you should see the text “Welcome to MicroPie ASGI.”
+
+What’s next?
+------------
+
+Now that you have a running MicroPie application, proceed to the
+:doc:`routing <routing>` tutorial to learn how URL paths map to
+methods and how to pass parameters to your handlers.
\ No newline at end of file
diff --git a/docs/docs/_sources/tutorial/routing.rst.txt b/docs/docs/_sources/tutorial/routing.rst.txt
new file mode 100644
index 0000000..d4a3be5
--- /dev/null
+++ b/docs/docs/_sources/tutorial/routing.rst.txt
@@ -0,0 +1,126 @@
+Routing and handlers
+====================
+
+MicroPie maps incoming HTTP requests to methods on your :class:`~micropie.App`
+subclass. This section explains how the mapping works and how your
+handlers receive input from the URL path, query strings, form data and
+sessions.
+
+URL to function mapping
+-----------------------
+
+When an HTTP request arrives, MicroPie extracts the path portion of the
+URL and uses the first path segment to determine which method should
+handle the request. For example, a GET request to ``/greet`` calls
+``greet`` on your :class:`~micropie.App` subclass. A request to the
+root URL ``/`` calls ``index``. Only methods that do not start with
+an underscore are exposed as route handlers. Prefacing a method name
+with an underscore makes it private and hides it from external
+requests.
+
+Handlers may be synchronous or asynchronous functions. They return
+either a string, bytes, a JSON‑serialisable object, a tuple of
+``(status_code, body)`` or ``(status_code, body, headers)``, or an
+iterator/generator for streaming responses. See
+:doc:`howto/streaming` for details on streaming.
+
+Parameters and arguments
+------------------------
+
+MicroPie automatically populates handler arguments from several
+sources in the following order:
+
+1. **Path parameters** – Additional path segments after the first map to
+ positional parameters. For example:
+
+ .. code-block:: python
+
+ class AppExample(App):
+ async def greet(self, name):
+ return f"Hello, {name}!"
+
+ Visiting ``/greet/Alice`` passes ``"Alice"`` as the ``name`` argument.
+ You can also use ``*args`` to capture an arbitrary number of path
+ segments.
+
+2. **Query parameters** – Named parameters in the query string fill
+ keyword arguments when path parameters are exhausted. For example,
+ ``/greet?name=Alice`` also passes ``"Alice"`` to the ``name``
+ parameter.
+
+3. **Body/form data** – For POST, PUT and PATCH requests, form fields
+ populate handler arguments. JSON bodies are decoded into a
+ dictionary of key/value pairs.
+
+4. **Files** – If the request is multipart/form‑data, uploaded files
+ appear in :attr:`~micropie.Request.files`. You can declare a file
+ argument in your handler signature to receive a file object.
+
+5. **Session data** – Values stored in :attr:`~micropie.Request.session`
+ fill remaining parameters. See :doc:`howto/sessions` for details.
+
+6. **Default values** – If no other source provides a value, default
+ values in your function signature are used.
+
+If MicroPie cannot determine a value for a required parameter, it
+returns a ``400 Bad Request``.
+
+Examples
+--------
+
+The following examples illustrate common patterns:
+
+.. code-block:: python
+
+ class MyApp(App):
+ async def greet(self, name="Guest"):
+ """Return a greeting for a named visitor.
+
+ If the ``name`` argument is not provided via the path or
+ query parameters, ``"Guest"`` is used as a default.
+ """
+ return f"Hello, {name}!"
+
+ async def add(self, x, y):
+ """Add two numbers provided via path segments.
+
+ Example: ``/add/2/3`` returns ``5``.
+ """
+ return str(int(x) + int(y))
+
+ async def submit(self, username="Anonymous"):
+ """Handle a form submission.
+
+ This handler accepts POST requests and uses the
+ ``username`` field from the request body.
+ """
+ return f"Form submitted by: {username}"
+
+See :ref:`request-object` for the attributes available on the current
+request and :ref:`app-class` for details about the ``App`` class.
+
+HTTP methods and responses
+--------------------------
+
+Handlers run for any HTTP method unless you explicitly check
+``self.request.method`` inside the handler. It is your
+responsibility to dispatch based on the method if your endpoint should
+behave differently for GET and POST. Handlers may return:
+
+* A string or bytes – sent as the body of the response with a
+ ``200 OK`` status.
+* A JSON‑serialisable object – automatically encoded into JSON and
+ returned with a ``Content‑Type`` of ``application/json``.
+* A tuple ``(status_code, body)`` – sets the HTTP status and body.
+* A tuple ``(status_code, body, headers)`` – sets status, body and
+ additional headers. Headers should be a list of ``(name, value)`` pairs.
+* A generator or async generator – streams chunks to the client. Use
+ this for large responses or server‑sent events.
+
+Advanced routing
+----------------
+
+You can implement explicit routing, path prefixing or complex
+dispatching by writing a custom :class:`~micropie.HttpMiddleware`. See
+the :doc:`howto/middleware` guide and the examples in the
+``examples/explicit_routing`` directory of the source distribution.
\ No newline at end of file
diff --git a/docs/docs/_sources/tutorial/websockets.rst.txt b/docs/docs/_sources/tutorial/websockets.rst.txt
new file mode 100644
index 0000000..e4197a2
--- /dev/null
+++ b/docs/docs/_sources/tutorial/websockets.rst.txt
@@ -0,0 +1,88 @@
+WebSocket support
+=================
+
+MicroPie includes first‑class support for WebSockets. WebSockets are a
+persistent, bidirectional communication channel over a single TCP
+connection. They enable real‑time applications such as chat, live
+notifications and collaborative editing.
+
+Mapping WebSocket routes
+------------------------
+
+WebSocket handlers live on the same :class:`~micropie.App` subclass
+that serves your HTTP routes. The naming convention is similar to
+HTTP handlers, but with a ``ws_`` prefix. For example, a method
+called ``ws_chat`` handles WebSocket connections at ``/chat``. If the
+path is empty, ``ws_index`` handles the root WebSocket route.
+
+When a WebSocket connection is initiated, MicroPie constructs a
+:class:`~micropie.WebSocket` object and passes it as the first
+argument to your handler, along with any path or query parameters. A
+typical handler must call :meth:`~micropie.WebSocket.accept` to accept
+the connection and then use :meth:`~micropie.WebSocket.receive_text`
+and :meth:`~micropie.WebSocket.send_text` (or their ``bytes``
+counterparts) to communicate.
+
+Example: echo server
+--------------------
+
+The example below implements a simple echo server. The server
+accepts the WebSocket connection and then echoes back whatever text it
+receives. When the client disconnects, the handler finishes.
+
+.. code-block:: python
+
+ from micropie import App
+
+ class MyApp(App):
+ async def ws_echo(self, ws):
+ # Accept the connection; without this call, MicroPie will
+ # automatically reject the WebSocket.
+ await ws.accept()
+ while True:
+ try:
+ message = await ws.receive_text()
+ except ConnectionClosed:
+ # Client closed the connection
+ break
+ # Send the same message back to the client
+ await ws.send_text(f"Echo: {message}")
+
+ app = MyApp()
+
+To test this endpoint, run your application and connect to
+``ws://127.0.0.1:8000/echo`` using a WebSocket client. Most modern
+browsers support WebSockets via JavaScript.
+
+Accessing query and path parameters
+-----------------------------------
+
+Just like HTTP handlers, WebSocket handlers receive path and query
+parameters. Additional positional arguments come from the path, and
+keyword arguments are filled from the query string or session. For
+example:
+
+.. code-block:: python
+
+ class MyApp(App):
+ async def ws_greet(self, ws, name="Guest"):
+ await ws.accept()
+ await ws.send_text(f"Hello {name}!")
+ await ws.close()
+
+Connecting to ``ws://localhost:8000/greet/Alice`` sends back
+``"Hello Alice!"``. Connecting to ``ws://localhost:8000/greet?name=Bob``
+sends ``"Hello Bob!"``. See :ref:`websocket-reference` for the
+complete API of the :class:`~micropie.WebSocket` class.
+
+Integrating Socket.IO
+---------------------
+
+MicroPie focuses on the core WebSocket protocol. If you need more
+advanced real‑time features—automatic reconnection, broadcasting, or
+fallback transports such as polling—you can integrate
+`python‑socketio <https://python-socketio.readthedocs.io>`_. See the
+``examples/socketio`` directory in the MicroPie source distribution for
+sample code and instructions. When integrating Socket.IO, you still
+run your MicroPie application behind an ASGI server and attach the
+Socket.IO server as additional middleware or route.
\ No newline at end of file
diff --git a/docs/docs/_static/alabaster.css b/docs/docs/_static/alabaster.css
new file mode 100644
index 0000000..d92336b
--- /dev/null
+++ b/docs/docs/_static/alabaster.css
@@ -0,0 +1,668 @@
+/* -- page layout ----------------------------------------------------------- */
+
+body {
+ font-family: Georgia, serif;
+ font-size: 17px;
+ background-color: #fff;
+ color: #000;
+ margin: 0;
+ padding: 0;
+}
+
+
+div.document {
+ width: 940px;
+ margin: 30px auto 0 auto;
+}
+
+div.documentwrapper {
+ float: left;
+ width: 100%;
+}
+
+div.bodywrapper {
+ margin: 0 0 0 220px;
+}
+
+div.sphinxsidebar {
+ width: 220px;
+ font-size: 14px;
+ line-height: 1.5;
+}
+
+hr {
+ border: 1px solid #B1B4B6;
+}
+
+div.body {
+ background-color: #fff;
+ color: #3E4349;
+ padding: 0 30px 0 30px;
+}
+
+div.body > .section {
+ text-align: left;
+}
+
+div.footer {
+ width: 940px;
+ margin: 20px auto 30px auto;
+ font-size: 14px;
+ color: #888;
+ text-align: right;
+}
+
+div.footer a {
+ color: #888;
+}
+
+p.caption {
+ font-family: inherit;
+ font-size: inherit;
+}
+
+
+div.relations {
+ display: none;
+}
+
+
+div.sphinxsidebar {
+ max-height: 100%;
+ overflow-y: auto;
+}
+
+div.sphinxsidebar a {
+ color: #444;
+ text-decoration: none;
+ border-bottom: 1px dotted #999;
+}
+
+div.sphinxsidebar a:hover {
+ border-bottom: 1px solid #999;
+}
+
+div.sphinxsidebarwrapper {
+ padding: 18px 10px;
+}
+
+div.sphinxsidebarwrapper p.logo {
+ padding: 0;
+ margin: -10px 0 0 0px;
+ text-align: center;
+}
+
+div.sphinxsidebarwrapper h1.logo {
+ margin-top: -10px;
+ text-align: center;
+ margin-bottom: 5px;
+ text-align: left;
+}
+
+div.sphinxsidebarwrapper h1.logo-name {
+ margin-top: 0px;
+}
+
+div.sphinxsidebarwrapper p.blurb {
+ margin-top: 0;
+ font-style: normal;
+}
+
+div.sphinxsidebar h3,
+div.sphinxsidebar h4 {
+ font-family: Georgia, serif;
+ color: #444;
+ font-size: 24px;
+ font-weight: normal;
+ margin: 0 0 5px 0;
+ padding: 0;
+}
+
+div.sphinxsidebar h4 {
+ font-size: 20px;
+}
+
+div.sphinxsidebar h3 a {
+ color: #444;
+}
+
+div.sphinxsidebar p.logo a,
+div.sphinxsidebar h3 a,
+div.sphinxsidebar p.logo a:hover,
+div.sphinxsidebar h3 a:hover {
+ border: none;
+}
+
+div.sphinxsidebar p {
+ color: #555;
+ margin: 10px 0;
+}
+
+div.sphinxsidebar ul {
+ margin: 10px 0;
+ padding: 0;
+ color: #000;
+}
+
+div.sphinxsidebar ul li.toctree-l1 > a {
+ font-size: 120%;
+}
+
+div.sphinxsidebar ul li.toctree-l2 > a {
+ font-size: 110%;
+}
+
+div.sphinxsidebar input {
+ border: 1px solid #CCC;
+ font-family: Georgia, serif;
+ font-size: 1em;
+}
+
+div.sphinxsidebar #searchbox {
+ margin: 1em 0;
+}
+
+div.sphinxsidebar .search > div {
+ display: table-cell;
+}
+
+div.sphinxsidebar hr {
+ border: none;
+ height: 1px;
+ color: #AAA;
+ background: #AAA;
+
+ text-align: left;
+ margin-left: 0;
+ width: 50%;
+}
+
+div.sphinxsidebar .badge {
+ border-bottom: none;
+}
+
+div.sphinxsidebar .badge:hover {
+ border-bottom: none;
+}
+
+/* To address an issue with donation coming after search */
+div.sphinxsidebar h3.donation {
+ margin-top: 10px;
+}
+
+/* -- body styles ----------------------------------------------------------- */
+
+a {
+ color: #004B6B;
+ text-decoration: underline;
+}
+
+a:hover {
+ color: #6D4100;
+ text-decoration: underline;
+}
+
+div.body h1,
+div.body h2,
+div.body h3,
+div.body h4,
+div.body h5,
+div.body h6 {
+ font-family: Georgia, serif;
+ font-weight: normal;
+ margin: 30px 0px 10px 0px;
+ padding: 0;
+}
+
+div.body h1 { margin-top: 0; padding-top: 0; font-size: 240%; }
+div.body h2 { font-size: 180%; }
+div.body h3 { font-size: 150%; }
+div.body h4 { font-size: 130%; }
+div.body h5 { font-size: 100%; }
+div.body h6 { font-size: 100%; }
+
+a.headerlink {
+ color: #DDD;
+ padding: 0 4px;
+ text-decoration: none;
+}
+
+a.headerlink:hover {
+ color: #444;
+ background: #EAEAEA;
+}
+
+div.body p, div.body dd, div.body li {
+ line-height: 1.4em;
+}
+
+div.admonition {
+ margin: 20px 0px;
+ padding: 10px 30px;
+ background-color: #EEE;
+ border: 1px solid #CCC;
+}
+
+div.admonition tt.xref, div.admonition code.xref, div.admonition a tt {
+ background-color: #FBFBFB;
+ border-bottom: 1px solid #fafafa;
+}
+
+div.admonition p.admonition-title {
+ font-family: Georgia, serif;
+ font-weight: normal;
+ font-size: 24px;
+ margin: 0 0 10px 0;
+ padding: 0;
+ line-height: 1;
+}
+
+div.admonition p.last {
+ margin-bottom: 0;
+}
+
+dt:target, .highlight {
+ background: #FAF3E8;
+}
+
+div.warning {
+ background-color: #FCC;
+ border: 1px solid #FAA;
+}
+
+div.danger {
+ background-color: #FCC;
+ border: 1px solid #FAA;
+ -moz-box-shadow: 2px 2px 4px #D52C2C;
+ -webkit-box-shadow: 2px 2px 4px #D52C2C;
+ box-shadow: 2px 2px 4px #D52C2C;
+}
+
+div.error {
+ background-color: #FCC;
+ border: 1px solid #FAA;
+ -moz-box-shadow: 2px 2px 4px #D52C2C;
+ -webkit-box-shadow: 2px 2px 4px #D52C2C;
+ box-shadow: 2px 2px 4px #D52C2C;
+}
+
+div.caution {
+ background-color: #FCC;
+ border: 1px solid #FAA;
+}
+
+div.attention {
+ background-color: #FCC;
+ border: 1px solid #FAA;
+}
+
+div.important {
+ background-color: #EEE;
+ border: 1px solid #CCC;
+}
+
+div.note {
+ background-color: #EEE;
+ border: 1px solid #CCC;
+}
+
+div.tip {
+ background-color: #EEE;
+ border: 1px solid #CCC;
+}
+
+div.hint {
+ background-color: #EEE;
+ border: 1px solid #CCC;
+}
+
+div.seealso {
+ background-color: #EEE;
+ border: 1px solid #CCC;
+}
+
+div.topic {
+ background-color: #EEE;
+}
+
+p.admonition-title {
+ display: inline;
+}
+
+p.admonition-title:after {
+ content: ":";
+}
+
+pre, tt, code {
+ font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
+ font-size: 0.9em;
+}
+
+.hll {
+ background-color: #FFC;
+ margin: 0 -12px;
+ padding: 0 12px;
+ display: block;
+}
+
+img.screenshot {
+}
+
+tt.descname, tt.descclassname, code.descname, code.descclassname {
+ font-size: 0.95em;
+}
+
+tt.descname, code.descname {
+ padding-right: 0.08em;
+}
+
+img.screenshot {
+ -moz-box-shadow: 2px 2px 4px #EEE;
+ -webkit-box-shadow: 2px 2px 4px #EEE;
+ box-shadow: 2px 2px 4px #EEE;
+}
+
+table.docutils {
+ border: 1px solid #888;
+ -moz-box-shadow: 2px 2px 4px #EEE;
+ -webkit-box-shadow: 2px 2px 4px #EEE;
+ box-shadow: 2px 2px 4px #EEE;
+}
+
+table.docutils td, table.docutils th {
+ border: 1px solid #888;
+ padding: 0.25em 0.7em;
+}
+
+table.field-list, table.footnote {
+ border: none;
+ -moz-box-shadow: none;
+ -webkit-box-shadow: none;
+ box-shadow: none;
+}
+
+table.footnote {
+ margin: 15px 0;
+ width: 100%;
+ border: 1px solid #EEE;
+ background: #FDFDFD;
+ font-size: 0.9em;
+}
+
+table.footnote + table.footnote {
+ margin-top: -15px;
+ border-top: none;
+}
+
+table.field-list th {
+ padding: 0 0.8em 0 0;
+}
+
+table.field-list td {
+ padding: 0;
+}
+
+table.field-list p {
+ margin-bottom: 0.8em;
+}
+
+/* Cloned from
+ * https://github.com/sphinx-doc/sphinx/commit/ef60dbfce09286b20b7385333d63a60321784e68
+ */
+.field-name {
+ -moz-hyphens: manual;
+ -ms-hyphens: manual;
+ -webkit-hyphens: manual;
+ hyphens: manual;
+}
+
+table.footnote td.label {
+ width: .1px;
+ padding: 0.3em 0 0.3em 0.5em;
+}
+
+table.footnote td {
+ padding: 0.3em 0.5em;
+}
+
+dl {
+ margin-left: 0;
+ margin-right: 0;
+ margin-top: 0;
+ padding: 0;
+}
+
+dl dd {
+ margin-left: 30px;
+}
+
+blockquote {
+ margin: 0 0 0 30px;
+ padding: 0;
+}
+
+ul, ol {
+ /* Matches the 30px from the narrow-screen "li > ul" selector below */
+ margin: 10px 0 10px 30px;
+ padding: 0;
+}
+
+pre {
+ background: unset;
+ padding: 7px 30px;
+ margin: 15px 0px;
+ line-height: 1.3em;
+}
+
+div.viewcode-block:target {
+ background: #ffd;
+}
+
+dl pre, blockquote pre, li pre {
+ margin-left: 0;
+ padding-left: 30px;
+}
+
+tt, code {
+ background-color: #ecf0f3;
+ color: #222;
+ /* padding: 1px 2px; */
+}
+
+tt.xref, code.xref, a tt {
+ background-color: #FBFBFB;
+ border-bottom: 1px solid #fff;
+}
+
+a.reference {
+ text-decoration: none;
+ border-bottom: 1px dotted #004B6B;
+}
+
+a.reference:hover {
+ border-bottom: 1px solid #6D4100;
+}
+
+/* Don't put an underline on images */
+a.image-reference, a.image-reference:hover {
+ border-bottom: none;
+}
+
+a.footnote-reference {
+ text-decoration: none;
+ font-size: 0.7em;
+ vertical-align: top;
+ border-bottom: 1px dotted #004B6B;
+}
+
+a.footnote-reference:hover {
+ border-bottom: 1px solid #6D4100;
+}
+
+a:hover tt, a:hover code {
+ background: #EEE;
+}
+div.sphinxsidebar {
+ position: fixed;
+ margin-left: 0;
+}
+
+@media screen and (max-width: 940px) {
+
+ body {
+ margin: 0;
+ padding: 20px 30px;
+ }
+
+ div.documentwrapper {
+ float: none;
+ background: #fff;
+ margin-left: 0;
+ margin-top: 0;
+ margin-right: 0;
+ margin-bottom: 0;
+ }
+
+ div.sphinxsidebar {
+ display: block;
+ float: none;
+ width: unset;
+ margin: -20px -30px 20px -30px;
+ position: static;
+ padding: 10px 20px;
+ background: #333;
+ color: #FFF;
+ }
+
+ div.sphinxsidebar h3, div.sphinxsidebar h4, div.sphinxsidebar p,
+ div.sphinxsidebar h3 a {
+ color: #fff;
+ }
+
+ div.sphinxsidebar a {
+ color: #AAA;
+ }
+
+ div.sphinxsidebar p.logo {
+ display: none;
+ }
+
+ div.document {
+ width: 100%;
+ margin: 0;
+ }
+
+ div.footer {
+ display: none;
+ }
+
+ div.bodywrapper {
+ margin: 0;
+ }
+
+ div.body {
+ min-height: 0;
+ min-width: auto; /* fixes width on small screens, breaks .hll */
+ padding: 0;
+ }
+
+ .hll {
+ /* "fixes" the breakage */
+ width: max-content;
+ }
+
+ .rtd_doc_footer {
+ display: none;
+ }
+
+ .document {
+ width: auto;
+ }
+
+ .footer {
+ width: auto;
+ }
+
+ .github {
+ display: none;
+ }
+
+ ul {
+ margin-left: 0;
+ }
+
+ li > ul {
+ /* Matches the 30px from the "ul, ol" selector above */
+ margin-left: 30px;
+ }
+}
+
+
+/* misc. */
+
+.revsys-inline {
+ display: none!important;
+}
+
+/* Hide ugly table cell borders in ..bibliography:: directive output */
+table.docutils.citation, table.docutils.citation td, table.docutils.citation th {
+ border: none;
+ /* Below needed in some edge cases; if not applied, bottom shadows appear */
+ -moz-box-shadow: none;
+ -webkit-box-shadow: none;
+ box-shadow: none;
+}
+
+
+/* relbar */
+
+.related {
+ line-height: 30px;
+ width: 100%;
+ font-size: 0.9rem;
+}
+
+.related.top {
+ border-bottom: 1px solid #EEE;
+ margin-bottom: 20px;
+}
+
+.related.bottom {
+ border-top: 1px solid #EEE;
+}
+
+.related ul {
+ padding: 0;
+ margin: 0;
+ list-style: none;
+}
+
+.related li {
+ display: inline;
+}
+
+nav#rellinks {
+ float: right;
+}
+
+nav#rellinks li+li:before {
+ content: "|";
+}
+
+nav#breadcrumbs li+li:before {
+ content: "\00BB";
+}
+
+/* Hide certain items when printing */
+@media print {
+ div.related {
+ display: none;
+ }
+}
+
+img.github {
+ position: absolute;
+ top: 0;
+ border: 0;
+ right: 0;
+}
\ No newline at end of file
diff --git a/docs/docs/_static/basic.css b/docs/docs/_static/basic.css
new file mode 100644
index 0000000..0028826
--- /dev/null
+++ b/docs/docs/_static/basic.css
@@ -0,0 +1,906 @@
+/*
+ * Sphinx stylesheet -- basic theme.
+ */
+
+/* -- main layout ----------------------------------------------------------- */
+
+div.clearer {
+ clear: both;
+}
+
+div.section::after {
+ display: block;
+ content: '';
+ clear: left;
+}
+
+/* -- relbar ---------------------------------------------------------------- */
+
+div.related {
+ width: 100%;
+ font-size: 90%;
+}
+
+div.related h3 {
+ display: none;
+}
+
+div.related ul {
+ margin: 0;
+ padding: 0 0 0 10px;
+ list-style: none;
+}
+
+div.related li {
+ display: inline;
+}
+
+div.related li.right {
+ float: right;
+ margin-right: 5px;
+}
+
+/* -- sidebar --------------------------------------------------------------- */
+
+div.sphinxsidebarwrapper {
+ padding: 10px 5px 0 10px;
+}
+
+div.sphinxsidebar {
+ float: left;
+ width: 230px;
+ margin-left: -100%;
+ font-size: 90%;
+ word-wrap: break-word;
+ overflow-wrap : break-word;
+}
+
+div.sphinxsidebar ul {
+ list-style: none;
+}
+
+div.sphinxsidebar ul ul,
+div.sphinxsidebar ul.want-points {
+ margin-left: 20px;
+ list-style: square;
+}
+
+div.sphinxsidebar ul ul {
+ margin-top: 0;
+ margin-bottom: 0;
+}
+
+div.sphinxsidebar form {
+ margin-top: 10px;
+}
+
+div.sphinxsidebar input {
+ border: 1px solid #98dbcc;
+ font-family: sans-serif;
+ font-size: 1em;
+}
+
+div.sphinxsidebar #searchbox form.search {
+ overflow: hidden;
+}
+
+div.sphinxsidebar #searchbox input[type="text"] {
+ float: left;
+ width: 80%;
+ padding: 0.25em;
+ box-sizing: border-box;
+}
+
+div.sphinxsidebar #searchbox input[type="submit"] {
+ float: left;
+ width: 20%;
+ border-left: none;
+ padding: 0.25em;
+ box-sizing: border-box;
+}
+
+
+img {
+ border: 0;
+ max-width: 100%;
+}
+
+/* -- search page ----------------------------------------------------------- */
+
+ul.search {
+ margin-top: 10px;
+}
+
+ul.search li {
+ padding: 5px 0;
+}
+
+ul.search li a {
+ font-weight: bold;
+}
+
+ul.search li p.context {
+ color: #888;
+ margin: 2px 0 0 30px;
+ text-align: left;
+}
+
+ul.keywordmatches li.goodmatch a {
+ font-weight: bold;
+}
+
+/* -- index page ------------------------------------------------------------ */
+
+table.contentstable {
+ width: 90%;
+ margin-left: auto;
+ margin-right: auto;
+}
+
+table.contentstable p.biglink {
+ line-height: 150%;
+}
+
+a.biglink {
+ font-size: 1.3em;
+}
+
+span.linkdescr {
+ font-style: italic;
+ padding-top: 5px;
+ font-size: 90%;
+}
+
+/* -- general index --------------------------------------------------------- */
+
+table.indextable {
+ width: 100%;
+}
+
+table.indextable td {
+ text-align: left;
+ vertical-align: top;
+}
+
+table.indextable ul {
+ margin-top: 0;
+ margin-bottom: 0;
+ list-style-type: none;
+}
+
+table.indextable > tbody > tr > td > ul {
+ padding-left: 0em;
+}
+
+table.indextable tr.pcap {
+ height: 10px;
+}
+
+table.indextable tr.cap {
+ margin-top: 10px;
+ background-color: #f2f2f2;
+}
+
+img.toggler {
+ margin-right: 3px;
+ margin-top: 3px;
+ cursor: pointer;
+}
+
+div.modindex-jumpbox {
+ border-top: 1px solid #ddd;
+ border-bottom: 1px solid #ddd;
+ margin: 1em 0 1em 0;
+ padding: 0.4em;
+}
+
+div.genindex-jumpbox {
+ border-top: 1px solid #ddd;
+ border-bottom: 1px solid #ddd;
+ margin: 1em 0 1em 0;
+ padding: 0.4em;
+}
+
+/* -- domain module index --------------------------------------------------- */
+
+table.modindextable td {
+ padding: 2px;
+ border-collapse: collapse;
+}
+
+/* -- general body styles --------------------------------------------------- */
+
+div.body {
+ min-width: inherit;
+ max-width: 800px;
+}
+
+div.body p, div.body dd, div.body li, div.body blockquote {
+ -moz-hyphens: auto;
+ -ms-hyphens: auto;
+ -webkit-hyphens: auto;
+ hyphens: auto;
+}
+
+a.headerlink {
+ visibility: hidden;
+}
+
+a:visited {
+ color: #551A8B;
+}
+
+h1:hover > a.headerlink,
+h2:hover > a.headerlink,
+h3:hover > a.headerlink,
+h4:hover > a.headerlink,
+h5:hover > a.headerlink,
+h6:hover > a.headerlink,
+dt:hover > a.headerlink,
+caption:hover > a.headerlink,
+p.caption:hover > a.headerlink,
+div.code-block-caption:hover > a.headerlink {
+ visibility: visible;
+}
+
+div.body p.caption {
+ text-align: inherit;
+}
+
+div.body td {
+ text-align: left;
+}
+
+.first {
+ margin-top: 0 !important;
+}
+
+p.rubric {
+ margin-top: 30px;
+ font-weight: bold;
+}
+
+img.align-left, figure.align-left, .figure.align-left, object.align-left {
+ clear: left;
+ float: left;
+ margin-right: 1em;
+}
+
+img.align-right, figure.align-right, .figure.align-right, object.align-right {
+ clear: right;
+ float: right;
+ margin-left: 1em;
+}
+
+img.align-center, figure.align-center, .figure.align-center, object.align-center {
+ display: block;
+ margin-left: auto;
+ margin-right: auto;
+}
+
+img.align-default, figure.align-default, .figure.align-default {
+ display: block;
+ margin-left: auto;
+ margin-right: auto;
+}
+
+.align-left {
+ text-align: left;
+}
+
+.align-center {
+ text-align: center;
+}
+
+.align-default {
+ text-align: center;
+}
+
+.align-right {
+ text-align: right;
+}
+
+/* -- sidebars -------------------------------------------------------------- */
+
+div.sidebar,
+aside.sidebar {
+ margin: 0 0 0.5em 1em;
+ border: 1px solid #ddb;
+ padding: 7px;
+ background-color: #ffe;
+ width: 40%;
+ float: right;
+ clear: right;
+ overflow-x: auto;
+}
+
+p.sidebar-title {
+ font-weight: bold;
+}
+
+nav.contents,
+aside.topic,
+div.admonition, div.topic, blockquote {
+ clear: left;
+}
+
+/* -- topics ---------------------------------------------------------------- */
+
+nav.contents,
+aside.topic,
+div.topic {
+ border: 1px solid #ccc;
+ padding: 7px;
+ margin: 10px 0 10px 0;
+}
+
+p.topic-title {
+ font-size: 1.1em;
+ font-weight: bold;
+ margin-top: 10px;
+}
+
+/* -- admonitions ----------------------------------------------------------- */
+
+div.admonition {
+ margin-top: 10px;
+ margin-bottom: 10px;
+ padding: 7px;
+}
+
+div.admonition dt {
+ font-weight: bold;
+}
+
+p.admonition-title {
+ margin: 0px 10px 5px 0px;
+ font-weight: bold;
+}
+
+div.body p.centered {
+ text-align: center;
+ margin-top: 25px;
+}
+
+/* -- content of sidebars/topics/admonitions -------------------------------- */
+
+div.sidebar > :last-child,
+aside.sidebar > :last-child,
+nav.contents > :last-child,
+aside.topic > :last-child,
+div.topic > :last-child,
+div.admonition > :last-child {
+ margin-bottom: 0;
+}
+
+div.sidebar::after,
+aside.sidebar::after,
+nav.contents::after,
+aside.topic::after,
+div.topic::after,
+div.admonition::after,
+blockquote::after {
+ display: block;
+ content: '';
+ clear: both;
+}
+
+/* -- tables ---------------------------------------------------------------- */
+
+table.docutils {
+ margin-top: 10px;
+ margin-bottom: 10px;
+ border: 0;
+ border-collapse: collapse;
+}
+
+table.align-center {
+ margin-left: auto;
+ margin-right: auto;
+}
+
+table.align-default {
+ margin-left: auto;
+ margin-right: auto;
+}
+
+table caption span.caption-number {
+ font-style: italic;
+}
+
+table caption span.caption-text {
+}
+
+table.docutils td, table.docutils th {
+ padding: 1px 8px 1px 5px;
+ border-top: 0;
+ border-left: 0;
+ border-right: 0;
+ border-bottom: 1px solid #aaa;
+}
+
+th {
+ text-align: left;
+ padding-right: 5px;
+}
+
+table.citation {
+ border-left: solid 1px gray;
+ margin-left: 1px;
+}
+
+table.citation td {
+ border-bottom: none;
+}
+
+th > :first-child,
+td > :first-child {
+ margin-top: 0px;
+}
+
+th > :last-child,
+td > :last-child {
+ margin-bottom: 0px;
+}
+
+/* -- figures --------------------------------------------------------------- */
+
+div.figure, figure {
+ margin: 0.5em;
+ padding: 0.5em;
+}
+
+div.figure p.caption, figcaption {
+ padding: 0.3em;
+}
+
+div.figure p.caption span.caption-number,
+figcaption span.caption-number {
+ font-style: italic;
+}
+
+div.figure p.caption span.caption-text,
+figcaption span.caption-text {
+}
+
+/* -- field list styles ----------------------------------------------------- */
+
+table.field-list td, table.field-list th {
+ border: 0 !important;
+}
+
+.field-list ul {
+ margin: 0;
+ padding-left: 1em;
+}
+
+.field-list p {
+ margin: 0;
+}
+
+.field-name {
+ -moz-hyphens: manual;
+ -ms-hyphens: manual;
+ -webkit-hyphens: manual;
+ hyphens: manual;
+}
+
+/* -- hlist styles ---------------------------------------------------------- */
+
+table.hlist {
+ margin: 1em 0;
+}
+
+table.hlist td {
+ vertical-align: top;
+}
+
+/* -- object description styles --------------------------------------------- */
+
+.sig {
+ font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
+}
+
+.sig-name, code.descname {
+ background-color: transparent;
+ font-weight: bold;
+}
+
+.sig-name {
+ font-size: 1.1em;
+}
+
+code.descname {
+ font-size: 1.2em;
+}
+
+.sig-prename, code.descclassname {
+ background-color: transparent;
+}
+
+.optional {
+ font-size: 1.3em;
+}
+
+.sig-paren {
+ font-size: larger;
+}
+
+.sig-param.n {
+ font-style: italic;
+}
+
+/* C++ specific styling */
+
+.sig-inline.c-texpr,
+.sig-inline.cpp-texpr {
+ font-family: unset;
+}
+
+.sig.c .k, .sig.c .kt,
+.sig.cpp .k, .sig.cpp .kt {
+ color: #0033B3;
+}
+
+.sig.c .m,
+.sig.cpp .m {
+ color: #1750EB;
+}
+
+.sig.c .s, .sig.c .sc,
+.sig.cpp .s, .sig.cpp .sc {
+ color: #067D17;
+}
+
+
+/* -- other body styles ----------------------------------------------------- */
+
+ol.arabic {
+ list-style: decimal;
+}
+
+ol.loweralpha {
+ list-style: lower-alpha;
+}
+
+ol.upperalpha {
+ list-style: upper-alpha;
+}
+
+ol.lowerroman {
+ list-style: lower-roman;
+}
+
+ol.upperroman {
+ list-style: upper-roman;
+}
+
+:not(li) > ol > li:first-child > :first-child,
+:not(li) > ul > li:first-child > :first-child {
+ margin-top: 0px;
+}
+
+:not(li) > ol > li:last-child > :last-child,
+:not(li) > ul > li:last-child > :last-child {
+ margin-bottom: 0px;
+}
+
+ol.simple ol p,
+ol.simple ul p,
+ul.simple ol p,
+ul.simple ul p {
+ margin-top: 0;
+}
+
+ol.simple > li:not(:first-child) > p,
+ul.simple > li:not(:first-child) > p {
+ margin-top: 0;
+}
+
+ol.simple p,
+ul.simple p {
+ margin-bottom: 0;
+}
+
+aside.footnote > span,
+div.citation > span {
+ float: left;
+}
+aside.footnote > span:last-of-type,
+div.citation > span:last-of-type {
+ padding-right: 0.5em;
+}
+aside.footnote > p {
+ margin-left: 2em;
+}
+div.citation > p {
+ margin-left: 4em;
+}
+aside.footnote > p:last-of-type,
+div.citation > p:last-of-type {
+ margin-bottom: 0em;
+}
+aside.footnote > p:last-of-type:after,
+div.citation > p:last-of-type:after {
+ content: "";
+ clear: both;
+}
+
+dl.field-list {
+ display: grid;
+ grid-template-columns: fit-content(30%) auto;
+}
+
+dl.field-list > dt {
+ font-weight: bold;
+ word-break: break-word;
+ padding-left: 0.5em;
+ padding-right: 5px;
+}
+
+dl.field-list > dd {
+ padding-left: 0.5em;
+ margin-top: 0em;
+ margin-left: 0em;
+ margin-bottom: 0em;
+}
+
+dl {
+ margin-bottom: 15px;
+}
+
+dd > :first-child {
+ margin-top: 0px;
+}
+
+dd ul, dd table {
+ margin-bottom: 10px;
+}
+
+dd {
+ margin-top: 3px;
+ margin-bottom: 10px;
+ margin-left: 30px;
+}
+
+.sig dd {
+ margin-top: 0px;
+ margin-bottom: 0px;
+}
+
+.sig dl {
+ margin-top: 0px;
+ margin-bottom: 0px;
+}
+
+dl > dd:last-child,
+dl > dd:last-child > :last-child {
+ margin-bottom: 0;
+}
+
+dt:target, span.highlighted {
+ background-color: #fbe54e;
+}
+
+rect.highlighted {
+ fill: #fbe54e;
+}
+
+dl.glossary dt {
+ font-weight: bold;
+ font-size: 1.1em;
+}
+
+.versionmodified {
+ font-style: italic;
+}
+
+.system-message {
+ background-color: #fda;
+ padding: 5px;
+ border: 3px solid red;
+}
+
+.footnote:target {
+ background-color: #ffa;
+}
+
+.line-block {
+ display: block;
+ margin-top: 1em;
+ margin-bottom: 1em;
+}
+
+.line-block .line-block {
+ margin-top: 0;
+ margin-bottom: 0;
+ margin-left: 1.5em;
+}
+
+.guilabel, .menuselection {
+ font-family: sans-serif;
+}
+
+.accelerator {
+ text-decoration: underline;
+}
+
+.classifier {
+ font-style: oblique;
+}
+
+.classifier:before {
+ font-style: normal;
+ margin: 0 0.5em;
+ content: ":";
+ display: inline-block;
+}
+
+abbr, acronym {
+ border-bottom: dotted 1px;
+ cursor: help;
+}
+
+/* -- code displays --------------------------------------------------------- */
+
+pre {
+ overflow: auto;
+ overflow-y: hidden; /* fixes display issues on Chrome browsers */
+}
+
+pre, div[class*="highlight-"] {
+ clear: both;
+}
+
+span.pre {
+ -moz-hyphens: none;
+ -ms-hyphens: none;
+ -webkit-hyphens: none;
+ hyphens: none;
+ white-space: nowrap;
+}
+
+div[class*="highlight-"] {
+ margin: 1em 0;
+}
+
+td.linenos pre {
+ border: 0;
+ background-color: transparent;
+ color: #aaa;
+}
+
+table.highlighttable {
+ display: block;
+}
+
+table.highlighttable tbody {
+ display: block;
+}
+
+table.highlighttable tr {
+ display: flex;
+}
+
+table.highlighttable td {
+ margin: 0;
+ padding: 0;
+}
+
+table.highlighttable td.linenos {
+ padding-right: 0.5em;
+}
+
+table.highlighttable td.code {
+ flex: 1;
+ overflow: hidden;
+}
+
+.highlight .hll {
+ display: block;
+}
+
+div.highlight pre,
+table.highlighttable pre {
+ margin: 0;
+}
+
+div.code-block-caption + div {
+ margin-top: 0;
+}
+
+div.code-block-caption {
+ margin-top: 1em;
+ padding: 2px 5px;
+ font-size: small;
+}
+
+div.code-block-caption code {
+ background-color: transparent;
+}
+
+table.highlighttable td.linenos,
+span.linenos,
+div.highlight span.gp { /* gp: Generic.Prompt */
+ user-select: none;
+ -webkit-user-select: text; /* Safari fallback only */
+ -webkit-user-select: none; /* Chrome/Safari */
+ -moz-user-select: none; /* Firefox */
+ -ms-user-select: none; /* IE10+ */
+}
+
+div.code-block-caption span.caption-number {
+ padding: 0.1em 0.3em;
+ font-style: italic;
+}
+
+div.code-block-caption span.caption-text {
+}
+
+div.literal-block-wrapper {
+ margin: 1em 0;
+}
+
+code.xref, a code {
+ background-color: transparent;
+ font-weight: bold;
+}
+
+h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
+ background-color: transparent;
+}
+
+.viewcode-link {
+ float: right;
+}
+
+.viewcode-back {
+ float: right;
+ font-family: sans-serif;
+}
+
+div.viewcode-block:target {
+ margin: -1px -10px;
+ padding: 0 10px;
+}
+
+/* -- math display ---------------------------------------------------------- */
+
+img.math {
+ vertical-align: middle;
+}
+
+div.body div.math p {
+ text-align: center;
+}
+
+span.eqno {
+ float: right;
+}
+
+span.eqno a.headerlink {
+ position: absolute;
+ z-index: 1;
+}
+
+div.math:hover a.headerlink {
+ visibility: visible;
+}
+
+/* -- printout stylesheet --------------------------------------------------- */
+
+@media print {
+ div.document,
+ div.documentwrapper,
+ div.bodywrapper {
+ margin: 0 !important;
+ width: 100%;
+ }
+
+ div.sphinxsidebar,
+ div.related,
+ div.footer,
+ #top-link {
+ display: none;
+ }
+}
\ No newline at end of file
diff --git a/docs/docs/_static/custom.css b/docs/docs/_static/custom.css
new file mode 100644
index 0000000..2a924f1
--- /dev/null
+++ b/docs/docs/_static/custom.css
@@ -0,0 +1 @@
+/* This file intentionally left blank. */
diff --git a/docs/docs/_static/doctools.js b/docs/docs/_static/doctools.js
new file mode 100644
index 0000000..0398ebb
--- /dev/null
+++ b/docs/docs/_static/doctools.js
@@ -0,0 +1,149 @@
+/*
+ * Base JavaScript utilities for all Sphinx HTML documentation.
+ */
+"use strict";
+
+const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([
+ "TEXTAREA",
+ "INPUT",
+ "SELECT",
+ "BUTTON",
+]);
+
+const _ready = (callback) => {
+ if (document.readyState !== "loading") {
+ callback();
+ } else {
+ document.addEventListener("DOMContentLoaded", callback);
+ }
+};
+
+/**
+ * Small JavaScript module for the documentation.
+ */
+const Documentation = {
+ init: () => {
+ Documentation.initDomainIndexTable();
+ Documentation.initOnKeyListeners();
+ },
+
+ /**
+ * i18n support
+ */
+ TRANSLATIONS: {},
+ PLURAL_EXPR: (n) => (n === 1 ? 0 : 1),
+ LOCALE: "unknown",
+
+ // gettext and ngettext don't access this so that the functions
+ // can safely bound to a different name (_ = Documentation.gettext)
+ gettext: (string) => {
+ const translated = Documentation.TRANSLATIONS[string];
+ switch (typeof translated) {
+ case "undefined":
+ return string; // no translation
+ case "string":
+ return translated; // translation exists
+ default:
+ return translated[0]; // (singular, plural) translation tuple exists
+ }
+ },
+
+ ngettext: (singular, plural, n) => {
+ const translated = Documentation.TRANSLATIONS[singular];
+ if (typeof translated !== "undefined")
+ return translated[Documentation.PLURAL_EXPR(n)];
+ return n === 1 ? singular : plural;
+ },
+
+ addTranslations: (catalog) => {
+ Object.assign(Documentation.TRANSLATIONS, catalog.messages);
+ Documentation.PLURAL_EXPR = new Function(
+ "n",
+ `return (${catalog.plural_expr})`
+ );
+ Documentation.LOCALE = catalog.locale;
+ },
+
+ /**
+ * helper function to focus on search bar
+ */
+ focusSearchBar: () => {
+ document.querySelectorAll("input[name=q]")[0]?.focus();
+ },
+
+ /**
+ * Initialise the domain index toggle buttons
+ */
+ initDomainIndexTable: () => {
+ const toggler = (el) => {
+ const idNumber = el.id.substr(7);
+ const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`);
+ if (el.src.substr(-9) === "minus.png") {
+ el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`;
+ toggledRows.forEach((el) => (el.style.display = "none"));
+ } else {
+ el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`;
+ toggledRows.forEach((el) => (el.style.display = ""));
+ }
+ };
+
+ const togglerElements = document.querySelectorAll("img.toggler");
+ togglerElements.forEach((el) =>
+ el.addEventListener("click", (event) => toggler(event.currentTarget))
+ );
+ togglerElements.forEach((el) => (el.style.display = ""));
+ if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler);
+ },
+
+ initOnKeyListeners: () => {
+ // only install a listener if it is really needed
+ if (
+ !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS &&
+ !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS
+ )
+ return;
+
+ document.addEventListener("keydown", (event) => {
+ // bail for input elements
+ if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return;
+ // bail with special keys
+ if (event.altKey || event.ctrlKey || event.metaKey) return;
+
+ if (!event.shiftKey) {
+ switch (event.key) {
+ case "ArrowLeft":
+ if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
+
+ const prevLink = document.querySelector('link[rel="prev"]');
+ if (prevLink && prevLink.href) {
+ window.location.href = prevLink.href;
+ event.preventDefault();
+ }
+ break;
+ case "ArrowRight":
+ if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
+
+ const nextLink = document.querySelector('link[rel="next"]');
+ if (nextLink && nextLink.href) {
+ window.location.href = nextLink.href;
+ event.preventDefault();
+ }
+ break;
+ }
+ }
+
+ // some keyboard layouts may need Shift to get /
+ switch (event.key) {
+ case "/":
+ if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break;
+ Documentation.focusSearchBar();
+ event.preventDefault();
+ }
+ });
+ },
+};
+
+// quick alias for translations
+const _ = Documentation.gettext;
+
+_ready(Documentation.init);
diff --git a/docs/docs/_static/documentation_options.js b/docs/docs/_static/documentation_options.js
new file mode 100644
index 0000000..b86f7e3
--- /dev/null
+++ b/docs/docs/_static/documentation_options.js
@@ -0,0 +1,13 @@
+const DOCUMENTATION_OPTIONS = {
+ VERSION: '0.20',
+ LANGUAGE: 'en',
+ COLLAPSE_INDEX: false,
+ BUILDER: 'html',
+ FILE_SUFFIX: '.html',
+ LINK_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt',
+ NAVIGATION_WITH_KEYS: false,
+ SHOW_SEARCH_SUMMARY: true,
+ ENABLE_SEARCH_SHORTCUTS: true,
+};
\ No newline at end of file
diff --git a/docs/docs/_static/file.png b/docs/docs/_static/file.png
new file mode 100644
index 0000000..a858a41
Binary files /dev/null and b/docs/docs/_static/file.png differ
diff --git a/docs/docs/_static/github-banner.svg b/docs/docs/_static/github-banner.svg
new file mode 100644
index 0000000..c47d9dc
--- /dev/null
+++ b/docs/docs/_static/github-banner.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="80" height="80" viewBox="0 0 250 250" fill="#fff">
+ <path d="M0 0l115 115h15l12 27 108 108V0z" fill="#151513"/>
+ <path d="M128 109c-15-9-9-19-9-19 3-7 2-11 2-11-1-7 3-2 3-2 4 5 2 11 2 11-3 10 5 15 9 16"/>
+ <path d="M115 115s4 2 5 0l14-14c3-2 6-3 8-3-8-11-15-24 2-41 5-5 10-7 16-7 1-2 3-7 12-11 0 0 5 3 7 16 4 2 8 5 12 9s7 8 9 12c14 3 17 7 17 7-4 8-9 11-11 11 0 6-2 11-7 16-16 16-30 10-41 2 0 3-1 7-5 11l-12 11c-1 1 1 5 1 5z"/>
+</svg>
diff --git a/docs/docs/_static/language_data.js b/docs/docs/_static/language_data.js
new file mode 100644
index 0000000..c7fe6c6
--- /dev/null
+++ b/docs/docs/_static/language_data.js
@@ -0,0 +1,192 @@
+/*
+ * This script contains the language-specific data used by searchtools.js,
+ * namely the list of stopwords, stemmer, scorer and splitter.
+ */
+
+var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"];
+
+
+/* Non-minified version is copied as a separate JS file, if available */
+
+/**
+ * Porter Stemmer
+ */
+var Stemmer = function() {
+
+ var step2list = {
+ ational: 'ate',
+ tional: 'tion',
+ enci: 'ence',
+ anci: 'ance',
+ izer: 'ize',
+ bli: 'ble',
+ alli: 'al',
+ entli: 'ent',
+ eli: 'e',
+ ousli: 'ous',
+ ization: 'ize',
+ ation: 'ate',
+ ator: 'ate',
+ alism: 'al',
+ iveness: 'ive',
+ fulness: 'ful',
+ ousness: 'ous',
+ aliti: 'al',
+ iviti: 'ive',
+ biliti: 'ble',
+ logi: 'log'
+ };
+
+ var step3list = {
+ icate: 'ic',
+ ative: '',
+ alize: 'al',
+ iciti: 'ic',
+ ical: 'ic',
+ ful: '',
+ ness: ''
+ };
+
+ var c = "[^aeiou]"; // consonant
+ var v = "[aeiouy]"; // vowel
+ var C = c + "[^aeiouy]*"; // consonant sequence
+ var V = v + "[aeiou]*"; // vowel sequence
+
+ var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0
+ var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1
+ var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1
+ var s_v = "^(" + C + ")?" + v; // vowel in stem
+
+ this.stemWord = function (w) {
+ var stem;
+ var suffix;
+ var firstch;
+ var origword = w;
+
+ if (w.length < 3)
+ return w;
+
+ var re;
+ var re2;
+ var re3;
+ var re4;
+
+ firstch = w.substr(0,1);
+ if (firstch == "y")
+ w = firstch.toUpperCase() + w.substr(1);
+
+ // Step 1a
+ re = /^(.+?)(ss|i)es$/;
+ re2 = /^(.+?)([^s])s$/;
+
+ if (re.test(w))
+ w = w.replace(re,"$1$2");
+ else if (re2.test(w))
+ w = w.replace(re2,"$1$2");
+
+ // Step 1b
+ re = /^(.+?)eed$/;
+ re2 = /^(.+?)(ed|ing)$/;
+ if (re.test(w)) {
+ var fp = re.exec(w);
+ re = new RegExp(mgr0);
+ if (re.test(fp[1])) {
+ re = /.$/;
+ w = w.replace(re,"");
+ }
+ }
+ else if (re2.test(w)) {
+ var fp = re2.exec(w);
+ stem = fp[1];
+ re2 = new RegExp(s_v);
+ if (re2.test(stem)) {
+ w = stem;
+ re2 = /(at|bl|iz)$/;
+ re3 = new RegExp("([^aeiouylsz])\\1$");
+ re4 = new RegExp("^" + C + v + "[^aeiouwxy]$");
+ if (re2.test(w))
+ w = w + "e";
+ else if (re3.test(w)) {
+ re = /.$/;
+ w = w.replace(re,"");
+ }
+ else if (re4.test(w))
+ w = w + "e";
+ }
+ }
+
+ // Step 1c
+ re = /^(.+?)y$/;
+ if (re.test(w)) {
+ var fp = re.exec(w);
+ stem = fp[1];
+ re = new RegExp(s_v);
+ if (re.test(stem))
+ w = stem + "i";
+ }
+
+ // Step 2
+ re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/;
+ if (re.test(w)) {
+ var fp = re.exec(w);
+ stem = fp[1];
+ suffix = fp[2];
+ re = new RegExp(mgr0);
+ if (re.test(stem))
+ w = stem + step2list[suffix];
+ }
+
+ // Step 3
+ re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/;
+ if (re.test(w)) {
+ var fp = re.exec(w);
+ stem = fp[1];
+ suffix = fp[2];
+ re = new RegExp(mgr0);
+ if (re.test(stem))
+ w = stem + step3list[suffix];
+ }
+
+ // Step 4
+ re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/;
+ re2 = /^(.+?)(s|t)(ion)$/;
+ if (re.test(w)) {
+ var fp = re.exec(w);
+ stem = fp[1];
+ re = new RegExp(mgr1);
+ if (re.test(stem))
+ w = stem;
+ }
+ else if (re2.test(w)) {
+ var fp = re2.exec(w);
+ stem = fp[1] + fp[2];
+ re2 = new RegExp(mgr1);
+ if (re2.test(stem))
+ w = stem;
+ }
+
+ // Step 5
+ re = /^(.+?)e$/;
+ if (re.test(w)) {
+ var fp = re.exec(w);
+ stem = fp[1];
+ re = new RegExp(mgr1);
+ re2 = new RegExp(meq1);
+ re3 = new RegExp("^" + C + v + "[^aeiouwxy]$");
+ if (re.test(stem) || (re2.test(stem) && !(re3.test(stem))))
+ w = stem;
+ }
+ re = /ll$/;
+ re2 = new RegExp(mgr1);
+ if (re.test(w) && re2.test(w)) {
+ re = /.$/;
+ w = w.replace(re,"");
+ }
+
+ // and turn initial Y back to y
+ if (firstch == "y")
+ w = firstch.toLowerCase() + w.substr(1);
+ return w;
+ }
+}
+
diff --git a/docs/docs/_static/minus.png b/docs/docs/_static/minus.png
new file mode 100644
index 0000000..d96755f
Binary files /dev/null and b/docs/docs/_static/minus.png differ
diff --git a/docs/docs/_static/plus.png b/docs/docs/_static/plus.png
new file mode 100644
index 0000000..7107cec
Binary files /dev/null and b/docs/docs/_static/plus.png differ
diff --git a/docs/docs/_static/pygments.css b/docs/docs/_static/pygments.css
new file mode 100644
index 0000000..04a4174
--- /dev/null
+++ b/docs/docs/_static/pygments.css
@@ -0,0 +1,84 @@
+pre { line-height: 125%; }
+td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
+span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
+td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
+span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
+.highlight .hll { background-color: #ffffcc }
+.highlight { background: #f8f8f8; }
+.highlight .c { color: #8f5902; font-style: italic } /* Comment */
+.highlight .err { color: #a40000; border: 1px solid #ef2929 } /* Error */
+.highlight .g { color: #000000 } /* Generic */
+.highlight .k { color: #004461; font-weight: bold } /* Keyword */
+.highlight .l { color: #000000 } /* Literal */
+.highlight .n { color: #000000 } /* Name */
+.highlight .o { color: #582800 } /* Operator */
+.highlight .x { color: #000000 } /* Other */
+.highlight .p { color: #000000; font-weight: bold } /* Punctuation */
+.highlight .ch { color: #8f5902; font-style: italic } /* Comment.Hashbang */
+.highlight .cm { color: #8f5902; font-style: italic } /* Comment.Multiline */
+.highlight .cp { color: #8f5902 } /* Comment.Preproc */
+.highlight .cpf { color: #8f5902; font-style: italic } /* Comment.PreprocFile */
+.highlight .c1 { color: #8f5902; font-style: italic } /* Comment.Single */
+.highlight .cs { color: #8f5902; font-style: italic } /* Comment.Special */
+.highlight .gd { color: #a40000 } /* Generic.Deleted */
+.highlight .ge { color: #000000; font-style: italic } /* Generic.Emph */
+.highlight .ges { color: #000000 } /* Generic.EmphStrong */
+.highlight .gr { color: #ef2929 } /* Generic.Error */
+.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
+.highlight .gi { color: #00A000 } /* Generic.Inserted */
+.highlight .go { color: #888888 } /* Generic.Output */
+.highlight .gp { color: #745334 } /* Generic.Prompt */
+.highlight .gs { color: #000000; font-weight: bold } /* Generic.Strong */
+.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
+.highlight .gt { color: #a40000; font-weight: bold } /* Generic.Traceback */
+.highlight .kc { color: #004461; font-weight: bold } /* Keyword.Constant */
+.highlight .kd { color: #004461; font-weight: bold } /* Keyword.Declaration */
+.highlight .kn { color: #004461; font-weight: bold } /* Keyword.Namespace */
+.highlight .kp { color: #004461; font-weight: bold } /* Keyword.Pseudo */
+.highlight .kr { color: #004461; font-weight: bold } /* Keyword.Reserved */
+.highlight .kt { color: #004461; font-weight: bold } /* Keyword.Type */
+.highlight .ld { color: #000000 } /* Literal.Date */
+.highlight .m { color: #990000 } /* Literal.Number */
+.highlight .s { color: #4e9a06 } /* Literal.String */
+.highlight .na { color: #c4a000 } /* Name.Attribute */
+.highlight .nb { color: #004461 } /* Name.Builtin */
+.highlight .nc { color: #000000 } /* Name.Class */
+.highlight .no { color: #000000 } /* Name.Constant */
+.highlight .nd { color: #888888 } /* Name.Decorator */
+.highlight .ni { color: #ce5c00 } /* Name.Entity */
+.highlight .ne { color: #cc0000; font-weight: bold } /* Name.Exception */
+.highlight .nf { color: #000000 } /* Name.Function */
+.highlight .nl { color: #f57900 } /* Name.Label */
+.highlight .nn { color: #000000 } /* Name.Namespace */
+.highlight .nx { color: #000000 } /* Name.Other */
+.highlight .py { color: #000000 } /* Name.Property */
+.highlight .nt { color: #004461; font-weight: bold } /* Name.Tag */
+.highlight .nv { color: #000000 } /* Name.Variable */
+.highlight .ow { color: #004461; font-weight: bold } /* Operator.Word */
+.highlight .pm { color: #000000; font-weight: bold } /* Punctuation.Marker */
+.highlight .w { color: #f8f8f8 } /* Text.Whitespace */
+.highlight .mb { color: #990000 } /* Literal.Number.Bin */
+.highlight .mf { color: #990000 } /* Literal.Number.Float */
+.highlight .mh { color: #990000 } /* Literal.Number.Hex */
+.highlight .mi { color: #990000 } /* Literal.Number.Integer */
+.highlight .mo { color: #990000 } /* Literal.Number.Oct */
+.highlight .sa { color: #4e9a06 } /* Literal.String.Affix */
+.highlight .sb { color: #4e9a06 } /* Literal.String.Backtick */
+.highlight .sc { color: #4e9a06 } /* Literal.String.Char */
+.highlight .dl { color: #4e9a06 } /* Literal.String.Delimiter */
+.highlight .sd { color: #8f5902; font-style: italic } /* Literal.String.Doc */
+.highlight .s2 { color: #4e9a06 } /* Literal.String.Double */
+.highlight .se { color: #4e9a06 } /* Literal.String.Escape */
+.highlight .sh { color: #4e9a06 } /* Literal.String.Heredoc */
+.highlight .si { color: #4e9a06 } /* Literal.String.Interpol */
+.highlight .sx { color: #4e9a06 } /* Literal.String.Other */
+.highlight .sr { color: #4e9a06 } /* Literal.String.Regex */
+.highlight .s1 { color: #4e9a06 } /* Literal.String.Single */
+.highlight .ss { color: #4e9a06 } /* Literal.String.Symbol */
+.highlight .bp { color: #3465a4 } /* Name.Builtin.Pseudo */
+.highlight .fm { color: #000000 } /* Name.Function.Magic */
+.highlight .vc { color: #000000 } /* Name.Variable.Class */
+.highlight .vg { color: #000000 } /* Name.Variable.Global */
+.highlight .vi { color: #000000 } /* Name.Variable.Instance */
+.highlight .vm { color: #000000 } /* Name.Variable.Magic */
+.highlight .il { color: #990000 } /* Literal.Number.Integer.Long */
\ No newline at end of file
diff --git a/docs/docs/_static/searchtools.js b/docs/docs/_static/searchtools.js
new file mode 100644
index 0000000..91f4be5
--- /dev/null
+++ b/docs/docs/_static/searchtools.js
@@ -0,0 +1,635 @@
+/*
+ * Sphinx JavaScript utilities for the full-text search.
+ */
+"use strict";
+
+/**
+ * Simple result scoring code.
+ */
+if (typeof Scorer === "undefined") {
+ var Scorer = {
+ // Implement the following function to further tweak the score for each result
+ // The function takes a result array [docname, title, anchor, descr, score, filename]
+ // and returns the new score.
+ /*
+ score: result => {
+ const [docname, title, anchor, descr, score, filename, kind] = result
+ return score
+ },
+ */
+
+ // query matches the full name of an object
+ objNameMatch: 11,
+ // or matches in the last dotted part of the object name
+ objPartialMatch: 6,
+ // Additive scores depending on the priority of the object
+ objPrio: {
+ 0: 15, // used to be importantResults
+ 1: 5, // used to be objectResults
+ 2: -5, // used to be unimportantResults
+ },
+ // Used when the priority is not in the mapping.
+ objPrioDefault: 0,
+
+ // query found in title
+ title: 15,
+ partialTitle: 7,
+ // query found in terms
+ term: 5,
+ partialTerm: 2,
+ };
+}
+
+// Global search result kind enum, used by themes to style search results.
+class SearchResultKind {
+ static get index() { return "index"; }
+ static get object() { return "object"; }
+ static get text() { return "text"; }
+ static get title() { return "title"; }
+}
+
+const _removeChildren = (element) => {
+ while (element && element.lastChild) element.removeChild(element.lastChild);
+};
+
+/**
+ * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping
+ */
+const _escapeRegExp = (string) =>
+ string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
+
+const _displayItem = (item, searchTerms, highlightTerms) => {
+ const docBuilder = DOCUMENTATION_OPTIONS.BUILDER;
+ const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX;
+ const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX;
+ const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY;
+ const contentRoot = document.documentElement.dataset.content_root;
+
+ const [docName, title, anchor, descr, score, _filename, kind] = item;
+
+ let listItem = document.createElement("li");
+ // Add a class representing the item's type:
+ // can be used by a theme's CSS selector for styling
+ // See SearchResultKind for the class names.
+ listItem.classList.add(`kind-${kind}`);
+ let requestUrl;
+ let linkUrl;
+ if (docBuilder === "dirhtml") {
+ // dirhtml builder
+ let dirname = docName + "/";
+ if (dirname.match(/\/index\/$/))
+ dirname = dirname.substring(0, dirname.length - 6);
+ else if (dirname === "index/") dirname = "";
+ requestUrl = contentRoot + dirname;
+ linkUrl = requestUrl;
+ } else {
+ // normal html builders
+ requestUrl = contentRoot + docName + docFileSuffix;
+ linkUrl = docName + docLinkSuffix;
+ }
+ let linkEl = listItem.appendChild(document.createElement("a"));
+ linkEl.href = linkUrl + anchor;
+ linkEl.dataset.score = score;
+ linkEl.innerHTML = title;
+ if (descr) {
+ listItem.appendChild(document.createElement("span")).innerHTML =
+ " (" + descr + ")";
+ // highlight search terms in the description
+ if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js
+ highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted"));
+ }
+ else if (showSearchSummary)
+ fetch(requestUrl)
+ .then((responseData) => responseData.text())
+ .then((data) => {
+ if (data)
+ listItem.appendChild(
+ Search.makeSearchSummary(data, searchTerms, anchor)
+ );
+ // highlight search terms in the summary
+ if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js
+ highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted"));
+ });
+ Search.output.appendChild(listItem);
+};
+const _finishSearch = (resultCount) => {
+ Search.stopPulse();
+ Search.title.innerText = _("Search Results");
+ if (!resultCount)
+ Search.status.innerText = Documentation.gettext(
+ "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories."
+ );
+ else
+ Search.status.innerText = Documentation.ngettext(
+ "Search finished, found one page matching the search query.",
+ "Search finished, found ${resultCount} pages matching the search query.",
+ resultCount,
+ ).replace('${resultCount}', resultCount);
+};
+const _displayNextItem = (
+ results,
+ resultCount,
+ searchTerms,
+ highlightTerms,
+) => {
+ // results left, load the summary and display it
+ // this is intended to be dynamic (don't sub resultsCount)
+ if (results.length) {
+ _displayItem(results.pop(), searchTerms, highlightTerms);
+ setTimeout(
+ () => _displayNextItem(results, resultCount, searchTerms, highlightTerms),
+ 5
+ );
+ }
+ // search finished, update title and status message
+ else _finishSearch(resultCount);
+};
+// Helper function used by query() to order search results.
+// Each input is an array of [docname, title, anchor, descr, score, filename, kind].
+// Order the results by score (in opposite order of appearance, since the
+// `_displayNextItem` function uses pop() to retrieve items) and then alphabetically.
+const _orderResultsByScoreThenName = (a, b) => {
+ const leftScore = a[4];
+ const rightScore = b[4];
+ if (leftScore === rightScore) {
+ // same score: sort alphabetically
+ const leftTitle = a[1].toLowerCase();
+ const rightTitle = b[1].toLowerCase();
+ if (leftTitle === rightTitle) return 0;
+ return leftTitle > rightTitle ? -1 : 1; // inverted is intentional
+ }
+ return leftScore > rightScore ? 1 : -1;
+};
+
+/**
+ * Default splitQuery function. Can be overridden in ``sphinx.search`` with a
+ * custom function per language.
+ *
+ * The regular expression works by splitting the string on consecutive characters
+ * that are not Unicode letters, numbers, underscores, or emoji characters.
+ * This is the same as ``\W+`` in Python, preserving the surrogate pair area.
+ */
+if (typeof splitQuery === "undefined") {
+ var splitQuery = (query) => query
+ .split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu)
+ .filter(term => term) // remove remaining empty strings
+}
+
+/**
+ * Search Module
+ */
+const Search = {
+ _index: null,
+ _queued_query: null,
+ _pulse_status: -1,
+
+ htmlToText: (htmlString, anchor) => {
+ const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html');
+ for (const removalQuery of [".headerlink", "script", "style"]) {
+ htmlElement.querySelectorAll(removalQuery).forEach((el) => { el.remove() });
+ }
+ if (anchor) {
+ const anchorContent = htmlElement.querySelector(`[role="main"] ${anchor}`);
+ if (anchorContent) return anchorContent.textContent;
+
+ console.warn(
+ `Anchored content block not found. Sphinx search tries to obtain it via DOM query '[role=main] ${anchor}'. Check your theme or template.`
+ );
+ }
+
+ // if anchor not specified or not found, fall back to main content
+ const docContent = htmlElement.querySelector('[role="main"]');
+ if (docContent) return docContent.textContent;
+
+ console.warn(
+ "Content block not found. Sphinx search tries to obtain it via DOM query '[role=main]'. Check your theme or template."
+ );
+ return "";
+ },
+
+ init: () => {
+ const query = new URLSearchParams(window.location.search).get("q");
+ document
+ .querySelectorAll('input[name="q"]')
+ .forEach((el) => (el.value = query));
+ if (query) Search.performSearch(query);
+ },
+
+ loadIndex: (url) =>
+ (document.body.appendChild(document.createElement("script")).src = url),
+
+ setIndex: (index) => {
+ Search._index = index;
+ if (Search._queued_query !== null) {
+ const query = Search._queued_query;
+ Search._queued_query = null;
+ Search.query(query);
+ }
+ },
+
+ hasIndex: () => Search._index !== null,
+
+ deferQuery: (query) => (Search._queued_query = query),
+
+ stopPulse: () => (Search._pulse_status = -1),
+
+ startPulse: () => {
+ if (Search._pulse_status >= 0) return;
+
+ const pulse = () => {
+ Search._pulse_status = (Search._pulse_status + 1) % 4;
+ Search.dots.innerText = ".".repeat(Search._pulse_status);
+ if (Search._pulse_status >= 0) window.setTimeout(pulse, 500);
+ };
+ pulse();
+ },
+
+ /**
+ * perform a search for something (or wait until index is loaded)
+ */
+ performSearch: (query) => {
+ // create the required interface elements
+ const searchText = document.createElement("h2");
+ searchText.textContent = _("Searching");
+ const searchSummary = document.createElement("p");
+ searchSummary.classList.add("search-summary");
+ searchSummary.innerText = "";
+ const searchList = document.createElement("ul");
+ searchList.setAttribute("role", "list");
+ searchList.classList.add("search");
+
+ const out = document.getElementById("search-results");
+ Search.title = out.appendChild(searchText);
+ Search.dots = Search.title.appendChild(document.createElement("span"));
+ Search.status = out.appendChild(searchSummary);
+ Search.output = out.appendChild(searchList);
+
+ const searchProgress = document.getElementById("search-progress");
+ // Some themes don't use the search progress node
+ if (searchProgress) {
+ searchProgress.innerText = _("Preparing search...");
+ }
+ Search.startPulse();
+
+ // index already loaded, the browser was quick!
+ if (Search.hasIndex()) Search.query(query);
+ else Search.deferQuery(query);
+ },
+
+ _parseQuery: (query) => {
+ // stem the search terms and add them to the correct list
+ const stemmer = new Stemmer();
+ const searchTerms = new Set();
+ const excludedTerms = new Set();
+ const highlightTerms = new Set();
+ const objectTerms = new Set(splitQuery(query.toLowerCase().trim()));
+ splitQuery(query.trim()).forEach((queryTerm) => {
+ const queryTermLower = queryTerm.toLowerCase();
+
+ // maybe skip this "word"
+ // stopwords array is from language_data.js
+ if (
+ stopwords.indexOf(queryTermLower) !== -1 ||
+ queryTerm.match(/^\d+$/)
+ )
+ return;
+
+ // stem the word
+ let word = stemmer.stemWord(queryTermLower);
+ // select the correct list
+ if (word[0] === "-") excludedTerms.add(word.substr(1));
+ else {
+ searchTerms.add(word);
+ highlightTerms.add(queryTermLower);
+ }
+ });
+
+ if (SPHINX_HIGHLIGHT_ENABLED) { // set in sphinx_highlight.js
+ localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" "))
+ }
+
+ // console.debug("SEARCH: searching for:");
+ // console.info("required: ", [...searchTerms]);
+ // console.info("excluded: ", [...excludedTerms]);
+
+ return [query, searchTerms, excludedTerms, highlightTerms, objectTerms];
+ },
+
+ /**
+ * execute search (requires search index to be loaded)
+ */
+ _performSearch: (query, searchTerms, excludedTerms, highlightTerms, objectTerms) => {
+ const filenames = Search._index.filenames;
+ const docNames = Search._index.docnames;
+ const titles = Search._index.titles;
+ const allTitles = Search._index.alltitles;
+ const indexEntries = Search._index.indexentries;
+
+ // Collect multiple result groups to be sorted separately and then ordered.
+ // Each is an array of [docname, title, anchor, descr, score, filename, kind].
+ const normalResults = [];
+ const nonMainIndexResults = [];
+
+ _removeChildren(document.getElementById("search-progress"));
+
+ const queryLower = query.toLowerCase().trim();
+ for (const [title, foundTitles] of Object.entries(allTitles)) {
+ if (title.toLowerCase().trim().includes(queryLower) && (queryLower.length >= title.length/2)) {
+ for (const [file, id] of foundTitles) {
+ const score = Math.round(Scorer.title * queryLower.length / title.length);
+ const boost = titles[file] === title ? 1 : 0; // add a boost for document titles
+ normalResults.push([
+ docNames[file],
+ titles[file] !== title ? `${titles[file]} > ${title}` : title,
+ id !== null ? "#" + id : "",
+ null,
+ score + boost,
+ filenames[file],
+ SearchResultKind.title,
+ ]);
+ }
+ }
+ }
+
+ // search for explicit entries in index directives
+ for (const [entry, foundEntries] of Object.entries(indexEntries)) {
+ if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) {
+ for (const [file, id, isMain] of foundEntries) {
+ const score = Math.round(100 * queryLower.length / entry.length);
+ const result = [
+ docNames[file],
+ titles[file],
+ id ? "#" + id : "",
+ null,
+ score,
+ filenames[file],
+ SearchResultKind.index,
+ ];
+ if (isMain) {
+ normalResults.push(result);
+ } else {
+ nonMainIndexResults.push(result);
+ }
+ }
+ }
+ }
+
+ // lookup as object
+ objectTerms.forEach((term) =>
+ normalResults.push(...Search.performObjectSearch(term, objectTerms))
+ );
+
+ // lookup as search terms in fulltext
+ normalResults.push(...Search.performTermsSearch(searchTerms, excludedTerms));
+
+ // let the scorer override scores with a custom scoring function
+ if (Scorer.score) {
+ normalResults.forEach((item) => (item[4] = Scorer.score(item)));
+ nonMainIndexResults.forEach((item) => (item[4] = Scorer.score(item)));
+ }
+
+ // Sort each group of results by score and then alphabetically by name.
+ normalResults.sort(_orderResultsByScoreThenName);
+ nonMainIndexResults.sort(_orderResultsByScoreThenName);
+
+ // Combine the result groups in (reverse) order.
+ // Non-main index entries are typically arbitrary cross-references,
+ // so display them after other results.
+ let results = [...nonMainIndexResults, ...normalResults];
+
+ // remove duplicate search results
+ // note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept
+ let seen = new Set();
+ results = results.reverse().reduce((acc, result) => {
+ let resultStr = result.slice(0, 4).concat([result[5]]).map(v => String(v)).join(',');
+ if (!seen.has(resultStr)) {
+ acc.push(result);
+ seen.add(resultStr);
+ }
+ return acc;
+ }, []);
+
+ return results.reverse();
+ },
+
+ query: (query) => {
+ const [searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms] = Search._parseQuery(query);
+ const results = Search._performSearch(searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms);
+
+ // for debugging
+ //Search.lastresults = results.slice(); // a copy
+ // console.info("search results:", Search.lastresults);
+
+ // print the results
+ _displayNextItem(results, results.length, searchTerms, highlightTerms);
+ },
+
+ /**
+ * search for object names
+ */
+ performObjectSearch: (object, objectTerms) => {
+ const filenames = Search._index.filenames;
+ const docNames = Search._index.docnames;
+ const objects = Search._index.objects;
+ const objNames = Search._index.objnames;
+ const titles = Search._index.titles;
+
+ const results = [];
+
+ const objectSearchCallback = (prefix, match) => {
+ const name = match[4]
+ const fullname = (prefix ? prefix + "." : "") + name;
+ const fullnameLower = fullname.toLowerCase();
+ if (fullnameLower.indexOf(object) < 0) return;
+
+ let score = 0;
+ const parts = fullnameLower.split(".");
+
+ // check for different match types: exact matches of full name or
+ // "last name" (i.e. last dotted part)
+ if (fullnameLower === object || parts.slice(-1)[0] === object)
+ score += Scorer.objNameMatch;
+ else if (parts.slice(-1)[0].indexOf(object) > -1)
+ score += Scorer.objPartialMatch; // matches in last name
+
+ const objName = objNames[match[1]][2];
+ const title = titles[match[0]];
+
+ // If more than one term searched for, we require other words to be
+ // found in the name/title/description
+ const otherTerms = new Set(objectTerms);
+ otherTerms.delete(object);
+ if (otherTerms.size > 0) {
+ const haystack = `${prefix} ${name} ${objName} ${title}`.toLowerCase();
+ if (
+ [...otherTerms].some((otherTerm) => haystack.indexOf(otherTerm) < 0)
+ )
+ return;
+ }
+
+ let anchor = match[3];
+ if (anchor === "") anchor = fullname;
+ else if (anchor === "-") anchor = objNames[match[1]][1] + "-" + fullname;
+
+ const descr = objName + _(", in ") + title;
+
+ // add custom score for some objects according to scorer
+ if (Scorer.objPrio.hasOwnProperty(match[2]))
+ score += Scorer.objPrio[match[2]];
+ else score += Scorer.objPrioDefault;
+
+ results.push([
+ docNames[match[0]],
+ fullname,
+ "#" + anchor,
+ descr,
+ score,
+ filenames[match[0]],
+ SearchResultKind.object,
+ ]);
+ };
+ Object.keys(objects).forEach((prefix) =>
+ objects[prefix].forEach((array) =>
+ objectSearchCallback(prefix, array)
+ )
+ );
+ return results;
+ },
+
+ /**
+ * search for full-text terms in the index
+ */
+ performTermsSearch: (searchTerms, excludedTerms) => {
+ // prepare search
+ const terms = Search._index.terms;
+ const titleTerms = Search._index.titleterms;
+ const filenames = Search._index.filenames;
+ const docNames = Search._index.docnames;
+ const titles = Search._index.titles;
+
+ const scoreMap = new Map();
+ const fileMap = new Map();
+
+ // perform the search on the required terms
+ searchTerms.forEach((word) => {
+ const files = [];
+ // find documents, if any, containing the query word in their text/title term indices
+ // use Object.hasOwnProperty to avoid mismatching against prototype properties
+ const arr = [
+ { files: terms.hasOwnProperty(word) ? terms[word] : undefined, score: Scorer.term },
+ { files: titleTerms.hasOwnProperty(word) ? titleTerms[word] : undefined, score: Scorer.title },
+ ];
+ // add support for partial matches
+ if (word.length > 2) {
+ const escapedWord = _escapeRegExp(word);
+ if (!terms.hasOwnProperty(word)) {
+ Object.keys(terms).forEach((term) => {
+ if (term.match(escapedWord))
+ arr.push({ files: terms[term], score: Scorer.partialTerm });
+ });
+ }
+ if (!titleTerms.hasOwnProperty(word)) {
+ Object.keys(titleTerms).forEach((term) => {
+ if (term.match(escapedWord))
+ arr.push({ files: titleTerms[term], score: Scorer.partialTitle });
+ });
+ }
+ }
+
+ // no match but word was a required one
+ if (arr.every((record) => record.files === undefined)) return;
+
+ // found search word in contents
+ arr.forEach((record) => {
+ if (record.files === undefined) return;
+
+ let recordFiles = record.files;
+ if (recordFiles.length === undefined) recordFiles = [recordFiles];
+ files.push(...recordFiles);
+
+ // set score for the word in each file
+ recordFiles.forEach((file) => {
+ if (!scoreMap.has(file)) scoreMap.set(file, new Map());
+ const fileScores = scoreMap.get(file);
+ fileScores.set(word, record.score);
+ });
+ });
+
+ // create the mapping
+ files.forEach((file) => {
+ if (!fileMap.has(file)) fileMap.set(file, [word]);
+ else if (fileMap.get(file).indexOf(word) === -1) fileMap.get(file).push(word);
+ });
+ });
+
+ // now check if the files don't contain excluded terms
+ const results = [];
+ for (const [file, wordList] of fileMap) {
+ // check if all requirements are matched
+
+ // as search terms with length < 3 are discarded
+ const filteredTermCount = [...searchTerms].filter(
+ (term) => term.length > 2
+ ).length;
+ if (
+ wordList.length !== searchTerms.size &&
+ wordList.length !== filteredTermCount
+ )
+ continue;
+
+ // ensure that none of the excluded terms is in the search result
+ if (
+ [...excludedTerms].some(
+ (term) =>
+ terms[term] === file ||
+ titleTerms[term] === file ||
+ (terms[term] || []).includes(file) ||
+ (titleTerms[term] || []).includes(file)
+ )
+ )
+ break;
+
+ // select one (max) score for the file.
+ const score = Math.max(...wordList.map((w) => scoreMap.get(file).get(w)));
+ // add result to the result list
+ results.push([
+ docNames[file],
+ titles[file],
+ "",
+ null,
+ score,
+ filenames[file],
+ SearchResultKind.text,
+ ]);
+ }
+ return results;
+ },
+
+ /**
+ * helper function to return a node containing the
+ * search summary for a given text. keywords is a list
+ * of stemmed words.
+ */
+ makeSearchSummary: (htmlText, keywords, anchor) => {
+ const text = Search.htmlToText(htmlText, anchor);
+ if (text === "") return null;
+
+ const textLower = text.toLowerCase();
+ const actualStartPosition = [...keywords]
+ .map((k) => textLower.indexOf(k.toLowerCase()))
+ .filter((i) => i > -1)
+ .slice(-1)[0];
+ const startWithContext = Math.max(actualStartPosition - 120, 0);
+
+ const top = startWithContext === 0 ? "" : "...";
+ const tail = startWithContext + 240 < text.length ? "..." : "";
+
+ let summary = document.createElement("p");
+ summary.classList.add("context");
+ summary.textContent = top + text.substr(startWithContext, 240).trim() + tail;
+
+ return summary;
+ },
+};
+
+_ready(Search.init);
diff --git a/docs/docs/_static/sphinx_highlight.js b/docs/docs/_static/sphinx_highlight.js
new file mode 100644
index 0000000..8a96c69
--- /dev/null
+++ b/docs/docs/_static/sphinx_highlight.js
@@ -0,0 +1,154 @@
+/* Highlighting utilities for Sphinx HTML documentation. */
+"use strict";
+
+const SPHINX_HIGHLIGHT_ENABLED = true
+
+/**
+ * highlight a given string on a node by wrapping it in
+ * span elements with the given class name.
+ */
+const _highlight = (node, addItems, text, className) => {
+ if (node.nodeType === Node.TEXT_NODE) {
+ const val = node.nodeValue;
+ const parent = node.parentNode;
+ const pos = val.toLowerCase().indexOf(text);
+ if (
+ pos >= 0 &&
+ !parent.classList.contains(className) &&
+ !parent.classList.contains("nohighlight")
+ ) {
+ let span;
+
+ const closestNode = parent.closest("body, svg, foreignObject");
+ const isInSVG = closestNode && closestNode.matches("svg");
+ if (isInSVG) {
+ span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
+ } else {
+ span = document.createElement("span");
+ span.classList.add(className);
+ }
+
+ span.appendChild(document.createTextNode(val.substr(pos, text.length)));
+ const rest = document.createTextNode(val.substr(pos + text.length));
+ parent.insertBefore(
+ span,
+ parent.insertBefore(
+ rest,
+ node.nextSibling
+ )
+ );
+ node.nodeValue = val.substr(0, pos);
+ /* There may be more occurrences of search term in this node. So call this
+ * function recursively on the remaining fragment.
+ */
+ _highlight(rest, addItems, text, className);
+
+ if (isInSVG) {
+ const rect = document.createElementNS(
+ "http://www.w3.org/2000/svg",
+ "rect"
+ );
+ const bbox = parent.getBBox();
+ rect.x.baseVal.value = bbox.x;
+ rect.y.baseVal.value = bbox.y;
+ rect.width.baseVal.value = bbox.width;
+ rect.height.baseVal.value = bbox.height;
+ rect.setAttribute("class", className);
+ addItems.push({ parent: parent, target: rect });
+ }
+ }
+ } else if (node.matches && !node.matches("button, select, textarea")) {
+ node.childNodes.forEach((el) => _highlight(el, addItems, text, className));
+ }
+};
+const _highlightText = (thisNode, text, className) => {
+ let addItems = [];
+ _highlight(thisNode, addItems, text, className);
+ addItems.forEach((obj) =>
+ obj.parent.insertAdjacentElement("beforebegin", obj.target)
+ );
+};
+
+/**
+ * Small JavaScript module for the documentation.
+ */
+const SphinxHighlight = {
+
+ /**
+ * highlight the search words provided in localstorage in the text
+ */
+ highlightSearchWords: () => {
+ if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight
+
+ // get and clear terms from localstorage
+ const url = new URL(window.location);
+ const highlight =
+ localStorage.getItem("sphinx_highlight_terms")
+ || url.searchParams.get("highlight")
+ || "";
+ localStorage.removeItem("sphinx_highlight_terms")
+ url.searchParams.delete("highlight");
+ window.history.replaceState({}, "", url);
+
+ // get individual terms from highlight string
+ const terms = highlight.toLowerCase().split(/\s+/).filter(x => x);
+ if (terms.length === 0) return; // nothing to do
+
+ // There should never be more than one element matching "div.body"
+ const divBody = document.querySelectorAll("div.body");
+ const body = divBody.length ? divBody[0] : document.querySelector("body");
+ window.setTimeout(() => {
+ terms.forEach((term) => _highlightText(body, term, "highlighted"));
+ }, 10);
+
+ const searchBox = document.getElementById("searchbox");
+ if (searchBox === null) return;
+ searchBox.appendChild(
+ document
+ .createRange()
+ .createContextualFragment(
+ '<p class="highlight-link">' +
+ '<a href="javascript:SphinxHighlight.hideSearchWords()">' +
+ _("Hide Search Matches") +
+ "</a></p>"
+ )
+ );
+ },
+
+ /**
+ * helper function to hide the search marks again
+ */
+ hideSearchWords: () => {
+ document
+ .querySelectorAll("#searchbox .highlight-link")
+ .forEach((el) => el.remove());
+ document
+ .querySelectorAll("span.highlighted")
+ .forEach((el) => el.classList.remove("highlighted"));
+ localStorage.removeItem("sphinx_highlight_terms")
+ },
+
+ initEscapeListener: () => {
+ // only install a listener if it is really needed
+ if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return;
+
+ document.addEventListener("keydown", (event) => {
+ // bail for input elements
+ if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return;
+ // bail with special keys
+ if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return;
+ if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) {
+ SphinxHighlight.hideSearchWords();
+ event.preventDefault();
+ }
+ });
+ },
+};
+
+_ready(() => {
+ /* Do not call highlightSearchWords() when we are on the search page.
+ * It will highlight words from the *previous* search query.
+ */
+ if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords();
+ SphinxHighlight.initEscapeListener();
+});
diff --git a/docs/docs/explanation/architecture.html b/docs/docs/explanation/architecture.html
new file mode 100644
index 0000000..f62eaf4
--- /dev/null
+++ b/docs/docs/explanation/architecture.html
@@ -0,0 +1,207 @@
+<!DOCTYPE html>
+
+<html lang="en" data-content_root="../">
+ <head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
+
+ <title>Architecture and design — MicroPie 0.20 documentation</title>
+ <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d1102ebc" />
+ <link rel="stylesheet" type="text/css" href="../_static/basic.css?v=b08954a9" />
+ <link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=f6a572b4" />
+ <script src="../_static/documentation_options.js?v=0144e382"></script>
+ <script src="../_static/doctools.js?v=9bcbadda"></script>
+ <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Glossary" href="../glossary.html" />
+ <link rel="prev" title="Explanations" href="index.html" />
+
+ <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
+
+
+
+
+ </head><body>
+ <div class="document">
+
+ <div class="sphinxsidebar" role="navigation" aria-label="Main">
+ <div class="sphinxsidebarwrapper">
+<h1 class="logo"><a href="../index.html">MicroPie</a></h1>
+
+
+
+<p class="blurb">A minimal ASGI web framework</p>
+
+
+
+
+<p>
+<iframe src="https://ghbtns.com/github-btn.html?user=patx&repo=micropie&type=watch&count=true&size=large&v=2"
+ allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
+</p>
+
+
+
+
+
+
+<search id="searchbox" style="display: none" role="search">
+ <div class="searchformwrapper">
+ <form class="search" action="../search.html" method="get">
+ <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" placeholder="Search"/>
+ <input type="submit" value="Go" />
+ </form>
+ </div>
+</search>
+<script>document.getElementById('searchbox').style.display = "block"</script><h3>Navigation</h3>
+<p class="caption" role="heading"><span class="caption-text">Documentation</span></p>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Tutorials</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../howto/index.html">How‑to guides</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../reference/index.html">API reference</a></li>
+<li class="toctree-l1 current"><a class="reference internal" href="index.html">Explanations</a><ul class="current">
+<li class="toctree-l2 current"><a class="current reference internal" href="#">Architecture and design</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
+</ul>
+
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="../index.html">Documentation overview</a><ul>
+ <li><a href="index.html">Explanations</a><ul>
+ <li>Previous: <a href="index.html" title="previous chapter">Explanations</a></li>
+ <li>Next: <a href="../glossary.html" title="next chapter">Glossary</a></li>
+ </ul></li>
+ </ul></li>
+</ul>
+</div>
+
+
+
+
+
+
+
+
+ </div>
+ </div>
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+
+
+ <div class="body" role="main">
+
+ <section id="architecture-and-design">
+<h1>Architecture and design<a class="headerlink" href="#architecture-and-design" title="Link to this heading">¶</a></h1>
+<p>MicroPie is intentionally small. Its goal is to provide just enough
+functionality to build asynchronous web applications without locking
+you into a rigid structure. This section discusses some of the key
+design choices and how they influence the API.</p>
+<section id="asgi-application">
+<h2>ASGI application<a class="headerlink" href="#asgi-application" title="Link to this heading">¶</a></h2>
+<p>MicroPie is built on top of the <a class="reference external" href="https://asgi.readthedocs.io/">ASGI</a> specification, which defines
+how Python applications communicate with asynchronous servers. Your
+application subclass inherits from <code class="xref py py-class docutils literal notranslate"><span class="pre">App</span></code> and
+implements the ASGI call interface via the <code class="docutils literal notranslate"><span class="pre">__call__</span></code> method. The
+framework inspects the <code class="docutils literal notranslate"><span class="pre">scope['type']</span></code> field to dispatch to HTTP,
+WebSocket or lifespan handling code.</p>
+</section>
+<section id="routing-by-naming">
+<h2>Routing by naming<a class="headerlink" href="#routing-by-naming" title="Link to this heading">¶</a></h2>
+<p>Unlike frameworks that require you to declare routes in advance,
+MicroPie derives routing information from the names of your methods.
+The first segment of the path becomes the handler name. This allows
+you to add new endpoints simply by defining a new method on your
+application subclass. The remaining path segments, query string
+parameters and form data are mapped to arguments via function
+signature inspection. This approach reduces boilerplate but may
+surprise users expecting explicit routing. You can always regain
+control by writing a custom middleware to map paths to handlers or by
+checking <code class="docutils literal notranslate"><span class="pre">self.request.method</span></code> and <code class="docutils literal notranslate"><span class="pre">self.request.path_params</span></code> inside
+your handlers.</p>
+</section>
+<section id="contextlocal-request">
+<h2>Context‑local request<a class="headerlink" href="#contextlocal-request" title="Link to this heading">¶</a></h2>
+<p>MicroPie stores the current request in a <code class="xref py py-mod docutils literal notranslate"><span class="pre">contextvars</span></code>
+ContextVar. This allows you to access <code class="docutils literal notranslate"><span class="pre">self.request</span></code> within your
+handler as well as from deeper helper functions without passing the
+request around explicitly. The context variable is reset at the end
+of each request to avoid leaking state.</p>
+</section>
+<section id="session-management">
+<h2>Session management<a class="headerlink" href="#session-management" title="Link to this heading">¶</a></h2>
+<p>Sessions are stored in a pluggable back‑end and identified by a
+random <code class="docutils literal notranslate"><span class="pre">session_id</span></code> cookie. The default in‑memory back‑end keeps
+session data in dictionaries keyed by session ID and updates a last
+access timestamp to implement expiration. You can customise the
+back‑end by providing your own implementation of
+<code class="xref py py-class docutils literal notranslate"><span class="pre">SessionBackend</span></code>. MicroPie saves sessions after a
+handler returns, only if <code class="docutils literal notranslate"><span class="pre">self.request.session</span></code> is non‑empty, to
+avoid creating unnecessary cookies.</p>
+</section>
+<section id="middleware-pipeline">
+<h2>Middleware pipeline<a class="headerlink" href="#middleware-pipeline" title="Link to this heading">¶</a></h2>
+<p>The middleware hooks allow you to intercept requests before and after
+handlers. Middleware can modify the request object, provide early
+responses (useful for authentication), and alter the final response.
+For WebSockets, separate middleware hooks run before the connection
+handler starts and after it finishes.</p>
+</section>
+<section id="streaming-and-sse-support">
+<h2>Streaming and SSE support<a class="headerlink" href="#streaming-and-sse-support" title="Link to this heading">¶</a></h2>
+<p>Handlers may return an iterator or asynchronous generator to stream
+data to the client. MicroPie detects such responses and iterates
+over them, sending each chunk to the client. When using server‑sent
+events (SSE) there is an additional challenge: if the client
+disconnects, the iterator must be cancelled. MicroPie wraps SSE
+responses in a small loop that listens for disconnect events and
+cancels the generator accordingly. Remember to include a
+<code class="docutils literal notranslate"><span class="pre">Content‑Type:</span> <span class="pre">text/event-stream</span></code> header when sending SSE.</p>
+</section>
+<section id="error-handling">
+<h2>Error handling<a class="headerlink" href="#error-handling" title="Link to this heading">¶</a></h2>
+<p>MicroPie automatically handles common error cases. Requests for
+unknown routes result in a <code class="docutils literal notranslate"><span class="pre">404</span> <span class="pre">Not</span> <span class="pre">Found</span></code>. If a required
+parameter is missing, MicroPie responds with <code class="docutils literal notranslate"><span class="pre">400</span> <span class="pre">Bad</span> <span class="pre">Request</span></code>.
+Unhandled exceptions inside handlers produce a <code class="docutils literal notranslate"><span class="pre">500</span> <span class="pre">Internal</span> <span class="pre">Server</span>
+<span class="pre">Error</span></code> and are printed to standard error. You can override these
+behaviours via middleware.</p>
+</section>
+<section id="extensibility">
+<h2>Extensibility<a class="headerlink" href="#extensibility" title="Link to this heading">¶</a></h2>
+<p>The minimalist core is designed to be extended. You can mount your
+application behind other ASGI middleware, integrate additional
+protocols like Socket.IO, or implement your own session storage. The
+framework imposes few constraints so that you remain in control of
+your stack.</p>
+</section>
+</section>
+
+
+ </div>
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="footer">
+ ©.
+
+ |
+ Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.2.3</a>
+ & <a href="https://alabaster.readthedocs.io">Alabaster 1.0.0</a>
+
+ |
+ <a href="../_sources/explanation/architecture.rst.txt"
+ rel="nofollow">Page source</a>
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file
diff --git a/docs/docs/explanation/index.html b/docs/docs/explanation/index.html
new file mode 100644
index 0000000..d33df67
--- /dev/null
+++ b/docs/docs/explanation/index.html
@@ -0,0 +1,133 @@
+<!DOCTYPE html>
+
+<html lang="en" data-content_root="../">
+ <head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
+
+ <title>Explanations — MicroPie 0.20 documentation</title>
+ <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d1102ebc" />
+ <link rel="stylesheet" type="text/css" href="../_static/basic.css?v=b08954a9" />
+ <link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=f6a572b4" />
+ <script src="../_static/documentation_options.js?v=0144e382"></script>
+ <script src="../_static/doctools.js?v=9bcbadda"></script>
+ <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Architecture and design" href="architecture.html" />
+ <link rel="prev" title="Exceptions" href="../reference/exceptions.html" />
+
+ <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
+
+
+
+
+ </head><body>
+ <div class="document">
+
+ <div class="sphinxsidebar" role="navigation" aria-label="Main">
+ <div class="sphinxsidebarwrapper">
+<h1 class="logo"><a href="../index.html">MicroPie</a></h1>
+
+
+
+<p class="blurb">A minimal ASGI web framework</p>
+
+
+
+
+<p>
+<iframe src="https://ghbtns.com/github-btn.html?user=patx&repo=micropie&type=watch&count=true&size=large&v=2"
+ allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
+</p>
+
+
+
+
+
+
+<search id="searchbox" style="display: none" role="search">
+ <div class="searchformwrapper">
+ <form class="search" action="../search.html" method="get">
+ <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" placeholder="Search"/>
+ <input type="submit" value="Go" />
+ </form>
+ </div>
+</search>
+<script>document.getElementById('searchbox').style.display = "block"</script><h3>Navigation</h3>
+<p class="caption" role="heading"><span class="caption-text">Documentation</span></p>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Tutorials</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../howto/index.html">How‑to guides</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../reference/index.html">API reference</a></li>
+<li class="toctree-l1 current"><a class="current reference internal" href="#">Explanations</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="architecture.html">Architecture and design</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
+</ul>
+
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="../index.html">Documentation overview</a><ul>
+ <li>Previous: <a href="../reference/exceptions.html" title="previous chapter">Exceptions</a></li>
+ <li>Next: <a href="architecture.html" title="next chapter">Architecture and design</a></li>
+ </ul></li>
+</ul>
+</div>
+
+
+
+
+
+
+
+
+ </div>
+ </div>
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+
+
+ <div class="body" role="main">
+
+ <section id="explanations">
+<h1>Explanations<a class="headerlink" href="#explanations" title="Link to this heading">¶</a></h1>
+<p>The explanation section explores concepts and design decisions behind
+MicroPie. It answers “why” questions and provides deeper context.
+For hands‑on instructions see the tutorials and how‑to guides; for
+precise definitions consult the reference.</p>
+<div class="toctree-wrapper compound">
+<p class="caption" role="heading"><span class="caption-text">Explanations</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="architecture.html">Architecture and design</a></li>
+</ul>
+</div>
+</section>
+
+
+ </div>
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="footer">
+ ©.
+
+ |
+ Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.2.3</a>
+ & <a href="https://alabaster.readthedocs.io">Alabaster 1.0.0</a>
+
+ |
+ <a href="../_sources/explanation/index.rst.txt"
+ rel="nofollow">Page source</a>
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file
diff --git a/docs/docs/genindex.html b/docs/docs/genindex.html
new file mode 100644
index 0000000..ec4c28f
--- /dev/null
+++ b/docs/docs/genindex.html
@@ -0,0 +1,346 @@
+<!DOCTYPE html>
+
+<html lang="en" data-content_root="./">
+ <head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Index — MicroPie 0.20 documentation</title>
+ <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d1102ebc" />
+ <link rel="stylesheet" type="text/css" href="_static/basic.css?v=b08954a9" />
+ <link rel="stylesheet" type="text/css" href="_static/alabaster.css?v=f6a572b4" />
+ <script src="_static/documentation_options.js?v=0144e382"></script>
+ <script src="_static/doctools.js?v=9bcbadda"></script>
+ <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+ <link rel="index" title="Index" href="#" />
+ <link rel="search" title="Search" href="search.html" />
+
+ <link rel="stylesheet" href="_static/custom.css" type="text/css" />
+
+
+
+
+
+ </head><body>
+ <div class="document">
+
+ <div class="sphinxsidebar" role="navigation" aria-label="Main">
+ <div class="sphinxsidebarwrapper">
+<h1 class="logo"><a href="index.html">MicroPie</a></h1>
+
+
+
+<p class="blurb">A minimal ASGI web framework</p>
+
+
+
+
+<p>
+<iframe src="https://ghbtns.com/github-btn.html?user=patx&repo=micropie&type=watch&count=true&size=large&v=2"
+ allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
+</p>
+
+
+
+
+
+
+<search id="searchbox" style="display: none" role="search">
+ <div class="searchformwrapper">
+ <form class="search" action="search.html" method="get">
+ <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" placeholder="Search"/>
+ <input type="submit" value="Go" />
+ </form>
+ </div>
+</search>
+<script>document.getElementById('searchbox').style.display = "block"</script><h3>Navigation</h3>
+<p class="caption" role="heading"><span class="caption-text">Documentation</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="tutorial/index.html">Tutorials</a></li>
+<li class="toctree-l1"><a class="reference internal" href="howto/index.html">How‑to guides</a></li>
+<li class="toctree-l1"><a class="reference internal" href="reference/index.html">API reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="explanation/index.html">Explanations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="glossary.html">Glossary</a></li>
+</ul>
+
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="index.html">Documentation overview</a><ul>
+ </ul></li>
+</ul>
+</div>
+
+
+
+
+
+
+
+
+ </div>
+ </div>
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+
+
+ <div class="body" role="main">
+
+
+<h1 id="index">Index</h1>
+
+<div class="genindex-jumpbox">
+ <a href="#_"><strong>_</strong></a>
+ | <a href="#A"><strong>A</strong></a>
+ | <a href="#B"><strong>B</strong></a>
+ | <a href="#C"><strong>C</strong></a>
+ | <a href="#F"><strong>F</strong></a>
+ | <a href="#G"><strong>G</strong></a>
+ | <a href="#H"><strong>H</strong></a>
+ | <a href="#I"><strong>I</strong></a>
+ | <a href="#L"><strong>L</strong></a>
+ | <a href="#M"><strong>M</strong></a>
+ | <a href="#P"><strong>P</strong></a>
+ | <a href="#Q"><strong>Q</strong></a>
+ | <a href="#R"><strong>R</strong></a>
+ | <a href="#S"><strong>S</strong></a>
+ | <a href="#W"><strong>W</strong></a>
+
+</div>
+<h2 id="_">_</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/app.html#call__">__call__()</a>
+</li>
+ <li><a href="reference/session.html#InMemorySessionBackend.__init__">__init__() (InMemorySessionBackend method)</a>
+</li>
+ </ul></td>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/app.html#redirect">_redirect()</a>
+</li>
+ <li><a href="reference/app.html#render_template">_render_template()</a>
+</li>
+ </ul></td>
+</tr></table>
+
+<h2 id="A">A</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/websocket.html#accept">accept()</a>
+</li>
+ <li><a href="reference/websocket.html#accepted">accepted</a>
+</li>
+ <li><a href="reference/middleware.html#HttpMiddleware.after_request">after_request() (HttpMiddleware method)</a>
+</li>
+ </ul></td>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/middleware.html#WebSocketMiddleware.after_websocket">after_websocket() (WebSocketMiddleware method)</a>
+</li>
+ <li><a href="reference/app.html#App">App (built-in class)</a>
+</li>
+ <li><a href="glossary.html#term-ASGI"><strong>ASGI</strong></a>
+</li>
+ </ul></td>
+</tr></table>
+
+<h2 id="B">B</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/middleware.html#HttpMiddleware.before_request">before_request() (HttpMiddleware method)</a>
+</li>
+ </ul></td>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/middleware.html#WebSocketMiddleware.before_websocket">before_websocket() (WebSocketMiddleware method)</a>
+</li>
+ <li><a href="reference/request.html#Request.body_params">body_params (Request attribute)</a>
+</li>
+ </ul></td>
+</tr></table>
+
+<h2 id="C">C</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/websocket.html#close">close()</a>
+</li>
+ </ul></td>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/exceptions.html#ConnectionClosed">ConnectionClosed (built-in class)</a>, <a href="reference/websocket.html#ConnectionClosed">[1]</a>
+</li>
+ <li><a href="glossary.html#term-context-variable"><strong>context variable</strong></a>
+</li>
+ </ul></td>
+</tr></table>
+
+<h2 id="F">F</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/request.html#Request.files">files (Request attribute)</a>
+</li>
+ </ul></td>
+</tr></table>
+
+<h2 id="G">G</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/request.html#Request.get_json">get_json (Request attribute)</a>
+</li>
+ </ul></td>
+</tr></table>
+
+<h2 id="H">H</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/request.html#Request.headers">headers (Request attribute)</a>
+</li>
+ </ul></td>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/middleware.html#HttpMiddleware">HttpMiddleware (built-in class)</a>
+</li>
+ </ul></td>
+</tr></table>
+
+<h2 id="I">I</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/session.html#InMemorySessionBackend">InMemorySessionBackend (built-in class)</a>
+</li>
+ </ul></td>
+</tr></table>
+
+<h2 id="L">L</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/session.html#InMemorySessionBackend.load">load() (InMemorySessionBackend method)</a>
+
+ <ul>
+ <li><a href="reference/session.html#SessionBackend.load">(SessionBackend method)</a>
+</li>
+ </ul></li>
+ </ul></td>
+</tr></table>
+
+<h2 id="M">M</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/request.html#Request.method">method (Request attribute)</a>
+</li>
+ </ul></td>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="glossary.html#term-middleware"><strong>middleware</strong></a>
+</li>
+ <li><a href="reference/app.html#middlewares">middlewares</a>
+</li>
+ </ul></td>
+</tr></table>
+
+<h2 id="P">P</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/request.html#Request.path_params">path_params (Request attribute)</a>
+</li>
+ </ul></td>
+</tr></table>
+
+<h2 id="Q">Q</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/request.html#Request.query_params">query_params (Request attribute)</a>
+</li>
+ </ul></td>
+</tr></table>
+
+<h2 id="R">R</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/websocket.html#receive_bytes">receive_bytes()</a>
+</li>
+ <li><a href="reference/websocket.html#receive_text">receive_text()</a>
+</li>
+ </ul></td>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/request.html#Request">Request (built-in class)</a>
+</li>
+ <li><a href="reference/app.html#request">request()</a>
+</li>
+ <li><a href="glossary.html#term-route-handler"><strong>route handler</strong></a>
+</li>
+ </ul></td>
+</tr></table>
+
+<h2 id="S">S</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/session.html#InMemorySessionBackend.save">save() (InMemorySessionBackend method)</a>
+
+ <ul>
+ <li><a href="reference/session.html#SessionBackend.save">(SessionBackend method)</a>
+</li>
+ </ul></li>
+ <li><a href="reference/request.html#Request.scope">scope (Request attribute)</a>
+</li>
+ <li><a href="reference/websocket.html#send_bytes">send_bytes()</a>
+</li>
+ <li><a href="reference/websocket.html#send_text">send_text()</a>
+</li>
+ <li><a href="glossary.html#term-session"><strong>session</strong></a>
+
+ <ul>
+ <li><a href="reference/request.html#Request.session">(Request attribute)</a>
+</li>
+ </ul></li>
+ </ul></td>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/websocket.html#session_id">session_id</a>
+</li>
+ <li><a href="reference/session.html#SESSION_TIMEOUT">SESSION_TIMEOUT (built-in variable)</a>
+</li>
+ <li><a href="reference/session.html#SessionBackend">SessionBackend (built-in class)</a>
+</li>
+ <li><a href="reference/app.html#shutdown_handlers">shutdown_handlers</a>
+</li>
+ <li><a href="reference/app.html#startup_handlers">startup_handlers</a>
+</li>
+ </ul></td>
+</tr></table>
+
+<h2 id="W">W</h2>
+<table style="width: 100%" class="indextable genindextable"><tr>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="glossary.html#term-WebSocket"><strong>WebSocket</strong></a>
+
+ <ul>
+ <li><a href="reference/websocket.html#WebSocket">(built-in class)</a>
+</li>
+ </ul></li>
+ </ul></td>
+ <td style="width: 33%; vertical-align: top;"><ul>
+ <li><a href="reference/middleware.html#WebSocketMiddleware">WebSocketMiddleware (built-in class)</a>
+</li>
+ <li><a href="reference/request.html#WebSocketRequest">WebSocketRequest (built-in class)</a>
+</li>
+ <li><a href="reference/app.html#ws_middlewares">ws_middlewares</a>
+</li>
+ </ul></td>
+</tr></table>
+
+
+
+ </div>
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="footer">
+ ©.
+
+ |
+ Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.2.3</a>
+ & <a href="https://alabaster.readthedocs.io">Alabaster 1.0.0</a>
+
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file
diff --git a/docs/docs/glossary.html b/docs/docs/glossary.html
new file mode 100644
index 0000000..cf50035
--- /dev/null
+++ b/docs/docs/glossary.html
@@ -0,0 +1,153 @@
+<!DOCTYPE html>
+
+<html lang="en" data-content_root="./">
+ <head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
+
+ <title>Glossary — MicroPie 0.20 documentation</title>
+ <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d1102ebc" />
+ <link rel="stylesheet" type="text/css" href="_static/basic.css?v=b08954a9" />
+ <link rel="stylesheet" type="text/css" href="_static/alabaster.css?v=f6a572b4" />
+ <script src="_static/documentation_options.js?v=0144e382"></script>
+ <script src="_static/doctools.js?v=9bcbadda"></script>
+ <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="prev" title="Architecture and design" href="explanation/architecture.html" />
+
+ <link rel="stylesheet" href="_static/custom.css" type="text/css" />
+
+
+
+
+
+ </head><body>
+ <div class="document">
+
+ <div class="sphinxsidebar" role="navigation" aria-label="Main">
+ <div class="sphinxsidebarwrapper">
+<h1 class="logo"><a href="index.html">MicroPie</a></h1>
+
+
+
+<p class="blurb">A minimal ASGI web framework</p>
+
+
+
+
+<p>
+<iframe src="https://ghbtns.com/github-btn.html?user=patx&repo=micropie&type=watch&count=true&size=large&v=2"
+ allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
+</p>
+
+
+
+
+
+
+<search id="searchbox" style="display: none" role="search">
+ <div class="searchformwrapper">
+ <form class="search" action="search.html" method="get">
+ <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" placeholder="Search"/>
+ <input type="submit" value="Go" />
+ </form>
+ </div>
+</search>
+<script>document.getElementById('searchbox').style.display = "block"</script><h3>Navigation</h3>
+<p class="caption" role="heading"><span class="caption-text">Documentation</span></p>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="tutorial/index.html">Tutorials</a></li>
+<li class="toctree-l1"><a class="reference internal" href="howto/index.html">How‑to guides</a></li>
+<li class="toctree-l1"><a class="reference internal" href="reference/index.html">API reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="explanation/index.html">Explanations</a></li>
+<li class="toctree-l1 current"><a class="current reference internal" href="#">Glossary</a></li>
+</ul>
+
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="index.html">Documentation overview</a><ul>
+ <li>Previous: <a href="explanation/architecture.html" title="previous chapter">Architecture and design</a></li>
+ </ul></li>
+</ul>
+</div>
+
+
+
+
+
+
+
+
+ </div>
+ </div>
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+
+
+ <div class="body" role="main">
+
+ <section id="glossary">
+<h1>Glossary<a class="headerlink" href="#glossary" title="Link to this heading">¶</a></h1>
+<p>This glossary defines terms used throughout the MicroPie documentation.</p>
+<dl class="simple glossary">
+<dt id="term-ASGI">ASGI<a class="headerlink" href="#term-ASGI" title="Link to this term">¶</a></dt><dd><p>The Asynchronous Server Gateway Interface. A standard for
+asynchronous communication between Python applications and
+servers. MicroPie applications implement the ASGI call
+interface. See the <a class="reference external" href="https://asgi.readthedocs.io">ASGI specification</a>.</p>
+</dd>
+<dt id="term-route-handler">route handler<a class="headerlink" href="#term-route-handler" title="Link to this term">¶</a></dt><dd><p>A method on your <code class="xref py py-class docutils literal notranslate"><span class="pre">App</span></code> subclass that handles an
+incoming HTTP request. The first segment of the URL path maps to
+the handler name, and remaining segments or query parameters map
+to arguments. Handlers may be synchronous or asynchronous.</p>
+</dd>
+<dt id="term-session">session<a class="headerlink" href="#term-session" title="Link to this term">¶</a></dt><dd><p>A dictionary of data associated with a client across multiple
+requests. MicroPie stores the session in a pluggable back‑end
+and identifies it using a <code class="docutils literal notranslate"><span class="pre">session_id</span></code> cookie. See
+<a class="reference internal" href="howto/sessions.html"><span class="doc">Managing sessions</span></a>.</p>
+</dd>
+<dt id="term-middleware">middleware<a class="headerlink" href="#term-middleware" title="Link to this term">¶</a></dt><dd><p>Code that runs before and/or after a request handler. Middleware
+can short‑circuit requests, modify responses, enforce security
+policies or implement custom routing. MicroPie defines
+<code class="xref py py-class docutils literal notranslate"><span class="pre">HttpMiddleware</span></code> and
+<code class="xref py py-class docutils literal notranslate"><span class="pre">WebSocketMiddleware</span></code> base classes.</p>
+</dd>
+<dt id="term-WebSocket">WebSocket<a class="headerlink" href="#term-WebSocket" title="Link to this term">¶</a></dt><dd><p>A persistent, bidirectional communication channel over TCP. In
+MicroPie, WebSocket handlers are methods prefixed with <code class="docutils literal notranslate"><span class="pre">ws_</span></code>.
+They receive an instance of <code class="xref py py-class docutils literal notranslate"><span class="pre">WebSocket</span></code> and
+optionally additional parameters. See <a class="reference internal" href="tutorial/websockets.html"><span class="doc">WebSocket support</span></a>.</p>
+</dd>
+<dt id="term-context-variable">context variable<a class="headerlink" href="#term-context-variable" title="Link to this term">¶</a></dt><dd><p>An object from the <code class="xref py py-mod docutils literal notranslate"><span class="pre">contextvars</span></code> module that stores data
+local to the current asynchronous context. MicroPie stores the
+current request in a context variable so it is accessible via
+<code class="xref py py-meth docutils literal notranslate"><span class="pre">request()</span></code> without passing it through your
+function calls.</p>
+</dd>
+</dl>
+</section>
+
+
+ </div>
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="footer">
+ ©.
+
+ |
+ Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.2.3</a>
+ & <a href="https://alabaster.readthedocs.io">Alabaster 1.0.0</a>
+
+ |
+ <a href="_sources/glossary.rst.txt"
+ rel="nofollow">Page source</a>
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file
diff --git a/docs/docs/howto/index.html b/docs/docs/howto/index.html
new file mode 100644
index 0000000..311538f
--- /dev/null
+++ b/docs/docs/howto/index.html
@@ -0,0 +1,144 @@
+<!DOCTYPE html>
+
+<html lang="en" data-content_root="../">
+ <head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
+
+ <title>How‑to guides — MicroPie 0.20 documentation</title>
+ <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d1102ebc" />
+ <link rel="stylesheet" type="text/css" href="../_static/basic.css?v=b08954a9" />
+ <link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=f6a572b4" />
+ <script src="../_static/documentation_options.js?v=0144e382"></script>
+ <script src="../_static/doctools.js?v=9bcbadda"></script>
+ <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Managing sessions" href="sessions.html" />
+ <link rel="prev" title="WebSocket support" href="../tutorial/websockets.html" />
+
+ <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
+
+
+
+
+ </head><body>
+ <div class="document">
+
+ <div class="sphinxsidebar" role="navigation" aria-label="Main">
+ <div class="sphinxsidebarwrapper">
+<h1 class="logo"><a href="../index.html">MicroPie</a></h1>
+
+
+
+<p class="blurb">A minimal ASGI web framework</p>
+
+
+
+
+<p>
+<iframe src="https://ghbtns.com/github-btn.html?user=patx&repo=micropie&type=watch&count=true&size=large&v=2"
+ allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
+</p>
+
+
+
+
+
+
+<search id="searchbox" style="display: none" role="search">
+ <div class="searchformwrapper">
+ <form class="search" action="../search.html" method="get">
+ <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" placeholder="Search"/>
+ <input type="submit" value="Go" />
+ </form>
+ </div>
+</search>
+<script>document.getElementById('searchbox').style.display = "block"</script><h3>Navigation</h3>
+<p class="caption" role="heading"><span class="caption-text">Documentation</span></p>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Tutorials</a></li>
+<li class="toctree-l1 current"><a class="current reference internal" href="#">How‑to guides</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="sessions.html">Managing sessions</a></li>
+<li class="toctree-l2"><a class="reference internal" href="middleware.html">Writing middleware</a></li>
+<li class="toctree-l2"><a class="reference internal" href="templates.html">Rendering templates</a></li>
+<li class="toctree-l2"><a class="reference internal" href="streaming.html">Streaming responses</a></li>
+<li class="toctree-l2"><a class="reference internal" href="static_files.html">Serving static files</a></li>
+<li class="toctree-l2"><a class="reference internal" href="socketio.html">Integrating Socket.IO</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="../reference/index.html">API reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../explanation/index.html">Explanations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
+</ul>
+
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="../index.html">Documentation overview</a><ul>
+ <li>Previous: <a href="../tutorial/websockets.html" title="previous chapter">WebSocket support</a></li>
+ <li>Next: <a href="sessions.html" title="next chapter">Managing sessions</a></li>
+ </ul></li>
+</ul>
+</div>
+
+
+
+
+
+
+
+
+ </div>
+ </div>
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+
+
+ <div class="body" role="main">
+
+ <section id="howto-guides">
+<h1>How‑to guides<a class="headerlink" href="#howto-guides" title="Link to this heading">¶</a></h1>
+<p>How‑to guides provide short recipes for solving a specific problem with
+MicroPie. They assume that you already know the basics covered in
+the tutorials. Each guide focuses on performing a single task. See
+the <a class="reference internal" href="../tutorial/index.html"><span class="doc">tutorials</span></a> for a more gentle
+introduction.</p>
+<div class="toctree-wrapper compound">
+<p class="caption" role="heading"><span class="caption-text">Guides</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="sessions.html">Managing sessions</a></li>
+<li class="toctree-l1"><a class="reference internal" href="middleware.html">Writing middleware</a></li>
+<li class="toctree-l1"><a class="reference internal" href="templates.html">Rendering templates</a></li>
+<li class="toctree-l1"><a class="reference internal" href="streaming.html">Streaming responses</a></li>
+<li class="toctree-l1"><a class="reference internal" href="static_files.html">Serving static files</a></li>
+<li class="toctree-l1"><a class="reference internal" href="socketio.html">Integrating Socket.IO</a></li>
+</ul>
+</div>
+</section>
+
+
+ </div>
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="footer">
+ ©.
+
+ |
+ Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.2.3</a>
+ & <a href="https://alabaster.readthedocs.io">Alabaster 1.0.0</a>
+
+ |
+ <a href="../_sources/howto/index.rst.txt"
+ rel="nofollow">Page source</a>
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file
diff --git a/docs/docs/howto/middleware.html b/docs/docs/howto/middleware.html
new file mode 100644
index 0000000..405275d
--- /dev/null
+++ b/docs/docs/howto/middleware.html
@@ -0,0 +1,213 @@
+<!DOCTYPE html>
+
+<html lang="en" data-content_root="../">
+ <head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
+
+ <title>Writing middleware — MicroPie 0.20 documentation</title>
+ <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d1102ebc" />
+ <link rel="stylesheet" type="text/css" href="../_static/basic.css?v=b08954a9" />
+ <link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=f6a572b4" />
+ <script src="../_static/documentation_options.js?v=0144e382"></script>
+ <script src="../_static/doctools.js?v=9bcbadda"></script>
+ <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Rendering templates" href="templates.html" />
+ <link rel="prev" title="Managing sessions" href="sessions.html" />
+
+ <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
+
+
+
+
+ </head><body>
+ <div class="document">
+
+ <div class="sphinxsidebar" role="navigation" aria-label="Main">
+ <div class="sphinxsidebarwrapper">
+<h1 class="logo"><a href="../index.html">MicroPie</a></h1>
+
+
+
+<p class="blurb">A minimal ASGI web framework</p>
+
+
+
+
+<p>
+<iframe src="https://ghbtns.com/github-btn.html?user=patx&repo=micropie&type=watch&count=true&size=large&v=2"
+ allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
+</p>
+
+
+
+
+
+
+<search id="searchbox" style="display: none" role="search">
+ <div class="searchformwrapper">
+ <form class="search" action="../search.html" method="get">
+ <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" placeholder="Search"/>
+ <input type="submit" value="Go" />
+ </form>
+ </div>
+</search>
+<script>document.getElementById('searchbox').style.display = "block"</script><h3>Navigation</h3>
+<p class="caption" role="heading"><span class="caption-text">Documentation</span></p>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Tutorials</a></li>
+<li class="toctree-l1 current"><a class="reference internal" href="index.html">How‑to guides</a><ul class="current">
+<li class="toctree-l2"><a class="reference internal" href="sessions.html">Managing sessions</a></li>
+<li class="toctree-l2 current"><a class="current reference internal" href="#">Writing middleware</a></li>
+<li class="toctree-l2"><a class="reference internal" href="templates.html">Rendering templates</a></li>
+<li class="toctree-l2"><a class="reference internal" href="streaming.html">Streaming responses</a></li>
+<li class="toctree-l2"><a class="reference internal" href="static_files.html">Serving static files</a></li>
+<li class="toctree-l2"><a class="reference internal" href="socketio.html">Integrating Socket.IO</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="../reference/index.html">API reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../explanation/index.html">Explanations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
+</ul>
+
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="../index.html">Documentation overview</a><ul>
+ <li><a href="index.html">How‑to guides</a><ul>
+ <li>Previous: <a href="sessions.html" title="previous chapter">Managing sessions</a></li>
+ <li>Next: <a href="templates.html" title="next chapter">Rendering templates</a></li>
+ </ul></li>
+ </ul></li>
+</ul>
+</div>
+
+
+
+
+
+
+
+
+ </div>
+ </div>
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+
+
+ <div class="body" role="main">
+
+ <section id="writing-middleware">
+<h1>Writing middleware<a class="headerlink" href="#writing-middleware" title="Link to this heading">¶</a></h1>
+<p>Middleware allows you to insert code that runs before and after your
+handlers. It is useful for cross‑cutting concerns such as logging,
+authentication, rate limiting or explicit routing. MicroPie defines
+separate middleware classes for HTTP and WebSocket connections.</p>
+<section id="http-middleware">
+<h2>HTTP middleware<a class="headerlink" href="#http-middleware" title="Link to this heading">¶</a></h2>
+<p>To create HTTP middleware, subclass <code class="xref py py-class docutils literal notranslate"><span class="pre">HttpMiddleware</span></code>
+and implement two asynchronous methods:</p>
+<ul class="simple">
+<li><p><code class="xref py py-meth docutils literal notranslate"><span class="pre">before_request()</span></code> – called before the
+handler is executed. If this method returns a dictionary with
+<code class="docutils literal notranslate"><span class="pre">status_code</span></code> and <code class="docutils literal notranslate"><span class="pre">body</span></code> keys, MicroPie immediately sends that
+response and skips calling the handler. You can also provide
+additional headers via a <code class="docutils literal notranslate"><span class="pre">headers</span></code> key.</p></li>
+<li><p><code class="xref py py-meth docutils literal notranslate"><span class="pre">after_request()</span></code> – called after the
+handler has returned a response but before it is sent to the client.
+You can modify the status code, body or headers by returning a
+dictionary with updated values.</p></li>
+</ul>
+<p>Register your middleware by appending an instance to
+<code class="xref py py-attr docutils literal notranslate"><span class="pre">middlewares</span></code> on your application:</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">micropie</span> <span class="kn">import</span> <span class="n">App</span><span class="p">,</span> <span class="n">HttpMiddleware</span>
+
+<span class="k">class</span> <span class="nc">LoggingMiddleware</span><span class="p">(</span><span class="n">HttpMiddleware</span><span class="p">):</span>
+ <span class="k">async</span> <span class="k">def</span> <span class="nf">before_request</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">request</span><span class="p">):</span>
+ <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Incoming request: </span><span class="si">{</span><span class="n">request</span><span class="o">.</span><span class="n">method</span><span class="si">}</span><span class="s2"> </span><span class="si">{</span><span class="n">request</span><span class="o">.</span><span class="n">scope</span><span class="p">[</span><span class="s1">'path'</span><span class="p">]</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
+ <span class="c1"># returning None continues processing</span>
+
+ <span class="k">async</span> <span class="k">def</span> <span class="nf">after_request</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">request</span><span class="p">,</span> <span class="n">status_code</span><span class="p">,</span> <span class="n">body</span><span class="p">,</span> <span class="n">headers</span><span class="p">):</span>
+ <span class="nb">print</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Response status: </span><span class="si">{</span><span class="n">status_code</span><span class="si">}</span><span class="s2">"</span><span class="p">)</span>
+ <span class="c1"># returning None uses the original response</span>
+
+<span class="k">class</span> <span class="nc">MyApp</span><span class="p">(</span><span class="n">App</span><span class="p">):</span>
+ <span class="k">async</span> <span class="k">def</span> <span class="nf">index</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+ <span class="k">return</span> <span class="s2">"Hello, world!"</span>
+
+<span class="n">app</span> <span class="o">=</span> <span class="n">MyApp</span><span class="p">()</span>
+<span class="n">app</span><span class="o">.</span><span class="n">middlewares</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">LoggingMiddleware</span><span class="p">())</span>
+</pre></div>
+</div>
+</section>
+<section id="websocket-middleware">
+<h2>WebSocket middleware<a class="headerlink" href="#websocket-middleware" title="Link to this heading">¶</a></h2>
+<p>WebSocket middleware must subclass <code class="xref py py-class docutils literal notranslate"><span class="pre">WebSocketMiddleware</span></code>
+and implement two methods:</p>
+<ul class="simple">
+<li><p><code class="xref py py-meth docutils literal notranslate"><span class="pre">before_websocket()</span></code> – called
+before a WebSocket handler runs. If this method returns a
+dictionary with <code class="docutils literal notranslate"><span class="pre">code</span></code> and <code class="docutils literal notranslate"><span class="pre">reason</span></code>, MicroPie closes the
+connection with the given code and reason.</p></li>
+<li><p><code class="xref py py-meth docutils literal notranslate"><span class="pre">after_websocket()</span></code> – called after
+the WebSocket handler completes. Use this to perform cleanup.</p></li>
+</ul>
+<p>Example:</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">micropie</span> <span class="kn">import</span> <span class="n">App</span><span class="p">,</span> <span class="n">WebSocketMiddleware</span>
+
+<span class="k">class</span> <span class="nc">RejectAnonymous</span><span class="p">(</span><span class="n">WebSocketMiddleware</span><span class="p">):</span>
+ <span class="k">async</span> <span class="k">def</span> <span class="nf">before_websocket</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">request</span><span class="p">):</span>
+ <span class="c1"># Reject connections without a "user" query parameter</span>
+ <span class="k">if</span> <span class="s2">"user"</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">request</span><span class="o">.</span><span class="n">query_params</span><span class="p">:</span>
+ <span class="k">return</span> <span class="p">{</span><span class="s2">"code"</span><span class="p">:</span> <span class="mi">1008</span><span class="p">,</span> <span class="s2">"reason"</span><span class="p">:</span> <span class="s2">"User name required"</span><span class="p">}</span>
+
+ <span class="k">async</span> <span class="k">def</span> <span class="nf">after_websocket</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">request</span><span class="p">):</span>
+ <span class="nb">print</span><span class="p">(</span><span class="s2">"WebSocket closed"</span><span class="p">)</span>
+
+<span class="k">class</span> <span class="nc">MyApp</span><span class="p">(</span><span class="n">App</span><span class="p">):</span>
+ <span class="k">async</span> <span class="k">def</span> <span class="nf">ws_chat</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">ws</span><span class="p">,</span> <span class="n">user</span><span class="p">):</span>
+ <span class="k">await</span> <span class="n">ws</span><span class="o">.</span><span class="n">accept</span><span class="p">()</span>
+ <span class="k">await</span> <span class="n">ws</span><span class="o">.</span><span class="n">send_text</span><span class="p">(</span><span class="sa">f</span><span class="s2">"Welcome, </span><span class="si">{</span><span class="n">user</span><span class="si">}</span><span class="s2">!"</span><span class="p">)</span>
+ <span class="k">await</span> <span class="n">ws</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
+
+<span class="n">app</span> <span class="o">=</span> <span class="n">MyApp</span><span class="p">()</span>
+<span class="n">app</span><span class="o">.</span><span class="n">ws_middlewares</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">RejectAnonymous</span><span class="p">())</span>
+</pre></div>
+</div>
+</section>
+<section id="explicit-routing-and-other-patterns">
+<h2>Explicit routing and other patterns<a class="headerlink" href="#explicit-routing-and-other-patterns" title="Link to this heading">¶</a></h2>
+<p>You can implement custom routing schemes by writing middleware that
+parses the incoming path and sets <code class="docutils literal notranslate"><span class="pre">request._route_handler</span></code> or
+<code class="docutils literal notranslate"><span class="pre">request._ws_route_handler</span></code> accordingly. See the examples in the
+<code class="docutils literal notranslate"><span class="pre">examples/middleware</span></code> directory for a complete implementation.</p>
+</section>
+</section>
+
+
+ </div>
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="footer">
+ ©.
+
+ |
+ Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.2.3</a>
+ & <a href="https://alabaster.readthedocs.io">Alabaster 1.0.0</a>
+
+ |
+ <a href="../_sources/howto/middleware.rst.txt"
+ rel="nofollow">Page source</a>
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file
diff --git a/docs/docs/howto/sessions.html b/docs/docs/howto/sessions.html
new file mode 100644
index 0000000..c03b41b
--- /dev/null
+++ b/docs/docs/howto/sessions.html
@@ -0,0 +1,202 @@
+<!DOCTYPE html>
+
+<html lang="en" data-content_root="../">
+ <head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
+
+ <title>Managing sessions — MicroPie 0.20 documentation</title>
+ <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d1102ebc" />
+ <link rel="stylesheet" type="text/css" href="../_static/basic.css?v=b08954a9" />
+ <link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=f6a572b4" />
+ <script src="../_static/documentation_options.js?v=0144e382"></script>
+ <script src="../_static/doctools.js?v=9bcbadda"></script>
+ <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Writing middleware" href="middleware.html" />
+ <link rel="prev" title="How‑to guides" href="index.html" />
+
+ <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
+
+
+
+
+ </head><body>
+ <div class="document">
+
+ <div class="sphinxsidebar" role="navigation" aria-label="Main">
+ <div class="sphinxsidebarwrapper">
+<h1 class="logo"><a href="../index.html">MicroPie</a></h1>
+
+
+
+<p class="blurb">A minimal ASGI web framework</p>
+
+
+
+
+<p>
+<iframe src="https://ghbtns.com/github-btn.html?user=patx&repo=micropie&type=watch&count=true&size=large&v=2"
+ allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
+</p>
+
+
+
+
+
+
+<search id="searchbox" style="display: none" role="search">
+ <div class="searchformwrapper">
+ <form class="search" action="../search.html" method="get">
+ <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" placeholder="Search"/>
+ <input type="submit" value="Go" />
+ </form>
+ </div>
+</search>
+<script>document.getElementById('searchbox').style.display = "block"</script><h3>Navigation</h3>
+<p class="caption" role="heading"><span class="caption-text">Documentation</span></p>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Tutorials</a></li>
+<li class="toctree-l1 current"><a class="reference internal" href="index.html">How‑to guides</a><ul class="current">
+<li class="toctree-l2 current"><a class="current reference internal" href="#">Managing sessions</a></li>
+<li class="toctree-l2"><a class="reference internal" href="middleware.html">Writing middleware</a></li>
+<li class="toctree-l2"><a class="reference internal" href="templates.html">Rendering templates</a></li>
+<li class="toctree-l2"><a class="reference internal" href="streaming.html">Streaming responses</a></li>
+<li class="toctree-l2"><a class="reference internal" href="static_files.html">Serving static files</a></li>
+<li class="toctree-l2"><a class="reference internal" href="socketio.html">Integrating Socket.IO</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="../reference/index.html">API reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../explanation/index.html">Explanations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
+</ul>
+
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="../index.html">Documentation overview</a><ul>
+ <li><a href="index.html">How‑to guides</a><ul>
+ <li>Previous: <a href="index.html" title="previous chapter">How‑to guides</a></li>
+ <li>Next: <a href="middleware.html" title="next chapter">Writing middleware</a></li>
+ </ul></li>
+ </ul></li>
+</ul>
+</div>
+
+
+
+
+
+
+
+
+ </div>
+ </div>
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+
+
+ <div class="body" role="main">
+
+ <section id="managing-sessions">
+<h1>Managing sessions<a class="headerlink" href="#managing-sessions" title="Link to this heading">¶</a></h1>
+<p>MicroPie includes simple session management built on top of cookies. A
+session stores data associated with a client across multiple requests.
+Sessions are useful for keeping track of login state, counters and
+temporary information.</p>
+<section id="enabling-sessions">
+<h2>Enabling sessions<a class="headerlink" href="#enabling-sessions" title="Link to this heading">¶</a></h2>
+<p>By default, MicroPie uses an in‑memory session back‑end implemented by
+<code class="xref py py-class docutils literal notranslate"><span class="pre">InMemorySessionBackend</span></code>. Each session is identified
+by a <code class="docutils literal notranslate"><span class="pre">session_id</span></code> cookie. When the client makes a request, the
+cookie is read and the session data is loaded from the back‑end. When
+you modify the session dictionary, MicroPie writes the updated
+session back at the end of the request and issues a <code class="docutils literal notranslate"><span class="pre">Set‑Cookie</span></code>
+header if needed.</p>
+<p>In order to use sessions, simply read and write the
+<code class="xref py py-attr docutils literal notranslate"><span class="pre">session</span></code> dictionary in your handler. The
+following example counts the number of visits for each client:</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">micropie</span> <span class="kn">import</span> <span class="n">App</span>
+
+<span class="k">class</span> <span class="nc">MyApp</span><span class="p">(</span><span class="n">App</span><span class="p">):</span>
+ <span class="k">async</span> <span class="k">def</span> <span class="nf">index</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+ <span class="k">if</span> <span class="s2">"visits"</span> <span class="ow">not</span> <span class="ow">in</span> <span class="bp">self</span><span class="o">.</span><span class="n">request</span><span class="o">.</span><span class="n">session</span><span class="p">:</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">request</span><span class="o">.</span><span class="n">session</span><span class="p">[</span><span class="s2">"visits"</span><span class="p">]</span> <span class="o">=</span> <span class="mi">1</span>
+ <span class="k">else</span><span class="p">:</span>
+ <span class="bp">self</span><span class="o">.</span><span class="n">request</span><span class="o">.</span><span class="n">session</span><span class="p">[</span><span class="s2">"visits"</span><span class="p">]</span> <span class="o">+=</span> <span class="mi">1</span>
+ <span class="k">return</span> <span class="sa">f</span><span class="s2">"You have visited </span><span class="si">{</span><span class="bp">self</span><span class="o">.</span><span class="n">request</span><span class="o">.</span><span class="n">session</span><span class="p">[</span><span class="s1">'visits'</span><span class="p">]</span><span class="si">}</span><span class="s2"> times."</span>
+
+<span class="n">app</span> <span class="o">=</span> <span class="n">MyApp</span><span class="p">()</span>
+</pre></div>
+</div>
+</section>
+<section id="custom-session-backends">
+<h2>Custom session back‑ends<a class="headerlink" href="#custom-session-backends" title="Link to this heading">¶</a></h2>
+<p>The in‑memory back‑end stores all sessions in a Python dictionary. It
+is suitable for development but will lose data when the process
+terminates and cannot be shared across worker processes. To persist
+sessions in a database or cache, implement the abstract
+<code class="xref py py-class docutils literal notranslate"><span class="pre">SessionBackend</span></code> interface:</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">micropie</span> <span class="kn">import</span> <span class="n">SessionBackend</span>
+
+<span class="k">class</span> <span class="nc">DatabaseSessionBackend</span><span class="p">(</span><span class="n">SessionBackend</span><span class="p">):</span>
+ <span class="k">async</span> <span class="k">def</span> <span class="nf">load</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">session_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-></span> <span class="nb">dict</span><span class="p">:</span>
+ <span class="c1"># fetch the session from your database or cache</span>
+ <span class="n">data</span> <span class="o">=</span> <span class="k">await</span> <span class="n">get_session_from_db</span><span class="p">(</span><span class="n">session_id</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">data</span> <span class="ow">or</span> <span class="p">{}</span>
+
+ <span class="k">async</span> <span class="k">def</span> <span class="nf">save</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">session_id</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">data</span><span class="p">:</span> <span class="nb">dict</span><span class="p">,</span> <span class="n">timeout</span><span class="p">:</span> <span class="nb">int</span><span class="p">)</span> <span class="o">-></span> <span class="kc">None</span><span class="p">:</span>
+ <span class="c1"># store the session with an expiration timeout</span>
+ <span class="k">await</span> <span class="n">save_session_to_db</span><span class="p">(</span><span class="n">session_id</span><span class="p">,</span> <span class="n">data</span><span class="p">,</span> <span class="n">timeout</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>Assign your back‑end when constructing your application:</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">backend</span> <span class="o">=</span> <span class="n">DatabaseSessionBackend</span><span class="p">()</span>
+<span class="n">app</span> <span class="o">=</span> <span class="n">MyApp</span><span class="p">(</span><span class="n">session_backend</span><span class="o">=</span><span class="n">backend</span><span class="p">)</span>
+</pre></div>
+</div>
+</section>
+<section id="expiring-sessions">
+<h2>Expiring sessions<a class="headerlink" href="#expiring-sessions" title="Link to this heading">¶</a></h2>
+<p>The global constant <code class="xref py py-data docutils literal notranslate"><span class="pre">micropie.SESSION_TIMEOUT</span></code> controls how long
+a session remains valid (in seconds). The default is eight hours.
+Back‑ends may choose to enforce this timeout in whatever manner makes
+sense for their storage layer.</p>
+</section>
+<section id="security-considerations">
+<h2>Security considerations<a class="headerlink" href="#security-considerations" title="Link to this heading">¶</a></h2>
+<p>Sessions are sent to the client as cookies and should be treated as
+untrusted input. Avoid storing sensitive information directly in the
+session. If you implement your own back‑end, ensure that session
+identifiers are random, unique and that the cookie includes the
+<code class="docutils literal notranslate"><span class="pre">HttpOnly</span></code>, <code class="docutils literal notranslate"><span class="pre">Secure</span></code> and <code class="docutils literal notranslate"><span class="pre">SameSite=Lax</span></code> directives. The
+in‑memory back‑end provided by MicroPie already issues these flags.</p>
+</section>
+</section>
+
+
+ </div>
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="footer">
+ ©.
+
+ |
+ Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.2.3</a>
+ & <a href="https://alabaster.readthedocs.io">Alabaster 1.0.0</a>
+
+ |
+ <a href="../_sources/howto/sessions.rst.txt"
+ rel="nofollow">Page source</a>
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file
diff --git a/docs/docs/howto/socketio.html b/docs/docs/howto/socketio.html
new file mode 100644
index 0000000..03bc60d
--- /dev/null
+++ b/docs/docs/howto/socketio.html
@@ -0,0 +1,175 @@
+<!DOCTYPE html>
+
+<html lang="en" data-content_root="../">
+ <head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
+
+ <title>Integrating Socket.IO — MicroPie 0.20 documentation</title>
+ <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d1102ebc" />
+ <link rel="stylesheet" type="text/css" href="../_static/basic.css?v=b08954a9" />
+ <link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=f6a572b4" />
+ <script src="../_static/documentation_options.js?v=0144e382"></script>
+ <script src="../_static/doctools.js?v=9bcbadda"></script>
+ <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="API reference" href="../reference/index.html" />
+ <link rel="prev" title="Serving static files" href="static_files.html" />
+
+ <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
+
+
+
+
+ </head><body>
+ <div class="document">
+
+ <div class="sphinxsidebar" role="navigation" aria-label="Main">
+ <div class="sphinxsidebarwrapper">
+<h1 class="logo"><a href="../index.html">MicroPie</a></h1>
+
+
+
+<p class="blurb">A minimal ASGI web framework</p>
+
+
+
+
+<p>
+<iframe src="https://ghbtns.com/github-btn.html?user=patx&repo=micropie&type=watch&count=true&size=large&v=2"
+ allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
+</p>
+
+
+
+
+
+
+<search id="searchbox" style="display: none" role="search">
+ <div class="searchformwrapper">
+ <form class="search" action="../search.html" method="get">
+ <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" placeholder="Search"/>
+ <input type="submit" value="Go" />
+ </form>
+ </div>
+</search>
+<script>document.getElementById('searchbox').style.display = "block"</script><h3>Navigation</h3>
+<p class="caption" role="heading"><span class="caption-text">Documentation</span></p>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Tutorials</a></li>
+<li class="toctree-l1 current"><a class="reference internal" href="index.html">How‑to guides</a><ul class="current">
+<li class="toctree-l2"><a class="reference internal" href="sessions.html">Managing sessions</a></li>
+<li class="toctree-l2"><a class="reference internal" href="middleware.html">Writing middleware</a></li>
+<li class="toctree-l2"><a class="reference internal" href="templates.html">Rendering templates</a></li>
+<li class="toctree-l2"><a class="reference internal" href="streaming.html">Streaming responses</a></li>
+<li class="toctree-l2"><a class="reference internal" href="static_files.html">Serving static files</a></li>
+<li class="toctree-l2 current"><a class="current reference internal" href="#">Integrating Socket.IO</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="../reference/index.html">API reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../explanation/index.html">Explanations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
+</ul>
+
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="../index.html">Documentation overview</a><ul>
+ <li><a href="index.html">How‑to guides</a><ul>
+ <li>Previous: <a href="static_files.html" title="previous chapter">Serving static files</a></li>
+ <li>Next: <a href="../reference/index.html" title="next chapter">API reference</a></li>
+ </ul></li>
+ </ul></li>
+</ul>
+</div>
+
+
+
+
+
+
+
+
+ </div>
+ </div>
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+
+
+ <div class="body" role="main">
+
+ <section id="integrating-socket-io">
+<h1>Integrating Socket.IO<a class="headerlink" href="#integrating-socket-io" title="Link to this heading">¶</a></h1>
+<p>MicroPie’s built‑in WebSocket support provides a simple API for
+bidirectional communication. If you require advanced features such
+as automatic reconnection, broadcasting to rooms, namespaces, or
+fallback transports for browsers that do not support WebSockets, you
+can integrate <a class="reference external" href="https://python-socketio.readthedocs.io">python‑socketio</a>.</p>
+<p>Socket.IO runs as an ASGI application, so you can mount it
+alongside your MicroPie app and serve both under the same Uvicorn
+server. The following example shows how to set up a basic chat
+application using Socket.IO with MicroPie.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">socketio</span>
+<span class="kn">from</span> <span class="nn">micropie</span> <span class="kn">import</span> <span class="n">App</span>
+
+<span class="c1"># Create a Socket.IO server instance (ASGI compatible)</span>
+<span class="n">sio</span> <span class="o">=</span> <span class="n">socketio</span><span class="o">.</span><span class="n">AsyncServer</span><span class="p">(</span><span class="n">async_mode</span><span class="o">=</span><span class="s2">"asgi"</span><span class="p">)</span>
+<span class="n">socket_app</span> <span class="o">=</span> <span class="n">socketio</span><span class="o">.</span><span class="n">ASGIApp</span><span class="p">(</span><span class="n">sio</span><span class="p">)</span>
+
+<span class="c1"># Create your MicroPie application</span>
+<span class="k">class</span> <span class="nc">MyApp</span><span class="p">(</span><span class="n">App</span><span class="p">):</span>
+ <span class="k">async</span> <span class="k">def</span> <span class="nf">index</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+ <span class="c1"># Serve an HTML page with Socket.IO client code (omitted)</span>
+ <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">_render_template</span><span class="p">(</span><span class="s2">"chat.html"</span><span class="p">)</span>
+
+<span class="n">app</span> <span class="o">=</span> <span class="n">MyApp</span><span class="p">()</span>
+
+<span class="c1"># Uvicorn accepts a single callable; wrap both apps in a simple</span>
+<span class="c1"># dispatcher that routes to Socket.IO on the /socket.io path</span>
+<span class="k">async</span> <span class="k">def</span> <span class="nf">application</span><span class="p">(</span><span class="n">scope</span><span class="p">,</span> <span class="n">receive</span><span class="p">,</span> <span class="n">send</span><span class="p">):</span>
+ <span class="k">if</span> <span class="n">scope</span><span class="p">[</span><span class="s2">"path"</span><span class="p">]</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s2">"/socket.io"</span><span class="p">):</span>
+ <span class="k">await</span> <span class="n">socket_app</span><span class="p">(</span><span class="n">scope</span><span class="p">,</span> <span class="n">receive</span><span class="p">,</span> <span class="n">send</span><span class="p">)</span>
+ <span class="k">else</span><span class="p">:</span>
+ <span class="k">await</span> <span class="n">app</span><span class="p">(</span><span class="n">scope</span><span class="p">,</span> <span class="n">receive</span><span class="p">,</span> <span class="n">send</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>Run the dispatcher with Uvicorn:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>uvicorn<span class="w"> </span>app:application
+</pre></div>
+</div>
+<p>On the client side, connect to <code class="docutils literal notranslate"><span class="pre">/socket.io</span></code> as usual using the
+Socket.IO JavaScript client. All other paths are handled by your
+MicroPie routes. See the <code class="docutils literal notranslate"><span class="pre">examples/socketio</span></code> directory in the
+MicroPie source distribution for a more complete implementation that
+includes HTML and JavaScript code.</p>
+<p>Note that python‑socketio may install its own dependencies. Consult
+the Socket.IO documentation for configuration options such as
+message queue back‑ends and authentication.</p>
+</section>
+
+
+ </div>
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="footer">
+ ©.
+
+ |
+ Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.2.3</a>
+ & <a href="https://alabaster.readthedocs.io">Alabaster 1.0.0</a>
+
+ |
+ <a href="../_sources/howto/socketio.rst.txt"
+ rel="nofollow">Page source</a>
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file
diff --git a/docs/docs/howto/static_files.html b/docs/docs/howto/static_files.html
new file mode 100644
index 0000000..38215f5
--- /dev/null
+++ b/docs/docs/howto/static_files.html
@@ -0,0 +1,168 @@
+<!DOCTYPE html>
+
+<html lang="en" data-content_root="../">
+ <head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
+
+ <title>Serving static files — MicroPie 0.20 documentation</title>
+ <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d1102ebc" />
+ <link rel="stylesheet" type="text/css" href="../_static/basic.css?v=b08954a9" />
+ <link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=f6a572b4" />
+ <script src="../_static/documentation_options.js?v=0144e382"></script>
+ <script src="../_static/doctools.js?v=9bcbadda"></script>
+ <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Integrating Socket.IO" href="socketio.html" />
+ <link rel="prev" title="Streaming responses" href="streaming.html" />
+
+ <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
+
+
+
+
+ </head><body>
+ <div class="document">
+
+ <div class="sphinxsidebar" role="navigation" aria-label="Main">
+ <div class="sphinxsidebarwrapper">
+<h1 class="logo"><a href="../index.html">MicroPie</a></h1>
+
+
+
+<p class="blurb">A minimal ASGI web framework</p>
+
+
+
+
+<p>
+<iframe src="https://ghbtns.com/github-btn.html?user=patx&repo=micropie&type=watch&count=true&size=large&v=2"
+ allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
+</p>
+
+
+
+
+
+
+<search id="searchbox" style="display: none" role="search">
+ <div class="searchformwrapper">
+ <form class="search" action="../search.html" method="get">
+ <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" placeholder="Search"/>
+ <input type="submit" value="Go" />
+ </form>
+ </div>
+</search>
+<script>document.getElementById('searchbox').style.display = "block"</script><h3>Navigation</h3>
+<p class="caption" role="heading"><span class="caption-text">Documentation</span></p>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Tutorials</a></li>
+<li class="toctree-l1 current"><a class="reference internal" href="index.html">How‑to guides</a><ul class="current">
+<li class="toctree-l2"><a class="reference internal" href="sessions.html">Managing sessions</a></li>
+<li class="toctree-l2"><a class="reference internal" href="middleware.html">Writing middleware</a></li>
+<li class="toctree-l2"><a class="reference internal" href="templates.html">Rendering templates</a></li>
+<li class="toctree-l2"><a class="reference internal" href="streaming.html">Streaming responses</a></li>
+<li class="toctree-l2 current"><a class="current reference internal" href="#">Serving static files</a></li>
+<li class="toctree-l2"><a class="reference internal" href="socketio.html">Integrating Socket.IO</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="../reference/index.html">API reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../explanation/index.html">Explanations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
+</ul>
+
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="../index.html">Documentation overview</a><ul>
+ <li><a href="index.html">How‑to guides</a><ul>
+ <li>Previous: <a href="streaming.html" title="previous chapter">Streaming responses</a></li>
+ <li>Next: <a href="socketio.html" title="next chapter">Integrating Socket.IO</a></li>
+ </ul></li>
+ </ul></li>
+</ul>
+</div>
+
+
+
+
+
+
+
+
+ </div>
+ </div>
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+
+
+ <div class="body" role="main">
+
+ <section id="serving-static-files">
+<h1>Serving static files<a class="headerlink" href="#serving-static-files" title="Link to this heading">¶</a></h1>
+<p>MicroPie deliberately avoids bundling a static file server. Serving
+static content such as images, CSS and JavaScript can be delegated to
+a specialised middleware or a separate web server. This approach
+keeps the core framework small and flexible.</p>
+<section id="using-a-static-file-middleware">
+<h2>Using a static file middleware<a class="headerlink" href="#using-a-static-file-middleware" title="Link to this heading">¶</a></h2>
+<p>To serve static files from within your MicroPie application, you can
+use third‑party libraries such as
+<a class="reference external" href="https://archmonger.github.io/ServeStatic/latest/">ServeStatic</a> or
+Starlette’s <cite>StaticFiles</cite> class. The example below uses
+ServeStatic to serve files from a <code class="docutils literal notranslate"><span class="pre">static</span></code> directory:</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">micropie</span> <span class="kn">import</span> <span class="n">App</span>
+<span class="kn">from</span> <span class="nn">servestatic</span> <span class="kn">import</span> <span class="n">ServeStatic</span>
+
+<span class="k">class</span> <span class="nc">MyApp</span><span class="p">(</span><span class="n">App</span><span class="p">):</span>
+ <span class="k">async</span> <span class="k">def</span> <span class="nf">index</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+ <span class="k">return</span> <span class="s2">"Hello, world!"</span>
+
+<span class="n">app</span> <span class="o">=</span> <span class="n">MyApp</span><span class="p">()</span>
+
+<span class="c1"># Mount the static file handler at the /static path</span>
+<span class="n">app_with_static</span> <span class="o">=</span> <span class="n">ServeStatic</span><span class="p">(</span><span class="n">app</span><span class="p">,</span> <span class="n">directory</span><span class="o">=</span><span class="s2">"static"</span><span class="p">,</span> <span class="n">path_prefix</span><span class="o">=</span><span class="s2">"/static"</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>When running your application, pass <code class="docutils literal notranslate"><span class="pre">app_with_static</span></code> to your ASGI
+server instead of <code class="docutils literal notranslate"><span class="pre">app</span></code>. Requests to paths under <code class="docutils literal notranslate"><span class="pre">/static</span></code> will
+be served from your <code class="docutils literal notranslate"><span class="pre">static</span></code> directory, while all other requests
+fall through to your MicroPie routes.</p>
+</section>
+<section id="using-a-reverse-proxy">
+<h2>Using a reverse proxy<a class="headerlink" href="#using-a-reverse-proxy" title="Link to this heading">¶</a></h2>
+<p>Alternatively, you can serve static files via a dedicated HTTP server
+such as Nginx or Caddy. In production deployments this is often the
+preferred option, as a dedicated server can handle caching and
+compression. Configure your web server to serve the <code class="docutils literal notranslate"><span class="pre">/static</span></code>
+prefix directly from the filesystem and forward all other requests to
+your ASGI server running MicroPie.</p>
+</section>
+</section>
+
+
+ </div>
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="footer">
+ ©.
+
+ |
+ Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.2.3</a>
+ & <a href="https://alabaster.readthedocs.io">Alabaster 1.0.0</a>
+
+ |
+ <a href="../_sources/howto/static_files.rst.txt"
+ rel="nofollow">Page source</a>
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file
diff --git a/docs/docs/howto/streaming.html b/docs/docs/howto/streaming.html
new file mode 100644
index 0000000..101b5bb
--- /dev/null
+++ b/docs/docs/howto/streaming.html
@@ -0,0 +1,186 @@
+<!DOCTYPE html>
+
+<html lang="en" data-content_root="../">
+ <head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
+
+ <title>Streaming responses — MicroPie 0.20 documentation</title>
+ <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d1102ebc" />
+ <link rel="stylesheet" type="text/css" href="../_static/basic.css?v=b08954a9" />
+ <link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=f6a572b4" />
+ <script src="../_static/documentation_options.js?v=0144e382"></script>
+ <script src="../_static/doctools.js?v=9bcbadda"></script>
+ <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Serving static files" href="static_files.html" />
+ <link rel="prev" title="Rendering templates" href="templates.html" />
+
+ <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
+
+
+
+
+ </head><body>
+ <div class="document">
+
+ <div class="sphinxsidebar" role="navigation" aria-label="Main">
+ <div class="sphinxsidebarwrapper">
+<h1 class="logo"><a href="../index.html">MicroPie</a></h1>
+
+
+
+<p class="blurb">A minimal ASGI web framework</p>
+
+
+
+
+<p>
+<iframe src="https://ghbtns.com/github-btn.html?user=patx&repo=micropie&type=watch&count=true&size=large&v=2"
+ allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
+</p>
+
+
+
+
+
+
+<search id="searchbox" style="display: none" role="search">
+ <div class="searchformwrapper">
+ <form class="search" action="../search.html" method="get">
+ <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" placeholder="Search"/>
+ <input type="submit" value="Go" />
+ </form>
+ </div>
+</search>
+<script>document.getElementById('searchbox').style.display = "block"</script><h3>Navigation</h3>
+<p class="caption" role="heading"><span class="caption-text">Documentation</span></p>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Tutorials</a></li>
+<li class="toctree-l1 current"><a class="reference internal" href="index.html">How‑to guides</a><ul class="current">
+<li class="toctree-l2"><a class="reference internal" href="sessions.html">Managing sessions</a></li>
+<li class="toctree-l2"><a class="reference internal" href="middleware.html">Writing middleware</a></li>
+<li class="toctree-l2"><a class="reference internal" href="templates.html">Rendering templates</a></li>
+<li class="toctree-l2 current"><a class="current reference internal" href="#">Streaming responses</a></li>
+<li class="toctree-l2"><a class="reference internal" href="static_files.html">Serving static files</a></li>
+<li class="toctree-l2"><a class="reference internal" href="socketio.html">Integrating Socket.IO</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="../reference/index.html">API reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../explanation/index.html">Explanations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
+</ul>
+
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="../index.html">Documentation overview</a><ul>
+ <li><a href="index.html">How‑to guides</a><ul>
+ <li>Previous: <a href="templates.html" title="previous chapter">Rendering templates</a></li>
+ <li>Next: <a href="static_files.html" title="next chapter">Serving static files</a></li>
+ </ul></li>
+ </ul></li>
+</ul>
+</div>
+
+
+
+
+
+
+
+
+ </div>
+ </div>
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+
+
+ <div class="body" role="main">
+
+ <section id="streaming-responses">
+<h1>Streaming responses<a class="headerlink" href="#streaming-responses" title="Link to this heading">¶</a></h1>
+<p>For long‑running tasks or large responses it is often desirable to
+stream data to the client in chunks rather than return a single
+buffer. MicroPie supports streaming by allowing your handler to
+return an iterator or asynchronous generator. Each chunk yielded by
+the generator is sent as part of the response body. When the
+generator finishes, MicroPie automatically sends an empty chunk to
+signal completion.</p>
+<section id="example-number-stream">
+<h2>Example: number stream<a class="headerlink" href="#example-number-stream" title="Link to this heading">¶</a></h2>
+<p>The following handler streams a sequence of numbers to the client one
+per second:</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">micropie</span> <span class="kn">import</span> <span class="n">App</span>
+<span class="kn">import</span> <span class="nn">asyncio</span>
+
+<span class="k">class</span> <span class="nc">MyApp</span><span class="p">(</span><span class="n">App</span><span class="p">):</span>
+ <span class="k">async</span> <span class="k">def</span> <span class="nf">numbers</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+ <span class="k">async</span> <span class="k">def</span> <span class="nf">generator</span><span class="p">():</span>
+ <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">5</span><span class="p">):</span>
+ <span class="k">yield</span> <span class="sa">f</span><span class="s2">"Number: </span><span class="si">{</span><span class="n">i</span><span class="si">}</span><span class="se">\n</span><span class="s2">"</span>
+ <span class="k">await</span> <span class="n">asyncio</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">generator</span><span class="p">()</span>
+
+<span class="n">app</span> <span class="o">=</span> <span class="n">MyApp</span><span class="p">()</span>
+</pre></div>
+</div>
+<p>Visiting <code class="docutils literal notranslate"><span class="pre">/numbers</span></code> will produce output like:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Number: 0
+Number: 1
+Number: 2
+Number: 3
+Number: 4
+</pre></div>
+</div>
+<p>MicroPie automatically sets <code class="docutils literal notranslate"><span class="pre">Content‑Type</span></code> to <code class="docutils literal notranslate"><span class="pre">text/html</span></code> if you
+do not specify a content type. You can override or add headers by
+returning a tuple <code class="docutils literal notranslate"><span class="pre">(status_code,</span> <span class="pre">body,</span> <span class="pre">headers)</span></code> and making the
+generator the body.</p>
+</section>
+<section id="handling-client-disconnects">
+<h2>Handling client disconnects<a class="headerlink" href="#handling-client-disconnects" title="Link to this heading">¶</a></h2>
+<p>If the client disconnects while a generator is running, MicroPie
+cancels the generator and closes the underlying response. This
+behaviour is important for long‑lived streams such as server‑sent
+events (SSE). When writing a generator, use <code class="docutils literal notranslate"><span class="pre">try</span></code>/<code class="docutils literal notranslate"><span class="pre">finally</span></code> or
+<code class="docutils literal notranslate"><span class="pre">async</span> <span class="pre">with</span></code> to perform cleanup when the stream is cancelled.</p>
+</section>
+<section id="serversent-events">
+<h2>Server‑sent events<a class="headerlink" href="#serversent-events" title="Link to this heading">¶</a></h2>
+<p>MicroPie treats any iterable response body as a general stream.
+Implementing true server‑sent events requires you to set the
+<code class="docutils literal notranslate"><span class="pre">Content‑Type</span></code> header to <code class="docutils literal notranslate"><span class="pre">text/event-stream</span></code> and send
+properly‑formatted SSE messages (<code class="docutils literal notranslate"><span class="pre">data:</span> <span class="pre">...\n\n</span></code>). Additionally,
+MicroPie includes a patch that handles early disconnection of SSE
+clients in its HTTP handling code. For a full example, see the
+<code class="docutils literal notranslate"><span class="pre">examples/sse</span></code> directory in the MicroPie source distribution.</p>
+</section>
+</section>
+
+
+ </div>
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="footer">
+ ©.
+
+ |
+ Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.2.3</a>
+ & <a href="https://alabaster.readthedocs.io">Alabaster 1.0.0</a>
+
+ |
+ <a href="../_sources/howto/streaming.rst.txt"
+ rel="nofollow">Page source</a>
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file
diff --git a/docs/docs/howto/templates.html b/docs/docs/howto/templates.html
new file mode 100644
index 0000000..a7af7fd
--- /dev/null
+++ b/docs/docs/howto/templates.html
@@ -0,0 +1,190 @@
+<!DOCTYPE html>
+
+<html lang="en" data-content_root="../">
+ <head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
+
+ <title>Rendering templates — MicroPie 0.20 documentation</title>
+ <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d1102ebc" />
+ <link rel="stylesheet" type="text/css" href="../_static/basic.css?v=b08954a9" />
+ <link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=f6a572b4" />
+ <script src="../_static/documentation_options.js?v=0144e382"></script>
+ <script src="../_static/doctools.js?v=9bcbadda"></script>
+ <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Streaming responses" href="streaming.html" />
+ <link rel="prev" title="Writing middleware" href="middleware.html" />
+
+ <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
+
+
+
+
+ </head><body>
+ <div class="document">
+
+ <div class="sphinxsidebar" role="navigation" aria-label="Main">
+ <div class="sphinxsidebarwrapper">
+<h1 class="logo"><a href="../index.html">MicroPie</a></h1>
+
+
+
+<p class="blurb">A minimal ASGI web framework</p>
+
+
+
+
+<p>
+<iframe src="https://ghbtns.com/github-btn.html?user=patx&repo=micropie&type=watch&count=true&size=large&v=2"
+ allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
+</p>
+
+
+
+
+
+
+<search id="searchbox" style="display: none" role="search">
+ <div class="searchformwrapper">
+ <form class="search" action="../search.html" method="get">
+ <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" placeholder="Search"/>
+ <input type="submit" value="Go" />
+ </form>
+ </div>
+</search>
+<script>document.getElementById('searchbox').style.display = "block"</script><h3>Navigation</h3>
+<p class="caption" role="heading"><span class="caption-text">Documentation</span></p>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Tutorials</a></li>
+<li class="toctree-l1 current"><a class="reference internal" href="index.html">How‑to guides</a><ul class="current">
+<li class="toctree-l2"><a class="reference internal" href="sessions.html">Managing sessions</a></li>
+<li class="toctree-l2"><a class="reference internal" href="middleware.html">Writing middleware</a></li>
+<li class="toctree-l2 current"><a class="current reference internal" href="#">Rendering templates</a></li>
+<li class="toctree-l2"><a class="reference internal" href="streaming.html">Streaming responses</a></li>
+<li class="toctree-l2"><a class="reference internal" href="static_files.html">Serving static files</a></li>
+<li class="toctree-l2"><a class="reference internal" href="socketio.html">Integrating Socket.IO</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="../reference/index.html">API reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../explanation/index.html">Explanations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
+</ul>
+
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="../index.html">Documentation overview</a><ul>
+ <li><a href="index.html">How‑to guides</a><ul>
+ <li>Previous: <a href="middleware.html" title="previous chapter">Writing middleware</a></li>
+ <li>Next: <a href="streaming.html" title="next chapter">Streaming responses</a></li>
+ </ul></li>
+ </ul></li>
+</ul>
+</div>
+
+
+
+
+
+
+
+
+ </div>
+ </div>
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+
+
+ <div class="body" role="main">
+
+ <section id="rendering-templates">
+<h1>Rendering templates<a class="headerlink" href="#rendering-templates" title="Link to this heading">¶</a></h1>
+<p>MicroPie can render HTML templates using the Jinja2 template engine.
+Templates allow you to separate presentation from code by placing
+HTML in separate files. Template rendering is optional; you can use
+MicroPie without Jinja2 installed, but the
+<code class="xref py py-meth docutils literal notranslate"><span class="pre">_render_template()</span></code> method will not be available.</p>
+<section id="installing-jinja2">
+<h2>Installing Jinja2<a class="headerlink" href="#installing-jinja2" title="Link to this heading">¶</a></h2>
+<p>If you installed MicroPie with the <code class="docutils literal notranslate"><span class="pre">[standard]</span></code> extra, Jinja2 is
+already available. Otherwise install it with pip:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>pip<span class="w"> </span>install<span class="w"> </span>jinja2
+</pre></div>
+</div>
+</section>
+<section id="creating-templates">
+<h2>Creating templates<a class="headerlink" href="#creating-templates" title="Link to this heading">¶</a></h2>
+<p>MicroPie looks for templates in a directory called <code class="docutils literal notranslate"><span class="pre">templates</span></code> in
+your current working directory. Use normal Jinja2 syntax in your
+templates. Here is a simple <code class="docutils literal notranslate"><span class="pre">templates/index.html</span></code> file:</p>
+<div class="highlight-html notranslate"><div class="highlight"><pre><span></span><span class="cp"><!DOCTYPE html></span>
+<span class="p"><</span><span class="nt">html</span> <span class="na">lang</span><span class="o">=</span><span class="s">"en"</span><span class="p">></span>
+<span class="p"><</span><span class="nt">head</span><span class="p">></span>
+ <span class="p"><</span><span class="nt">meta</span> <span class="na">charset</span><span class="o">=</span><span class="s">"UTF-8"</span><span class="p">></span>
+ <span class="p"><</span><span class="nt">title</span><span class="p">></span>{{ title }}<span class="p"></</span><span class="nt">title</span><span class="p">></span>
+<span class="p"></</span><span class="nt">head</span><span class="p">></span>
+<span class="p"><</span><span class="nt">body</span><span class="p">></span>
+ <span class="p"><</span><span class="nt">h1</span><span class="p">></span>{{ message }}<span class="p"></</span><span class="nt">h1</span><span class="p">></span>
+<span class="p"></</span><span class="nt">body</span><span class="p">></span>
+<span class="p"></</span><span class="nt">html</span><span class="p">></span>
+</pre></div>
+</div>
+</section>
+<section id="rendering-a-template">
+<h2>Rendering a template<a class="headerlink" href="#rendering-a-template" title="Link to this heading">¶</a></h2>
+<p>To render a template, call <code class="xref py py-meth docutils literal notranslate"><span class="pre">_render_template()</span></code> from
+within an asynchronous handler. The method returns a string containing
+the rendered HTML. Because template loading and rendering may block,
+MicroPie runs it in a background thread using <code class="docutils literal notranslate"><span class="pre">asyncio.to_thread</span></code>.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">micropie</span> <span class="kn">import</span> <span class="n">App</span>
+
+<span class="k">class</span> <span class="nc">MyApp</span><span class="p">(</span><span class="n">App</span><span class="p">):</span>
+ <span class="k">async</span> <span class="k">def</span> <span class="nf">index</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
+ <span class="k">return</span> <span class="k">await</span> <span class="bp">self</span><span class="o">.</span><span class="n">_render_template</span><span class="p">(</span>
+ <span class="s2">"index.html"</span><span class="p">,</span>
+ <span class="n">title</span><span class="o">=</span><span class="s2">"Welcome"</span><span class="p">,</span>
+ <span class="n">message</span><span class="o">=</span><span class="s2">"Hello from MicroPie!"</span><span class="p">,</span>
+ <span class="p">)</span>
+
+<span class="n">app</span> <span class="o">=</span> <span class="n">MyApp</span><span class="p">()</span>
+</pre></div>
+</div>
+<p>When you visit <code class="docutils literal notranslate"><span class="pre">/</span></code> in your browser, MicroPie returns the rendered
+HTML with a <code class="docutils literal notranslate"><span class="pre">Content‑Type</span></code> of <code class="docutils literal notranslate"><span class="pre">text/html;</span> <span class="pre">charset=utf‑8</span></code>.</p>
+</section>
+<section id="template-variables">
+<h2>Template variables<a class="headerlink" href="#template-variables" title="Link to this heading">¶</a></h2>
+<p>You can pass arbitrary keyword arguments to <cite>_render_template</cite>. These
+become variables in the Jinja2 template. For more information on
+creating complex templates, including inheritance and control flow,
+refer to the <a class="reference external" href="https://jinja.palletsprojects.com">Jinja2 documentation</a>.</p>
+</section>
+</section>
+
+
+ </div>
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="footer">
+ ©.
+
+ |
+ Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.2.3</a>
+ & <a href="https://alabaster.readthedocs.io">Alabaster 1.0.0</a>
+
+ |
+ <a href="../_sources/howto/templates.rst.txt"
+ rel="nofollow">Page source</a>
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file
diff --git a/docs/docs/index.html b/docs/docs/index.html
new file mode 100644
index 0000000..d7a61d8
--- /dev/null
+++ b/docs/docs/index.html
@@ -0,0 +1,191 @@
+<!DOCTYPE html>
+
+<html lang="en" data-content_root="./">
+ <head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
+
+ <title>MicroPie ASGI Web Framework — MicroPie 0.20 documentation</title>
+ <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=d1102ebc" />
+ <link rel="stylesheet" type="text/css" href="_static/basic.css?v=b08954a9" />
+ <link rel="stylesheet" type="text/css" href="_static/alabaster.css?v=f6a572b4" />
+ <script src="_static/documentation_options.js?v=0144e382"></script>
+ <script src="_static/doctools.js?v=9bcbadda"></script>
+ <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Tutorials" href="tutorial/index.html" />
+
+ <link rel="stylesheet" href="_static/custom.css" type="text/css" />
+
+
+
+
+
+ </head><body>
+ <div class="document">
+
+ <div class="sphinxsidebar" role="navigation" aria-label="Main">
+ <div class="sphinxsidebarwrapper">
+<h1 class="logo"><a href="#">MicroPie</a></h1>
+
+
+
+<p class="blurb">A minimal ASGI web framework</p>
+
+
+
+
+<p>
+<iframe src="https://ghbtns.com/github-btn.html?user=patx&repo=micropie&type=watch&count=true&size=large&v=2"
+ allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
+</p>
+
+
+
+
+
+
+<search id="searchbox" style="display: none" role="search">
+ <div class="searchformwrapper">
+ <form class="search" action="search.html" method="get">
+ <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" placeholder="Search"/>
+ <input type="submit" value="Go" />
+ </form>
+ </div>
+</search>
+<script>document.getElementById('searchbox').style.display = "block"</script><h3>Navigation</h3>
+<p class="caption" role="heading"><span class="caption-text">Documentation</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="tutorial/index.html">Tutorials</a></li>
+<li class="toctree-l1"><a class="reference internal" href="howto/index.html">How‑to guides</a></li>
+<li class="toctree-l1"><a class="reference internal" href="reference/index.html">API reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="explanation/index.html">Explanations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="glossary.html">Glossary</a></li>
+</ul>
+
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="#">Documentation overview</a><ul>
+ <li>Next: <a href="tutorial/index.html" title="next chapter">Tutorials</a></li>
+ </ul></li>
+</ul>
+</div>
+
+
+
+
+
+
+
+
+ </div>
+ </div>
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+
+
+ <div class="body" role="main">
+
+ <section id="micropie-asgi-web-framework">
+<h1>MicroPie ASGI Web Framework<a class="headerlink" href="#micropie-asgi-web-framework" title="Link to this heading">¶</a></h1>
+<p>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.</p>
+<p>This documentation is organized according to the
+Diátaxis documentation framework. That framework separates documentation into
+four distinct types:</p>
+<ul class="simple">
+<li><p><strong>Tutorials</strong> – step‑by‑step introductions that teach you how to
+accomplish a task. Tutorials should avoid deep explanations and help
+you get started quickly.</p></li>
+<li><p><strong>How‑to guides</strong> – recipes focused on solving a particular problem.
+Guides assume you already know the basics and want to apply MicroPie
+to a concrete task.</p></li>
+<li><p><strong>Reference</strong> – authoritative descriptions of classes, functions and
+modules. These documents are factual and concise.</p></li>
+<li><p><strong>Explanation</strong> – discussions that explore the rationale behind
+design choices and deeper concepts in MicroPie.</p></li>
+</ul>
+<p>In addition to these four types, a small glossary collects
+terminology used throughout the framework. If you are new to
+MicroPie, start with the tutorial. If you want to accomplish a
+specific task, head to the how‑to guides. If you need to look up a
+particular method or class, consult the reference manual. For
+background and design considerations, see the explanation section.</p>
+</section>
+<section id="contents">
+<h1>Contents<a class="headerlink" href="#contents" title="Link to this heading">¶</a></h1>
+<div class="toctree-wrapper compound">
+<p class="caption" role="heading"><span class="caption-text">Documentation</span></p>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="tutorial/index.html">Tutorials</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="tutorial/quickstart.html">Quick start</a></li>
+<li class="toctree-l2"><a class="reference internal" href="tutorial/routing.html">Routing and handlers</a></li>
+<li class="toctree-l2"><a class="reference internal" href="tutorial/websockets.html">WebSocket support</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="howto/index.html">How‑to guides</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="howto/sessions.html">Managing sessions</a></li>
+<li class="toctree-l2"><a class="reference internal" href="howto/middleware.html">Writing middleware</a></li>
+<li class="toctree-l2"><a class="reference internal" href="howto/templates.html">Rendering templates</a></li>
+<li class="toctree-l2"><a class="reference internal" href="howto/streaming.html">Streaming responses</a></li>
+<li class="toctree-l2"><a class="reference internal" href="howto/static_files.html">Serving static files</a></li>
+<li class="toctree-l2"><a class="reference internal" href="howto/socketio.html">Integrating Socket.IO</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="reference/index.html">API reference</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="reference/app.html">App class</a></li>
+<li class="toctree-l2"><a class="reference internal" href="reference/request.html">Request objects</a></li>
+<li class="toctree-l2"><a class="reference internal" href="reference/websocket.html">WebSocket class</a></li>
+<li class="toctree-l2"><a class="reference internal" href="reference/middleware.html">Middleware classes</a></li>
+<li class="toctree-l2"><a class="reference internal" href="reference/session.html">Session back‑ends</a></li>
+<li class="toctree-l2"><a class="reference internal" href="reference/exceptions.html">Exceptions</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="explanation/index.html">Explanations</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="explanation/architecture.html">Architecture and design</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="glossary.html">Glossary</a></li>
+</ul>
+</div>
+</section>
+<section id="indices-and-tables">
+<h1>Indices and tables<a class="headerlink" href="#indices-and-tables" title="Link to this heading">¶</a></h1>
+<ul class="simple">
+<li><p><a class="reference internal" href="genindex.html"><span class="std std-ref">Index</span></a></p></li>
+<li><p><a class="reference internal" href="py-modindex.html"><span class="std std-ref">Module Index</span></a></p></li>
+<li><p><a class="reference internal" href="search.html"><span class="std std-ref">Search Page</span></a></p></li>
+</ul>
+</section>
+
+
+ </div>
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="footer">
+ ©.
+
+ |
+ Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.2.3</a>
+ & <a href="https://alabaster.readthedocs.io">Alabaster 1.0.0</a>
+
+ |
+ <a href="_sources/index.rst.txt"
+ rel="nofollow">Page source</a>
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file
diff --git a/docs/docs/objects.inv b/docs/docs/objects.inv
new file mode 100644
index 0000000..e9dc387
Binary files /dev/null and b/docs/docs/objects.inv differ
diff --git a/docs/docs/reference/app.html b/docs/docs/reference/app.html
new file mode 100644
index 0000000..819cc5b
--- /dev/null
+++ b/docs/docs/reference/app.html
@@ -0,0 +1,220 @@
+<!DOCTYPE html>
+
+<html lang="en" data-content_root="../">
+ <head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
+
+ <title>App class — MicroPie 0.20 documentation</title>
+ <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d1102ebc" />
+ <link rel="stylesheet" type="text/css" href="../_static/basic.css?v=b08954a9" />
+ <link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=f6a572b4" />
+ <script src="../_static/documentation_options.js?v=0144e382"></script>
+ <script src="../_static/doctools.js?v=9bcbadda"></script>
+ <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Request objects" href="request.html" />
+ <link rel="prev" title="API reference" href="index.html" />
+
+ <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
+
+
+
+
+ </head><body>
+ <div class="document">
+
+ <div class="sphinxsidebar" role="navigation" aria-label="Main">
+ <div class="sphinxsidebarwrapper">
+<h1 class="logo"><a href="../index.html">MicroPie</a></h1>
+
+
+
+<p class="blurb">A minimal ASGI web framework</p>
+
+
+
+
+<p>
+<iframe src="https://ghbtns.com/github-btn.html?user=patx&repo=micropie&type=watch&count=true&size=large&v=2"
+ allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
+</p>
+
+
+
+
+
+
+<search id="searchbox" style="display: none" role="search">
+ <div class="searchformwrapper">
+ <form class="search" action="../search.html" method="get">
+ <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" placeholder="Search"/>
+ <input type="submit" value="Go" />
+ </form>
+ </div>
+</search>
+<script>document.getElementById('searchbox').style.display = "block"</script><h3>Navigation</h3>
+<p class="caption" role="heading"><span class="caption-text">Documentation</span></p>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Tutorials</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../howto/index.html">How‑to guides</a></li>
+<li class="toctree-l1 current"><a class="reference internal" href="index.html">API reference</a><ul class="current">
+<li class="toctree-l2 current"><a class="current reference internal" href="#">App class</a></li>
+<li class="toctree-l2"><a class="reference internal" href="request.html">Request objects</a></li>
+<li class="toctree-l2"><a class="reference internal" href="websocket.html">WebSocket class</a></li>
+<li class="toctree-l2"><a class="reference internal" href="middleware.html">Middleware classes</a></li>
+<li class="toctree-l2"><a class="reference internal" href="session.html">Session back‑ends</a></li>
+<li class="toctree-l2"><a class="reference internal" href="exceptions.html">Exceptions</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="../explanation/index.html">Explanations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
+</ul>
+
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="../index.html">Documentation overview</a><ul>
+ <li><a href="index.html">API reference</a><ul>
+ <li>Previous: <a href="index.html" title="previous chapter">API reference</a></li>
+ <li>Next: <a href="request.html" title="next chapter">Request objects</a></li>
+ </ul></li>
+ </ul></li>
+</ul>
+</div>
+
+
+
+
+
+
+
+
+ </div>
+ </div>
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+
+
+ <div class="body" role="main">
+
+ <section id="app-class">
+<h1>App class<a class="headerlink" href="#app-class" title="Link to this heading">¶</a></h1>
+<p id="id1">The <code class="xref py py-class docutils literal notranslate"><span class="pre">App</span></code> class is the core of a MicroPie application.
+It implements the ASGI call interface and dispatches HTTP, WebSocket
+and lifespan events to your handlers. Subclass <code class="xref py py-class docutils literal notranslate"><span class="pre">App</span></code>
+and add public methods to create route handlers. Instantiate your
+subclass and pass the resulting object to an ASGI server such as
+Uvicorn.</p>
+<section id="constructor">
+<h2>Constructor<a class="headerlink" href="#constructor" title="Link to this heading">¶</a></h2>
+<dl class="py class">
+<dt class="sig sig-object py" id="App">
+<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">App</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">session_backend</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#App" title="Link to this definition">¶</a></dt>
+<dd><p>Create a new application. If <em>session_backend</em> is provided it must
+be an instance of <code class="xref py py-class docutils literal notranslate"><span class="pre">SessionBackend</span></code>. When omitted,
+MicroPie uses an in‑memory back‑end.</p>
+</dd></dl>
+
+</section>
+<section id="attributes">
+<h2>Attributes<a class="headerlink" href="#attributes" title="Link to this heading">¶</a></h2>
+<dl class="py attribute">
+<dt class="sig sig-object py" id="middlewares">
+<span class="sig-name descname"><span class="pre">middlewares</span></span><a class="headerlink" href="#middlewares" title="Link to this definition">¶</a></dt>
+<dd><p>A list of <code class="xref py py-class docutils literal notranslate"><span class="pre">HttpMiddleware</span></code> instances. Middlewares
+run before and after every HTTP request. Append a middleware
+instance to enable it. See <a class="reference internal" href="../howto/middleware.html"><span class="doc">Writing middleware</span></a> for examples.</p>
+</dd></dl>
+
+<dl class="py attribute">
+<dt class="sig sig-object py" id="ws_middlewares">
+<span class="sig-name descname"><span class="pre">ws_middlewares</span></span><a class="headerlink" href="#ws_middlewares" title="Link to this definition">¶</a></dt>
+<dd><p>A list of <code class="xref py py-class docutils literal notranslate"><span class="pre">WebSocketMiddleware</span></code> instances used for
+WebSocket connections.</p>
+</dd></dl>
+
+<dl class="py attribute">
+<dt class="sig sig-object py" id="startup_handlers">
+<span class="sig-name descname"><span class="pre">startup_handlers</span></span><a class="headerlink" href="#startup_handlers" title="Link to this definition">¶</a></dt>
+<dd><p>A list of asynchronous callables that run during the ASGI
+<code class="docutils literal notranslate"><span class="pre">lifespan.startup</span></code> event. Use this to set up resources such as
+database connections. See <a class="reference internal" href="../tutorial/quickstart.html"><span class="doc">Quick start</span></a> for an
+example.</p>
+</dd></dl>
+
+<dl class="py attribute">
+<dt class="sig sig-object py" id="shutdown_handlers">
+<span class="sig-name descname"><span class="pre">shutdown_handlers</span></span><a class="headerlink" href="#shutdown_handlers" title="Link to this definition">¶</a></dt>
+<dd><p>A list of asynchronous callables that run during the ASGI
+<code class="docutils literal notranslate"><span class="pre">lifespan.shutdown</span></code> event. Use this to clean up resources.</p>
+</dd></dl>
+
+</section>
+<section id="methods">
+<h2>Methods<a class="headerlink" href="#methods" title="Link to this heading">¶</a></h2>
+<dl class="py method">
+<dt class="sig sig-object py" id="call__">
+<span class="sig-name descname"><span class="pre">__call__</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">scope</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">receive</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">send</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#call__" title="Link to this definition">¶</a></dt>
+<dd><p>The ASGI entry point. Dispatches to HTTP, WebSocket or lifespan
+handlers based on <code class="docutils literal notranslate"><span class="pre">scope['type']</span></code>. You normally do not call this
+directly; the ASGI server calls it for you.</p>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="request">
+<span class="sig-name descname"><span class="pre">request</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#request" title="Link to this definition">¶</a></dt>
+<dd><p>Return the current <code class="xref py py-class docutils literal notranslate"><span class="pre">Request</span></code> object. This is
+stored in a context variable so that it is available throughout
+asynchronous callbacks.</p>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="redirect">
+<span class="sig-name descname"><span class="pre">_redirect</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">location</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">extra_headers</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#redirect" title="Link to this definition">¶</a></dt>
+<dd><p>Return a tuple <code class="docutils literal notranslate"><span class="pre">(302,</span> <span class="pre">'',</span> <span class="pre">headers)</span></code> representing an HTTP redirect
+to <em>location</em>. Use this helper in your handlers to redirect the
+client.</p>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="render_template">
+<span class="sig-name descname"><span class="pre">_render_template</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#render_template" title="Link to this definition">¶</a></dt>
+<dd><p>Render a Jinja2 template asynchronously. Returns a string
+containing the rendered output. Requires Jinja2 to be installed.
+See <a class="reference internal" href="../howto/templates.html"><span class="doc">Rendering templates</span></a> for details.</p>
+</dd></dl>
+
+<p>Additionally, MicroPie defines several private helper methods such as
+<code class="docutils literal notranslate"><span class="pre">_parse_cookies</span></code> and <code class="docutils literal notranslate"><span class="pre">_send_response</span></code>. These are considered
+internal and not part of the public API. They may change without
+notice.</p>
+</section>
+</section>
+
+
+ </div>
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="footer">
+ ©.
+
+ |
+ Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.2.3</a>
+ & <a href="https://alabaster.readthedocs.io">Alabaster 1.0.0</a>
+
+ |
+ <a href="../_sources/reference/app.rst.txt"
+ rel="nofollow">Page source</a>
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file
diff --git a/docs/docs/reference/exceptions.html b/docs/docs/reference/exceptions.html
new file mode 100644
index 0000000..e891c9b
--- /dev/null
+++ b/docs/docs/reference/exceptions.html
@@ -0,0 +1,147 @@
+<!DOCTYPE html>
+
+<html lang="en" data-content_root="../">
+ <head>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
+
+ <title>Exceptions — MicroPie 0.20 documentation</title>
+ <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d1102ebc" />
+ <link rel="stylesheet" type="text/css" href="../_static/basic.css?v=b08954a9" />
+ <link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=f6a572b4" />
+ <script src="../_static/documentation_options.js?v=0144e382"></script>
+ <script src="../_static/doctools.js?v=9bcbadda"></script>
+ <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Explanations" href="../explanation/index.html" />
+ <link rel="prev" title="Session back‑ends" href="session.html" />
+
+ <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
+
+
+
+
+ </head><body>
+ <div class="document">
+
+ <div class="sphinxsidebar" role="navigation" aria-label="Main">
+ <div class="sphinxsidebarwrapper">
+<h1 class="logo"><a href="../index.html">MicroPie</a></h1>
+
+
+
+<p class="blurb">A minimal ASGI web framework</p>
+
+
+
+
+<p>
+<iframe src="https://ghbtns.com/github-btn.html?user=patx&repo=micropie&type=watch&count=true&size=large&v=2"
+ allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
+</p>
+
+
+
+
+
+
+<search id="searchbox" style="display: none" role="search">
+ <div class="searchformwrapper">
+ <form class="search" action="../search.html" method="get">
+ <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" placeholder="Search"/>
+ <input type="submit" value="Go" />
+ </form>
+ </div>
+</search>
+<script>document.getElementById('searchbox').style.display = "block"</script><h3>Navigation</h3>
+<p class="caption" role="heading"><span class="caption-text">Documentation</span></p>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Tutorials</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../howto/index.html">How‑to guides</a></li>
+<li class="toctree-l1 current"><a class="reference internal" href="index.html">API reference</a><ul class="current">
+<li class="toctree-l2"><a class="reference internal" href="app.html">App class</a></li>
+<li class="toctree-l2"><a class="reference internal" href="request.html">Request objects</a></li>
+<li class="toctree-l2"><a class="reference internal" href="websocket.html">WebSocket class</a></li>
+<li class="toctree-l2"><a class="reference internal" href="middleware.html">Middleware classes</a></li>
+<li class="toctree-l2"><a class="reference internal" href="session.html">Session back‑ends</a></li>
+<li class="toctree-l2 current"><a class="current referen
[Diff truncated. Use the raw view or local clone for the full content.]