Merge pull request #150 from KaartGroup/next_slot_available

Convenience properties for when API is next available

.gitignore

@@ -1,5 +1,7 @@
 .DS_Store
+.idea/
 .pytest_cache/
+.vscode/
 **/__pycache__/
 *.py[cod]
 dist/
@@ -11,4 +13,4 @@ eggs/
 pip-log.txt
 docs/_build/
 Pipfile.lock
-venv/
+venv/

overpass/api.py

@@ -7,8 +7,10 @@
 import json
 import logging
 import re
-from datetime import datetime
+from datetime import datetime, timezone
 from io import StringIO
+from math import ceil
+from typing import Optional
 
 import geojson
 import requests
@@ -204,6 +206,34 @@ def slots_running(self) -> tuple:
         """
         return self._api_status()["running_slots"]
 
+    @property
+    def slot_available_datetime(self) -> Optional[datetime]:
+        """
+        :returns: None if a slot is available now (no wait needed) or a datetime representing when the next slot will become available
+        """
+        if self.slots_available:
+            return None
+        return min(self.slots_running + self.slots_waiting)
+
+    @property
+    def slot_available_countdown(self) -> int:
+        """
+        :returns: 0 if a slot is available now, or an int of seconds until the next slot is free
+        """
+        try:
+            return max(
+                ceil(
+                    (
+                        self.slot_available_datetime -
+                        datetime.now(timezone.utc)
+                    ).total_seconds()
+                ),
+                0
+            )
+        except TypeError:
+            # Can't subtract from None, which means slot is available now
+            return 0
+
     def search(self, feature_type, regex=False):
         """Search for something."""
         raise NotImplementedError()

setup.py

@@ -20,5 +20,5 @@
         "Topic :: Utilities",
     ],
     install_requires=["requests>=2.3.0", "geojson>=1.0.9", "shapely>=1.6.4"],
-    extras_require={"test": ["pytest"]},
+    extras_require={"test": ["pytest", "requests-mock[fixture]"]},
 )