rabbitmq-amqp-python-client 0.2.0__tar.gz → 0.3.0__tar.gz

rabbitmq_amqp_python_client-0.3.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: rabbitmq-amqp-python-client
+Version: 0.3.0
+Summary: Python RabbitMQ client for AMQP 1.0 protocol
+License: Apache-2.0 license
+License-File: LICENSE
+Author: RabbitMQ team
+Requires-Python: >=3.9,<4.0
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: packaging (>=23.0,<24.0)
+Requires-Dist: python-qpid-proton (>=0.39.0,<0.40.0)
+Requires-Dist: typing-extensions (>=4.13.0,<5.0.0)
+Description-Content-Type: text/markdown
+
+## RabbitMQ AMQP 1.0 Python Client
+This library is meant to be used with RabbitMQ `4.x`. Suitable for testing in pre-production environments.
+
+The client is distributed via [`PIP`](https://pypi.org/project/rabbitmq-amqp-python-client/):
+```bash
+ pip install rabbitmq-amqp-python-client
+```
+
+### Getting Started    
+
+Inside the [examples](./examples) folder you can find a set of examples that show how to use the client.
+
+
+### Documentation
+
+[Client Guide](https://www.rabbitmq.com/client-libraries/amqp-client-libraries) select the python section.
+
+
+### Build
+
+- `make rabbitmq-server`: run the RabbitMQ server in a docker container
+- `poetry build`: build the source project
+- `poetry install`: resolves and install dependencies
+- `make test`: run the tests
+
+### Note for MAC users:
+
+To run TLS you need to:
+``` bash
+- pip uninstall python-qpid-proton
+- brew install swig
+- brew install pkg-config
+- export CFLAGS="-I/usr/local/opt/openssl/include"; pip install python-qpid-proton --verbose --no-cache-dir
+```
+
+Read more about the issue [here](https://stackoverflow.com/questions/44979947/python-qpid-proton-for-mac-using-amqps)
+
+### SSL Problems in local environment
+
+If when running tests, this exceptions is raised by the proton library: `SSLUnavailable`:
+``` bash
+pip uninstall python-qpid-proton -y
+
+sudo apt-get update
+sudo apt-get install -y swig cmake build-essential libssl-dev pkg-config
+
+export PKG_CONFIG_PATH=/usr/lib/x86_64-linux-gnu/pkgconfig
+export CFLAGS="-I/usr/include/openssl"
+export LDFLAGS="-L/usr/lib/x86_64-linux-gnu"
+
+pip install "python-qpid-proton>=0.39.0,<0.40.0" --no-binary python-qpid-proton --verbose --no-cache-dir
+```
+
+### Async Interface (Experimental)
+
+The client provides an async interface via the `rabbitmq_amqp_python_client.asyncio` module. The async classes act as facades that:
+
+- Wrap the corresponding synchronous classes
+- Execute blocking operations in a thread pool executor using `run_in_executor`
+- Coordinate concurrent access using `asyncio.Lock`
+- Implement proper async context managers (`async with`) for resource management
+- Maintain API compatibility with the synchronous version
+
+**Key differences from the synchronous interface:**
+
+1. Use `AsyncEnvironment` instead of `Environment`
+2. All operations must be awaited with `await`
+3. Use `async with` for resource management (connections, publishers, consumers, management)
+4. Consumer signal handling uses `asyncio.Event` and `loop.add_signal_handler`
+
+For a complete example showing proper consumer termination and signal handling, refer to:
+
+- [examples/getting_started/getting_started_async.py](./examples/getting_started/getting_started_async.py)
+
+Additional async examples are available in the [examples](./examples) folder:
+
+- OAuth2: [examples/oauth/oAuth2_async.py](./examples/oauth/oAuth2_async.py)
+- Reconnection: [examples/reconnection/reconnection_example_async.py](./examples/reconnection/reconnection_example_async.py)
+- Streams: [examples/streams/example_with_streams_async.py](./examples/streams/example_with_streams_async.py)
+- TLS: [examples/tls/tls_example_async.py](./examples/tls/tls_example_async.py)
+
+
+

rabbitmq_amqp_python_client-0.3.0/README.md

@@ -0,0 +1,82 @@
+## RabbitMQ AMQP 1.0 Python Client
+This library is meant to be used with RabbitMQ `4.x`. Suitable for testing in pre-production environments.
+
+The client is distributed via [`PIP`](https://pypi.org/project/rabbitmq-amqp-python-client/):
+```bash
+ pip install rabbitmq-amqp-python-client
+```
+
+### Getting Started    
+
+Inside the [examples](./examples) folder you can find a set of examples that show how to use the client.
+
+
+### Documentation
+
+[Client Guide](https://www.rabbitmq.com/client-libraries/amqp-client-libraries) select the python section.
+
+
+### Build
+
+- `make rabbitmq-server`: run the RabbitMQ server in a docker container
+- `poetry build`: build the source project
+- `poetry install`: resolves and install dependencies
+- `make test`: run the tests
+
+### Note for MAC users:
+
+To run TLS you need to:
+``` bash
+- pip uninstall python-qpid-proton
+- brew install swig
+- brew install pkg-config
+- export CFLAGS="-I/usr/local/opt/openssl/include"; pip install python-qpid-proton --verbose --no-cache-dir
+```
+
+Read more about the issue [here](https://stackoverflow.com/questions/44979947/python-qpid-proton-for-mac-using-amqps)
+
+### SSL Problems in local environment
+
+If when running tests, this exceptions is raised by the proton library: `SSLUnavailable`:
+``` bash
+pip uninstall python-qpid-proton -y
+
+sudo apt-get update
+sudo apt-get install -y swig cmake build-essential libssl-dev pkg-config
+
+export PKG_CONFIG_PATH=/usr/lib/x86_64-linux-gnu/pkgconfig
+export CFLAGS="-I/usr/include/openssl"
+export LDFLAGS="-L/usr/lib/x86_64-linux-gnu"
+
+pip install "python-qpid-proton>=0.39.0,<0.40.0" --no-binary python-qpid-proton --verbose --no-cache-dir
+```
+
+### Async Interface (Experimental)
+
+The client provides an async interface via the `rabbitmq_amqp_python_client.asyncio` module. The async classes act as facades that:
+
+- Wrap the corresponding synchronous classes
+- Execute blocking operations in a thread pool executor using `run_in_executor`
+- Coordinate concurrent access using `asyncio.Lock`
+- Implement proper async context managers (`async with`) for resource management
+- Maintain API compatibility with the synchronous version
+
+**Key differences from the synchronous interface:**
+
+1. Use `AsyncEnvironment` instead of `Environment`
+2. All operations must be awaited with `await`
+3. Use `async with` for resource management (connections, publishers, consumers, management)
+4. Consumer signal handling uses `asyncio.Event` and `loop.add_signal_handler`
+
+For a complete example showing proper consumer termination and signal handling, refer to:
+
+- [examples/getting_started/getting_started_async.py](./examples/getting_started/getting_started_async.py)
+
+Additional async examples are available in the [examples](./examples) folder:
+
+- OAuth2: [examples/oauth/oAuth2_async.py](./examples/oauth/oAuth2_async.py)
+- Reconnection: [examples/reconnection/reconnection_example_async.py](./examples/reconnection/reconnection_example_async.py)
+- Streams: [examples/streams/example_with_streams_async.py](./examples/streams/example_with_streams_async.py)
+- TLS: [examples/tls/tls_example_async.py](./examples/tls/tls_example_async.py)
+
+

{rabbitmq_amqp_python_client-0.2.0 → rabbitmq_amqp_python_client-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "rabbitmq-amqp-python-client"
-version = "0.2.0"
+version = "0.3.0"
 description = "Python RabbitMQ client for AMQP 1.0 protocol"
 authors = ["RabbitMQ team"]
 license = "Apache-2.0 license"
@@ -23,7 +23,11 @@ pytest = "^8.3.4"
 black = "^24.3.0"
 python-qpid-proton = "^0.39.0"
 requests = "^2.31.0"
+pytest-asyncio = "^1.2.0"
 
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

{rabbitmq_amqp_python_client-0.2.0 → rabbitmq_amqp_python_client-0.3.0}/rabbitmq_amqp_python_client/__init__.py

@@ -2,6 +2,13 @@ from importlib import metadata
 
 from .address_helper import AddressHelper
 from .amqp_consumer_handler import AMQPMessagingHandler
+from .asyncio import (
+    AsyncConnection,
+    AsyncConsumer,
+    AsyncEnvironment,
+    AsyncManagement,
+    AsyncPublisher,
+)
 from .common import ExchangeType, QueueType
 from .connection import Connection
 from .consumer import Consumer
@@ -99,4 +106,9 @@ __all__ = [
     "RecoveryConfiguration",
     "OAuth2Options",
     "Converter",
+    "AsyncConnection",
+    "AsyncConsumer",
+    "AsyncPublisher",
+    "AsyncManagement",
+    "AsyncEnvironment",
 ]

rabbitmq_amqp_python_client-0.3.0/rabbitmq_amqp_python_client/asyncio/__init__.py

@@ -0,0 +1,13 @@
+from .connection import AsyncConnection
+from .consumer import AsyncConsumer
+from .environment import AsyncEnvironment
+from .management import AsyncManagement
+from .publisher import AsyncPublisher
+
+__all__ = [
+    "AsyncConnection",
+    "AsyncConsumer",
+    "AsyncManagement",
+    "AsyncPublisher",
+    "AsyncEnvironment",
+]

rabbitmq_amqp_python_client-0.3.0/rabbitmq_amqp_python_client/asyncio/connection.py

@@ -0,0 +1,317 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Callable, Optional, Union
+
+from ..address_helper import validate_address
+from ..connection import Connection
+from ..consumer import Consumer
+from ..entities import (
+    ConsumerOptions,
+    OAuth2Options,
+    RecoveryConfiguration,
+)
+from ..exceptions import ArgumentOutOfRangeException
+from ..management import Management
+from ..publisher import Publisher
+from ..qpid.proton._handlers import MessagingHandler
+from ..ssl_configuration import (
+    PosixSslConfigurationContext,
+    WinSslConfigurationContext,
+)
+from .consumer import AsyncConsumer
+from .management import AsyncManagement
+from .publisher import AsyncPublisher
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncConnection:
+    """
+    Asyncio-compatible facade around Connection.
+
+    This class manages the connection to RabbitMQ and provides factory methods for
+    creating publishers, consumers, and management interfaces. It supports both
+    single-node and multi-node configurations, as well as SSL/TLS connections.
+
+    Note:
+        The underlying Proton BlockingConnection is NOT thread-safe. A lock is used
+        to serialize all operations.
+
+    Attributes:
+        _connection (Connection): The underlying synchronous Connection
+        _connection_lock (asyncio.Lock): Lock for coordinating access to the shared connection
+        _async_publishers (list[AsyncPublisher]): List of active async publishers
+        _async_consumers (list[AsyncConsumer]): List of active async consumers
+        _async_managements (list[AsyncManagement]): List of active async management interfaces
+        _remove_callback (Optional[Callable[[AsyncConnection], None]]): Callback on close
+    """
+
+    def __init__(
+        self,
+        uri: Optional[str] = None,
+        uris: Optional[list[str]] = None,
+        ssl_context: Union[
+            PosixSslConfigurationContext, WinSslConfigurationContext, None
+        ] = None,
+        oauth2_options: Optional[OAuth2Options] = None,
+        recovery_configuration: RecoveryConfiguration = RecoveryConfiguration(),
+    ):
+        """
+        Initialize AsyncConnection.
+
+        Args:
+            uri: Optional single-node connection URI
+            uris: Optional multi-node connection URIs
+            ssl_context: Optional SSL/TLS configuration
+            oauth2_options: Optional OAuth2 configuration
+            recovery_configuration: Configuration for automatic recovery
+
+        Raises:
+            ValidationCodeException: If recovery configuration is invalid
+        """
+        self._connection = Connection(
+            uri=uri,
+            uris=uris,
+            ssl_context=ssl_context,
+            oauth2_options=oauth2_options,
+            recovery_configuration=recovery_configuration,
+        )
+        self._connection_lock = asyncio.Lock()
+        self._async_publishers: list[AsyncPublisher] = []
+        self._async_consumers: list[AsyncConsumer] = []
+        self._async_managements: list[AsyncManagement] = []
+        self._remove_callback: Optional[Callable[[AsyncConnection], None]] = None
+
+    async def dial(self) -> None:
+        """
+        Establish a connection to the AMQP server.
+
+        Configures SSL if specified and establishes the connection using the
+        provided URI(s). Also initializes the management interface.
+        """
+        async with self._connection_lock:
+            await asyncio.to_thread(self._connection.dial)
+
+    def _set_remove_callback(
+        self, callback: Optional[Callable[[AsyncConnection], None]]
+    ) -> None:
+        """Set callback to be called when connection is closed."""
+        self._remove_callback = callback
+
+    def _remove_publisher(self, publisher: AsyncPublisher) -> None:
+        """Remove a publisher from the active list."""
+        if publisher in self._async_publishers:
+            self._async_publishers.remove(publisher)
+
+    def _remove_consumer(self, consumer: AsyncConsumer) -> None:
+        """Remove a consumer from the active list."""
+        if consumer in self._async_consumers:
+            self._async_consumers.remove(consumer)
+
+    def _remove_management(self, management: AsyncManagement) -> None:
+        """Remove a management interface from the active list."""
+        if management in self._async_managements:
+            self._async_managements.remove(management)
+
+    async def close(self) -> None:
+        """
+        Close the connection to the AMQP 1.0 server.
+
+        Closes the underlying connection and removes it from the connection list.
+        """
+        logger.debug("Closing async connection")
+        try:
+            for async_publisher in self._async_publishers[:]:
+                await async_publisher.close()
+            for async_consumer in self._async_consumers[:]:
+                await async_consumer.close()
+            for async_management in self._async_managements[:]:
+                await async_management.close()
+
+            async with self._connection_lock:
+                await asyncio.to_thread(self._connection.close)
+        except Exception as e:
+            logger.error(f"Error closing async connections: {e}")
+            raise e
+        finally:
+            if self._remove_callback is not None:
+                self._remove_callback(self)
+
+    def _set_connection_managements(self, management: Management) -> None:
+        if len(self._connection._managements) == 0:
+            self._connection._managements = [management]
+
+    async def management(
+        self,
+    ) -> AsyncManagement:
+        """
+        Get the management interface for this connection.
+
+        Returns:
+            AsyncManagement: The management interface for performing administrative tasks
+        """
+        if len(self._async_managements) > 0:
+            return self._async_managements[0]
+
+        async_management: Optional[AsyncManagement] = None
+        async with self._connection_lock:
+            if len(self._async_managements) == 0:
+                async_management = AsyncManagement(
+                    self._connection._conn,
+                    connection_lock=self._connection_lock,
+                )
+
+                self._set_connection_managements(
+                    async_management._management
+                )  # TODO: check this
+                self._async_managements.append(async_management)
+
+                async_management._set_remove_callback(self._remove_management)
+
+        if async_management is not None:
+            await async_management.open()
+
+        return self._async_managements[0]
+
+    def _set_connection_publishers(self, publisher: Publisher) -> None:
+        """Set the list of publishers in the underlying connection."""
+        publisher._set_publishers_list(
+            [async_publisher._publisher for async_publisher in self._async_publishers]
+        )
+        self._connection._publishers.append(publisher)
+
+    async def publisher(self, destination: str = "") -> AsyncPublisher:
+        """
+        Create a new publisher instance.
+
+        Args:
+            destination: Optional default destination for published messages
+
+        Returns:
+            AsyncPublisher: A new publisher instance
+
+        Raises:
+            RuntimeError: If publisher creation fails
+            ArgumentOutOfRangeException: If destination address format is invalid
+        """
+        if destination != "":
+            if not validate_address(destination):
+                raise ArgumentOutOfRangeException(
+                    "destination address must start with /queues or /exchanges"
+                )
+
+        async with self._connection_lock:
+            async_publisher = AsyncPublisher(
+                self._connection._conn,
+                destination,
+                connection_lock=self._connection_lock,
+            )
+            await async_publisher.open()
+            if async_publisher._publisher is None:
+                raise RuntimeError("Failed to create publisher")
+            self._set_connection_publishers(
+                async_publisher._publisher
+            )  # TODO: check this
+            self._async_publishers.append(async_publisher)
+
+            async_publisher._set_remove_callback(self._remove_publisher)
+
+            return async_publisher
+
+    def _set_connection_consumers(self, consumer: Consumer) -> None:
+        """Set the list of consumers in the underlying connection."""
+        self._connection._consumers.append(consumer)
+
+    async def consumer(
+        self,
+        destination: str,
+        message_handler: Optional[MessagingHandler] = None,
+        consumer_options: Optional[ConsumerOptions] = None,
+        credit: Optional[int] = None,
+    ) -> AsyncConsumer:
+        """
+        Create a new consumer instance.
+
+        Args:
+            destination: The address to consume from
+            message_handler: Optional handler for processing messages
+            consumer_options: Optional configuration for queue consumption. Each queue has its own consumer options.
+            credit: Optional credit value for flow control
+
+        Returns:
+            AsyncConsumer: A new consumer instance
+
+        Raises:
+            RuntimeError: If consumer creation fails
+            ArgumentOutOfRangeException: If destination address format is invalid
+        """
+        if not validate_address(destination):
+            raise ArgumentOutOfRangeException(
+                "destination address must start with /queues or /exchanges"
+            )
+        if consumer_options is not None:
+            consumer_options.validate(
+                {
+                    "4.0.0": self._connection._is_server_version_gte("4.0.0"),
+                    "4.1.0": self._connection._is_server_version_gte("4.1.0"),
+                    "4.2.0": self._connection._is_server_version_gte("4.2.0"),
+                }
+            )
+
+        async with self._connection_lock:
+            async_consumer = AsyncConsumer(
+                self._connection._conn,
+                destination,
+                message_handler,  # pyright: ignore[reportArgumentType]
+                consumer_options,
+                credit,
+                connection_lock=self._connection_lock,
+            )
+            await async_consumer.open()
+            if async_consumer._consumer is None:
+                raise RuntimeError("Failed to create consumer")
+            self._set_connection_consumers(async_consumer._consumer)  # TODO: check this
+            self._async_consumers.append(async_consumer)
+
+            async_consumer._set_remove_callback(self._remove_consumer)
+
+            return async_consumer
+
+    async def refresh_token(self, token: str) -> None:
+        """
+        Refresh the oauth token
+
+        Args:
+            token: the oauth token to refresh
+
+        Raises:
+            ValidationCodeException: If oauth is not enabled
+        """
+        async with self._connection_lock:
+            await asyncio.to_thread(self._connection.refresh_token, token)
+
+    async def __aenter__(self) -> AsyncConnection:
+        """ "Async context manager entry."""
+        await self.dial()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[object],
+    ) -> None:
+        """Async context manager exit."""
+        await self.close()
+
+    @property
+    def active_producers(self) -> int:
+        """Get the number of active producers of the connection."""
+        return len(self._async_publishers)
+
+    @property
+    def active_consumers(self) -> int:
+        """Get the number of active consumers of the connection."""
+        return len(self._async_consumers)