redfish-python-sdk 1.2.0__tar.gz → 1.2.3__tar.gz

{redfish_python_sdk-1.2.0/redfish_python_sdk.egg-info → redfish_python_sdk-1.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: redfish-python-sdk
-Version: 1.2.0
+Version: 1.2.3
 Summary: A Python SDK for interacting with Redfish-compliant BMC endpoints
 Author: RedNote Infrastructure
 License: BSD 3-Clause License
@@ -63,11 +63,14 @@ Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: ruff>=0.4.0; extra == "dev"
 Dynamic: license-file
 
-# Redfish Python SDK
+# redfish-python-sdk
+**redfish-python-sdk** is a typed, high-level Python SDK for managing
+multi-vendor BMCs and bare-metal servers through the DMTF Redfish API.
 
 [![PyPI version](https://img.shields.io/pypi/v/redfish-python-sdk)](https://pypi.org/project/redfish-python-sdk/)
 [![Python versions](https://img.shields.io/pypi/pyversions/redfish-python-sdk)](https://pypi.org/project/redfish-python-sdk/)
 [![License](https://img.shields.io/pypi/l/redfish-python-sdk)](https://github.com/rednote-infra/redfish-python-sdk/blob/main/LICENSE)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/redfish-python-sdk?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/redfish-python-sdk)
 
 [English](README.md) | [中文](README_zh.md)
 
@@ -97,11 +100,11 @@ pip install redfish-python-sdk
 pip install git+https://github.com/rednote-infra/redfish-python-sdk.git
 
 # Install a specific version
-pip install redfish-python-sdk==1.0.0
-pip install git+https://github.com/rednote-infra/redfish-python-sdk.git@v1.0.0
+pip install redfish-python-sdk==1.2.3
+pip install git+https://github.com/rednote-infra/redfish-python-sdk.git@v1.2.3
 
 # In requirements.txt
-# redfish-python-sdk>=1.0.0
+# redfish-python-sdk>=1.2.3
 ```
 
 ## Quick Start

{redfish_python_sdk-1.2.0 → redfish_python_sdk-1.2.3}/README.md

@@ -1,8 +1,11 @@
-# Redfish Python SDK
+# redfish-python-sdk
+**redfish-python-sdk** is a typed, high-level Python SDK for managing
+multi-vendor BMCs and bare-metal servers through the DMTF Redfish API.
 
 [![PyPI version](https://img.shields.io/pypi/v/redfish-python-sdk)](https://pypi.org/project/redfish-python-sdk/)
 [![Python versions](https://img.shields.io/pypi/pyversions/redfish-python-sdk)](https://pypi.org/project/redfish-python-sdk/)
 [![License](https://img.shields.io/pypi/l/redfish-python-sdk)](https://github.com/rednote-infra/redfish-python-sdk/blob/main/LICENSE)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/redfish-python-sdk?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/redfish-python-sdk)
 
 [English](README.md) | [中文](README_zh.md)
 
@@ -32,11 +35,11 @@ pip install redfish-python-sdk
 pip install git+https://github.com/rednote-infra/redfish-python-sdk.git
 
 # Install a specific version
-pip install redfish-python-sdk==1.0.0
-pip install git+https://github.com/rednote-infra/redfish-python-sdk.git@v1.0.0
+pip install redfish-python-sdk==1.2.3
+pip install git+https://github.com/rednote-infra/redfish-python-sdk.git@v1.2.3
 
 # In requirements.txt
-# redfish-python-sdk>=1.0.0
+# redfish-python-sdk>=1.2.3
 ```
 
 ## Quick Start

{redfish_python_sdk-1.2.0 → redfish_python_sdk-1.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "redfish-python-sdk"
-version = "1.2.0"
+version = "1.2.3"
 description = "A Python SDK for interacting with Redfish-compliant BMC endpoints"
 requires-python = ">=3.9"
 readme = "README.md"

{redfish_python_sdk-1.2.0 → redfish_python_sdk-1.2.3/redfish_python_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: redfish-python-sdk
-Version: 1.2.0
+Version: 1.2.3
 Summary: A Python SDK for interacting with Redfish-compliant BMC endpoints
 Author: RedNote Infrastructure
 License: BSD 3-Clause License
@@ -63,11 +63,14 @@ Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: ruff>=0.4.0; extra == "dev"
 Dynamic: license-file
 
-# Redfish Python SDK
+# redfish-python-sdk
+**redfish-python-sdk** is a typed, high-level Python SDK for managing
+multi-vendor BMCs and bare-metal servers through the DMTF Redfish API.
 
 [![PyPI version](https://img.shields.io/pypi/v/redfish-python-sdk)](https://pypi.org/project/redfish-python-sdk/)
 [![Python versions](https://img.shields.io/pypi/pyversions/redfish-python-sdk)](https://pypi.org/project/redfish-python-sdk/)
 [![License](https://img.shields.io/pypi/l/redfish-python-sdk)](https://github.com/rednote-infra/redfish-python-sdk/blob/main/LICENSE)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/redfish-python-sdk?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/redfish-python-sdk)
 
 [English](README.md) | [中文](README_zh.md)
 
@@ -97,11 +100,11 @@ pip install redfish-python-sdk
 pip install git+https://github.com/rednote-infra/redfish-python-sdk.git
 
 # Install a specific version
-pip install redfish-python-sdk==1.0.0
-pip install git+https://github.com/rednote-infra/redfish-python-sdk.git@v1.0.0
+pip install redfish-python-sdk==1.2.3
+pip install git+https://github.com/rednote-infra/redfish-python-sdk.git@v1.2.3
 
 # In requirements.txt
-# redfish-python-sdk>=1.0.0
+# redfish-python-sdk>=1.2.3
 ```
 
 ## Quick Start

{redfish_python_sdk-1.2.0 → redfish_python_sdk-1.2.3}/redfish_python_sdk.egg-info/SOURCES.txt

@@ -21,6 +21,23 @@ redfish_sdk/managers/session.py
 redfish_sdk/managers/systems.py
 redfish_sdk/managers/task.py
 redfish_sdk/managers/update.py
+redfish_sdk/managers/log_collect_strategies/__init__.py
+redfish_sdk/managers/log_collect_strategies/base.py
+redfish_sdk/managers/log_collect_strategies/inspur.py
+redfish_sdk/managers/log_collect_strategies/lenovo.py
+redfish_sdk/managers/log_collect_strategies/registry.py
+redfish_sdk/managers/log_collect_strategies/smoothcompute.py
+redfish_sdk/managers/log_collect_strategies/xfusion.py
+redfish_sdk/managers/log_collect_strategies/zte.py
+redfish_sdk/managers/oem_extractors/__init__.py
+redfish_sdk/managers/oem_extractors/base.py
+redfish_sdk/managers/oem_extractors/h3c.py
+redfish_sdk/managers/oem_extractors/inspur.py
+redfish_sdk/managers/oem_extractors/lenovo.py
+redfish_sdk/managers/oem_extractors/nettrix.py
+redfish_sdk/managers/oem_extractors/registry.py
+redfish_sdk/managers/oem_extractors/xfusion.py
+redfish_sdk/managers/oem_extractors/zte.py
 redfish_sdk/managers/update_strategies/__init__.py
 redfish_sdk/managers/update_strategies/base.py
 redfish_sdk/managers/update_strategies/h3c.py
@@ -40,6 +57,7 @@ redfish_sdk/models/drive.py
 redfish_sdk/models/event.py
 redfish_sdk/models/fru.py
 redfish_sdk/models/gpu.py
+redfish_sdk/models/log_collect.py
 redfish_sdk/models/logs.py
 redfish_sdk/models/managers.py
 redfish_sdk/models/memory.py
@@ -58,9 +76,13 @@ redfish_sdk/models/task.py
 redfish_sdk/models/thermal.py
 redfish_sdk/models/update.py
 tests/test_client_mock.py
+tests/test_exception_hints_mock.py
+tests/test_http_retry_mock.py
+tests/test_log_collect_mock.py
 tests/test_log_entries_mock.py
 tests/test_models.py
 tests/test_models_mock.py
+tests/test_oem_extractors.py
 tests/test_offline_json.py
 tests/test_real_bmc.py
 tests/test_sdk_mock.py

{redfish_python_sdk-1.2.0 → redfish_python_sdk-1.2.3}/redfish_sdk/__init__.py

@@ -28,6 +28,7 @@ Quick start:
 """
 from .client import RedfishClient
 from .exceptions import (
+    LogCollectFailedError,
     RedfishAuthError,
     RedfishConnectionError,
     RedfishException,
@@ -55,7 +56,7 @@ from .models.managers import (
 from .models.resource_key import RedfishResource
 from .models.systems import BootOption
 
-__version__ = "1.2.0"
+__version__ = "1.2.3"
 __author__ = "RedNote Infrastructure"
 
 __all__ = [
@@ -67,6 +68,7 @@ __all__ = [
     "RedfishConnectionError",
     "RedfishTimeoutError",
     "RedfishValidationError",
+    "LogCollectFailedError",
     # Models commonly used at API boundary.
     "BootOption",
     "DnsService",

{redfish_python_sdk-1.2.0 → redfish_python_sdk-1.2.3}/redfish_sdk/client.py

@@ -117,6 +117,9 @@ class RedfishClient:
         connect_timeout: int = 10,
         read_timeout: int = 30,
         scheme: str = "https",
+        retry_5xx: int = 0,
+        retry_on_read_timeout: bool = False,
+        retry_backoff: float = 1.0,
     ):
         """
         Initialize the Redfish Client.
@@ -132,6 +135,15 @@ class RedfishClient:
             connect_timeout: TCP connection timeout in seconds (default 10)
             read_timeout: HTTP response read timeout in seconds (default 30)
             scheme: URL scheme — "https" (default) or "http"
+            retry_5xx: Extra retries when the BMC returns a 5xx (default 0 —
+                no retry). GET/HEAD retry on 500/502/503/504; POST/PATCH/DELETE
+                retry only on 503/504 to minimise double-write risk. Useful
+                against overloaded / flaky BMCs (e.g. AMI MegaRAC firmware
+                that intermittently returns Base.1.x.InternalError).
+            retry_on_read_timeout: When True, also retry on read timeouts
+                (default False). Same idempotency rule as ``retry_5xx``.
+            retry_backoff: Base seconds between retries (linear back-off:
+                attempt ``n`` sleeps ``retry_backoff * n``). Default 1.0s.
         """
         self._http_client = RedfishHttpClient(
             host=host,
@@ -142,6 +154,9 @@ class RedfishClient:
             connect_timeout=connect_timeout,
             read_timeout=read_timeout,
             scheme=scheme,
+            retry_5xx=retry_5xx,
+            retry_on_read_timeout=retry_on_read_timeout,
+            retry_backoff=retry_backoff,
         )
 
         # Root service cache
@@ -391,9 +406,20 @@ class RedfishClient:
         return root.systems.odata_id
 
     def _get_task_service(self) -> TaskService:
-        """Get the TaskService resource."""
+        """
+        Get the TaskService resource.
+
+        Prefers the standard ``TaskService`` root link (present on every
+        DMTF-conformant BMC we've seen). Falls back to the non-standard
+        ``Tasks`` link some SDK-internal models also expose, and finally to
+        the well-known path so a very stripped-down BMC still works.
+        """
         root = self._get_root()
-        return self._http_client.get(root.tasks.odata_id, TaskService)
+        link = getattr(root, "task_service", None) or getattr(root, "tasks", None)
+        odata_id = getattr(link, "odata_id", None) if link is not None else None
+        if not odata_id:
+            odata_id = "/redfish/v1/TaskService"
+        return self._http_client.get(odata_id, TaskService)
 
     def _get_update_service(self) -> UpdateService:
         """Get the UpdateService resource."""
@@ -914,6 +940,110 @@ class RedfishClient:
         """
         return self._managers.log_entries(log_id, manager_id)
 
+    # ------------------------------------------------------------------
+    # Out-of-band diagnostic log collection + download
+    # ------------------------------------------------------------------
+
+    def collect_diagnostic_data(
+        self,
+        diagnostic_data_type: Optional[str] = None,
+        log_id: Optional[str] = None,
+        manager_id: str = "1",
+        oem_params: Optional[dict] = None,
+    ) -> Task:
+        """
+        Trigger ``#LogService.CollectDiagnosticData`` to generate an
+        out-of-band diagnostic log bundle.
+
+        Automatically detects the server vendor and builds the vendor-specific
+        request body; the action target is discovered dynamically from the
+        LogService ``Actions`` block.
+
+        Args:
+            diagnostic_data_type: ``DiagnosticDataType`` value; ``None`` uses
+                the vendor default (OEM when available, else ``Manager``).
+            log_id: Log service ID. ``None`` auto-selects the sole service.
+            manager_id: Manager ID (default "1").
+            oem_params: Optional dict shallow-merged into the request body.
+
+        Returns:
+            A :class:`Task` referencing the asynchronous collection.
+        """
+        return self._managers.collect_diagnostic_data(
+            diagnostic_data_type, log_id, manager_id, oem_params
+        )
+
+    def download_diagnostic_data(
+        self,
+        task_or_entry,
+        output_path: Optional[str] = None,
+    ) -> "bytes | str":
+        """
+        Download the artifact produced by a diagnostic-data collection.
+
+        Args:
+            task_or_entry: A completed :class:`Task` or a :class:`LogEntry`
+                carrying ``AdditionalDataURI``.
+            output_path: When provided, stream the bundle to this path and
+                return the absolute file path; otherwise return ``bytes``.
+
+        Returns:
+            The file bytes, or the absolute written path.
+        """
+        return self._managers.download_diagnostic_data(task_or_entry, output_path)
+
+    def collect_and_download_diagnostic_data(
+        self,
+        output_path: str,
+        diagnostic_data_type: Optional[str] = None,
+        log_id: Optional[str] = None,
+        manager_id: str = "1",
+        poll_interval: int = 5,
+        timeout: int = 1800,
+        *,
+        reuse_existing: bool = True,
+        max_retries: int = 0,
+        retry_backoff: int = 30,
+    ) -> str:
+        """
+        One-click helper: trigger collection, wait for the task, then download.
+
+        Reuses a prior matching collection when available (``reuse_existing``,
+        default True) and can retry a failed collection up to ``max_retries``
+        times (default 0 — no retry). See
+        :meth:`ManagersManager.collect_and_download_diagnostic_data` for the
+        full behaviour contract.
+
+        Args:
+            output_path: Destination file path for the downloaded bundle.
+            diagnostic_data_type: See :meth:`collect_diagnostic_data`.
+            log_id: See :meth:`collect_diagnostic_data`.
+            manager_id: Manager ID (default "1").
+            poll_interval: Task poll interval in seconds (default 5).
+            timeout: Max wait in seconds (default 1800 — bundles are slow).
+            reuse_existing: Reuse a matching prior task on the BMC when
+                available (default True).
+            max_retries: Extra retries on failure (default 0).
+            retry_backoff: Seconds between retries (default 30).
+
+        Returns:
+            The absolute path of the downloaded file.
+
+        Raises:
+            LogCollectFailedError: When the collection ultimately fails.
+        """
+        return self._managers.collect_and_download_diagnostic_data(
+            output_path,
+            diagnostic_data_type,
+            log_id,
+            manager_id,
+            poll_interval,
+            timeout,
+            reuse_existing=reuse_existing,
+            max_retries=max_retries,
+            retry_backoff=retry_backoff,
+        )
+
     def get_network_protocol(self, manager_id: str = "1") -> NetworkProtocol:
         """
         Get network protocol configuration for a BMC manager.

redfish_python_sdk-1.2.3/redfish_sdk/exceptions.py

@@ -0,0 +1,200 @@
+"""
+Custom exceptions for the Redfish Python SDK.
+"""
+
+
+class RedfishException(Exception):
+    """
+    Base exception for all Redfish SDK errors.
+
+    Raised when a Redfish API call returns a non-successful HTTP status code.
+    """
+
+    def __init__(self, status_code: int, message: str, body: str = ""):
+        self.status_code = status_code
+        self.message = message
+        self.body = body
+        super().__init__(f"[HTTP {status_code}] {message}")
+
+    def __repr__(self) -> str:
+        return f"RedfishException(status_code={self.status_code}, message={self.message!r})"
+
+
+class RedfishNotFoundError(RedfishException):
+    """Raised when a resource is not found (HTTP 404)."""
+
+    def __init__(self, path: str):
+        super().__init__(404, f"Resource not found: {path}")
+
+
+class RedfishAuthError(RedfishException):
+    """Raised when authentication fails (HTTP 401 / 403)."""
+
+    def __init__(self, status_code: int = 401):
+        super().__init__(status_code, "Authentication failed. Check username and password.")
+
+
+class RedfishConnectionError(RedfishException):
+    """
+    Raised when unable to connect to the BMC.
+
+    The message includes a category-specific troubleshooting hint derived
+    from the underlying ``cause`` so operators can quickly tell apart
+    "wrong IP / host down" from "wrong port / Redfish disabled" from
+    "TLS / DNS" issues.
+
+    Attributes:
+        host: The BMC host that failed to connect.
+        cause: The underlying transport exception (usually from ``requests``
+            / ``urllib3``).
+        reason: One of ``"refused"``, ``"unreachable"``, ``"dns"``,
+            ``"tls"``, ``"other"`` — a coarse category derived from ``cause``.
+    """
+
+    def __init__(self, host: str, cause: Exception = None):
+        self.host = host
+        self.cause = cause
+        self.reason = _classify_connection_cause(cause)
+        hint = _connection_hint(host, self.reason)
+        super().__init__(
+            0,
+            f"Unable to connect to host: {host}. Cause: {cause}. {hint}",
+        )
+
+
+class RedfishTimeoutError(RedfishException):
+    """
+    Raised when a request times out.
+
+    Timeout usually means the BMC accepted the TCP connection but is too slow
+    to respond (e.g. mid-collection, or under heavy load). It's distinct from
+    :class:`RedfishConnectionError`, which means the TCP handshake itself
+    never succeeded.
+    """
+
+    def __init__(self, host: str):
+        self.host = host
+        super().__init__(
+            0,
+            f"Request timed out connecting to: {host}. "
+            f"Hint: the BMC accepted the TCP connection but did not respond "
+            f"within the read timeout — it may be busy (e.g. running a "
+            f"diagnostic collection) or overloaded. Consider raising "
+            f"``read_timeout`` on RedfishClient, or retrying later.",
+        )
+
+
+class RedfishValidationError(RedfishException):
+    """Raised for invalid input parameters (e.g., unsupported reset type)."""
+
+    def __init__(self, message: str):
+        super().__init__(400, message)
+
+
+class LogCollectFailedError(RedfishException):
+    """
+    Raised when out-of-band diagnostic-data collection fails on the BMC.
+
+    Carries the full BMC context so the caller can diagnose without having to
+    re-query the BMC: the terminal task state/status, the complete list of
+    BMC messages, and (when available) the history of progress snapshots
+    observed while polling.
+
+    Attributes:
+        task_id: Task or synthetic-task identifier the collection ran under.
+        task_state: Terminal ``TaskState`` reported by the BMC.
+        task_status: Terminal ``TaskStatus`` reported by the BMC.
+        messages: Full ``Messages`` list from the BMC (each entry retains its
+            ``MessageId`` / ``Message`` / ``Severity`` / ``Resolution`` fields).
+        progress_history: Optional list of intermediate progress snapshots
+            captured during polling — useful for vendors (e.g. ZTE) whose
+            progress endpoint replaces earlier state on each poll.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        task_id: str = "",
+        task_state: str = "",
+        task_status: str = "",
+        messages: list = None,
+        progress_history: list = None,
+    ):
+        super().__init__(500, message)
+        self.task_id = task_id
+        self.task_state = task_state
+        self.task_status = task_status
+        self.messages = messages or []
+        self.progress_history = progress_history or []
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers for RedfishConnectionError diagnosis
+# ---------------------------------------------------------------------------
+
+# Substrings observed in the string form of common transport failures.
+# Ordered so the most specific matches win when combined into a single blob.
+_CAUSE_MARKERS = (
+    ("refused", ("connection refused", "econnrefused", "errno 61", "errno 111")),
+    ("unreachable", (
+        "no route to host", "network is unreachable", "host is down",
+        "ehostunreach", "enetunreach",
+    )),
+    ("dns", (
+        "name or service not known", "nodename nor servname",
+        "temporary failure in name resolution", "getaddrinfo failed",
+    )),
+    ("tls", (
+        "ssl", "certificate", "handshake failed", "wrong version number",
+    )),
+)
+
+
+def _classify_connection_cause(cause) -> str:
+    """
+    Categorise a low-level connection failure so callers can display a
+    targeted hint. Returns one of: ``refused`` / ``unreachable`` / ``dns``
+    / ``tls`` / ``other``.
+    """
+    if cause is None:
+        return "other"
+    blob = f"{cause!r} {cause}".lower()
+    for reason, markers in _CAUSE_MARKERS:
+        for m in markers:
+            if m in blob:
+                return reason
+    return "other"
+
+
+def _connection_hint(host: str, reason: str) -> str:
+    """Return a one-line, action-oriented hint for the given failure reason."""
+    if reason == "refused":
+        return (
+            f"Hint: {host} accepted routing (host is up) but no service is "
+            f"listening on the requested TCP port. Check: 1) the IP is a BMC "
+            f"address (not a host OS address); 2) the BMC Redfish/HTTPS "
+            f"service is enabled; 3) the port matches your RedfishClient "
+            f"``scheme``/port (Redfish default is 443 for https)."
+        )
+    if reason == "unreachable":
+        return (
+            f"Hint: {host} is not routable from this machine. Check network "
+            f"connectivity (VPN / firewall / VLAN / subnet)."
+        )
+    if reason == "dns":
+        return (
+            f"Hint: could not resolve host name {host!r}. Check DNS or use "
+            f"the raw IP address instead."
+        )
+    if reason == "tls":
+        return (
+            f"Hint: TLS/SSL handshake failed with {host}. BMC self-signed "
+            f"certificates are expected — RedfishClient defaults to "
+            f"``verify_ssl=False``. If you enabled verification, provide a "
+            f"trust store; otherwise check the server's TLS version."
+        )
+    return (
+        f"Hint: unclassified connection failure to {host}. Verify basic "
+        f"connectivity with ``ping`` / ``nc -zv {host} 443``."
+    )