Documentation issues

[MaPePeR]

I think I encountered some issues in the RabbitMQ tutorial. (I haven't tried the library yet, though)

• https://aio-pika.readthedocs.io/en/latest/rabbitmq-tutorial/1-introduction.html#hello-world

RabbitMQ libraries

RabbitMQ speaks AMQP 0.9.1, which is an open, general-purpose protocol for messaging. There are a number of clients for RabbitMQ in many different languages. In this tutorial series we’re going to use aio-pika, which is the Python client recommended by the RabbitMQ team. To install it you can use the pip package management tool.

Is that really the case? I couldn't find anything "official". They only ever mention pika on their website.

• https://aio-pika.readthedocs.io/en/latest/rabbitmq-tutorial/2-work-queues.html#preparation

  We don’t have a real-world task, like images to be resized or pdf files to be rendered, so let’s fake it by just pretending we’re busy - by using the time.sleep() function.

The time.sleep() function is not used in that section. Only much later in "Message acknowledgment" is asyncio.sleep used.

Our old receive.py script also requires some changes: it needs to fake a second of work for every dot in the message body. It will pop messages from the queue and perform the task, so let’s call it tasks_worker.py:

async def on_message(message: AbstractIncomingMessage) -> None:
    async with message.process():
        print(f" [x] Received message {message!r}")
        print(f"     Message body is: {message.body!r}")

This does not do any sleeping.

• https://aio-pika.readthedocs.io/en/latest/rabbitmq-tutorial/3-publish-subscribe.html#temporary-queues

Secondly, once we disconnect the consumer the queue should be deleted. There’s an exclusive flag for that:

queue = await channel.declare_queue(exclusive=True)

I'm not sure if aio-pika uses a different wording than pika or rabbitmq, but exclusive is not the word for "automatic deletion". I thought exclusive means, that only a single consumer can connect to a queue. There is also an auto_delete parameter, so I assume that is an error.

• Patterns and helpers

I feel like there needs to be more detailed documentation of what the patterns actually do. They are written in a way that it seems like they can only be used between two aio-pika implementations and there is no possible interoperability between other AMQP implementations possible?

From reading the documentation it feels like aio-pika is a lot more ergonomic for asynchronous usage than pika, but the fact that it is not based on the "official recommended implementation" makes it a lot harder to argue for. Can you explain, why it was not possible to keep this as a wrapper around pika and you had to go for your own implementation?

[mosquito]

Yep, most of this was left here by mistake when adapting the documentation.

You you want make PR and fix this all?

[mosquito]

As for the wrap around pika, that was originally the case, but pika itself is callback hell and when you need socket control, you can't do that.

I don't remember all the details anymore, but what is most memorable is that in the protocol the message consists of three or more frames, which have to be sent in a strictly defined order in a defined channel. That is, you can competitively send different messages in different channels, but pika does not give such control, and you had to block the whole connection for the time of sending the message.

If it makes you feel better, https://github.com/gmr/pamqp is parsing the protocol and @gmr is one of the pika contributors.

[MaPePeR]

I'm not sure if aio-pika uses a different wording than pika or rabbitmq, but exclusive is not the word for "automatic deletion". I thought exclusive means, that only a single consumer can connect to a queue. There is also an auto_delete parameter, so I assume that is an error.

Here I was wrong: exclusive is used in two contexts:

As a Queue Property, which does indead result in the described behavior:

• Exclusive (used by only one connection and the queue will be deleted when that connection closes)

And for exclusive Consumers:

When registering a consumer with an AMQP 0-9-1 client, the exclusive flag can be set to true to request the consumer to be the only one on the target queue.

I tried fixing the other things I noticed in #549.