Merge branch 'main' into exception_signal

.github/workflows/pipeline.yml

@@ -0,0 +1,41 @@
+name: CI/CD pipeline
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.6, 3.7, 3.8, 3.9]
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        pip install --upgrade pip
+        pip install "tox<4" "tox-gh-actions<3" "setuptools<58" "coveralls<4"
+    - name: Test with tox
+      run: tox
+    - name: Coveralls
+      run: coveralls --service github
+      env:
+        COVERALLS_PARALLEL: true
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        COVERALLS_FLAG_NAME: test-${{ matrix.python-version }}
+
+  finish-coveralls:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+    - name: Install "coveralls<4"
+      run: pip install coveralls
+    - name: Coveralls Finished
+      run: coveralls --service github --finish
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.readthedocs.yaml

@@ -0,0 +1,12 @@
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  version: 3.7
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

ARCHITECTURE.rst

@@ -0,0 +1,74 @@
+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 (`swagger 2`_, `OpenAPI 3`_), 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/
+.. _swagger 2: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operation-object
+.. _OpenAPI 3: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#operationObject

MAINTAINERS

@@ -2,3 +2,5 @@ João Santos <[email protected]>
 Henning Jacobs <[email protected]>
 Rafael Caricio <[email protected]>
 Daniel Grossmann-Kavanagh <[email protected]>
+Ruwan Lambrichts <[email protected]>
+Robbe Sneyders <[email protected]>

README.rst

@@ -5,12 +5,12 @@ Connexion
    :alt: Join the chat at https://gitter.im/zalando/connexion
    :target: https://gitter.im/zalando/connexion?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
 
-.. image:: https://travis-ci.org/zalando/connexion.svg?branch=master
-   :target: https://travis-ci.org/zalando/connexion
-   :alt: Travis CI build status
+.. image:: https://github.com/zalando/connexion/actions/workflows/pipeline.yml/badge.svg
+   :alt: Build status
+   :target: https://github.com/zalando/connexion/actions/workflows/pipeline.yml
 
-.. image:: https://coveralls.io/repos/zalando/connexion/badge.svg?branch=master
-   :target: https://coveralls.io/r/zalando/connexion?branch=master
+.. image:: https://coveralls.io/repos/github/zalando/connexion/badge.svg?branch=main
+   :target: https://coveralls.io/github/zalando/connexion?branch=main
    :alt: Coveralls status
 
 .. image:: https://img.shields.io/pypi/v/connexion.svg
@@ -26,7 +26,7 @@ Connexion
    :alt: Python Versions
 
 .. image:: https://img.shields.io/pypi/l/connexion.svg
-   :target: https://github.com/zalando/connexion/blob/master/LICENSE
+   :target: https://github.com/zalando/connexion/blob/main/LICENSE.txt
    :alt: License
 
 Connexion is a framework that automagically handles HTTP requests based on `OpenAPI Specification`_
@@ -568,6 +568,9 @@ Contributing to Connexion/TODOs
 We welcome your ideas, issues, and pull requests. Just follow the
 usual/standard GitHub practices.
 
+You can find out more about how Connexion works and where to apply your changes by having a look
+at our `ARCHITECTURE.rst <ARCHITECTURE.rst>`_.
+
 Unless you explicitly state otherwise in advance, any non trivial
 contribution intentionally submitted for inclusion in this project by you
 to the steward of this repository (Zalando SE, Berlin) shall be under the

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
@@ -6,28 +15,21 @@
 from .apps import AbstractApp  # NOQA
 from .decorators.produces import NoContent  # NOQA
 from .exceptions import ProblemException  # NOQA
-# add operation for backwards compatability
+# add operation for backwards compatibility
 from .operations import compat
 from .problem import problem  # NOQA
 from .resolver import Resolution, Resolver, RestyResolver  # NOQA
+from .utils import not_installed_error  # NOQA
 
-full_name = '{}.operation'.format(__package__)
+full_name = f'{__package__}.operation'
 sys.modules[full_name] = sys.modules[compat.__name__]
 
 
-def not_installed_error(exc):  # pragma: no cover
-    import functools
-
-    def _required_lib(exc, *args, **kwargs):
-        raise exc
-
-    return functools.partial(_required_lib, exc)
-
-
 try:
+    from flask import request  # NOQA
+
     from .apis.flask_api import FlaskApi, context  # NOQA
     from .apps.flask_app import FlaskApp
-    from flask import request  # NOQA
 except ImportError as e:  # pragma: no cover
     _flask_not_installed_error = not_installed_error(e)
     FlaskApi = _flask_not_installed_error

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 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