hdx-python-utilities 3.9.2__tar.gz → 3.9.3__tar.gz

{hdx_python_utilities-3.9.2 → hdx_python_utilities-3.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hdx-python-utilities
-Version: 3.9.2
+Version: 3.9.3
 Summary: HDX Python Utilities for streaming tabular data, date and time handling and other helpful functions
 Project-URL: Homepage, https://github.com/OCHA-DAP/hdx-python-utilities
 Author-email: Michael Rans <rans@email.com>

{hdx_python_utilities-3.9.2 → hdx_python_utilities-3.9.3}/documentation/index.md

@@ -341,6 +341,18 @@ Examples:
     )
     assert date == expected_date
 
+    # Handle quarter
+    date = datetime(2020, 7, 31, 7, 33, 54, tzinfo=timezone.utc)
+    assert get_quarter(date) == 3
+    year = 2022
+    quarter = 3
+    assert get_quarter_start(year, quarter) == datetime(
+        2022, 7, 1, tzinfo=timezone.utc
+    )
+    assert get_quarter_end(year, quarter) == datetime(
+        2022, 9, 30, 23, 59, 59, tzinfo=timezone.utc
+    )
+
 ## Loading and saving JSON and YAML
 
 Examples:

{hdx_python_utilities-3.9.2 → hdx_python_utilities-3.9.3}/requirements.txt

@@ -200,7 +200,7 @@ rpds-py==0.27.1
     #   referencing
 ruamel-yaml==0.18.15
     # via hdx-python-utilities (pyproject.toml)
-ruamel-yaml-clib==0.2.12
+ruamel-yaml-clib==0.2.14
     # via ruamel-yaml
 shellingham==1.5.4
     # via typer

{hdx_python_utilities-3.9.2 → hdx_python_utilities-3.9.3}/src/hdx/utilities/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '3.9.2'
-__version_tuple__ = version_tuple = (3, 9, 2)
+__version__ = version = '3.9.3'
+__version_tuple__ = version_tuple = (3, 9, 3)
 
 __commit_id__ = commit_id = None

{hdx_python_utilities-3.9.2 → hdx_python_utilities-3.9.3}/src/hdx/utilities/dateparse.py

@@ -3,7 +3,7 @@
 import re
 import time
 from calendar import monthrange
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from io import StringIO
 from typing import Dict, Optional, Tuple
 
@@ -1129,3 +1129,63 @@ def iso_string_from_datetime(date: datetime) -> str:
         str: ISO formatted date without any time elements
     """
     return date.date().isoformat()
+
+
+def get_quarter(date: datetime) -> int:
+    """Get the quarter of the given date
+
+    Args:
+        date (datetime): Date
+
+    Returns:
+        int: Quarter in which the given date is contained
+    """
+    return (date.month - 1) // 3 + 1
+
+
+def get_quarter_start(year: int, quarter: int) -> datetime:
+    """Get the first day of the quarter in which a given date is contained
+
+    Args:
+        year (int): Year
+        quarter (int): Quarter
+
+    Returns:
+        datetime: First day of quarter
+    """
+    month = 3 * (quarter - 1) + 1
+    return datetime(year, month, 1, tzinfo=timezone.utc)
+
+
+def get_quarter_end(
+    year: int, quarter: int, max_time: bool = True, include_microseconds: bool = False
+):
+    """Get the last day of the quarter in which a given date is contained
+
+    Args:
+        year (int): Year
+        quarter (int): Quarter
+        max_time (bool): Make date time component 23:59:59:999999. Defaults to True.
+        include_microseconds (bool): Includes microseconds if True. Defaults to False.
+
+    Returns:
+        datetime: First day of quarter
+    """
+    year = year + 3 * quarter // 12
+    month = 3 * quarter % 12 + 1
+    if max_time:
+        hours = 23
+        minutes = 59
+        seconds = 59
+        if include_microseconds:
+            microseconds = 999999
+        else:
+            microseconds = 0
+    else:
+        hours = 0
+        minutes = 0
+        seconds = 0
+        microseconds = 0
+    return datetime(
+        year, month, 1, hours, minutes, seconds, microseconds, tzinfo=timezone.utc
+    ) + timedelta(days=-1)

{hdx_python_utilities-3.9.2 → hdx_python_utilities-3.9.3}/tests/hdx/utilities/test_dateparse.py

@@ -7,6 +7,9 @@ from dateutil.parser import ParserError
 
 from hdx.utilities.dateparse import (
     get_datetime_from_timestamp,
+    get_quarter,
+    get_quarter_end,
+    get_quarter_start,
     get_timestamp_from_datetime,
     iso_string_from_datetime,
     now_utc,
@@ -301,3 +304,147 @@ class TestDateParse:
         date = datetime(2020, 7, 31, 7, 33, 54, tzinfo=timezone.utc)
         string = iso_string_from_datetime(date)
         assert string == "2020-07-31"
+
+    def test_get_quarter(self):
+        date = datetime(2020, 7, 31, 7, 33, 54, tzinfo=timezone.utc)
+        assert get_quarter(date) == 3
+        assert (
+            get_quarter(datetime(year=2021, month=10, day=5, tzinfo=timezone.utc)) == 4
+        )
+        assert (
+            get_quarter(datetime(year=2020, month=9, day=25, tzinfo=timezone.utc)) == 3
+        )
+        assert (
+            get_quarter(datetime(year=2020, month=12, day=11, tzinfo=timezone.utc)) == 4
+        )
+        assert (
+            get_quarter(datetime(year=2020, month=1, day=2, tzinfo=timezone.utc)) == 1
+        )
+
+    def test_get_quarter_start_end(self):
+        year = 2022
+        quarter = 3
+        assert get_quarter_start(year, quarter) == datetime(
+            2022, 7, 1, tzinfo=timezone.utc
+        )
+        assert get_quarter_end(year, quarter) == datetime(
+            2022, 9, 30, 23, 59, 59, tzinfo=timezone.utc
+        )
+        assert get_quarter_end(year, quarter, max_time=False) == datetime(
+            2022, 9, 30, tzinfo=timezone.utc
+        )
+        assert get_quarter_end(year, quarter, include_microseconds=True) == datetime(
+            2022, 9, 30, 23, 59, 59, 999999, tzinfo=timezone.utc
+        )
+
+        date = datetime(2020, 10, 5, tzinfo=timezone.utc)
+        assert get_quarter_start(date.year, get_quarter(date)) == datetime(
+            2020, 10, 1, tzinfo=timezone.utc
+        )
+        assert get_quarter_end(
+            date.year, get_quarter(date), max_time=False
+        ) == datetime(2020, 12, 31, tzinfo=timezone.utc)
+
+        date = datetime(2020, 9, 25, tzinfo=timezone.utc)
+        assert get_quarter_start(date.year, get_quarter(date)) == datetime(
+            2020, 7, 1, tzinfo=timezone.utc
+        )
+        assert get_quarter_end(
+            date.year, get_quarter(date), max_time=False
+        ) == datetime(2020, 9, 30, tzinfo=timezone.utc)
+
+        date = datetime(2020, 7, 1, tzinfo=timezone.utc)
+        assert get_quarter_start(date.year, get_quarter(date)) == datetime(
+            2020, 7, 1, tzinfo=timezone.utc
+        )
+        assert get_quarter_end(
+            date.year, get_quarter(date), max_time=False
+        ) == datetime(2020, 9, 30, tzinfo=timezone.utc)
+
+        date = datetime(2020, 9, 30, tzinfo=timezone.utc)
+        assert get_quarter_start(date.year, get_quarter(date)) == datetime(
+            2020, 7, 1, tzinfo=timezone.utc
+        )
+        assert get_quarter_end(
+            date.year, get_quarter(date), max_time=False
+        ) == datetime(2020, 9, 30, tzinfo=timezone.utc)
+
+        date = datetime(2020, 12, 11, tzinfo=timezone.utc)
+        assert get_quarter_start(date.year, get_quarter(date)) == datetime(
+            2020, 10, 1, tzinfo=timezone.utc
+        )
+        assert get_quarter_end(
+            date.year, get_quarter(date), max_time=False
+        ) == datetime(2020, 12, 31, tzinfo=timezone.utc)
+
+        date = datetime(2020, 10, 1, tzinfo=timezone.utc)
+        assert get_quarter_start(date.year, get_quarter(date)) == datetime(
+            2020, 10, 1, tzinfo=timezone.utc
+        )
+        assert get_quarter_end(
+            date.year, get_quarter(date), max_time=False
+        ) == datetime(2020, 12, 31, tzinfo=timezone.utc)
+
+        date = datetime(2020, 12, 31, tzinfo=timezone.utc)
+        assert get_quarter_start(date.year, get_quarter(date)) == datetime(
+            2020, 10, 1, tzinfo=timezone.utc
+        )
+        assert get_quarter_end(
+            date.year, get_quarter(date), max_time=False
+        ) == datetime(2020, 12, 31, tzinfo=timezone.utc)
+
+        date = datetime(2020, 1, 2, tzinfo=timezone.utc)
+        assert get_quarter_start(date.year, get_quarter(date)) == datetime(
+            2020, 1, 1, tzinfo=timezone.utc
+        )
+        assert get_quarter_end(
+            date.year, get_quarter(date), max_time=False
+        ) == datetime(2020, 3, 31, tzinfo=timezone.utc)
+
+        date = datetime(2020, 1, 1, tzinfo=timezone.utc)
+        assert get_quarter_start(date.year, get_quarter(date)) == datetime(
+            2020, 1, 1, tzinfo=timezone.utc
+        )
+        assert get_quarter_end(
+            date.year, get_quarter(date), max_time=False
+        ) == datetime(2020, 3, 31, tzinfo=timezone.utc)
+
+        date = datetime(2020, 3, 31, tzinfo=timezone.utc)
+        assert get_quarter_start(date.year, get_quarter(date)) == datetime(
+            2020, 1, 1, tzinfo=timezone.utc
+        )
+        assert get_quarter_end(
+            date.year, get_quarter(date), max_time=False
+        ) == datetime(2020, 3, 31, tzinfo=timezone.utc)
+
+        date = datetime(2020, 2, 29, tzinfo=timezone.utc)
+        assert get_quarter_start(date.year, get_quarter(date)) == datetime(
+            2020, 1, 1, tzinfo=timezone.utc
+        )
+        assert get_quarter_end(
+            date.year, get_quarter(date), max_time=False
+        ) == datetime(2020, 3, 31, tzinfo=timezone.utc)
+
+        date = datetime(2020, 5, 6, tzinfo=timezone.utc)
+        assert get_quarter_start(date.year, get_quarter(date)) == datetime(
+            2020, 4, 1, tzinfo=timezone.utc
+        )
+        assert get_quarter_end(
+            date.year, get_quarter(date), max_time=False
+        ) == datetime(2020, 6, 30, tzinfo=timezone.utc)
+
+        date = datetime(2020, 4, 1, tzinfo=timezone.utc)
+        assert get_quarter_start(date.year, get_quarter(date)) == datetime(
+            2020, 4, 1, tzinfo=timezone.utc
+        )
+        assert get_quarter_end(
+            date.year, get_quarter(date), max_time=False
+        ) == datetime(2020, 6, 30, tzinfo=timezone.utc)
+
+        date = datetime(2020, 6, 30, tzinfo=timezone.utc)
+        assert get_quarter_start(date.year, get_quarter(date)) == datetime(
+            2020, 4, 1, tzinfo=timezone.utc
+        )
+        assert get_quarter_end(
+            date.year, get_quarter(date), max_time=False
+        ) == datetime(2020, 6, 30, tzinfo=timezone.utc)