Kiota = Frustration

[danielniccoli]

Every time I try and touch https://github.com/microsoftgraph/msgraph-sdk-python there is something that is broken, or missing documentation, or diffuse.

For examples,

1)
I need to send an email in MIME format. I know how to do it with an HTTP request, but the docs fail to explain how to do it with the msgraph SDK. The sample just shows the HTTP request: https://learn.microsoft.com/en-us/graph/api/user-sendmail?view=graph-rest-1.0&tabs=http#example-4-send-a-new-message-using-mime-format

2)
Sending it via JSON is documented, but wrong!

from msgraph.generated.models.send_mail_post_request_body import SendMailPostRequestBody

This throws Import "msgraph.generated.models.send_mail_post_request_body" could not be resolved! Instead, it can be found here.

from msgraph.generated.users.item.send_mail.send_mail_post_request_body import (
    SendMailPostRequestBody,
)

And because there's no proper documentation in this auto-generated crap, this can only be found by searching through the code base.

3)
And it doesn't help if neither the docs are updated, nor the issue that hasn't been touched by Microsoft since it's creation six months ago.

4)
I got some external help with the MIME problem above and it was suggested to use

request_info = client.me.send_mail.to_post_request_information()
...

However, this throws a TypeError: body cannot be null. Fact aside that null does not exist in Python, the code shows the following:

def to_post_request_information(self,body: Optional[SendMailPostRequestBody] = None, request_configuration: Optional[SendMailRequestBuilderPostRequestConfiguration] = None) -> RequestInformation:
    if not body:
        raise TypeError("body cannot be null.")
    ....

An parameter with the default value of None, annotated as optional, that is then checked if it is None and raises an error, if it is actually None. Fantastic!

5) And now that everything is auto-generated, no one seems to feel responsible to actually deliver a stable product or documentation.

[shemogumbe]

Hello @danielniccoli
Thanks for raising this, I understand this can be very frustrating when the documentation snippets look misleading.
Kindly note that the issue you have raised has been brought to our attention, and a few others here and we are working to resolve them in this PR, to be completed this week, the next run of snippet updates for the docs will have these fully resolved microsoftgraph/microsoft-graph-devx-api#2019

[baywet]

Hi @danielniccoli
Thanks for the precious feedback you've provided here. I'm going to augment Shem's answer with additional pointers. I'd like to make clear to other readers that the Microsoft Graph client development experiences involves lots of different components, kiota being one of them. While I understand the feedback has to be sent somewhere, most of that feedback is not about kiota itself.

Snippets

As Shem mentioned, we already had identified those defects internally, a PR is in the works, and once it's merged snippets will be more accurate.

mime email API

This API is challenging because it was implemented in a way that can't be expressed with OData/CSDL. As a reminder our generation pipelines follow this general process:

1. Service teams describe their APIs in CSDL.
2. CSDL gets converted to OpenAPI description.
3. SDKs are generated from the description thanks to kiota.

If we don't have / can't model the information at step 1, it's impossible to get client support at step 3.
We've had an issue tracking this for a while now, and while we're not expecting a resolution at the CSDL step, discussions about supporting OAI overlays offer a path forward and implementation is ongoing (effectively we'd had a patch document in the metadata repository, and have a step 2b which would "augment" the resulting description)

Once the metadata is in place, a final limitation of kiota itself needs to be overcome. Kiota currently doesn't support multiple request/response body format for the same operation. This is something we've been tracking and have designed for but no active work is happening right now, feedback like this helps prioritizing work.

Lack of replies to some issues

This is an ongoing staffing issue that has been made worst by recent reorganizations, you should not have to experience that. We're actively working to set up processes to help us be more efficient at replying. Feedback like this helps illustrate customers' pain and funnel things up the management chain.

Optional type with defensive statement

I think some information was lost in translation during implementation of Python generation.
If we compare with the Java equivalent the request body is clearly marked as "NonNull" and has a defensive statement.
Now, changing this for Python would not be a source breaking change since python doesn't check for those types aspect AFAIK. And it wouldn't be a runtime breaking change because of the defensive statement already in place. Let me go ahead an create a bug.

I hope this lengthy reply answers some of the frustrations you've experience, and I'd like to extend my apologies for the subpart experience. Rest assured we're working to improving things despite the limited resources.

[baywet]

#4507