python-rundeck 0.3.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

{python_rundeck-0.3.0.dist-info → python_rundeck-1.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-rundeck
-Version: 0.3.0
+Version: 1.0.0
 Summary: Python client for the Rundeck API (v14-v56).
 License-Expression: MIT
 License-File: LICENSE
@@ -51,6 +51,7 @@ Contents
 - Quick start
 - Configuration
 - Available resources
+- Return types policy
 - Examples by resource
 - Error handling
 - Development and testing
@@ -80,7 +81,8 @@ for p in projects:
 # Get a project and run a job
 project = rd.projects.get("demo")
 jobs = project.jobs.list()
-execu = jobs[0].run()
+# Use as_execution=True to receive an Execution object.
+execu = jobs[0].run(as_execution=True)
 print(execu.id)
 ```
 
@@ -122,6 +124,40 @@ Available resources
 - `config_management` (`ConfigManagementManager`): global configuration `/config`.
 - `scm` (via `project.scm` and `job.scm`): import/export plugins, setup, enable/disable, status, actions (commit/import/export...).
 
+Return types policy
+-------------------
+- Resource managers use `list/get/create/update` to return objects (`RundeckObject`).
+- Factory managers return the created resource object for actions that create it
+  (e.g., `project.adhoc` returns `Execution`).
+- Utility managers return raw API responses (dict/str/bytes).
+- `delete(...)` returns `None`.
+- Object methods return raw API responses and update the object in place when needed.
+- Explicit flags are used when an object return is requested (e.g., `as_execution=True`).
+
+Resource managers:
+- `projects`, `jobs`, `executions`, `tokens`, `users`, `plugins`, `features`, `key_storage`, `system.acl`, `project.webhooks`.
+
+Factory managers:
+- `adhoc` (via `project.adhoc`).
+  Returns `Execution` objects (execution factory).
+
+Utility managers:
+- `system`, `config_management`, `metrics`, `scheduler`, `webhooks` (event send).
+- `scm` (via `project.scm` and `job.scm`), and project sub-managers like
+  `project.config`, `project.resources`, `project.sources`, `project.readme`,
+  `project.archive`, `project.acl`.
+
+Note: `project.webhooks.create(...)` returns the raw API response (e.g., `{"msg": "Saved webhook"}`)
+because the Rundeck API does not return the created webhook object.
+
+Example:
+```python
+job = rd.jobs.get("job-id")          # -> Job (object)
+resp = job.run()                     # -> dict (raw API response)
+execu = job.run(as_execution=True)   # -> Execution (object)
+execution.refresh()                  # updates in place, returns None
+```
+
 Examples by resource (complete)
 -------------------------------
 Projects
@@ -240,7 +276,7 @@ project.jobs.import_jobs(content=open("jobs.json", "rb").read(), fileformat="jso
 Note: import remains exposed as `import_jobs(...)` (the Python keyword prevents a direct call to `.import`). If you prefer the alias, use `getattr(rd.jobs, "import")(...)`.
 
 # Run and get the execution
-execution = job.run(argString="-option value")
+execution = job.run(as_execution=True, argString="-option value")
 
 # Bulk actions
 rd.jobs.bulk.enable_execution(["id1", "id2"])
@@ -398,7 +434,8 @@ ks = rd.key_storage
 # Create a secret (password)
 ks.create("integration/secret1", content="s3cr3t", content_type="application/x-rundeck-data-password")
 resources = ks.list()  # root listing
-meta = ks.get_metadata("integration/secret1")
+meta = ks.get("integration/secret1")
+content = meta.content()  # raw bytes
 ks.delete("integration/secret1")
 
 # AdHoc commands/scripts

{python_rundeck-0.3.0.dist-info → python_rundeck-1.0.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
 rundeck/__init__.py,sha256=M413mLKjB08nWuo5godsAmk2ly9vEYw5Xzc-Pt4Pqds,951
-rundeck/base.py,sha256=8JAghfRDGMWAhCbwedfPjuPu7ahKF8cE_ndkM1WEyuM,7125
+rundeck/base.py,sha256=TGqxLj9F4Y0x7nQGqkjuw7xitzxWOa2fn4apkjpckwE,7119
 rundeck/client.py,sha256=o1ScXT9AffgAVOhs5l8PFKqAFjSd1Dk0zWT_uzmQfVg,10949
 rundeck/config.py,sha256=WZxhYDS2S4dZfvRgEMAzeGtM3EKll0CZMI_h9CZDzpA,5278
 rundeck/const.py,sha256=uK6LPGQfkq0y5ae1QUcQ7uyV7PSKdDKMRfpNoHNAT74,845
@@ -9,20 +9,20 @@ rundeck/v1/__init__.py,sha256=stKy-CO4DYAq_xa35LOgghZQ6LtrDcZ5WkuffNPGR0I,13
 rundeck/v1/objects/__init__.py,sha256=5n01WuyYDbuLLGGKoqO342Nb15Qgk3s5MUpJKp-o8Ko,21
 rundeck/v1/objects/adhoc.py,sha256=P_Ncn7ho-yEBXm-9e_JOF3ZX6MNAmpNyo_wX7QFwwM4,3447
 rundeck/v1/objects/config_management.py,sha256=Abeputc-VcHqgQgsE3HHOcUIVWNAB-wgLahpkfo0Wmc,1539
-rundeck/v1/objects/executions.py,sha256=v5ySlu4nOinvTtbM_1MpVF3bv8iNd8qbsckdqyVuJmQ,9628
+rundeck/v1/objects/executions.py,sha256=BK1IvQGQJ_fMzpZgwZ2LJN6xslA2yIKprC6RZwLnGNI,9584
 rundeck/v1/objects/features.py,sha256=bVMLB86HIZF7dhN3EpqMVP_Yo_J2_hqtbJjZFb7BMxU,1283
-rundeck/v1/objects/jobs.py,sha256=fwhgxksV-i4_fA2jupeacvqlYNsKU5zBMWWZhbrWL8Q,11082
-rundeck/v1/objects/key_storage.py,sha256=mfFEUGcDnnDgTwnwCNNCXGuy_rmMi01fuXvcxinsWzI,2776
+rundeck/v1/objects/jobs.py,sha256=fHG2iqN1b9UQevUcYNqd2qh7jQzbR4IKfs8-Keiuoj8,11582
+rundeck/v1/objects/key_storage.py,sha256=TFa69t_jNZx1WbK0IQ5T1_x4tboHh3DOqSGNFX3CyVw,3673
 rundeck/v1/objects/metrics.py,sha256=R5SrySTHFznFgolJ3hezasSN7sZ3BSdTJs7PgN4w5p8,1004
 rundeck/v1/objects/plugins.py,sha256=a2vGsiQGz8V5gXNepj2KP98M926zzxRpksddKtZy5N8,1124
 rundeck/v1/objects/projects.py,sha256=FgqwbVpONjrOOVynoJenBtaJIj7x6dnAoNudQ6-nEVo,15512
 rundeck/v1/objects/scheduler.py,sha256=1lRGPdIej9OTNueSE9_p9PxS4b_M-ANTUJoztRo3IjE,1243
 rundeck/v1/objects/scm.py,sha256=f4y76CLF6J6q1ZE_Rrm9SXm2wlD3qaqXavt1DNzo_JE,7688
-rundeck/v1/objects/system.py,sha256=wTfIxs4zINXxJF3zaEckB75sTFeeUq31O864y-B_pdo,4629
+rundeck/v1/objects/system.py,sha256=pEjGPcnr7LOlN0RpfPtaD0dRTJuy58GPtwB0k6EVV4Y,4876
 rundeck/v1/objects/tokens.py,sha256=OWnfs1QUTpJbsaKf7r0Y7w3VYxxGZxBDead8JAoPKck,2373
-rundeck/v1/objects/users.py,sha256=N7WjC2UqXrmd0PurI317lua5wMSZN-C1YfdjjPWpqgA,3278
+rundeck/v1/objects/users.py,sha256=Ys3JE9rs1u7DIcIH3rG39rjZ--gwsfaXPHCsrxBXJaA,3330
 rundeck/v1/objects/webhooks.py,sha256=F_HzNvlBRPvS_viu2reCRc7ECqRSUhp5RfD_G3r-ZZk,3358
-python_rundeck-0.3.0.dist-info/METADATA,sha256=R2kNIAOkP26epzMRnUSZiRIwb7fvk4ayS0dmRwXM-Ug,16283
-python_rundeck-0.3.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-python_rundeck-0.3.0.dist-info/licenses/LICENSE,sha256=3X-BjvCzow8iLfLMykDaEAXjE9JvDrEHPkH9UK7MMMA,1073
-python_rundeck-0.3.0.dist-info/RECORD,,
+python_rundeck-1.0.0.dist-info/METADATA,sha256=aMBsZwnVx9C1nmFrTjcY7QMVzIJZSsr72cDxmFdNBEk,17935
+python_rundeck-1.0.0.dist-info/WHEEL,sha256=3ny-bZhpXrU6vSQ1UPG34FoxZBp3lVcvK0LkgUz6VLk,88
+python_rundeck-1.0.0.dist-info/licenses/LICENSE,sha256=3X-BjvCzow8iLfLMykDaEAXjE9JvDrEHPkH9UK7MMMA,1073
+python_rundeck-1.0.0.dist-info/RECORD,,

{python_rundeck-0.3.0.dist-info → python_rundeck-1.0.0.dist-info}/WHEEL

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

rundeck/base.py

@@ -50,14 +50,16 @@ class RundeckObject(Generic[ResourceT]):
     def to_dict(self) -> dict[str, Any]:
         return dict(self._attrs)
 
-    def refresh(self: ResourceT) -> ResourceT:
-        """Recharge la ressource en interrogeant son manager."""
+    def refresh(self: ResourceT) -> None:
+        """
+        Recharge la ressource en interrogeant son manager.
+
+        """
         ident = self._attrs.get(self._id_attr)
         if ident is None:
             raise AttributeError(f"{self.__class__.__name__} has no identifier")
         fresh = self.manager.get(ident)
         self._attrs = fresh._attrs
-        return self
 
     def pformat(self) -> str:
         """Retourne une représentation jolie du dictionnaire d'attributs."""

rundeck/v1/objects/executions.py

@@ -111,16 +111,15 @@ class Execution(RundeckObject):
         """
         return self._attrs.get("status") == "aborted"
 
-    def refresh(self) -> "Execution":
+    def refresh(self) -> None:
         """
         Actualise les données de l'exécution
 
         Returns:
-            Exécution actualisée
+            None.
         """
         updated = self.manager.get(self.id)
         self._attrs = updated._attrs
-        return self
 
 
 class ExecutionManager(RundeckObjectManager):

rundeck/v1/objects/jobs.py

@@ -22,22 +22,40 @@ class Job(RundeckObject):
             return f"{base}/{suffix.lstrip('/')}"
         return base
 
-    def run(self, **kwargs: Any) -> Execution:
+    def run(
+        self, as_execution: bool = False, **kwargs: Any
+    ) -> Execution | dict[str, Any]:
         """
-        Exécute le job et retourne l'exécution.
+        Exécute le job et retourne la réponse brute par défaut.
+
+        Args:
+            as_execution: True pour envelopper la réponse en Execution.
         """
         path = self._job_path("run")
         result = self.rd.http_post(path, json=kwargs or None)
-        # Wrap avec le manager d'exécutions existant.
-        return Execution(self.manager.rd.executions, result)
+        if as_execution:
+            # Wrap avec le manager d'exécutions existant.
+            return Execution(self.manager.rd.executions, result)
+        return result
 
-    def retry(self, execution_id: str, **kwargs: Any) -> Execution:
+    def retry(
+        self,
+        execution_id: str,
+        as_execution: bool = False,
+        **kwargs: Any,
+    ) -> Execution | dict[str, Any]:
         """
         Relance une exécution (retry).
+
+        Args:
+            execution_id: ID de l'exécution à relancer.
+            as_execution: True pour envelopper la réponse en Execution.
         """
         path = self._job_path(f"retry/{execution_id}")
         result = self.rd.http_post(path, json=kwargs or None)
-        return Execution(self.manager.rd.executions, result)
+        if as_execution:
+            return Execution(self.manager.rd.executions, result)
+        return result
 
     def delete(self) -> None:
         """Supprime le job courant."""

rundeck/v1/objects/key_storage.py

@@ -15,6 +15,28 @@ class StorageKey(RundeckObject):
     _id_attr = "path"
     _repr_attr = "name"
 
+    def _relative_path(self) -> str:
+        path = self.path
+        # API returns "keys/..." but endpoints expect the relative path.
+        if isinstance(path, str) and path.startswith("keys/"):
+            return path[len("keys/") :]
+        return path
+
+    def content(self, accept: str = "application/pgp-keys") -> bytes:
+        """Récupère le contenu d'une clé (ex: clé publique)."""
+        path = self.manager._file_path(self._relative_path())
+        headers = {"Accept": accept} if accept else None
+        response = self.manager.rd.http_get(path, headers=headers, raw=True)
+        return response.content
+
+    def update(self, content: bytes | str, content_type: str) -> dict[str, Any]:
+        """Met à jour le contenu de la clé et rafraîchit l'objet."""
+        updated = self.manager.update(
+            self._relative_path(), content=content, content_type=content_type
+        )
+        self._attrs = updated._attrs
+        return updated.to_dict()
+
 
 class StorageKeyManager(RundeckObjectManager[StorageKey]):
     """Manager pour les clés/ressources du storage."""
@@ -43,7 +65,7 @@ class StorageKeyManager(RundeckObjectManager[StorageKey]):
             resources = result.get("resources") or []
         return self._wrap_list(resources)
 
-    def get_metadata(self, path: str) -> StorageKey:
+    def get(self, path: str) -> StorageKey:
         """Récupère les métadonnées d'une clé/fichier."""
         target = self._file_path(path)
         result = self.rd.http_get(target)
@@ -51,24 +73,23 @@ class StorageKeyManager(RundeckObjectManager[StorageKey]):
             return self._wrap(result)
         return self._wrap({"path": path, "raw": result})
 
-    def get_content(self, path: str, accept: str = "application/pgp-keys") -> bytes:
-        """Récupère le contenu d'une clé (ex: clé publique)."""
-        target = self._file_path(path)
-        headers = {"Accept": accept} if accept else None
-        response = self.rd.http_get(target, headers=headers, raw=True)
-        return response.content
-
-    def create(self, path: str, content: bytes | str, content_type: str) -> Any:
+    def create(self, path: str, content: bytes | str, content_type: str) -> StorageKey:
         """Crée une nouvelle clé/fichier à l'emplacement donné."""
         target = self._file_path(path)
         headers = {"Content-Type": content_type, "Accept": "application/json"}
-        return self.rd.http_post(target, data=content, headers=headers)
+        result = self.rd.http_post(target, data=content, headers=headers)
+        if isinstance(result, dict):
+            return self._wrap(result)
+        return self._wrap({"path": path, "raw": result})
 
-    def update(self, path: str, content: bytes | str, content_type: str) -> Any:
+    def update(self, path: str, content: bytes | str, content_type: str) -> StorageKey:
         """Met à jour une clé/fichier existant."""
         target = self._file_path(path)
         headers = {"Content-Type": content_type, "Accept": "application/json"}
-        return self.rd.http_put(target, data=content, headers=headers)
+        result = self.rd.http_put(target, data=content, headers=headers)
+        if isinstance(result, dict):
+            return self._wrap(result)
+        return self._wrap({"path": path, "raw": result})
 
     def delete(self, path: str) -> None:
         """Supprime une clé/fichier."""

rundeck/v1/objects/system.py

@@ -34,6 +34,12 @@ class SystemACL(RundeckObject):
     _id_attr = "name"
     _repr_attr = "name"
 
+    def update(self, content: str) -> dict[str, Any]:
+        """Met à jour la policy ACL et rafraîchit l'objet."""
+        updated = self.manager.update(self.name, content)
+        self._attrs = updated._attrs
+        return updated.to_dict()
+
 
 class SystemACLManager(RundeckObjectManager[SystemACL]):
     """Sous-manager pour les endpoints ACL système."""

rundeck/v1/objects/users.py

@@ -18,7 +18,7 @@ class User(RundeckObject):
         firstName: str | None = None,
         lastName: str | None = None,
         email: str | None = None,
-    ) -> "User":
+    ) -> dict[str, Any]:
         """
         Met à jour les informations de l'utilisateur
 
@@ -28,7 +28,7 @@ class User(RundeckObject):
             email: Email
 
         Returns:
-            Utilisateur mis à jour
+            Réponse brute de l'API.
         """
         data: dict[str, Any] = {}
         if firstName:
@@ -40,8 +40,9 @@ class User(RundeckObject):
 
         path = self.manager._build_path(f"info/{self.login}")
         result = self.manager.rd.http_post(path, json=data)
-        self._attrs.update(result)
-        return self
+        if isinstance(result, dict):
+            self._attrs.update(result)
+        return result
 
     def roles(self) -> list[str]:
         """