Azure-docs: Python API Reference for SDK

[FluxReality]

It would be great to have a full API reference for the Python SDK as well. Particularly since there are differences between what's been implemented in the various SDKs

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 33af8d92-74d2-2cdd-53f9-299eca57969e
• Version Independent ID: 6029edb3-5839-c2c3-6ce0-30349eccf6b9
• Content: Understand the Azure IoT SDKs
• Content Source: articles/iot-hub/iot-hub-devguide-sdks.md
• Service: iot-hub
• GitHub Login: @dominicbetts
• Microsoft Alias: dobett

[mimckitt]

Thanks for the feedback! We are currently investigating and will update you shortly.

[asergaz]

@FluxReality I may not have understood the question well. When you search on python sdk in github , can't you find the information you need?

Thanks!

[asergaz]

Since we have not heard back from you we will now proceed to close this thread. If there are further questions regarding this matter, please tag me in your reply. We will gladly continue the discussion and we will reopen the issue.

[FluxReality]

Hi im sorry for such slow reply and that you could not understand my question mr @sergaz-msft . So i will clarify here.

In the devguide. you can see that most other SDKs such as for .NET, C, JAVA and NodeJS, there are separate "API-reference" links, but for python it says "API reference: see C API reference" and the same for iOS.

Now by the structure of this SDK, it seems that the python version is NOT a full implementation of the C-API thus making it hard to follow this documentation.

Therefore, it still would be great if it could be documented in the same way as for the .NET, C, JAVA and node SDKs.

[asergaz]

Hello @FluxReality sorry I missed your comment on a timely manner since it was already closed.

I understand your suggestion now :). I believe that Python SDK is very dependent of Azure IoT SDK C and that is why we are pointing it to C API Reference, though I will include the content author @dominicbetts to help us clarify the decision on adding the reference "API reference: see C API reference" instead of a dedicated one.

Thank you so much for your great feedback!

[yzhong94]

Hi @FluxReality , thanks for the feedback. We are definitely aware of this issue, we have been working with the doc team, but we are running into technical difficulty. Python version is a full implementation of the C-API, where are you seeing discrepancy?

[FluxReality]

Hi @yzhong94 and thanks for your reply.

It might just be me not being able to navigate or misunderstand the documentation, but if you take a class like IotHubClientand the method set_message_callback It has a few overloads that I can not find in the C-documentation.

And the naming conventions seems different, making search much harder.

[yzhong94]

Adding @pierreca

[pierreca]

@FluxReality: that's absolutely valid feedback.

The best source right now to "discover" the API is a combination of 3 things:

• the following sample has most of the API covered: https://github.com/Azure/azure-iot-sdk-python/blob/master/device/samples/iothub_client_sample.py
• Some docstrings were added to try and accomodate the docs.microsoft.com team framework limitations... which didn't work (but it's still valid): https://github.com/Azure/azure-iot-sdk-python/blob/master/device/iothub_client_python/iothub_client_python.py
• the C++ file that generates the python wrapper over the C wrapper is actually pretty readable (and is the ultimate source of truth): https://github.com/Azure/azure-iot-sdk-python/blob/master/device/iothub_client_python/src/iothub_client_python.cpp

I realize that this response is less than ideal (itborders on the unacceptable for any SDK if you ask me). So I want to provide a little bit of context about the situation we're in and how we're planning to make it better:

Stated simply, the current Python SDK, as it is, (a wrapper over the C SDK) doesn't work well enough for anyone. It's not just a docs thing (the current C wrapper form prevents the docs team from ingesting it), it's a usability problem: we only support a couple of OS configurations and have a slew of external, native dependencies that break the "batteries included" promise of python. It also suffers from many of the C SDK limitations that we shouldn't have (filesystem access, things like that)

Because of that, we are rewriting the SDK entirely in Python, with pythonic APIs, and python docstrings that the docs team will be able to ingest. This also means we are going to deprecate the current SDK and are trying to minimize the efforts around it (and that includes not publishing proper existing API docs), as we're trying to focus on the "right" fix (a whole new SDK, that works better for everyone and would be properly documented.

Again, I realize it's not a good answer, I just hope it unblocks you enough to keep going while we fix this - we're a few weeks out to have something a whole lot better.

[FluxReality]

Thank you @pierreca for your explanation.

This is actually what I did, and was eventually able to build a python-module that is working. As you point out; - the SDK is buggy, and the fact that the documentation is missing, makes it really hard to find out where the problem is. Is it wrong use of the API or the API itself to blame?

Nevertheless I appreciate the Python SDK, because Python seems like a good fit for this type of solution, with its vast selection of libraries and its easy containerization with docker. It's extremely flexible.

I will be looking forward to the release of the full Pythonic API.

[asergaz]

We will now proceed to close this thread. If there are further questions regarding this matter, please tag me in your reply. We will gladly continue the discussion and we will reopen the issue.