libres 0.9.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

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.0'
+__version__ = '0.10.0'
 __all__ = (
     'new_scheduler',
     'registry'

libres/context/registry.py

@@ -82,6 +82,8 @@ class Registry:
     """
 
     contexts: dict[str, Context]
+    # FIXME: Why do we allow this to be None? Do we make use
+    #        of this anywhere?
     master_context: Context | None = None
 
     def __init__(self) -> None:

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/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/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/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/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/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/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/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')

libres/db/scheduler.py

@@ -10,7 +10,11 @@ from sqlalchemy.sql import and_, not_
 from uuid import uuid4 as new_uuid, UUID
 
 from libres.context.core import ContextServicesMixin
-from libres.db.models import ORMBase, Allocation, ReservedSlot, Reservation
+from libres.db.models import ORMBase
+from libres.db.models import Allocation
+from libres.db.models import ReservedSlot
+from libres.db.models import Reservation
+from libres.db.models import ReservationBlocker
 from libres.db.queries import Queries
 from libres.modules import errors
 from libres.modules import events
@@ -195,6 +199,13 @@ class Scheduler(ContextServicesMixin):
 
         return query
 
+    def managed_blockers(self) -> Query[ReservationBlocker]:
+        """ The blockers managed by this scheduler / resource. """
+        query = self.session.query(ReservationBlocker)
+        query = query.filter(ReservationBlocker.resource == self.resource)
+
+        return query
+
     def extinguish_managed_records(self) -> None:
         """ WARNING:
         Completely removes any trace of the records managed by this scheduler.
@@ -202,6 +213,7 @@ class Scheduler(ContextServicesMixin):
 
         """
         self.managed_reservations().delete('fetch')
+        self.managed_blockers().delete('fetch')
         self.managed_reserved_slots().delete('fetch')
         self.managed_allocations().delete('fetch')
 
@@ -265,17 +277,43 @@ class Scheduler(ContextServicesMixin):
         if id is not None:
             groups = groups.filter(Reservation.id == id)
 
-        allocations = self.managed_allocations()
-        allocations = allocations.with_entities(Allocation.id)
-        allocations = allocations.filter(Allocation.group.in_(groups))
+        query: Query[Allocation] = self.managed_allocations()
+        query = query.join(ReservedSlot)
+        query = query.filter(Allocation.group.in_(groups))
+        query = query.filter(
+            ReservedSlot.reservation_token == token
+        )
+        query = query.filter(
+            ReservedSlot.source_type == 'reservation'
+        )
+        return query
 
-        query = self.managed_allocations()
+    def allocations_by_blocker(
+        self,
+        token: UUID,
+        id: int | None = None
+    ) -> Query[Allocation]:
+        """ Returns the allocations for the blocker.
+
+        If you already have a blocker you can instead use target_allocations.
+
+        """
+
+        groups = self.managed_blockers()
+        groups = groups.with_entities(ReservationBlocker.target)
+        groups = groups.filter(ReservationBlocker.token == token)
+
+        if id is not None:
+            groups = groups.filter(ReservationBlocker.id == id)
+
+        query: Query[Allocation] = self.managed_allocations()
         query = query.join(ReservedSlot)
+        query = query.filter(Allocation.group.in_(groups))
         query = query.filter(
             ReservedSlot.reservation_token == token
         )
         query = query.filter(
-            ReservedSlot.allocation_id.in_(allocations)
+            ReservedSlot.source_type == 'blocker'
         )
         return query
 
@@ -957,6 +995,10 @@ class Scheduler(ContextServicesMixin):
         reservations = self.managed_reservations()
         reservations = reservations.with_entities(Reservation.target)
 
+        # all the blockers
+        blockers = self.managed_blockers()
+        blockers = blockers.with_entities(ReservationBlocker.target)
+
         # all the groups which are fully inside the required scope
         groups = self.managed_allocations().with_entities(Allocation.group)
         groups = groups.group_by(Allocation.group)
@@ -994,6 +1036,11 @@ class Scheduler(ContextServicesMixin):
             not_(Allocation.group.in_(reservations))
         )
 
+        # .. without the ones with blockers
+        candidates = candidates.filter(
+            not_(Allocation.group.in_(blockers))
+        )
+
         # .. including only the groups fully inside the required scope
         allocations = candidates.filter(Allocation.group.in_(groups))
 
@@ -1324,6 +1371,7 @@ class Scheduler(ContextServicesMixin):
                     slot.end = slot_end
                     slot.resource = allocation.resource
                     slot.reservation_token = reservation.token
+                    slot.source_type = 'reservation'
 
                     # the slots are written with the allocation
                     allocation.reserved_slots.append(slot)
@@ -1416,7 +1464,7 @@ class Scheduler(ContextServicesMixin):
 
     def change_email(self, token: UUID, new_email: str) -> None:
 
-        for reservation in self.reservations_by_token(token).all():
+        for reservation in self.reservations_by_token(token):
             reservation.email = new_email
 
     def change_reservation_data(
@@ -1425,7 +1473,7 @@ class Scheduler(ContextServicesMixin):
         data: Any | None
     ) -> None:
 
-        for reservation in self.reservations_by_token(token).all():
+        for reservation in self.reservations_by_token(token):
             reservation.data = data
 
     def change_reservation_time_candidates(
@@ -1511,7 +1559,7 @@ class Scheduler(ContextServicesMixin):
                 if existing_reservation.end in ends:
                     return None
 
-        # will return raise a MultipleResultsFound exception if this is a group
+        # will raise a MultipleResultsFound exception if this is a group
         if existing_reservation.status == 'approved':
             allocation = self.allocations_by_reservation(token, id).one()
         else:
@@ -1556,6 +1604,298 @@ class Scheduler(ContextServicesMixin):
 
         return new_reservation
 
+    @overload
+    def add_blocker(
+        self,
+        dates: _dtrange | Collection[_dtrange],
+        group: None = ...,
+        reason: str | None = ...,
+        token: UUID | None = ...
+    ) -> list[ReservationBlocker]: ...
+
+    @overload
+    def add_blocker(
+        self,
+        dates: None,
+        group: UUID,
+        reason: str | None = ...,
+        token: UUID | None = ...
+    ) -> list[ReservationBlocker]: ...
+
+    @overload
+    def add_blocker(
+        self,
+        dates: None = ...,
+        *,
+        group: UUID,
+        reason: str | None = ...,
+        token: UUID | None = ...
+    ) -> list[ReservationBlocker]: ...
+
+    def add_blocker(
+        self,
+        dates: _dtrange | Collection[_dtrange] | None = None,
+        group: UUID | None = None,
+        reason: str | None = None,
+        token: UUID | None = None
+    ) -> list[ReservationBlocker]:
+        """ Adds a blocker to one or many allocations.
+
+        Returns a list of `ReservationBlocker`, compared to reservations
+        blockers are added in a single step and don't require approval.
+
+        Blockers are intended for administrative purposes, where adding
+        a reservation would be too cumbersome by comparison.
+
+        :dates:
+            The dates to reserve. May either be a tuple of start/end datetimes
+            or a list of such tuples.
+
+        :group:
+            The allocation group to reserve. ``dates``and ``group`` are
+            mutually exclusive.
+
+        :reason:
+            The reason for blocking the targeted ranges.
+
+        """
+
+        assert (dates or group) and not (dates and group)
+
+        if group:
+            dates = self.allocation_dates_by_group(group)
+
+        assert dates is not None
+        dates = self._prepare_dates(dates)
+        timezone = self.timezone
+
+        # First, the request is checked for saneness. If any requested
+        # date cannot be reserved the request as a whole fails.
+        for start, end in dates:
+
+            # are the parameters valid?
+            if not utils.is_valid_reservation_length(start, end, timezone):
+                raise errors.ReservationTooLong
+
+            if start > end or (end - start).seconds < 5 * 60:
+                raise errors.ReservationTooShort
+
+            # can all allocations be reserved?
+            for allocation in self.allocations_in_range(start, end):
+
+                # start and end are not rasterized, so we need this check
+                if not allocation.overlaps(start, end):
+                    continue
+
+                assert allocation.is_master
+
+                if not allocation.find_spot(start, end):
+                    raise errors.AlreadyReservedError
+
+                free = self.free_allocations_count(allocation, start, end)
+                if free < allocation.quota:
+                    raise errors.AlreadyReservedError
+
+                if not allocation.contains(start, end):
+                    raise errors.TimerangeTooLong()
+
+        # ok, we're good to go
+        if token is None:
+            token = new_uuid()
+        reserved_slots = []
+
+        def create_reserved_slots(
+            allocation: Allocation,
+            start: datetime,
+            end: datetime,
+            including_mirrors: bool = True
+        ) -> None:
+            for slot_start, slot_end in allocation.all_slots(start, end):
+                slot = ReservedSlot()
+                slot.start = slot_start
+                slot.end = slot_end
+                slot.resource = allocation.resource
+                slot.reservation_token = token
+                slot.source_type = 'blocker'
+
+                # the slots are written with the allocation
+                allocation.reserved_slots.append(slot)
+                reserved_slots.append(slot)
+
+            # the allocation may be fake, make it real
+            if allocation.is_transient:
+                self.session.add(allocation)
+
+            if not including_mirrors or allocation.quota == 1:
+                return
+
+            for mirror in self.allocation_mirrors_by_master(allocation):
+                create_reserved_slots(
+                    mirror, start, end,
+                    including_mirrors=False
+                )
+
+        # groups are reserved by group-identifier - so all members of a group
+        # or none of them. As such there's no start / end date which is defined
+        # implicitly by the allocation
+        def new_blockers_by_group(
+            group: UUID | None
+        ) -> Iterator[ReservationBlocker]:
+
+            if group:
+                blocker = ReservationBlocker()
+                blocker.token = token
+                blocker.target = group
+                blocker.target_type = 'group'
+                blocker.resource = self.resource
+                blocker.reason = reason
+
+                for allocation in self.allocations_by_group(group):
+                    create_reserved_slots(
+                        allocation,
+                        allocation._start,
+                        allocation._end
+                    )
+
+                yield blocker
+
+        # all other reservations are reserved by start/end date
+        def new_blockers_by_dates(
+            dates: list[tuple[datetime, datetime]]
+        ) -> Iterator[ReservationBlocker]:
+
+            already_reserved_groups = set()
+
+            for start, end in dates:
+                for allocation in self.allocations_in_range(start, end):
+                    if allocation.group in already_reserved_groups:
+                        continue
+
+                    if not allocation.overlaps(start, end):
+                        continue
+
+                    # automatically reserve the whole group if the allocation
+                    # is part of a group
+                    if allocation.in_group:
+                        already_reserved_groups.add(allocation.group)
+
+                        yield from new_blockers_by_group(allocation.group)
+                    else:
+                        blocker = ReservationBlocker()
+                        blocker.token = token
+                        blocker.start, blocker.end = rasterizer.rasterize_span(
+                            start, end, allocation.raster
+                        )
+                        blocker.timezone = allocation.timezone
+                        blocker.target = allocation.group
+                        blocker.target_type = 'allocation'
+                        blocker.resource = self.resource
+                        blocker.reason = reason
+
+                        create_reserved_slots(allocation, start, end)
+
+                        yield blocker
+
+        # create the blockers and reserved slots
+        if group:
+            blockers = list(new_blockers_by_group(group))
+        else:
+            blockers = list(new_blockers_by_dates(dates))
+
+        if not blockers:
+            raise errors.InvalidReservationError
+
+        if not reserved_slots:
+            raise errors.NotReservableError
+
+        for blocker in blockers:
+            self.session.add(blocker)
+
+        return blockers
+
+    def remove_blocker(
+        self,
+        token: UUID,
+        id: int | None = None
+    ) -> None:
+        """ Removes all reserved slots of the given reservation blocker token.
+
+        The id is optional. If given, only the blocker with the given
+        token AND id is removed.
+
+        """
+
+        for slot in self.reserved_slots_by_blocker(token, id):
+            self.session.delete(slot)
+
+        for blocker in self.blockers_by_token(token, id):
+            self.session.delete(blocker)
+
+        # some allocations still reference reserved_slots if not for this
+        self.session.expire_all()
+
+    def change_blocker_reason(
+        self,
+        token: UUID,
+        new_reason: str | None,
+    ) -> None:
+
+        for blocker in self.blockers_by_token(token):
+            blocker.reason = new_reason
+
+    def change_blocker(
+        self,
+        token: UUID,
+        id: int,
+        new_start: datetime,
+        new_end: datetime,
+    ) -> ReservationBlocker | None:
+        """ Allows to change the timespan of a blocker under certain
+        conditions:
+
+        - The new timespan must be reservable inside the existing allocation.
+          (So you cannot use this method to block another allocation)
+        - The referenced allocation must not be in a group.
+
+        Returns the new blocker if a change was made and None instead.
+
+        """
+
+        assert new_start and new_end
+
+        new_start, new_end = self._prepare_range(new_start, new_end)
+        existing_blocker = self.blockers_by_token(token, id).one()
+
+        # if there's nothing to change, do not change
+        if (
+            existing_blocker.start == new_start
+            and existing_blocker.end in (
+                new_end,
+                new_end - timedelta(microseconds=1)
+            )
+        ):
+            return None
+
+        # will raise a MultipleResultsFound exception if this is a group
+        allocation = existing_blocker.target_allocations().one()
+
+        if not allocation.contains(new_start, new_end):
+            raise errors.TimerangeTooLong()
+
+        old_reason = existing_blocker.reason
+
+        with self.begin_nested():
+            self.remove_blocker(token, id)
+
+            new_blocker, = self.add_blocker(
+                dates=(new_start, new_end),
+                reason=old_reason,
+                token=token
+            )
+            new_blocker.id = id
+
+        return new_blocker
+
     def search_allocations(
         self,
         start: datetime,
@@ -1629,8 +1969,6 @@ class Scheduler(ContextServicesMixin):
         assert start
         assert end
 
-        start, end = self._prepare_range(start, end)
-
         assert whole_day in ('yes', 'no', 'any')
         assert groups in ('yes', 'no', 'any')
 
@@ -1645,7 +1983,7 @@ class Scheduler(ContextServicesMixin):
         else:
             day_numbers = None
 
-        query = self.allocations_in_range(start, end)
+        query = self.allocations_in_range(*self._prepare_range(start, end))
         query = query.order_by(Allocation._start)
 
         allocations = []
@@ -1653,17 +1991,23 @@ class Scheduler(ContextServicesMixin):
         known_groups = set()
         known_ids = set()
 
-        for allocation in query.all():
+        for allocation in query:
 
             if not self.is_allocation_exposed(allocation):
                 continue
-
-            s = datetime.combine(allocation.start.date(), start.time())
-            e = datetime.combine(allocation.end.date(), end.time())
-
-            # the raw dates will be UTC
-            s = sedate.replace_timezone(s, 'UTC')
-            e = sedate.replace_timezone(e, 'UTC')
+            allocation_start = allocation.display_start()
+            # NOTE: We want the correct timezone, but we don't want the
+            #       date to be on the next day for a full-day reservation
+            #       so we skip the microsecond addition
+            allocation_end = sedate.to_timezone(allocation.end, self.timezone)
+            s = sedate.standardize_date(datetime.combine(
+                allocation_start.date(),
+                start.time()
+            ), self.timezone)
+            e = sedate.standardize_date(datetime.combine(
+                allocation_end.date(),
+                end.time()
+            ), self.timezone)
 
             if not allocation.overlaps(s, e):
                 continue
@@ -1784,6 +2128,23 @@ class Scheduler(ContextServicesMixin):
 
         return targets
 
+    def reserved_slots_by_type(
+        self,
+        token: UUID,
+        type: Literal['reservation', 'blocker'] | None = None,
+    ) -> Query[ReservedSlot]:
+        """ Returns all reserved slots for the given token.
+        The type is also optional and can be used to restrict the type of
+        reserved slot that's returned
+        """
+
+        assert token
+
+        query = self.managed_reserved_slots()
+        if type is not None:
+            query = query.filter(ReservedSlot.source_type == type)
+        return query.filter(ReservedSlot.reservation_token == token)
+
     def reserved_slots_by_reservation(
         self,
         token: UUID,
@@ -1794,10 +2155,7 @@ class Scheduler(ContextServicesMixin):
         specific reservation matching token and id.
         """
 
-        assert token
-
-        query = self.managed_reserved_slots()
-        query = query.filter(ReservedSlot.reservation_token == token)
+        query = self.reserved_slots_by_type(token, 'reservation')
 
         if id is None:
             return query
@@ -1806,6 +2164,25 @@ class Scheduler(ContextServicesMixin):
             ids = allocations.with_entities(Allocation.id)
             return query.filter(ReservedSlot.allocation_id.in_(ids))
 
+    def reserved_slots_by_blocker(
+        self,
+        token: UUID,
+        id: int | None = None
+    ) -> Query[ReservedSlot]:
+        """ Returns all reserved slots of the given blocker.
+        The id is optional and may be used only return the slots from a
+        specific reservation matching token and id.
+        """
+
+        query = self.reserved_slots_by_type(token, 'blocker')
+
+        if id is None:
+            return query
+        else:
+            allocations = self.allocations_by_blocker(token, id)
+            ids = allocations.with_entities(Allocation.id)
+            return query.filter(ReservedSlot.allocation_id.in_(ids))
+
     def reservations_by_group(self, group: UUID) -> Query[Reservation]:
         tokens = self.managed_reservations().with_entities(Reservation.token)
         tokens = tokens.filter(Reservation.target == group)
@@ -1840,3 +2217,22 @@ class Scheduler(ContextServicesMixin):
             raise errors.InvalidReservationToken from None
 
         return query
+
+    def blockers_by_token(
+        self,
+        token: UUID,
+        id: int | None = None
+    ) -> Query[ReservationBlocker]:
+
+        query = self.managed_blockers()
+        query = query.filter(ReservationBlocker.token == token)
+
+        if id:
+            query = query.filter(ReservationBlocker.id == id)
+
+        try:
+            query.first()
+        except exc.NoResultFound:
+            raise errors.InvalidReservationToken from None
+
+        return query

{libres-0.9.0.dist-info → libres-0.10.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: libres
-Version: 0.9.0
+Version: 0.10.0
 Summary: A library to reserve things
 Home-page: http://github.com/seantis/libres/
 Author: Denis Krienbühl
@@ -142,6 +142,40 @@ 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)
+~~~~~~~~~~~~~~~~~~~
+
+- Fixes bug in `Scheduler.search_allocations` when the searched
+  time range contains multiple DST <-> ST transitions.
+  [Daverball]
+
 0.9.0 (23.05.2025)
 ~~~~~~~~~~~~~~~~~~~
 

{libres-0.9.0.dist-info → libres-0.10.0.dist-info}/RECORD

@@ -1,21 +1,23 @@
 libres/.gitignore,sha256=tyWYoDW7-zMdsfiJIVONRWJ5JmqJCTHzBOsi_rkIYZg,49
-libres/__init__.py,sha256=PvqWkTPcr2krxpiiHWHCJEJ0-goR_I_aTo41XWRlQvQ,243
+libres/__init__.py,sha256=9v-iLfER2w_g4fiTMUPafUATTCY4gPd72_57PqtTeog,260
 libres/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 libres/context/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 libres/context/core.py,sha256=AZMmFVqTVSkK3pomhoamLWOeqynY23g_uf32yjhgrRQ,7353
 libres/context/exposure.py,sha256=0krsky3XYplG7Uf5oLlQgdXp6XuEDjN2JGe3ljgLM14,287
-libres/context/registry.py,sha256=9UZcTQFZnTfHS1ERC8O8wXZqTwsxIz795q5Mi7UvnMg,4894
+libres/context/registry.py,sha256=JfV-QccpDbAEq154aHu7_-hznr5kXYY58czZ-0-m8vA,4986
 libres/context/session.py,sha256=bVvZ7cvSKffGrzxpDM7vKrGgwAPWRoS4No6HK1--xlg,2488
 libres/context/settings.py,sha256=IkdG67QUUuk_sQMXiwsJgelrsbx6M-7f72uJBA2JoJA,1374
 libres/db/__init__.py,sha256=Fks6T8aEacYVvXB9U1v182zKX7SuEUAkC5hTK50AuQk,145
-libres/db/queries.py,sha256=mVLMcFh7tbAOOp8fveB1T-ZBt0X3hQiaN5Krt5Mmhhs,10917
-libres/db/scheduler.py,sha256=L9I-vj3Y71h7rtPyaqfE4dD6QzZ79NiS48oXissY35w,64355
-libres/db/models/__init__.py,sha256=IL52K-0tg_v6zuiiE2k4UQNqneeb8CLUUVo_t_OBU-g,325
-libres/db/models/allocation.py,sha256=Zi-H3HGz4Xt9VhwUZmoUMc8xGr8rPBNiHGumnYcjlwI,29005
+libres/db/queries.py,sha256=EqsrKL5x5OlTWefvcESs5zg7ZyneXavTC-sGARX4OxM,11043
+libres/db/scheduler.py,sha256=mPuA-48VWQvzHQVy0VsXz4Be_f1YDVlElXWjwGaI6hA,77373
+libres/db/models/__init__.py,sha256=ESy82b2y6YX_D143QP2cns1MRsXxO32fQUvrc7DE6VY,408
+libres/db/models/allocation.py,sha256=4n6zjHWUSzxICjkap1s0pQgDOMki1vkO4l1MI65Ynk8,30699
 libres/db/models/base.py,sha256=Y2Lc60vJ1Du73D0sLozVNi1TfhtrQ3i_64NV7hsnc4g,117
-libres/db/models/other.py,sha256=REg6GlJo58eAubu4MzJqNtWqoEJrq_hTGeOs7XYU5BQ,791
-libres/db/models/reservation.py,sha256=GmDf9r_Sr0ZOQG2q-GbOtDTeJkOa8FJSi2tpWYk_hEA,5865
-libres/db/models/reserved_slot.py,sha256=_r8RUHlaQHDgo14oO5mPUyfS8pI4jmrP-_l5HzuCPwA,3090
+libres/db/models/blocker.py,sha256=P30FLf-ILqT03ZHnbFBVykY37xFAuCeOglhIH6B_1-c,4488
+libres/db/models/other.py,sha256=XRdyLo1gFY-Sg4iBSPBwOxeqZSpL5PerZISexcAQyDg,853
+libres/db/models/reservation.py,sha256=NnsH1PL_Tu2zt-fHMl_KURfj0RsvJzCPj-SmE-GR86Q,5819
+libres/db/models/reserved_slot.py,sha256=nVggmkPBB4oR1f5dEH-bsLggX5hAUNqfH7CApcRoApw,3263
+libres/db/models/timespan.py,sha256=uo6Xjie5rzm8JklsdCp0CyjeUPYOSHO9tOZI3b1oShs,220
 libres/db/models/timestamp.py,sha256=EsuxdQSUsPCkHb1F7HdrDevWZ5wDWerDFRIhqfhefNw,1301
 libres/db/models/types/__init__.py,sha256=8fx7ecDasCKsCJxGjt4qP5BbDJCG88dJRa0nzD6IetY,186
 libres/db/models/types/json_type.py,sha256=ko6K4YRWERWCpg0wYzuwJ_u-VLJ4K3j3ksJ7cGyiMzw,1137
@@ -26,8 +28,8 @@ libres/modules/errors.py,sha256=afcvKDfu7XYnGt6CfTG1gpmCaoMTPgtxwmTe2Cyz9qc,2146
 libres/modules/events.py,sha256=-YHwFJKory8RSIRTths5LBn92sodEPkhARH_a1Xml3c,5299
 libres/modules/rasterizer.py,sha256=-KYG03YkaPNnyohl_HrEJZqdHrhmGesbLgxxPahNTCc,3155
 libres/modules/utils.py,sha256=W5Kuu9LhhUWZMKLAhw7DmQEuNYb9aXWpW_HXCn62lhU,1871
-libres-0.9.0.dist-info/licenses/LICENSE,sha256=w1rojULT3naueSnr4r62MSQipL4VPtsfEcTFmSKpVuI,1069
-libres-0.9.0.dist-info/METADATA,sha256=-nJfZgAP64skrmh5Xh3GwywW0Un7KznV_AbSq9CD6Xg,10048
-libres-0.9.0.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
-libres-0.9.0.dist-info/top_level.txt,sha256=Exs6AnhZc0UTcsD5Ylyx1P89j19hJ4Dy13jxQyZwi3k,7
-libres-0.9.0.dist-info/RECORD,,
+libres-0.10.0.dist-info/licenses/LICENSE,sha256=w1rojULT3naueSnr4r62MSQipL4VPtsfEcTFmSKpVuI,1069
+libres-0.10.0.dist-info/METADATA,sha256=f3P6JcW2iBhZb666Qj1BDmttM6Z1YQiILrOGTsabres,10924
+libres-0.10.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+libres-0.10.0.dist-info/top_level.txt,sha256=Exs6AnhZc0UTcsD5Ylyx1P89j19hJ4Dy13jxQyZwi3k,7
+libres-0.10.0.dist-info/RECORD,,

{libres-0.9.0.dist-info → libres-0.10.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.8.0)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any