Feat/replace arrow (#323) (#324)

* Remove arrow dependency from main group.

Add optional [arrow] group.

Fix time_utils imports. Default now uses Pendulum, but Arrow utils can be imported from time_utils.arrow_tils.

Update time_utils constant names (uppercase)

Update demos.

* Update demo

* Auto-export requirements files

---------

Co-authored-by: GitHub Action <[email protected]>

Author: redjax

demo.py

@@ -45,13 +45,19 @@
 from red_utils import CustomException
 from red_utils.ext.context_managers import cli_spinners
 
+
 def test_file_utils_list() -> list[Path]:
     cwd = Path.cwd()
     search_dir = f"{cwd}/red_utils"
 
     list_files_test = path_utils.list_files(in_dir=search_dir, ext_filter=".py")
     print(f".py files found in {search_dir}: {len(list_files_test)}")
 
+    if len(list_files_test) == 0:
+        raise FileNotFoundError(
+            f"Did not find any Python files in directory: {search_dir}"
+        )
+
     rand_index = random.randint(0, len(list_files_test) - 1)
     print(f"Example util file: {list_files_test[rand_index]}")
 
@@ -209,8 +215,8 @@ def _trim(in_uuid=uuid_utils.get_rand_uuid(), trim=12):
 
 
 def test_time_utils():
-    fmt: str = time_utils.default_format
-    fmt_12: str = time_utils.twelve_hour_format
+    fmt: str = time_utils.TIME_FMT_24H
+    fmt_12: str = time_utils.TIME_FMT_12H
 
     def dt_as_dt(ts=time_utils.get_ts(), fmt=fmt):
         _dt = time_utils.datetime_as_dt(ts=ts, format=fmt)
@@ -223,7 +229,7 @@ def dt_as_str(ts=time_utils.get_ts(), fmt=fmt):
         return _dt
 
     now_unformatted = time_utils.get_ts(format=fmt)
-    now = now_unformatted.strftime(time_utils.default_format)
+    now = now_unformatted.strftime(time_utils.TIME_FMT_24H)
     print(f"Timestamp ({type(now_unformatted)}): {now_unformatted}")
     print(f"Timestamp formatted ({type(now)}): {now}")
 
@@ -394,6 +400,10 @@ def test_fastapi_utils():
 
 
 def test_sqlalchemy_utils():
+    if not pkgutil.find_loader("sqlalchemy"):
+        print(f"SQLAlchemy dependency missing, skipping tests.")
+        return None
+
     base = sqlalchemy_utils.Base()
     connection = sqlalchemy_utils.saSQLiteConnection()
     print(f"Connection: {connection}")
@@ -428,6 +438,48 @@ def test_ensuredirs(_dirs: list[Path] = [Path("test"), Path("test/testing")]):
     path_utils.ensure_dirs_exist(ensure_dirs=_dirs)
 
 
+def test_pendulum():
+    if not pkgutil.find_loader("pendulum"):
+        print(f"Pendulum dependency not found, skipping timestamp demo.")
+        return None
+
+    from red_utils.ext.time_utils import (
+        VALID_TIME_PERIODS,
+        TIME_FMT_24H,
+        TIME_FMT_12H,
+        TS_STR_REPLACE_MAP,
+        get_ts,
+    )
+
+    test = get_ts()
+    print(f"Test timestamp 1 - 24h/no-params ({type(test)}): {test}")
+
+    test2 = get_ts(as_str=True)
+    print(f"Test timestamp 2 - 24h ({type(test2)}): {test2}")
+
+    test3 = get_ts(as_str=True, str_fmt=TIME_FMT_12H)
+    print(f"Test timestamp 3 - 12h ({type(test3)}): {test3}")
+
+    test4 = get_ts(as_str=True, safe_str=True)
+    print(f"Test timestamp 4 - 24h/safe-string ({type(test4)}): {test4}")
+
+    test5 = get_ts(as_str=True, safe_str=True, str_fmt=TIME_FMT_12H)
+    print(f"Test timestamp 5 - 12h/safe-string ({type(test5)}): {test5}")
+
+
+def test_arrow():
+    if not pkgutil.find_loader("arrow"):
+        print(f"Arrow dependency not found, skipping timestamp demo.")
+        return None
+
+    import arrow
+    from red_utils.ext.time_utils.arrow_utils import shift_ts
+
+    now = arrow.now()
+    print(f"Now: {now}")
+    print(f"+1 day: {now.shift(days=1)}")
+
+
 def main():
     """Main function to control flow of demo.
 

pdm.lock

@@ -11,7 +11,6 @@ dependencies = [
     "loguru>=0.7.0",
     "msgpack>=1.0.5",
     "httpx>=0.24.1",
-    "arrow>=1.2.3",
     "pendulum>=2.1.2",
     "rich>=13.5.3",
 ]
@@ -43,6 +42,7 @@ all = [
     "msgpack>=1.0.5",
     "pendulum>=2.1.2",
     "sqlalchemy>=2.0.21",
+    "arrow>=1.3.0",
 ]
 fastapi = [
     "fastapi>=0.103.1",
@@ -62,6 +62,9 @@ http = [
     "pendulum>=2.1.2",
 ]
 "ci.lint" = ["ruff>=0.1.7", "black>=23.12.0"]
+arrow = [
+    "arrow>=1.3.0",
+]
 
 [tool.pdm.dev-dependencies]
 dev = [

pyproject.toml

@@ -4,11 +4,18 @@
 
 ## Use pkgutil to only load modules
 #  if dependencies are met
-if pkgutil.find_loader("arrow"):
-    from . import arrow_utils
-
-if pkgutil.find_loader("pendulum"):
-    from . import pendulum_utils
+# if pkgutil.find_loader("arrow"):
+#     from . import arrow_utils
+
+# if pkgutil.find_loader("pendulum"):
+#     from . import pendulum_utils
+
+if pkgutil.find_loader("arrow") and pkgutil.find_loader("pendulum"):
+    from . import time_utils
+elif pkgutil.find_loader("arrow"):
+    from .time_utils import arrow_utils
+elif pkgutil.find_loader("pendulum"):
+    from .time_utils import pendulum_utils
 
 if pkgutil.find_loader("loguru"):
     from . import loguru_utils

red_utils/ext/__init__.py

@@ -0,0 +1,16 @@
+import pkgutil
+
+if pkgutil.find_loader("arrow"):
+    from . import arrow_utils
+
+if pkgutil.find_loader("pendulum"):
+    from . import pendulum_utils
+    from .pendulum_utils import get_ts
+    from .pendulum_utils.validators import validate_time_period
+    from .pendulum_utils.constants import (
+        TIME_FMT_24H,
+        TIME_FMT_12H,
+        DEFAULT_TZ,
+        TS_STR_REPLACE_MAP,
+        VALID_TIME_PERIODS,
+    )

red_utils/ext/arrow_utils/constants.py

@@ -2,5 +2,6 @@
 #  i.e. from arrow_utils.shift_ts()
 from __future__ import annotations
 
-from . import constants, operations, validators
+from .constants import TIME_FMT_12H, TIME_FMT_24H, VALID_TIME_PERIODS
+from .validators import validate_time_period
 from .operations import shift_ts

red_utils/ext/arrow_utils/validators.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
-valid_time_periods: list[str] = [
+TIME_FMT_24H: str = "%Y-%m-%d_%H:%M:%S"
+TIME_FMT_12H: str = "%Y-%m-%d_%I:%M:%S%p"
+
+VALID_TIME_PERIODS: list[str] = [
     "years",
     "months",
     "weeks",

red_utils/ext/pendulum_utils/__init__.py

@@ -4,11 +4,12 @@
 
 from typing import Union
 
-from .constants import default_format, twelve_hour_format
-from .validators import valid_time_periods
+from .constants import TIME_FMT_24H, TIME_FMT_12H
+from .validators import VALID_TIME_PERIODS
 
 import arrow
 
+
 def shift_ts(
     start_date: Union[datetime.datetime, str, arrow.Arrow] = None,
     _tz: str = "US/Eastern",
@@ -47,15 +48,15 @@ def shift_ts(
     ## Validate inputs
     if not period:
         raise ValueError(
-            f"Missing a period of time. Must be one of {valid_time_periods}"
+            f"Missing a period of time. Must be one of {VALID_TIME_PERIODS}"
         )
     if not isinstance(period, str) and not isinstance(period, datetime.datetime):
         raise TypeError(
             f"Invalid type for period: ({type(period)}). Must be one of [str, datetime.datetime]"
         )
-    if period not in valid_time_periods:
+    if period not in VALID_TIME_PERIODS:
         raise TypeError(
-            f"Invalid period of time: [{period}]. Must be one of {valid_time_periods}"
+            f"Invalid period of time: [{period}]. Must be one of {VALID_TIME_PERIODS}"
         )
     if not amount:
         raise ValueError("Missing amount of time to shift timestamp")

red_utils/ext/pendulum_utils/constants.py

@@ -0,0 +1,27 @@
+## List of accepted values for 'period'
+from __future__ import annotations
+
+from .constants import VALID_TIME_PERIODS
+
+
+def validate_time_period(period: str = None) -> str:
+    """Validate a time period string.
+
+    Description:
+    ------------
+    Pass a time period (i.e. "days", "weeks", etc). If the period
+    matches a valid time period, string is returned, otherwise a
+    ValueError is raised.
+    """
+    if period is None:
+        raise ValueError("Missing a time period to evaluate")
+    if not isinstance(period, str):
+        raise TypeError(
+            f"Invalid type for time period: ({type(period)}). Must be one of {VALID_TIME_PERIODS}"
+        )
+    if period not in VALID_TIME_PERIODS:
+        raise ValueError(
+            f"Invalid time period: '{period}'. Must be one of {VALID_TIME_PERIODS}"
+        )
+
+    return period

red_utils/ext/time_utils/__init__.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from .constants import (
+    TIME_FMT_24H,
+    DEFAULT_TZ,
+    TS_STR_REPLACE_MAP,
+    TIME_FMT_12H,
+)
+from .operations import get_ts
+from .validators import VALID_TIME_PERIODS

red_utils/ext/arrow_utils/__init__.py renamed to red_utils/ext/time_utils/arrow_utils/__init__.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+TIME_FMT_24H: str = "YYYY-MM-DD HH:MM:SS"
+TIME_FMT_12H: str = "YYYY-MM-DD hh:mm:ssA"
+DEFAULT_TZ: str = "America/New_York"
+
+## Mapping for string character replacement
+TS_STR_REPLACE_MAP = [
+    {"search": ":", "replace": "-"},
+    {"search": " ", "replace": "_"},
+]
+
+VALID_TIME_PERIODS: list[str] = [
+    "years",
+    "months",
+    "weeks",
+    "days",
+    "hours",
+    "minutes",
+    "seconds",
+]

red_utils/ext/arrow_utils/__main__.py renamed to red_utils/ext/time_utils/arrow_utils/__main__.py

@@ -3,21 +3,22 @@
 from typing import Union
 
 from .constants import (
-    default_format,
-    default_tz,
-    safe_str_replace_map,
-    twelve_hour_format,
+    TIME_FMT_24H,
+    DEFAULT_TZ,
+    TS_STR_REPLACE_MAP,
+    TIME_FMT_12H,
 )
-from .validators import valid_time_periods
+from .validators import VALID_TIME_PERIODS
 
 import pendulum
 
+
 def get_ts(
-    tz: str = default_tz,
+    tz: str = DEFAULT_TZ,
     as_str: bool = False,
-    str_fmt: str = default_format,
+    str_fmt: str = TIME_FMT_24H,
     safe_str: bool = False,
-    char_replace_map: list[dict] = safe_str_replace_map,
+    char_replace_map: list[dict] = TS_STR_REPLACE_MAP,
 ) -> pendulum.DateTime:
     """Return a Pendulum.DateTime object of the current time. Optionally
     return timestamp as a string.

red_utils/ext/pendulum_utils/validators.py renamed to red_utils/ext/time_utils/arrow_utils/constants.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from .constants import VALID_TIME_PERIODS
+
+
+def validate_time_period(period: str = None) -> str:
+    """Validate a time period string.
+
+    Description:
+    ------------
+    Pass a time period (i.e. "days", "weeks", etc). If the period
+    matches a valid time period, string is returned, otherwise a
+    ValueError is raised.
+    """
+    if period is None:
+        raise ValueError("Missing a time period to evaluate")
+    if not isinstance(period, str):
+        raise TypeError(
+            f"Invalid type for time period: ({type(period)}). Must be one of {VALID_TIME_PERIODS}"
+        )
+    if period not in VALID_TIME_PERIODS:
+        raise ValueError(
+            f"Invalid time period: '{period}'. Must be one of {VALID_TIME_PERIODS}"
+        )
+
+    return period