opsmanager 0.1.0__py3-none-any.whl

opsmanager/__init__.py

@@ -0,0 +1,67 @@
+# Copyright 2024 Frank Snow
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+MongoDB Ops Manager Python Client
+
+A production-quality Python client library for the MongoDB Ops Manager API.
+
+Example usage:
+    from opsmanager import OpsManagerClient
+
+    client = OpsManagerClient(
+        base_url="https://ops-manager.example.com",
+        public_key="your-public-key",
+        private_key="your-private-key",
+    )
+
+    # List all hosts in a project
+    hosts = client.deployments.list_hosts(project_id="your-project-id")
+
+    # Get metrics for a host
+    metrics = client.measurements.host(
+        project_id="your-project-id",
+        host_id="host-id",
+        granularity="PT1M",
+        period="P1D",
+    )
+"""
+
+__version__ = "0.1.0"
+__author__ = "Frank Snow"
+
+from opsmanager.client import OpsManagerClient
+from opsmanager.errors import (
+    OpsManagerError,
+    OpsManagerAuthenticationError,
+    OpsManagerNotFoundError,
+    OpsManagerBadRequestError,
+    OpsManagerForbiddenError,
+    OpsManagerConflictError,
+    OpsManagerServerError,
+    OpsManagerRateLimitError,
+)
+
+__all__ = [
+    "OpsManagerClient",
+    "OpsManagerError",
+    "OpsManagerAuthenticationError",
+    "OpsManagerNotFoundError",
+    "OpsManagerBadRequestError",
+    "OpsManagerForbiddenError",
+    "OpsManagerConflictError",
+    "OpsManagerServerError",
+    "OpsManagerRateLimitError",
+    "__version__",
+]

opsmanager/auth.py

@@ -0,0 +1,92 @@
+# Copyright 2024 Frank Snow
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Authentication module for MongoDB Ops Manager API.
+
+The Ops Manager API uses HTTP Digest Authentication with API key pairs.
+This module provides the authentication handler for requests.
+"""
+
+from requests.auth import HTTPDigestAuth
+from typing import Optional
+
+
+class OpsManagerAuth(HTTPDigestAuth):
+    """HTTP Digest Authentication for Ops Manager API.
+
+    Ops Manager uses HTTP Digest Authentication with a public/private API key pair.
+    The public key is used as the username and the private key as the password.
+
+    Example:
+        auth = OpsManagerAuth(
+            public_key="your-public-key",
+            private_key="your-private-key"
+        )
+
+        # Used with requests
+        response = requests.get(url, auth=auth)
+
+    Note:
+        API keys can be created at either the Organization or Project level
+        in Ops Manager. The key's permissions determine which API endpoints
+        are accessible.
+    """
+
+    def __init__(self, public_key: str, private_key: str):
+        """Initialize the authentication handler.
+
+        Args:
+            public_key: The Ops Manager API public key (used as username).
+            private_key: The Ops Manager API private key (used as password).
+        """
+        super().__init__(username=public_key, password=private_key)
+        self._public_key = public_key
+
+    @property
+    def public_key(self) -> str:
+        """Return the public key (for logging/debugging, not the private key)."""
+        return self._public_key
+
+    def __repr__(self) -> str:
+        # Mask the private key in repr for security
+        return f"OpsManagerAuth(public_key={self._public_key!r}, private_key='***')"
+
+
+def create_auth(
+    public_key: Optional[str] = None,
+    private_key: Optional[str] = None,
+) -> OpsManagerAuth:
+    """Create an authentication handler from API keys.
+
+    Args:
+        public_key: The Ops Manager API public key.
+        private_key: The Ops Manager API private key.
+
+    Returns:
+        OpsManagerAuth: Configured authentication handler.
+
+    Raises:
+        ValueError: If public_key or private_key is not provided.
+
+    Note:
+        In a future version, this could support loading keys from
+        environment variables or configuration files.
+    """
+    if not public_key:
+        raise ValueError("public_key is required")
+    if not private_key:
+        raise ValueError("private_key is required")
+
+    return OpsManagerAuth(public_key=public_key, private_key=private_key)

opsmanager/client.py

@@ -0,0 +1,206 @@
+# Copyright 2024 Frank Snow
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Main client for MongoDB Ops Manager API.
+
+This is the primary entry point for interacting with the Ops Manager API.
+"""
+
+from typing import Callable, Optional
+
+from opsmanager.auth import OpsManagerAuth
+from opsmanager.network import NetworkSession
+from opsmanager.services.organizations import OrganizationsService
+from opsmanager.services.projects import ProjectsService
+from opsmanager.services.clusters import ClustersService
+from opsmanager.services.deployments import DeploymentsService
+from opsmanager.services.measurements import MeasurementsService
+from opsmanager.services.performance_advisor import PerformanceAdvisorService
+from opsmanager.services.alerts import AlertsService
+
+
+class OpsManagerClient:
+    """Client for MongoDB Ops Manager API.
+
+    This is the main entry point for interacting with Ops Manager.
+    It provides access to all API services through properties.
+
+    Example:
+        from opsmanager import OpsManagerClient
+
+        # Create client
+        client = OpsManagerClient(
+            base_url="https://ops-manager.example.com",
+            public_key="your-public-key",
+            private_key="your-private-key",
+        )
+
+        # Use services
+        projects = client.projects.list()
+        hosts = client.deployments.list_hosts(project_id="abc123")
+        metrics = client.measurements.host(
+            project_id="abc123",
+            host_id="host123",
+            period="P1D",
+        )
+
+        # Close when done
+        client.close()
+
+        # Or use as context manager
+        with OpsManagerClient(...) as client:
+            projects = client.projects.list()
+
+    Attributes:
+        organizations: Service for managing organizations.
+        projects: Service for managing projects (groups).
+        clusters: Service for managing clusters.
+        deployments: Service for hosts, databases, and disks.
+        measurements: Service for time-series metrics.
+        performance_advisor: Service for slow query analysis and index suggestions.
+        alerts: Service for alert management.
+    """
+
+    # Default base URL for Cloud Manager (Ops Manager URL must be provided)
+    DEFAULT_BASE_URL = "https://cloud.mongodb.com"
+
+    def __init__(
+        self,
+        base_url: str,
+        public_key: str,
+        private_key: str,
+        timeout: float = 30.0,
+        rate_limit: float = 2.0,
+        retry_count: int = 3,
+        retry_backoff: float = 1.0,
+        verify_ssl: bool = True,
+        user_agent: Optional[str] = None,
+    ):
+        """Initialize the Ops Manager client.
+
+        Args:
+            base_url: Base URL for the Ops Manager instance
+                (e.g., "https://ops-manager.example.com").
+            public_key: API public key.
+            private_key: API private key.
+            timeout: Request timeout in seconds (default 30).
+            rate_limit: Maximum requests per second (default 2).
+                Set conservatively to protect production Ops Manager.
+            retry_count: Number of retries for failed requests (default 3).
+            retry_backoff: Base backoff time between retries in seconds.
+            verify_ssl: Whether to verify SSL certificates (default True).
+            user_agent: Custom User-Agent string.
+        """
+        # Create authentication handler
+        auth = OpsManagerAuth(public_key=public_key, private_key=private_key)
+
+        # Create network session with rate limiting
+        self._session = NetworkSession(
+            base_url=base_url.rstrip("/"),
+            auth=auth,
+            timeout=timeout,
+            rate_limit=rate_limit,
+            retry_count=retry_count,
+            retry_backoff=retry_backoff,
+            verify_ssl=verify_ssl,
+            user_agent=user_agent,
+        )
+
+        # Initialize services
+        self._organizations = OrganizationsService(self._session)
+        self._projects = ProjectsService(self._session)
+        self._clusters = ClustersService(self._session)
+        self._deployments = DeploymentsService(self._session)
+        self._measurements = MeasurementsService(self._session)
+        self._performance_advisor = PerformanceAdvisorService(self._session)
+        self._alerts = AlertsService(self._session)
+
+    @property
+    def organizations(self) -> OrganizationsService:
+        """Service for managing organizations."""
+        return self._organizations
+
+    @property
+    def projects(self) -> ProjectsService:
+        """Service for managing projects (groups)."""
+        return self._projects
+
+    @property
+    def clusters(self) -> ClustersService:
+        """Service for managing clusters."""
+        return self._clusters
+
+    @property
+    def deployments(self) -> DeploymentsService:
+        """Service for hosts, databases, and disks."""
+        return self._deployments
+
+    @property
+    def measurements(self) -> MeasurementsService:
+        """Service for time-series metrics."""
+        return self._measurements
+
+    @property
+    def performance_advisor(self) -> PerformanceAdvisorService:
+        """Service for slow query analysis and index suggestions."""
+        return self._performance_advisor
+
+    @property
+    def alerts(self) -> AlertsService:
+        """Service for alert management."""
+        return self._alerts
+
+    def set_rate_limit(self, rate: float) -> None:
+        """Update the rate limit for API requests.
+
+        Args:
+            rate: Maximum requests per second.
+        """
+        self._session.set_rate_limit(rate)
+
+    def on_request(self, callback: Callable) -> None:
+        """Set a callback to be invoked before each request.
+
+        Useful for logging or debugging.
+
+        Args:
+            callback: Function(method, url, kwargs) called before each request.
+        """
+        self._session.on_request(callback)
+
+    def on_response(self, callback: Callable) -> None:
+        """Set a callback to be invoked after each response.
+
+        Useful for logging or debugging.
+
+        Args:
+            callback: Function(response) called after each response.
+        """
+        self._session.on_response(callback)
+
+    def close(self) -> None:
+        """Close the client and release resources."""
+        self._session.close()
+
+    def __enter__(self) -> "OpsManagerClient":
+        """Enter context manager."""
+        return self
+
+    def __exit__(self, *args) -> None:
+        """Exit context manager."""
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"OpsManagerClient(base_url={self._session.base_url!r})"

opsmanager/errors.py

@@ -0,0 +1,332 @@
+# Copyright 2024 Frank Snow
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Exception hierarchy for MongoDB Ops Manager API client.
+
+All exceptions inherit from OpsManagerError, allowing callers to catch
+all API-related errors with a single except clause if desired.
+"""
+
+from typing import Any, Dict, Optional
+
+
+class OpsManagerError(Exception):
+    """Base exception for all Ops Manager API errors.
+
+    Attributes:
+        message: Human-readable error message.
+        status_code: HTTP status code from the API response (if applicable).
+        error_code: Ops Manager error code from the response (if applicable).
+        detail: Detailed error message from the API response.
+        response: Raw response data from the API.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        error_code: Optional[str] = None,
+        detail: Optional[str] = None,
+        response: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.error_code = error_code
+        self.detail = detail
+        self.response = response or {}
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.error_code:
+            parts.append(f"[{self.error_code}]")
+        if self.detail:
+            parts.append(f"- {self.detail}")
+        return " ".join(parts)
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"message={self.message!r}, "
+            f"status_code={self.status_code}, "
+            f"error_code={self.error_code!r})"
+        )
+
+
+class OpsManagerAuthenticationError(OpsManagerError):
+    """Authentication failed (HTTP 401).
+
+    Raised when API credentials are invalid or missing.
+    """
+
+    def __init__(
+        self,
+        message: str = "Authentication failed",
+        error_code: Optional[str] = None,
+        detail: Optional[str] = None,
+        response: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(
+            message=message,
+            status_code=401,
+            error_code=error_code,
+            detail=detail,
+            response=response,
+        )
+
+
+class OpsManagerForbiddenError(OpsManagerError):
+    """Access forbidden (HTTP 403).
+
+    Raised when the authenticated user lacks permission for the requested resource.
+    """
+
+    def __init__(
+        self,
+        message: str = "Access forbidden",
+        error_code: Optional[str] = None,
+        detail: Optional[str] = None,
+        response: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(
+            message=message,
+            status_code=403,
+            error_code=error_code,
+            detail=detail,
+            response=response,
+        )
+
+
+class OpsManagerNotFoundError(OpsManagerError):
+    """Resource not found (HTTP 404).
+
+    Raised when the requested resource does not exist.
+    """
+
+    def __init__(
+        self,
+        message: str = "Resource not found",
+        error_code: Optional[str] = None,
+        detail: Optional[str] = None,
+        response: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(
+            message=message,
+            status_code=404,
+            error_code=error_code,
+            detail=detail,
+            response=response,
+        )
+
+
+class OpsManagerBadRequestError(OpsManagerError):
+    """Bad request (HTTP 400).
+
+    Raised when the request is malformed or contains invalid parameters.
+    """
+
+    def __init__(
+        self,
+        message: str = "Bad request",
+        error_code: Optional[str] = None,
+        detail: Optional[str] = None,
+        response: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(
+            message=message,
+            status_code=400,
+            error_code=error_code,
+            detail=detail,
+            response=response,
+        )
+
+
+class OpsManagerConflictError(OpsManagerError):
+    """Conflict (HTTP 409).
+
+    Raised when the request conflicts with the current state of the resource,
+    such as attempting to create a resource that already exists.
+    """
+
+    def __init__(
+        self,
+        message: str = "Conflict",
+        error_code: Optional[str] = None,
+        detail: Optional[str] = None,
+        response: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(
+            message=message,
+            status_code=409,
+            error_code=error_code,
+            detail=detail,
+            response=response,
+        )
+
+
+class OpsManagerRateLimitError(OpsManagerError):
+    """Rate limit exceeded (HTTP 429).
+
+    Raised when too many requests have been made in a given time period.
+
+    Attributes:
+        retry_after: Seconds to wait before retrying (if provided by API).
+    """
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        error_code: Optional[str] = None,
+        detail: Optional[str] = None,
+        response: Optional[Dict[str, Any]] = None,
+        retry_after: Optional[int] = None,
+    ):
+        super().__init__(
+            message=message,
+            status_code=429,
+            error_code=error_code,
+            detail=detail,
+            response=response,
+        )
+        self.retry_after = retry_after
+
+
+class OpsManagerServerError(OpsManagerError):
+    """Server error (HTTP 5xx).
+
+    Raised when the Ops Manager server encounters an internal error.
+    """
+
+    def __init__(
+        self,
+        message: str = "Server error",
+        status_code: int = 500,
+        error_code: Optional[str] = None,
+        detail: Optional[str] = None,
+        response: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(
+            message=message,
+            status_code=status_code,
+            error_code=error_code,
+            detail=detail,
+            response=response,
+        )
+
+
+class OpsManagerTimeoutError(OpsManagerError):
+    """Request timeout.
+
+    Raised when a request to the Ops Manager API times out.
+    """
+
+    def __init__(
+        self,
+        message: str = "Request timed out",
+        detail: Optional[str] = None,
+    ):
+        super().__init__(
+            message=message,
+            detail=detail,
+        )
+
+
+class OpsManagerConnectionError(OpsManagerError):
+    """Connection error.
+
+    Raised when unable to connect to the Ops Manager API.
+    """
+
+    def __init__(
+        self,
+        message: str = "Connection failed",
+        detail: Optional[str] = None,
+    ):
+        super().__init__(
+            message=message,
+            detail=detail,
+        )
+
+
+class OpsManagerValidationError(OpsManagerError):
+    """Client-side validation error.
+
+    Raised when input validation fails before making an API request.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        field: Optional[str] = None,
+    ):
+        detail = f"Invalid value for field: {field}" if field else None
+        super().__init__(
+            message=message,
+            detail=detail,
+        )
+        self.field = field
+
+
+def raise_for_status(status_code: int, response_data: Dict[str, Any]) -> None:
+    """Raise an appropriate exception based on HTTP status code.
+
+    Args:
+        status_code: HTTP status code from the response.
+        response_data: Parsed JSON response body.
+
+    Raises:
+        OpsManagerError: Appropriate subclass based on status code.
+    """
+    if 200 <= status_code < 300:
+        return
+
+    error_code = response_data.get("errorCode")
+    detail = response_data.get("detail")
+    reason = response_data.get("reason", "")
+
+    error_classes = {
+        400: OpsManagerBadRequestError,
+        401: OpsManagerAuthenticationError,
+        403: OpsManagerForbiddenError,
+        404: OpsManagerNotFoundError,
+        409: OpsManagerConflictError,
+        429: OpsManagerRateLimitError,
+    }
+
+    if status_code in error_classes:
+        raise error_classes[status_code](
+            message=reason or error_classes[status_code].__doc__.split("\n")[0],
+            error_code=error_code,
+            detail=detail,
+            response=response_data,
+        )
+
+    if status_code >= 500:
+        raise OpsManagerServerError(
+            message=reason or "Server error",
+            status_code=status_code,
+            error_code=error_code,
+            detail=detail,
+            response=response_data,
+        )
+
+    # Generic error for unexpected status codes
+    raise OpsManagerError(
+        message=reason or f"HTTP {status_code}",
+        status_code=status_code,
+        error_code=error_code,
+        detail=detail,
+        response=response_data,
+    )