Connexion 3 alpha release is out now! 🎉

[RobbeSneyders]

We've been working on Connexion 3 for about a year now, and we're happy to finally be able to release a first alpha release. The goal of the alpha release is to provide users the ability to test the new version and provide feedback while we further polish the codebase and update the documentation.

🛠️ Connexion 3 brings some major changes:

• Connexion can now be used as middleware to supercharge any ASGI or WSGI compatible framework.
• Aiohttp support has been dropped in favor of an ASGI compatible AsyncApp based on Starlette which is almost a drop-in replacement for the FlaskApp.
• Connexion functionality is now pluggable by adding or removing middleware.
• Validation is now pluggable by content type, solving longstanding issues regarding endpoints with multiple content types and providing the ability to plug in your own validation logic.

But these are only the highlights. There's a whole list of changes, fixes, and improvements, which you can read about in the changelog.

📃 Documentation

We still need to update the documentation for Connexion 3, but in the meantime, we've created a single page which provides high level documentation to get started with the new version here.

📣 Feedback

We would really love to hear from you. By trying Connexion 3 now and providing feedback, you get the opportunity to make sure that updating your application will be as painless as possible, while helping to create a more stable GA release.

• For questions, comments, and feedback, please use this thread
• For issues specific to the alpha version, please create a new issue and mark it with the Connexion 3 milestone
• For missing documentation, please comment on Improve and update documentation for version 3.0 #1531

[perrystallings]

Started testing the starlette app and found 2 issues:

• release is missing the asgiref dependency
• running AsyncApp still requires a flask install (is this intentional?)

[RobbeSneyders]

Thanks for the feedback @perrystallings!

• release is missing the asgiref dependency

Submitted #1667 to fix this

• running AsyncApp still requires a flask install (is this intentional?)

This is indeed not intentional, you should be able to run the AsyncApp without installing Flask. Submitted #1668 to fix this.

We'll release this as a new version asap.

[perrystallings]

Thanks!

[RobbeSneyders]

These changes have been released as 3.0.0a2.

[perrystallings]

Further exploring the AsyncApp, why does AsyncApp.middleware_app.app return a Starlette Router rather than a Starlette app? (FlaskApp.middleware_app.app returns a flask app and the old AioHttp did the same)

Context: trying to configure opentelemetry without writing custom a connexion middleware. Unfortunately this seems to require a starlette app rather than a Router

• Github: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation/opentelemetry-instrumentation-starlette
• Docs: https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/starlette/starlette.html

[RobbeSneyders]

Thanks for this! This is exactly the feedback we're looking for: real-life use cases that we need to cater to.

---

The AsyncApp is built on top of a Starlette Router because a Starlette App is a Router wrapped with a middleware stack. Which is what Connexion now is as well. It's a lot simpler to not have multiple middleware stacks wraped by each other. The default middleware stack of Starlette would also duplicate some of the behavior of Connexion (such as error handling), which we don't want to happen there.

---

I had a quick look at your links, and the good news is that the opentelemetry instrumentation also provides a generic ASGI middleware, which is exactly what Connexion 3 now enables. You should be able to plug it into the middleware stack as follows (untested):

from connexion import AsyncApp, ConnexionMiddleware
from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware

middleware_stack = ConnexionMiddleware.default_middlewares + [OpenTelemetryMiddleware]

app = AsyncApp(__name__, middlewares=middleware_stack)
app.add_api(...)

It's not completely clear yet to me what the advantage of the Starlette specific instrumentator is.

---

Note that if you want to pass arguments to middleware you add to the stack, you can use a partial.

from functools import partial

middleware = partial(OpenTelemetryMiddleware, *args, **kwargs)
middleware_stack = ConnexionMiddleware.default_middlewares + [OpenTelemetryMiddleware]

app = AsyncApp(__name__, middlewares=middleware_stack)

We currently use the same interface to specify middleware as Django, which allows a lot of flexibility. This is needed because the order of the middleware matters.

We might want to add an add_middleware() method similar to Starlette's to enable simple use cases though. This is something I would still consider for the 3.0 release.

We probably should at least expose the default_middlewares via the app directly instead of via the ConnexionMiddleware.

[perrystallings]

Thanks for the context! Just tested the configuration and it works!

[SpudInNZ]

First off, congrats to the team for getting to the 3.0.0 release.

Is there an expected migration path for 2.x projects built upon AioHttp? I'm guessing not, since AioHttp (to the best of my knowledge) is not ASGI compatioble and the team there seems to have given up on development of the 4.x branch.

Or do I have this wrong?

[RobbeSneyders]

Thanks @SpudInNZ!

As far as I'm aware, there are indeed no plans for AioHttp to support the ASGI spec, which unfortunately means connexion can no longer support it.

I see 2 possible migration paths:

• Switch to Connexion's AsyncApp. I think this should be possible if you're not heavily dependent on the AioHttp ecosystem. We're happy to help make this as painless as possible. So if you can provide feedback on the migration, we can see if there's ways for us to make this easier or at least provide documentation.
• Switch to a Connexion 2 fork such as https://github.com/athenianco/especifico by @vmarkovtsev

[SpudInNZ]

@RobbeSneyders

Thanks for the reply. In truth it's difficult for us to make the case for migration. However we may start new projects with the new stack.

[drummerwolli]

Hi @RobbeSneyders , i created an issue, but i cant tag it with the 3.0.0 milestone: #1670 ...

congratz on the release progress! looking forward!

[SpudInNZ]

According to the docs, "Connexion now exposes context, operation, receive, scope as global request-level context".
How is this exposed to an endpoint handler? I can't find anything in the example projects. For example, in the implementation of:

@StarletteDecorator()
async def get_greeting(name: str) -> str:
    return f"Hello {name}!"

.. how would I access the request headers?

Connexion 2.x app.add_api() supported the pass_context_arg_name parameter, this was extremely useful. Could this be supported in 3.x as well, passing in (presumably) a Starlette Request to api handlers? Or are we expected to use custom middleware to achieve this now?

EDIT: After some digging around I've found I can use

import typing as t
from connexion.decorators import StarletteDecorator
from connexion.context import scope, receive
import starlette.requests


@StarletteDecorator()
async def get_greeting(name: str) -> str:
    request = starlette.requests.Request(scope, receive)
    hdrs = request.headers  # for example

    return f"Hello {name}!"

Is this what I am supposed to do?

[RobbeSneyders]

We indeed still need to document this behavior. Working on the documentation as we speak 🙂

You can access all these objects in the request-level context by importing from connexion.context:

from connexion.context import context, operation, request, receive, scope

The request is also still available as

from connexion import request

but that is now a Starlette Request instead of a Flask one.

The pass_context_arg_name parameter has been removed, but the mechanism hasn't. So ou can no longer define the name, but you can still get the connexion context in your handler function via the hardcoded context_ parameter name.

def handler(context_)
    pass

I'm wondering if we still need this now that the context is available globally as well though.

[jagadeeshgarvis]

Thanks for this work! I am migrating one of our applications to connexion 3 (with starlette) from connexion 2 (with flask).

I am facing some difficulties is accessing form or files data. I am able to access query_params without any issues using connexion.requests

I am able to port almost everything except for this error in reading uploaded files as multipart form field.

await connexion.request.form() or await connexion.request.files() is making the app go into a limbo.

Even form = await connexion.request._starlette_request.form() this doesn't seems to be working

Even if I place this inside a try, catch, there are no error messages and the app isn't returning anything.

[jagadeeshgarvis]

@RobbeSneyders Not all fields are available using this method as well..

Let's say, I have my spec like this:

          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Event file to upload
                filetype:
                  type: string
                  $ref: "#/components/schemas/EventUploadType"
              required:
                - file
                - filetype

I am able to access: file but I am not able to access filetype.

Also just for context, when I am debugging, this field filetype was available in _form field of the ASGI Request till we reach this point in. code:

class AsyncParameterDecorator(BaseParameterDecorator):
    def __call__(self, function: t.Callable) -> t.Callable:
        unwrapped_function = unwrap_decorators(function)
        arguments, has_kwargs = inspect_function_arguments(unwrapped_function)

        @functools.wraps(function)
        async def wrapper(request: ASGIRequest) -> t.Any:
            request_body = self._maybe_get_body(
                request, arguments=arguments, has_kwargs=has_kwargs
            )

            while asyncio.iscoroutine(request_body):
                request_body = await request_body

            kwargs = prep_kwargs(
                request,
                request_body=request_body,
                files=await request.files(),
                arguments=arguments,
                has_kwargs=has_kwargs,
                sanitize=self.sanitize_fn,
            )

            return await function(**kwargs)

        return wrapper

Pls See the value in debugger:

But this field is not accessible in the actual post view function. I had tried passing them as arguments and also tried accessing the _form.

Anyway to overcome this?

I am also wondering if this could be related to the name of the parameter: filetype is this causing any issues?

[RobbeSneyders]

You're right. With Swagger 2, this works since form data is defined as parameters in the specification. With OpenAPI 3, form data is defined in the body, so we pass in the whole body.

This will work:

def post(file, body):
    # body = {"filetype": "..."}

But I agree that this is not very consistent. I think we should either

• Copy the Swagger behavior for OpenAPI and pass the top level fields in separately.
  (This might impact the behavior of strict_validation as well.)
• Don't pass in the files separately for OpenAPI either, and just include them in the body

I'll have to look how this was done on Connexion 2.X before deciding on how to move forward.
CC: @Ruwann

[jagadeeshgarvis]

Thanks for quick response... and helping here.... now I am able to access it from body. Posting it here so that it may help others as well.

[RobbeSneyders]

Yes that should work. Both options mentioned above will change this interface and break your code though. But I'll keep you updated here so you can change it when the fix is released.

[RobbeSneyders]

@Ruwann I checked and this is the same behavior as we had on Connexion 2 (see also #1679)

I would propose to go with a single body argument and include the files in there under there respective key. This is consistent with other content-types and we can still make this more user friendly in the future by providing parsing functionality (#1190).

[rashmi-mi]

Ran into a peculiar issue - we have 2 APIs defined in OpenAPI yml -
/exceptions/{exception-id}
/exceptions/dates

Since /exceptions/{exception-id} is defined before the /exceptions/dates API, Starlette routing picks up the first API all the time. This used to work with connexion 2.0. I am guessing the right fix is changing the order but wanted to bring it to your notice here.

[RobbeSneyders]

Yes, we are aware. This is documented in the change log as a breaking change. We'll make sure to highlight this in the routing documentation again.

[rashmi-mi]

Thanks @RobbeSneyders! Missed that one.

[rashmi-mi]

Hi @RobbeSneyders Do you think CORS support be made part of the default implementation since the order in which the middleware is inserted matters?
If CORSMiddleware is the last one added, the swagger implementation returns with a 405 for OPTIONS method. Making it the first Middleware before the default list works fine. Not sure which other middleware would interfere with the CORS Middleware.

[RobbeSneyders]

We will not make it default, since it is not always desired.

Adding middleware at specific locations will become easer with #1683 which I just opened yesterday. It adds an add_middleware interface to add middleware to the stack, which supports different logical locations.

The CORS middleware needs to be inserted before the RoutingMiddleware, so you'll be able to do:

from connexion.middleware import MiddlewarePosition

app.add_middleware(CorsMiddleware, position=MiddlewarePosition.BEFORE_ROUTING)

[rashmi-mi]

This is great, thanks @RobbeSneyders!

[RobbeSneyders]

This has been released as 3.0.0a5

[rashmi-mi]

Thanks!

[RobbeSneyders]

Latest release is 3.0.0a6 already, which contains some additional fixes related to this functionality.

[ergo]

Hi, thank you for all the hard work on Connexion. Is there a ballpark date for beta/rc?

[SpudInNZ]

It seems to have gone awfully quiet with this project, can we get an update please?

[RobbeSneyders]

Hi @SpudInNZ,
Both @Ruwann and I had less time to spend on connexion the previous weeks, but we are still moving forward (albeit slowly), which also allows for additional feedback on the Alpha release.

We are ironing out some final issues which we want to resolve (eg. #1709) and adding documentation (#1701, #1706), which unfortunately takes a bit longer than hoped.

If people want to help, they can triage issues or help write documentation (#1531)

[danderwald]

Hi,

first things first: congrats!

I was wondering if it would be possible to easily migrate to v3 and migrate flask to quart (=keep the migration fairly short but enables async coding).

According to the docs, this will not be possible, because automatic routing / parameter injection / response serialization will not be available. Can this somehow be added "manually" (without implementing it explicitly :))? or is this not foreseen?

[RobbeSneyders]

Hi @danderwald. Is there a reason for you to want to migrate to quart instead of the AsyncApp based on Starlets?

[danderwald]

Hi,

pragmatic reasons :)

• one reason is that quarts api is the same as the flask one (for example for templating / globals /events / ...), so I just would need to replace the imports
• because the API is the same, my team would not need to learn a new framework
• we would be able to use concurrency (in combination with an asgi based framework/server) without much migration effort ( => to get rid of some blocking IO by exchanging requests with httpx)

[hedleyroos]

I don't have a question but I need to congratulate you somehow! Ported a Connexion 2 application that uses Django's ORM behind the scenes in a few hours. So far everything just works.

[RobbeSneyders]

Thanks @hedleyroos! Great to hear!

Let us know if you run into any issues.

[Qreativeai]

excited for final release

[RobbeSneyders]

Connexion 3 is out now! 🎉
Any further discussion can happen on the new announcement.