Documentation: Python Server info is under Python Client

[XavierGeerinck]

Describe the issue

https://docs.dapr.io/developing-applications/sdks/python/python-client/#publish--subscribe-to-messages lists Server information under Client making it unclear what is required in the code. Personally, I believe that DaprClient and DaprServer should be entirely isolated to make it clear.

URL of the docs

https://docs.dapr.io/developing-applications/sdks/python/python-client/#publish--subscribe-to-messages

Expected content

Should be split up in Client and Server

Additional context

More specifically, examples using the below should be under Client

from dapr.clients import DaprClient

While examples using the below should be under Server

from dapr.ext.grpc import App

This is since Python does not support HTTP Server bindings for Bindings, PubSub and others. HTTP support in Python is mainly used for Actor support AFAIK

[paulyuk]

Hi @XavierGeerinck -

I agree as-is this is wrong, because we have a client page and we show server content, namely subscribing to pubsub in Flask or FastAPI.

My belief is that it's a good thing to keep client and server content together. I also believe that users commonly think first about their scenario, in their language, and then want guidance how to use it and what implementation details matter. I prefer that we do not over-index on clients and servers. That to me is an implementation detail that can come later in understanding.

scenario -> my language (and my server stack, e.g. Flask/FastAPI/Express) -> code and package instructions

Using pub-sub as an example I would expect:

Pub-sub -> Python & Flask -> "pip install __" and "copy/paste __ code"

To go down this road I propose we refactor a bit and basically flatten the SDK pages:

• Start with a language SDK, e.g. Python or Javascript
• Begin the doc with install instructions, carefully pointing out Client, Server(s), and Actors modules
• Go scenario/API by scenario/API and show the snippets.
• include a small picture like we have in core docs showing the client app, server app and sidecars so people have a mental model of the concepts
• For client snippets, be really clear you need Dapr.Client. For server snippets be really clear you need Dapr. -- keeping in mind there is not one generic server but rather a server "extension" for each framework stack, like Flask or FastAPI.
• At the end have an appendix perhaps of what SDKs have what APIs in each.

The benefits of this are:

• much faster path and less clicks from scenario to code, which I believe is key to user success
• clarity about client and server is still intact
• alignment with quickstarts which are also scenario->code
• alignment with building blocks which are scenario->code
• we can link directly to these pages from Building Blocks

What do you think about this alternative approach?

[dapr-bot]

This issue has been automatically marked as stale because it has not had activity in the last 60 days. It will be closed in the next 7 days unless it is tagged (pinned, good first issue, help wanted or triaged/resolved) or other activity occurs. Thank you for your contributions.

[berndverst]

Pointing out some outdated information here @XavierGeerinck:

We have convenience PubSub route registration and mapping in FastAPI and Flask via a decorator, same as in the gRPC library.

Additionally, the input binding decorator concept does not apply to gRPC. For input bindings routes are not defined in the application code. However, gRPC does not support custom routes - so the built in gRPC server must redirect a particular event to the correctly registered method. This concept does not apply to HTTP where every input binding sends a request to a fixed route - unless the binding yaml contains a particular route metadata. There is no way to control the route from Fast API or Flask itself.

Users wishing to receive input binding events via HTTP are advised to manually listen to OPTIONS and POST requests on these endpoints.

However, use of gRPC is the preferred method in the Python SDK.

I agree with @paulyuk that keeping things grouped by framework makes the most sense. gRPC (which should be the default if you don't know what to pick), FastAPI and Flask.

I don't have the bandwidth to restructure these docs or examples, but PRs are welcome.

[berndverst]

Wouldn't the problem be solved if the headers simply said

Publish messages (client) ** Subscribe to messages (server) **