Add ARCHITECTURE.rst and module docstrings

ARCHITECTURE.rst

@@ -0,0 +1,73 @@
+Architecture
+============
+
+This document describes the high-level architecture of Connexion.
+
+.. image:: docs/images/architecture.png
+  :width: 800
+  :align: center
+  :alt: Connexion architecture
+
+Apps
+----
+
+A Connexion ``App`` or application wraps a specific framework application (currently Flask or
+AioHttp) and exposes a standardized interface for users to create and configure their Connexion
+application.
+
+While a Connexion app implements the WSGI interface, it only acts ass a pass-through and doesn't
+actually intercept requests and responses. Connexion does all request and response manipulation
+by wrapping the user view function in a Connexion ``Operation``. The underlying framework
+application handles incoming requests and routes them to the correct Connexion ``Operation``.
+
+Api
+---
+
+A connexion ``API`` takes in an OpenAPI specification and translates the operations defined in it to
+a set of Connexion ``Operations``. This set of operations is implemented as a framework blueprint
+(A `Flask blueprint`_ or framework-specific equivalent), which can be registered on the framework
+application.
+
+For each operation, the ``API`` resolves the user view function to link to the operation, wraps it
+with a Connexion ``Operation`` which it configures based on the OpenAPI spec, and finally adds it as
+a route on the framework blueprint.
+
+When the ``API`` is registered on the Connexion ``APP``, the underlying framework blueprint is
+registered on the framework app.
+
+Operations
+----------
+
+A Connexion ``Operation`` implements an `OpenAPI operation`_, which describes a single API
+operation on a path. It wraps the view function linked to the operation with decorators to handle
+security, validation, serialization etc. based on the OpenAPI specification, and exposes the result
+to be registered as a route on the application.
+
+These decorators intercept incoming requests and outgoing responses of the operation and allow
+Connexion to manipulate them while leaving the routing up to the underlying framework. The split
+into separate decorators allows for a clean layered implementation of Connexion functionality.
+
+The result is equivalent to the following user code, but instead Connexion implements this
+automatically based on the OpenAPI spec.
+
+.. code-block:: python
+
+    @request_response_lifecycle
+    @secure_endpoint
+    @validate_inputs
+    @deserialize_function_inputs
+    @serialize_function_outputs
+    @validate_outputs
+    def user_provided_view_function():
+        ...
+
+
+Connexion requests and responses
+--------------------------------
+
+Connexion defines a request and response interface for internal use. The outermost decorator of
+the operation casts framework specific requests to ``ConnexionRequests`` and ``ConnexionResponses``
+to framework specific responses.
+
+.. _Flask blueprint: https://flask.palletsprojects.com/en/2.0.x/blueprints/
+.. _OpenAPI operation: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operation-object

connexion/__init__.py

@@ -1,3 +1,12 @@
+"""
+Connexion is a framework that automagically handles HTTP requests based on OpenAPI Specification
+(formerly known as Swagger Spec) of your API described in YAML format. Connexion allows you to
+write an OpenAPI specification, then maps the endpoints to your Python functions; this makes it
+unique, as many tools generate the specification based on your Python code. You can describe your
+REST API in as much detail as you want; then Connexion guarantees that it will work as you
+specified.
+"""
+
 import sys
 
 import werkzeug.exceptions as exceptions  # NOQA

connexion/__main__.py

@@ -1,3 +1,7 @@
+"""
+This module provides an entrypoint for Connexion's CLI.
+"""
+
 from connexion.cli import main  # pragma: no cover
 
 main()  # pragma: no cover

connexion/apis/__init__.py

@@ -1 +1,16 @@
+"""
+This module defines an Connexion APIs. A connexion API takes in an OpenAPI specification and
+translates the operations defined in it to a set of Connexion Operations. This set of operations
+is implemented as a framework blueprint (A Flask blueprint or framework-specific equivalent),
+which can be registered on the framework application.
+
+For each operation, the API resolves the user view function to link to the operation, wraps it
+with a Connexion Operation which it configures based on the OpenAPI spec, and finally adds it as
+a route on the framework blueprint.
+
+When the API is registered on the Connexion APP, the underlying framework blueprint is registered
+on the framework app.
+"""
+
+
 from .abstract import AbstractAPI  # NOQA

connexion/apis/abstract.py

@@ -1,3 +1,7 @@
+"""
+This module defines an AbstractAPI, which defines a standardized interface for a Connexion API.
+"""
+
 import abc
 import logging
 import pathlib

connexion/apis/aiohttp_api.py

@@ -1,3 +1,8 @@
+"""
+This module defines an AioHttp Connexion API which implements translations between AioHttp and
+Connexion requests / responses.
+"""
+
 import asyncio
 import logging
 import re

connexion/apis/flask_api.py

@@ -1,3 +1,8 @@
+"""
+This module defines a Flask Connexion API which implements translations between Flask and
+Connexion requests / responses.
+"""
+
 import logging
 import warnings
 

connexion/apis/flask_utils.py

@@ -1,3 +1,7 @@
+"""
+This module defines utility functions related to the Flask framework.
+"""
+
 import functools
 import random
 import re

connexion/apps/__init__.py

@@ -1 +1,6 @@
+"""
+This module defines Connexion applications. A Connexion App wraps a specific framework application
+and exposes a standardized interface for users to create and configure their Connexion application.
+"""
+
 from .abstract import AbstractApp  # NOQA

connexion/apps/abstract.py

@@ -1,3 +1,8 @@
+"""
+This module defines an AbstractApp, which defines a standardized user interface for a Connexion
+application.
+"""
+
 import abc
 import logging
 import pathlib

connexion/apps/aiohttp_app.py

@@ -1,3 +1,7 @@
+"""
+This module defines an AioHttpApp, a Connexion application to wrap an AioHttp application.
+"""
+
 import logging
 import os.path
 import pkgutil

connexion/apps/flask_app.py

@@ -1,3 +1,7 @@
+"""
+This module defines a FlaskApp, a Connexion application to wrap an AioHttp application.
+"""
+
 import datetime
 import logging
 import pathlib

connexion/cli.py

@@ -1,3 +1,8 @@
+"""
+This module defines a command-line interface (CLI) that runs an OpenAPI specification to be a
+starting point for developing your API with Connexion.
+"""
+
 import logging
 import sys
 from os import path

connexion/decorators/__init__.py

@@ -0,0 +1,3 @@
+"""
+This module defines decorators which Connexion uses to wrap user provided view functions.
+"""

connexion/decorators/coroutine_wrappers.py

@@ -1,3 +1,7 @@
+"""
+This module defines view function decorators specifically for coroutine operations.
+"""
+
 import asyncio
 import functools
 

connexion/decorators/decorator.py

@@ -1,3 +1,8 @@
+"""
+This module defines a BaseDecorator to wrap a user view function and a RequestResponseDecorator
+which manages the lifecycle of a request internally in Connexion.
+"""
+
 import functools
 import logging
 

connexion/decorators/metrics.py

@@ -1,3 +1,8 @@
+"""
+This module defines view function decorator to collect UWSGI metrics and expose them via an
+endpoint.
+"""
+
 import functools
 import os
 import time

connexion/decorators/parameter.py

@@ -1,3 +1,7 @@
+"""
+This module defines a decorator to convert request parameters to arguments for the view function.
+"""
+
 import functools
 import inspect
 import logging

connexion/decorators/produces.py

@@ -1,4 +1,7 @@
-# Decorators to change the return type of endpoints
+"""
+This module defines decorators to change the return type of a view function.
+"""
+
 import functools
 import logging
 

connexion/decorators/response.py

@@ -1,4 +1,7 @@
-# Decorators to change the return type of endpoints
+"""
+This module defines an view function decorator to validate its responses.
+"""
+
 import functools
 import logging
 

connexion/decorators/uri_parsing.py

@@ -1,4 +1,7 @@
-# Decorators to split query and path parameters
+"""
+This module defines view function decorators to split query and path parameters.
+"""
+
 import abc
 import functools
 import json

connexion/decorators/validation.py

@@ -1,3 +1,7 @@
+"""
+This module defines view function decorators to validate request and response parameters and bodies.
+"""
+
 import collections
 import copy
 import functools

connexion/exceptions.py

@@ -1,3 +1,7 @@
+"""
+This module defines Exception classes used by Connexion to generate a proper response.
+"""
+
 import warnings
 
 from jsonschema.exceptions import ValidationError
@@ -14,8 +18,8 @@ class ProblemException(ConnexionException):
     def __init__(self, status=400, title=None, detail=None, type=None,
                  instance=None, headers=None, ext=None):
         """
-        This exception is holds arguments that are going to be passed to the
-        `connexion.problem` function to generate a propert response.
+        This exception holds arguments that are going to be passed to the
+        `connexion.problem` function to generate a proper response.
         """
         self.status = status
         self.title = title

connexion/handlers.py

@@ -1,3 +1,7 @@
+"""
+This module defines error handlers, operations that produce proper response problems.
+"""
+
 import logging
 
 from .exceptions import AuthenticationProblem, ResolverProblem

connexion/http_facts.py

@@ -1,3 +1,7 @@
+"""
+This module contains definitions of the HTTP protocol.
+"""
+
 FORM_CONTENT_TYPES = [
     'application/x-www-form-urlencoded',
     'multipart/form-data'

connexion/json_schema.py

@@ -1,3 +1,7 @@
+"""
+Module containing all code related to json schema validation.
+"""
+
 from copy import deepcopy
 
 from jsonschema import Draft4Validator, RefResolver, _utils

connexion/jsonifier.py

@@ -1,9 +1,22 @@
+"""
+This module centralizes all functionality related to json encoding and decoding in Connexion.
+"""
+
 import datetime
 import json
 import uuid
 
 
 class JSONEncoder(json.JSONEncoder):
+    """The default Connexion JSON encoder. Handles extra types compared to the
+    built-in :class:`json.JSONEncoder`.
+
+    -   :class:`datetime.datetime` and :class:`datetime.date` are
+        serialized to :rfc:`822` strings. This is the same as the HTTP
+        date format.
+    -   :class:`uuid.UUID` is serialized to a string.
+    """
+
     def default(self, o):
         if isinstance(o, datetime.datetime):
             if o.tzinfo:
@@ -25,7 +38,7 @@ def default(self, o):
 
 class Jsonifier(object):
     """
-    Used to serialized and deserialize to/from JSon
+    Central point to serialize and deserialize to/from JSon in Connexion.
     """
     def __init__(self, json_=json, **kwargs):
         """

connexion/lifecycle.py

@@ -1,5 +1,11 @@
+"""
+This module defines interfaces for requests and responses used in Connexion for authentication,
+validation, serialization, etc.
+"""
+
 
 class ConnexionRequest(object):
+    """Connexion interface for a request."""
     def __init__(self,
                  url,
                  method,
@@ -28,6 +34,7 @@ def json(self):
 
 
 class ConnexionResponse(object):
+    """Connexion interface for a response."""
     def __init__(self,
                  status_code=200,
                  mimetype=None,

connexion/mock.py

@@ -1,3 +1,7 @@
+"""
+This module contains a mock resolver that returns mock functions for operations it cannot resolve.
+"""
+
 import functools
 import logging
 

connexion/operations/__init__.py

@@ -1,3 +1,11 @@
+"""
+This module defines Connexion Operation classes. A Connexion Operation implements an OpenAPI
+operation, which describes a single API operation on a path. It wraps the view function linked to
+the operation with decorators to handle security, validation, serialization etc. based on the
+OpenAPI specification, and exposes the result to be registered as a route on the application.
+
+"""
+
 from .abstract import AbstractOperation  # noqa
 from .openapi import OpenAPIOperation  # noqa
 from .secure import SecureOperation  # noqa

connexion/operations/abstract.py

@@ -1,3 +1,8 @@
+"""
+This module defines an AbstractOperation class which implements an abstract Operation interface
+and functionality shared between Swagger 2 and OpenAPI 3 specifications.
+"""
+
 import abc
 import logging
 

connexion/operations/compat.py

@@ -1,3 +1,5 @@
-# This is a dummy module for backwards compatability with < v2.0
+"""
+This is a dummy module for backwards compatibility with < v2.0.
+"""
 from .secure import *  # noqa
 from .swagger2 import *  # noqa

connexion/operations/openapi.py

@@ -1,3 +1,7 @@
+"""
+This module defines an OpenAPIOperation class, a Connexion operation specific for OpenAPI 3 specs.
+"""
+
 import logging
 from copy import copy, deepcopy