# patroni.scripts.barman.utils module

Utilitary stuff to be used by Barman related scripts.

exception patroni.scripts.barman.utils.ApiNotOk

  Bases: `Exception`

  The `pg-backup-api` is not currently up and running.

class patroni.scripts.barman.utils.OperationStatus(*values)

  Bases: `IntEnum`

  Possible status of `pg-backup-api` operations.

  Variables:

    - IN_PROGRESS – the operation is still ongoing.

    - FAILED – the operation failed.

    - DONE – the operation finished successfully.

  DONE = 2
  FAILED = 1
  IN_PROGRESS = 0

class patroni.scripts.barman.utils.PgBackupApi(api_url: str, cert_file: str | None, key_file: str | None, retry_wait: int, max_retries: int)

  Bases: `object`

  Facilities for communicating with the `pg-backup-api`.

  Variables:

    - api_url – base URL to reach the `pg-backup-api`.

    - cert_file – certificate to authenticate against the `pg-backup-api`, if required.

    - key_file – certificate key to authenticate against the `pg-backup-api`, if required.

    - retry_wait – how long in seconds to wait before retrying a failed request to the `pg-backup-api`.

    - max_retries – maximum number of retries when `pg-backup-api` returns malformed responses.

    - http – a HTTP pool manager for performing web requests.

  __init__(api_url: str, cert_file: str | None, key_file: str | None, retry_wait: int, max_retries: int) → None

    Create a new instance of `BarmanRecover`.

    Make sure the `pg-backup-api` is reachable and running fine.

    Note

    When using any method which send requests to the API, be aware that they might raise `RetriesExceeded` upon HTTP request errors.

    Similarly, when instantiating this class you may face an `ApiNotOk`, if the API is down or returns a bogus status.

    Parameters:

      - api_url – base URL to reach the `pg-backup-api`.

      - cert_file – certificate to authenticate against the `pg-backup-api`, if required.

      - key_file – certificate key to authenticate against the `pg-backup-api`, if required.

      - retry_wait – how long in seconds to wait before retrying a failed request to the `pg-backup-api`.

      - max_retries – maximum number of retries when `pg-backup-api` returns malformed responses.

  _build_full_url(url_path: str) → str

    Build the full URL by concatenating url_path with the base URL.

    Parameters:

      url_path – path to be accessed in the `pg-backup-api`.

    Returns:

      the full URL after concatenating.

  static _deserialize_response(response: HTTPResponse) → Any

    Retrieve body from response as a deserialized JSON object.

    Parameters:

      response – response from which JSON body will be deserialized.

    Returns:

      the deserialized JSON body.

  _ensure_api_ok() → None

    Ensure `pg-backup-api` is reachable and `OK`.

    Raises:

      `ApiNotOk`: if `pg-backup-api` status is not `OK`.

  _get_request(url_path: str) → Any

    Perform a `GET` request to url_path.

    Parameters:

      url_path – URL to perform the `GET` request against.

    Returns:

      the deserialized response body.

    Raises:
      `RetriesExceeded`: raised from the corresponding `urllib3`

        exception.

  _post_request(url_path: str, body: Any) → Any

    Perform a `POST` request to url_path serializing body as JSON.

    Parameters:

      - url_path – URL to perform the `POST` request against.

      - body – the body to be serialized as JSON and sent in the request.

    Returns:

      the deserialized response body.

    Raises:
      `RetriesExceeded`: raised from the corresponding `urllib3`

        exception.

  static _serialize_request(body: Any) → Any

    Serialize a request body.

    Parameters:

      body – content of the request body to be serialized.

    Returns:

      the serialized request body.

  create_config_switch_operation(*args: Any, **kwargs: Any) → Any
  create_recovery_operation(*args: Any, **kwargs: Any) → Any
  get_operation_status(*args: Any, **kwargs: Any) → Any

exception patroni.scripts.barman.utils.RetriesExceeded

  Bases: `Exception`

  Maximum number of retries exceeded.

patroni.scripts.barman.utils.retry(exceptions: Type[Exception] | Tuple[Type[Exception], ...]) → Any

  Retry an operation n times if expected exceptions are faced.

  Note

  Should be used as a decorator of a class’ method as it expects the first argument to be a class instance.

  The class which method is going to be decorated should contain a couple attributes:

  - `max_retries`: maximum retry attempts before failing;

  - `retry_wait`: how long in seconds to wait before retrying.

  Parameters:

    exceptions – exceptions that could trigger a retry attempt.

  Raises:
    `RetriesExceeded`: if the maximum number of attempts has been

      exhausted.

patroni.scripts.barman.utils.set_up_logging(log_file: str | None = None) → None

  Set up logging to file, if log_file is given, otherwise to console.

  Parameters:

    log_file – file where to log messages, if any.