Repository: MaineKuehn/usim

Issue:
Simplify Resource conditions
**Short description of the feature**
Resources inherently lend themselves to ``await`` a specific level. A shorthand notation to derive conditions of the underlying ``Tracked`` value is desirable.

**Describe the solution you'd like**
Resources should directly support the comparison operators of ``Tracked`` values. The ``other`` should be either an appropriate ``resource.resource_type`` or a compatible ``dict``.

```python3
resource == resource.resource_type(desired=value)
resource == dict(desired=value)
resource == {'desired': value}
```

**Describe alternatives and the context you have considered**
Manually deriving conditions requires access to a hidden field and a helper:

```python3
resource._available == resource.resource_type(desired=value)
```


Discussion:

Patch:
diff --git a/docs/source/api/usim_resources.rst b/docs/source/api/usim_resources.rst
index 9d0366a..d2f0a71 100644
--- a/docs/source/api/usim_resources.rst
+++ b/docs/source/api/usim_resources.rst
@@ -4,6 +4,10 @@ Resource Modelling
 Resource Containers
 -------------------
 
+Resources support the comparison operations, such as ``==``, ``>=``, or ``<``.
+This derives a :py:class:`~usim.Comparison` that triggers when the Resources'
+levels reaches the desired value.
+
 .. autoclass:: usim.Resources
     :members:
 
diff --git a/usim/_basics/resource.py b/usim/_basics/resource.py
index 429d7a1..7ec42e6 100644
--- a/usim/_basics/resource.py
+++ b/usim/_basics/resource.py
@@ -1,4 +1,4 @@
-from typing import TypeVar, Generic, Optional, Type
+from typing import TypeVar, Generic, Optional, Type, Union, Dict
 
 from .._core.loop import __LOOP_STATE__
 from ._resource_level import __specialise__, ResourceLevels
@@ -72,6 +72,36 @@ class BaseResources(Generic[T]):
         )
         return f'{self.__class__.__name__}({content})'
 
+    def __eq__(self, other: Union[ResourceLevels[T], Dict[str, T]]):
+        if isinstance(other, dict):
+            other = self.resource_type(**other)
+        return self._available == other
+
+    def __ne__(self, other: Union[ResourceLevels[T], Dict[str, T]]):
+        if isinstance(other, dict):
+            other = self.resource_type(**other)
+        return self._available != other
+
+    def __gt__(self, other: Union[ResourceLevels[T], Dict[str, T]]):
+        if isinstance(other, dict):
+            other = self.resource_type(**other)
+        return self._available > other
+
+    def __ge__(self, other: Union[ResourceLevels[T], Dict[str, T]]):
+        if isinstance(other, dict):
+            other = self.resource_type(**other)
+        return self._available >= other
+
+    def __le__(self, other: Union[ResourceLevels[T], Dict[str, T]]):
+        if isinstance(other, dict):
+            other = self.resource_type(**other)
+        return self._available <= other
+
+    def __lt__(self, other: Union[ResourceLevels[T], Dict[str, T]]):
+        if isinstance(other, dict):
+            other = self.resource_type(**other)
+        return self._available < other
+
 
 class BorrowedResources(BaseResources[T]):
     """


Test patch:
diff --git a/usim_pytest/test_types/test_resource.py b/usim_pytest/test_types/test_resource.py
index ba1aadd..6e08061 100644
--- a/usim_pytest/test_types/test_resource.py
+++ b/usim_pytest/test_types/test_resource.py
@@ -187,6 +187,51 @@ class BaseResourceCase:
         async with resources.borrow(a=10, b=10):
             assert time == 10
 
+    @via_usim
+    async def test_compare(self):
+        resources = self.resource_type(a=10, b=10)
+
+        async def borrow_shortly(resource: BaseResources, **amounts):
+            async with resource.borrow(**amounts):
+                pass
+
+        async with Scope() as scope:
+            await (resources == {'a': 10, 'b': 10})
+            scope.do(borrow_shortly(resources, a=5, b=5), after=10)
+            await (resources == resources.resource_type(a=5, b=5))
+            assert time.now == 10
+        assert time.now == 10
+        async with Scope() as scope:
+            await (resources > {'a': 9, 'b': 9})
+            scope.do(borrow_shortly(resources, a=5, b=5), after=10)
+            await (resources > resources.resource_type(a=5, b=5))
+            assert time.now == 10
+        assert time.now == 20
+        async with Scope() as scope:
+            await (resources >= {'a': 10, 'b': 10})
+            scope.do(borrow_shortly(resources, a=5, b=5), after=10)
+            await (resources >= resources.resource_type(a=5, b=5))
+            assert time.now == 20
+        assert time.now == 30
+        async with Scope() as scope:
+            await (resources <= {'a': 10, 'b': 10})
+            scope.do(borrow_shortly(resources, a=5, b=5), after=10)
+            await (resources <= resources.resource_type(a=5, b=5))
+            assert time.now == 40
+        assert time.now == 40
+        async with Scope() as scope:
+            await (resources < {'a': 11, 'b': 11})
+            scope.do(borrow_shortly(resources, a=5, b=5), after=10)
+            await (resources < resources.resource_type(a=6, b=6))
+            assert time.now == 50
+        assert time.now == 50
+        async with Scope() as scope:
+            await (resources != {'a': 5, 'b': 5})
+            scope.do(borrow_shortly(resources, a=5, b=5), after=10)
+            await (resources != resources.resource_type(a=10, b=10))
+            assert time.now == 60
+        assert time.now == 60
+
 
 class TestCapacity(BaseResourceCase):
     resource_type = Capacities
diff --git a/usim_pytest/utility.py b/usim_pytest/utility.py
index 9faff58..6f11d66 100644
--- a/usim_pytest/utility.py
+++ b/usim_pytest/utility.py
@@ -74,7 +74,8 @@ def via_usim(test_case: Callable[..., Coroutine]):
             nonlocal test_completed
             await test_case(*args, **kwargs)
             test_completed = True
-        run(complete_test_case())
+        result = run(complete_test_case())
         if not test_completed:
             raise UnfinishedTest(test_case)
+        return result
     return run_test