More doc improvements and other fixes (#306)

* Improved docs + better custom repr

* Add __or__, __ror__ and __ior__ to MultiClusterMap

* Use from_ptr method when loading single Job/Step/Node

Author: tazend

CHANGELOG.md

@@ -11,15 +11,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Ability to modify Database Jobs
 - New classes to interact with the Partition API
-    - [pyslurm.Partition](https://pyslurm.github.io/23.2/reference/partition/#pyslurm.Partition)
-    - [pyslurm.Partitions](https://pyslurm.github.io/23.2/reference/partition/#pyslurm.Partitions)
+    - [pyslurm.Partition][]
+    - [pyslurm.Partitions][]
 - New attributes for a Database Job:
-    - extra
-    - failed_node
-- Now possible to initialize a [pyslurm.db.Jobs][] collection with existing job
-  ids or pyslurm.db.Job objects
-- Added `as_dict` function to all Collections
+    - `extra`
+    - `failed_node`
 - Added a new Base Class [MultiClusterMap][pyslurm.xcollections.MultiClusterMap] that some Collections inherit from.
+- Added `to_json` function to all Collections
 
 ### Fixed
 
@@ -29,9 +27,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     - the Job was older than a day
 
 ### Changed
- 
-- `JobSearchFilter` has been renamed to `JobFilter`
-- Renamed `as_dict` Function of some classes to `to_dict`
+
+- Improved Docs
+- Renamed `JobSearchFilter` to [pyslurm.db.JobFilter][]
+- Renamed `as_dict` function of some classes to `to_dict`
 
 ## [23.2.1](https://github.com/PySlurm/pyslurm/releases/tag/v23.2.1) - 2023-05-18
 

docs/reference/index.md

@@ -25,7 +25,7 @@ The `pyslurm` package is a wrapper around the Slurm C-API
     it!
 
 
-## Functionality already reworked:
+## Reworked Classes
 
 * Job API
     * [pyslurm.Job][]

pyslurm/core/job/job.pxd

@@ -69,10 +69,10 @@ cdef class Jobs(MultiClusterMap):
     """A [`Multi Cluster`][pyslurm.xcollections.MultiClusterMap] collection of [pyslurm.Job][] objects.
 
     Args:
-        jobs (Union[list, dict], optional=None):
+        jobs (Union[list[int], dict[int, pyslurm.Job], str], optional=None):
             Jobs to initialize this collection with.
         frozen (bool, optional=False):
-            Control whether this collection is "frozen" when reloading Job
+            Control whether this collection is `frozen` when reloading Job
             information.
 
     Attributes:

pyslurm/core/job/job.pyx

@@ -89,6 +89,14 @@ cdef class Jobs(MultiClusterMap):
 
         Raises:
             RPCError: When getting all the Jobs from the slurmctld failed.
+
+        Examples:
+            >>> import pyslurm
+            >>> jobs = pyslurm.Jobs.load()
+            >>> print(jobs)
+            pyslurm.Jobs({1: pyslurm.Job(1), 2: pyslurm.Job(2)})
+            >>> print(jobs[1])
+            pyslurm.Job(1)
         """
         cdef:
             dict passwd = {}
@@ -134,6 +142,9 @@ cdef class Jobs(MultiClusterMap):
     def reload(self):
         """Reload the information for jobs in a collection.
 
+        Returns:
+            (pyslurm.Partitions): Returns self
+
         Raises:
             RPCError: When getting the Jobs from the slurmctld failed.
         """
@@ -203,7 +214,7 @@ cdef class Job:
         self._dealloc_impl()
 
     def __repr__(self):
-        return f'{self.__class__.__name__}({self.id})'
+        return f'pyslurm.{self.__class__.__name__}({self.id})'
 
     @staticmethod
     def load(job_id):
@@ -233,15 +244,13 @@ cdef class Job:
         """
         cdef:
             job_info_msg_t *info = NULL
-            Job wrap = Job.__new__(Job)
+            Job wrap = None
 
         try: 
             verify_rpc(slurm_load_job(&info, job_id, slurm.SHOW_DETAIL))
 
             if info and info.record_count:
-                # Copy info
-                wrap._alloc_impl()
-                memcpy(wrap.ptr, &info.job_array[0], sizeof(slurm_job_info_t))
+                wrap = Job.from_ptr(&info.job_array[0])
                 info.record_count = 0
 
                 if not slurm.IS_JOB_PENDING(wrap.ptr):

pyslurm/core/job/step.pyx

@@ -59,6 +59,10 @@ cdef class JobSteps(dict):
         elif steps is not None:
             raise TypeError("Invalid Type: {type(steps)}")
 
+    def __repr__(self):
+        data = super().__repr__()
+        return f'pyslurm.{self.__class__.__name__}({data})'
+
     @staticmethod
     def load(job):
         """Load the Job Steps from the system.
@@ -69,6 +73,14 @@ cdef class JobSteps(dict):
 
         Returns:
             (pyslurm.JobSteps): JobSteps of the Job
+
+        Examples:
+            >>> import pyslurm
+            >>> steps = pyslurm.JobSteps.load(1)
+            >>> print(steps)
+            pyslurm.JobSteps({'batch': pyslurm.JobStep('batch')})
+            >>> print(steps[1])
+            pyslurm.JobStep('batch')
         """
         cdef:
             Job _job
@@ -187,7 +199,7 @@ cdef class JobStep:
         JobStep.__dict__[name].__set__(self, val)
 
     def __repr__(self):
-        return f'{self.__class__.__name__}({self.id})'
+        return f'pyslurm.{self.__class__.__name__}({self.id})'
 
     @staticmethod
     def load(job_id, step_id):
@@ -214,17 +226,15 @@ cdef class JobStep:
         """
         cdef:
             job_step_info_response_msg_t *info = NULL
-            JobStep wrap = JobStep.__new__(JobStep)
+            JobStep wrap = None
 
         job_id = job_id.id if isinstance(job_id, Job) else job_id
         rc = slurm_get_job_steps(<time_t>0, job_id, dehumanize_step_id(step_id),
                                        &info, slurm.SHOW_ALL)
         verify_rpc(rc)
 
         if info and info.job_step_count == 1:
-            # Copy new info
-            wrap._alloc_impl()
-            memcpy(wrap.ptr, &info.job_steps[0], sizeof(job_step_info_t))
+            wrap = JobStep.from_ptr(&info.job_steps[0])
             info.job_step_count = 0
             slurm_free_job_step_info_response_msg(info)
         else:

pyslurm/core/job/submission.pxd

@@ -495,9 +495,9 @@ cdef class JobSubmitDescription:
         standard_in (str):
             Path to a File acting as standard_in for the batch-script.
             This is the same as -i/--input from sbatch.
-        standard_in (str):
-            Path to a File acting as standard_in for the batch-script.
-            This is the same as -i/--input from sbatch.
+        standard_error (str):
+            Path to a File acting as standard_error for the batch-script.
+            This is the same as -e/--error from sbatch.
         standard_output (str):
             Path to a File to write the Jobs standard_output.
             This is the same as -o/--output from sbatch.

pyslurm/core/job/submission.pyx

@@ -73,6 +73,9 @@ cdef class JobSubmitDescription:
 
         slurm_init_job_desc_msg(self.ptr)
 
+    def __repr__(self):
+        return f'pyslurm.{self.__class__.__name__}'
+
     def submit(self):
         """Submit a batch job description.
 
@@ -87,9 +90,12 @@ cdef class JobSubmitDescription:
             >>> desc = pyslurm.JobSubmitDescription(
             ...     name="test-job",
             ...     cpus_per_task=1,
-            ...     time_limit="10-00:00:00")
+            ...     time_limit="10-00:00:00",
+            ...     script="/path/to/your/submit_script.sh")
             >>> 
             >>> job_id = desc.submit()
+            >>> print(job_id)
+            99
         """
         cdef submit_response_msg_t *resp = NULL
 
@@ -112,9 +118,9 @@ cdef class JobSubmitDescription:
 
         Args:
             overwrite (bool): 
-                If set to True, the value from an option found in the
+                If set to `True`, the value from an option found in the
                 environment will override the current value of the attribute
-                in this instance. Default is False
+                in this instance. Default is `False`
 
         Examples:
             Lets consider you want to set the name of the Job, its Account
@@ -141,13 +147,13 @@ cdef class JobSubmitDescription:
         self._parse_env(overwrite)
 
     def load_sbatch_options(self, overwrite=False):
-        """Load values from #SBATCH options in the batch script.
+        """Load values from `#SBATCH` options in the batch script.
 
         Args:
             overwrite (bool):
-                If set to True, the value from an option found in the in the
+                If set to `True`, the value from an option found in the in the
                 batch script will override the current value of the attribute
-                in this instance. Default is False
+                in this instance. Default is `False`
         """
         if not self.script:
             raise ValueError("You need to set the 'script' attribute first.")

pyslurm/core/node.pxd

@@ -62,7 +62,7 @@ cdef class Nodes(MultiClusterMap):
     """A [`Multi Cluster`][pyslurm.xcollections.MultiClusterMap] collection of [pyslurm.Node][] objects.
 
     Args:
-        nodes (Union[list, dict, str], optional=None):
+        nodes (Union[list[str], dict[str, Node], str], optional=None):
             Nodes to initialize this collection with.
 
     Attributes:
@@ -161,8 +161,7 @@ cdef class Node:
         free_memory (int):
             Free Memory in Mebibytes on the node.
         memory_reserved_for_system (int):
-            Raw Memory in Mebibytes reserved for the System not usable by
-            Jobs.
+            Memory in Mebibytes reserved for the System not usable by Jobs.
         temporary_disk (int):
             Amount of temporary disk space this node has, in Mebibytes.
         weight (int):
@@ -210,9 +209,10 @@ cdef class Node:
         external_sensors (dict):
             External Sensor info for the Node.
             The dict returned contains the following information:
-                * joules_total (int)
-                * current_watts (int)
-                * temperature (int)
+
+            * `joules_total` (int)
+            * `current_watts` (int)
+            * `temperature` (int)
         state (str):
             State the node is currently in.
         next_state (str):

pyslurm/core/node.pyx

@@ -121,13 +121,16 @@ cdef class Nodes(MultiClusterMap):
         return nodes
 
     def reload(self):
-        """Reload the information for nodes in a collection.
+        """Reload the information for Nodes in a collection.
 
         !!! note
 
             Only information for nodes which are already in the collection at
             the time of calling this method will be reloaded.
 
+        Returns:
+            (pyslurm.Nodes): Returns self
+
         Raises:
             RPCError: When getting the Nodes from the slurmctld failed.
         """
@@ -246,7 +249,7 @@ cdef class Node:
         Node.__dict__[name].__set__(self, val)
 
     def __repr__(self):
-        return f'{self.__class__.__name__}({self.name})'
+        return f'pyslurm.{self.__class__.__name__}({self.name})'
 
     @staticmethod
     cdef Node from_ptr(node_info_t *in_ptr):
@@ -271,6 +274,10 @@ cdef class Node:
 
         Implements the slurm_load_node_single RPC.
 
+        Args:
+            name (str):
+                The name of the Node to load.
+
         Returns:
             (pyslurm.Node): Returns a new Node instance.
 
@@ -285,7 +292,7 @@ cdef class Node:
         cdef:
             node_info_msg_t      *node_info = NULL
             partition_info_msg_t *part_info = NULL
-            Node wrap = Node.__new__(Node)
+            Node wrap = None
 
         try:
             verify_rpc(slurm_load_node_single(&node_info,
@@ -294,9 +301,7 @@ cdef class Node:
             slurm_populate_node_partitions(node_info, part_info)
 
             if node_info and node_info.record_count:
-                # Copy info
-                wrap._alloc_impl()
-                memcpy(wrap.info, &node_info.node_array[0], sizeof(node_info_t))
+                wrap = Node.from_ptr(&node_info.node_array[0])
                 node_info.record_count = 0
             else:
                 raise RPCError(msg=f"Node '{name}' does not exist")

pyslurm/core/partition.pyx

@@ -186,7 +186,7 @@ cdef class Partition:
         self._dealloc_impl() 
 
     def __repr__(self):
-        return f'{self.__class__.__name__}({self.name})'
+        return f'pyslurm.{self.__class__.__name__}({self.name})'
 
     @staticmethod
     cdef Partition from_ptr(partition_info_t *in_ptr):

pyslurm/db/assoc.pyx

@@ -206,7 +206,7 @@ cdef class Association:
             slurmdb_init_assoc_rec(self.ptr, 0)
 
     def __repr__(self):
-        return f'{self.__class__.__name__}({self.id})'
+        return f'pyslurm.db.{self.__class__.__name__}({self.id})'
 
     @staticmethod
     cdef Association from_ptr(slurmdb_assoc_rec_t *in_ptr):

pyslurm/db/connection.pyx

@@ -48,6 +48,10 @@ cdef class Connection:
     def __dealloc__(self):
         self.close()
 
+    def __repr__(self):
+        state = "open" if self.is_open else "closed"
+        return f'pyslurm.db.{self.__class__.__name__} is {state}'
+
     @staticmethod
     def open():
         """Open a new connection to the slurmdbd
@@ -61,6 +65,8 @@ cdef class Connection:
         Examples:
             >>> import pyslurm
             >>> connection = pyslurm.db.Connection.open()
+            >>> print(connection.is_open)
+            True
         """
         cdef Connection conn = Connection.__new__(Connection)
         conn.ptr = <void*>slurmdb_connection_get(&conn.flags)
@@ -77,6 +83,8 @@ cdef class Connection:
             >>> connection = pyslurm.db.Connection.open()
             >>> ...
             >>> connection.close()
+            >>> print(connection.is_open)
+            False
         """
         if self.is_open:
             slurmdb_connection_close(&self.ptr)

pyslurm/db/job.pxd

@@ -163,7 +163,8 @@ cdef class Job:
         job_id (int, optional=0):
             An Integer representing a Job-ID.
         cluster (str, optional=None):
-            Name of the Cluster for this Job.
+            Name of the Cluster for this Job. Default is the name of the local
+            Cluster.
 
     Other Parameters:
         admin_comment (str):