libres 0.9.0__tar.gz → 0.10.0__tar.gz

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

@@ -1,6 +1,40 @@
 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/src/libres.egg-info → libres-0.10.0}/PKG-INFO

@@ -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 → libres-0.10.0}/pyproject.toml

@@ -11,7 +11,7 @@ branch = true
 source = ["src"]
 
 [tool.bumpversion]
-current_version = "0.9.0"
+current_version = "0.10.0"
 commit = true
 message = "Release {new_version}"
 tag = true
@@ -108,6 +108,7 @@ select = [
     "PERF",
     "PGH004",
     "PIE",
+    "PT",
     "PYI",
     "Q",
     "RUF",
@@ -156,7 +157,6 @@ ignore = [
     "UP009",
     "UP012",
     "UP032",
-    "UP038",
 ]
 unfixable = []
 external = ["TC"]
@@ -164,11 +164,11 @@ allowed-confusables = ["×"]
 preview = true
 
 [tool.ruff.lint.extend-per-file-ignores]
+"src/**/*.py" = ["PT"]
 "tests/**/*.py" = [
     "C4",
     "D",
     "FLY002",
-    "I002",
     "ISC",
     "N",
     "Q",
@@ -219,65 +219,80 @@ docstring-code-format = true
 docstring-code-line-length = "dynamic"
 
 [tool.tox]
-legacy_tox_ini = """
-[tox]
-envlist = py39,py310,py311,flake8,bandit,mypy,report
-
-[gh-actions]
-python =
-    3.9: py39
-    3.10: py310
-    3.11: py311,flake8,bandit,mypy
-    3.12: py312
-    3.13: py313
+requires = ["tox>=4.21"]
+envlist = [
+    "3.9",
+    "3.10",
+    "3.11",
+    "3.12",
+    "3.13",
+    "flake8",
+    "ruff",
+    "bandit",
+    "mypy",
+    "report"
+]
 
-[testenv]
-usedevelop = true
-setenv =
-    py{39,310,311,312,313}: COVERAGE_FILE = .coverage.{envname}
-deps =
-    -e{toxinidir}[test]
-commands = pytest --cov --cov-report= {posargs}
+[tool.tox.gh.python]
+"3.9" = ["3.9"]
+"3.10" = ["3.10"]
+"3.11" = ["3.11", "flake8", "bandit", "ruff", "mypy"]
+"3.12" = ["3.12"]
+"3.13" = ["3.13"]
 
-[testenv:ruff]
-basepython = python3.11
+[tool.tox.env_run_base]
+use_develop = true
+set_env = { COVERAGE_FILE = ".coverage.{envname}" }
+deps = ["-e{toxinidir}[test]"]
+commands = [
+    [
+        "pytest",
+        "--cov",
+        "--cov-report=",
+        { replace = "posargs", default = [], extend = true }
+    ],
+]
+[tool.tox.env.ruff]
+base_python = ["python3.11"]
 skip_install = true
-deps =
-    ruff
-commands = ruff check
+deps = ["ruff"]
+commands = [["ruff", "check"]]
 
-[testenv:flake8]
-basepython = python3.11
+[tool.tox.env.flake8]
+base_python = ["python3.11"]
 skip_install = true
-deps =
-    flake8
-    flake8-type-checking
-commands = flake8 src/ tests/
+deps = [
+    "flake8",
+    "flake8-type-checking",
+]
+commands = [["flake8", "src{/}", "tests{/}"]]
 
-[testenv:bandit]
-basepython = python3.11
+[tool.tox.env.bandit]
+base_python = ["python3.11"]
 skip_install = true
-deps =
-    bandit[toml]
-commands = bandit -q -c pyproject.toml -r src
+deps = ["bandit[toml]"]
+commands = [["bandit", "-q", "-c", "pyproject.toml", "-r", "src"]]
 
-[testenv:mypy]
-basepython = python3.11
-deps =
-    -e{toxinidir}[mypy]
-commands =
-    mypy -p libres --python-version 3.9
-    mypy -p libres --python-version 3.10
-    mypy -p libres --python-version 3.11
-    mypy -p libres --python-version 3.12
-    mypy -p libres --python-version 3.13
-
-[testenv:report]
-deps =
-    coverage
+[tool.tox.env.mypy]
+base_python = ["python3.11"]
 skip_install = true
-commands =
-    coverage combine
-    coverage report -m
+deps = ["-e{toxinidir}[mypy]"]
+commands = [
+    ["mypy", "-p", "libres", "--python-version", "3.9"],
+    ["mypy", "-p", "libres", "--python-version", "3.10"],
+    ["mypy", "-p", "libres", "--python-version", "3.11"],
+    ["mypy", "-p", "libres", "--python-version", "3.12"],
+    ["mypy", "-p", "libres", "--python-version", "3.13"],
+]
 
-"""
+[tool.tox.env.report]
+base_python = ["python3.11"]
+skip_install = true
+ignore_errors = true
+ignore_outcome = true
+set_env = { COVERAGE_FILE = ".coverage" }
+deps = ["coverage"]
+commands = [
+    ["coverage", "combine", "{toxinidir}"],
+    ["coverage", "report", "-m"],
+]

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

{libres-0.9.0 → libres-0.10.0}/src/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-0.9.0 → 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.0 → 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.0 → 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.0 → 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.