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

redfish_sdk/models/check.py

@@ -0,0 +1,231 @@
+"""
+模型层注解式校验引擎。
+
+提供自定义 Field() 包装和 validate_model() 通用校验函数，
+实现 Go playground/validator 风格的 struct tag 声明式校验。
+
+用法:
+    # 模型定义（替换 from pydantic import Field）
+    from redfish_sdk.models.check import Field
+
+    class Processor(Entity):
+        manufacturer: Optional[str] = Field(None, alias="Manufacturer", validate="required,type=str")
+        total_cores:  Optional[int] = Field(None, alias="TotalCores",   validate="required,type=int,gt=0")
+
+    # 校验（测试代码中调用）
+    from redfish_sdk.models.check import validate_model
+    validate_model(processor_instance)
+"""
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+from pydantic import BaseModel
+from pydantic import Field as _PydanticField
+
+# ---------------------------------------------------------------------------
+# 自定义 Field() 包装
+# ---------------------------------------------------------------------------
+
+def Field(default=None, *, alias=None, validate=None, **kwargs):
+    """
+    Pydantic Field 的增强包装，新增 validate 参数。
+
+    用法与原生 Field 完全一致，额外支持 validate 标签:
+        Field(None, alias="Manufacturer", validate="required,type=str")
+
+    内部实现: 将 validate 字符串存入 json_schema_extra，
+    供 validate_model() 在运行时读取。
+    """
+    if validate is not None:
+        extra = kwargs.get("json_schema_extra") or {}
+        extra["validate"] = validate
+        kwargs["json_schema_extra"] = extra
+    return _PydanticField(default, alias=alias, **kwargs)
+
+
+# ---------------------------------------------------------------------------
+# 标签解析器
+# ---------------------------------------------------------------------------
+
+_TYPE_MAP = {
+    "str": str,
+    "int": int,
+    "float": float,
+    "bool": bool,
+}
+
+
+def _parse_validate_tag(tag: str) -> dict:
+    """
+    解析 validate 标签字符串为规则字典。
+
+    示例:
+        "required,type=str"              → {"required": True, "type": str}
+        "required,type=int,gt=0"         → {"required": True, "type": int, "gt": 0}
+        "oneof=On Off PoweringOn"        → {"oneof": ("On", "Off", "PoweringOn")}
+        "status"                         → {"status": True}
+        "gte_field=total_cores"          → {"gte_field": "total_cores"}
+    """
+    rules = {}
+    for part in tag.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        if "=" in part:
+            key, val = part.split("=", 1)
+            key = key.strip()
+            val = val.strip()
+            if key == "type":
+                rules["type"] = _TYPE_MAP[val]
+            elif key in ("gt", "ge", "lt", "le"):
+                rules[key] = float(val) if "." in val else int(val)
+            elif key == "oneof":
+                rules["oneof"] = tuple(val.split())
+            elif key.endswith("_field"):
+                rules[key] = val  # 跨字段引用，存字段名
+            else:
+                rules[key] = val
+        else:
+            # 无值标签：required, status, list
+            rules[part] = True
+    return rules
+
+
+# ---------------------------------------------------------------------------
+# 通用校验引擎
+# ---------------------------------------------------------------------------
+
+def validate_model(obj: BaseModel) -> None:
+    """
+    根据模型字段上的 validate 标签自动执行校验。
+
+    行为:
+        - required 且值为 None/空字符串 → warnings.warn（WARN，不失败）
+        - 类型不匹配 → AssertionError（FAIL）
+        - 值域不满足 → AssertionError（FAIL）
+        - 枚举不匹配 → AssertionError（FAIL）
+
+    用法:
+        validate_model(processor_instance)
+    """
+    resource_id = getattr(obj, "odata_id", "unknown")
+    cls_name = obj.__class__.__name__
+
+    for field_name, field_info in obj.__class__.model_fields.items():
+        extra = field_info.json_schema_extra
+        if not extra or "validate" not in extra:
+            continue
+
+        tag = extra["validate"]
+        rules = _parse_validate_tag(tag)
+        value = getattr(obj, field_name, None)
+
+        # --- status 特殊处理 ---
+        if rules.get("status"):
+            if value is not None:
+                _check_status(value, cls_name, resource_id)
+            continue
+
+        required = rules.get("required", False)
+
+        # --- None 检查 ---
+        if value is None:
+            if required:
+                warnings.warn(
+                    f"{cls_name}.{field_name} 为 None (resource={resource_id})",
+                    stacklevel=2,
+                )
+            continue
+
+        # --- 空字符串检查 ---
+        if isinstance(value, str) and value == "":
+            if required:
+                warnings.warn(
+                    f"{cls_name}.{field_name} 为空字符串 (resource={resource_id})",
+                    stacklevel=2,
+                )
+            continue
+
+        # --- list 标签 ---
+        if rules.get("list"):
+            assert isinstance(value, list), (
+                f"{cls_name}.{field_name} 类型错误: 期望 list, "
+                f"实际 {type(value).__name__} (resource={resource_id})"
+            )
+            continue
+
+        # --- type 类型检查 ---
+        expected = rules.get("type")
+        if expected is not None:
+            if expected is float:
+                assert isinstance(value, (int, float)), (
+                    f"{cls_name}.{field_name} 类型错误: 期望 数字, "
+                    f"实际 {type(value).__name__} (值={value!r}, resource={resource_id})"
+                )
+            else:
+                assert isinstance(value, expected), (
+                    f"{cls_name}.{field_name} 类型错误: 期望 {expected.__name__}, "
+                    f"实际 {type(value).__name__} (值={value!r}, resource={resource_id})"
+                )
+
+        # --- gt / ge / lt / le 值域检查 ---
+        if isinstance(value, (int, float)):
+            if "gt" in rules:
+                assert value > rules["gt"], (
+                    f"{cls_name}.{field_name} 应 > {rules['gt']}, "
+                    f"实际={value} (resource={resource_id})"
+                )
+            if "ge" in rules:
+                assert value >= rules["ge"], (
+                    f"{cls_name}.{field_name} 应 >= {rules['ge']}, "
+                    f"实际={value} (resource={resource_id})"
+                )
+            if "lt" in rules:
+                assert value < rules["lt"], (
+                    f"{cls_name}.{field_name} 应 < {rules['lt']}, "
+                    f"实际={value} (resource={resource_id})"
+                )
+            if "le" in rules:
+                assert value <= rules["le"], (
+                    f"{cls_name}.{field_name} 应 <= {rules['le']}, "
+                    f"实际={value} (resource={resource_id})"
+                )
+
+        # --- oneof 枚举检查 ---
+        if "oneof" in rules and isinstance(value, str):
+            assert value in rules["oneof"], (
+                f"{cls_name}.{field_name} 值不在允许范围: "
+                f"实际={value!r}, 允许={rules['oneof']} (resource={resource_id})"
+            )
+
+        # --- gte_field 跨字段检查 ---
+        if "gte_field" in rules and isinstance(value, (int, float)):
+            other_name = rules["gte_field"]
+            other_val = getattr(obj, other_name, None)
+            if other_val is not None and isinstance(other_val, (int, float)):
+                assert value >= other_val, (
+                    f"{cls_name}.{field_name} ({value}) 应 >= "
+                    f"{other_name} ({other_val}) (resource={resource_id})"
+                )
+
+
+def _check_status(status: Any, parent_cls: str, resource_id: str) -> None:
+    """校验 Status 子对象。"""
+    from redfish_sdk.models.common import Status
+
+    assert isinstance(status, Status), (
+        f"{parent_cls}.status 类型错误: 期望 Status, "
+        f"实际 {type(status).__name__} (resource={resource_id})"
+    )
+    if status.state is not None:
+        assert isinstance(status.state, str), (
+            f"{parent_cls}.status.state 类型错误: "
+            f"期望 str, 实际 {type(status.state).__name__} (resource={resource_id})"
+        )
+    if status.health is not None:
+        assert isinstance(status.health, str), (
+            f"{parent_cls}.status.health 类型错误: "
+            f"期望 str, 实际 {type(status.health).__name__} (resource={resource_id})"
+        )

redfish_sdk/models/common.py

@@ -0,0 +1,102 @@
+"""
+Common base models for Redfish resources.
+"""
+from __future__ import annotations
+
+from typing import Generic, List, Optional, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Link(BaseModel):
+    """
+    Base class for all Redfish resource links.
+    Contains only the @odata.id field, which uniquely identifies the resource URL.
+    """
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    odata_id: Optional[str] = Field(None, alias="@odata.id")
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(odata_id={self.odata_id!r})"
+
+
+class Entity(Link):
+    """
+    Entity is the base class for all Redfish resources.
+    Inherits from Link and adds common fields like Id, Name, Description, and ETag.
+
+    """
+    odata_context: Optional[str] = Field(None, alias="@odata.context")
+    odata_type: Optional[str] = Field(None, alias="@odata.type")
+    odata_etag: Optional[str] = Field(None, alias="@odata.etag")
+    id: Optional[str] = Field(None, alias="Id")
+    name: Optional[str] = Field(None, alias="Name")
+    description: Optional[str] = Field(None, alias="Description")
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(id={self.id!r}, name={self.name!r})"
+
+
+T = TypeVar("T", bound=Link)
+
+
+class Collection(Entity, Generic[T]):
+    """
+    Generic Redfish collection container.
+
+    Example:
+        /redfish/v1/Systems -> Collection[System]
+        /redfish/v1/Chassis -> Collection[Chassis]
+
+    """
+    members_count: Optional[int] = Field(None, alias="Members@odata.count")
+    members: Optional[List[T]] = Field(default_factory=list, alias="Members")
+
+
+class Status(BaseModel):
+    """
+    Standard Redfish status object, used across most resource types.
+    """
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    state: Optional[str] = Field(None, alias="State")
+    health: Optional[str] = Field(None, alias="Health")
+    health_rollup: Optional[str] = Field(None, alias="HealthRollup")
+
+
+class ExtendedInfo(BaseModel):
+    """Extended error information."""
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    message_id: Optional[str] = Field(None, alias="MessageId")
+    message: Optional[str] = Field(None, alias="Message")
+    message_args: Optional[List[str]] = Field(None, alias="MessageArgs")
+    severity: Optional[str] = Field(None, alias="Severity")
+    resolution: Optional[str] = Field(None, alias="Resolution")
+
+
+class RedfishError(BaseModel):
+    """
+    Standard Redfish error response body.
+    """
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    code: Optional[str] = Field(None, alias="code")
+    message: Optional[str] = Field(None, alias="message")
+    extended_info: Optional[List[ExtendedInfo]] = Field(None, alias="@Message.ExtendedInfo")
+
+
+class RedfishResponse(BaseModel):
+    """
+    Generic Redfish operation response.
+    Used for reset, patch and other mutation operations that return minimal data.
+    """
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    error: Optional[RedfishError] = Field(None, alias="error")
+    odata_id: Optional[str] = Field(None, alias="@odata.id")
+    odata_type: Optional[str] = Field(None, alias="@odata.type")
+    message: Optional[str] = Field(None, alias="Message")
+    task_id: Optional[str] = Field(None, alias="TaskId")
+    task_state: Optional[str] = Field(None, alias="TaskState")

redfish_sdk/models/drive.py

@@ -0,0 +1,53 @@
+"""
+Drive (HDD/SSD/NVMe) component models.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict
+
+from .check import Field
+from .common import Entity, Status
+
+
+class Location(BaseModel):
+    """Physical location info."""
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    info: Optional[str] = Field(None, alias="Info")
+    info_format: Optional[str] = Field(None, alias="InfoFormat")
+    placement: Optional[Any] = Field(None, alias="Placement")
+    postal_address: Optional[Any] = Field(None, alias="PostalAddress")
+
+
+class Drive(Entity):
+    """
+    Represents a physical storage drive (HDD/SSD/NVMe).
+    Endpoint: /redfish/v1/Chassis/{chassisId}/Drives/{driveId}
+
+    """
+    indicator_led: Optional[str] = Field(None, alias="IndicatorLED")
+    model: Optional[str] = Field(None, alias="Model", validate="type=str")
+    revision: Optional[str] = Field(None, alias="Revision")
+    capacity_bytes: Optional[int] = Field(None, alias="CapacityBytes", validate="required,type=int,gt=0")
+    protocol: Optional[str] = Field(None, alias="Protocol", validate="type=str")
+    serial_number: Optional[str] = Field(None, alias="SerialNumber", validate="type=str")
+    media_type: Optional[str] = Field(None, alias="MediaType", validate="type=str")
+    manufacturer: Optional[str] = Field(None, alias="Manufacturer", validate="type=str")
+    capable_speed_gbs: Optional[Any] = Field(None, alias="CapableSpeedGbs")
+    negotiated_speed_gbs: Optional[Any] = Field(None, alias="NegotiatedSpeedGbs")
+    failure_predicted: Optional[bool] = Field(None, alias="FailurePredicted")
+    predicted_media_life_left_percent: Optional[int] = Field(
+        None, alias="PredictedMediaLifeLeftPercent"
+    )
+    hotspare_type: Optional[str] = Field(None, alias="HotspareType")
+    status_indicator: Optional[str] = Field(None, alias="StatusIndicator")
+    status: Optional[Status] = Field(None, alias="Status", validate="status")
+    location: Optional[List[Location]] = Field(None, alias="Location")
+    # Drive power state + Redfish Actions (e.g. #Drive.Reset).
+    # `actions` is intentionally weakly typed (dict) because vendors vary widely
+    # in how they expose action targets/AllowableValues. Helper methods on
+    # SystemsManager parse the well-known sub-keys.
+    power_state: Optional[str] = Field(None, alias="PowerState")
+    actions: Optional[Dict[str, Any]] = Field(None, alias="Actions")

redfish_sdk/models/event.py

@@ -0,0 +1,64 @@
+"""
+Event service models.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import Field
+
+from .common import Entity, Link, Status  # noqa: F401  (Status kept for downstream imports)
+
+
+class EventService(Entity):
+    """
+    The Event service provides event subscription management.
+    Endpoint: /redfish/v1/EventService
+    """
+    subscriptions: Optional[Link] = Field(None, alias="Subscriptions")
+    delivery_retry_attempts: Optional[int] = Field(None, alias="DeliveryRetryAttempts")
+    delivery_retry_interval_seconds: Optional[int] = Field(
+        None, alias="DeliveryRetryIntervalSeconds"
+    )
+    event_types_for_subscription: Optional[List[str]] = Field(
+        None, alias="EventTypesForSubscription"
+    )
+    service_enabled: Optional[bool] = Field(None, alias="ServiceEnabled")
+    status: Optional[Status] = Field(None, alias="Status")
+    # Redfish Actions block (e.g. #EventService.SubmitTestEvent).
+    actions: Optional[Dict[str, Any]] = Field(None, alias="Actions")
+
+
+class Subscription(Entity):
+    """
+    Represents an event subscription (webhook).
+    Endpoint: /redfish/v1/EventService/Subscriptions/{subscriptionId}
+    """
+    context: Optional[str] = Field(None, alias="Context")
+    destination: Optional[str] = Field(None, alias="Destination")
+    event_types: Optional[List[str]] = Field(None, alias="EventTypes")
+    # Type widened to Any: different BMC vendors return either a dict
+    # (``{"X-Auth-Token": "..."}``) or a list of dicts
+    # (``[{"X-Auth-Token": "..."}]``). Mirrors the lenient style used by
+    # ``EventService.actions`` above.
+    http_headers: Optional[Any] = Field(None, alias="HttpHeaders")
+    oem_type: Optional[str] = Field(None, alias="OemSubscriptionType")
+    protocol: Optional[str] = Field(None, alias="Protocol")
+    registry_prefixes: Optional[List[str]] = Field(None, alias="RegistryPrefixes")
+    resource_types: Optional[List[str]] = Field(None, alias="ResourceTypes")
+    # Type widened to Any: per Redfish spec ``Status`` is a complex object
+    # (``{"State": "Enabled", "Health": "OK"}``), but multiple BMC vendors
+    # return a bare string (e.g. ``"Enabled"``) for EventDestination.
+    # Mirrors the lenient style of ``http_headers`` above.
+    status: Optional[Any] = Field(None, alias="Status")
+    subscription_type: Optional[str] = Field(None, alias="SubscriptionType")
+    # —— Additional fields observed across BMC vendors ——
+    origin_resources: Optional[List[Dict[str, Any]]] = Field(
+        None, alias="OriginResources"
+    )
+    delivery_retry_policy: Optional[str] = Field(
+        None, alias="DeliveryRetryPolicy"
+    )
+    message_ids: Optional[List[str]] = Field(None, alias="MessageIds")
+    event_format_type: Optional[str] = Field(None, alias="EventFormatType")
+    severities: Optional[List[str]] = Field(None, alias="Severities")

redfish_sdk/models/fru.py

@@ -0,0 +1,59 @@
+"""
+FRU (Field Replaceable Unit) models.
+
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .common import Entity, Status
+from .oem import MainBoard
+
+
+class FruChassis(BaseModel):
+    """FRU chassis component info."""
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    chassis_part_number: Optional[str] = Field(None, alias="ChassisPartNumber")
+    chassis_serial_number: Optional[str] = Field(None, alias="ChassisSerialNumber")
+    chassis_type: Optional[str] = Field(None, alias="ChassisType")
+
+
+class FruProduct(BaseModel):
+    """FRU product info."""
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    manufacturer: Optional[str] = Field(None, alias="Manufacturer")
+    name: Optional[str] = Field(None, alias="Name")
+    part_number: Optional[str] = Field(None, alias="PartNumber")
+    serial_number: Optional[str] = Field(None, alias="SerialNumber")
+    version: Optional[str] = Field(None, alias="Version")
+    asset_tag: Optional[str] = Field(None, alias="AssetTag")
+
+
+class FruDevice(BaseModel):
+    """FRU device info (card, module, etc.)."""
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    name: Optional[str] = Field(None, alias="Name")
+    manufacturer: Optional[str] = Field(None, alias="Manufacturer")
+    part_number: Optional[str] = Field(None, alias="PartNumber")
+    serial_number: Optional[str] = Field(None, alias="SerialNumber")
+
+
+class Fru(Entity):
+    """
+    FRU (Field Replaceable Unit) information resource.
+    Contains hardware inventory info like board, chassis, and product details.
+
+    Retrieved via the OEM FRU link in the System or Chassis resource:
+    - system.oem.bmc.fru.odata_id
+
+    """
+    chassis: Optional[FruChassis] = Field(None, alias="Chassis")
+    board: Optional[MainBoard] = Field(None, alias="MainBoard")
+    product: Optional[FruProduct] = Field(None, alias="Product")
+    device: Optional[FruDevice] = Field(None, alias="device")
+    status: Optional[Status] = Field(None, alias="Status")

redfish_sdk/models/gpu.py

@@ -0,0 +1,33 @@
+"""
+GPU (Graphics Processing Unit) component models.
+
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict
+
+from .check import Field
+from .common import Entity
+
+
+class GpuOEM(BaseModel):
+    """OEM-specific GPU fields."""
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    serial_number: Optional[str] = Field(None, alias="SerialNumber")
+
+
+class Gpu(Entity):
+    """
+    Represents a GPU (Graphics Processing Unit).
+    Can come from either /redfish/v1/Systems/{systemId}/GraphicsControllers
+    or derived from /redfish/v1/Chassis/{chassisId}/PCIeDevices.
+
+    """
+    manufacturer: Optional[str] = Field(None, alias="Manufacturer", validate="type=str")
+    model: Optional[str] = Field(None, alias="Model", validate="type=str")
+    version: Optional[str] = Field(None, alias="Version", validate="type=str")
+    power_watts: Optional[str] = Field(None, alias="PowerWatts", validate="type=str")
+    oem: Optional[GpuOEM] = Field(None, alias="Oem")

redfish_sdk/models/logs.py

@@ -0,0 +1,56 @@
+"""
+Log service models.
+
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from pydantic import Field
+
+from .common import Entity, Link, Status
+
+
+class Log(Entity):
+    """
+    Represents a log service on a system or manager.
+    Endpoint: /redfish/v1/Systems/{id}/LogServices/{logId}
+              /redfish/v1/Managers/{id}/LogServices/{logId}
+
+    """
+    date_time: Optional[str] = Field(None, alias="DateTime")
+    date_time_local_offset: Optional[str] = Field(None, alias="DateTimeLocalOffset")
+    entries: Optional[Link] = Field(None, alias="Entries")
+    max_number_of_records: Optional[int] = Field(None, alias="MaxNumberOfRecords")
+    overwrite_policy: Optional[str] = Field(None, alias="OverWritePolicy")
+    service_enabled: Optional[bool] = Field(None, alias="ServiceEnabled")
+    status: Optional[Status] = Field(None, alias="Status")
+    # Redfish Actions block (e.g. #LogService.ClearLog).
+    actions: Optional[Dict[str, Any]] = Field(None, alias="Actions")
+
+
+class LogEntry(Entity):
+    """
+    A single log entry within a log service.
+    Endpoint: /redfish/v1/Systems/{id}/LogServices/{logId}/Entries/{entryId}
+
+    """
+    created: Optional[str] = Field(None, alias="Created")
+    entry_code: Optional[str] = Field(None, alias="EntryCode")
+    entry_type: Optional[str] = Field(None, alias="EntryType")
+    message: Optional[str] = Field(None, alias="Message")
+    message_args: Optional[list] = Field(None, alias="MessageArgs")
+    message_id: Optional[str] = Field(None, alias="MessageId")
+    oem_log_entry_code: Optional[str] = Field(None, alias="OemLogEntryCode")
+    oem_record_format: Optional[str] = Field(None, alias="OemRecordFormat")
+    sensor_number: Optional[int] = Field(None, alias="SensorNumber")
+    sensor_type: Optional[str] = Field(None, alias="SensorType")
+    severity: Optional[str] = Field(None, alias="Severity")
+    status: Optional[Status] = Field(None, alias="Status")
+    # DMTF v1.4 optional fields commonly needed for
+    # compliance checks (e.g. bmc_autotest managers_004*_*_log_check.py).
+    # ``odata_id`` / ``odata_type`` are already inherited from Entity.
+    event_timestamp: Optional[str] = Field(None, alias="EventTimestamp")
+    diagnostic_data_size_bytes: Optional[int] = Field(
+        None, alias="DiagnosticDataSizeBytes"
+    )