[Queue] Added support for receiving one message from queue

[tasherif-msft]

Resolves #14844 and resolves #14762. Many customers have reported confusion around using receive_messages() to pop one item from the queue.
This PR adds a new API that makes it simpler for the user to pop one element.
Related issues:
#14665
#11784
#14762

[kasobol-msft]

We should also do similar thing for peek_messages for completeness.

[tasherif-msft]

We should also do similar thing for peek_messages for completeness.

The reason I did not add a peek_message()/peek_one_message() method is because I believe the reason we wanted to create a receieve_one_message is due to the fact that it returns a page iterator which is not very convenient in the case of one message and creates confusion for some customers.

However, in the case of peeking, the pre-exisitng peek_messages() is very straight forward and returns a [message(s)] depending on what the user set as max_messages. So if they simply pass max_messages=1 they would get a [message1].

[kasobol-msft]

We should also do similar thing for peek_messages for completeness.

The reason I did not add a peek_message()/peek_one_message() method is because I believe the reason we wanted to create a receieve_one_message is due to the fact that it returns a page iterator which is not very convenient in the case of one message and creates confusion for some customers.

However, in the case of peeking, the pre-exisitng peek_messages() is very straight forward and returns a [message(s)] depending on what the user set as max_messages. So if they simply pass max_messages=1 they would get a [message1].

message = client.peek_message()
if message is not None:
    do_something_with(message)
else
   do_something_else()

How would this look like with peek_messages ? What's the simplest way to do this with array as a result?
In .NET I added both peek and receive after I had to write some array checking logic 10th time and that got me frustrated :)

[tasherif-msft]

We should also do similar thing for peek_messages for completeness.

The reason I did not add a peek_message()/peek_one_message() method is because I believe the reason we wanted to create a receieve_one_message is due to the fact that it returns a page iterator which is not very convenient in the case of one message and creates confusion for some customers.
However, in the case of peeking, the pre-exisitng peek_messages() is very straight forward and returns a [message(s)] depending on what the user set as max_messages. So if they simply pass max_messages=1 they would get a [message1].

message = client.peek_message()
if message is not None:
    do_something_with(message)
else
   do_something_else()

How would this look like with peek_messages ? What's the simplest way to do this with array as a result?
In .NET I added both peek and receive after I had to write some array checking logic 10th time and that got me frustrated :)

so for your example, the current peek_messages() would do:

message = client.peek_messages(max_messages=1)
if message != []:
    do_something_with(message[0])
else:
    do_something_else()

[kasobol-msft]

We should also do similar thing for peek_messages for completeness.

The reason I did not add a peek_message()/peek_one_message() method is because I believe the reason we wanted to create a receieve_one_message is due to the fact that it returns a page iterator which is not very convenient in the case of one message and creates confusion for some customers.
However, in the case of peeking, the pre-exisitng peek_messages() is very straight forward and returns a [message(s)] depending on what the user set as max_messages. So if they simply pass max_messages=1 they would get a [message1].

message = client.peek_message()
if message is not None:
    do_something_with(message)
else
   do_something_else()

How would this look like with peek_messages ? What's the simplest way to do this with array as a result?
In .NET I added both peek and receive after I had to write some array checking logic 10th time and that got me frustrated :)

so for your example, the current peek_messages() would do:

message = client.peek_messages(max_messages=1)
if message != []:
    do_something_with(message[0])
else:
    do_something_else()

that looks good. let's leave it then until we have signal from users.