feat: Overhaul slurmutils API and add slurmdbd editor

Merge pull request #4 from canonical/add-slurmdbd

CONTRIBUTING.md

@@ -170,7 +170,7 @@ included in the project:
     with a clear title and description against the `main` branch.
 
 **IMPORTANT**: By submitting a patch, improvement, or new feature, you agree to allow the maintainers of slurmutils to 
-license your contributions under the terms of the [Apache 2.0 license](./LICENSE), and you agree to sign
+license your contributions under the terms of the [GNU Lesser General Public License, v3.0](./LICENSE), and you agree to sign
 [Canonical's contributor license agreement](https://ubuntu.com/legal/contributors)
 
 ## Discussions
@@ -196,5 +196,5 @@ The following guidelines must be adhered to if you are writing code to be merged
 ## License & CLA
 
 By contributing your code to slurmutils, you agree to license your contribution under the 
-[Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0.html), and you agree to
+[GNU Lesser General Public License, v3.0](./LICENSE), and you agree to
 sign [Canonical's contributor license agreement](https://ubuntu.com/legal/contributors).

README.md

@@ -1,64 +1,102 @@
-<h1 align="center">
-  slurmutils
-</h1>
+<div align="center">
 
-<p align="center">
-  Utilities and APIs for interacting with the SLURM workload manager.
-</p>
+# slurmutils
+
+Utilities and APIs for interfacing with the Slurm workload manager.
+
+[![Matrix](https://img.shields.io/matrix/ubuntu-hpc%3Amatrix.org?logo=matrix&label=ubuntu-hpc)](https://matrix.to/#/#ubuntu-hpc:matrix.org)
+
+</div>
 
 ## Features
 
-* `slurmconf`: An API for performing CRUD operations on the SLURM configuration file _slurm.conf_
+`slurmutils` is a collection of various utilities and APIs to make it easier 
+for you and your friends to interface with the Slurm workload manager, especially if you 
+are orchestrating deployments of new and current Slurm clusters. Gone are the days of
+seething over incomplete Jinja2 templates. Current utilities and APIs shipped in the 
+`slurmutils` package include:
+
+#### `from slurmutils.editors import ...`
+
+* `slurmconfig`:  An editor _slurm.conf_ and _Include_ files.
+* `slurmdbdconfig`: An editor for _slurmdbd.conf_ files.
 
 ## Installation
 
-#### Option 1: PyPI
+#### Option 1: Install from PyPI
 
 ```shell
 $ python3 -m pip install slurmutils
 ```
 
 #### Option 2: Install from source
 
+We use the [Poetry](https://python-poetry.org) packaging and dependency manager to
+manage this project. It must be installed on your system if installing `slurmutils`
+from source.
+
 ```shell
 $ git clone https://github.com/canonical/slurmutils.git
 $ cd slurmutils
-$ python3 -m pip install .
+$ poetry install
 ```
 
 ## Usage
 
-#### `slurmconf`
+### Editors
 
-This module provides an API for performing CRUD operations on the SLURM configuration file _slurm.conf_.
-With this module, you can:
+#### `slurmconfig`
 
-##### Edit a pre-existing configuration
+This module provides an API for editing both _slurm.conf_ and _Include_ files,
+and can create new configuration files if they do not exist. Here's some common Slurm
+lifecycle management operators you can perform using this editor:
+
+##### Edit a pre-existing _slurm.conf_ configuration file
 
 ```python
-from slurmutils.slurmconf import SlurmConf
+from slurmutils.editors import slurmconfig
 
-with SlurmConf("/etc/slurm/slurm.conf") as conf:
-    del conf.inactive_limit
-    conf.max_job_count = 20000
-    conf.proctrack_type = "proctrack/linuxproc"
+# Open, edit, and save the slurm.conf file located at _/etc/slurm/slurm.conf_.
+with slurmconfig.edit("/etc/slurm/slurm.conf") as config:
+    del config.inactive_limit
+    config.max_job_count = 20000
+    config.proctrack_type = "proctrack/linuxproc"
 ```
 
-##### Add new nodes
-
-```python3
-from slurmutils.slurmconf import Node, SlurmConf
-
-with SlurmConf("/etc/slurm/slurm.conf") as conf:
-    node_name = "test-node"
-    node_conf = {
-        "NodeName": node_name,
-        "NodeAddr": "12.34.56.78",
-        "CPUs": 1, 
-        "RealMemory": 1000, 
-        "TmpDisk": 10000,
-    }
-    conf.nodes.update({node_name: Node(**node_conf)})
+##### Add a new node to the _slurm.conf_ file
+
+```python
+from slurmutils.editors import slurmconfig
+from slurmutils.models import Node
+
+with slurmconfig.edit("/etc/slurm/slurm.conf") as config:
+    node = Node(
+        NodeName="batch-[0-25]", 
+        NodeAddr="12.34.56.78", 
+        CPUs=1, 
+        RealMemory=1000, 
+        TmpDisk=10000,
+    )
+    config.nodes[node.node_name] = node
+```
+
+#### `slurmdbdconfig`
+
+This module provides and API for editing _slurmdbd.conf_ files, and can create new
+_slurmdbd.conf_ files if they do not exist. Here's some operations you can perform
+on the _slurmdbd.conf_ file using this editor:
+
+##### Edit a pre-existing _slurmdbd.conf_ configuration file
+
+```python
+from slurmutils.editors import slurmdbdconfig
+
+with slurmdbdconfig.edit("/etc/slurm/slurmdbd.conf") as config:
+    config.archive_usage = "yes"
+    config.log_file = "/var/spool/slurmdbd.log"
+    config.debug_flags = ["DB_EVENT", "DB_JOB", "DB_USAGE"]
+    del config.auth_alt_types
+    del config.auth_alt_parameters
 ```
 
 ## Project & Community
@@ -75,5 +113,5 @@ Check out these links below:
 
 ## License
 
-The `slurmutils` package is free software, distributed under the Apache Software License, version 2.0.
+The `slurmutils` package is free software, distributed under the GNU Lesser General Public License, v3.0.
 See the [LICENSE](./LICENSE) file for more information.

pyproject.toml

@@ -1,16 +1,47 @@
-# Copyright 2023 Canonical Ltd.
+# Copyright 2024 Canonical Ltd.
 #
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License version 3 as published by the Free Software Foundation.
 #
-#     http://www.apache.org/licenses/LICENSE-2.0
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
 #
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
+# You should have received a copy of the GNU Lesser General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "slurmutils"
+version = "0.2.0"
+description = "Utilities and APIs for interfacing with the Slurm workload manager."
+repository = "https://github.com/canonical/slurmutils"
+authors = ["Jason C. Nucciarone <[email protected]>"]
+maintainers = ["Jason C. Nucciarone <[email protected]>"]
+license = "LGPL-3.0-only"
+readme = "README.md"
+keywords = ["HPC", "administration", "orchestration", "utility"]
+classifiers=[
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+]
+
+[tool.poetry.dependencies]
+python = ">=3.8"
+
+[tool.poetry.urls]
+"Bug Tracker" = "https://github.com/canonical/slurmutils/issues"
 
 # Testing tools configuration
 [tool.coverage.run]
@@ -27,7 +58,6 @@ log_cli_level = "INFO"
 [tool.codespell]
 skip = "build,lib,venv,icon.svg,.tox,.git,.mypy_cache,.ruff_cache,.vscode,.coverage"
 
-
 # Formatting tools configuration
 [tool.black]
 line-length = 99
@@ -50,7 +80,7 @@ extend-ignore = [
     "D409",
     "D413",
 ]
-ignore = ["E501", "D107"]
+ignore = ["E501", "D105", "D107"]
 extend-exclude = ["__pycache__", "*.egg_info", "__init__.py"]
 per-file-ignores = {"tests/*" = ["D100","D101","D102","D103","D104"]}
 

slurmutils/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2024 Canonical Ltd.
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License version 3 as published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Utilities and APIs for interfacing with the Slurm workload manager."""

slurmutils/editors/__init__.py

@@ -0,0 +1,18 @@
+# Copyright 2024 Canonical Ltd.
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License version 3 as published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Editors for Slurm workload manager configuration files."""
+
+from . import slurmconfig
+from . import slurmdbdconfig