python-ipmi 0.5.7__py3-none-any.whl → 0.6.0__py3-none-any.whl

pyipmi/__init__.py

@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
 # Copyright (c) 2014  Kontron Europe GmbH
 #
 # This library is free software; you can redistribute it and/or
@@ -15,10 +14,11 @@
 # License along with this library; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
 
-from __future__ import absolute_import
+from __future__ import annotations
 
 import time
 import ast
+from typing import Any, Literal
 
 from . import bmc
 from . import chassis
@@ -27,46 +27,45 @@ from . import event
 from . import fru
 from . import hpm
 from . import lan
+from . import logger  # noqa: F401 - installs the NullHandler
 from . import messaging
 from . import picmg
 from . import sdr
 from . import sel
 from . import sensor
+from . import vita
 from . import msgs
 
 from .errors import IpmiTimeoutError, CompletionCodeError, RetryError
+from .msgs import Message
 from .msgs.registry import create_request_by_name
 from .session import Session
 from .utils import check_rsp_completion_code, is_string
 
 try:
-    from version import __version__
+    from .version import __version__
 except ImportError:
     __version__ = 'dev'
 
 
-def create_connection(interface):
+def create_connection(interface: Any) -> Ipmi:
     session = Session()
     session.interface = interface
-    ipmi = Ipmi()
-    ipmi.interface = interface
-    ipmi.session = session
-    ipmi.requester = NullRequester()
-    return ipmi
+    return Ipmi(interface=interface, session=session)
 
 
-class Requester(object):
+class Requester:
     """The Requester class.
 
     This represents an IPMI device which initiates a request/response
     message exchange.
     """
 
-    def __init__(self, ipmb_address):
+    def __init__(self, ipmb_address: int) -> None:
         self.ipmb_address = ipmb_address
 
 
-class NullRequester(object):
+class NullRequester:
     """The NullRequester class.
 
     This requester is used for interfaces which doesn't require a valid
@@ -74,31 +73,32 @@ class NullRequester(object):
     """
 
     @property
-    def ipmb_address(self):
+    def ipmb_address(self) -> int:
         raise AssertionError('NullRequester does not provide an IPMB address')
 
 
-class Routing(object):
+class Routing:
     """The Target class represents an IPMI target."""
 
-    def __init__(self, rq_sa, rs_sa, channel):
+    def __init__(self, rq_sa: int, rs_sa: int, channel: int | None) -> None:
         self.rq_sa = rq_sa
         self.rs_sa = rs_sa
         self.channel = channel
 
-    def __str__(self):
+    def __str__(self) -> str:
         s = 'Routing: Rq: %s Rs: %s Ch: %s' \
                 % (self.rq_sa, self.rs_sa, self.channel)
         return s
 
 
-class Target(object):
+class Target:
     """The Target class represents an IPMI target."""
 
-    routing = None
-    ipmb_address = None
+    routing: list[Routing] | None = None
+    ipmb_address: int | None = None
 
-    def __init__(self, ipmb_address=None, routing=None):
+    def __init__(self, ipmb_address: int | None = None,
+                 routing: str | list[tuple] | None = None) -> None:
         """Initializer for the Target class.
 
         `ipmb_address` is the IPMB target address
@@ -111,49 +111,57 @@ class Target(object):
         if routing:
             self.set_routing(routing)
 
-    def set_routing_information(self, routing):
+    def set_routing_information(self, routing: str | list[tuple]) -> None:
         self.set_routing(routing)
 
-    def set_routing(self, routing):
+    def set_routing(self, routing: str | list[tuple]) -> None:
         """Set the path over which a target is reachable.
 
-        The path is given as a list of tuples in the form (address,
-        bridge_channel).
+        Each hop of the path is a tuple ``(rq_sa, rs_sa, channel)``: the
+        requester address, the responder address and the channel of the
+        bridge to the next hop. The channel of the last hop is None.
 
-        Example #1: access to an ATCA blade in a chassis
-              slave = 0x81, target = 0x82
-              routing = [(0x81,0x20,0),(0x20,0x82,None)]
+        Args:
+            routing: The list of hops, or its string representation as
+                given on the command line.
 
-        Example #2: access to an AMC in a uTCA chassis
-              slave = 0x81, target = 0x72
-              routing = [(0x81,0x20,0),(0x20,0x82,7),(0x20,0x72,None)]
+        Example #1, access to an ATCA blade in a chassis (slave 0x81,
+        target 0x82)::
 
+            routing = [(0x81, 0x20, 0), (0x20, 0x82, None)]
 
-                         uTCA - MCH                        AMC
-                       .-------------------.             .--------.
-                       |       .-----------|             |        |
-                       | ShMC  | CM        |             | MMC    |
-            channel=0  |       |           |  channel=7  |        |
-        81 ------------| 0x20  |0x82  0x20 |-------------| 0x72   |
-                       |       |           |             |        |
-                       |       |           |             |        |
-                       |       `-----------|             |        |
-                       `-------------------´             `--------´
-          `------------´     `---´        `---------------´
+        Example #2, access to an AMC in a uTCA chassis (slave 0x81,
+        target 0x72)::
 
-        Example #3: access to an AMC in a ATCA AMC carrier
+            routing = [(0x81, 0x20, 0), (0x20, 0x82, 7), (0x20, 0x72, None)]
 
-        slave = 0x81, target = 0x72
-        routing = [(0x81,0x20,0),(0x20,0x8e,7),(0x20,0x80,None)]
+                             uTCA - MCH                        AMC
+                           .-------------------.             .--------.
+                           |       .-----------|             |        |
+                           | ShMC  | CM        |             | MMC    |
+                channel=0  |       |           |  channel=7  |        |
+            81 ------------| 0x20  |0x82  0x20 |-------------| 0x72   |
+                           |       |           |             |        |
+                           |       |           |             |        |
+                           |       `-----------|             |        |
+                           `-------------------´             `--------´
+              `------------´     `---´        `---------------´
 
+        Example #3, access to an AMC in an ATCA AMC carrier (slave 0x81,
+        target 0x72)::
+
+            routing = [(0x81, 0x20, 0), (0x20, 0x8e, 7), (0x20, 0x80, None)]
         """
         if is_string(routing):
             # if type(routing) in [unicode, str]:
             routing = ast.literal_eval(routing)
         self.routing = [Routing(*route) for route in routing]
 
-    def __str__(self):
-        string = 'Target: IPMB: 0x%02x\n' % self.ipmb_address
+    def __str__(self) -> str:
+        if self.ipmb_address is None:
+            string = 'Target: IPMB: none\n'
+        else:
+            string = 'Target: IPMB: 0x%02x\n' % self.ipmb_address
         if self.routing:
             for route in self.routing:
                 string += ' %s\n' % route
@@ -162,20 +170,50 @@ class Target(object):
 
 class Ipmi(bmc.Bmc, chassis.Chassis, dcmi.Dcmi, fru.Fru, picmg.Picmg, hpm.Hpm,
            sdr.Sdr, sensor.Sensor, event.Event, sel.Sel, lan.Lan,
-           messaging.Messaging):
+           messaging.Messaging, vita.Vita):
+
+    def __init__(self, interface: Any = None, target: Target | None = None,
+                 session: Session | None = None,
+                 requester: Any = None) -> None:
+        self._interface = interface
+
+        # we need a session, set if not passed
+        if session is None:
+            session = Session()
+        self._session = session
+        # session needs an interface
+        self._session.interface = interface
 
-    def __init__(self):
-        self._interface = None
-        self._session = None
-        self._target = None
+        self._target = target
+        self.requester = requester if requester is not None else NullRequester()
 
         for base in Ipmi.__bases__:
-            base.__init__(self)
+            base.__init__(self)  # type: ignore[misc]
+
+    def __enter__(self) -> Ipmi:
+        self.open()
+        return self
+
+    def __exit__(self, exception_type: Any, exception_value: Any,
+                 traceback: Any) -> Literal[False]:
+        self.close()
+        return False
 
-    def is_ipmc_accessible(self):
+    def open(self) -> None:
+        self.interface.open()
+        if self.session is not None:
+            self.session.establish()
+
+    def close(self) -> None:
+        if self.session is not None:
+            self.session.close()
+        self.interface.close()
+
+    def is_ipmc_accessible(self) -> bool:
         return self.interface.is_ipmc_accessible(self.target)
 
-    def wait_until_ipmb_is_accessible(self, timeout, interval=0.25):
+    def wait_until_ipmb_is_accessible(self, timeout: float,
+                                      interval: float = 0.25) -> None:
         start_time = time.time()
         while time.time() < start_time + (timeout):
             try:
@@ -185,7 +223,7 @@ class Ipmi(bmc.Bmc, chassis.Chassis, dcmi.Dcmi, fru.Fru, picmg.Picmg, hpm.Hpm,
 
         self.is_ipmc_accessible()
 
-    def send_message(self, req, retry=3):
+    def send_message(self, req: Message, retry: int = 3) -> Message:
         req.target = self.target
         req.requester = self.requester
         rsp = None
@@ -203,7 +241,8 @@ class Ipmi(bmc.Bmc, chassis.Chassis, dcmi.Dcmi, fru.Fru, picmg.Picmg, hpm.Hpm,
 
         return rsp
 
-    def send_message_with_name(self, name, *args, **kwargs):
+    def send_message_with_name(self, name: str, *args: Any,
+                               **kwargs: Any) -> Message:
         req = create_request_by_name(name)
 
         for key, value in kwargs.items():
@@ -213,7 +252,7 @@ class Ipmi(bmc.Bmc, chassis.Chassis, dcmi.Dcmi, fru.Fru, picmg.Picmg, hpm.Hpm,
         check_rsp_completion_code(rsp)
         return rsp
 
-    def raw_command(self, lun, netfn, raw_bytes):
+    def raw_command(self, lun: int, netfn: int, raw_bytes: bytes) -> bytes:
         """Send the raw command data and return the raw response.
 
         lun: the logical unit number
@@ -225,33 +264,35 @@ class Ipmi(bmc.Bmc, chassis.Chassis, dcmi.Dcmi, fru.Fru, picmg.Picmg, hpm.Hpm,
         return self.interface.send_and_receive_raw(self.target, lun, netfn,
                                                    raw_bytes)
 
-    def _get_interface(self):
+    @property
+    def interface(self) -> Any:
         try:
             return self._interface
         except AttributeError:
-            raise RuntimeError('No interface has been set')
+            raise RuntimeError('No interface has been set') from None
 
-    def _get_session(self):
+    @interface.setter
+    def interface(self, interface: Any) -> None:
+        self._interface = interface
+
+    @property
+    def session(self) -> Session:
         try:
             return self._session
         except AttributeError:
-            raise RuntimeError('No IPMI session has been set')
+            raise RuntimeError('No IPMI session has been set') from None
 
-    def _get_target(self):
+    @session.setter
+    def session(self, session: Session) -> None:
+        self._session = session
+
+    @property
+    def target(self) -> Target | None:
         try:
             return self._target
         except AttributeError:
-            raise RuntimeError('No IPMI target has been set')
+            raise RuntimeError('No IPMI target has been set') from None
 
-    def _set_interface(self, interface):
-        self._interface = interface
-
-    def _set_session(self, session):
-        self._session = session
-
-    def _set_target(self, target):
+    @target.setter
+    def target(self, target: Target | None) -> None:
         self._target = target
-
-    target = property(_get_target, _set_target)
-    interface = property(_get_interface, _set_interface)
-    session = property(_get_session, _set_session)

pyipmi/bmc.py

@@ -14,27 +14,80 @@
 # License along with this library; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
 
-from .msgs import create_request_by_name
+"""BMC device commands: device ID, resets, I2C access and watchdog timer.
+
+The commands are the methods of :class:`Bmc`, which are available on
+:class:`pyipmi.Ipmi`.
+
+Example:
+    Print the device ID and the firmware version of the BMC::
+
+        device_id = ipmi.get_device_id()
+        print(device_id.device_id, device_id.fw_revision)
+"""
+
+from __future__ import annotations
+
+from array import array
+
+from .msgs import create_request_by_name, Message
 from .utils import check_completion_code
 from .state import State
 from .fields import VersionField
+from .constants import manufacturer_name
+from .mixin import IpmiMixin
+
+
+class Bmc(IpmiMixin):
+    """BMC device commands, available on :class:`pyipmi.Ipmi`."""
 
+    def get_device_id(self) -> DeviceId:
+        """Get the device ID of the controller.
 
-class Bmc(object):
-    def get_device_id(self):
+        Returns:
+            The device ID, firmware version, IPMI version and supported
+            functions of the controller.
+        """
         return DeviceId(self.send_message_with_name('GetDeviceId'))
 
-    def get_device_guid(self):
+    def get_device_guid(self) -> DeviceGuid:
+        """Get the GUID of the controller.
+
+        Returns:
+            The device GUID.
+        """
         return DeviceGuid(self.send_message_with_name('GetDeviceGuid'))
 
-    def cold_reset(self):
+    def cold_reset(self) -> None:
+        """Cold reset the controller, it is reinitialized."""
         self.send_message_with_name('ColdReset')
 
-    def warm_reset(self):
+    def warm_reset(self) -> None:
+        """Warm reset the controller, its state is kept."""
         self.send_message_with_name('WarmReset')
 
-    def i2c_write_read(self, bus_type, bus_id, channel, address, count,
-                       data=None):
+    def i2c_write_read(self, bus_type: int, bus_id: int, channel: int,
+                       address: int, count: int,
+                       data: bytes | None = None) -> array:
+        """Write to and read from a device on an I2C bus of the controller.
+
+        The data is written first, then ``count`` bytes are read.
+
+        Args:
+            bus_type: 0 for a public bus (IPMB), 1 for a private bus.
+            bus_id: The bus ID.
+            channel: The channel number of a public bus.
+            address: The 7-bit I2C address of the device.
+            count: The number of bytes to read.
+            data: The data to write, nothing is written if None or empty.
+
+        Returns:
+            The data read.
+
+        Raises:
+            CompletionCodeError: The controller rejected the request, e.g.
+                because the device did not acknowledge.
+        """
         req = create_request_by_name('MasterWriteRead')
         req.bus_id.type = bus_type
         req.bus_id.id = bus_id
@@ -47,14 +100,55 @@ class Bmc(object):
         check_completion_code(rsp.completion_code)
         return rsp.data
 
-    def i2c_write(self, bus_type, bus_id, channel, address, data):
+    def i2c_write(self, bus_type: int, bus_id: int, channel: int,
+                  address: int, data: bytes) -> None:
+        """Write to a device on an I2C bus of the controller.
+
+        Args:
+            bus_type: 0 for a public bus (IPMB), 1 for a private bus.
+            bus_id: The bus ID.
+            channel: The channel number of a public bus.
+            address: The 7-bit I2C address of the device.
+            data: The data to write.
+
+        Raises:
+            CompletionCodeError: The controller rejected the request.
+        """
         self.i2c_write_read(bus_type, bus_id, channel, address, 0, data)
 
-    def i2c_read(self, bus_type, bus_id, channel, address, count):
+    def i2c_read(self, bus_type: int, bus_id: int, channel: int,
+                 address: int, count: int) -> array:
+        """Read from a device on an I2C bus of the controller.
+
+        Args:
+            bus_type: 0 for a public bus (IPMB), 1 for a private bus.
+            bus_id: The bus ID.
+            channel: The channel number of a public bus.
+            address: The 7-bit I2C address of the device.
+            count: The number of bytes to read.
+
+        Returns:
+            The data read.
+
+        Raises:
+            CompletionCodeError: The controller rejected the request.
+        """
         return self.i2c_write_read(bus_type, bus_id, channel,
                                    address, count, None)
 
-    def set_watchdog_timer(self, config):
+    def set_watchdog_timer(self, config: Watchdog) -> None:
+        """Set the watchdog timer.
+
+        The timer is started with :meth:`reset_watchdog_timer`.
+
+        Args:
+            config: The settings of the watchdog timer. All attributes
+                except ``is_running`` and ``present_countdown`` have to be
+                set.
+
+        Raises:
+            CompletionCodeError: The controller rejected the settings.
+        """
         req = create_request_by_name('SetWatchdogTimer')
         req.timer_use.timer_use = config.timer_use
         req.timer_use.dont_stop = config.dont_stop and 1 or 0
@@ -69,14 +163,49 @@ class Bmc(object):
         rsp = self.send_message(req)
         check_completion_code(rsp.completion_code)
 
-    def get_watchdog_timer(self):
+    def get_watchdog_timer(self) -> Watchdog:
+        """Get the settings and the present countdown of the watchdog timer.
+
+        Returns:
+            The watchdog timer, ``dont_stop`` is not set.
+        """
         return Watchdog(self.send_message_with_name('GetWatchdogTimer'))
 
-    def reset_watchdog_timer(self):
+    def reset_watchdog_timer(self) -> None:
+        """Start or restart the watchdog timer with its initial countdown.
+
+        Raises:
+            CompletionCodeError: The timer was not set before (0x80).
+        """
         self.send_message_with_name('ResetWatchdogTimer')
 
 
 class Watchdog(State):
+    """The settings of the watchdog timer.
+
+    The ``TIMER_USE_*`` and ``TIMEOUT_ACTION_*`` constants are the timer
+    uses and the timeout actions.
+
+    Attributes:
+        timer_use (int): The use of the timer, one of the ``TIMER_USE_*``
+            constants.
+        is_running (bool): Only returned: the timer is running.
+        dont_log (bool): Don't log the timer expiration in the SEL.
+        pre_timeout_interrupt (int): The interrupt before the timeout
+            action: 0 none, 1 SMI, 2 NMI / diagnostic interrupt, 3 messaging
+            interrupt.
+        timeout_action (int): The action on the timer expiration, one of
+            the ``TIMEOUT_ACTION_*`` constants.
+        pre_timeout_interval (int): The time in seconds before the timeout
+            action at which the pre-timeout interrupt is generated.
+        timer_use_expiration_flags (int): A bit mask with one bit per timer
+            use, bit 1 for BIOS FRB2 up to bit 5 for OEM: the expired timer
+            uses when returned, the flags to clear when set.
+        initial_countdown (int): The countdown value in 100 ms units.
+        present_countdown (int): Only returned: the present countdown value
+            in 100 ms units.
+    """
+
     TIMER_USE_OEM = 5
     TIMER_USE_SMS_OS = 4
     TIMER_USE_OS_LOAD = 3
@@ -88,8 +217,12 @@ class Watchdog(State):
     TIMEOUT_ACTION_POWER_DOWN = 2
     TIMEOUT_ACTION_POWER_CYCLE = 3
 
+    #: Only used to set the timer: keep a running timer running. It is not
+    #: returned by :meth:`Bmc.get_watchdog_timer`.
+    dont_stop: bool | None
+
     __properties__ = [
-        # (propery, description)
+        # (property, description)
         ('timer_use', ''),
         ('dont_stop', ''),
         ('is_running', ''),
@@ -102,7 +235,7 @@ class Watchdog(State):
         ('present_countdown', ''),
     ]
 
-    def _from_response(self, rsp):
+    def _from_response(self, rsp: Message) -> None:
         self.timer_use = rsp.timer_use.timer_use
         self.is_running = bool(rsp.timer_use.is_running)
         self.dont_log = bool(rsp.timer_use.dont_log)
@@ -115,8 +248,30 @@ class Watchdog(State):
 
 
 class DeviceId(State):
-
-    def __str__(self):
+    """The device ID of a controller.
+
+    Attributes:
+        device_id (int): The device ID.
+        revision (int): The device revision.
+        provides_sdrs (bool): The device provides device SDRs.
+        available (bool): The device firmware, an SDR update or the
+            self-initialization is in progress. Despite its name, the
+            device is in normal operation if this is False.
+        fw_revision (VersionField): The firmware revision.
+        ipmi_version (VersionField): The IPMI version, e.g. 2.0.
+        manufacturer_id (int): The IANA manufacturer ID.
+        manufacturer_name (str | None): The name of a well known
+            manufacturer, see :func:`pyipmi.constants.manufacturer_name`.
+            None for other manufacturers.
+        product_id (int): The product ID.
+        supported_functions (list[str]): The supported device functions,
+            see :meth:`supports_function`.
+        aux (list[int] | None): The auxiliary firmware revision, None if
+            the controller does not report it.
+    """
+
+    def __str__(self) -> str:
+        """Return the device ID fields as one line."""
         string = 'Device ID: %d' % self.device_id
         string += ' revision: %d' % self.revision
         string += ' available: %d' % self.available
@@ -127,15 +282,20 @@ class DeviceId(State):
         string += ' functions: %s' % ','.join(self.supported_functions)
         return string
 
-    def supports_function(self, name):
-        """Return if a function is supported.
+    def supports_function(self, name: str) -> bool:
+        """Return whether the device supports a function.
+
+        Args:
+            name: The function, one of 'SENSOR', 'SDR_REPOSITORY', 'SEL',
+                'FRU_INVENTORY', 'IPMB_EVENT_RECEIVER',
+                'IPMB_EVENT_GENERATOR', 'BRIDGE' or 'CHASSIS', in any case.
 
-        `name` is one of 'SENSOR', 'SDR_REPOSITORY', 'SEL', 'FRU_INVENTORY',
-        'IPMB_EVENT_RECEIVER', 'IPMB_EVENT_GENERATOR', 'BRIDGE', 'CHASSIS'.
+        Returns:
+            True if the function is supported.
         """
         return name.lower() in self.supported_functions
 
-    def _from_response(self, rsp):
+    def _from_response(self, rsp: Message) -> None:
         self.device_id = rsp.device_id
         self.revision = rsp.device_revision.device_revision
         self.provides_sdrs = bool(rsp.device_revision.provides_device_sdrs)
@@ -148,6 +308,7 @@ class DeviceId(State):
             (rsp.ipmi_version & 0xf, (rsp.ipmi_version >> 4) & 0xf))
 
         self.manufacturer_id = rsp.manufacturer_id
+        self.manufacturer_name = manufacturer_name(self.manufacturer_id)
         self.product_id = rsp.product_id
 
         self.supported_functions = []
@@ -171,10 +332,18 @@ class DeviceId(State):
 
 
 class DeviceGuid(State):
-    def __str__(self):
+    """The GUID of a controller.
+
+    Attributes:
+        device_guid (Sequence[int]): The 16 bytes of the GUID as returned.
+        device_guid_string (str): The GUID in the usual string format.
+    """
+
+    def __str__(self) -> str:
+        """Return the GUID string."""
         return 'Device GUID: %s' % self.device_guid_string
 
-    def _from_response(self, rsp):
+    def _from_response(self, rsp: Message) -> None:
         self.device_guid = rsp.device_guid
         self.device_guid_string = \
             '%02x%02x%02x%02x-%02x%02x-%02x%02x-%02x%02x-' \