docs: ability to declare queue/exchange binding

[MagicAbdel]

Description

Hi,

I was implementing dead lettering in RabbitMQ using faststream and I had to bind an queue/exchange. It resulted in the following:

if channel := rabbit_router.broker._channel:
    queue = await channel.get_queue(QUEUE.name)
    await queue.bind(
        DEAD_LETTER_EXCHANGE.name, routing_key=QUEUE.name
    )

With this; It can now can be written in a single line as (without accessing the "private" _channel):

await rabbit_router.broker.declarer.declare_binding(QUEUE, DEAD_LETTER_EXCHANGE)

Included a unit test scenario where we declare a queue/exchange binding, making sure that single call is made to the declare_queue/declare_exchange.

There might be some improvements to this code but I believe they should be in the RabbitQueue and not in the declarer. Let me know if there is anything to change.

NOTE: while running scripts/test-cov.sh I got the following (As I didn't touch any of these I just skipped it):

FAILED tests/prometheus/confluent/test_confluent.py::TestConsume::test_concurrent_consume - assert False
FAILED tests/a_docs/nats/js/test_object.py::test_basic - AssertionError: Expected 'mock' to be called once. Called 2 times.

Fixes #NOT_APPLICABLE

Type of change

Please delete options that are not relevant.

• Documentation (typos, code examples, or any documentation updates)
• New feature (a non-breaking change that adds functionality)
• This change requires a documentation update

Checklist

• My code adheres to the style guidelines of this project (scripts/lint.sh shows no errors)
• I have conducted a self-review of my own code
• I have made the necessary changes to the documentation
• My changes do not generate any new warnings
• I have added tests to validate the effectiveness of my fix or the functionality of my new feature
• Both new and existing unit tests pass successfully on my local environment by running scripts/test-cov.sh
• I have ensured that static analysis tests are passing by running scripts/static-analysis.sh
• I have included code examples to illustrate the modifications

[Lancetnik]

Sorry, but I don't think, that the new method required

async def declare_binding(
    self,
    queue: "RabbitQueue",
    exchange: "RabbitExchange",
    routing_key: Optional[str] = None,
) -> None:
    """Declare a binding between a queue and an exchange."""
    q = await self.declare_queue(queue)
    exch = await self.declare_exchange(exchange)

    await q.bind(
        exchange=exch,
        routing_key=routing_key,
    )

Inner code looks simple enough to provide it to user as it. Probably, we can just add such example to the documentation?

[Lancetnik]

I think, we can just add the example to the doc as it

[MagicAbdel]

You're right, now that I think about it it's just syntactic sugar. I reverted changes and added the example to the doc

[Lancetnik]

@MagicAbdel thank you for the suggestion and the PR itself!

[Lancetnik]

We are using includable python files to be sure, that all code examples are runnable and correct. This reason we have a special tests for such files in tests/docs/...

It will be kind, if you add any test for you code example. I think, it should use monkeypathcing to check, that inner aio-pika method was called correctly

[MagicAbdel]

That was my bad I didn't notice there were tests for doc code snippets, that is really nice btw! I just added relevant test

[Lancetnik]

Finall, I just want to clone the repo and take a look at compiled documentation. Then I'll merge it. Thank your for the work!