Azure/azure-sdk-for-python

Service Bus typings for message are a bit too condensed

richardpark-msft opened this issue · 3 comments

richardpark-msft commented
  • Package Name: azure-servicebus
  • Package Version: latest
  • Operating System: OS2/Warp
  • Python Version: 3.10

Describe the bug

The signature (in intellisense) for ServiceBusSender.send_messages looks like this, currently:

(message: MessageTypes | ServiceBusMessageBatch, *, timeout: float | None = None, **kwargs: Any) -> None

It wasn't clear to me what I could actually pass here because 'MessageTypes' isn't expandable in the intellisense tooltip. I ended up clicking through to the source code for send_messages, then once again on the Union["MessageTypes"] definition where I could see the expanded list.

It's not horrible, but I think the goal here to save me from having to do that.

Side note - doc comment mismatch

The doc comment does actually list out some of the types so I could use that. It's not super pleasant because there's no formatting in that block of text at all.

I also noticed the signatures don't quite match the doc comment:

# from the doc comment for send_messages()

:type message: Union[~azure.servicebus.ServiceBusMessage, ~azure.servicebus.ServiceBusMessageBatch,
 ~azure.servicebus.amqp.AmqpAnnotatedMessage, List[Union[~azure.servicebus.ServiceBusMessage, 
~azure.servicebus.amqp.AmqpAnnotatedMessage]]]

However, the full list has Mapping[str,Any] and an Iterable[Mapping] as well.

  MessageTypes = Union[
     Mapping[str, Any],
     ServiceBusMessage,
     AmqpAnnotatedMessage,
     Iterable[Mapping[str, Any]],
     Iterable[ServiceBusMessage],
     Iterable[AmqpAnnotatedMessage],
 ]

To Reproduce
Steps to reproduce the behavior:

  1. Use ServiceBusSender.send_messages() in VSCode

Expected behavior

Would it be possible to split the Union apart and list the individual types at the send_messages function?

If that's too many types in the signature perhaps you could group them, logically?

    IterableOfMessages = Union[
        Iterable[Mapping[str, Any]],
        Iterable[ServiceBusMessage],
        Iterable[AmqpAnnotatedMessage],
    ]

    def send_messages(
        self,
        message: Union[ServiceBusMessage, AmqpAnnotatedMessage, Mapping[str, Any] | IterableOfMessages, ServiceBusMessageBatch],

If this is unfixable that's not a huge deal. Just something I noticed when I was trying things out.

Screenshots

Additional context

github-actions commented

Thanks for the feedback! We are routing this to the appropriate team for follow-up. cc @EldertGrootenboer.

kashifkhan commented

Thank you for the feedback @richardpark-msft . We will investigate and get back to you asap.

richardpark-msft commented

(it looks like this technique is used in Event Grid too, so I suppose the overall issue is really about the pattern itself)