diff --git a/docs/examples/1_china.py b/docs/examples/1_china.py index 52655282..2eb403f4 100644 --- a/docs/examples/1_china.py +++ b/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() ) diff --git a/tests/endpoints/test_cargo_movements_real.py b/tests/endpoints/test_cargo_movements_real.py index 25b81c94..c2d82b66 100644 --- a/tests/endpoints/test_cargo_movements_real.py +++ b/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,8 +113,8 @@ 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() @@ -116,8 +122,8 @@ 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: diff --git a/tests/test_to_ISODate.py b/tests/test_to_ISODate.py new file mode 100644 index 00000000..9c7340cd --- /dev/null +++ b/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" + ) diff --git a/vortexasdk/api/shared_types.py b/vortexasdk/api/shared_types.py index 41945047..42be9636 100644 --- a/vortexasdk/api/shared_types.py +++ b/vortexasdk/api/shared_types.py @@ -1,5 +1,6 @@ from abc import ABC from dataclasses import dataclass +from datetime import datetime from typing import List, Optional from vortexasdk.api.id import ID @@ -7,6 +8,11 @@ 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.""" diff --git a/vortexasdk/endpoints/cargo_movements.py b/vortexasdk/endpoints/cargo_movements.py index 60b7cd0e..d18d0f9d 100644 --- a/vortexasdk/endpoints/cargo_movements.py +++ b/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),