python-jcli 0.1.0__py3-none-any.whl

jcli/sdk/config.py

@@ -0,0 +1,227 @@
+"""Configuration management for jcli.
+
+Handles loading/saving YAML config, profile CRUD, and environment variable overrides.
+"""
+
+import copy
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+DEFAULT_CONFIG_DIR = Path.home() / ".jcli"
+DEFAULT_CONFIG_FILE = DEFAULT_CONFIG_DIR / "config.yaml"
+
+DEFAULT_PROFILE_NAME = "default"
+
+# Environment variable names
+ENV_URL = "JCLI_URL"
+ENV_USERNAME = "JCLI_USERNAME"
+ENV_API_TOKEN = "JCLI_API_TOKEN"
+ENV_PROFILE = "JCLI_PROFILE"
+
+# Profile field names
+FIELD_URL = "url"
+FIELD_USERNAME = "username"
+FIELD_API_TOKEN = "api_token"
+FIELD_DESCRIPTION = "description"
+
+PROFILE_FIELDS = (FIELD_URL, FIELD_USERNAME, FIELD_API_TOKEN, FIELD_DESCRIPTION)
+
+DEFAULT_CONFIG_TEMPLATE: dict[str, Any] = {
+    "active_profile": DEFAULT_PROFILE_NAME,
+    "profiles": {
+        DEFAULT_PROFILE_NAME: {
+            FIELD_URL: "https://jenkins.example.com",
+            FIELD_USERNAME: "admin",
+            FIELD_API_TOKEN: "your-api-token-here",
+            FIELD_DESCRIPTION: "Default Jenkins instance",
+        }
+    },
+}
+
+
+class ConfigError(Exception):
+    """Raised when configuration operations fail."""
+
+
+class ProfileNotFoundError(ConfigError):
+    """Raised when a requested profile does not exist."""
+
+
+class Config:
+    """Jenkins CLI configuration manager.
+
+    Manages profiles (url, username, api_token, description) stored in YAML.
+    Environment variables (JCLI_URL, JCLI_USERNAME, JCLI_API_TOKEN, JCLI_PROFILE)
+    override config file values when present.
+    """
+
+    def __init__(self, config_path: str | Path | None = None) -> None:
+        self._config_path = Path(config_path) if config_path else DEFAULT_CONFIG_FILE
+        self._data: dict[str, Any] = {}
+        self._loaded = False
+
+    @property
+    def config_path(self) -> Path:
+        return self._config_path
+
+    def load(self) -> "Config":
+        """Load config from disk. Creates default config if file doesn't exist.
+
+        Returns:
+            self, for chaining.
+        """
+        if self._config_path.exists():
+            with open(self._config_path, "r", encoding="utf-8") as f:
+                loaded = yaml.safe_load(f)
+                if loaded and isinstance(loaded, dict):
+                    self._data = loaded
+                else:
+                    self._data = copy.deepcopy(DEFAULT_CONFIG_TEMPLATE)
+        else:
+            self._data = copy.deepcopy(DEFAULT_CONFIG_TEMPLATE)
+            self.save()
+
+        self._loaded = True
+        return self
+
+    def save(self) -> None:
+        """Persist current config to disk, creating parent dirs as needed."""
+        self._config_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(self._config_path, "w", encoding="utf-8") as f:
+            yaml.dump(self._data, f, default_flow_style=False, allow_unicode=True)
+
+    def _ensure_loaded(self) -> None:
+        if not self._loaded:
+            self.load()
+
+    def _get_profiles(self) -> dict[str, dict[str, str]]:
+        self._ensure_loaded()
+        profiles = self._data.get("profiles", {})
+        if not isinstance(profiles, dict):
+            return {}
+        return profiles
+
+    def _apply_env_overrides(self, profile_data: dict[str, str]) -> dict[str, str]:
+        """Apply environment variable overrides to a profile's data.
+
+        Environment variables take precedence over config file values.
+        """
+        result = dict(profile_data)
+
+        env_url = os.environ.get(ENV_URL)
+        if env_url:
+            result[FIELD_URL] = env_url
+
+        env_username = os.environ.get(ENV_USERNAME)
+        if env_username:
+            result[FIELD_USERNAME] = env_username
+
+        env_token = os.environ.get(ENV_API_TOKEN)
+        if env_token:
+            result[FIELD_API_TOKEN] = env_token
+
+        return result
+
+    def get_active_profile_name(self) -> str:
+        """Return the active profile name (env override > config file > default)."""
+        self._ensure_loaded()
+        env_profile = os.environ.get(ENV_PROFILE)
+        if env_profile:
+            return env_profile
+        return self._data.get("active_profile", DEFAULT_PROFILE_NAME)
+
+    def get_active_profile(self) -> dict[str, str]:
+        """Return the active profile data with env overrides applied.
+
+        Raises:
+            ProfileNotFoundError: if the active profile doesn't exist.
+        """
+        name = self.get_active_profile_name()
+        return self.get_profile(name)
+
+    def list_profiles(self) -> dict[str, dict[str, str]]:
+        """Return all profiles (without env overrides)."""
+        return self._get_profiles()
+
+    def get_profile(self, name: str) -> dict[str, str]:
+        """Return a specific profile with env overrides applied.
+
+        Args:
+            name: Profile name.
+
+        Returns:
+            Profile data dict with keys: url, username, api_token, description.
+
+        Raises:
+            ProfileNotFoundError: if profile doesn't exist.
+        """
+        profiles = self._get_profiles()
+        if name not in profiles:
+            raise ProfileNotFoundError(f"Profile '{name}' not found")
+        return self._apply_env_overrides(profiles[name])
+
+    def add_profile(
+        self,
+        name: str,
+        url: str,
+        username: str,
+        api_token: str,
+        description: str = "",
+    ) -> None:
+        """Create or update a profile.
+
+        Args:
+            name: Profile name.
+            url: Jenkins server URL.
+            username: Jenkins username.
+            api_token: Jenkins API token.
+            description: Optional description.
+        """
+        self._ensure_loaded()
+        profiles = self._data.setdefault("profiles", {})
+        profiles[name] = {
+            FIELD_URL: url,
+            FIELD_USERNAME: username,
+            FIELD_API_TOKEN: api_token,
+            FIELD_DESCRIPTION: description,
+        }
+        self.save()
+
+    def remove_profile(self, name: str) -> None:
+        """Remove a profile.
+
+        Args:
+            name: Profile name to remove.
+
+        Raises:
+            ProfileNotFoundError: if profile doesn't exist.
+        """
+        self._ensure_loaded()
+        profiles = self._data.get("profiles", {})
+        if name not in profiles:
+            raise ProfileNotFoundError(f"Profile '{name}' not found")
+        del profiles[name]
+        # If we removed the active profile, reset to default
+        if self._data.get("active_profile") == name:
+            self._data["active_profile"] = DEFAULT_PROFILE_NAME
+        self.save()
+
+    def set_active_profile(self, name: str) -> None:
+        """Set the active profile.
+
+        Args:
+            name: Profile name to activate.
+
+        Raises:
+            ProfileNotFoundError: if profile doesn't exist.
+        """
+        self._ensure_loaded()
+        profiles = self._data.get("profiles", {})
+        if name not in profiles:
+            raise ProfileNotFoundError(f"Profile '{name}' not found")
+        self._data["active_profile"] = name
+        self.save()

jcli/sdk/credential.py

@@ -0,0 +1,143 @@
+"""Jenkins Credential SDK.
+ 
+Provides functions for managing Jenkins credentials via the REST API.
+Default store is ``system``, default domain is ``_`` (global domain).
+ 
+API reference:
+  - List:   GET  /credentials/store/{store}/domain/{domain}/api/json
+  - Get:    GET  /credentials/store/{store}/domain/_/credential/{id}/api/json
+  - Create: POST /credentials/store/{store}/domain/{domain}/createCredentials
+  - Update: POST /credentials/store/{store}/domain/_/credential/{id}/updateCredentials
+  - Delete: POST /credentials/store/{store}/domain/{domain}/credential/{id}/doDelete
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from jcli.sdk.client import JenkinsClient
+
+
+DEFAULT_STORE = "system"
+DEFAULT_DOMAIN = "_"
+
+
+def _build_base_path(store: str, domain: str) -> str:
+    """Build the base path for credential store/domain operations."""
+    return f"/credentials/store/{store}/domain/{domain}"
+
+
+def list_credentials(
+    client: JenkinsClient,
+    store: str = DEFAULT_STORE,
+    domain: str = DEFAULT_DOMAIN,
+    depth: int | None = None,
+) -> Any:
+    """List all credentials in a store/domain.
+
+    Args:
+        client: Jenkins API client.
+        store: Credential store ID (default: ``system``).
+        domain: Credential domain ID (default: ``_``).
+        depth: Optional API depth parameter for nested expansion.
+
+    Returns:
+        Parsed JSON response from Jenkins.
+    """
+    path = f"{_build_base_path(store, domain)}/api/json"
+    params: dict[str, Any] = {}
+    if depth is not None:
+        params["depth"] = str(depth)
+    return client.get_json(path, params=params)
+
+
+def get_credential(
+    client: JenkinsClient,
+    cred_id: str,
+    store: str = DEFAULT_STORE,
+) -> Any:
+    """Get details of a single credential.
+
+    Args:
+        client: Jenkins API client.
+        cred_id: Credential ID.
+        store: Credential store ID (default: ``system``).
+
+    Returns:
+        Parsed JSON response containing credential details.
+    """
+    path = (
+        f"{_build_base_path(store, DEFAULT_DOMAIN)}"
+        f"/credential/{cred_id}/api/json"
+    )
+    return client.get_json(path)
+
+
+def create_credential(
+    client: JenkinsClient,
+    xml_data: str | bytes,
+    store: str = DEFAULT_STORE,
+    domain: str = DEFAULT_DOMAIN,
+) -> Any:
+    """Create a new credential from XML config.
+
+    The XML must follow the Jenkins credentials XStream format for the
+    target credential type (e.g. ``UsernamePasswordCredentialsImpl``).
+
+    Args:
+        client: Jenkins API client.
+        xml_data: Credential XML config (str or bytes).
+        store: Credential store ID (default: ``system``).
+        domain: Credential domain ID (default: ``_``).
+
+    Returns:
+        ``requests.Response`` from the POST request.
+    """
+    path = f"{_build_base_path(store, domain)}/createCredentials"
+    return client.post_xml(path, xml_data)
+
+
+def update_credential(
+    client: JenkinsClient,
+    cred_id: str,
+    xml_data: str | bytes,
+    store: str = DEFAULT_STORE,
+) -> Any:
+    """Update an existing credential.
+
+    Args:
+        client: Jenkins API client.
+        cred_id: Credential ID to update.
+        xml_data: New credential XML config.
+        store: Credential store ID (default: ``system``).
+
+    Returns:
+        ``requests.Response`` from the POST request.
+    """
+    path = (
+        f"{_build_base_path(store, DEFAULT_DOMAIN)}"
+        f"/credential/{cred_id}/updateCredentials"
+    )
+    return client.post_xml(path, xml_data)
+
+
+def delete_credential(
+    client: JenkinsClient,
+    cred_id: str,
+    store: str = DEFAULT_STORE,
+) -> Any:
+    """Delete a credential.
+
+    Args:
+        client: Jenkins API client.
+        cred_id: Credential ID to delete.
+        store: Credential store ID (default: ``system``).
+
+    Returns:
+        ``requests.Response`` from the POST request.
+    """
+    path = (
+        f"{_build_base_path(store, DEFAULT_DOMAIN)}"
+        f"/credential/{cred_id}/doDelete"
+    )
+    return client.post_data(path, data={})

jcli/sdk/exceptions.py

@@ -0,0 +1,59 @@
+"""Jenkins SDK exception hierarchy.
+
+All exceptions inherit from JenkinsError, so callers can catch broadly or narrowly.
+"""
+
+
+class JenkinsError(Exception):
+    """Base exception for all Jenkins-related errors."""
+
+    def __init__(self, message: str = "Jenkins error") -> None:
+        super().__init__(message)
+        self.message = message
+
+
+class JenkinsAuthError(JenkinsError):
+    """Raised when authentication fails (HTTP 401)."""
+
+    def __init__(self, message: str = "Authentication failed (401)") -> None:
+        super().__init__(message)
+
+
+class JenkinsNotFoundError(JenkinsError):
+    """Raised when a resource is not found (HTTP 404)."""
+
+    def __init__(self, message: str = "Resource not found (404)") -> None:
+        super().__init__(message)
+
+
+class JenkinsConnectionError(JenkinsError):
+    """Raised when connection to Jenkins fails or times out."""
+
+    def __init__(self, message: str = "Connection failed") -> None:
+        super().__init__(message)
+
+
+class JenkinsAPIError(JenkinsError):
+    """Raised for non-401/404 API errors.
+
+    Attributes:
+        status_code: HTTP status code from the response.
+    """
+
+    def __init__(self, message: str = "API error", status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class JenkinsConfigError(JenkinsError):
+    """Raised for configuration errors (invalid URL, missing credentials, etc.)."""
+
+    def __init__(self, message: str = "Configuration error") -> None:
+        super().__init__(message)
+
+
+class JenkinsCrumbError(JenkinsError):
+    """Raised when Crumb (CSRF token) fetch fails."""
+
+    def __init__(self, message: str = "Crumb fetch failed") -> None:
+        super().__init__(message)

jcli/sdk/job.py

@@ -0,0 +1,191 @@
+"""Jenkins Job SDK — CRUD and lifecycle operations for Jenkins jobs."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from jcli.sdk.client import JenkinsClient
+
+
+def list_jobs(client: JenkinsClient, depth: int = 0) -> list[dict[str, Any]]:
+    """List all jobs with name, url, and color.
+
+    Args:
+        client: Authenticated JenkinsClient instance.
+        depth: Recursion depth for folder jobs (0 = top-level only).
+
+    Returns:
+        List of job dicts with keys: name, url, color.
+    """
+    data = client.get_json("/api/json", tree="jobs[name,url,color]")
+    return data.get("jobs", [])
+
+
+def get_job(client: JenkinsClient, name: str) -> dict[str, Any]:
+    """Get full details for a specific job.
+
+    Args:
+        client: Authenticated JenkinsClient instance.
+        name: Job name (URL-encoding is handled by the client).
+
+    Returns:
+        Job details dict as returned by the Jenkins REST API.
+
+    Raises:
+        JenkinsNotFoundError: If the job does not exist.
+    """
+    return client.get_json(f"/job/{name}/api/json")
+
+
+def create_job(client: JenkinsClient, name: str, config_xml: str) -> None:
+    """Create a new job from an XML configuration string.
+
+    Args:
+        client: Authenticated JenkinsClient instance.
+        name: Name for the new job.
+        config_xml: Jenkins job config XML as a string.
+
+    Raises:
+        JenkinsAPIError: On creation failure (e.g. duplicate name, bad XML).
+    """
+    client.post_xml(f"/createItem?name={name}", config_xml)
+
+
+def delete_job(client: JenkinsClient, name: str) -> None:
+    """Delete a job.
+
+    Args:
+        client: Authenticated JenkinsClient instance.
+        name: Name of the job to delete.
+
+    Raises:
+        JenkinsNotFoundError: If the job does not exist.
+    """
+    client.post_data(f"/job/{name}/doDelete", data={})
+
+
+def copy_job(client: JenkinsClient, from_name: str, new_name: str) -> None:
+    """Copy an existing job to a new name.
+
+    Args:
+        client: Authenticated JenkinsClient instance.
+        from_name: Source job name.
+        new_name: Name for the copied job.
+
+    Raises:
+        JenkinsNotFoundError: If the source job does not exist.
+    """
+    client.post_data(
+        "/createItem",
+        data={"name": new_name, "mode": "copy", "from": from_name},
+    )
+
+
+def rename_job(
+    client: "JenkinsClient",
+    old_name: str,
+    new_name: str,
+) -> Any:
+    """Rename a job.
+
+    Args:
+        client: Jenkins API client.
+        old_name: Current job name.
+        new_name: New job name.
+
+    Returns:
+        Response from Jenkins (redirect on success).
+
+    Raises:
+        JenkinsNotFoundError: If the job does not exist.
+    """
+    path = f"/job/{old_name}/doRename"
+    return client.request("POST", path, params={"newName": new_name})
+
+
+def enable_job(client: JenkinsClient, name: str) -> None:
+    """Enable a disabled job.
+
+    Args:
+        client: Authenticated JenkinsClient instance.
+        name: Name of the job to enable.
+
+    Raises:
+        JenkinsNotFoundError: If the job does not exist.
+    """
+    client.post_data(f"/job/{name}/enable", data={})
+
+
+def disable_job(client: JenkinsClient, name: str) -> None:
+    """Disable a job.
+
+    Args:
+        client: Authenticated JenkinsClient instance.
+        name: Name of the job to disable.
+
+    Raises:
+        JenkinsNotFoundError: If the job does not exist.
+    """
+    client.post_data(f"/job/{name}/disable", data={})
+
+
+def update_job_config(
+    client: JenkinsClient,
+    name: str,
+    config_xml: str,
+) -> Any:
+    """Update a job's configuration.
+
+    Args:
+        client: Jenkins API client.
+        name: Job name.
+        config_xml: New XML configuration.
+
+    Returns:
+        Response from Jenkins.
+    """
+    return client.post_xml(f"/job/{name}/config.xml", config_xml)
+
+
+def get_job_config(client: JenkinsClient, name: str) -> str:
+    """Retrieve the XML configuration for a job.
+
+    Args:
+        client: Authenticated JenkinsClient instance.
+        name: Name of the job.
+
+    Returns:
+        Job configuration as an XML string.
+
+    Raises:
+        JenkinsNotFoundError: If the job does not exist.
+    """
+    resp = client.request("GET", f"/job/{name}/config.xml")
+    return resp.text
+
+
+def create_folder(client: JenkinsClient, name: str) -> Any:
+    """Create a Jenkins folder.
+
+    Args:
+        client: Jenkins API client.
+        name: Folder name.
+
+    Returns:
+        Response from Jenkins.
+    """
+    path = f"/createItem?name={name}&mode=com.cloudbees.hudson.plugins.folder.Folder"
+    return client.request("POST", path)
+
+
+def delete_folder(client: JenkinsClient, name: str) -> Any:
+    """Delete a Jenkins folder and all its contents.
+
+    Args:
+        client: Jenkins API client.
+        name: Folder name.
+
+    Returns:
+        Response from Jenkins.
+    """
+    return client.request("POST", f"/job/{name}/doDelete")