slurmctld: more docs

Author: tazend

pyslurm/core/slurmctld/base.pxd

@@ -40,8 +40,21 @@ from pyslurm.utils cimport cstr
 
 
 cdef class PingResponse:
-    """Slurm Controller Ping response information"""
+    """Slurm Controller Ping response information
 
+    Attributes:
+        is_primary (bool):
+            Whether this Slurm Controller is the primary Server.
+        is_responding (bool):
+            Whether this Slurm Controller actually responds to the ping.
+        index (int):
+            The index in the slurm.conf. For example, 0 means primary.
+        hostname (str):
+            Hostname of the Controller
+        latency (float):
+            The latency which the Controller responds with. This is in
+            milliseconds.
+    """
     cdef public:
         is_primary
         is_responding

pyslurm/core/slurmctld/base.pyx

@@ -25,11 +25,11 @@
 from pyslurm.core.error import verify_rpc, RPCError
 from pyslurm.utils.helpers import instance_to_dict
 from pyslurm.utils import cstr
+from pyslurm.utils.uint import u16_parse
 from typing import Union
 import time
 from enum import IntEnum
 from .config import Config
-from pyslurm.utils.uint import u16_parse
 from .enums import ShutdownMode
 
 
@@ -88,6 +88,12 @@ def ping_primary():
 
     Returns:
         (pyslurm.slurmctld.PingResponse): a ping response
+
+    Examples:
+        >>> from pyslurm import slurmctld
+        >>> resp = slurmctld.ping_primary()
+        >>> print(resp.hostname, resp.latency, resp.is_primary)
+        slurmctl 1.222 True
     """
     return ping(0)
 
@@ -99,6 +105,12 @@ def ping_backup():
 
     Returns:
         (pyslurm.slurmctld.PingResponse): a ping response
+
+    Examples:
+        >>> from pyslurm import slurmctld
+        >>> resp = slurmctld.ping_backup()
+        >>> print(resp.hostname, resp.latency, resp.is_primary)
+        slurmctlbackup 1.373 False
     """
     return ping(1)
 
@@ -140,6 +152,10 @@ def shutdown(mode: Union[ShutdownMode, int]):
 
     Raises:
         (pyslurm.RPCError): When shutdowning the daemons was not successful.
+
+    Examples:
+        >>> from pyslurm import slurmctld
+        >>> slurmctld.shutdown(slurmctld.ShutdownMode.ALL)
     """
     verify_rpc(slurm_shutdown(int(mode)))
 
@@ -149,6 +165,10 @@ def reconfigure():
 
     Raises:
         (pyslurm.RPCError): When reconfiguring was not successful.
+
+    Examples:
+        >>> from pyslurm import slurmctld
+        >>> slurmctld.reconfigure()
     """
     verify_rpc(slurm_reconfigure())
 
@@ -168,6 +188,10 @@ def takeover(index = 1):
 
     Raises:
         (pyslurm.RPCError): When reconfiguring was not successful.
+
+    Examples:
+        >>> from pyslurm import slurmctld
+        >>> slurmctld.takeover(1)
     """
     verify_rpc(slurm_takeover(index))
 
@@ -176,7 +200,7 @@ def add_debug_flags(flags):
     """Add DebugFlags to slurmctld
 
     Args:
-        flags (list):
+        flags (list[str]):
             For an available list of possible values, please check the
             `slurm.conf` documentation under `DebugFlags`.
 
@@ -185,7 +209,7 @@ def add_debug_flags(flags):
 
     Examples:
         >>> from pyslurm import slurmctld
-        >>> slurmctld.add_debug_flags(["CpuFrequency"])
+        >>> slurmctld.add_debug_flags(["CpuFrequency", "Backfill"])
     """
     if not flags:
         return
@@ -201,7 +225,7 @@ def remove_debug_flags(flags):
     """Remove DebugFlags from slurmctld.
 
     Args:
-        flags (list):
+        flags (list[str]):
             For an available list of possible values, please check the
             `slurm.conf` documentation under `DebugFlags`.
 
@@ -231,6 +255,8 @@ def clear_debug_flags():
     Examples:
         >>> from pyslurm import slurmctld
         >>> slurmctld.clear_debug_flags()
+        >>> print(slurmctld.get_debug_flags())
+        []
     """
     current_flags = get_debug_flags()
     if not current_flags:
@@ -269,6 +295,9 @@ def set_log_level(level):
     Examples:
         >>> from pyslurm import slurmctld
         >>> slurmctld.set_log_level("quiet")
+        >>> log_level = slurmctld.get_log_level()
+        >>> print(log_level)
+        quiet
     """
     data = _log_level_str_to_int(level)
     verify_rpc(slurm_set_debug_level(data))
@@ -282,8 +311,8 @@ def get_log_level():
 
     Examples:
         >>> from pyslurm import slurmctld
-        >>> level = slurmctld.get_log_level()
-        >>> print(level)
+        >>> log_level = slurmctld.get_log_level()
+        >>> print(log_level)
         quiet
     """
     return Config.load().slurmctld_log_level
@@ -298,6 +327,8 @@ def enable_scheduler_logging():
     Examples:
         >>> from pyslurm import slurmctld
         >>> slurmctld.enable_scheduler_logging()
+        >>> print(slurmctld.is_scheduler_logging_enabled())
+        True
     """
     verify_rpc(slurm_set_schedlog_level(1))
 
@@ -334,6 +365,8 @@ def set_fair_share_dampening_factor(factor):
     Examples:
         >>> from pyslurm import slurmctld
         >>> slurmctld.set_fair_share_dampening_factor(100)
+        >>> print(slurmctld.get_fair_share_dampening_factor)
+        100
     """
     max_value = (2 ** 16) - 1
     if not factor or factor >= max_value:

pyslurm/core/slurmctld/config.pxd

@@ -79,6 +79,12 @@ cdef class Config:
     All attributes in this class are read-only.
 
     Attributes:
+        cgroup_config (pyslurm.slurmctld.CgroupConfig):
+            The CGroup Configuration data
+        accounting_gather_config (pyslurm.slurmctld.AccountingGatherConfig):.
+            The Accounting Gather Configuration data.
+        mpi_config (pyslurm.slurmctld.MPIConfig):
+            The MPI Configuration data.
         accounting_storage_enforce (list[str]):
             List of enforcements on Job submissions.
 
@@ -1104,7 +1110,7 @@ cdef class MPIConfig:
             of the job have the same architecture.
 
             {mpi.conf#OPT_PMIxDirectSameArch}
-        pmix_environment (dict[str, Union[str, int]):
+        pmix_environment (dict[str, Union[str, int]]):
             Environment variables to bet set in the Job environment, used by
             PMIx.
 

pyslurm/core/slurmctld/config.pyx

@@ -41,7 +41,9 @@ from typing import Union
 cdef class MPIConfig:
 
     def __init__(self):
-        raise RuntimeError("Cannot instantiate class directly")
+        raise RuntimeError("Cannot instantiate class directly. "
+                           "Use slurmctld.Config.load() and access the "
+                           "mpi_config attribute there")
 
     def to_dict(self):
         """MPI config formatted as a dictionary.
@@ -82,7 +84,9 @@ cdef class MPIConfig:
 cdef class CgroupConfig:
 
     def __init__(self):
-        raise RuntimeError("Cannot instantiate class directly")
+        raise RuntimeError("Cannot instantiate class directly. "
+                           "Use slurmctld.Config.load() and access the "
+                           "cgroup_config attribute there")
 
     def to_dict(self):
         """Cgroup config formatted as a dictionary.
@@ -128,7 +132,9 @@ cdef class CgroupConfig:
 cdef class AccountingGatherConfig:
 
     def __init__(self):
-        raise RuntimeError("Cannot instantiate class directly")
+        raise RuntimeError("Cannot instantiate class directly. "
+                           "Use slurmctld.Config.load() and access the "
+                           "accounting_gather_config attribute there")
 
     def to_dict(self):
         """AccountingGather config formatted as a dictionary.
@@ -152,10 +158,8 @@ cdef class AccountingGatherConfig:
         out.energy_ipmi_frequency = int(conf.get("EnergyIPMIFrequency", 30))
         out.energy_ipmi_calc_adjustment = _yesno_to_bool(
                 conf.get("EnergyIPMICalcAdjustment"))
-
-        # TODO: maybe dict?
-        out.energy_ipmi_power_sensors = conf.get("EnergyIPMIPowerSensors")
-
+        out.energy_ipmi_power_sensors = cstr.to_dict(
+                conf.get("EnergyIPMIPowerSensors", ""), delim1=";", delim2="=")
         out.energy_ipmi_user_name = conf.get("EnergyIPMIUsername")
         out.energy_ipmi_password = conf.get("EnergyIPMIPassword")
         out.energy_ipmi_timeout = int(conf.get("EnergyIPMITimeout", 10))
@@ -190,22 +194,6 @@ cdef class Config:
         slurm_free_ctl_conf(self.ptr)
         self.ptr = NULL
 
-    @staticmethod
-    def load_scontrol():
-        cdef Config conf = Config.__new__(Config)
-        verify_rpc(slurm_load_ctl_conf(0, &conf.ptr))
-
-        out = _parse_config_key_pairs(slurm_ctl_conf_2_key_pairs(conf.ptr),
-                                      owned=True)
-        out["CgroupSupportConfiguration"] = _parse_config_key_pairs(
-                conf.ptr.cgroup_conf)
-        out["AccountingGatherConfiguration"] = _parse_config_key_pairs(
-                conf.ptr.acct_gather_conf)
-        out["MPIPluginsConfiguration"] = _parse_config_key_pairs(
-                conf.ptr.mpi_conf)
-
-        return out
-
     @staticmethod
     def load():
         """Load the current Slurm configuration (slurm.conf)
@@ -351,7 +339,6 @@ cdef class Config:
 
     @property
     def batch_start_timeout(self):
-        # seconds
         return u16_parse(self.ptr.batch_start_timeout)
 
     @property
@@ -394,7 +381,6 @@ cdef class Config:
 
     @property
     def complete_wait_time(self):
-        # seconds
         return u16_parse(self.ptr.complete_wait)
 
     @property
@@ -442,7 +428,6 @@ cdef class Config:
 
     @property
     def eio_timeout(self):
-        # seconds
         return u16_parse(self.ptr.eio_timeout)
 
     @property
@@ -458,7 +443,6 @@ cdef class Config:
 
     @property
     def epilog_msg_time(self):
-        # ms
         return u32_parse(self.ptr.epilog_msg_time)
 
     @property
@@ -525,7 +509,6 @@ cdef class Config:
 
     @property
     def inactive_limit(self):
-        # seconds
         return u16_parse(self.ptr.inactive_limit)
 
     @property
@@ -598,7 +581,6 @@ cdef class Config:
 
     @property
     def kill_wait_time(self):
-        # seconds
         return u16_parse(self.ptr.kill_wait)
 
     @property
@@ -754,7 +736,6 @@ cdef class Config:
 
     @property
     def priority_decay_half_life(self):
-        # seconds
         return u32_parse(self.ptr.priority_decay_hl)
 
     @property
@@ -852,7 +833,6 @@ cdef class Config:
 
     @property
     def prolog_epilog_timeout(self):
-        # seconds
         return u16_parse(self.ptr.prolog_epilog_timeout)
 
     @property
@@ -942,7 +922,6 @@ cdef class Config:
 
     @property
     def scheduler_time_slice(self):
-        # seconds
         return u16_parse(self.ptr.sched_time_slice)
 
     @property
@@ -1027,7 +1006,6 @@ cdef class Config:
 
     @property
     def slurmctld_timeout(self):
-        # seconds
         return u16_parse(self.ptr.slurmctld_timeout)
 
     @property