python-rundeck 0.1.0__py3-none-any.whl

rundeck/config.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+"""
+Gestion de la configuration Rundeck (arguments, variables d'env, fichiers).
+"""
+
+import configparser
+import os
+from pathlib import Path
+from typing import Any
+
+from rundeck.const import DEFAULT_API_VERSION, DEFAULT_TIMEOUT, USER_AGENT
+
+DEFAULT_CONFIG_FILES: list[str] = [
+    "/etc/rundeck.cfg",
+    str(Path.home() / ".rundeck.cfg"),
+]
+
+
+class RundeckConfigError(Exception):
+    """Erreur de configuration Rundeck."""
+
+
+def _resolve_existing_files(config_files: list[str]) -> list[str]:
+    existing: list[str] = []
+    for file in config_files:
+        path = Path(file).expanduser()
+        if path.exists():
+            existing.append(str(path.resolve()))
+    return existing
+
+
+def _coerce_timeout(value: Any) -> float:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return DEFAULT_TIMEOUT
+
+
+def _coerce_ssl_verify(value: Any) -> bool | str:
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return True
+    text = str(value).strip().lower()
+    if text in {"true", "1", "yes", "y"}:
+        return True
+    if text in {"false", "0", "no", "n"}:
+        return False
+    # Assume path to CA bundle
+    return value
+
+
+class RundeckConfig:
+    """Charge la configuration depuis args/env/fichiers avec priorité décroissante."""
+
+    def __init__(
+        self,
+        url: str | None = None,
+        token: str | None = None,
+        username: str | None = None,
+        password: str | None = None,
+        api_version: int | str | None = None,
+        timeout: float | None = None,
+        ssl_verify: bool | str | None = None,
+        config_files: list[str] | None = None,
+        config_section: str = "rundeck",
+    ) -> None:
+        env_url = os.getenv("RUNDECK_URL")
+        env_token = os.getenv("RUNDECK_TOKEN")
+        env_username = os.getenv("RUNDECK_USERNAME")
+        env_password = os.getenv("RUNDECK_PASSWORD")
+        env_api_version = os.getenv("RUNDECK_API_VERSION")
+        env_timeout = os.getenv("RUNDECK_TIMEOUT")
+        env_ssl_verify = os.getenv("RUNDECK_SSL_VERIFY")
+        env_user_agent = os.getenv("RUNDECK_USER_AGENT")
+
+        files = self._resolve_files(config_files)
+        file_conf = self._parse_files(files, config_section) if files else {}
+
+        self.url: str | None = url or env_url or file_conf.get("url")
+        self.token: str | None = token or env_token or file_conf.get("token")
+        self.username: str | None = (
+            username or env_username or file_conf.get("username")
+        )
+        self.password: str | None = (
+            password or env_password or file_conf.get("password")
+        )
+        self.api_version: str = str(
+            api_version
+            or env_api_version
+            or file_conf.get("api_version")
+            or DEFAULT_API_VERSION
+        )
+        self.timeout: float = (
+            float(timeout)
+            if timeout is not None
+            else _coerce_timeout(env_timeout or file_conf.get("timeout"))
+        )
+        self.ssl_verify: bool | str = (
+            ssl_verify
+            if ssl_verify is not None
+            else _coerce_ssl_verify(env_ssl_verify or file_conf.get("ssl_verify"))
+        )
+        self.user_agent: str = (
+            env_user_agent or file_conf.get("user_agent") or USER_AGENT
+        )
+        self.config_files = files
+
+    @staticmethod
+    def _resolve_files(config_files: list[str] | None) -> list[str]:
+        if config_files:
+            resolved = _resolve_existing_files(config_files)
+            if not resolved:
+                raise RundeckConfigError("Aucun fichier de configuration trouvé.")
+            return resolved
+
+        env_cfg = os.getenv("RUNDECK_CFG")
+        if env_cfg:
+            resolved = _resolve_existing_files([env_cfg])
+            if not resolved:
+                raise RundeckConfigError(
+                    f"Fichier de configuration introuvable: {env_cfg}"
+                )
+            return resolved
+
+        return _resolve_existing_files(DEFAULT_CONFIG_FILES)
+
+    @staticmethod
+    def _parse_files(
+        files: list[str],
+        section: str,
+    ) -> dict[str, Any]:
+        parser = configparser.ConfigParser()
+        parser.read(files, encoding="utf-8")
+        if not parser.has_section(section):
+            return {}
+
+        def _get(option: str) -> Any:
+            try:
+                return parser.get(section, option)
+            except (configparser.NoSectionError, configparser.NoOptionError):
+                return None
+
+        return {
+            "url": _get("url"),
+            "token": _get("token"),
+            "username": _get("username"),
+            "password": _get("password"),
+            "api_version": _get("api_version"),
+            "timeout": _get("timeout"),
+            "ssl_verify": _get("ssl_verify"),
+            "user_agent": _get("user_agent"),
+        }
+
+    @classmethod
+    def from_config(
+        cls, config_section: str | None = None, config_files: list[str] | None = None
+    ) -> "RundeckConfig":
+        """
+        Charge uniquement depuis fichiers/env (sans arguments explicites).
+        """
+        return cls(
+            config_files=config_files,
+            config_section=config_section or "rundeck",
+        )

rundeck/const.py

@@ -0,0 +1,45 @@
+"""
+Constantes partagées pour le client Rundeck.
+"""
+
+# Package metadata
+__version__ = "0.1.0"
+
+# Auth
+RUNDECK_AUTH_HEADER = "X-Rundeck-Auth-Token"
+
+# HTTP methods
+HTTP_GET = "GET"
+HTTP_POST = "POST"
+HTTP_PUT = "PUT"
+HTTP_DELETE = "DELETE"
+
+# Content / formats
+FORMAT_JSON = "json"
+
+# API versions (cf. docs Rundeck: current 56, minimum 14, dépréciation 17)
+API_VERSION_CURRENT = "56"
+API_VERSION_MIN = "14"
+API_VERSION_DEPRECATION = "17"
+
+# Defaults
+DEFAULT_API_VERSION = API_VERSION_CURRENT
+DEFAULT_TIMEOUT = 30
+USER_AGENT = "python-rundeck"
+
+
+__all__ = [
+    "__version__",
+    "API_VERSION_CURRENT",
+    "API_VERSION_DEPRECATION",
+    "API_VERSION_MIN",
+    "DEFAULT_API_VERSION",
+    "DEFAULT_TIMEOUT",
+    "FORMAT_JSON",
+    "HTTP_DELETE",
+    "HTTP_GET",
+    "HTTP_POST",
+    "HTTP_PUT",
+    "RUNDECK_AUTH_HEADER",
+    "USER_AGENT",
+]

rundeck/exceptions.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+"""
+Exceptions et helpers pour l'API Rundeck.
+"""
+
+from typing import Any
+
+import requests
+
+
+class RundeckError(Exception):
+    """Exception de base pour toutes les erreurs Rundeck."""
+
+    def __init__(
+        self,
+        message: str = "",
+        error_code: str | None = None,
+        response: requests.Response | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.error_code = error_code
+        self.response = response
+        self.response_code = response.status_code if response is not None else None
+
+        # Stocke le corps de la réponse (JSON ou texte brut)
+        if response is None or not response.text:
+            self.response_body: Any | None = None
+        else:
+            try:
+                self.response_body = response.json()
+            except ValueError:
+                self.response_body = response.text
+
+    def __str__(self) -> str:
+        code = f"{self.response_code}: " if self.response_code is not None else ""
+        error = f" ({self.error_code})" if self.error_code else ""
+        return f"{code}{self.message}{error}"
+
+
+class RundeckHTTPError(RundeckError):
+    """Erreur HTTP générique renvoyée par Rundeck."""
+
+
+class RundeckOperationError(RundeckHTTPError):
+    """Erreur lors d'une opération métier."""
+
+
+class RundeckAuthenticationError(RundeckOperationError):
+    """Authentification ou autorisation refusée."""
+
+
+class RundeckNotFoundError(RundeckOperationError):
+    """Ressource introuvable."""
+
+
+class RundeckValidationError(RundeckOperationError):
+    """Entrée invalide (erreur 400)."""
+
+
+class RundeckApiVersionUnsupportedError(RundeckValidationError):
+    """Version d'API non supportée pour la ressource demandée."""
+
+
+class RundeckConflictError(RundeckOperationError):
+    """Conflit (erreur 409)."""
+
+
+class RundeckQuotaExceededError(RundeckOperationError):
+    """Quota dépassé (erreur 429)."""
+
+
+class RundeckServerError(RundeckHTTPError):
+    """Erreur serveur (5xx)."""
+
+
+class RundeckConnectionError(RundeckError):
+    """Erreur réseau ou connexion refusée."""
+
+
+class RundeckTimeoutError(RundeckError):
+    """Timeout réseau."""
+
+
+def _extract_error(response: requests.Response) -> tuple[str, str | None, Any | None]:
+    """
+    Extrait le message et le code d'erreur depuis la réponse HTTP.
+    """
+    message = f"HTTP {response.status_code}"
+    error_code: str | None = None
+    body: Any | None = None
+
+    if response.text:
+        try:
+            body = response.json()
+        except ValueError:
+            body = response.text
+
+    if isinstance(body, dict):
+        message = (
+            body.get("message")
+            or body.get("error")
+            or body.get("errorMessage")
+            or message
+        )
+        error_code = body.get("errorCode") or body.get("error_code")
+    elif isinstance(body, str) and body.strip():
+        message = body.strip()
+
+    return message, error_code, body
+
+
+def raise_for_status(response: requests.Response) -> None:
+    """
+    Lève une exception spécialisée en fonction du code HTTP.
+    """
+    message, error_code, body = _extract_error(response)
+    status = response.status_code
+    code_lower = error_code.lower() if isinstance(error_code, str) else None
+
+    # Certains retours peuvent être HTTP 200 mais contenir un errorCode explicite
+    if (
+        response.ok
+        and not code_lower
+        and not (isinstance(body, dict) and body.get("error") is True)
+    ):
+        return
+
+    if code_lower == "unauthorized":
+        raise RundeckAuthenticationError(message, error_code, response)
+    if code_lower == "api-version-unsupported":
+        raise RundeckApiVersionUnsupportedError(message, error_code, response)
+    if status == 400:
+        raise RundeckValidationError(message, error_code, response)
+    if status in (401, 403):
+        raise RundeckAuthenticationError(message, error_code, response)
+    if status == 404:
+        raise RundeckNotFoundError(message, error_code, response)
+    if status == 409:
+        raise RundeckConflictError(message, error_code, response)
+    if status == 429:
+        raise RundeckQuotaExceededError(message, error_code, response)
+    if status >= 500:
+        raise RundeckServerError(message, error_code, response)
+
+    raise RundeckHTTPError(message, error_code, response)
+
+
+__all__ = [
+    "RundeckApiVersionUnsupportedError",
+    "RundeckAuthenticationError",
+    "RundeckConflictError",
+    "RundeckConnectionError",
+    "RundeckError",
+    "RundeckHTTPError",
+    "RundeckNotFoundError",
+    "RundeckOperationError",
+    "RundeckQuotaExceededError",
+    "RundeckServerError",
+    "RundeckTimeoutError",
+    "RundeckValidationError",
+    "raise_for_status",
+]

rundeck/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561 type hints.

rundeck/v1/__init__.py

@@ -0,0 +1 @@
+# Package v1

rundeck/v1/objects/__init__.py

@@ -0,0 +1 @@
+# Package v1.objects

rundeck/v1/objects/adhoc.py

@@ -0,0 +1,93 @@
+"""
+Exécution AdHoc (commandes, scripts, URLs) pour un projet.
+"""
+
+from typing import Any
+
+from rundeck.base import RundeckObjectManager
+from rundeck.v1.objects.executions import Execution
+
+
+class AdhocManager(RundeckObjectManager[Execution]):
+    """Manager pour les exécutions AdHoc d'un projet."""
+
+    _obj_cls = Execution
+
+    def _project_name(self, project: str | None) -> str:
+        project_name = project or (self.parent.id if self.parent else None)
+        if not project_name:
+            raise ValueError("Le nom du projet est requis pour les commandes AdHoc")
+        return project_name
+
+    def _wrap_execution(self, result: Any, refresh: bool = True) -> Execution:
+        data = (
+            result.get("execution")
+            if isinstance(result, dict) and "execution" in result
+            else result
+        )
+        if isinstance(data, dict):
+            exec_id = data.get("id")
+            # Les réponses AdHoc ne sont pas complètes,
+            # Le rafraîchissement permet d'obtenir toutes les données
+            if refresh and exec_id:
+                try:
+                    return self.rd.executions.get(exec_id)
+                except Exception:
+                    return Execution(self.rd.executions, data)
+        return Execution(self.rd.executions, data)
+
+    def run_command(
+        self,
+        exec: str,
+        project: str | None = None,
+        refresh: bool = True,
+        **options: Any,
+    ) -> Execution:
+        """Exécute une commande shell AdHoc."""
+        project_name = self._project_name(project)
+        payload: dict[str, Any] = {"exec": exec, "project": project_name}
+        payload.update(options)
+        path = f"/project/{project_name}/run/command"
+        result = self.rd.http_post(path, json=payload)
+        return self._wrap_execution(result, refresh=refresh)
+
+    def run_script(
+        self,
+        script: str | None = None,
+        project: str | None = None,
+        refresh: bool = True,
+        script_file: tuple[str, Any, str | None] | None = None,
+        **options: Any,
+    ) -> Execution:
+        """Exécute un script AdHoc (contenu inline ou multipart)."""
+        project_name = self._project_name(project)
+        path = f"/project/{project_name}/run/script"
+        if script_file:
+            filename, content, content_type = script_file
+            payload: dict[str, Any] = {"project": project_name}
+            payload.update(options)
+            files = {"scriptFile": (filename, content, content_type or "text/plain")}
+            result = self.rd.http_post(path, data=payload, files=files)
+        else:
+            payload: dict[str, Any] = {"script": script or "", "project": project_name}
+            payload.update(options)
+            result = self.rd.http_post(path, json=payload)
+        return self._wrap_execution(result, refresh=refresh)
+
+    def run_url(
+        self,
+        script_url: str,
+        project: str | None = None,
+        refresh: bool = True,
+        **options: Any,
+    ) -> Execution:
+        """Exécute un script AdHoc depuis une URL."""
+        project_name = self._project_name(project)
+        payload: dict[str, Any] = {"scriptURL": script_url, "project": project_name}
+        payload.update(options)
+        path = f"/project/{project_name}/run/url"
+        result = self.rd.http_post(path, json=payload)
+        return self._wrap_execution(result, refresh=refresh)
+
+
+__all__ = ["AdhocManager"]

rundeck/v1/objects/config_management.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+"""
+Gestion de la configuration Rundeck (instance globale).
+"""
+
+from rundeck.base import RundeckObjectManager
+
+
+class ConfigManagementManager(RundeckObjectManager):
+    """
+    Gestion des configurations globales (plugin/custom) via /config.
+    """
+
+    _path = "/config"
+
+    def list(self) -> list[dict[str, str]]:
+        """Liste toutes les configs et propriétés."""
+        path = self._build_path("list")
+        return self.rd.http_get(path)
+
+    def save(self, entries: list[dict[str, str]]) -> dict[str, str | list[str]]:
+        """
+        Crée ou met à jour des configs (payload: liste de dicts {key, value, strata?}).
+        """
+        path = self._build_path("save")
+        return self.rd.http_post(path, json=entries)
+
+    def delete(self, key: str, strata: str | None = None) -> None:
+        """
+        Supprime une config via /config/delete avec payload JSON.
+        """
+        payload: dict[str, str] = {"key": key}
+        if strata:
+            payload["strata"] = strata
+        path = self._build_path("delete")
+        self.rd.http_delete(path, json=payload)
+
+    def refresh(self) -> dict[str, str]:
+        """
+        Recharge les configurations depuis les fichiers de propriétés.
+        """
+        path = self._build_path("refresh")
+        return self.rd.http_post(path)
+
+    def restart(self) -> dict[str, str]:
+        """
+        Redémarre le serveur Rundeck.
+        """
+        path = self._build_path("restart")
+        return self.rd.http_post(path)