charmarr-lib-core 0.12.2__py3-none-any.whl

charmarr_lib/core/__init__.py

@@ -0,0 +1,126 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Core libraries for Charmarr charms."""
+
+from charmarr_lib.core._arr import (
+    ApplicationConfigBuilder,
+    ArrApiClient,
+    ArrApiConnectionError,
+    ArrApiError,
+    ArrApiResponseError,
+    BaseArrApiClient,
+    DownloadClientConfigBuilder,
+    DownloadClientResponse,
+    HostConfigResponse,
+    MediaIndexerClient,
+    MediaManagerConnection,
+    QualityProfileResponse,
+    RecyclarrError,
+    RootFolderResponse,
+    SecretGetter,
+    config_has_api_key,
+    generate_api_key,
+    read_api_key,
+    reconcile_config_xml,
+    reconcile_download_clients,
+    reconcile_external_url,
+    reconcile_media_manager_connections,
+    reconcile_root_folder,
+    sync_trash_profiles,
+    update_api_key,
+)
+from charmarr_lib.core._juju import (
+    all_events,
+    ensure_pebble_user,
+    get_config_hash,
+    get_secret_rotation_policy,
+    observe_events,
+    reconcilable_events_k8s,
+    reconcilable_events_k8s_workloadless,
+    sync_secret_rotation_policy,
+)
+from charmarr_lib.core._k8s import (
+    K8sResourceManager,
+    PermissionCheckResult,
+    PermissionCheckStatus,
+    ReconcileResult,
+    check_storage_permissions,
+    delete_permission_check_job,
+    is_hardware_device_mounted,
+    is_storage_mounted,
+    reconcile_hardware_transcoding,
+    reconcile_storage_volume,
+)
+from charmarr_lib.core._variant import (
+    get_default_trash_profiles,
+    get_root_folder,
+)
+from charmarr_lib.core.constants import (
+    MEDIA_MANAGER_IMPLEMENTATIONS,
+    MEDIA_TYPE_DOWNLOAD_PATHS,
+)
+from charmarr_lib.core.enums import (
+    ContentVariant,
+    DownloadClient,
+    DownloadClientType,
+    MediaIndexer,
+    MediaManager,
+    RequestManager,
+)
+
+__all__ = [
+    "MEDIA_MANAGER_IMPLEMENTATIONS",
+    "MEDIA_TYPE_DOWNLOAD_PATHS",
+    "ApplicationConfigBuilder",
+    "ArrApiClient",
+    "ArrApiConnectionError",
+    "ArrApiError",
+    "ArrApiResponseError",
+    "BaseArrApiClient",
+    "ContentVariant",
+    "DownloadClient",
+    "DownloadClientConfigBuilder",
+    "DownloadClientResponse",
+    "DownloadClientType",
+    "HostConfigResponse",
+    "K8sResourceManager",
+    "MediaIndexer",
+    "MediaIndexerClient",
+    "MediaManager",
+    "MediaManagerConnection",
+    "PermissionCheckResult",
+    "PermissionCheckStatus",
+    "QualityProfileResponse",
+    "ReconcileResult",
+    "RecyclarrError",
+    "RequestManager",
+    "RootFolderResponse",
+    "SecretGetter",
+    "all_events",
+    "check_storage_permissions",
+    "config_has_api_key",
+    "delete_permission_check_job",
+    "ensure_pebble_user",
+    "generate_api_key",
+    "get_config_hash",
+    "get_default_trash_profiles",
+    "get_root_folder",
+    "get_secret_rotation_policy",
+    "is_hardware_device_mounted",
+    "is_storage_mounted",
+    "observe_events",
+    "read_api_key",
+    "reconcilable_events_k8s",
+    "reconcilable_events_k8s_workloadless",
+    "reconcile_config_xml",
+    "reconcile_download_clients",
+    "reconcile_external_url",
+    "reconcile_hardware_transcoding",
+    "reconcile_media_manager_connections",
+    "reconcile_root_folder",
+    "reconcile_storage_volume",
+    "sync_secret_rotation_policy",
+    "sync_trash_profiles",
+    "update_api_key",
+]

charmarr_lib/core/_arr/__init__.py

@@ -0,0 +1,72 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""API clients, config builders, and reconcilers for *ARR applications."""
+
+from charmarr_lib.core._arr._arr_client import (
+    ArrApiClient,
+    DownloadClientResponse,
+    HostConfigResponse,
+    QualityProfileResponse,
+    RootFolderResponse,
+)
+from charmarr_lib.core._arr._base_client import (
+    ArrApiConnectionError,
+    ArrApiError,
+    ArrApiResponseError,
+    BaseArrApiClient,
+)
+from charmarr_lib.core._arr._config_builders import (
+    ApplicationConfigBuilder,
+    DownloadClientConfigBuilder,
+    SecretGetter,
+)
+from charmarr_lib.core._arr._config_xml import (
+    config_has_api_key,
+    generate_api_key,
+    read_api_key,
+    reconcile_config_xml,
+    update_api_key,
+)
+from charmarr_lib.core._arr._protocols import (
+    MediaIndexerClient,
+    MediaManagerConnection,
+)
+from charmarr_lib.core._arr._reconcilers import (
+    reconcile_download_clients,
+    reconcile_external_url,
+    reconcile_media_manager_connections,
+    reconcile_root_folder,
+)
+from charmarr_lib.core._arr._recyclarr import (
+    RecyclarrError,
+    sync_trash_profiles,
+)
+
+__all__ = [
+    "ApplicationConfigBuilder",
+    "ArrApiClient",
+    "ArrApiConnectionError",
+    "ArrApiError",
+    "ArrApiResponseError",
+    "BaseArrApiClient",
+    "DownloadClientConfigBuilder",
+    "DownloadClientResponse",
+    "HostConfigResponse",
+    "MediaIndexerClient",
+    "MediaManagerConnection",
+    "QualityProfileResponse",
+    "RecyclarrError",
+    "RootFolderResponse",
+    "SecretGetter",
+    "config_has_api_key",
+    "generate_api_key",
+    "read_api_key",
+    "reconcile_config_xml",
+    "reconcile_download_clients",
+    "reconcile_external_url",
+    "reconcile_media_manager_connections",
+    "reconcile_root_folder",
+    "sync_trash_profiles",
+    "update_api_key",
+]

charmarr_lib/core/_arr/_arr_client.py

@@ -0,0 +1,154 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""API client for Radarr, Sonarr, and Lidarr (/api/v3)."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from charmarr_lib.core._arr._base_client import RESPONSE_MODEL_CONFIG, BaseArrApiClient
+
+
+class DownloadClientResponse(BaseModel):
+    """Download client response from *arr API."""
+
+    model_config = RESPONSE_MODEL_CONFIG
+
+    id: int
+    name: str
+    enable: bool
+    protocol: str
+    implementation: str
+
+
+class RootFolderResponse(BaseModel):
+    """Root folder response from *arr API."""
+
+    model_config = RESPONSE_MODEL_CONFIG
+
+    id: int
+    path: str
+    accessible: bool
+
+
+class QualityProfileResponse(BaseModel):
+    """Quality profile response from *arr API."""
+
+    model_config = RESPONSE_MODEL_CONFIG
+
+    id: int
+    name: str
+
+
+class HostConfigResponse(BaseModel):
+    """Host configuration response from *arr API."""
+
+    model_config = RESPONSE_MODEL_CONFIG
+
+    id: int
+    bind_address: str = Field(alias="bindAddress")
+    port: int
+    url_base: str | None = Field(default=None, alias="urlBase")
+
+
+class ArrApiClient(BaseArrApiClient):
+    """API client for Radarr, Sonarr, and Lidarr (/api/v3).
+
+    Provides methods for managing download clients, root folders,
+    quality profiles, and host configuration.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+    ) -> None:
+        """Initialize the v3 API client.
+
+        Args:
+            base_url: Base URL of the arr application (e.g., "http://localhost:7878")
+            api_key: API key for authentication
+            timeout: Request timeout in seconds
+            max_retries: Maximum number of retries for transient failures
+        """
+        super().__init__(
+            base_url=base_url,
+            api_key=api_key,
+            api_version="v3",
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+
+    # Download Clients
+
+    def get_download_clients(self) -> list[DownloadClientResponse]:
+        """Get all configured download clients."""
+        return self._get_validated_list("/downloadclient", DownloadClientResponse)
+
+    def get_download_client(self, client_id: int) -> dict[str, Any]:
+        """Get a download client by ID as raw dict.
+
+        Args:
+            client_id: ID of the download client
+        """
+        return self._get(f"/downloadclient/{client_id}")
+
+    def add_download_client(self, config: dict[str, Any]) -> DownloadClientResponse:
+        """Add a new download client.
+
+        Args:
+            config: Download client configuration payload
+        """
+        return self._post_validated("/downloadclient", config, DownloadClientResponse)
+
+    def update_download_client(
+        self, client_id: int, config: dict[str, Any]
+    ) -> DownloadClientResponse:
+        """Update an existing download client.
+
+        Args:
+            client_id: ID of the download client to update
+            config: Updated download client configuration
+        """
+        config_with_id = {**config, "id": client_id}
+        return self._put_validated(
+            f"/downloadclient/{client_id}", config_with_id, DownloadClientResponse
+        )
+
+    def delete_download_client(self, client_id: int) -> None:
+        """Delete a download client.
+
+        Args:
+            client_id: ID of the download client to delete
+        """
+        self._delete(f"/downloadclient/{client_id}")
+
+    # Root Folders
+
+    def get_root_folders(self) -> list[RootFolderResponse]:
+        """Get all configured root folders."""
+        return self._get_validated_list("/rootfolder", RootFolderResponse)
+
+    def add_root_folder(self, path: str) -> RootFolderResponse:
+        """Add a new root folder.
+
+        Args:
+            path: Filesystem path for the root folder
+        """
+        return self._post_validated("/rootfolder", {"path": path}, RootFolderResponse)
+
+    # Quality Profiles (read-only for media-manager relation)
+
+    def get_quality_profiles(self) -> list[QualityProfileResponse]:
+        """Get all configured quality profiles."""
+        return self._get_validated_list("/qualityprofile", QualityProfileResponse)
+
+    # Host Config (get_host_config_raw and update_host_config are in BaseArrApiClient)
+
+    def get_host_config(self) -> HostConfigResponse:
+        """Get host configuration with typed response."""
+        return self._get_validated("/config/host", HostConfigResponse)

charmarr_lib/core/_arr/_base_client.py

@@ -0,0 +1,314 @@
+# Copyright 2025 The Charmarr Project
+# See LICENSE file for licensing details.
+
+"""Base API client for *arr applications."""
+
+import logging
+from typing import Any, Self
+
+import httpx
+from pydantic import BaseModel, ConfigDict
+from tenacity import (
+    retry,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+logger = logging.getLogger(__name__)
+
+# Response models use extra="allow" to accept unknown fields from the API.
+# This ensures forward compatibility when *arr APIs add new fields, while
+# still providing type safety for the fields we actually use.
+RESPONSE_MODEL_CONFIG = ConfigDict(extra="allow", populate_by_name=True)
+
+
+class ArrApiError(Exception):
+    """Base exception for arr API errors."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class ArrApiConnectionError(ArrApiError):
+    """Raised when connection to the API fails."""
+
+
+class ArrApiResponseError(ArrApiError):
+    """Raised when the API returns an error response."""
+
+
+class BaseArrApiClient:
+    """Shared HTTP mechanics for all arr applications.
+
+    Provides common HTTP patterns for interacting with *arr application APIs.
+    Handles session management, API key authentication, and error handling
+    with exponential backoff retries for transient failures.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        api_version: str,
+        *,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+    ) -> None:
+        """Initialize the API client.
+
+        Args:
+            base_url: Base URL of the arr application (e.g., "http://localhost:7878")
+            api_key: API key for authentication
+            api_version: API version string (e.g., "v3" for Radarr, "v1" for Prowlarr)
+            timeout: Request timeout in seconds
+            max_retries: Maximum number of retries for transient failures
+        """
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._api_version = api_version
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._client: httpx.Client | None = None
+
+    @property
+    def client(self) -> httpx.Client:
+        """Get or create the HTTP client with configured headers."""
+        if self._client is None:
+            self._client = httpx.Client(
+                headers={"X-Api-Key": self._api_key},
+                timeout=self._timeout,
+            )
+        return self._client
+
+    def close(self) -> None:
+        """Close the HTTP client and release resources."""
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+    def __enter__(self) -> Self:
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit - close client."""
+        self.close()
+
+    def _url(self, endpoint: str) -> str:
+        """Build full URL for an API endpoint.
+
+        Args:
+            endpoint: API endpoint path (e.g., "/downloadclient")
+
+        Returns:
+            Full URL including base URL and API version prefix
+        """
+        endpoint = endpoint.lstrip("/")
+        return f"{self._base_url}/api/{self._api_version}/{endpoint}"
+
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        """Make an HTTP request with exponential backoff retry.
+
+        Args:
+            method: HTTP method (GET, POST, PUT, DELETE)
+            endpoint: API endpoint path
+            json: JSON body for POST/PUT requests
+            params: Query parameters
+
+        Returns:
+            HTTP response object
+
+        Raises:
+            ArrApiConnectionError: If connection fails after all retries
+            ArrApiResponseError: If the API returns an error response
+        """
+        url = self._url(endpoint)
+
+        @retry(
+            retry=retry_if_exception_type((httpx.ConnectError, httpx.TimeoutException)),
+            stop=stop_after_attempt(self._max_retries),
+            wait=wait_exponential(multiplier=1, min=1, max=10),
+            reraise=True,
+        )
+        def _do_request() -> httpx.Response:
+            response = self.client.request(
+                method=method,
+                url=url,
+                json=json,
+                params=params,
+            )
+            response.raise_for_status()
+            return response
+
+        try:
+            return _do_request()
+        except httpx.ConnectError as e:
+            raise ArrApiConnectionError(
+                f"Failed to connect to {url} after {self._max_retries} attempts"
+            ) from e
+        except httpx.TimeoutException as e:
+            raise ArrApiConnectionError(
+                f"Request to {url} timed out after {self._max_retries} attempts"
+            ) from e
+        except httpx.HTTPStatusError as e:
+            raise ArrApiResponseError(
+                f"API request failed: {e.response.status_code} {e.response.reason_phrase}",
+                status_code=e.response.status_code,
+            ) from e
+
+    def _get(self, endpoint: str, *, params: dict[str, Any] | None = None) -> Any:
+        """Make a GET request and return JSON response.
+
+        Args:
+            endpoint: API endpoint path
+            params: Optional query parameters
+
+        Returns:
+            Parsed JSON response (dict or list)
+        """
+        response = self._request("GET", endpoint, params=params)
+        return response.json()
+
+    def _post(self, endpoint: str, json: dict[str, Any]) -> dict[str, Any]:
+        """Make a POST request and return JSON response.
+
+        Args:
+            endpoint: API endpoint path
+            json: JSON body to send
+
+        Returns:
+            Parsed JSON response
+        """
+        response = self._request("POST", endpoint, json=json)
+        return response.json()
+
+    def _put(self, endpoint: str, json: dict[str, Any]) -> dict[str, Any]:
+        """Make a PUT request and return JSON response.
+
+        Args:
+            endpoint: API endpoint path
+            json: JSON body to send
+
+        Returns:
+            Parsed JSON response
+        """
+        response = self._request("PUT", endpoint, json=json)
+        return response.json()
+
+    def _delete(self, endpoint: str) -> None:
+        """Make a DELETE request.
+
+        Args:
+            endpoint: API endpoint path
+        """
+        self._request("DELETE", endpoint)
+
+    def _get_validated[ModelT: BaseModel](
+        self,
+        endpoint: str,
+        response_model: type[ModelT],
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> ModelT:
+        """Make a GET request and validate response against a Pydantic model.
+
+        Args:
+            endpoint: API endpoint path
+            response_model: Pydantic model class to validate against
+            params: Optional query parameters
+
+        Returns:
+            Validated Pydantic model instance
+        """
+        data = self._get(endpoint, params=params)
+        return response_model.model_validate(data)
+
+    def _get_validated_list[ModelT: BaseModel](
+        self,
+        endpoint: str,
+        item_model: type[ModelT],
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> list[ModelT]:
+        """Make a GET request and validate response as a list of Pydantic models.
+
+        Args:
+            endpoint: API endpoint path
+            item_model: Pydantic model class for list items
+            params: Optional query parameters
+
+        Returns:
+            List of validated Pydantic model instances
+        """
+        data = self._get(endpoint, params=params)
+        return [item_model.model_validate(item) for item in data]
+
+    def _post_validated[ModelT: BaseModel](
+        self,
+        endpoint: str,
+        json: dict[str, Any],
+        response_model: type[ModelT],
+    ) -> ModelT:
+        """Make a POST request and validate response against a Pydantic model.
+
+        Args:
+            endpoint: API endpoint path
+            json: JSON body to send
+            response_model: Pydantic model class to validate against
+
+        Returns:
+            Validated Pydantic model instance
+        """
+        data = self._post(endpoint, json)
+        return response_model.model_validate(data)
+
+    def _put_validated[ModelT: BaseModel](
+        self,
+        endpoint: str,
+        json: dict[str, Any],
+        response_model: type[ModelT],
+    ) -> ModelT:
+        """Make a PUT request and validate response against a Pydantic model.
+
+        Args:
+            endpoint: API endpoint path
+            json: JSON body to send
+            response_model: Pydantic model class to validate against
+
+        Returns:
+            Validated Pydantic model instance
+        """
+        data = self._put(endpoint, json)
+        return response_model.model_validate(data)
+
+    def get_host_config_raw(self) -> dict[str, Any]:
+        """Get host configuration as raw dict.
+
+        All *arr applications have a /config/host endpoint that returns
+        settings like bindAddress, port, urlBase, and applicationUrl.
+        """
+        return self._get("/config/host")
+
+    def update_host_config(self, config: dict[str, Any]) -> dict[str, Any]:
+        """Update host configuration.
+
+        Merges provided config with current settings and PUTs the result.
+
+        Args:
+            config: Host configuration settings to update
+
+        Returns:
+            Updated host configuration
+        """
+        current = self._get("/config/host")
+        updated = {**current, **config}
+        return self._put("/config/host", updated)