bleemeo 0.1.0__py3-none-any.whl

bleemeo/__init__.py

@@ -0,0 +1,59 @@
+# Copyright 2015-2024 Bleemeo
+#
+# bleemeo.com an infrastructure monitoring solution in the Cloud
+#
+# 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.
+
+from .client import Client
+from .enums import (
+    AgentType,
+    ConfigItemSource,
+    ConfigItemType,
+    DisconnectionReason,
+    GloutonDiagnostics,
+    Graph,
+    ReportIncluded,
+    ReportPeriod,
+    Status,
+    TagType,
+)
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConfigurationError,
+    ResourceNotFoundError,
+    ThrottleError,
+)
+from .resources import Resource
+
+__all__ = [
+    "Client",
+    "AgentType",
+    "ConfigItemSource",
+    "ConfigItemType",
+    "DisconnectionReason",
+    "GloutonDiagnostics",
+    "Graph",
+    "ReportIncluded",
+    "ReportPeriod",
+    "Status",
+    "TagType",
+    "APIError",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConfigurationError",
+    "ResourceNotFoundError",
+    "ThrottleError",
+    "Resource",
+]

bleemeo/_authenticator.py

@@ -0,0 +1,155 @@
+# Copyright 2015-2024 Bleemeo
+#
+# bleemeo.com an infrastructure monitoring solution in the Cloud
+#
+# 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.
+from __future__ import annotations
+
+import threading
+from urllib import parse
+
+import requests
+
+from .exceptions import APIError, AuthenticationError
+
+
+class Authenticator:
+    def __init__(
+        self,
+        api_url: str,
+        session: requests.Session,
+        oauth_id: str,
+        oauth_secret: str | None = None,
+        username: str | None = None,
+        password: str | None = None,
+        oauth_initial_refresh_token: str | None = None,
+    ):
+        self.api_url = api_url
+        self.session = session
+        self.oauth_client_id = oauth_id
+        self.oauth_client_secret = oauth_secret
+        self.username = username
+        self.password = password
+
+        self._lock = threading.Lock()
+        self._current_token: str | None = None
+        self._current_refresh: str | None = oauth_initial_refresh_token
+
+    @property
+    def tokens(self) -> tuple[str, str]:
+        with self._lock:
+            if not isinstance(self._current_token, str):
+                self.__authenticate()
+
+            return str(self._current_token), str(self._current_refresh)
+
+    def get_token(self, force_refetch: bool = False) -> str:
+        with self._lock:
+            if not self._current_token or force_refetch:
+                self.__authenticate()
+
+            return str(self._current_token)
+
+    def __authenticate(self) -> None:
+        url = parse.urljoin(self.api_url, "/o/token/")
+
+        if self._current_refresh:
+            data = {
+                "grant_type": "refresh_token",
+                "refresh_token": self._current_refresh,
+                "client_id": self.oauth_client_id,
+            }
+
+            if self.oauth_client_secret:
+                data["client_secret"] = self.oauth_client_secret
+
+            response = self.session.post(
+                url,
+                headers={
+                    "X-Requested-With": "XMLHttpRequest",
+                    "Content-Type": "application/x-www-form-urlencoded",
+                },
+                data=data,
+                timeout=10,
+            )
+            if response.status_code == 200:
+                response_data = response.json()
+                self._current_token = response_data["access_token"]
+                self._current_refresh = response_data["refresh_token"]
+
+                return
+
+            if not self.username:
+                raise AuthenticationError(
+                    "The provided initial refresh token is invalid.", response
+                )
+
+        data = {
+            "grant_type": "password",
+            "username": str(self.username),
+            "password": self.password or "",
+            "client_id": self.oauth_client_id,
+        }
+
+        if self.oauth_client_secret:
+            data["client_secret"] = self.oauth_client_secret
+
+        response = self.session.post(
+            url,
+            headers={
+                "X-Requested-With": "XMLHttpRequest",
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            data=data,
+            timeout=10,
+        )
+        if response.status_code != 200:
+            raise AuthenticationError(
+                f"Failed to retrieve OAuth, status={response.status_code}", response
+            )
+
+        response_data = response.json()
+        self._current_token = response_data["access_token"]
+        self._current_refresh = response_data["refresh_token"]
+
+    def logout(self) -> None:
+        with self._lock:
+            if not self._current_refresh:
+                return
+
+            url = parse.urljoin(self.api_url, "/o/revoke_token/")
+            data = {
+                "token": self._current_refresh,
+                "client_id": self.oauth_client_id,
+                "token_type_hint": "refresh_token",
+            }
+
+            if self.oauth_client_secret:
+                data["client_secret"] = self.oauth_client_secret
+
+            response = self.session.post(
+                url,
+                headers={
+                    "X-Requested-With": "XMLHttpRequest",
+                    "Content-type": "application/x-www-form-urlencoded",
+                },
+                data=data,
+                timeout=10,
+            )
+            if response.status_code != 200:
+                raise APIError(
+                    f"Failed to revoke token, status={response.status_code}", response
+                )
+
+            self._current_token = None
+            self._current_refresh = None

bleemeo/client.py

@@ -0,0 +1,473 @@
+# Copyright 2015-2024 Bleemeo
+#
+# bleemeo.com an infrastructure monitoring solution in the Cloud
+#
+# 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.
+from __future__ import annotations
+
+import math
+import os
+import time
+from collections.abc import Iterator, Sequence
+from datetime import datetime, timedelta
+from typing import Any
+from urllib import parse
+
+from requests import PreparedRequest, Request, Response, Session
+
+from ._authenticator import Authenticator
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConfigurationError,
+    ResourceNotFoundError,
+    ThrottleError,
+)
+from .resources import Resource
+
+
+class Client:
+    """
+    A Client is a helper to interact with the Bleemeo API,
+    providing methods to retrieve, list, create, update and delete resources.
+    """
+
+    DEFAULT_ENDPOINT = "https://api.bleemeo.com"
+    DEFAULT_OAUTH_CLIENT_ID = "1fc6de3e-8750-472e-baea-3ba22bb4eb56"
+    DEFAULT_THROTTLE_MAX_AUTO_RETRY_DELAY = 60  # seconds
+    DEFAULT_USER_AGENT = "Bleemeo Python Client"
+
+    def __init__(
+        self,
+        *,
+        api_url: str | None = None,
+        account_id: str | None = None,
+        username: str | None = None,
+        password: str | None = None,
+        oauth_client_id: str | None = None,
+        oauth_client_secret: str | None = None,
+        oauth_initial_refresh_token: str | None = None,
+        custom_headers: dict[str, Any] | None = None,
+        throttle_max_auto_retry_delay: int
+        | None = DEFAULT_THROTTLE_MAX_AUTO_RETRY_DELAY,
+        load_from_env: bool = False,
+    ):
+        """
+        The credentials (username or initial refresh token) are the only mandatory parameters.
+        They can alternatively be provided as environment variables, by setting `load_from_env` to True.
+        See the [README](https://github.com/bleemeo/bleemeo-python/#configuration) for extended details.
+
+        Args:
+            api_url (str | None): Base URL to access the Bleemeo API.
+            account_id (str | None): Your Bleemeo account ID.
+            username (str | None): Your Bleemeo username.
+            password (str | None): Your Bleemeo password.
+            oauth_client_id (str | None): Your Bleemeo OAuth client ID.
+            oauth_client_secret (str | None): Your Bleemeo OAuth client secret.
+            oauth_initial_refresh_token (str | None): An initial OAuth refresh token
+                (as an alternative to username/password credentials).
+            custom_headers (dict[str, Any]): Additional headers to pass to the Bleemeo API.
+            throttle_max_auto_retry_delay (int | None): Maximum number of seconds to wait
+                for retrying a throttled request (can be set to 0 or None not to retry at all).
+            load_from_env (bool): Whether to load environment variables as Client parameters.
+
+        Raises:
+            ConfigurationError: If neither credentials nor initial refresh token are provided.
+        """
+        if load_from_env:
+            api_url = api_url or os.environ.get("BLEEMEO_API_URL")
+            account_id = account_id or os.environ.get("BLEEMEO_ACCOUNT_ID")
+            username = username or os.environ.get("BLEEMEO_USER")
+            password = password or os.environ.get("BLEEMEO_PASSWORD")
+            oauth_client_id = oauth_client_id or os.environ.get(
+                "BLEEMEO_OAUTH_CLIENT_ID"
+            )
+            oauth_client_secret = oauth_client_secret or os.environ.get(
+                "BLEEMEO_OAUTH_CLIENT_SECRET"
+            )
+            oauth_initial_refresh_token = oauth_initial_refresh_token or os.environ.get(
+                "BLEEMEO_OAUTH_INITIAL_REFRESH_TOKEN"
+            )
+
+        if not username and not oauth_initial_refresh_token:
+            raise ConfigurationError(
+                "Either a username or an initial OAuth refresh token must be provided."
+            )
+
+        self.api_url = api_url or self.DEFAULT_ENDPOINT
+        self.username = username
+        self.password = password
+        self.oauth_client_id = oauth_client_id or self.DEFAULT_OAUTH_CLIENT_ID
+        self.oauth_client_secret = oauth_client_secret
+        self.oauth_initial_refresh_token = oauth_initial_refresh_token
+        self.throttle_max_auto_retry_delay = throttle_max_auto_retry_delay
+        self.session = Session()
+        self.session.headers = {
+            "User-Agent": self.DEFAULT_USER_AGENT,
+            "Accept": "application/json",
+        }
+
+        if account_id:
+            self.session.headers["X-Bleemeo-Account"] = account_id
+        if custom_headers:
+            self.session.headers.update(custom_headers)
+
+        self._throttle_deadline = datetime.min
+        self._authenticator = Authenticator(
+            self.api_url,
+            self.session,
+            self.oauth_client_id,
+            self.oauth_client_secret,
+            self.username,
+            self.password,
+            self.oauth_initial_refresh_token,
+        )
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.logout()
+
+    @property
+    def account_id(self) -> str | None:
+        return (
+            str(self.session.headers["X-Bleemeo-Account"])
+            if "X-Bleemeo-Account" in self.session.headers
+            else None
+        )
+
+    @account_id.setter
+    def account_id(self, account_id: str | None) -> None:
+        if account_id:
+            self.session.headers["X-Bleemeo-Account"] = account_id
+        else:
+            del self.session.headers["X-Bleemeo-Account"]
+
+    @property
+    def tokens(self) -> tuple[str, str]:
+        """tokens returns a tuple containing the current access and refresh tokens."""
+        return self._authenticator.tokens
+
+    def logout(self) -> None:
+        """logout revokes the OAuth token, preventing it from being reused."""
+        self._authenticator.logout()
+        self.session.close()
+
+    def _build_url(self, *parts: str) -> str:
+        url = self.api_url
+        for part in parts:
+            url = parse.urljoin(url, part)
+        if not url.endswith("/"):
+            url = url + "/"
+        return url
+
+    def _send(self, req: PreparedRequest, settings: Any) -> Response:
+        """_send wraps `Session.send()` to make it easily mockable."""
+        return self.session.send(req, **settings)
+
+    def _do_request(
+        self, request: Request, authenticated: bool, is_retry: bool = False
+    ) -> Response:
+        if request.headers is None:
+            request.headers = {}
+
+        if "Content-Type" not in request.headers and request.json:
+            request.headers["Content-Type"] = "application/json"
+
+        if authenticated:
+            request.headers.update(
+                {
+                    "Authorization": f"Bearer {self._authenticator.get_token(force_refetch=is_retry)}"
+                }
+            )
+
+        prep = self.session.prepare_request(request)
+        # Merge environment settings into session
+        settings = self.session.merge_environment_settings(
+            prep.url, {}, None, None, None
+        )
+
+        resp = self._send(prep, settings)
+        if resp.status_code == 401 and authenticated and not is_retry:
+            resp = self._do_request(request, authenticated=True, is_retry=True)
+
+        return resp
+
+    def _do_with_error_handling(self, authenticated: bool, req: Request) -> Response:
+        response = self._do_request(req, authenticated)
+        if response.status_code >= 400:
+            if response.status_code == 400:  # Bad Request
+                raise BadRequestError(response)
+            if response.status_code == 401:  # Unauthorized
+                raise AuthenticationError(
+                    f"Authentication failed on {req.url}", response
+                )
+            if response.status_code == 404:  # Not Found
+                raise ResourceNotFoundError(req.url, response)
+            if response.status_code == 429:  # Too Many Requests
+                throttle_error = ThrottleError(response)
+                self._throttle_deadline = throttle_error.throttle_deadline
+                raise throttle_error
+
+            raise APIError(
+                f"Request {req.method} on {req.url} failed with status {response.status_code}",
+                response,
+            )
+        return response
+
+    def do(
+        self,
+        method: str,
+        url: str,
+        authenticated: bool = True,
+        params: dict[str, Any] | None = None,
+        data: Any | None = None,
+    ) -> Response:
+        """
+        do is a lower-level method to build and execute the request according to the given parameters.
+        It raises errors depending on the received response, and handles throttled requests retry.
+
+        When possible, prefer the higher-level get, get_page, count, iterate, create, update and delete.
+
+        Args:
+            method (str): The HTTP method to execute the request as.
+            url (str): The (relative) URL on which to execute the request.
+            authenticated (bool): Whether the request should be authenticated.
+            params (dict[str, Any]): The parameters to pass to the request.
+            data (Any | None): The body of the request in case of a POST or a PATCH.
+
+        Returns:
+            Response: The response to the request.
+
+        Raises:
+            AuthenticationError: If the authentication fails.
+            ThrottleError: If too many requests are sent too close.
+            APIError: When receiving a non-successful status code not covered by the above exceptions.
+        """
+        time_to_wait = self._throttle_deadline - datetime.now()
+        if time_to_wait > timedelta(seconds=0):
+            raise ThrottleError.prevent(math.ceil(time_to_wait.total_seconds()))
+
+        req = Request(
+            method=method,
+            url=self._build_url(url),
+            json=data,
+            params=params,
+        )
+
+        try:
+            response = self._do_with_error_handling(authenticated, req)
+        except ThrottleError as throttle_error:
+            if (
+                not self.throttle_max_auto_retry_delay
+                or throttle_error.delay_seconds > self.throttle_max_auto_retry_delay
+            ):
+                raise throttle_error
+
+            time.sleep(throttle_error.delay_seconds)
+
+            response = self._do_with_error_handling(authenticated, req)
+
+        return response
+
+    def get(
+        self, resource: Resource | str, id: str, fields: Sequence[str] | None = None
+    ) -> Response:
+        """
+        get retrieves the resource with the given id with only the given fields, if any.
+
+        Args:
+            resource (Resource | str): The kind of resource to retrieve.
+            id (str): The id of the resource to retrieve.
+            fields (Sequence[str] | None, optional): Specific fields to retrieve. Defaults to None (only the default ones).
+
+        Returns:
+            Response: The response to the request.
+
+        Raises:
+            AuthenticationError: If the authentication fails.
+            ThrottleError: If too many requests are sent too close.
+            APIError: When receiving a non-successful status code not covered by the above exceptions.
+        """
+        url = parse.urljoin(
+            resource.value if isinstance(resource, Resource) else resource, id
+        )
+        params = {"fields": ",".join(fields)} if fields else None
+
+        return self.do("GET", url, params=params)
+
+    def get_page(
+        self,
+        resource: Resource | str,
+        *,
+        page: int = 1,
+        page_size: int = 25,
+        params: dict[str, Any] | None = None,
+    ) -> Response:
+        """
+        get_page retrieves a given-page-sized list of resources matching the given params at the given page.
+        To collect all the resources matching some params (i.e., instead of querying all pages one by one),
+        prefer using the `iterate()` method which is faster.
+
+        Args:
+            resource (Resource | str): The kind of resource to retrieve.
+            page (int): The number of the page to retrieve.
+            page_size (int): The size of the page to retrieve.
+            params (dict[str, Any]): The parameters the resources should match.
+
+        Returns:
+            Response: The response to the request.
+
+        Raises:
+            AuthenticationError: If the authentication fails.
+            ThrottleError: If too many requests are sent too close.
+            APIError: When receiving a non-successful status code not covered by the above exceptions.
+        """
+        url = resource.value if isinstance(resource, Resource) else resource
+        params = params.copy() if params else {}
+        params.update({"page": page, "page_size": page_size})
+
+        return self.do("GET", url, params=params)
+
+    def count(
+        self, resource: Resource | str, params: dict[str, Any] | None = None
+    ) -> int:
+        """
+        count returns the number of resources matching the given params.
+
+        Args:
+            resource (Resource | str): The kind of resource to count.
+            params (dict[str, Any]): The parameters the resources should match.
+
+        Returns:
+            Response: The response to the request.
+
+        Raises:
+            AuthenticationError: If the authentication fails.
+            ThrottleError: If too many requests are sent too close.
+            APIError: When receiving a non-successful status code not covered by the above exceptions.
+        """
+        resp = self.get_page(resource, page=1, page_size=0, params=params)
+
+        return int(resp.json()["count"])
+
+    def iterate(
+        self, resource: Resource | str, params: dict[str, Any] | None = None
+    ) -> Iterator[dict[str, Any]]:
+        """
+        iterate yields the resources of the given kind matching the given params.
+
+        Args:
+            resource (Resource | str): The kind of resource to iterate.
+            params (dict[str, Any]): The parameters the resources should match.
+
+        Raises:
+            AuthenticationError: If the authentication fails.
+            ThrottleError: If too many requests are sent too close.
+            APIError: When receiving a non-successful status code not covered by the above exceptions.
+        """
+        params = params.copy() if params else {}
+        params.update({"page_size": 2500})
+
+        next_url: str | None = self._build_url(
+            resource.value if isinstance(resource, Resource) else resource
+        )
+        while next_url is not None:
+            resp = self.do("GET", next_url, params=params)
+            data = resp.json()
+            yield from data.get("results", [])
+
+            next_url = data.get("next", None)
+            params = None  # Avoid duplicating the params, which are already given back in the next URL.
+
+    def create(
+        self, resource: Resource | str, data: Any, fields: Sequence[str] | None = None
+    ) -> Response:
+        """
+        create creates a new resource of the given kind with the given data.
+        Fields expected to be returned can be specified as varargs.
+
+        Args:
+            resource (Resource | str): The kind of resource to create.
+            data (Any): The body of the POST request.
+            fields (Sequence[str] | None): Specific fields to retrieve. Defaults to None (only the default ones).
+
+        Returns:
+            Response: The response to the request.
+
+        Raises:
+            AuthenticationError: If the authentication fails.
+            ThrottleError: If too many requests are sent too close.
+            APIError: When receiving a non-successful status code not covered by the above exceptions.
+        """
+        url = resource.value if isinstance(resource, Resource) else resource
+        params = {"fields": ",".join(fields)} if fields else None
+
+        return self.do("POST", url, data=data, params=params)
+
+    def update(
+        self,
+        resource: Resource | str,
+        id: str,
+        data: Any,
+        fields: Sequence[str] | None = None,
+    ) -> Response:
+        """
+        update updates the resource of the given kind and id with the given data.
+        Since the request is sent as a PATCH, only the fields specified in the body (data) will be updated.
+        Fields expected to be returned can be specified as varargs.
+
+        Args:
+            resource (Resource | str): The kind of resource to update.
+            id (str): The ID of the resource to update.
+            data (Any): The body of the PATCH request.
+            fields (Sequence[str] | None): Specific fields to retrieve. Defaults to None (only the default ones).
+
+        Returns:
+            Response: The response to the request.
+
+        Raises:
+            AuthenticationError: If the authentication fails.
+            ThrottleError: If too many requests are sent too close.
+            APIError: When receiving a non-successful status code not covered by the above exceptions.
+        """
+        url = parse.urljoin(
+            resource.value if isinstance(resource, Resource) else resource, id
+        )
+        params = {"fields": ",".join(fields)} if fields else None
+
+        return self.do("PATCH", url, data=data, params=params)
+
+    def delete(self, resource: Resource | str, id: str) -> Response:
+        """
+        delete deletes the resource of the given kind and id from the server.
+
+        Args:
+            resource (Resource | str): The kind of resource to delete.
+            id (str): The ID of the resource to delete.
+
+        Returns:
+            Response: The response to the request.
+
+        Raises:
+            AuthenticationError: If the authentication fails.
+            ThrottleError: If too many requests are sent too close.
+            APIError: When receiving a non-successful status code not covered by the above exceptions.
+        """
+        url = parse.urljoin(
+            resource.value if isinstance(resource, Resource) else resource, id
+        )
+
+        return self.do("DELETE", url)

bleemeo/enums.py

@@ -0,0 +1,113 @@
+# Copyright 2015-2024 Bleemeo
+#
+# bleemeo.com an infrastructure monitoring solution in the Cloud
+#
+# 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.
+
+
+class AgentType:
+    AWS_ACCOUNT = "aws_account"
+    AWS_TRUSTED_ADVISOR = "aws_trusted_advisor"
+    AWS_DYNAMODB = "aws_dynamodb"
+    AWS_EC2 = "aws_ec2"
+    AWS_ELB = "aws_elb"
+    AWS_RDS = "aws_rds"
+    AWS_S3 = "aws_s3"
+    AGENT = "agent"
+    MONITOR = "connection_check"
+    SNMP = "snmp"
+    K8S = "kubernetes"
+    VSPHERE_CLUSTER = "vsphere_cluster"
+    VSPHERE_HOST = "vsphere_host"
+    VSPHERE_VM = "vsphere_vm"
+
+
+class DisconnectionReason:
+    CLEAN_SHUTDOWN = 1
+    AGENT_TIMEOUT = 2
+    AGENT_AUTO_UPGRADE = 3
+    AGENT_UPGRADE = 4
+
+
+class GloutonDiagnostics:
+    CRASH = 0
+    ON_DEMAND = 1
+
+
+class Graph:
+    LINE = 0
+    STACK = 1
+    PIE = 2
+    GAUGE = 3
+    AVAILABILITY_TIMELINE = 4
+    NUMBER = 5
+    STATUS = 6
+    SNMP_STATUS = 7
+    TEXT = 8
+    IMAGE = 9
+    HEATMAP_STATUS = 10
+    BAR = 11
+
+
+class ReportPeriod:
+    WEEKLY = 0
+    MONTHLY = 1
+
+
+class ReportIncluded:
+    NONE = 0
+    PARTIAL = 1
+    FULL = 2
+
+
+class ConfigItemSource:
+    UNKNOWN = 0
+    DEFAULT = 1
+    FILE = 2
+    ENV = 3
+    API = 4
+
+
+class ConfigItemType:
+    ANY = 0
+    INT = 1
+    FLOAT = 2
+    BOOL = 3
+    STRING = 4
+    LIST_STR = 10
+    LIST_INT = 11
+    MAP_STR_STR = 20
+    MAP_STR_INT = 21
+    THRESHOLDS = 30
+    SERVICES = 31
+    NAME_INSTANCES = 32
+    BLACKBOX_TARGETS = 33
+    PROMETHEUS_TARGETS = 34
+    TYPE_SNMP_TARGETS = 35
+    TYPE_LOG_INPUTS = 36
+
+
+class Status:
+    OK = 0
+    WARNING = 1
+    CRITICAL = 2
+    UNKNOWN = 3
+
+
+class TagType:
+    AUTOMATIC_API = 0
+    CREATED_BY_GLOUTON = 1
+    CREATED_BY_FRONTEND = 2
+    AUTOMATIC_GLOUTON = 3
+    AUTOMATIC_API_SERVICE = 4
+    NO_TYPE = 10

bleemeo/exceptions.py

@@ -0,0 +1,97 @@
+# Copyright 2015-2024 Bleemeo
+#
+# bleemeo.com an infrastructure monitoring solution in the Cloud
+#
+# 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.
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+
+import requests
+
+
+class ConfigurationError(Exception):
+    """A ConfigurationError is raised when a misconfiguration is detected."""
+
+    pass
+
+
+class APIError(Exception):
+    """
+    An APIError is raised when the API returns a non-successful status code.
+    It serves as superclass for AuthenticationError and ThrottleError.
+    """
+
+    def __init__(self, message: str, response: requests.Response) -> None:
+        if response.status_code:
+            message = f"{response.status_code}: {message}"
+
+        super().__init__(message)
+        self.response = response
+
+
+class BadRequestError(APIError):
+    """A BadRequestError is raised when the API returns a 400 - Bad Request status code."""
+
+    def __init__(self, response: requests.Response) -> None:
+        fields = response.json()
+        message = "Bad request:\n" + "\n".join(
+            [f"- {field}: {' / '.join(errors)}" for field, errors in fields.items()]
+        )
+        super().__init__(message, response)
+        self.error_fields = fields
+
+
+class AuthenticationError(APIError):
+    """An AuthenticationError is raised when the API returns a 401 - Unauthorized status code."""
+
+    pass
+
+
+class ResourceNotFoundError(APIError):
+    """A ResourceNotFoundError is raised when the API returns a 404 - Not Found status code."""
+
+    def __init__(self, url: str, response: requests.Response) -> None:
+        super().__init__(f"Resource {url} not found", response)
+        self.url = url
+
+
+class ThrottleError(APIError):
+    """
+    A ThrottleError is raised when the API returns a 429 - Too Many Requests status code.
+    It contains the delay and the deadline until a new request can safely be sent.
+    If the error is not raised from the throttle-prevention mechanism, it also contains the API response.
+    """
+
+    def __init__(
+        self,
+        response: requests.Response | None = None,
+        delay_seconds: int | None = None,
+    ) -> None:
+        ds = 30
+        if delay_seconds is not None:
+            ds = delay_seconds
+        elif response is not None and "Retry-After":
+            ds = int(response.headers.get("Retry-After") or 30)
+
+        super().__init__(
+            f"Throttle error: request must be retried after {ds}s.",
+            response or requests.Response(),
+        )
+        self.delay_seconds = ds
+        self.throttle_deadline = datetime.now() + timedelta(seconds=ds)
+
+    @classmethod
+    def prevent(cls, delay_seconds: int) -> ThrottleError:
+        """prevent can be used to build a ThrottleError without actually sending the request to the API."""
+        return cls(response=None, delay_seconds=delay_seconds)

bleemeo/resources.py

@@ -0,0 +1,63 @@
+# Copyright 2015-2024 Bleemeo
+#
+# bleemeo.com an infrastructure monitoring solution in the Cloud
+#
+# 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.
+
+from enum import Enum
+
+
+class Resource(Enum):
+    """A Resource represents a route to a model on the Bleemeo API."""
+
+    ACCOUNT = "v1/account/"
+    ACCOUNT_CONFIG = "v1/accountconfig/"
+    AGENT_CONFIG = "v1/agentconfig/"
+    APPLICATION = "v1/application/"
+    AUDITLOG = "v1/auditlog/"
+    AGENT = "v1/agent/"
+    AGENT_FACT = "v1/agentfact/"
+    AGENT_TYPE = "v1/agenttype/"
+    AWS_INTEGRATION = "v1/awsintegration/"
+    CONTACTS_GROUP = "v1/contactsgroup/"
+    CONTAINER = "v1/container/"
+    DASHBOARD = "v1/dashboard/"
+    EVENT = "v1/event/"
+    GLOUTON_CONFIG_ITEM = "v1/gloutonconfigitem/"
+    GLOUTON_CRASH_REPORT = "v1/gloutoncrashreport/"
+    GLOUTON_DIAGNOSTIC = "v1/gloutondiagnostic/"
+    HEALTHCHECK = "v1/healthcheck/"
+    INTEGRATION = "v1/integration/"
+    INTEGRATION_TEMPLATE = "v1/integrationtemplate/"
+    LIMIT = "v1/limit/"
+    METRIC = "v1/metric/"
+    METRIC_ANNOTATION = "v1/metricannotation/"
+    METRIC_NAME = "v1/metricname/"
+    METRIC_OPERATION = "v1/metricoperation/"
+    METRIC_TEMPLATE_GROUP = "v1/metrictemplategroup/"
+    NOTIFICATION_EXECUTION = "v1/notificationexecution/"
+    NOTIFICATION_RULE = "v1/notificationrule/"
+    RECORDING_RULE = "v1/recordingrule/"
+    REPORT = "v1/report/"
+    SILENCE = "v1/silence/"
+    SILENCE_RECURRENT = "v1/silencerecurrent/"
+    SLO = "v1/slo/"
+    SERVER_GROUP = "v1/servergroup/"
+    SERVICE = "v1/service/"
+    SESSION = "v1/session/"
+    TAG = "v1/tag/"
+    USER = "v1/user/"
+    WIDGET = "v1/widget/"
+
+    def __str__(self) -> str:
+        return self.value

bleemeo-0.1.0.dist-info/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.

bleemeo-0.1.0.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.1
+Name: bleemeo
+Version: 0.1.0
+Summary: A simple Python3 client for interacting with the Bleemeo API.
+Author: Bleemeo Packaging Team
+Author-email: packaging-team@bleemeo.com
+Requires-Python: >=3.8,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: requests (>=2.32.3,<3.0.0)
+Description-Content-Type: text/markdown
+
+# Bleemeo Python [![Python 3.8 at least](https://img.shields.io/badge/python-%3E%3D3.8-blue.svg?style=flat&logo=python&logoColor=white)](https://www.python.org/downloads/release/python-380/) [![GitHub License](https://img.shields.io/github/license/bleemeo/bleemeo-python)](https://github.com/bleemeo/bleemeo-python/blob/main/LICENSE)
+
+Python library for interacting with the Bleemeo API
+
+## Requirements
+
+- Python3.8 or later
+- An account on [Bleemeo](https://bleemeo.com/)
+
+## Installation
+
+Take a look at [venv](https://docs.python.org/3/tutorial/venv.html).
+This tool provides isolated Python environments, which are more practical than installing packages system-wide.
+
+After you’ve created and activated a virtual environment, run the command:
+
+```shell
+python -m pip install --upgrade bleemeo
+```
+
+## Documentation
+
+The Python library is documented using docstring
+in [the source code](https://github.com/bleemeo/bleemeo-python/bleemeo).
+
+Some examples of library usage can be found in [examples](./examples).
+
+## Basic usage
+
+Listing the first 10 agents of your account:
+
+```python
+from bleemeo import Client, Resource, APIError
+
+
+def list_agents():
+    with Client(load_from_env=True) as client:
+        try:
+            resp_page = client.get_page(Resource.AGENT, page=1, page_size=10,
+                                        params={"active": True, "fields": "id,fqdn,display_name"})
+            for agent in resp_page.json()["results"]:
+                print(f"* Agent {agent['display_name']} (fqdn = {agent['fqdn']}, id = {agent['id']})")
+        except APIError as e:
+            print(f"API error: {e}:\n{e.response.text}")
+
+
+if __name__ == '__main__':
+    list_agents()
+```
+
+Save this file as list_agents.py.
+
+Run it with:
+
+```shell
+BLEEMEO_USER=user-email@domain.com BLEEMEO_PASSWORD=password python3 list_agents.py
+```
+
+> More examples can be found in [examples](./examples)
+
+To run an example from a clone of this repository, run the following:
+
+```shell
+BLEEMEO_USER=user-email@domain.com BLEEMEO_PASSWORD=password python3 examples/list_metrics.py
+```
+
+## Environment
+
+At least the following options should be configured (as environment variables or with options):
+
+- Credentials OR initial refresh token
+- All other configuration options are optional and could be omitted
+
+> Ways to provide those options are referenced in the [Configuration](#configuration) section.
+
+## Configuration
+
+**For environment variables to be taken into account, the parameter `load_from_env` of the `Client` constructor must be
+set to `True`.**
+
+| Property                      | Constructor parameter(s)                  | Env variable(s)                                           | Default values                                                       |
+|-------------------------------|-------------------------------------------|-----------------------------------------------------------|----------------------------------------------------------------------|
+| Credentials                   | `username` & `password`                   | `BLEEMEO_USER` & `BLEEMEO_PASSWORD`                       | None. This option is required (unless initial refresh token is used) |
+| Bleemeo account header        | `account_id`                              | `BLEEMEO_ACCOUNT_ID`                                      | The first account associated with used credentials.                  |
+| OAuth client ID/secret        | `oauth_client_id` & `oauth_client_secret` | `BLEEMEO_OAUTH_CLIENT_ID` & `BLEEMEO_OAUTH_CLIENT_SECRET` | The default SDK OAuth client ID                                      |
+| API URL                       | `api_url`                                 | `BLEEMEO_API_URL`                                         | `https://api.bleemeo.com`                                            |
+| Initial refresh token         | `oauth_initial_refresh_token`             | `BLEEMEO_OAUTH_INITIAL_REFRESH_TOKEN`                     | None. This is an alternative to username & password credentials.     |
+| Custom headers                | `custom_headers`                          | -                                                         | `{"User-Agent": "Bleemeo Python Client"}`                            |
+| Throttle max auto retry delay | `throttle_max_auto_retry_delay`           | -                                                         | 1 minute.                                                            |
+

bleemeo-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+bleemeo/__init__.py,sha256=kjg04H_Q7VdvD9ylqkbBmOEZ2-2PCgmoFTc1JBeUsUc,1447
+bleemeo/_authenticator.py,sha256=kHu-E4UWMmQD4a5yW1BYkUKUUt_4UUSNoCCKiKS53L0,5084
+bleemeo/client.py,sha256=mlg3th8Hck1HBvQD0Xb1Q3LqB8SH4d49_fpnrFaRI8s,18494
+bleemeo/enums.py,sha256=0ce-FiT6ftGx7Dj0yPrCsBG6LwISTvB_e9kOB6soEu0,2252
+bleemeo/exceptions.py,sha256=UG6sYHGM79RIrhK2pj_1SURgwZwYPizeoCYOBczwl4c,3350
+bleemeo/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bleemeo/resources.py,sha256=twkDD2WuJWuynPoXLKWjUiTBHL_DecKOlR_SxbJIL6g,2183
+bleemeo-0.1.0.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+bleemeo-0.1.0.dist-info/METADATA,sha256=qz3kPoX_bHflxi3ikyZBKypzhc5sS7VHj4qW8xn-leY,5035
+bleemeo-0.1.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+bleemeo-0.1.0.dist-info/RECORD,,

bleemeo-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.9.0
+Root-Is-Purelib: true
+Tag: py3-none-any