Add comprehensive docstrings, expand API reference, upgrade to Starlette 1.0

- Add docstrings to all undocumented public methods across API, Request,
  Response, Router, Route, BackgroundQueue, and related classes
- Expand api.rst with autodoc sections for RouteGroup, BackgroundQueue,
  QueryDict, and RateLimiter
- Update starlette dependency to >=1.0
- Drop Python 3.9 support (required by Starlette 1.0), minimum is now 3.10
- Bump version to 3.4.0

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: kennethreitz

README.md

@@ -17,7 +17,7 @@ if __name__ == "__main__":
 
     $ pip install responder
 
-That's it. Supports Python 3.9+.
+That's it. Supports Python 3.10+.
 
 ## The Basics
 

docs/source/api.rst

@@ -43,6 +43,45 @@ status code, headers, and cookies.
     :inherited-members:
 
 
+Route Groups
+------------
+
+Group related routes under a shared URL prefix — useful for API versioning
+and organizing large applications.
+
+.. autoclass:: responder.api.RouteGroup
+    :members:
+
+
+Background Queue
+----------------
+
+Run tasks in background threads without blocking the response. Available
+as ``api.background``.
+
+.. autoclass:: responder.background.BackgroundQueue
+    :members:
+
+
+Query Dict
+----------
+
+A dictionary subclass for query string parameters with multi-value support.
+
+.. autoclass:: responder.models.QueryDict
+    :members:
+
+
+Rate Limiter
+------------
+
+In-memory token bucket rate limiter. Limits requests per client IP address
+and returns ``429 Too Many Requests`` when exceeded.
+
+.. autoclass:: responder.ext.ratelimit.RateLimiter
+    :members:
+
+
 Status Code Helpers
 -------------------
 

docs/source/index.rst

@@ -86,7 +86,7 @@ Installation
 
     $ uv pip install responder
 
-Python 3.9 and above. That's it.
+Python 3.10 and above. That's it.
 
 
 .. toctree::

pyproject.toml

@@ -12,7 +12,7 @@ license = {text = "Apache 2.0"}
 authors = [
   { name = "Kenneth Reitz", email = "me@kennethreitz.org" },
 ]
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 classifiers = [
   "Development Status :: 5 - Production/Stable",
   "Environment :: Web Environment",
@@ -21,7 +21,6 @@ classifiers = [
   "Operating System :: OS Independent",
   "Programming Language :: Python",
   "Programming Language :: Python :: 3",
-  "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
@@ -42,7 +41,7 @@ dependencies = [
   "pueblo[sfa-full]>=0.0.11",
   "pydantic>=2",
   "python-multipart",
-  "starlette[full]>=0.40",
+  "starlette[full]>=1.0",
   "uvicorn[standard]",
 ]
 

responder/__version__.py

@@ -1 +1 @@
-__version__ = "3.3.0"
+__version__ = "3.4.0"

responder/api.py

@@ -61,6 +61,31 @@ def __init__(
         lifespan=None,
         request_id=False,
     ):
+        """Create a new Responder API instance.
+
+        :param debug: If ``True``, enable debug mode with verbose error pages.
+        :param title: The title of the API, used in OpenAPI documentation.
+        :param version: The version string for the API (e.g. ``"1.0"``).
+        :param description: A longer description of the API for OpenAPI docs.
+        :param terms_of_service: URL to the API's terms of service.
+        :param contact: Contact information dict for the API (``name``, ``url``, ``email``).
+        :param license: License information dict (``name``, ``url``).
+        :param openapi: The OpenAPI version string (e.g. ``"3.0.2"``). Enables OpenAPI schema generation.
+        :param openapi_route: The URL path for the OpenAPI schema (default ``"/schema.yml"``).
+        :param static_dir: Directory for static files. Set to ``None`` to disable. Created automatically if missing.
+        :param static_route: URL prefix for serving static files (default ``"/static"``).
+        :param templates_dir: Directory for Jinja2 templates (default ``"templates"``).
+        :param auto_escape: If ``True``, auto-escape HTML/XML in templates.
+        :param secret_key: Secret key for signing cookie-based sessions. **Always set this in production.**
+        :param enable_hsts: If ``True``, redirect all HTTP requests to HTTPS.
+        :param docs_route: URL path for interactive API docs (e.g. ``"/docs"``). Enables OpenAPI if not already set.
+        :param cors: If ``True``, enable CORS middleware.
+        :param cors_params: Dict of CORS configuration (``allow_origins``, ``allow_methods``, etc.).
+        :param allowed_hosts: List of allowed hostnames (e.g. ``["example.com"]``). Defaults to ``["*"]``.
+        :param openapi_theme: Documentation UI theme: ``"swagger_ui"``, ``"redoc"``, ``"rapidoc"``, or ``"elements"``.
+        :param lifespan: An async context manager for startup/shutdown logic.
+        :param request_id: If ``True``, add ``X-Request-ID`` headers to all responses.
+        """  # noqa: E501
         self.background = BackgroundQueue()
 
         self.secret_key = secret_key
@@ -150,12 +175,30 @@ def requests(self):
 
     @property
     def static_app(self):
+        """The Starlette ``StaticFiles`` application for serving static assets."""
         if not hasattr(self, "_static_app"):
             assert self.static_dir is not None
             self._static_app = StaticFiles(directory=self.static_dir)
         return self._static_app
 
     def before_request(self, websocket=False):
+        """Register a function to run before every request.
+
+        If the hook sets ``resp.status_code``, the route handler is skipped
+        and the response is sent immediately (short-circuiting).
+
+        :param websocket: If ``True``, register as a WebSocket before-request hook instead of HTTP.
+
+        Usage::
+
+            @api.before_request()
+            def check_auth(req, resp):
+                if "Authorization" not in req.headers:
+                    resp.status_code = 401
+                    resp.media = {"error": "unauthorized"}
+
+        """  # noqa: E501
+
         def decorator(f):
             self.router.before_request(f, websocket=websocket)
             return f
@@ -180,6 +223,21 @@ def decorator(f):
         return decorator
 
     def add_middleware(self, middleware_cls, **middleware_config):
+        """Add ASGI middleware to the application.
+
+        Middleware wraps the entire application and can inspect or modify
+        every request and response. Middleware is applied in reverse order —
+        the last middleware added runs first.
+
+        :param middleware_cls: A Starlette-compatible middleware class.
+        :param middleware_config: Keyword arguments passed to the middleware constructor.
+
+        Usage::
+
+            from starlette.middleware.httpsredirect import HTTPSRedirectMiddleware
+            api.add_middleware(HTTPSRedirectMiddleware)
+
+        """
         self.app = middleware_cls(self.app, **middleware_config)
 
     def exception_handler(self, exception_cls):
@@ -501,6 +559,10 @@ def serve(self, *, address=None, port=None, debug=False, **options):
         uvicorn.run(self, host=address, port=port, **options)
 
     def run(self, **kwargs):
+        """Run the application. Shorthand for :meth:`serve` that inherits the ``debug`` setting.
+
+        :param kwargs: Keyword arguments passed through to :meth:`serve`.
+        """
         if "debug" not in kwargs:
             kwargs.update({"debug": self.debug})
         self.serve(**kwargs)

responder/background.py

@@ -9,7 +9,33 @@
 
 
 class BackgroundQueue:
+    """A queue for running tasks in background threads.
+
+    Uses a ``ThreadPoolExecutor`` sized to the number of CPUs. Access it
+    via ``api.background``.
+
+    Usage::
+
+        # As a decorator — fire and forget
+        @api.background.task
+        def send_email(to, subject):
+            ...
+
+        send_email("user@example.com", "Hello")
+
+        # Direct submission
+        future = api.background.run(send_email, "user@example.com", "Hello")
+
+        # As a callable (supports async functions)
+        await api.background(send_email, "user@example.com", "Hello")
+
+    """
+
     def __init__(self, n=None):
+        """Create a new background queue.
+
+        :param n: Number of worker threads. Defaults to CPU count.
+        """
         if n is None:
             n = multiprocessing.cpu_count()
 
@@ -18,11 +44,24 @@ def __init__(self, n=None):
         self.results = []
 
     def run(self, f, *args, **kwargs):
+        """Submit a function to run in a background thread.
+
+        :param f: The function to run.
+        :returns: A ``concurrent.futures.Future`` for the result.
+        """
         f = self.pool.submit(f, *args, **kwargs)
         self.results.append(f)
         return f
 
     def task(self, f):
+        """Decorator that wraps a function to run in the background thread pool.
+
+        The decorated function returns a ``Future`` instead of blocking.
+        Exceptions are printed to stderr via traceback.
+
+        :param f: The function to wrap.
+        """
+
         def on_future_done(fs):
             try:
                 fs.result()