rabbitmq-management-sdk 0.1.0__tar.gz

rabbitmq_management_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: rabbitmq-management-sdk
+Version: 0.1.0
+Summary: Python SDK for the RabbitMQ Management HTTP API to manage queues, exchanges, bindings, users, and policies.
+Keywords: rabbitmq,rabbitmq management api,rabbitmq http api,rabbitmq admin,rabbitmq management,rabbitmq provisioning
+Author: brianmori
+Author-email: brianmori <52781411+brianmori@users.noreply.github.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Systems Administration
+Requires-Dist: pydantic>=2.12.5,<3.0.0
+Requires-Dist: httpx>=0.28.1,<1.0.0
+Requires-Python: >=3.14
+Project-URL: Homepage, https://github.com/brianmori/rabbitmq-management-sdk
+Project-URL: Documentation, https://brianmori.github.io/rabbitmq-management-sdk
+Project-URL: Repository, https://github.com/brianmori/rabbitmq-management-sdk
+Project-URL: Issues, https://github.com/brianmori/rabbitmq-management-sdk/issues
+Description-Content-Type: text/markdown
+
+# rabbitmq-admin-sdk
+
+A modern, typed Python SDK for the RabbitMQ HTTP Management API.
+
+## Development setup
+
+This project uses [uv](https://docs.astral.sh/uv/) for dependency and environment management.
+
+```bash
+uv sync --group dev
+```
+
+That command creates/syncs the local environment with all development dependencies needed for linting, typing, and
+tests (for example: `ruff`, `pytest`, `mypy`, and `python-dotenv`).

rabbitmq_management_sdk-0.1.0/README.md

@@ -0,0 +1,14 @@
+# rabbitmq-admin-sdk
+
+A modern, typed Python SDK for the RabbitMQ HTTP Management API.
+
+## Development setup
+
+This project uses [uv](https://docs.astral.sh/uv/) for dependency and environment management.
+
+```bash
+uv sync --group dev
+```
+
+That command creates/syncs the local environment with all development dependencies needed for linting, typing, and
+tests (for example: `ruff`, `pytest`, `mypy`, and `python-dotenv`).

rabbitmq_management_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,121 @@
+[project]
+name = "rabbitmq-management-sdk"
+version = "0.1.0"
+description = "Python SDK for the RabbitMQ Management HTTP API to manage queues, exchanges, bindings, users, and policies."
+readme = "README.md"
+authors = [
+    { name = "brianmori", email = "52781411+brianmori@users.noreply.github.com" }
+]
+license = "Apache-2.0"
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Systems Administration",
+]
+keywords = [
+    "rabbitmq",
+    "rabbitmq management api",
+    "rabbitmq http api",
+    "rabbitmq admin",
+    "rabbitmq management",
+    "rabbitmq provisioning",
+]
+
+requires-python = ">=3.14"
+dependencies = [
+    "pydantic>=2.12.5,<3.0.0",
+    "httpx>=0.28.1,<1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/brianmori/rabbitmq-management-sdk"
+Documentation = "https://brianmori.github.io/rabbitmq-management-sdk"
+Repository = "https://github.com/brianmori/rabbitmq-management-sdk"
+Issues = "https://github.com/brianmori/rabbitmq-management-sdk/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.1,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.15.2,<1.0.0",
+    "pytest>=9.0.3,<10.0.0",
+    "pytest-cov>=7.1.0,<8.0.0",
+    "mypy>=2.1.0,<3.0.0",
+    "pip-audit>=2.10.0,<3.0.0",
+    "python-dotenv>=1.2.2,<2.0.0",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py314"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E", # pycodestyle errors
+    "W", # pycodestyle warnings
+    "F", # pyflakes
+    "I", # isort
+    "B", # flake8-bugbear
+    "C4", # flake8-comprehensions
+    "UP", # pyupgrade
+    "SIM", # flake8-simplify
+    "TCH", # flake8-type-checking  — moves pure-annotation imports into TYPE_CHECKING blocks
+    "ANN", # flake8-annotations     — enforces type hint coverage
+    "PTH", # flake8-use-pathlib     — prefers pathlib over os.path
+    "RUF", # ruff-specific rules
+    "PL", # pylint
+    "TID", # flake8-tidy-imports
+]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.isort]
+known-first-party = ["rabbitmq_management_sdk"]
+
+[tool.ruff.lint.pylint]
+max-args = 8
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.ruff.lint.flake8-type-checking]
+runtime-evaluated-base-classes = ["rabbitmq_management_sdk.domains.base.RabbitMQBase"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*" = ["PLR2004"]
+
+[tool.uv.workspace]
+members = [
+    "rabbitmq-management-sdk",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+markers = [
+    "unit: Unit tests (fast, no I/O)",
+    "integration: Integration tests with mocked HTTP (fast, no real I/O)",
+    "live: Live tests against a real RabbitMQ instance (slow, requires Docker)",
+]
+env_files = [".env"]
+addopts = "--import-mode=importlib"
+
+[tool.mypy]
+python_version = "3.14"
+strict = true
+files = ["src", "tests"]
+ignore_missing_imports = true
+plugins = ["pydantic.mypy"]

rabbitmq_management_sdk-0.1.0/src/rabbitmq_management_sdk/__init__.py

@@ -0,0 +1,44 @@
+from rabbitmq_management_sdk.client.config import Config, SSLConfig
+from rabbitmq_management_sdk.client.rabbitmq_client import RabbitMQClient
+from rabbitmq_management_sdk.exceptions import (
+    APIError,
+    BadRequestError,
+    ConflictError,
+    ConnectionError,
+    ForbiddenError,
+    MalformedResponseError,
+    MethodNotAllowedError,
+    NotFoundError,
+    PreconditionFailedError,
+    RabbitMQError,
+    ServerError,
+    ServiceUnavailableError,
+    TimeoutError,
+    TooManyRequestsError,
+    TransportError,
+    UnauthorizedError,
+    UnprocessableEntityError,
+)
+
+__all__ = [
+    "APIError",
+    "BadRequestError",
+    "Config",
+    "ConflictError",
+    "ConnectionError",
+    "ForbiddenError",
+    "MalformedResponseError",
+    "MethodNotAllowedError",
+    "NotFoundError",
+    "PreconditionFailedError",
+    "RabbitMQClient",
+    "RabbitMQError",
+    "SSLConfig",
+    "ServerError",
+    "ServiceUnavailableError",
+    "TimeoutError",
+    "TooManyRequestsError",
+    "TransportError",
+    "UnauthorizedError",
+    "UnprocessableEntityError",
+]

rabbitmq_management_sdk-0.1.0/src/rabbitmq_management_sdk/client/config.py

@@ -0,0 +1,128 @@
+import ssl
+from enum import IntEnum
+from urllib.parse import quote
+
+from pydantic import BaseModel, Field, FilePath, SecretStr, model_validator
+
+
+class SSLConfig(BaseModel):
+    """SSLContext for internal PKI or mutual TLS.
+
+    Attributes:
+        ca_bundle: Path to a custom CA bundle (.pem) for internal PKI.
+        client_cert: Tuple of (cert_path, key_path) for mTLS.
+        verify: Set to False to disable verification entirely (dev only).
+        min_version: Minimum TLS version. Defaults to TLSv1.2.
+    """
+
+    verify: bool = True
+    # FilePath validates that the file actually exists on the system
+    ca_bundle: FilePath | None = None
+    # Tuple of (cert_file, key_file)
+    client_cert: tuple[FilePath, FilePath] | None = None
+    min_version: ssl.TLSVersion = Field(
+        default=ssl.TLSVersion.TLSv1_2, description="Minimum TLS version. Defaults to TLSv1.2."
+    )
+
+
+class Config(BaseModel):
+    """Configuration for the RabbitMQ management API client.
+
+    Attributes:
+         host: Hostname or IP of the RabbitMQ node.
+         port: Management API port. Defaults to 15672 (plain).
+         username: RabbitMQ management user.
+         password: Password for the management user.
+         ssl_context: TLS settings. When None the connection uses plain HTTP.
+         virtual_host: Default virtual host for vhost-scoped API calls. Defaults to '/'.
+         version_override: Pin a specific RabbitMQ version (e.g. '4.3.0') instead of relying on automatic detection.
+    """
+
+    host: str = Field(description="Hostname or IP of the RabbitMQ node.")
+    port: int = Field(
+        default=15672,
+        gt=1024,
+        lt=65536,
+        description="Management API port. Defaults to 15672 (plain).",
+    )
+
+    username: str | None = Field(description="RabbitMQ management user.")
+    password: SecretStr | None = Field(description="Password for the management user.")
+
+    ssl_context: SSLConfig | None = Field(
+        default=None,
+        description="TLS settings. When None the connection uses plain HTTP.",
+    )
+
+    virtual_host: str = Field(
+        default="/",
+        description="Defaults to '/', the RabbitMQ built-in virtual host.",
+    )
+
+    @property
+    def virtual_host_safe(self) -> str:
+        """Return the virtual host name URL-encoded for use in API paths.
+
+        The result is percent-encoded with ``safe=""`` so that ``/`` becomes
+        ``%2F``. Managers receive this value and must NOT encode it again.
+        """
+        return quote(self.virtual_host, safe="")
+
+    strict: bool = Field(
+        default=False,
+        description="If True, all default arguments are sent explicitly to RabbitMQ. "
+        "Note: Enabling this on existing queues will cause a 406 Precondition Failed "
+        "conflict if they were originally created without explicit defaults.",
+    )
+
+    version_override: RabbitMQVersion | None = Field(
+        default=None,
+        description=(
+            "Pin a specific RabbitMQ version string (e.g. '4.3.0') instead of "
+            "relying on automatic detection. Useful when the management API is "
+            "behind a proxy that strips version headers."
+        ),
+    )
+
+    @property
+    def base_url(self) -> str:
+        """The base URL for API calls."""
+        scheme = "https" if self.ssl_context is not None else "http"
+        return f"{scheme}://{self.host}:{self.port}/api"
+
+    @model_validator(mode="after")
+    def validate_config(self) -> Config:
+        has_basic_auth = self.username is not None and self.password is not None
+        has_mtls = self.ssl_context is not None and self.ssl_context.client_cert is not None
+
+        if not (has_basic_auth or has_mtls):
+            raise ValueError("Provide either username/password or a client certificate.")
+
+        if has_basic_auth and has_mtls:
+            raise ValueError("Choose Basic Auth (username/password) or mTLS (client_cert). ")
+
+        return self
+
+
+class RabbitMQVersion(BaseModel):
+    """Semantic version of the RabbitMQ server."""
+
+    major: int
+    minor: int
+    patch: int
+
+    @classmethod
+    def parse(cls, version: str) -> RabbitMQVersion:
+        try:
+            major, minor, patch = version.split(".")
+            return cls(major=int(major), minor=int(minor), patch=int(patch))
+        except ValueError:
+            raise ValueError(f"Unrecognised RabbitMQ version string: {version!r}") from None
+
+    def __str__(self) -> str:
+        return f"{self.major}.{self.minor}.{self.patch}"
+
+
+class RabbitMQMajorVersion(IntEnum):
+    V4 = 4
+    V5 = 5

rabbitmq_management_sdk-0.1.0/src/rabbitmq_management_sdk/client/rabbitmq_client.py

@@ -0,0 +1,149 @@
+import logging
+from http import HTTPMethod
+from typing import TYPE_CHECKING
+
+from rabbitmq_management_sdk.client.config import RabbitMQMajorVersion, RabbitMQVersion
+from rabbitmq_management_sdk.client.utils import create_ssl_context
+from rabbitmq_management_sdk.domains.v4.admin.services import AdminManagerV4
+from rabbitmq_management_sdk.domains.v4.bindings.services import BindingManagerV4
+from rabbitmq_management_sdk.domains.v4.exchanges.services import ExchangeManagerV4
+from rabbitmq_management_sdk.domains.v4.queues.services import QueueManagerV4
+from rabbitmq_management_sdk.exceptions import MalformedResponseError, RabbitMQError
+from rabbitmq_management_sdk.http_adapter import HttpAdapter, HttpResponse, factory
+from rabbitmq_management_sdk.http_adapter.config import BasicAuthentication
+
+if TYPE_CHECKING:
+    import ssl
+
+    from rabbitmq_management_sdk.client.config import Config
+
+logger = logging.getLogger(__name__)
+
+
+class RabbitMQClient:
+    """Client for the RabbitMQ Management API.
+
+    Attributes:
+      _config: Configuration for the client.
+      _ha: HTTP adapter for making API requests.
+      _basic_auth: Basic authentication for API requests.
+      _version: Semantic version of the RabbitMQ server.
+    """
+
+    def __init__(self, config: Config) -> None:
+        self._config = config
+        self._ha: HttpAdapter
+        self._basic_auth: BasicAuthentication
+
+        default_headers: dict[str, str] = {}
+        ssl_context: ssl.SSLContext | None = None
+
+        if config.password and config.username:
+            self._basic_auth = BasicAuthentication(
+                username=config.username, password=config.password.get_secret_value()
+            )
+            default_headers["Authorization"] = self._basic_auth.auth_header
+
+        if config.ssl_context:
+            ssl_context = create_ssl_context(config.ssl_context)
+
+        self._ha = factory.create_adapter(
+            host=config.host, port=config.port, default_headers=default_headers, ssl_context=ssl_context
+        )
+
+        self._version: RabbitMQVersion = self._get_version()
+
+        logger.debug(
+            "RabbitMQClient initialized",
+            extra={"host": config.host, "port": config.port, "version": self._version},
+        )
+
+    def _get_version(self) -> RabbitMQVersion:
+        """
+        Retrieves the RabbitMQ version from the server.
+
+        Returns:
+            RabbitMQVersion: The semantic version of the RabbitMQ server.
+
+        Raises:
+            RabbitMQError: If there is a problem communicating with the server or parsing the version.
+        """
+
+        if self._config.version_override is not None:
+            return self._config.version_override
+
+        try:
+            hr: HttpResponse = self._ha.request(method=HTTPMethod.GET, path="/api/overview")
+            data = hr.json()
+        except RabbitMQError as e:
+            logger.error(
+                "Failed to reach RabbitMQ Management API during version detection. "
+                "Consider setting version_override in Config and/or proxy settings.",
+                extra={"host": self._config.host, "port": self._config.port},
+                exc_info=e,
+            )
+            raise
+
+        rabbitmq_version = data.get("rabbitmq_version")
+
+        if not isinstance(rabbitmq_version, str):
+            logger.error(
+                "RabbitMQ version field missing or not a string in /api/overview response. "
+                "Consider setting version_override in Config.",
+                extra={
+                    "host": self._config.host,
+                    "port": self._config.port,
+                    "rabbitmq_version": rabbitmq_version,
+                },
+            )
+            raise MalformedResponseError(
+                f"Expected a string for rabbitmq_version, got {type(rabbitmq_version).__name__}. "
+                f"Set version_override in Config to bypass detection."
+            )
+
+        try:
+            return RabbitMQVersion.parse(rabbitmq_version)
+        except ValueError as e:
+            logger.error(
+                "RabbitMQ version string could not be parsed.",
+                extra={
+                    "host": self._config.host,
+                    "port": self._config.port,
+                    "rabbitmq_version": rabbitmq_version,
+                },
+                exc_info=e,
+            )
+            raise MalformedResponseError(
+                f"Could not parse rabbitmq_version {rabbitmq_version!r}. "
+                f"Set version_override in Config to bypass detection."
+            ) from e
+
+    @property
+    def queues(self) -> QueueManagerV4:
+        if self._version.major == RabbitMQMajorVersion.V4:
+            return QueueManagerV4(
+                http_client=self._ha, vhost=self._config.virtual_host_safe, strict=self._config.strict
+            )
+        raise NotImplementedError(f"Version {self._version} not supported")
+
+    @property
+    def admin(self) -> AdminManagerV4:
+        if self._version.major == RabbitMQMajorVersion.V4:
+            return AdminManagerV4(http_client=self._ha, strict=self._config.strict)
+        raise NotImplementedError(f"Version {self._version} not supported")
+
+    @property
+    def exchanges(self) -> ExchangeManagerV4:
+        if self._version.major == RabbitMQMajorVersion.V4:
+            return ExchangeManagerV4(
+                http_client=self._ha, vhost=self._config.virtual_host_safe, strict=self._config.strict
+            )
+        raise NotImplementedError(f"Version {self._version} not supported")
+
+    @property
+    def bindings(self) -> BindingManagerV4:
+        if self._version.major == RabbitMQMajorVersion.V4:
+            return BindingManagerV4(
+                http_client=self._ha, vhost=self._config.virtual_host_safe, strict=self._config.strict
+            )
+        raise NotImplementedError(f"Version {self._version} not supported")

rabbitmq_management_sdk-0.1.0/src/rabbitmq_management_sdk/client/utils.py

@@ -0,0 +1,34 @@
+import ssl
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from rabbitmq_management_sdk.client.config import SSLConfig
+
+
+def create_ssl_context(sc: SSLConfig) -> ssl.SSLContext:
+    """Creates a SSL context for the RabbitMQ Management API.
+
+    TLS Version defaults to TLSv1.2 and hostname verification is enabled.
+
+    Args:
+        sc: SSL configuration for the client.
+
+    Returns:
+        An SSL context configured with the provided SSL settings.
+    """
+    ctx = ssl.create_default_context(
+        purpose=ssl.Purpose.SERVER_AUTH,
+        cafile=sc.ca_bundle,
+    )
+    ctx.verify_mode = ssl.CERT_REQUIRED
+    ctx.minimum_version = sc.min_version
+    ctx.check_hostname = True
+
+    if not sc.verify:
+        ctx.check_hostname = False
+        ctx.verify_mode = ssl.CERT_NONE
+
+    if sc.client_cert:
+        ctx.load_cert_chain(*sc.client_cert)
+
+    return ctx

rabbitmq_management_sdk-0.1.0/src/rabbitmq_management_sdk/domains/base.py

@@ -0,0 +1,50 @@
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+from rabbitmq_management_sdk.exceptions import MalformedResponseError
+
+if TYPE_CHECKING:
+    from rabbitmq_management_sdk.http_adapter.base import HttpResponse
+
+
+class RabbitMQBase(BaseModel):
+    model_config = ConfigDict(extra="ignore", frozen=True, populate_by_name=True, use_enum_values=True)
+
+
+def parse_one[T: RabbitMQBase](response: HttpResponse, model: type[T]) -> T:
+    """Parse a single model from an HTTP response body.
+
+    Args:
+        response: The HTTP response to parse.
+        model: The Pydantic model class to validate against.
+
+    Returns:
+        A validated model instance.
+
+    Raises:
+        MalformedResponseError: If the body cannot be decoded or does not match the schema.
+    """
+    try:
+        return model.model_validate(response.json())
+    except ValidationError as e:
+        raise MalformedResponseError(f"Response body did not match {model.__name__}") from e
+
+
+def parse_list[T: RabbitMQBase](response: HttpResponse, model: type[T]) -> list[T]:
+    """Parse a list of models from an HTTP response body.
+
+    Args:
+        response: The HTTP response to parse.
+        model: The Pydantic model class to validate each item against.
+
+    Returns:
+        A list of validated model instances.
+
+    Raises:
+        MalformedResponseError: If the body cannot be decoded or an item does not match the schema.
+    """
+    try:
+        return [model.model_validate(item) for item in response.json()]
+    except ValidationError as e:
+        raise MalformedResponseError(f"Response body did not match list[{model.__name__}]") from e

rabbitmq_management_sdk-0.1.0/src/rabbitmq_management_sdk/domains/v4/admin/schemas/vhost_request.py

@@ -0,0 +1,37 @@
+# domains/v4/vhost/schemas/vhost_request.py
+from enum import StrEnum
+from typing import Literal
+
+from pydantic import Field
+
+from rabbitmq_management_sdk.domains.base import RabbitMQBase
+
+
+class VhostLimitName(StrEnum):
+    """Valid vhost limit names accepted by the RabbitMQ Management API."""
+
+    MAX_CONNECTIONS = "max-connections"
+    MAX_QUEUES = "max-queues"
+
+
+class VhostRequest(RabbitMQBase):
+    description: str | None = None
+    tags: list[str] = Field(default_factory=list)
+    tracing: bool = False
+    default_queue_type: Literal["classic", "quorum", "stream"] = "classic"
+
+
+class VhostLimitRequest(RabbitMQBase):
+    """Payload for ``PUT /api/vhost-limits/{vhost}/{limit}``.
+
+    The vhost and limit name are part of the URL — only the value is sent
+    in the request body.
+
+    Attributes:
+        value (int): The value to be set for the specific vhost limit.
+
+    Example:
+        >>> VhostLimitRequest(value=100)
+    """
+
+    value: int = Field(ge=-1, description="Limit must be -1 (unlimited), 0 (block) or a positive integer.")

rabbitmq_management_sdk-0.1.0/src/rabbitmq_management_sdk/domains/v4/admin/schemas/vhost_response.py

@@ -0,0 +1,35 @@
+# domains/v4/vhost/schemas/vhost_response.py
+from typing import Literal
+
+from pydantic import Field
+
+from rabbitmq_management_sdk.domains.base import RabbitMQBase
+
+
+class VhostResponse(RabbitMQBase):
+    name: str
+    description: str | None = None
+    tags: list[str] = Field(default_factory=list)
+    tracing: bool
+    default_queue_type: Literal["classic", "quorum", "stream"] | None = None
+    cluster_state: dict[str, str] | None = None
+
+
+class VhostLimitValues(RabbitMQBase):
+    max_connections: int | None = Field(alias="max-connections", default=None)
+    max_queues: int | None = Field(alias="max-queues", default=None)
+
+
+class VhostLimitResponse(RabbitMQBase):
+    """A single vhost limit as returned by the Management API.
+
+    Returned by both `GET /api/vhost-limits/{vhost}` and `GET /api/vhost-limits`.
+    The `vhost` field is always present, which is useful when listing limits
+    across the entire cluster.
+
+    Example:
+        >>> {"vhost": "test", "value": {"max-connections": 3, "max-queues": 3}}
+    """
+
+    vhost: str
+    value: VhostLimitValues