encommon 0.7.6__py3-none-any.whl → 0.8.1__py3-none-any.whl

encommon/times/duration.py

@@ -11,6 +11,10 @@ from typing import Literal
 from typing import Union
 from typing import get_args
 
+from ..types.strings import COMMAS
+from ..types.strings import SEMPTY
+from ..types.strings import SPACED
+
 
 
 DURAGROUP = Literal[
@@ -33,7 +37,7 @@ DURAUNITS = Union[
 
 class Duration:
     """
-    Convert provided the seconds into a human friendly format.
+    Convert the provided seconds in a human friendly format.
 
     Example
     -------
@@ -52,8 +56,8 @@ class Duration:
 
     :param seconds: Period in seconds that will be iterated.
     :param smart: Determines if we hide seconds after minute.
-    :param groups: Determine the amount of groups to show,
-        ensuring the larger units are returned before smaller.
+    :param groups: Determine the quantity of groups to show,
+        ensuring larger units are returned before smaller.
     """
 
     __source: float
@@ -122,7 +126,7 @@ class Duration:
         """
         Built-in method representing numeric value for instance.
 
-        :returns: Numeric representation for values from instance.
+        :returns: Numeric representation for value in instance.
         """
 
         return int(self.__source)
@@ -134,7 +138,7 @@ class Duration:
         """
         Built-in method representing numeric value for instance.
 
-        :returns: Numeric representation for values from instance.
+        :returns: Numeric representation for value in instance.
         """
 
         return float(self.__source)
@@ -326,7 +330,7 @@ class Duration:
         source = self.__source
         seconds = int(source)
 
-        returned: dict[DURAUNITS, int] = {}
+        units: dict[DURAUNITS, int] = {}
 
         groups: dict[DURAGROUP, int] = {
             'year': 31536000,
@@ -337,60 +341,67 @@ class Duration:
             'minute': 60}
 
 
-        for key, value in groups.items():
+        items = groups.items()
+
+        for key, value in items:
 
             if seconds < value:
                 continue
 
             _value = seconds // value
-
-            returned[key] = _value
-
             seconds %= value
 
+            units[key] = _value
+
 
-        if (source < 60
-                or (seconds >= 1
-                    and source > 60)):
-            returned['second'] = seconds
+        if ((seconds >= 1
+                and source > 60)
+                or source < 60):
+            units['second'] = seconds
 
-        if (self.__smart
-                and 'second' in returned
-                and len(returned) >= 2):
-            del returned['second']
+        if ('second' in units
+                and len(units) >= 2
+                and self.__smart):
+            del units['second']
 
 
-        items = (
-            list(returned.items())
+        _groups = (
+            list(units.items())
             [:self.__groups])
 
         if short is False:
-            return dict(items)
+            return dict(_groups)
 
         return {
             DURAMAPS[k]: v
-            for k, v in items}
+            for k, v in _groups}
 
 
     def __duration(
         self,
-        delim: str = ' ',
+        delim: str = SPACED,
         short: bool = True,
     ) -> str:
         """
-        Return the compact format calculated from source duration.
+        Return the compact format determined by source duration.
 
         :param delim: Optional delimiter for between the groups.
         :param short: Determine if we should use the short hand.
-        :returns: Compact format calculated from source duration.
+        :returns: Compact format determined by source duration.
         """
 
         parts: list[str] = []
 
         groups = self.units(short)
-        spaced = '' if short else ' '
 
-        for part, value in groups.items():
+        space = (
+            SEMPTY if short
+            else SPACED)
+
+
+        items = groups.items()
+
+        for part, value in items:
 
             unit: str = part
 
@@ -399,7 +410,8 @@ class Duration:
                 unit += 's'
 
             parts.append(
-                f'{value}{spaced}{unit}')
+                f'{value}{space}{unit}')
+
 
         return delim.join(parts)
 
@@ -409,9 +421,9 @@ class Duration:
         self,
     ) -> str:
         """
-        Return the compact format calculated from source duration.
+        Return the compact format determined by source duration.
 
-        :returns: Compact format calculated from source duration.
+        :returns: Compact format determined by source duration.
         """
 
         return self.__duration()
@@ -422,12 +434,13 @@ class Duration:
         self,
     ) -> str:
         """
-        Return the compact format calculated from source duration.
+        Return the compact format determined by source duration.
 
-        :returns: Compact format calculated from source duration.
+        :returns: Compact format determined by source duration.
         """
 
-        return self.short.replace(' ', '')
+        return self.short.replace(
+            SPACED, SEMPTY)
 
 
     @property
@@ -435,12 +448,13 @@ class Duration:
         self,
     ) -> str:
         """
-        Return the verbose format calculated from source duration.
+        Return the verbose format determined by source duration.
 
-        :returns: Compact format calculated from source duration.
+        :returns: Verbose format determined by source duration.
         """
 
         if self.__source < 60:
             return 'just now'
 
-        return self.__duration(', ', False)
+        return self.__duration(
+            COMMAS, False)

encommon/times/parse.py

@@ -15,7 +15,6 @@ from typing import Optional
 from typing import TYPE_CHECKING
 
 from dateutil import parser
-from dateutil.tz import gettz
 
 from snaptime import snap
 
@@ -23,6 +22,7 @@ from .common import NUMERISH
 from .common import PARSABLE
 from .common import SNAPABLE
 from .common import STRINGNOW
+from .common import findtz
 from .common import strptime
 from .common import utcdatetime
 
@@ -87,14 +87,7 @@ def parse_time(  # noqa: CFQ004
             and re_match(NUMERISH, source)):
         source = float(source)
 
-
-    if tzname is not None:
-        tzinfo = gettz(tzname)
-    else:
-        tzinfo = timezone.utc
-
-    if tzinfo is None:
-        raise ValueError('tzname')
+    tzinfo = findtz(tzname)
 
 
     if isinstance(source, (int, float)):
@@ -129,7 +122,7 @@ def parse_time(  # noqa: CFQ004
             .astimezone(timezone.utc))
 
 
-    raise ValueError('source')
+    raise ValueError('source')  # NOCVR
 
 
 
@@ -159,13 +152,10 @@ def shift_time(
     :returns: Python datetime object containing related time.
     """
 
-    anchor = parse_time(anchor, tzname=tzname)
-
-    parsed = snap(anchor, notate)
-
-    assert isinstance(parsed, datetime)
+    anchor = parse_time(
+        anchor, tzname=tzname)
 
-    return parsed
+    return snap(anchor, notate)
 
 
 
@@ -195,18 +185,14 @@ def string_time(
     :returns: Python datetime object containing related time.
     """
 
-    parsed: Optional[datetime] = None
-
     if formats is not None:
         with suppress(ValueError):
-            parsed = strptime(source, formats)
-
-    if parsed is None:
-        parsed = parser.parse(source)
+            return strptime(source, formats)
 
-    assert isinstance(parsed, datetime)
+    parsed = parser.parse(source)
 
-    return parse_time(parsed, tzname=tzname)
+    return parse_time(
+        parsed, tzname=tzname)
 
 
 
@@ -234,4 +220,6 @@ def since_time(
 
     delta = stop - start
 
-    return abs(delta.total_seconds())
+    since = delta.total_seconds()
+
+    return abs(since)

encommon/times/test/test_common.py

@@ -11,6 +11,9 @@ from dateutil.tz import gettz
 
 from pytest import raises
 
+from ..common import STAMP_SIMPLE
+from ..common import UNIXEPOCH
+from ..common import findtz
 from ..common import strptime
 from ..common import utcdatetime
 
@@ -28,6 +31,8 @@ def test_utcdatetime() -> None:
     assert dtime.month == 1
     assert dtime.day == 1
     assert dtime.hour == 0
+    assert dtime.minute == 0
+    assert dtime.second == 0
 
 
     dtime = utcdatetime(
@@ -38,41 +43,67 @@ def test_utcdatetime() -> None:
     assert dtime.month == 1
     assert dtime.day == 1
     assert dtime.hour == 6
+    assert dtime.minute == 0
+    assert dtime.second == 0
 
 
-    assert utcdatetime().year >= 2023
 
+def test_strptime() -> None:
+    """
+    Perform various tests associated with relevant routines.
+    """
 
 
-def test_strptime() -> None:
+    parsed = strptime(
+        UNIXEPOCH, STAMP_SIMPLE)
+
+    assert parsed.year == 1970
+    assert parsed.month == 1
+    assert parsed.day == 1
+    assert parsed.hour == 0
+    assert parsed.minute == 0
+    assert parsed.second == 0
+
+
+
+def test_strptime_raises() -> None:
     """
     Perform various tests associated with relevant routines.
     """
 
+    _raises = raises(ValueError)
 
-    dtime = strptime('1970', '%Y')
+    with _raises as reason:
+        strptime('foo', '%Y')
 
-    assert dtime.year == 1970
-    assert dtime.month == 1
-    assert dtime.day == 1
-    assert dtime.hour == 0
+    _reason = str(reason.value)
 
+    assert _reason == 'invalid'
 
-    dtime = strptime('1970', ['%Y'])
 
-    assert dtime.year == 1970
-    assert dtime.month == 1
-    assert dtime.day == 1
-    assert dtime.hour == 0
 
+def test_findtz() -> None:
+    """
+    Perform various tests associated with relevant routines.
+    """
 
 
-def test_strptime_raises() -> None:
+    tzinfo = findtz('UTC')
+
+    assert 'UTC' in str(tzinfo)
+
+
+
+def test_findtz_raises() -> None:
     """
     Perform various tests associated with relevant routines.
     """
 
-    with raises(ValueError) as reason:
-        strptime('foo', '%Y')
+    _raises = raises(ValueError)
+
+    with _raises as reason:
+        findtz('foo')
+
+    _reason = str(reason.value)
 
-    assert str(reason.value) == 'invalid'
+    assert _reason == 'tzname'

encommon/times/test/test_duration.py

@@ -8,6 +8,7 @@ is permitted, for more information consult the project license file.
 
 
 from ..duration import Duration
+from ...types.strings import COMMAS
 
 
 
@@ -16,9 +17,10 @@ def test_Duration() -> None:
     Perform various tests associated with relevant routines.
     """
 
-    duration = Duration(95401)
+    durate = Duration(95401)
 
-    attrs = list(duration.__dict__)
+
+    attrs = list(durate.__dict__)
 
     assert attrs == [
         '_Duration__source',
@@ -26,91 +28,94 @@ def test_Duration() -> None:
         '_Duration__groups']
 
 
-    assert repr(duration) == (
-        'Duration('
-        'seconds=95401.0, '
-        'smart=True, '
-        'groups=7)')
+    assert repr(durate)[:23] == (
+        'Duration(seconds=95401.')
 
-    assert isinstance(hash(duration), int)
-    assert str(duration) == '1d2h30m'
+    assert hash(durate) > 0
 
+    assert str(durate) == '1d2h30m'
 
-    assert int(duration) == 95401
-    assert float(duration) == 95401
 
-    assert duration + 1 == 95402
-    assert duration + duration == 190802
-    assert duration - 1 == 95400
-    assert duration - duration == 0
+    assert int(durate) == 95401
+    assert float(durate) == 95401
 
-    assert duration == duration
-    assert duration != Duration(60)
-    assert duration != 'invalid'
+    assert durate + 1 == 95402
+    assert durate + durate == 190802
+    assert durate - 1 == 95400
+    assert durate - durate == 0
 
-    assert duration > Duration(95400)
-    assert duration >= Duration(95401)
-    assert duration < Duration(95402)
-    assert duration <= Duration(95401)
+    assert durate == durate
+    assert durate != Duration(60)
+    assert durate != 'invalid'
 
+    assert durate > Duration(95400)
+    assert durate >= Duration(95401)
+    assert durate < Duration(95402)
+    assert durate <= Duration(95401)
 
-    assert duration.source == 95401
-    assert duration.smart is True
-    assert duration.groups == 7
 
-    assert duration.short == '1d 2h 30m'
-    assert duration.compact == '1d2h30m'
-    assert duration.verbose == (
-        '1 day, 2 hours, 30 minutes')
+    assert durate.source == 95401
+
+    assert durate.smart is True
 
-    assert duration.units() == {
+    assert durate.groups == 7
+
+    assert durate.units() == {
         'day': 1,
         'hour': 2,
         'minute': 30}
 
+    assert durate.short == '1d 2h 30m'
+
+    assert durate.compact == '1d2h30m'
+
+    assert durate.verbose == (
+        '1 day, 2 hours, 30 minutes')
+
+
 
-    duration = Duration(
+def test_Duration_cover() -> None:
+    """
+    Perform various tests associated with relevant routines.
+    """
+
+    durate = Duration(
         seconds=7501,
         smart=False)
 
-    assert duration.short == '2h 5m 1s'
-    assert duration.compact == '2h5m1s'
-    assert duration.verbose == (
+    assert durate.short == '2h 5m 1s'
+    assert durate.compact == '2h5m1s'
+    assert durate.verbose == (
         '2 hours, 5 minutes, 1 second')
 
 
-    duration = Duration(
+    durate = Duration(
+        groups=3,
         seconds=694800,
-        smart=False,
-        groups=3)
+        smart=False)
 
-    assert duration.short == '1w 1d 1h'
-    assert duration.compact == '1w1d1h'
-    assert duration.verbose == (
+    assert durate.short == '1w 1d 1h'
+    assert durate.compact == '1w1d1h'
+    assert durate.verbose == (
         '1 week, 1 day, 1 hour')
 
 
-    duration = Duration(36295261)
+    durate = Duration(36295261)
 
-    assert duration.units() == {
-        'year': 1,
-        'week': 3,
-        'month': 1,
-        'day': 4,
-        'hour': 2,
-        'minute': 1}
+    units = durate.units(False)
+    assert units == {
+        'year': 1, 'week': 3,
+        'month': 1, 'day': 4,
+        'hour': 2, 'minute': 1}
 
-    assert duration.units(True) == {
-        'y': 1,
-        'w': 3,
-        'mon': 1,
-        'd': 4,
-        'h': 2,
-        'm': 1}
+    units = durate.units(True)
+    assert units == {
+        'y': 1, 'w': 3, 'mon': 1,
+        'd': 4, 'h': 2, 'm': 1}
 
 
 
-def test_Duration_cover() -> None:
+def test_Duration_iterate() -> None:
     """
     Perform various tests associated with relevant routines.
     """
@@ -126,52 +131,72 @@ def test_Duration_cover() -> None:
 
     expects = {
 
-        year: ('1y', '1 year'),
-        year + 1: ('1y', '1 year'),
+        year: (
+            '1y', '1 year'),
+        year + 1: (
+            '1y', '1 year'),
         year - 1: (
             '12mon4d23h59m',
             '12 months, 4 days'),
 
-        quarter: ('3mon', '3 months'),
-        quarter + 1: ('3mon', '3 months'),
+        quarter: (
+            '3mon', '3 months'),
+        quarter + 1: (
+            '3mon', '3 months'),
         quarter - 1: (
             '2mon4w1d23h59m',
             '2 months, 4 weeks'),
 
-        month: ('1mon', '1 month'),
-        month + 1: ('1mon', '1 month'),
+        month: (
+            '1mon', '1 month'),
+        month + 1: (
+            '1mon', '1 month'),
         month - 1: (
             '4w1d23h59m',
             '4 weeks, 1 day'),
 
-        week: ('1w', '1 week'),
-        week + 1: ('1w', '1 week'),
+        week: (
+            '1w', '1 week'),
+        week + 1: (
+            '1w', '1 week'),
         week - 1: (
             '6d23h59m',
             '6 days, 23 hours'),
 
-        day: ('1d', '1 day'),
-        day + 1: ('1d', '1 day'),
+        day: (
+            '1d', '1 day'),
+        day + 1: (
+            '1d', '1 day'),
         day - 1: (
             '23h59m',
             '23 hours, 59 minutes'),
 
-        hour: ('1h', '1 hour'),
-        hour + 1: ('1h', '1 hour'),
-        hour - 1: ('59m', '59 minutes'),
+        hour: (
+            '1h', '1 hour'),
+        hour + 1: (
+            '1h', '1 hour'),
+        hour - 1: (
+            '59m', '59 minutes'),
+
+        second: (
+            '1m', '1 minute'),
+        second + 1: (
+            '1m', '1 minute'),
+        second - 1: (
+            '59s', 'just now')}
 
-        second: ('1m', '1 minute'),
-        second + 1: ('1m', '1 minute'),
-        second - 1: ('59s', 'just now')}
 
+    items = expects.items()
 
-    for source, expect in expects.items():
+    for source, expect in items:
 
-        duration = Duration(source)
-        assert duration.compact == expect[0]
+        durate = Duration(source)
 
-        duration = Duration(source)
-        verbose = ', '.join(
-            duration.verbose.split(', ')[:2])
+        compact, verbose = expect
+        _compact = durate.compact
+        _verbose = COMMAS.join(
+            durate.verbose
+            .split(', ')[:2])
 
-        assert verbose == expect[1]
+        assert _compact == compact
+        assert _verbose == verbose