python-rundeck 0.3.0__tar.gz → 1.0.0__tar.gz

{python_rundeck-0.3.0 → python_rundeck-1.0.0}/PKG-INFO

@@ -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 → python_rundeck-1.0.0}/README.md

@@ -13,6 +13,7 @@ Contents
 - Quick start
 - Configuration
 - Available resources
+- Return types policy
 - Examples by resource
 - Error handling
 - Development and testing
@@ -42,7 +43,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)
 ```
 
@@ -84,6 +86,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
@@ -202,7 +238,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"])
@@ -360,7 +396,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 → python_rundeck-1.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-rundeck"
-version = "0.3.0"
+version = "1.0.0"
 description = "Python client for the Rundeck API (v14-v56)."
 authors = [
     {name = "Pascal Seckinger",email = "pascal.seckinger@protonmail.com"}

{python_rundeck-0.3.0 → python_rundeck-1.0.0}/src/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."""

{python_rundeck-0.3.0 → python_rundeck-1.0.0}/src/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):

{python_rundeck-0.3.0 → python_rundeck-1.0.0}/src/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."""

{python_rundeck-0.3.0 → python_rundeck-1.0.0}/src/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."""

{python_rundeck-0.3.0 → python_rundeck-1.0.0}/src/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."""

{python_rundeck-0.3.0 → python_rundeck-1.0.0}/src/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]:
         """