Skip to content

Commit 8246fb2

Browse files
tazendtazend
authored
Rework Reservation API (PySlurm#373)
* feat: rework reservations * add tests for reservations * fix docs * add custom enums for slurm * add u8_[set|parse]_bool_flag functions * add hack to improve generate docs for enum members
1 parent e4684e0 commit 8246fb2

File tree

10 files changed

+1036
-6
lines changed

10 files changed

+1036
-6
lines changed

‎docs/reference/reservation.md

+4-5
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,7 @@
22
title: Reservation
33
---
44

5-
!!! warning
6-
This API is currently being completely reworked, and is subject to be
7-
removed in the future when a replacement is introduced
8-
9-
::: pyslurm.deprecated.reservation
5+
::: pyslurm.Reservation
6+
::: pyslurm.Reservations
7+
::: pyslurm.ReservationFlags
8+
::: pyslurm.ReservationReoccurrence

‎pyslurm/__init__.py

+6
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,12 @@
2222
)
2323
from pyslurm.core.node import Node, Nodes
2424
from pyslurm.core.partition import Partition, Partitions
25+
from pyslurm.core.reservation import (
26+
Reservation,
27+
Reservations,
28+
ReservationFlags,
29+
ReservationReoccurrence,
30+
)
2531
from pyslurm.core import error
2632
from pyslurm.core.error import (
2733
PyslurmError,

‎pyslurm/core/reservation.pxd

+166
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
#########################################################################
2+
# reservation.pxd - interface to work with reservations in slurm
3+
#########################################################################
4+
# Copyright (C) 2025 Toni Harzendorf <[email protected]>
5+
#
6+
# This file is part of PySlurm
7+
#
8+
# PySlurm is free software; you can redistribute it and/or modify
9+
# it under the terms of the GNU General Public License as published by
10+
# the Free Software Foundation; either version 2 of the License, or
11+
# (at your option) any later version.
12+
13+
# PySlurm is distributed in the hope that it will be useful,
14+
# but WITHOUT ANY WARRANTY; without even the implied warranty of
15+
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16+
# GNU General Public License for more details.
17+
#
18+
# You should have received a copy of the GNU General Public License along
19+
# with PySlurm; if not, write to the Free Software Foundation, Inc.,
20+
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
21+
#
22+
# cython: c_string_type=unicode, c_string_encoding=default
23+
# cython: language_level=3
24+
25+
from libc.string cimport memcpy, memset
26+
from libc.stdint cimport uint8_t, uint16_t, uint32_t, uint64_t
27+
from libc.stdlib cimport free
28+
from pyslurm cimport slurm
29+
from pyslurm.slurm cimport (
30+
reserve_info_t,
31+
reserve_info_msg_t,
32+
resv_desc_msg_t,
33+
reservation_name_msg_t,
34+
reserve_response_msg_t,
35+
slurm_free_reservation_info_msg,
36+
slurm_load_reservations,
37+
slurm_delete_reservation,
38+
slurm_update_reservation,
39+
slurm_create_reservation,
40+
slurm_init_resv_desc_msg,
41+
xfree,
42+
try_xmalloc,
43+
)
44+
45+
from pyslurm.utils cimport cstr
46+
from pyslurm.utils cimport ctime
47+
from pyslurm.utils.ctime cimport time_t
48+
from pyslurm.utils.uint cimport (
49+
u32,
50+
u32_parse,
51+
u64_parse_bool_flag,
52+
u64_set_bool_flag,
53+
)
54+
from pyslurm.xcollections cimport MultiClusterMap
55+
56+
cdef extern void slurm_free_resv_desc_msg(resv_desc_msg_t *msg)
57+
cdef extern void slurm_free_reserve_info_members(reserve_info_t *resv)
58+
59+
60+
cdef class Reservations(MultiClusterMap):
61+
"""A [`Multi Cluster`][pyslurm.xcollections.MultiClusterMap] collection of [pyslurm.Reservation][] objects.
62+
63+
Args:
64+
reservations (Union[list[str], dict[str, pyslurm.Reservation], str], optional=None):
65+
Reservations to initialize this collection with.
66+
"""
67+
cdef:
68+
reserve_info_msg_t *info
69+
reserve_info_t tmp_info
70+
71+
72+
cdef class Reservation:
73+
"""A Slurm Reservation.
74+
75+
Args:
76+
name (str, optional=None):
77+
Name for a Reservation.
78+
**kwargs (Any, optional=None):
79+
All Attributes of a Reservation are eligible to be set, except
80+
`cpu_ids_by_node`. Although the `name` attribute can also be
81+
changed on the instance, the change will not be taken into account
82+
by `slurmctld` when calling `modify()`.
83+
84+
Attributes:
85+
accounts (list[str]):
86+
List of account names that have access to the Reservation.
87+
burst_buffer (str):
88+
Burst Buffer specification.
89+
comment (str):
90+
Arbitrary comment for the Reservation.
91+
cpus (int):
92+
Amount of CPUs used by the Reservation
93+
cpu_ids_by_node (dict[str, int]):
94+
A Mapping where each key is the node-name, and the values are a
95+
string of CPU-IDs reserved on the specific nodes.
96+
end_time (int):
97+
Unix Timestamp when the Reservation ends.
98+
features (list[str]):
99+
List of features required by the Reservation.
100+
groups (list[str]):
101+
List of Groups that can access the Reservation.
102+
licenses (list[str]):
103+
List of licenses to be reserved.
104+
max_start_delay (int):
105+
Maximum delay, in seconds, where Jobs are permitted to overlap with
106+
the Reservation once Jobs are queued for it.
107+
name (str):
108+
Name of the Reservation.
109+
node_count (int):
110+
Count of Nodes required.
111+
nodes (str):
112+
Nodes to be reserved.
113+
When creating or updating a Reservation, you can also pass the
114+
string `ALL`, when you want all nodes to be included in the
115+
Reservation.
116+
partition (str):
117+
Name of the partition to be used.
118+
purge_time (int):
119+
When the Reservation is idle for this amount of seconds, it will be
120+
removed.
121+
start_time (int):
122+
When the Reservation starts. This is a Unix timestamp.
123+
duration (int):
124+
How long, in minutes, the reservation runs for. Unless a
125+
`start_time` has already been specified, setting this will set the
126+
`start_time` the current time, meaning the Reservation will start
127+
immediately.
128+
129+
For setting this attribute, instead of minutes you can also specify
130+
a time-string like this:
131+
132+
duration = "1-00:00:00"
133+
134+
The above means that the Reservation will last for 1 day.
135+
is_active (bool):
136+
Whether the reservation is currently active or not.
137+
tres (dict[str, int]):
138+
TRES for the Reservation.
139+
users (list[str]):
140+
List of user names permitted to use the Reservation.
141+
flags (pyslurm.ReservationFlags):
142+
Optional Flags for the Reservation.
143+
For convenience, instead of using [pyslurm.ReservationFlags][] in
144+
combination with the logical Operators, you can set this attribute
145+
via a [list][] of [str][]:
146+
147+
flags = ["MAINTENANCE", "FLEX", "MAGNETIC"]
148+
149+
When setting like this, the strings must match the names of members
150+
in [pyslurm.ReservationFlags][].
151+
reoccurrence (pyslurm.ReservationReoccurrence):
152+
Describes if and when this Reservation reoccurs.
153+
Since [pyslurm.ReservationReoccurrence] members are also just
154+
strings, you can conveniently also set the attribute like this:
155+
156+
reoccurrence = "DAILY"
157+
"""
158+
cdef:
159+
reserve_info_t *info
160+
resv_desc_msg_t *umsg
161+
_reoccurrence
162+
163+
cdef readonly cluster
164+
165+
@staticmethod
166+
cdef Reservation from_ptr(reserve_info_t *in_ptr)

0 commit comments

Comments
 (0)