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

pyipmi/__init__.py

@@ -14,10 +14,38 @@
 # License along with this library; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
 
+"""A pure Python IPMI library.
+
+A connection to an IPMI device is an :class:`Ipmi` object, created by
+:func:`create_connection` for an interface (see
+:func:`pyipmi.interfaces.create_interface`).
+The connection sends the requests to its :class:`Target`, the BMC or a
+controller behind it, which is reached over the :class:`Routing` hops of
+the target. The IPMI commands are the methods of :class:`Ipmi`, which
+inherits them from the command groups of the modules, e.g.
+:mod:`pyipmi.bmc` and :mod:`pyipmi.sdr`.
+
+Example:
+    Print the device ID of a BMC over RMCP+::
+
+        import pyipmi
+        import pyipmi.interfaces
+
+        interface = pyipmi.interfaces.create_interface('rmcpplus')
+        ipmi = pyipmi.create_connection(interface)
+        ipmi.session.set_session_type_rmcp('10.0.0.1', port=623)
+        ipmi.session.set_auth_type_user('admin', 'admin')
+        ipmi.target = pyipmi.Target(ipmb_address=0x20)
+
+        with ipmi:
+            print(ipmi.get_device_id())
+"""
+
 from __future__ import annotations
 
 import time
 import ast
+import warnings
 from typing import Any, Literal
 
 from . import bmc
@@ -49,6 +77,19 @@ except ImportError:
 
 
 def create_connection(interface: Any) -> Ipmi:
+    """Create a connection for an interface.
+
+    The connection gets a new :class:`pyipmi.session.Session` for the
+    interface. The target is not set, assign it to :attr:`Ipmi.target`
+    before sending requests.
+
+    Args:
+        interface: The interface, e.g. created by
+            :func:`pyipmi.interfaces.create_interface`.
+
+    Returns:
+        The connection.
+    """
     session = Session()
     session.interface = interface
     return Ipmi(interface=interface, session=session)
@@ -78,9 +119,17 @@ class NullRequester:
 
 
 class Routing:
-    """The Target class represents an IPMI target."""
+    """One hop of the path to a target, see :meth:`Target.set_routing`."""
 
     def __init__(self, rq_sa: int, rs_sa: int, channel: int | None) -> None:
+        """Initialize the hop.
+
+        Args:
+            rq_sa: The requester slave address.
+            rs_sa: The responder slave address.
+            channel: The channel of the bridge to the next hop, None for
+                the last hop.
+        """
         self.rq_sa = rq_sa
         self.rs_sa = rs_sa
         self.channel = channel
@@ -99,11 +148,14 @@ class Target:
 
     def __init__(self, ipmb_address: int | None = None,
                  routing: str | list[tuple] | None = None) -> None:
-        """Initializer for the Target class.
+        """Initialize the target.
 
-        `ipmb_address` is the IPMB target address
-        `routing` is the bridging information used to build send message
-        commands.
+        Args:
+            ipmb_address: The IPMB address of the target, e.g. 0x20 for
+                the BMC.
+            routing: The path over which the target is reachable, used to
+                build the bridged Send Message requests, see
+                :meth:`set_routing`.
         """
         if ipmb_address:
             self.ipmb_address = ipmb_address
@@ -112,6 +164,10 @@ class Target:
             self.set_routing(routing)
 
     def set_routing_information(self, routing: str | list[tuple]) -> None:
+        """Set the path over which a target is reachable.
+
+        An alias of :meth:`set_routing`.
+        """
         self.set_routing(routing)
 
     def set_routing(self, routing: str | list[tuple]) -> None:
@@ -171,10 +227,32 @@ class Target:
 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, vita.Vita):
+    """A connection to an IPMI device.
+
+    The IPMI commands are the methods of this class, which it inherits
+    from the command groups, e.g. :meth:`get_device_id` from the one of
+    :mod:`pyipmi.bmc`. The requests are sent over the interface to
+    the target.
+
+    The connection is a context manager, which opens the interface and
+    establishes the session on entry and closes them on exit. Set up the
+    session before, see the example of :mod:`pyipmi`.
+    """
 
     def __init__(self, interface: Any = None, target: Target | None = None,
                  session: Session | None = None,
                  requester: Any = None) -> None:
+        """Initialize the connection.
+
+        Args:
+            interface: The interface the requests are sent over.
+            target: The target of the requests.
+            session: The session, a new one if not given. The interface
+                of the session is set to ``interface``.
+            requester: The requester of the requests, needed by interfaces
+                that send the requests on the IPMB, a
+                :class:`NullRequester` if not given.
+        """
         self._interface = interface
 
         # we need a session, set if not passed
@@ -200,30 +278,83 @@ class Ipmi(bmc.Bmc, chassis.Chassis, dcmi.Dcmi, fru.Fru, picmg.Picmg, hpm.Hpm,
         return False
 
     def open(self) -> None:
+        """Open the interface and establish the session."""
         self.interface.open()
         if self.session is not None:
             self.session.establish()
 
     def close(self) -> None:
+        """Close the session and the interface."""
         if self.session is not None:
             self.session.close()
         self.interface.close()
 
+    def is_target_accessible(self) -> bool:
+        """Check if the target answers.
+
+        Returns:
+            True if the target answers. Depending on the interface, False
+            is returned or an exception is raised if it does not.
+        """
+        return self.interface.is_target_accessible(self.target)
+
     def is_ipmc_accessible(self) -> bool:
-        return self.interface.is_ipmc_accessible(self.target)
+        """Deprecated, the old name of :meth:`is_target_accessible`."""
+        warnings.warn('is_ipmc_accessible is deprecated, use '
+                      'is_target_accessible', DeprecationWarning,
+                      stacklevel=2)
+        return self.is_target_accessible()
 
-    def wait_until_ipmb_is_accessible(self, timeout: float,
-                                      interval: float = 0.25) -> None:
+    def wait_until_target_is_accessible(self, timeout: float,
+                                        interval: float = 0.25) -> None:
+        """Wait until the target is accessible.
+
+        Args:
+            timeout: The time to wait in seconds.
+            interval: The time between the checks in seconds.
+
+        Raises:
+            IpmiTimeoutError: The target is not accessible after the
+                timeout, if the interface raises it, see
+                :meth:`is_target_accessible`.
+        """
         start_time = time.time()
         while time.time() < start_time + (timeout):
             try:
-                self.is_ipmc_accessible()
+                if self.is_target_accessible():
+                    return
             except IpmiTimeoutError:
-                time.sleep(interval)
+                pass
+            time.sleep(interval)
+
+        self.is_target_accessible()
 
-        self.is_ipmc_accessible()
+    def wait_until_ipmb_is_accessible(self, timeout: float,
+                                      interval: float = 0.25) -> None:
+        """Deprecated, use :meth:`wait_until_target_is_accessible`."""
+        warnings.warn('wait_until_ipmb_is_accessible is deprecated, use '
+                      'wait_until_target_is_accessible', DeprecationWarning,
+                      stacklevel=2)
+        self.wait_until_target_is_accessible(timeout, interval)
 
     def send_message(self, req: Message, retry: int = 3) -> Message:
+        """Send a request to the target and return the response.
+
+        The request is sent again if the target is busy. The completion
+        code of the response is not checked.
+
+        Args:
+            req: The request message.
+            retry: The number of tries.
+
+        Returns:
+            The response message.
+
+        Raises:
+            RetryError: The target is still busy after ``retry`` tries.
+            CompletionCodeError: The interface failed with another
+                completion code, e.g. of a bridged Send Message request.
+        """
         req.target = self.target
         req.requester = self.requester
         rsp = None
@@ -236,13 +367,28 @@ class Ipmi(bmc.Bmc, chassis.Chassis, dcmi.Dcmi, fru.Fru, picmg.Picmg, hpm.Hpm,
             except CompletionCodeError as e:
                 if e.cc == msgs.constants.CC_NODE_BUSY:
                     continue
+                raise
         else:
             raise RetryError()
 
         return rsp
 
-    def send_message_with_name(self, name: str, *args: Any,
-                               **kwargs: Any) -> Message:
+    def send_message_by_name(self, name: str, *args: Any,
+                             **kwargs: Any) -> Message:
+        """Send a request by its name and return the response.
+
+        Args:
+            name: The name of the request, e.g. ``'GetDeviceId'``.
+            *args: Not used.
+            **kwargs: The fields of the request, set as attributes.
+
+        Returns:
+            The response message.
+
+        Raises:
+            CompletionCodeError: The completion code of the response is
+                not successful.
+        """
         req = create_request_by_name(name)
 
         for key, value in kwargs.items():
@@ -252,20 +398,37 @@ 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: int, netfn: int, raw_bytes: bytes) -> bytes:
-        """Send the raw command data and return the raw response.
+    def send_message_with_name(self, name: str, *args: Any,
+                               **kwargs: Any) -> Message:
+        """Deprecated, the old name of :meth:`send_message_by_name`."""
+        warnings.warn('send_message_with_name is deprecated, use '
+                      'send_message_by_name', DeprecationWarning,
+                      stacklevel=2)
+        return self.send_message_by_name(name, *args, **kwargs)
 
-        lun: the logical unit number
-        netfn: the network function
-        raw_bytes: the raw message as bytestring
+    def send_raw(self, lun: int, netfn: int, raw_bytes: bytes) -> bytes:
+        """Send a raw request to the target and return the raw response.
 
-        Returns the response as bytestring.
+        Args:
+            lun: The logical unit number.
+            netfn: The network function.
+            raw_bytes: The request, starting with the command ID.
+
+        Returns:
+            The response, starting with the completion code.
         """
         return self.interface.send_and_receive_raw(self.target, lun, netfn,
                                                    raw_bytes)
 
+    def raw_command(self, lun: int, netfn: int, raw_bytes: bytes) -> bytes:
+        """Deprecated, the old name of :meth:`send_raw`."""
+        warnings.warn('raw_command is deprecated, use send_raw',
+                      DeprecationWarning, stacklevel=2)
+        return self.send_raw(lun, netfn, raw_bytes)
+
     @property
     def interface(self) -> Any:
+        """The interface the requests are sent over."""
         try:
             return self._interface
         except AttributeError:
@@ -277,6 +440,7 @@ class Ipmi(bmc.Bmc, chassis.Chassis, dcmi.Dcmi, fru.Fru, picmg.Picmg, hpm.Hpm,
 
     @property
     def session(self) -> Session:
+        """The session of the connection."""
         try:
             return self._session
         except AttributeError:
@@ -288,6 +452,7 @@ class Ipmi(bmc.Bmc, chassis.Chassis, dcmi.Dcmi, fru.Fru, picmg.Picmg, hpm.Hpm,
 
     @property
     def target(self) -> Target | None:
+        """The target of the requests."""
         try:
             return self._target
         except AttributeError:

pyipmi/bmc.py

@@ -48,7 +48,7 @@ class Bmc(IpmiMixin):
             The device ID, firmware version, IPMI version and supported
             functions of the controller.
         """
-        return DeviceId(self.send_message_with_name('GetDeviceId'))
+        return DeviceId(self.send_message_by_name('GetDeviceId'))
 
     def get_device_guid(self) -> DeviceGuid:
         """Get the GUID of the controller.
@@ -56,15 +56,15 @@ class Bmc(IpmiMixin):
         Returns:
             The device GUID.
         """
-        return DeviceGuid(self.send_message_with_name('GetDeviceGuid'))
+        return DeviceGuid(self.send_message_by_name('GetDeviceGuid'))
 
     def cold_reset(self) -> None:
         """Cold reset the controller, it is reinitialized."""
-        self.send_message_with_name('ColdReset')
+        self.send_message_by_name('ColdReset')
 
     def warm_reset(self) -> None:
         """Warm reset the controller, its state is kept."""
-        self.send_message_with_name('WarmReset')
+        self.send_message_by_name('WarmReset')
 
     def i2c_write_read(self, bus_type: int, bus_id: int, channel: int,
                        address: int, count: int,
@@ -169,7 +169,7 @@ class Bmc(IpmiMixin):
         Returns:
             The watchdog timer, ``dont_stop`` is not set.
         """
-        return Watchdog(self.send_message_with_name('GetWatchdogTimer'))
+        return Watchdog(self.send_message_by_name('GetWatchdogTimer'))
 
     def reset_watchdog_timer(self) -> None:
         """Start or restart the watchdog timer with its initial countdown.
@@ -177,7 +177,7 @@ class Bmc(IpmiMixin):
         Raises:
             CompletionCodeError: The timer was not set before (0x80).
         """
-        self.send_message_with_name('ResetWatchdogTimer')
+        self.send_message_by_name('ResetWatchdogTimer')
 
 
 class Watchdog(State):

pyipmi/chassis.py

@@ -207,7 +207,7 @@ class Chassis(IpmiMixin):
         Returns:
             The chassis status.
         """
-        return ChassisStatus(self.send_message_with_name('GetChassisStatus'))
+        return ChassisStatus(self.send_message_by_name('GetChassisStatus'))
 
     def chassis_control(self, option: int) -> None:
         """Control the chassis power.

pyipmi/dcmi.py

@@ -92,8 +92,8 @@ class Dcmi(IpmiMixin):
             (bits ``major`` and ``minor``, the DCMI version),
             ``parameter_revision`` and ``parameter_data``.
         """
-        rsp = self.send_message_with_name('GetDcmiCapabilities',
-                                          parameter_selector=selector)
+        rsp = self.send_message_by_name('GetDcmiCapabilities',
+                                        parameter_selector=selector)
         return rsp
 
     def get_power_reading(self, mode: int, attributes: int = 0) -> Message:
@@ -113,8 +113,8 @@ class Dcmi(IpmiMixin):
             ``reading_state`` (bit 6 is set if the power measurement is
             active).
         """
-        rsp = self.send_message_with_name('GetPowerReading',
-                                          mode=mode, attributes=attributes)
+        rsp = self.send_message_by_name('GetPowerReading',
+                                        mode=mode, attributes=attributes)
         return rsp
 
     def _get_all_instances(self, name: str, entity_id: int,
@@ -131,11 +131,11 @@ class Dcmi(IpmiMixin):
         items: list[Any] = []
         start = 0
         while True:
-            rsp = self.send_message_with_name(name,
-                                              sensor_type=1,
-                                              entity_id=entity_id,
-                                              entity_instance=0,
-                                              entity_instance_start=start)
+            rsp = self.send_message_by_name(name,
+                                            sensor_type=1,
+                                            entity_id=entity_id,
+                                            entity_instance=0,
+                                            entity_instance_start=start)
             received = decode(rsp)
             new = [(k, i) for (k, i) in received if k not in keys]
             for (k, i) in new:
@@ -204,7 +204,7 @@ class Dcmi(IpmiMixin):
             CompletionCodeError: The BMC rejected the request, e.g. if no
                 power limit is set (0x80).
         """
-        return self.send_message_with_name('GetPowerLimit')
+        return self.send_message_by_name('GetPowerLimit')
 
     def set_power_limit(self, power_limit: int, correction_time_limit: int,
                         statistics_sampling_period: int,
@@ -223,7 +223,7 @@ class Dcmi(IpmiMixin):
             exception_actions: The action if the limit is exceeded, one of
                 the ``POWER_LIMIT_EXCEPTION_*`` constants.
         """
-        self.send_message_with_name(
+        self.send_message_by_name(
                 'SetPowerLimit',
                 exception_actions=exception_actions,
                 power_limit=power_limit,
@@ -232,13 +232,13 @@ class Dcmi(IpmiMixin):
 
     def activate_power_limit(self) -> None:
         """Activate the power limit."""
-        self.send_message_with_name('ActivateDeactivatePowerLimit',
-                                    activation=1)
+        self.send_message_by_name('ActivateDeactivatePowerLimit',
+                                  activation=1)
 
     def deactivate_power_limit(self) -> None:
         """Deactivate the power limit."""
-        self.send_message_with_name('ActivateDeactivatePowerLimit',
-                                    activation=0)
+        self.send_message_by_name('ActivateDeactivatePowerLimit',
+                                  activation=0)
 
     def get_thermal_limit(self, entity_id: int,
                           entity_instance: int) -> Message:
@@ -254,9 +254,9 @@ class Dcmi(IpmiMixin):
             ``temperature_limit`` in degree Celsius and ``exception_time``
             in seconds.
         """
-        return self.send_message_with_name('GetThermalLimit',
-                                           entity_id=entity_id,
-                                           entity_instance=entity_instance)
+        return self.send_message_by_name('GetThermalLimit',
+                                         entity_id=entity_id,
+                                         entity_instance=entity_instance)
 
     def set_thermal_limit(self, entity_id: int, entity_instance: int,
                           temperature_limit: int, exception_time: int,
@@ -301,9 +301,9 @@ class Dcmi(IpmiMixin):
             (bits ``major`` and ``minor``), ``parameter_revision`` and
             ``parameter_data``.
         """
-        return self.send_message_with_name('GetDcmiConfigurationParameters',
-                                           parameter_selector=selector,
-                                           set_selector=set_selector)
+        return self.send_message_by_name('GetDcmiConfigurationParameters',
+                                         parameter_selector=selector,
+                                         set_selector=set_selector)
 
     def set_dcmi_configuration_parameters(self, selector: int, data: bytes,
                                           set_selector: int = 0) -> None:
@@ -314,21 +314,21 @@ class Dcmi(IpmiMixin):
             data: The parameter data.
             set_selector: The set selector of the parameter.
         """
-        self.send_message_with_name('SetDcmiConfigurationParameters',
-                                    parameter_selector=selector,
-                                    set_selector=set_selector,
-                                    parameter_data=data)
+        self.send_message_by_name('SetDcmiConfigurationParameters',
+                                  parameter_selector=selector,
+                                  set_selector=set_selector,
+                                  parameter_data=data)
 
     def _get_dcmi_string(self, name: str, length_request_size: int) -> bytes:
         # the first request is only used to get the total length
-        rsp = self.send_message_with_name(name, offset=0,
-                                          number_of_bytes=length_request_size)
+        rsp = self.send_message_by_name(name, offset=0,
+                                        number_of_bytes=length_request_size)
         total_length = rsp.total_length
         data = b''
         while len(data) < total_length:
             count = min(MAX_STRING_CHUNK_SIZE, total_length - len(data))
-            rsp = self.send_message_with_name(name, offset=len(data),
-                                              number_of_bytes=count)
+            rsp = self.send_message_by_name(name, offset=len(data),
+                                            number_of_bytes=count)
             chunk = rsp.data.tobytes()
             if not chunk:
                 break
@@ -338,9 +338,9 @@ class Dcmi(IpmiMixin):
     def _set_dcmi_string(self, name: str, data: bytes) -> None:
         for offset in range(0, len(data), MAX_STRING_CHUNK_SIZE):
             chunk = data[offset:offset + MAX_STRING_CHUNK_SIZE]
-            self.send_message_with_name(name, offset=offset,
-                                        number_of_bytes=len(chunk),
-                                        data=chunk)
+            self.send_message_by_name(name, offset=offset,
+                                      number_of_bytes=len(chunk),
+                                      data=chunk)
 
     def get_asset_tag(self) -> str:
         """Return the asset tag of the system.

pyipmi/fields.py

@@ -53,7 +53,13 @@ class VersionField:
 
 
 def _unpack6bitascii(data: Sequence[int]) -> str:
-    """Unpack the 6bit ascii encoded string."""
+    """Unpack the 6bit ascii encoded string.
+
+    The characters are packed in groups of 3 bytes, the last group can be
+    shorter, e.g. 5 characters take 4 bytes.
+    """
+    count = len(data) * 8 // 6
+    data = list(data) + [0] * (-len(data) % 3)
     string = ''
     for i in range(0, len(data), 3):
         d = data[i:i+3]
@@ -61,7 +67,7 @@ def _unpack6bitascii(data: Sequence[int]) -> str:
         string += chr(0x20 + (((d[0] & 0xc0) >> 6) | ((d[1] & 0xf) << 2)))
         string += chr(0x20 + (((d[1] & 0xf0) >> 4) | ((d[2] & 0x3) << 4)))
         string += chr(0x20 + ((d[2] & 0xfc) >> 2))
-    return string
+    return string[:count]
 
 
 class TypeLengthString:

pyipmi/fru.py

@@ -82,8 +82,8 @@ class Fru(IpmiMixin):
         Returns:
             The size of the FRU inventory area in bytes.
         """
-        rsp = self.send_message_with_name('GetFruInventoryAreaInfo',
-                                          fru_id=fru_id)
+        rsp = self.send_message_by_name('GetFruInventoryAreaInfo',
+                                        fru_id=fru_id)
         return rsp.area_size
 
     def write_fru_data(self, data: bytes, offset: int = 0,
@@ -101,10 +101,10 @@ class Fru(IpmiMixin):
             Exception: The device wrote fewer bytes than were sent.
         """
         for chunk in chunks(data, self.write_length):
-            write_rsp = self.send_message_with_name('WriteFruData',
-                                                    fru_id=fru_id,
-                                                    offset=offset,
-                                                    data=chunk)
+            write_rsp = self.send_message_by_name('WriteFruData',
+                                                  fru_id=fru_id,
+                                                  offset=offset,
+                                                  data=chunk)
 
             # check if device wrote the same number of bytes sent
             if write_rsp.count_written != len(chunk):
@@ -147,8 +147,8 @@ class Fru(IpmiMixin):
             req_size = min(read_length.length, area_size - off)
 
             try:
-                rsp = self.send_message_with_name('ReadFruData', fru_id=fru_id,
-                                                  offset=off, count=req_size)
+                rsp = self.send_message_by_name('ReadFruData', fru_id=fru_id,
+                                                offset=off, count=req_size)
             except CompletionCodeError as ex:
                 if ex.cc in (constants.CC_CANT_RET_NUM_REQ_BYTES,
                              constants.CC_REQ_DATA_FIELD_EXCEED,