libres 0.9.1__tar.gz → 0.10.0__tar.gz

{libres-0.9.1 → libres-0.10.0}/HISTORY.rst

@@ -1,6 +1,33 @@
 Changelog
 ---------
 
+0.10.0 (15.01.2026)
+~~~~~~~~~~~~~~~~~~~
+
+- Adds new entity `ReservationBlocker` for administrative blockers
+  of targeted allocations for the targeted timespans, this also ends
+  up adding a new column `source_type` to `ReservedSlot` which can be
+  added using the following recipe using an alembic `Operations` object::
+
+    operations.add_column(
+      'reserved_slots',
+      Column(
+        'source_type',
+        Enum(
+            'reservation', 'blocker',
+            name='reserved_slot_source_type'
+        ),
+        nullable=False,
+        server_default='reservation'
+      )
+    )
+    operations.alter_column(
+      'reserved_slots',
+      'source_type',
+      server_default=None
+    )
+
+
 0.9.1 (05.08.2025)
 ~~~~~~~~~~~~~~~~~~~
 

{libres-0.9.1/src/libres.egg-info → libres-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: libres
-Version: 0.9.1
+Version: 0.10.0
 Summary: A library to reserve things
 Home-page: http://github.com/seantis/libres/
 Author: Denis Krienbühl
@@ -142,6 +142,33 @@ After this, create a new release on Github.
 Changelog
 ---------
 
+0.10.0 (15.01.2026)
+~~~~~~~~~~~~~~~~~~~
+
+- Adds new entity `ReservationBlocker` for administrative blockers
+  of targeted allocations for the targeted timespans, this also ends
+  up adding a new column `source_type` to `ReservedSlot` which can be
+  added using the following recipe using an alembic `Operations` object::
+
+    operations.add_column(
+      'reserved_slots',
+      Column(
+        'source_type',
+        Enum(
+            'reservation', 'blocker',
+            name='reserved_slot_source_type'
+        ),
+        nullable=False,
+        server_default='reservation'
+      )
+    )
+    operations.alter_column(
+      'reserved_slots',
+      'source_type',
+      server_default=None
+    )
+
+
 0.9.1 (05.08.2025)
 ~~~~~~~~~~~~~~~~~~~
 

{libres-0.9.1 → libres-0.10.0}/pyproject.toml

@@ -11,7 +11,7 @@ branch = true
 source = ["src"]
 
 [tool.bumpversion]
-current_version = "0.9.1"
+current_version = "0.10.0"
 commit = true
 message = "Release {new_version}"
 tag = true
@@ -157,7 +157,6 @@ ignore = [
     "UP009",
     "UP012",
     "UP032",
-    "UP038",
 ]
 unfixable = []
 external = ["TC"]

{libres-0.9.1 → libres-0.10.0}/src/libres/__init__.py

@@ -3,9 +3,9 @@ from __future__ import annotations
 from libres.context.registry import create_default_registry
 from libres.db import new_scheduler
 
-registry = create_default_registry()
+registry = create_default_registry()  # noqa: RUF067
 
-__version__ = '0.9.1'
+__version__ = '0.10.0'
 __all__ = (
     'new_scheduler',
     'registry'

{libres-0.9.1 → libres-0.10.0}/src/libres/db/models/__init__.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from libres.db.models.base import ORMBase
 from libres.db.models.allocation import Allocation
+from libres.db.models.blocker import ReservationBlocker
 from libres.db.models.reserved_slot import ReservedSlot
 from libres.db.models.reservation import Reservation
 
@@ -10,5 +11,6 @@ __all__ = (
     'ORMBase',
     'Allocation',
     'ReservedSlot',
-    'Reservation'
+    'Reservation',
+    'ReservationBlocker',
 )

{libres-0.9.1 → libres-0.10.0}/src/libres/db/models/allocation.py

@@ -10,9 +10,10 @@ from sqlalchemy.schema import Column
 from sqlalchemy.schema import Index
 from sqlalchemy.schema import UniqueConstraint
 from sqlalchemy.orm import object_session
+from sqlalchemy.orm import relationship
 from sqlalchemy.orm.util import has_identity
 
-from libres.db.models import ORMBase
+from libres.db.models.base import ORMBase
 from libres.db.models.types import UUID, UTCDateTime, JSON
 from libres.db.models.other import OtherModels
 from libres.db.models.timestamp import TimestampMixin
@@ -136,9 +137,15 @@ class Allocation(TimestampMixin, ORMBase, OtherModels):
         nullable=False
     )
 
-    if TYPE_CHECKING:
-        # forward declare backref
-        reserved_slots: list[ReservedSlot]
+    # Reserved_slots are eagerly joined since we usually want both
+    # allocation and reserved_slots. There's barely a function which does
+    # not need to know about reserved slots when working with allocations.
+    reserved_slots: relationship[list[ReservedSlot]] = relationship(
+        'ReservedSlot',
+        lazy='joined',
+        cascade='all, delete-orphan',
+        back_populates='allocation'
+    )
 
     __table_args__ = (
         Index('mirror_resource_ix', 'mirror_of', 'resource'),
@@ -502,15 +509,32 @@ class Allocation(TimestampMixin, ORMBase, OtherModels):
         """Returns the availability in percent."""
 
         total = self.count_slots()
-        used = len(self.reserved_slots)
+        blocked = sum(
+            1
+            for s in self.reserved_slots
+            if s.source_type == 'blocker'
+        )
+        reserved = sum(
+            1
+            for s in self.reserved_slots
+            if s.source_type == 'reservation'
+        )
 
-        if total == used:
+        if total == blocked:
+            # if everything is blocked this allocation is unavailable
             return 0.0
 
-        if used == 0:
+        # blockers detract from the total slots
+        # they're not part of the availability
+        total -= blocked
+
+        if total == reserved:
+            return 0.0
+
+        if reserved == 0:
             return 100.0
 
-        return 100.0 - (float(used) / float(total) * 100.0)
+        return 100.0 - 100.0 * (reserved / total)
 
     @property
     def normalized_availability(self) -> float:
@@ -542,27 +566,53 @@ class Allocation(TimestampMixin, ORMBase, OtherModels):
         # the normalized total slots correspond to the naive delta
         total = naive_delta.total_seconds() // (self.raster * 60)
         if real_delta > naive_delta:
-            # this is the most complicated case since we need to
-            # reduce the set of reserved slots by the hour we skipped
+            # this is the most complicated case since we need to reduce the
+            # set of reserved slots by the hour we removed from the total
             ambiguous_start = start.replace(
                 hour=2, minute=0, second=0, microsecond=0)
             ambiguous_end = ambiguous_start.replace(hour=3)
-            used = sum(
-                1 for r in self.reserved_slots
+            blocked = sum(
+                1
+                for r in self.reserved_slots
+                if r.source_type == 'blocker'
+                if not ambiguous_start <= r.start < ambiguous_end
+            )
+            reserved = sum(
+                1
+                for r in self.reserved_slots
+                if r.source_type == 'reservation'
                 if not ambiguous_start <= r.start < ambiguous_end
             )
         else:
-            used = len(self.reserved_slots)
-            # add one hour's worth of reserved slots
-            used += 60 // self.raster
+            blocked = sum(
+                1
+                for s in self.reserved_slots
+                if s.source_type == 'blocker'
+            )
+            reserved = sum(
+                1
+                for s in self.reserved_slots
+                if s.source_type == 'reservation'
+            )
+            # add one hour's worth of slots to compensate for the extra
+            # hour we added to the total.
+            reserved += 60 // self.raster
 
-        if used == 0:
-            return 100.0
+        if total == blocked:
+            # if everything is blocked this allocation is unavailable
+            return 0.0
+
+        # blockers detract from the total slots
+        # they're not part of the availability
+        total -= blocked
 
-        if total == used:
+        if total == reserved:
             return 0.0
 
-        return 100.0 - (float(used) / float(total) * 100.0)
+        if reserved == 0:
+            return 100.0
+
+        return 100.0 - 100.0 * (reserved / total)
 
     @property
     def in_group(self) -> int:

libres-0.10.0/src/libres/db/models/blocker.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+import sedate
+
+from datetime import datetime, timedelta
+
+from sqlalchemy import types
+from sqlalchemy.orm import object_session
+from sqlalchemy.schema import Column
+from sqlalchemy.schema import Index
+
+from libres.db.models.base import ORMBase
+from libres.db.models.types import UUID, UTCDateTime
+from libres.db.models.other import OtherModels
+from libres.db.models.timespan import Timespan
+from libres.db.models.timestamp import TimestampMixin
+
+
+from typing import Literal
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    import uuid
+    from sedate.types import TzInfoOrName
+    from sqlalchemy.orm import Query
+
+    from libres.db.models import Allocation
+
+
+class ReservationBlocker(TimestampMixin, ORMBase, OtherModels):
+    """Describes a reservation blocker.
+
+    Blockers can be used to signify that an allocation will be blocked for
+    the specified time span, in order to e.g. perform cleaning duties on
+    the relevant resource.
+
+    """
+
+    __tablename__ = 'reservation_blockers'
+
+    id: Column[int] = Column(
+        types.Integer(),
+        primary_key=True,
+        autoincrement=True
+    )
+
+    token: Column[uuid.UUID] = Column(
+        UUID(),
+        nullable=False,
+    )
+
+    target: Column[uuid.UUID] = Column(
+        UUID(),
+        nullable=False,
+    )
+
+    target_type: Column[Literal['group', 'allocation']] = Column(
+        types.Enum(  # type:ignore[arg-type]
+            'group', 'allocation',
+            name='reservation_blocker_target_type'
+        ),
+        nullable=False
+    )
+
+    resource: Column[uuid.UUID] = Column(
+        UUID(),
+        nullable=False
+    )
+
+    start: Column[datetime | None] = Column(
+        UTCDateTime(timezone=False),
+        nullable=True
+    )
+
+    end: Column[datetime | None] = Column(
+        UTCDateTime(timezone=False),
+        nullable=True
+    )
+
+    timezone: Column[str | None] = Column(
+        types.String(),
+        nullable=True
+    )
+
+    reason: Column[str | None] = Column(
+        types.String(),
+        nullable=True
+    )
+
+    __table_args__ = (
+        Index('blocker_target_ix', 'target', 'id'),
+    )
+
+    def target_allocations(
+        self,
+        masters_only: bool = True
+    ) -> Query[Allocation]:
+        """ Returns the allocations this blocker is targeting.
+
+        """
+        Allocation = self.models.Allocation  # noqa: N806
+        query = object_session(self).query(Allocation)
+        query = query.filter(Allocation.group == self.target)
+
+        if masters_only:
+            query = query.filter(Allocation.resource == Allocation.mirror_of)
+
+        # order by date
+        query = query.order_by(Allocation._start)
+
+        return query  # type: ignore[no-any-return]
+
+    def display_start(
+        self,
+        timezone: TzInfoOrName | None = None
+    ) -> datetime:
+        """Does nothing but to form a nice pair to display_end."""
+        assert self.start is not None
+        if timezone is None:
+            assert self.timezone is not None
+            timezone = self.timezone
+        return sedate.to_timezone(self.start, timezone)
+
+    def display_end(
+        self,
+        timezone: TzInfoOrName | None = None
+    ) -> datetime:
+        """Returns the end plus one microsecond (nicer display)."""
+        assert self.end is not None
+        if timezone is None:
+            assert self.timezone is not None
+            timezone = self.timezone
+
+        end = self.end + timedelta(microseconds=1)
+        return sedate.to_timezone(end, timezone)
+
+    def timespans(self) -> list[Timespan]:
+        """ Returns the timespans targeted by this blocker.
+
+        The result is a list of :class:`~libres.db.models.timespan.Timespan`
+        timespans. The start and end are the start and end dates of the
+        referenced allocations.
+
+        The timespans are ordered by start.
+
+        """
+
+        if self.target_type == 'allocation':
+            # we don't need to hit the database in this case
+            assert self.start is not None
+            assert self.end is not None
+            return [
+                Timespan(self.start, self.end + timedelta(microseconds=1))
+            ]
+        elif self.target_type == 'group':
+            return [
+                Timespan(allocation.start, allocation.end)
+                for allocation in self.target_allocations()
+            ]
+        else:
+            raise NotImplementedError
+
+    @property
+    def title(self) -> str | None:
+        return self.reason

{libres-0.9.1 → libres-0.10.0}/src/libres/db/models/other.py

@@ -11,6 +11,7 @@ if TYPE_CHECKING:
         Allocation: type[_models.Allocation]
         ReservedSlot: type[_models.ReservedSlot]
         Reservation: type[_models.Reservation]
+        ReservationBlocker: type[_models.ReservationBlocker]
 
 
 models = None
@@ -25,7 +26,7 @@ class OtherModels:
         global models
         if not models:
             # FIXME: libres.db exports ORMBase, do we really
-            #        want to makes this accesible?
+            #        want to makes this accessible?
             from libres.db import models as m_
             models = m_
 

{libres-0.9.1 → libres-0.10.0}/src/libres/db/models/reservation.py

@@ -9,15 +9,15 @@ from sqlalchemy.orm import object_session, deferred
 from sqlalchemy.schema import Column
 from sqlalchemy.schema import Index
 
-from libres.db.models import ORMBase
+from libres.db.models.base import ORMBase
 from libres.db.models.types import UUID, UTCDateTime, JSON
 from libres.db.models.other import OtherModels
+from libres.db.models.timespan import Timespan
 from libres.db.models.timestamp import TimestampMixin
 
 
 from typing import Any
 from typing import Literal
-from typing import NamedTuple
 from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     import uuid
@@ -27,11 +27,6 @@ if TYPE_CHECKING:
     from libres.db.models import Allocation
 
 
-class Timespan(NamedTuple):
-    start: datetime
-    end: datetime
-
-
 class Reservation(TimestampMixin, ORMBase, OtherModels):
     """Describes a pending or approved reservation.
 

{libres-0.9.1 → libres-0.10.0}/src/libres/db/models/reserved_slot.py

@@ -8,18 +8,19 @@ from sqlalchemy.schema import Column
 from sqlalchemy.schema import Index
 from sqlalchemy.schema import ForeignKey
 from sqlalchemy.orm import relationship
-from sqlalchemy.orm import backref
 
 from libres.modules.rasterizer import (
     rasterize_start,
     rasterize_end,
 )
 
-from libres.db.models import ORMBase, Allocation
+from libres.db.models.allocation import Allocation
+from libres.db.models.base import ORMBase
 from libres.db.models.types import UUID, UTCDateTime
 from libres.db.models.timestamp import TimestampMixin
 
 
+from typing import Literal
 from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     import uuid
@@ -52,22 +53,25 @@ class ReservedSlot(TimestampMixin, ORMBase):
 
     allocation_id: Column[int] = Column(
         types.Integer(),
-        ForeignKey(Allocation.id),
+        ForeignKey('allocations.id'),
         nullable=False
     )
 
+    # Reserved_slots are eagerly joined since we usually want both
+    # allocation and reserved_slots. There's barely a function which does
+    # not need to know about reserved slots when working with allocations.
     allocation: relationship[Allocation] = relationship(
         Allocation,
         primaryjoin=Allocation.id == allocation_id,
+        back_populates='reserved_slots',
+    )
 
-        # Reserved_slots are eagerly joined since we usually want both
-        # allocation and reserved_slots. There's barely a function which does
-        # not need to know about reserved slots when working with allocation.
-        backref=backref(
-            'reserved_slots',
-            lazy='joined',
-            cascade='all, delete-orphan'
-        )
+    source_type: Column[Literal['reservation', 'blocker']] = Column(
+        types.Enum(  # type:ignore[arg-type]
+            'reservation', 'blocker',
+            name='reserved_slot_source_type'
+        ),
+        nullable=False
     )
 
     reservation_token: Column[uuid.UUID] = Column(

libres-0.10.0/src/libres/db/models/timespan.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+
+from typing import NamedTuple
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from datetime import datetime
+
+
+class Timespan(NamedTuple):
+    start: datetime
+    end: datetime

{libres-0.9.1 → libres-0.10.0}/src/libres/db/queries.py

@@ -253,7 +253,7 @@ class Queries(ContextServicesMixin):
 
         slots = self.session.query(ReservedSlot).filter(
             ReservedSlot.reservation_token == token
-        )
+        ).filter(ReservedSlot.source_type == 'reservation')
 
         slots.delete('fetch')
 
@@ -340,6 +340,7 @@ class Queries(ContextServicesMixin):
                     reservations.with_entities(Reservation.token)
                 )
             )
+            slots = slots.filter(ReservedSlot.source_type == 'reservation')
 
             slots.delete('fetch')
             reservations.delete('fetch')