batutils 2.0.0__py3-none-any.whl

batutils/__init__.py

@@ -0,0 +1,5 @@
+__version__ = '2.0.0'
+
+__author__ = 'Thordur Matthiasson <doddi79@gmail.com>'
+__license__ = 'MIT License'
+__copyright__ = 'Copyright 2024 - Thordur Matthiasson, Copyright 2013-2024 - CCP Games ehf'

batutils/_common/__init__.py

@@ -0,0 +1,6 @@
+"""Here we should place code that is used in multiple submodules so they don't
+import from one another, thus enabling us to use any single submodule without
+everything else tagging along.
+
+"""
+from ._decode import *

batutils/_common/_decode.py

@@ -0,0 +1,40 @@
+__all__ = [
+    'decode_bytes',
+]
+
+_ENCODINGS_TO_TRY = (
+    'utf-8',
+    'latin-1',
+    'utf-16',
+    'utf-32',
+    'windows-1252',
+    'big5',
+    'shift_jis',
+    'gb18030',
+    'iso-8859-15'
+)
+
+
+def decode_bytes(byte_str: bytes) -> str:
+    """Tries to decode a bytes string into a str by trial-and-error, first using
+    the default encoding of the current runtime environment, and then by going
+    through a list of the most commonly used encodings used at the time of this
+    writing, in September 2023, as estimated by ChatGTP 4. :D
+
+    :raises ValueError: If it fails to decode the given bytes using any of the
+                        encodings attempted
+    """
+    try:  # First we try to Decode with default encoding!
+        return byte_str.decode()
+    except UnicodeDecodeError:
+        pass
+
+    # If not, then we go through the list...!
+    for enc in _ENCODINGS_TO_TRY:
+        try:
+            return byte_str.decode(enc)
+        except UnicodeDecodeError:
+            pass
+
+    # If we reach here, then we've failed to decode :(
+    raise ValueError(f'failed to decode bytes to str by trial and error: {byte_str!r}')

batutils/dtu/__init__.py

@@ -0,0 +1,19 @@
+"""This is the main API module of datetimeutils of batutils.
+
+The intended use case is to go:
+```python
+from batutils import dtu
+```
+
+And then use `dtu` in your code as it serves as the "official" API of the
+package.
+"""
+from batutils.dtu.structs import *
+
+from batutils.dtu.shortcuts import *
+
+from batutils.dtu.casting import *
+from batutils.dtu.formatting import *
+from batutils.dtu.parsers import *
+
+from batutils import __version__ as VERSION  # noqa

batutils/dtu/casting/__init__.py

@@ -0,0 +1,5 @@
+from ._filetime import *
+from ._string import *
+from ._timestamp import *
+from ._instant import *
+from ._any import *

batutils/dtu/casting/_any.py

@@ -0,0 +1,136 @@
+__all__ = [
+    'any_to_datetime',
+]
+import warnings
+
+from batutils.dtu.structs import *
+from batutils._common import *
+from batutils.dtu.casting._filetime import *
+from batutils.dtu.casting._string import *
+from batutils.dtu.casting._timestamp import *
+from batutils.dtu.casting._instant import *
+
+_NOT_SUPPLIED = object()
+
+_now = Datetime.now()
+_1000_years_plus = _now.replace(_now.year + 1000)
+_1000_years_minus = _now.replace(_now.year - 1000)
+
+_TIMESTAMP_MIN_RANGE = datetime_to_timestamp(_1000_years_minus)
+_TIMESTAMP_MAX_RANGE = datetime_to_timestamp(_1000_years_plus)
+
+_INSTANT_MIN_RANGE = datetime_to_instant(_1000_years_minus)
+_INSTANT_MAX_RANGE = datetime_to_instant(_1000_years_plus)
+
+_REVERSE_DATETIME_REXEX = re.compile(r'(?P<day>3[01]|[012]?\d)[- /.,\\](?P<month>1[012]|0?\d)[- /.,\\]'
+                                     r'(?P<year>[12][0189]\d{2})(?:[ @Tt]{0,1}(?:(?P<hour>[2][0-3]|[01]?\d)[ .:,]'
+                                     r'(?P<minute>[012345]?\d))?(?:[ .:,](?P<second>[012345]?\d)'
+                                     r'(?:[ .:,](?P<millisecond>\d{0,6}))?)?)?')
+_REVERSE_US_DATETIME_REXEX = re.compile(r'(?P<month>1[012]|0?\d)[- /.,\\](?P<day>3[01]|[012]?\d)[- /.,\\]'
+                                        r'(?P<year>[12][0189]\d{2})(?:[ @Tt]{0,1}(?:(?P<hour>[2][0-3]|[01]?\d)[ .:,]'
+                                        r'(?P<minute>[012345]?\d))?(?:[ .:,](?P<second>[012345]?\d)'
+                                        r'(?:[ .:,](?P<millisecond>\d{0,6}))?)?)?')
+
+
+def any_to_datetime(temporal_object: T_TEMPORAL_VALUE,
+                    default: Any = _NOT_SUPPLIED) -> Union[Datetime, Any]:
+    """Turns datetime, date, Windows filetime and posix time into a python
+    datetime if possible. By default, returns the same input value on failed
+    casting but another default return value can be given.
+
+    This function is timezone naive.
+
+    If given a number the following trickery is performed:
+
+    - If the number, treated as a timestamp, represents a datetime value that is
+      within 1000 years of now (past or future) it will be treated as a timestamp
+      because timestamps are the most commonly used numerical representations of
+      datetimes
+    - If the number is outside that range, we'll check if the number would be
+      within 1000 years of now if treated as an instant.
+    - Otherwise, we assume that such a large number must be a filetime
+
+    This does mean that there are certain cases that will yield incorrect
+    results, including:
+
+    - Timestamps more than 1000 years in the past or future (they'll be
+      treated as instants or filetimes)
+    - Instants within a couple of years of 1970 (1969-01-20 to 1971-01-22 at
+      the time of this writing) will be treated as timestamps
+    - Filetimes for the years 1600-1601 might get treated as instants or
+      timestamps
+
+    Concerning strings, there are also potential pitfalls if casting US
+    formatted YYYY-DD-MM strings, as this method will FIRST assume a standard
+    ISO format and only try the US one if that fails, so US formatted strings
+    with days between 1 and 12 will be treated as ISO and have their day and
+    month numbers switched.
+
+    Note: This is a "best-guess" method and if these edge cases are
+    unacceptable, you should totally not be using it, and instead, know exactly
+    what format your data is in and use the appropriate specific casting method.
+    """
+    if default == _NOT_SUPPLIED:
+        default = temporal_object
+    try:
+        if isinstance(temporal_object, Datetime):
+            return temporal_object
+
+        if isinstance(temporal_object, Date):
+            return datetime.datetime.combine(temporal_object, Time())
+
+        if isinstance(temporal_object, (float, int)):
+            if _TIMESTAMP_MIN_RANGE < temporal_object < _TIMESTAMP_MAX_RANGE:
+                # This range means that the number, if treated as a timestamp,
+                # represents a datetime within 1000 years to/from now so it's the
+                # most likely bet!
+                return timestamp_to_datetime(temporal_object)
+
+            if _INSTANT_MIN_RANGE < temporal_object < _INSTANT_MAX_RANGE:
+                # This range means that the number, if treated as an instant,
+                # represents a datetime within 1000 years to/from now so it's the
+                # second most likely bet!
+                return timestamp_to_datetime(temporal_object)
+
+            # This number is so large that it's most likely a filetime!
+            return filetime_to_datetime(temporal_object)
+
+        if isinstance(temporal_object, bytes):
+            try:
+                temporal_object = decode_bytes(temporal_object)
+            except ValueError:
+                return temporal_object
+
+        if isinstance(temporal_object, str):
+            # Is this a number in string format?
+            try:
+                # Let's just try and pass this through the int caster, if that works, we evaluate it again as an int
+                return any_to_datetime(int(temporal_object))
+            except (TypeError, ValueError):
+                pass
+
+            try:
+                # Let's just try and pass this through the float caster, if that works, we evaluate it again as an int
+                return any_to_datetime(float(temporal_object))
+            except (TypeError, ValueError):
+                pass
+
+            # First we'll try the day-month-year pattern
+            value = regex_to_datetime(temporal_object, _REVERSE_DATETIME_REXEX)
+            if value:
+                return value
+
+            # Then the month-day-year pattern
+            value = regex_to_datetime(temporal_object, _REVERSE_US_DATETIME_REXEX)
+            if value:
+                return value
+
+            # How'bout good old ISO year-month-day then? :D
+            value = isostr_to_datetime(temporal_object)
+            if value:
+                return value
+
+    except (OverflowError, ValueError):
+        pass  # Oh well
+
+    return default

batutils/dtu/casting/_filetime.py

@@ -0,0 +1,36 @@
+__all__ = [
+    'filetime_to_datetime',
+    'datetime_to_filetime',
+]
+
+from batutils.dtu.structs import *
+
+_FILETIME_NULL_DATE = Datetime(1601, 1, 1, 0, 0, 0)
+
+
+def filetime_to_datetime(filetime: T_NUMBER) -> Datetime:
+    """Converts a Windows file time value (number of 100-nanosecond ticks since
+    1 January 1601 00:00:00 UTC) to a standard python datetime.
+    Valid values are approx. -5.04911232e17 to 2.65046774399999999e18
+
+    This function is timezone naive.
+
+    :raise OverflowError: if filetime value is out of the range of python
+                          datetime (between the year 1 and 9999 AD)
+    """
+    return _FILETIME_NULL_DATE + TimeDelta(microseconds=(filetime / 10))
+
+
+def datetime_to_filetime(dt: T_DATE_VALUE) -> int:
+    """Converts a python datetime (or date) object to a Windows filetime value
+    (number of 100-nanosecond ticks since 1 January 1601 00:00:00 UTC).
+
+    If the supplied parameter is a date as opposed to a datetime, it will first
+    be converted locally to a datetime with the time 00:00:00.000000
+
+    This function is timezone naive.
+    """
+    if not isinstance(dt, Datetime) and isinstance(dt, Date):
+        dt = Datetime.combine(dt, Time(0, 0, 0))
+    delta = dt - _FILETIME_NULL_DATE
+    return 10 * ((delta.days * 86400 + delta.seconds) * 1000000 + delta.microseconds)

batutils/dtu/casting/_instant.py

@@ -0,0 +1,31 @@
+__all__ = [
+    'instant_to_datetime',
+    'datetime_to_instant',
+]
+from batutils.dtu.structs import *
+from ._timestamp import *
+
+
+def instant_to_datetime(milliseconds_since_epoch: T_NUMBER, minmax_on_fail: bool = False) -> Datetime:
+    """Converts an integer representing milliseconds since the Unix epoch
+    (January 1, 1970) to a Python datetime object.
+
+    :param milliseconds_since_epoch: Milliseconds since Unix epoch (January 1, 1970).
+    :param minmax_on_fail: If True, will return the minimum or maximum possible
+                           value of Datetime in case of overflow (positive or
+                           negative)
+    :return: A Python Datetime
+    """
+    return timestamp_to_datetime(milliseconds_since_epoch / 1000., minmax_on_fail)
+
+
+def datetime_to_instant(dt: T_DATE_VALUE) -> int:
+    """Converts a Python datetime object to the number of milliseconds since
+    Unix epoch (January 1, 1970).
+
+    If given a date only, it will assume a time of 00:00:00.000000.
+
+    :param dt: Python datetime (or date).
+    :return: Number of milliseconds since Unix epoch (January 1, 1970)
+    """
+    return int(datetime_to_timestamp(dt) * 1000)

batutils/dtu/casting/_string.py

@@ -0,0 +1,81 @@
+__all__ = [
+    'regex_to_datetime',
+    'isostr_to_datetime',
+]
+
+from batutils.dtu.structs import *
+from typing import *
+
+_T_PATTERN = Union[re.Pattern, str]
+
+# Rexex from HELL! ;)
+_ISODATE_REGEX = re.compile(r'^(?:(?P<year>[0]{0,3}[1-9]\d{0,3})[- /.,\\]'
+                            r'(?P<month>1[012]|0?\d)[- /.,\\](?P<day>3[01]|[012]?\d))?'
+                            r'(?:[ @Tt]{0,1}(?:(?P<hour>[2][0-3]|[01]?\d)[ .:,]'
+                            r'(?P<minute>[012345]?\d))?(?:[ .:,](?P<second>[012345]?\d)'
+                            r'(?:[ .:,](?P<millisecond>\d{0,6}))?)?)?')
+
+
+def regex_to_datetime(string: str, regex_pattern: _T_PATTERN) -> Optional[Datetime]:
+    """Given a string and a regex pattern with named groups with the same
+    keywords as the datetime object takes, this method uses that pattern to grab
+    those keywords and initialize and return a datetime object.
+
+    If only date keywords are found, the resulting datetime will have its time
+    set to midnight (0:00:00.0).
+
+    If only time keywords are found, the resulting datetime will have its date
+    set to today's date.
+
+    Failing to find a valid pattern this will simply return a None.
+    """
+    if isinstance(regex_pattern, str):
+        regex_pattern = re.compile(regex_pattern)
+    match = regex_pattern.match(string.strip())
+    if match:
+        parts = match.groupdict()
+        found_date = False
+        if parts['year'] and parts['month'] and parts['day']:
+            date_part = Date(int(parts['year']), int(parts['month']), int(parts['day']))
+            found_date = True
+        else:
+            date_part = Date.today()
+
+        found_time = False
+        if parts['hour'] and parts['minute']:
+            time_part = Time(int(parts['hour']), int(parts['minute']), int(parts['second'] or 0), int(parts['millisecond'] or 0))
+            found_time = True
+        else:
+            time_part = Time()
+
+        if found_date or found_time:
+            return Datetime.combine(date_part, time_part)
+    return None
+
+
+def isostr_to_datetime(string: str) -> Optional[Datetime]:
+    """Converts an iso(-ish) formatted string to datetime.
+
+    The pattern is quite forgiving in a few ways so context based
+    sanity-checking might be in order when parsing strings from "iffy"
+    sources (user input):
+
+        - The time part is optional, as well as individual time parts
+        - Seperator character for date parts can be: dash (-), slash (/),
+          backslash (\\), dot (.), comma (,), or space ( )
+        - Seperator character for time parts can be: colum (:), dot (.),
+          comma (,), or space ( )
+        - Seperator character of date and time halves can be: either case of
+          the letter T (T or t), the at symbol (@) or space ( )
+        - Values less than ten do not have to be zero-filled
+          ("2013-1-2T3:4:5.6789" == "2013-01-02T03:04:05.6789")
+        - The year can be any value from 1-9999
+
+    Otherwise, normal datetime restrictions apply (month must be 1-12, minutes
+    hust me 0-59 etc.)
+
+    This function is timezone naive.
+
+    Failing to find a valid pattern this will simply return a None.
+    """
+    return regex_to_datetime(string, _ISODATE_REGEX)

batutils/dtu/casting/_timestamp.py

@@ -0,0 +1,50 @@
+__all__ = [
+    'timestamp_to_datetime',
+    'datetime_to_timestamp',
+]
+from batutils.dtu.structs import *
+import calendar
+
+
+def timestamp_to_datetime(seconds_since_epoch: T_NUMBER, minmax_on_fail: bool = False) -> Datetime:
+    """Converts an int or float representing seconds since the Unix epoch
+    (January 1, 1970) to a Python datetime object.
+
+    :param seconds_since_epoch: Seconds since Unix epoch (January 1, 1970).
+    :param minmax_on_fail: If True, will return the minimum or maximum possible
+                           value of Datetime in case of overflow (positive or
+                           negative)
+    :return: A Python Datetime
+    """
+    try:
+        return Datetime.fromtimestamp(seconds_since_epoch)
+    except OSError:
+        try:
+            return Datetime(1970, 1, 1, 0, 0, 0, 0) + TimeDelta(seconds=seconds_since_epoch)
+        except OverflowError:
+            if minmax_on_fail:
+                if seconds_since_epoch > 0:
+                    return Datetime.max
+                else:
+                    return Datetime.min
+            else:
+                raise
+
+
+def datetime_to_timestamp(dt: T_DATE_VALUE) -> float:
+    """Converts a Python datetime object to the number of seconds since
+    Unix epoch (January 1, 1970) as a float, including fractional seconds.
+
+    If given a date only, it will assume a time of 00:00:00.000000.
+
+    :param dt: Python datetime (or date).
+    :return: Number of seconds since Unix epoch (January 1, 1970)
+    """
+    if not isinstance(dt, Datetime) and isinstance(dt, Date):
+        dt = Datetime.combine(dt, Time(0, 0, 0, 0))
+        # TODO(thordurm@ccpgames.com>) 2024-05-22: HANDLE SECONDS!!!
+
+    int_part = float(calendar.timegm(dt.utctimetuple()))
+    if dt.microsecond:
+        int_part += dt.microsecond / 1000000.0
+    return int_part

batutils/dtu/formatting/__init__.py

@@ -0,0 +1,2 @@
+from ._serialize import *
+from ._delta import *

batutils/dtu/formatting/_delta.py

@@ -0,0 +1,62 @@
+__all__ = [
+    'deltastr',
+    'agostr',
+]
+
+from batutils.dtu.structs import *
+
+
+def deltastr(delta: TimeDelta, default: str = '') -> str:
+    """Turns timedelta into a string like "3 weeks"
+    or "a few seconds" or "1 year and 7 months".
+
+    Example:
+
+        >>> deltastr(datetime.timedelta(days=2002, seconds=20000))
+        '5 years'
+        >>> deltastr(datetime.timedelta(days=366, seconds=20000))
+        '1 year and 5 hours'
+        >>> deltastr(datetime.timedelta(seconds=360))
+        '6 minutes'
+        >>> deltastr(datetime.timedelta(seconds=90))
+        '1 minute'
+        >>> deltastr(datetime.timedelta(seconds=59))
+        'a few seconds'
+    """
+    if not isinstance(delta, TimeDelta):
+        return default
+
+    ds = DeltaSplit(delta)
+    return ds.to_str(max_number_of_fields=2,
+                     include_seconds=False,
+                     directionals=None,
+                     only_sec_str='a few seconds',
+                     granularity_halting_threshold=1)
+
+
+def agostr(delta_or_date: Union[T_DATETIME_VALUE, TimeDelta], default: str = '', utc: bool = True) -> str:
+    """Same as deltastr except if given a date/time/datetime value it
+    automatically calculates the timedelta from (or to) now to (or from) the
+    given value and uses that.
+
+    This function uses UTC time for comparison by default but can be instructed
+    to use the local timezone of its running environment.
+    """
+    if utc:
+        now = Datetime.utcnow()
+    else:
+        now = Datetime.now()
+
+    if isinstance(delta_or_date, Datetime):
+        delta_or_date = now - delta_or_date
+
+    elif isinstance(delta_or_date, Date):
+        delta_or_date = now.date() - delta_or_date
+
+    elif isinstance(delta_or_date, Time):
+        delta_or_date = Datetime.combine(now.date(), delta_or_date)
+
+    return deltastr(delta_or_date, default)
+
+
+

batutils/dtu/formatting/_serialize.py

@@ -0,0 +1,26 @@
+__all__ = [
+    'serialize',
+    'to_str',
+]
+
+from batutils.dtu.structs import *
+
+
+def serialize(temporal_object: T_TEMPORAL_VALUE) -> Union[str, float]:
+    """Returns the ISO string version of datetimes, dates, times and the float
+    version of total_seconds of timedeltas.
+
+    If the given value is none of these, the same value is just returned
+    """
+    if isinstance(temporal_object, (Datetime, Date, Time)):
+        return temporal_object.isoformat()
+    elif isinstance(temporal_object, TimeDelta):
+        return temporal_object.total_seconds()
+    else:
+        return temporal_object
+
+
+def to_str(temporal_object: T_TEMPORAL_VALUE) -> str:
+    """Returns a string version of whatever serialize returned.
+    """
+    return str(serialize(temporal_object))

batutils/dtu/parsers/__init__.py

@@ -0,0 +1,2 @@
+from ._string import *
+from ._timedelta import *

batutils/dtu/parsers/_string.py

@@ -0,0 +1,44 @@
+__all__ = [
+    'str_to_rel',
+    'str_to_2dates',
+]
+
+
+from batutils.dtu.structs import *
+
+DATE_REXEX = re.compile(r'(?P<year>[0]{0,3}[1-9]\d{0,3})[- /.,\\](?P<month>1[012]|0?\d)[- /.,\\](?P<day>3[01]|[012]?\d)')
+
+
+def str_to_rel(str_value: str) -> Optional[Datetime]:
+    """
+    """
+    str_value = str_value.strip().lower()
+    if str_value in ('now', 'today'):
+        return Datetime.now()
+    elif str_value == 'yesterday':
+        return Datetime.now() - TimeDelta(days=1)
+    elif str_value == 'tomorrow':
+        return Datetime.now() + TimeDelta(days=1)
+    else:
+        return None
+
+
+def str_to_2dates(str_value: str) -> Optional[Tuple[Date, Date]]:
+    """Converts a string in the format "FROM_DATE SEPERATOR TO_DATE" where
+    FROM_DATE and TO_DATE are ISO formatted dates and SEPERATOR is anything and
+    turns it into a 2-tuple of python date objects.
+
+    >>> str_to_2dates('1969-08-15 to 1967-08-19')  # Woodstock
+    (datetime.date(1969, 8, 15), datetime.date(1967, 8, 19))
+    """
+    try:
+        match = DATE_REXEX.findall(str_value.strip())
+        if match:
+            if len(match) == 2:  # We want two dates
+                if len(match[0]) == 3 and len(match[1]) == 3:  # We want three parts
+                    date_from = datetime.date(int(match[0][0]), int(match[0][1]), int(match[0][2]))
+                    date_to = datetime.date(int(match[1][0]), int(match[1][1]), int(match[1][2]))
+                    return date_from, date_to
+        return None
+    except Exception:
+        return None