feat: Use datetime type as time argument, closes #45

docs/examples/1_china.py

@@ -12,6 +12,8 @@
 
 
 """
+from datetime import datetime
+
 from vortexasdk import CargoMovements
 
 df = (
@@ -20,8 +22,8 @@
         filter_activity="loading_start",
         filter_vessels="vlcc",
         filter_destinations="China",
-        filter_time_min="2019-08-29T00:00:00.000Z",
-        filter_time_max="2019-10-30T00:00:00.000Z",
+        filter_time_min=datetime(2019, 8, 29),
+        filter_time_max=datetime(2019, 10, 30),
     )
     .to_df()
 )

tests/endpoints/test_cargo_movements_real.py

@@ -1,3 +1,5 @@
+from datetime import datetime
+
 from tests.testcases import TestCaseUsingRealAPI
 from tests.timer import Timer
 from tests.utils import to_markdown
@@ -15,8 +17,8 @@ def test_search_returns_unique_results(self):
             filter_origins=[
                 "68faf65af1345067f11dc6723b8da32f00e304a6f33c000118fccd81947deb4e"
             ],
-            filter_time_min="2019-08-29T00:00:00.000Z",
-            filter_time_max="2019-10-30T00:00:00.000Z",
+            filter_time_min=datetime(2017, 8, 29),
+            filter_time_max=datetime(2017, 10, 29),
         )
 
         print("---------------------------------")
@@ -35,8 +37,8 @@ def test_search_single_filter_id(self):
             .search(
                 filter_activity="loading_state",
                 filter_products="6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653",
-                filter_time_min="2019-08-29T00:00:00.000Z",
-                filter_time_max="2019-08-29T00:10:00.000Z",
+                filter_time_min=datetime(2019, 8, 29),
+                filter_time_max=datetime(2019, 8, 29, 0, 10),
             )
             .to_df()
             .head(2)
@@ -50,8 +52,8 @@ def test_search_single_filter_origin_name(self):
             .search(
                 filter_activity="loading_state",
                 filter_origins="Rotterdam",
-                filter_time_min="2019-08-29T00:00:00.000Z",
-                filter_time_max="2019-08-29T00:10:00.000Z",
+                filter_time_min=datetime(2019, 8, 29),
+                filter_time_max=datetime(2019, 8, 29, 0, 10),
             )
             .to_df()
             .head(2)
@@ -62,11 +64,15 @@ def test_search_single_filter_origin_name(self):
     def test_search_single_filter_owner_name(self):
         df = (
             CargoMovements()
-            .search(filter_activity="loading_state", filter_owners="DHT")
+            .search(
+                filter_activity="loading_state",
+                filter_owners="DHT",
+                filter_time_min=datetime(2019, 10, 1, 0),
+                filter_time_max=datetime(2019, 10, 1, 1),
+            )
             .to_df()
             .head(2)
         )
-
         assert len(df) == 2
 
     def test_search_single_filter_waypoint_name(self):
@@ -75,8 +81,8 @@ def test_search_single_filter_waypoint_name(self):
             .search(
                 filter_activity="any_activity",
                 filter_waypoints="Suez",
-                filter_time_min="2019-08-29T00:00:00.000Z",
-                filter_time_max="2019-08-29T00:10:00.000Z",
+                filter_time_min=datetime(2019, 8, 29),
+                filter_time_max=datetime(2019, 8, 29, 0, 10),
             )
             .to_df()
             .head(2)
@@ -91,8 +97,8 @@ def test_search_list_filter_id(self):
                 filter_products=[
                     "6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653"
                 ],
-                filter_time_min="2019-08-29T00:00:00.000Z",
-                filter_time_max="2019-08-29T00:10:00.000Z",
+                filter_time_min=datetime(2019, 8, 29),
+                filter_time_max=datetime(2019, 8, 29, 0, 10),
                 filter_activity="loading_state",
             )
             .to_df()
@@ -107,17 +113,17 @@ def test_search_to_list(self):
             filter_products=[
                 "6f11b0724c9a4e85ffa7f1445bc768f054af755a090118dcf99f14745c261653"
             ],
-            filter_time_min="2019-08-29T00:00:00.000Z",
-            filter_time_max="2019-08-29T00:10:00.000Z",
+            filter_time_min=datetime(2019, 8, 29),
+            filter_time_max=datetime(2019, 8, 29, 0, 10),
             filter_activity="loading_state",
         ).to_list()
 
     def test_speed(self):
         with Timer("Search") as t_search:
             cms = CargoMovements().search(
                 filter_activity="loading_state",
-                filter_time_min="2019-08-29T00:00:00.000Z",
-                filter_time_max="2019-08-30T00:00:00.000Z",
+                filter_time_min=datetime(2019, 8, 29),
+                filter_time_max=datetime(2019, 8, 29, 0, 10),
             )
 
         with Timer("to_list") as t_to_list:

tests/test_to_ISODate.py

@@ -0,0 +1,15 @@
+from datetime import datetime
+from unittest import TestCase
+
+from vortexasdk.api.shared_types import to_ISODate
+
+
+class TestToISODate(TestCase):
+    def test_to_ISODate(self):
+        assert to_ISODate(datetime(2018, 12, 31)) == "2018-12-31T00:00:00.000Z"
+
+    def test_to_ISODate_with_time(self):
+        assert (
+            to_ISODate(datetime(2018, 12, 31, 23, 59, 59, 123456))
+            == "2018-12-31T23:59:59.123Z"
+        )

vortexasdk/api/shared_types.py

@@ -1,12 +1,18 @@
 from abc import ABC
 from dataclasses import dataclass
+from datetime import datetime
 from typing import List, Optional
 
 from vortexasdk.api.id import ID
 
 ISODate = str
 
 
+# noinspection PyPep8Naming
+def to_ISODate(utc_datetime: datetime) -> str:
+    return utc_datetime.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+
+
 @dataclass(frozen=True)
 class Entity:
     """Holds commonly used properties."""

vortexasdk/endpoints/cargo_movements.py

@@ -1,6 +1,8 @@
 """Cargo Movements Endpoint."""
+from datetime import datetime
 from typing import List, Union
 
+from vortexasdk.api.shared_types import to_ISODate
 from vortexasdk.conversions import (
     convert_to_corporation_ids,
     convert_to_geography_ids,
@@ -24,8 +26,8 @@ def __init__(self):
     def search(
         self,
         filter_activity: str,
-        filter_time_min: str = "2019-10-01T00:00:00.000Z",
-        filter_time_max: str = "2019-10-01T01:00:00.000Z",
+        filter_time_min: datetime = datetime(2019, 10, 1, 0),
+        filter_time_max: datetime = datetime(2019, 10, 1, 1),
         cm_unit: str = "b",
         filter_charterers: Union[str, List[str]] = None,
         filter_destinations: Union[str, List[str]] = None,
@@ -48,9 +50,9 @@ def search(
               'unloading_end', 'unloaded_state', 'storing_state', 'storing_start', 'storing_end', 'transiting_state',
                'any_activity'].
 
-            filter_time_min: The start date of the time filter.
+            filter_time_min: The UTC start date of the time filter.
 
-            filter_time_max: The end date of the time filter.
+            filter_time_max: The UTC end date of the time filter.
 
             cm_unit: Unit of measurement. Enter 'b' for barrels or 't' for tonnes.
 
@@ -89,8 +91,8 @@ def search(
         >>> df = CargoMovements().search(
             filter_origins="Rotterdam",
             filter_activity='loading_state',
-            filter_time_min="2018-12-01T00:00:00.000Z",
-            filter_time_max="2018-12-01T12:00:00.000Z",
+            filter_time_min=datetime(2018, 12, 1),
+            filter_time_max=datetime(2018, 12, 1, 12),
         ).to_df(columns=['product.grade.label', 'product.group.label', 'vessels.0.vessel_class'])
         ```
 
@@ -118,8 +120,8 @@ def search(
             filter_activity="loading_state",
             filter_waypoints="suez",
             filter_vessels="vlcc",
-            filter_time_min="2016-12-01T00:00:00.000Z",
-            filter_time_max="2018-12-01T12:00:00.000Z",
+            filter_time_min=datetime(2016, 12, 01),
+            filter_time_max=datetime(2018, 12, 01),
         ).to_df(columns=cols)
         ```
 
@@ -144,8 +146,8 @@ def search(
         params = {
             # Compulsory search parameters
             "filter_activity": filter_activity,
-            "filter_time_min": filter_time_min,
-            "filter_time_max": filter_time_max,
+            "filter_time_min": to_ISODate(filter_time_min),
+            "filter_time_max": to_ISODate(filter_time_max),
             "cm_unit": cm_unit,
             "size": self._MAX_PAGE_RESULT_SIZE,
             "filter_charterers": corporation(filter_charterers),