redfish-python-sdk 1.0.0__py3-none-any.whl

redfish_sdk/managers/account.py

@@ -0,0 +1,96 @@
+"""
+Account service manager — manages user accounts and roles.
+
+Provides:
+- List accounts
+- List roles
+- Add account
+- Update account
+- Delete account
+
+"""
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, List
+
+from ..models.account import Account, Role
+
+if TYPE_CHECKING:
+    from ..client import RedfishClient
+
+logger = logging.getLogger(__name__)
+
+
+class AccountServiceManager:
+    """
+    Manages Redfish Account resources.
+
+    """
+
+    def __init__(self, client: RedfishClient):
+        self._client = client
+        self._http = client._http_client
+
+    def accounts(self) -> List[Account]:
+        """
+        Get the list of user accounts.
+
+        """
+        account_service = self._client._get_account_service()
+        return self._client._get_collection(account_service.accounts.odata_id, Account)
+
+    def roles(self) -> List[Role]:
+        """
+        Get the list of user roles.
+
+        """
+        account_service = self._client._get_account_service()
+        return self._client._get_collection(account_service.roles.odata_id, Role)
+
+    def add(self, account: Account) -> Account:
+        """
+        Create a new user account.
+
+
+        Args:
+            account: Account model with UserName, Password, RoleId, Enabled fields
+
+        Returns:
+            Created account resource
+        """
+        account_service = self._client._get_account_service()
+        return self._http.post(
+            account_service.accounts.odata_id, Account, body=account
+        )
+
+    def update(self, username: str, account: Account) -> Account:
+        """
+        Update an existing user account.
+
+
+        Args:
+            username: Username of the account to update
+            account: Account model with fields to update
+
+        Returns:
+            Updated account resource
+        """
+        account_service = self._client._get_account_service()
+        path = f"{account_service.accounts.odata_id}/{username}"
+        return self._http.patch(path, Account, account)
+
+    def delete(self, username: str) -> str:
+        """
+        Delete a user account.
+
+
+        Args:
+            username: Username of the account to delete
+
+        Returns:
+            Response body (usually empty)
+        """
+        account_service = self._client._get_account_service()
+        path = f"{account_service.accounts.odata_id}/{username}"
+        return self._http.delete(path)

redfish_sdk/managers/chassis.py

@@ -0,0 +1,327 @@
+"""
+Chassis manager — manages physical server enclosure resources.
+
+Provides access to:
+- Chassis info (manufacturer, model, serial number, power state)
+- Thermal data (fan speeds, temperatures)
+- Power data (PSUs, voltage, power control)
+- Drives (HDDs/SSDs/NVMe with multi-vendor fallback)
+- Network adapters (NICs)
+- PCIe devices (GPU, HBA, etc.)
+- FRU service data
+
+"""
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, List, Optional
+
+from ..exceptions import (
+    RedfishException,
+    RedfishNotFoundError,
+    RedfishValidationError,
+)
+from ..models.chassis import (
+    Chassis,
+    Drive,
+    NetworkAdapter,
+    PCIeDevice,
+    Power,
+    Thermal,
+)
+from ..models.thermal import InletHistoryTemperature
+
+if TYPE_CHECKING:
+    from ..client import RedfishClient
+
+logger = logging.getLogger(__name__)
+
+# Allowed IndicatorLED states per Redfish spec.
+_INDICATOR_LED_STATES = ("Lit", "Blinking", "Off")
+
+
+class ChassisManager:
+    """
+    Manages Redfish Chassis resources.
+
+
+    """
+
+    def __init__(self, client: RedfishClient):
+        self._client = client
+        self._http = client._http_client
+
+    def get(self, chassis_id: str = "1") -> Chassis:
+        """
+        Get a chassis resource by ID.
+
+        Special handling: if the chassis collection URL already ends with "/{id}",
+        use it directly to avoid double-appending (some vendors return the direct path).
+
+
+
+        Args:
+            chassis_id: Chassis ID (default "1")
+
+        Returns:
+            Chassis resource
+        """
+        odata_id = self._client._get_chassis_collection_odata_id()
+
+        # If the collection odata_id already points to a specific chassis (ends with /1)
+        # use it directly; otherwise append the chassis_id
+        if odata_id.endswith(f"/{chassis_id}"):
+            return self._http.get(odata_id, Chassis)
+
+        return self._http.get(f"{odata_id}/{chassis_id}", Chassis)
+
+    def thermal(self, chassis_id: str = "1") -> Thermal:
+        """
+        Get thermal information (fans and temperatures) for a chassis.
+
+
+        """
+        chassis = self.get(chassis_id)
+        return self._http.get(chassis.thermal.odata_id, Thermal)
+
+    def inlet_history_temperature(self, chassis_id: str = "1") -> Optional[InletHistoryTemperature]:
+        """
+        Get air inlet historical temperature samples for a chassis.
+
+        Discovery flow:
+          1. Fetch the Thermal resource via ``thermal(chassis_id)``.
+          2. Read ``Thermal.inlet_history_temperature.odata_id``.
+          3. GET that URL and parse as :class:`InletHistoryTemperature`.
+
+        Returns ``None`` when the sub-resource is not advertised by the BMC
+        or returns 404 (vendor does not implement it). Other transport errors
+        (auth failure, network issues, etc.) propagate to the caller.
+
+        Args:
+            chassis_id: Chassis ID (default "1")
+
+        Returns:
+            InletHistoryTemperature model, or None when not supported.
+        """
+        thermal = self.thermal(chassis_id)
+        if thermal.inlet_history_temperature is None:
+            logger.debug("Thermal resource has no InletHistoryTemperature link")
+            return None
+
+        odata_id = thermal.inlet_history_temperature.odata_id
+        try:
+            return self._http.get(odata_id, InletHistoryTemperature)
+        except RedfishNotFoundError as exc:
+            logger.debug("InletHistoryTemperature not found at %s: %s", odata_id, exc)
+            return None
+
+    def power(self, chassis_id: str = "1") -> Power:
+        """
+        Get power information (PSUs and power controls) for a chassis.
+
+
+        """
+        chassis = self.get(chassis_id)
+        return self._http.get(chassis.power.odata_id, Power)
+
+    def drives(self, chassis_id: str = "1") -> List[Drive]:
+        """
+        Get the list of physical drives in a chassis.
+
+        Multi-vendor fallback strategy:
+        1. Try Chassis.Links.Drives[0] as a collection endpoint
+        2. If that returns empty/no members, fetch each link individually
+        3. Fall back to Chassis.Drives if Links.Drives is not set
+
+
+        multi-vendor fallback logic.
+
+        Returns:
+            List of Drive objects
+        """
+        chassis = self.get(chassis_id)
+
+        # Strategy 1: Use Chassis.Links.Drives
+        if chassis.links and chassis.links.drives:
+            drive_links = chassis.links.drives
+            if drive_links:
+                # Try first link as a collection endpoint
+                first_link = drive_links[0]
+                try:
+                    drives = self._client._get_collection(first_link.odata_id, Drive)
+                    if drives:
+                        return drives
+                except RedfishException:
+                    pass
+
+                # If collection is empty, fetch each link individually
+                result = []
+                for link in drive_links:
+                    try:
+                        drive = self._http.get(link.odata_id, Drive)
+                        if drive:
+                            result.append(drive)
+                    except RedfishException as exc:
+                        logger.warning("Failed to fetch drive %s: %s", link.odata_id, exc)
+
+                if result:
+                    return result
+
+        # Strategy 2: Use Chassis.Drives collection endpoint
+        if chassis.drives:
+            try:
+                return self._client._get_collection(chassis.drives.odata_id, Drive)
+            except RedfishException as exc:
+                logger.warning("Chassis.Drives collection failed: %s", exc)
+
+        return []
+
+    def network_adapters(self, chassis_id: str = "1") -> List[NetworkAdapter]:
+        """
+        Get the list of network adapters (NICs) in a chassis.
+
+
+        """
+        chassis = self.get(chassis_id)
+        return self._client._get_collection(chassis.network_adapters.odata_id, NetworkAdapter)
+
+    def pcie_devices(self, chassis_id: str = "1") -> List[PCIeDevice]:
+        """
+        Get the list of PCIe devices in a chassis.
+
+        Multi-vendor fallback strategy:
+        1. Try Chassis.PCIeDevices collection endpoint
+        2. Fall back to Chassis.Links.PCIeDevices (individual links)
+
+
+
+        Returns:
+            List of PCIeDevice objects
+        """
+        chassis = self.get(chassis_id)
+
+        # Strategy 1: Use Chassis.PCIeDevices collection endpoint
+        if chassis.pcie_devices:
+            try:
+                return self._client._get_collection(chassis.pcie_devices.odata_id, PCIeDevice)
+            except RedfishException as exc:
+                logger.warning("Chassis.PCIeDevices collection failed: %s", exc)
+
+        # Strategy 2: Use Chassis.Links.PCIeDevices individual links
+        if chassis.links and chassis.links.pcie_devices:
+            return self._client._get_list(chassis.links.pcie_devices, PCIeDevice)
+
+        return []
+
+    def fru_service(self, chassis_id: str = "1") -> List[dict]:
+        """
+        Get FRU service data from the chassis OEM extension.
+
+        This is a vendor-specific (华为 iBMC) feature that provides
+        detailed FRU board info via /redfish/v1/Chassis/{id}/FruService.
+
+
+
+        Returns:
+            List of raw FRU service data dicts
+        """
+        chassis = self.get(chassis_id)
+        if chassis.oem is None or chassis.oem.fru_service is None:
+            return []
+
+        fru_service_url = chassis.oem.fru_service
+        try:
+            collection_raw = self._http.get_raw(fru_service_url)
+            members = collection_raw.get("Members", [])
+            results = []
+            for member in members:
+                member_id = member.get("@odata.id")
+                if member_id:
+                    try:
+                        fru_data = self._http.get_raw(member_id)
+                        results.append(fru_data)
+                    except RedfishException as exc:
+                        logger.warning("Failed to fetch FRU service %s: %s", member_id, exc)
+            return results
+        except RedfishException as exc:
+            logger.warning("FRU service collection failed: %s", exc)
+            return []
+
+    def fru_service_board(self, chassis_id: str = "1") -> Optional[dict]:
+        """
+        Get the primary FRU board info (the '/0' member of the FRU service collection).
+
+
+        """
+        chassis = self.get(chassis_id)
+        if chassis.oem is None or chassis.oem.fru_service is None:
+            return None
+
+        fru_service_url = chassis.oem.fru_service
+        try:
+            collection_raw = self._http.get_raw(fru_service_url)
+            members = collection_raw.get("Members", [])
+            for member in members:
+                member_id = member.get("@odata.id", "")
+                if member_id.endswith("/0"):
+                    return self._http.get_raw(member_id)
+        except RedfishException as exc:
+            logger.warning("FRU service board fetch failed: %s", exc)
+
+        return None
+
+    # ------------------------------------------------------------------
+    # IndicatorLED write helpers
+    # ------------------------------------------------------------------
+
+    def set_indicator_led(self, state: str, chassis_id: str = "1") -> str:
+        """
+        Set the chassis IndicatorLED state via PATCH.
+
+        Reads the chassis first so the HTTP layer has a fresh ETag for If-Match.
+
+        Args:
+            state: One of "Lit", "Blinking", "Off".
+            chassis_id: Chassis ID (default "1").
+
+        Returns:
+            The IndicatorLED value after the patch (re-read from BMC).
+
+        Raises:
+            RedfishValidationError: If ``state`` is not an allowed value.
+        """
+        _validate_indicator_led_state(state)
+        chassis = self.get(chassis_id)
+        logger.info("PATCH IndicatorLED=%s on %s", state, chassis.odata_id)
+        self._http.patch_raw(chassis.odata_id, {"IndicatorLED": state})
+        return self.get(chassis_id).indicator_led
+
+    def set_drive_indicator_led(self, drive_odata_id: str, state: str) -> str:
+        """
+        Set a Drive IndicatorLED state via PATCH on the drive resource.
+
+        Args:
+            drive_odata_id: Full ``@odata.id`` of the drive resource.
+            state: One of "Lit", "Blinking", "Off".
+
+        Returns:
+            The IndicatorLED value after the patch (re-read from BMC).
+
+        Raises:
+            RedfishValidationError: If ``state`` is not an allowed value.
+        """
+        _validate_indicator_led_state(state)
+        # Refresh ETag before PATCH.
+        drive_before = self._http.get(drive_odata_id, Drive)
+        logger.info("PATCH IndicatorLED=%s on %s", state, drive_before.odata_id)
+        self._http.patch_raw(drive_odata_id, {"IndicatorLED": state})
+        drive_after = self._http.get(drive_odata_id, Drive)
+        return drive_after.indicator_led
+
+
+def _validate_indicator_led_state(state: str) -> None:
+    if state not in _INDICATOR_LED_STATES:
+        raise RedfishValidationError(
+            f"Invalid IndicatorLED state '{state}'. "
+            f"Allowed values: {list(_INDICATOR_LED_STATES)}"
+        )

redfish_sdk/managers/event.py

@@ -0,0 +1,264 @@
+"""
+Event service manager — manages event subscriptions.
+
+"""
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+from ..exceptions import RedfishValidationError
+from ..models.event import EventService, Subscription
+
+if TYPE_CHECKING:
+    from ..client import RedfishClient
+
+logger = logging.getLogger(__name__)
+
+
+class EventServiceManager:
+    """
+    Manages Redfish Event subscriptions.
+
+    """
+
+    def __init__(self, client: RedfishClient):
+        self._client = client
+        self._http = client._http_client
+
+    # ------------------------------------------------------------------
+    # internal helpers
+    # ------------------------------------------------------------------
+
+    def _resolve_subscription_path(self, id_or_uri: str) -> str:
+        """
+        Accept either a bare subscription Id (e.g. ``"1"``) or a full
+        ``@odata.id`` path (e.g. ``"/redfish/v1/EventService/Subscriptions/1"``)
+        and return the absolute Redfish path to GET/DELETE against.
+
+        The dual-form is needed because some callers (e.g. those iterating
+        over the ``Members`` block of the Subscriptions collection) already
+        hold the absolute path.
+        """
+        if not isinstance(id_or_uri, str) or not id_or_uri:
+            raise RedfishValidationError(
+                "subscription id_or_uri must be a non-empty string"
+            )
+        if id_or_uri.startswith("/redfish/"):
+            return id_or_uri
+        event_service = self._client._get_event_service()
+        return f"{event_service.subscriptions.odata_id}/{id_or_uri}"
+
+    # ------------------------------------------------------------------
+    # EventService resource
+    # ------------------------------------------------------------------
+
+    def service(self) -> EventService:
+        """
+        Get the full :class:`EventService` resource (incl. the Actions block).
+
+        Differs from :meth:`subscriptions` which only returns the list of
+        active subscriptions. Use this when you need the SubmitTestEvent
+        action target or the EventTypesForSubscription allowable values.
+        """
+        return self._client._get_event_service()
+
+    # ------------------------------------------------------------------
+    # Subscription CRUD
+    # ------------------------------------------------------------------
+
+    def subscriptions(self) -> List[Subscription]:
+        """
+        Get the list of event subscriptions (collection-expanded).
+
+        Internally lists the ``Subscriptions`` collection and fetches each
+        member by its ``@odata.id``; members that fail to fetch are skipped
+        with a warning.
+        """
+        event_service = self._client._get_event_service()
+        return self._client._get_collection(
+            event_service.subscriptions.odata_id, Subscription
+        )
+
+    def get_subscription(self, id_or_uri: str) -> Subscription:
+        """
+        Get a single subscription by its Id or full ``@odata.id``.
+
+        Args:
+            id_or_uri: Either a bare subscription Id (e.g. ``"1"``) or the
+                full ``@odata.id`` path
+                (e.g. ``"/redfish/v1/EventService/Subscriptions/1"``).
+
+        Returns:
+            The :class:`Subscription` resource.
+        """
+        path = self._resolve_subscription_path(id_or_uri)
+        return self._http.get(path, Subscription)
+
+    def subscribe(
+        self,
+        destination: str,
+        event_types: Optional[List[str]] = None,
+        context: Optional[str] = None,
+        *,
+        protocol: str = "Redfish",
+        http_headers: Optional[Any] = None,
+        origin_resources: Optional[List[Dict[str, Any]]] = None,
+        subscription_type: Optional[str] = None,
+        registry_prefixes: Optional[List[str]] = None,
+        resource_types: Optional[List[str]] = None,
+        message_ids: Optional[List[str]] = None,
+        delivery_retry_policy: Optional[str] = None,
+        event_format_type: Optional[str] = None,
+        severities: Optional[List[str]] = None,
+        oem_subscription_type: Optional[str] = None,
+        extra: Optional[Dict[str, Any]] = None,
+        raw_body: Optional[Dict[str, Any]] = None,
+    ) -> Subscription:
+        """
+        Create a new event subscription (webhook).
+
+        The signature is intentionally vendor-agnostic: every Redfish
+        Subscription field observed in the wild is exposed as a
+        keyword-only parameter, and ``extra`` / ``raw_body`` give a final
+        escape hatch for OEM-specific payloads. The SDK does **not** apply
+        any vendor-default values; callers may attempt multiple payload
+        shapes in sequence if a BMC rejects the first one.
+
+        Args:
+            destination: URL to receive events (e.g. ``"https://my-server/events"``).
+            event_types: Optional list of event types (e.g. ``["Alert"]``).
+            context: Optional context string identifying the subscription.
+            protocol: Wire protocol; defaults to ``"Redfish"``.
+            http_headers: Optional headers to be sent on the callback POST.
+                Pass a ``dict`` (``{"X-Auth-Token": "..."}``) or a
+                ``list[dict]`` — both forms are common across BMC vendors.
+            origin_resources: Optional list of ``{"@odata.id": "..."}``
+                filtering the resources of interest.
+            subscription_type: Optional ``SubscriptionType`` value
+                (e.g. ``"RedfishEvent"``, ``"SSE"``).
+            registry_prefixes: Optional message-registry filter list.
+            resource_types: Optional list of resource-type filters.
+            message_ids: Optional list of message Ids to filter on.
+            delivery_retry_policy: Optional retry policy value.
+            event_format_type: Optional event format type.
+            severities: Optional severity filter list.
+            oem_subscription_type: Optional vendor-specific subscription type.
+            extra: Optional dict shallow-merged into the request body —
+                useful for one-off OEM fields without bypassing field hints.
+            raw_body: If provided, **replaces** the auto-generated body
+                entirely. Use this when a BMC accepts only a non-standard
+                payload shape.
+
+        Returns:
+            The created :class:`Subscription` resource (as echoed by the BMC).
+        """
+        event_service = self._client._get_event_service()
+
+        if raw_body is not None:
+            body: Dict[str, Any] = dict(raw_body)
+        else:
+            body = {"Destination": destination, "Protocol": protocol}
+            if event_types is not None:
+                body["EventTypes"] = event_types
+            if context is not None:
+                body["Context"] = context
+            if http_headers is not None:
+                body["HttpHeaders"] = http_headers
+            if origin_resources is not None:
+                body["OriginResources"] = origin_resources
+            if subscription_type is not None:
+                body["SubscriptionType"] = subscription_type
+            if registry_prefixes is not None:
+                body["RegistryPrefixes"] = registry_prefixes
+            if resource_types is not None:
+                body["ResourceTypes"] = resource_types
+            if message_ids is not None:
+                body["MessageIds"] = message_ids
+            if delivery_retry_policy is not None:
+                body["DeliveryRetryPolicy"] = delivery_retry_policy
+            if event_format_type is not None:
+                body["EventFormatType"] = event_format_type
+            if severities is not None:
+                body["Severities"] = severities
+            if oem_subscription_type is not None:
+                body["OemSubscriptionType"] = oem_subscription_type
+            if extra:
+                body.update(extra)
+
+        return self._http.post(
+            event_service.subscriptions.odata_id,
+            Subscription,
+            raw_body=body,
+        )
+
+    def delete(self, id_or_uri: str) -> str:
+        """
+        Delete an event subscription.
+
+        Args:
+            id_or_uri: Either a bare subscription Id (e.g. ``"1"``) or the
+                full ``@odata.id`` path
+                (e.g. ``"/redfish/v1/EventService/Subscriptions/1"``).
+
+        Returns:
+            Raw response body (typically empty on 204).
+        """
+        path = self._resolve_subscription_path(id_or_uri)
+        return self._http.delete(path)
+
+    # ------------------------------------------------------------------
+    # Actions
+    # ------------------------------------------------------------------
+
+    def submit_test_event(
+        self,
+        event_type: str,
+        message: Optional[str] = None,
+        message_id: Optional[str] = None,
+        severity: Optional[str] = None,
+        message_args: Optional[List[str]] = None,
+    ) -> None:
+        """
+        Invoke ``#EventService.SubmitTestEvent`` on the BMC.
+
+        Args:
+            event_type: Event type, e.g. ``"Alert"`` / ``"StatusChange"``.
+                Subject to ``EventType@Redfish.AllowableValues`` on the BMC.
+            message: Optional event message string.
+            message_id: Optional Redfish MessageId.
+            severity: Optional severity (e.g. ``"OK"`` / ``"Warning"`` / ``"Critical"``).
+            message_args: Optional message argument list.
+
+        Raises:
+            RedfishValidationError: If EventService does not expose
+                SubmitTestEvent or ``event_type`` is not in the allowable list.
+        """
+        from ..models.common import RedfishResponse
+
+        es = self.service()
+        actions = es.actions or {}
+        action = actions.get("#EventService.SubmitTestEvent")
+        if not isinstance(action, dict) or not action.get("target"):
+            raise RedfishValidationError(
+                "EventService does not expose #EventService.SubmitTestEvent action"
+            )
+        target = action["target"]
+        allowable = action.get("EventType@Redfish.AllowableValues")
+        if allowable and event_type not in allowable:
+            raise RedfishValidationError(
+                f"Event type '{event_type}' not in allowable values {allowable}"
+            )
+
+        body: dict = {"EventType": event_type}
+        if message is not None:
+            body["Message"] = message
+        if message_id is not None:
+            body["MessageId"] = message_id
+        if severity is not None:
+            body["Severity"] = severity
+        if message_args is not None:
+            body["MessageArgs"] = message_args
+
+        logger.info("POST SubmitTestEvent (%s) -> %s", event_type, target)
+        self._http.post(target, RedfishResponse, raw_body=body)