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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-rundeck
-Version: 0.2.0
+Version: 1.0.0
 Summary: Python client for the Rundeck API (v14-v56).
 License-Expression: MIT
 License-File: LICENSE
@@ -38,110 +38,148 @@ Description-Content-Type: text/markdown
 
 python-rundeck
 ===============
+![PyPI Version](https://img.shields.io/pypi/v/python-rundeck)
+![Python Versions](https://img.shields.io/pypi/pyversions/python-rundeck)
+![License](https://img.shields.io/pypi/l/python-rundeck)
+![Downloads](https://static.pepy.tech/badge/python-rundeck)
 
-Client Python pour l’API Rundeck (v14–v56), inspiré de l’architecture de python-gitlab. Fournit des managers typés pour les ressources clés (projects, jobs, executions, tokens, users, système, configuration) et SCM (import/export).
+Python client for the Rundeck API (v14-v56), inspired by the python-gitlab architecture. Provides typed managers for key resources (projects, jobs, executions, tokens, users, system, configuration) and SCM (import/export).
 
-Sommaire
+Contents
 --------
 - Installation
-- Démarrage rapide
+- Quick start
 - Configuration
-- Ressources disponibles
-- Exemples par ressource
-- Gestion des erreurs
-- Développement et tests
+- Available resources
+- Return types policy
+- Examples by resource
+- Error handling
+- Development and testing
 
 Installation
 ------------
-Prerequis : Python 3.11+. Le projet utilise Poetry.
+Prerequisites: Python 3.11+. Install from PyPI.
 
 ```bash
-poetry install
-# ou en editable avec pip
-pip install -e .
+pip install python-rundeck
 ```
 
-Démarrage rapide
-----------------
+Quick start
+-----------
 ```python
 from rundeck.client import Rundeck
 
 rd = Rundeck(url="https://rundeck.example.com", token="MY_TOKEN", api_version=56)
-# Auth par mot de passe (session cookie) si pas de token
+# Password auth (session cookie) if no token
 rd = Rundeck(url="https://rundeck.example.com", username="admin", password="admin", api_version=56)
 
-# Lister les projets
+# List projects
 projects = rd.projects.list()
 for p in projects:
     print(p.name)
 
-# Récupérer un projet et lancer un job
+# 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)
 ```
 
 Configuration
 -------------
-La configuration suit un modèle en cascade (args > env > fichiers > défauts) via `RundeckConfig`.
-
-Paramètres principaux :
-- `url` : URL Rundeck (ex. `https://rundeck.example.com`)
-- `token` : Token API (en-tête `X-Rundeck-Auth-Token`)
-- `username` / `password` : Authentification par session (j_security_check) si aucun token n'est fourni.
-- `api_version` : Version d’API (ex. `56`)
-- `timeout` : Timeout des requêtes (float, secondes)
-- `ssl_verify` : Vérification TLS (bool ou chemin CA)
-
-Fichiers de config : si besoin, passez `config_files` ou `Rundeck.from_config(config_section=...)`.
-Variables d'env utiles (config client) :
-- `RUNDECK_URL` : URL de base
-- `RUNDECK_TOKEN` : token API (en-tête `X-Rundeck-Auth-Token`)
-- `RUNDECK_USERNAME` / `RUNDECK_PASSWORD` : auth session (si pas de token)
-- `RUNDECK_API_VERSION` : version d'API (ex: 56)
-- `RUNDECK_TIMEOUT` : timeout des requêtes (secondes)
-- `RUNDECK_SSL_VERIFY` : vérification TLS (bool ou chemin CA)
-- `RUNDECK_USER_AGENT` : User-Agent HTTP
-
-Ressources disponibles
-----------------------
-- `projects` (`ProjectManager`) : CRUD projets, export/import de jobs, config projet, archive (export/import).
-- `jobs` (`JobManager`) : liste, get, suppressions, actions bulk, exécution.
-- `executions` (`ExecutionManager`) : liste/filtre, running, get/delete, query avancée.
-- `tokens` (`TokenManager`) : liste, get, create, delete.
-- `users` (`UserManager`) : opérations utilisateurs (selon implémentation courante).
-- `metrics` (`MetricsManager`) : endpoints `/metrics` (list/data/healthcheck/ping).
-- `plugins` (`PluginManager`) : liste des plugins installés (`/plugin/list`).
-- `webhooks` (`WebhookEventManager` + `ProjectWebhookManager`) : gestion des webhooks projet et envoi via token.
-- `key_storage` (`StorageKeyManager`) : gestion du stockage des clés `/storage/keys`.
-- `adhoc` (`AdhocManager`, via `project.adhoc`) : exécution de commandes/scripts AdHoc.
-- `system` (`SystemManager`) : info système, exécutions enable/disable, logstorage, ACL.
-- `config_management` (`ConfigManagementManager`) : configuration globale `/config`.
-- `scm` (via `project.scm` et `job.scm`) : plugins import/export, setup, enable/disable, statut, actions (commit/import/export...).
-
-Exemples par ressource (complets)
----------------------------------
-Projets
+Configuration follows a cascading model (args > env > files > defaults) via `RundeckConfig`.
+
+Main parameters:
+- `url`: Rundeck URL (e.g. `https://rundeck.example.com`)
+- `token`: API token (header `X-Rundeck-Auth-Token`)
+- `username` / `password`: Session authentication (j_security_check) if no token is provided.
+- `api_version`: API version (e.g. `56`)
+- `timeout`: Request timeout (float, seconds)
+- `ssl_verify`: TLS verification (bool or CA path)
+
+Config files: if needed, pass `config_files` or `Rundeck.from_config(config_section=...)`.
+Useful env vars (client config):
+- `RUNDECK_URL`: Base URL
+- `RUNDECK_TOKEN`: API token (header `X-Rundeck-Auth-Token`)
+- `RUNDECK_USERNAME` / `RUNDECK_PASSWORD`: Session auth (if no token)
+- `RUNDECK_API_VERSION`: API version (e.g. 56)
+- `RUNDECK_TIMEOUT`: Request timeout (seconds)
+- `RUNDECK_SSL_VERIFY`: TLS verification (bool or CA path)
+- `RUNDECK_USER_AGENT`: HTTP User-Agent
+
+Available resources
+-------------------
+- `projects` (`ProjectManager`): CRUD projects, job export/import, project config, archive (export/import).
+- `jobs` (`JobManager`): list, get, deletions, bulk actions, execution.
+- `executions` (`ExecutionManager`): list/filter, running, get/delete, advanced query.
+- `tokens` (`TokenManager`): list, get, create, delete.
+- `users` (`UserManager`): user operations (per current implementation).
+- `metrics` (`MetricsManager`): `/metrics` endpoints (list/data/healthcheck/ping).
+- `plugins` (`PluginManager`): list installed plugins (`/plugin/list`).
+- `webhooks` (`WebhookEventManager` + `ProjectWebhookManager`): project webhook management and sending via token.
+- `key_storage` (`StorageKeyManager`): key storage management `/storage/keys`.
+- `adhoc` (`AdhocManager`, via `project.adhoc`): run AdHoc commands/scripts.
+- `system` (`SystemManager`): system info, executions enable/disable, logstorage, ACL.
+- `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
 ```python
-# CRUD projet
+# CRUD project
 p = rd.projects.create("demo")
 p = rd.projects.get("demo")
 rd.projects.delete("demo")
 projects = rd.projects.list()
 
-# Export / import de jobs d'un projet (via le manager de jobs)
+# Export / import jobs from a project (via job manager)
 project.jobs.export(format="json", idlist="id1,id2", groupPath="group/sub")
 project.jobs.import_jobs(content=open("jobs.json").read(), format="json", dupeOption="update", uuidOption="remove")
 
-# Export / import du projet (archive ZIP)
+# Project export / import (ZIP archive)
 archive = project.archive
-resp = archive.export(export_all=False, export_webhooks=True)  # Response brute (zip)
+resp = archive.export(export_all=False, export_webhooks=True)  # Raw response (zip)
 token_info = archive.export_async(exportAll=True)
 status = archive.export_status(token_info.get("token", ""))
 zip_resp = archive.export_download(token_info.get("token", ""))
 
-# Import d'archive (synchrone ou async)
+# Archive import (sync or async)
 archive.import_archive(
     content=open("project-export.zip", "rb").read(),
     jobUuidOption="preserve",
@@ -151,16 +189,16 @@ archive.import_archive(
 archive.import_archive(content=open("project-export.zip", "rb").read(), async_import=True)
 archive.import_status()
 
-# Readme / MOTD du projet
-project.readme.get_readme()  # texte par défaut
+# Project README / MOTD
+project.readme.get_readme()  # default text
 project.readme.get_readme(accept="application/json")
-project.readme.update_readme("Nouveau contenu", content_type="text/plain")
+project.readme.update_readme("New content", content_type="text/plain")
 project.readme.delete_readme()
 project.readme.get_motd()
-project.readme.update_motd("Message du jour", content_type="text/plain")
+project.readme.update_motd("Message of the day", content_type="text/plain")
 project.readme.delete_motd()
 
-# Config projet (clé/valeur)
+# Project config (key/value)
 conf = p.config.get()
 p.config.keys.get("project.label")
 p.config.keys.set("project.label", "Demo")
@@ -168,27 +206,27 @@ p.config.keys.update({"project.description": "Sample"})
 p.config.replace({"project.label": "Demo", "project.description": "Sample"})
 p.config.keys.delete("project.label")
 
-# SCM import/export (sur un projet)
-scm_import = project.scm.import_  # ou getattr(project.scm, "import")
+# SCM import/export (on a project)
+scm_import = project.scm.import_  # or getattr(project.scm, "import")
 scm_export = project.scm.export
 
-# Découverte des plugins
+# Plugin discovery
 scm_import.plugins.list()
 scm_export.plugins.list()
 
-# Champs d'entrée pour un plugin et setup (plugin_type explicite)
+# Input fields for a plugin and setup (explicit plugin_type)
 fields = scm_import.plugins.input_fields("git-import")
 scm_import.config.setup("git-import", {"url": "ssh://git@example.com/repo.git", "dir": "/tmp/repo"})
 
-# Activer/désactiver un plugin
+# Enable/disable a plugin
 scm_import.config.enable("git-import")
 scm_export.config.disable("custom-export")
 
-# Statut/config SCM
+# SCM status/config
 import_status = scm_import.actions.status()
 export_conf = scm_export.config.get()
 
-# Actions SCM côté projet (ex: commit/pull/push selon plugin)
+# Project-side SCM actions (e.g., commit/pull/push depending on plugin)
 action_fields = scm_export.actions.input_fields("commit")
 scm_export.actions.perform(
     "commit",
@@ -201,14 +239,14 @@ scm_export.actions.perform(
 
 Jobs
 ```python
-# Lister les jobs d’un projet
+# List jobs for a project
 jobs = rd.jobs.list(project="demo", groupPath="ops")
 
-# Depuis un projet parenté
+# From a parent project
 project = rd.projects.get("demo")
 jobs = project.jobs.list()
 
-# Accès direct à un job
+# Direct access to a job
 job = rd.jobs.get("job-id")
 job.delete()
 job.definition(format="yaml")
@@ -223,7 +261,7 @@ tags = job.tags()
 workflow = job.workflow()
 forecast = job.forecast(time="2024-05-01T10:00:00Z", max=5)
 
-# Exporter/importer des jobs via le manager (paramètre project ou parent)
+# Export/import jobs via manager (project parameter or parent)
 rd.jobs.export(project="demo", format="xml", idlist="id1,id2", groupPath="group")
 rd.jobs.import_jobs(
     project="demo",
@@ -231,30 +269,30 @@ rd.jobs.import_jobs(
     fileformat="xml",
     dupeOption="update",
 )
-# Ou via un projet parenté
+# Or via a parent project
 project.jobs.export(format="json")
 project.jobs.import_jobs(content=open("jobs.json", "rb").read(), fileformat="json")
 
-Note: l'import reste exposé sous le nom `import_jobs(...)` (le mot-clé Python empêche un appel direct à `.import`). Si vous préférez l'alias, utilisez `getattr(rd.jobs, "import")(...)`.
+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")(...)`.
 
-# Exécuter et récupérer l'exécution
-execution = job.run(argString="-option value")
+# Run and get the execution
+execution = job.run(as_execution=True, argString="-option value")
 
-# Actions bulk
+# Bulk actions
 rd.jobs.bulk.enable_execution(["id1", "id2"])
 rd.jobs.bulk.disable_execution(["id1", "id2"])
 rd.jobs.bulk.delete(["id1", "id2"])
 rd.jobs.bulk.enable_schedule(["id1", "id2"])
 rd.jobs.bulk.disable_schedule(["id1", "id2"])
 
-# Upload de fichiers d'option et fichiers uploadés
+# Upload option files and uploaded files
 job.upload_option_file("csvfile", open("data.csv", "rb").read(), file_name="data.csv")
 job.list_uploaded_files(max=20)
 rd.jobs.get_uploaded_file_info("file-id")
 
-# SCM import/export sur un job
+# SCM import/export on a job
 job_scm_export = job.scm.export
-job_scm_import = job.scm.import_  # ou getattr(job.scm, "import")
+job_scm_import = job.scm.import_  # or getattr(job.scm, "import")
 
 job_scm_export.status()
 job_scm_export.diff()
@@ -264,7 +302,7 @@ job_scm_import.status()
 job_scm_import.input_fields("pull")
 job_scm_import.perform("pull", input_values={"message": "Update from repo"})
 
-# Ressources d'un projet
+# Project resources
 resources = project.resources.list(format="json", groupPath="ops")
 node = project.resources.get("node1")
 sources = project.sources.list()
@@ -278,18 +316,18 @@ project.acl.update("policy.aclpolicy", content="...yaml...")
 project.acl.delete("policy.aclpolicy")
 ```
 
-Exécutions
+Executions
 ```python
-# Liste simple ou paginée
+# Simple or paginated list
 execs = rd.executions.list(project="demo", status="running", max=50, offset=0)
-running = rd.executions.running(project="demo")  # ou "*" pour tous
+running = rd.executions.running(project="demo")  # or "*" for all
 
-# Détails / suppression
+# Details / deletion
 e = rd.executions.get("123")
 rd.executions.delete("123")
 rd.executions.bulk_delete(["123", "124"])
 
-# Requête avancée (query)
+# Advanced query
 advanced = rd.executions.query(
     project="demo",
     statusFilter="failed",
@@ -299,12 +337,12 @@ advanced = rd.executions.query(
     max=100,
 )
 
-# Méthodes sur Execution
+# Execution methods
 e.abort(asUser="admin")
 output = e.get_output(offset=0, maxlines=100)
 state = e.get_state()
 is_running = e.is_running()
-e.refresh()  # recharge les données
+e.refresh()  # reload data
 ```
 
 Tokens
@@ -316,20 +354,20 @@ new_token = rd.tokens.create(user="alice", roles=["admin"], duration="90d", name
 rd.tokens.delete(new_token.id)
 ```
 
-Utilisateurs
+Users
 ```python
 users = rd.users.list()
 me = rd.users.get_current()
 u = rd.users.get("bob")
 roles = rd.users.current_roles()
 
-# Mise à jour via manager ou objet
+# Update via manager or object
 u = rd.users.update("bob", firstName="Bob", lastName="Builder", email="bob@example.com")
-u.roles()            # via l'objet
-u.update(email="new@example.com")  # met à jour et rafraîchit l'objet
+u.roles()            # via the object
+u.update(email="new@example.com")  # updates and refreshes the object
 ```
 
-Système
+System
 ```python
 system = rd.system
 info = system.info()
@@ -339,7 +377,7 @@ system.logstorage.info()
 system.logstorage.incomplete(max=50, offset=0)
 system.logstorage.incomplete_resume()
 
-# Mode exécution (sous-manager)
+# Execution mode (sub-manager)
 system.executions.enable()
 system.executions.disable()
 system.executions.status()
@@ -356,7 +394,7 @@ rd.scheduler.takeover(all_servers=True)
 rd.scheduler.takeover(server_uuid="uuid-123", project="demo", job_id="job-1")
 ```
 
-Métriques
+Metrics
 ```python
 metrics = rd.metrics
 metrics.list()
@@ -364,16 +402,16 @@ metrics.data()
 metrics.healthcheck()
 metrics.ping()
 
-# Plugins installés
+# Installed plugins
 plugins = rd.plugins.list()
 for plugin in plugins:
     print(plugin.name, plugin.service)
 
-# Détail d'un plugin
+# Plugin details
 first = plugins[0]
 detail = rd.plugins.detail(first.service, first.name)
 
-# Webhooks projet et envoi
+# Project webhooks and send
 project = rd.projects.get("demo")
 wh = project.webhooks
 wh.create(
@@ -393,27 +431,28 @@ wh.delete(first_hook.id)
 
 # Key storage (/storage/keys)
 ks = rd.key_storage
-# Créer un secret (password)
+# Create a secret (password)
 ks.create("integration/secret1", content="s3cr3t", content_type="application/x-rundeck-data-password")
-resources = ks.list()  # liste racine
-meta = ks.get_metadata("integration/secret1")
+resources = ks.list()  # root listing
+meta = ks.get("integration/secret1")
+content = meta.content()  # raw bytes
 ks.delete("integration/secret1")
 
 # AdHoc commands/scripts
 project = rd.projects.get("demo")
 exec1 = project.adhoc.run_command("echo 'hello world'")
 exec2 = project.adhoc.run_script("echo 'from script'")
-# exec2.id pour suivre l'exécution
-# Mode stub (sans refresh immédiat) puis refresh manuel
+# exec2.id to track execution
+# Stub mode (no immediate refresh) then manual refresh
 exec_stub = project.adhoc.run_command("echo stub", refresh=False)
-exec_stub.refresh()  # charge l'objet complet
+exec_stub.refresh()  # load the full object
 # Script via multipart (upload)
 exec3 = project.adhoc.run_script(
     script_file=("hello.sh", "echo multipart", "text/plain"),
     refresh=False,
 )
 
-# Features système
+# System features
 features = rd.features.list()
 if features:
     first = features[0]
@@ -421,7 +460,7 @@ if features:
     print(first.name, status.enabled)
 ```
 
-Configuration globale `/config`
+Global configuration `/config`
 ```python
 cfg = rd.config_management
 all_configs = cfg.list()
@@ -433,27 +472,28 @@ cfg.restart()
 
 Pagination
 ----------
-Les managers héritent de `RundeckObjectManager.iter(...)` (offset/max). Exemple :
+Managers inherit `RundeckObjectManager.iter(...)` (offset/max). Example:
 ```python
 for job in rd.jobs.iter(project="demo", page_size=100):
     print(job.id)
 ```
 
-Gestion des erreurs
--------------------
-Les erreurs HTTP passent par `raise_for_status` et lèvent des exceptions dédiées (ex. `RundeckAuthenticationError`, `RundeckNotFoundError`, `RundeckValidationError`, `RundeckConflictError`, `RundeckServerError`). Gérez-les avec un bloc `try/except` autour des appels client.
-
-Développement et tests
-----------------------
-- Formatage/Lint : `black src/rundeck tests/`, `ruff check src/rundeck tests/`
-- Typage : `mypy src/rundeck/`
-- Tests : `pytest`
-- Tests d'intégration locaux : `scripts/run-integration.sh` (démarre docker compose à la racine, exporte par défaut `RUNDECK_URL=http://localhost:4440`, `RUNDECK_TOKEN=adminToken`, `RUNDECK_API_VERSION=56`, attend le healthcheck, lance `poetry run pytest -m integration`). Vous pouvez surcharger les variables d'environnement avant l'appel. Ajoutez `KEEP_STACK=1` pour ne pas arrêter l'instance après les tests. Script de teardown dédié : `scripts/stop-integration.sh`.
-
-Structure du code
------------------
-- `src/rundeck/base.py` : objets/manager génériques, helpers `_build_path`, pagination, CRUD.
-- `src/rundeck/client.py` : client HTTP, méthodes `http_get/post/put/delete/list`.
-- `src/rundeck/v1/objects/` : managers et objets métiers (projects, jobs, executions, system, tokens, users, config_management).
-- Schéma managers/objets : on applique le pattern manager → objet partout où l’API expose une ressource identifiable (jobs, projects, users, tokens, executions, etc.). Pour les endpoints purement globaux ou utilitaires sans ressource (ex. `/system` et ses sous-domaines, `/config`, `/metrics`), on utilise des sous-managers dédiés plutôt que de forcer un objet artificiel.
+Error handling
+--------------
+HTTP errors go through `raise_for_status` and raise dedicated exceptions (e.g., `RundeckAuthenticationError`, `RundeckNotFoundError`, `RundeckValidationError`, `RundeckConflictError`, `RundeckServerError`). Handle them with a `try/except` block around client calls.
+
+Development and testing
+-----------------------
+- Development setup (contributors): clone the repo and run `poetry install`.
+- Formatting/Lint: `black src/rundeck tests/`, `ruff check src/rundeck tests/`
+- Typing: `mypy src/rundeck/`
+- Tests: `pytest`
+- Local integration tests: `scripts/run-integration.sh` (starts docker compose at repo root, exports by default `RUNDECK_URL=http://localhost:4440`, `RUNDECK_TOKEN=adminToken`, `RUNDECK_API_VERSION=56`, waits for the healthcheck, runs `poetry run pytest -m integration`). You can override env vars before running. Add `KEEP_STACK=1` to keep the instance running after tests. Dedicated teardown script: `scripts/stop-integration.sh`.
+
+Code structure
+--------------
+- `src/rundeck/base.py`: generic objects/managers, `_build_path` helpers, pagination, CRUD.
+- `src/rundeck/client.py`: HTTP client, `http_get/post/put/delete/list` methods.
+- `src/rundeck/v1/objects/`: domain managers and objects (projects, jobs, executions, system, tokens, users, config_management).
+- Managers/objects schema: we apply the manager -> object pattern wherever the API exposes an identifiable resource (jobs, projects, users, tokens, executions, etc.). For purely global or utility endpoints without a resource (e.g., `/system` and its subdomains, `/config`, `/metrics`), we use dedicated sub-managers rather than forcing an artificial object.