dfdatetime 20260730__py3-none-any.whl

dfdatetime/__init__.py

@@ -0,0 +1,26 @@
+"""Digital Forensics Date and Time (dfDateTime).
+
+dfDateTime, or Digital Forensics date and time, provides date and time objects to
+preserve accuracy and precision.
+"""
+
+# Imports for date time values factory.
+from dfdatetime import apfs_time
+from dfdatetime import cocoa_time
+from dfdatetime import delphi_date_time
+from dfdatetime import dotnet_datetime
+from dfdatetime import fat_date_time
+from dfdatetime import filetime
+from dfdatetime import hfs_time
+from dfdatetime import golang_time
+from dfdatetime import java_time
+from dfdatetime import ole_automation_date
+from dfdatetime import posix_time
+from dfdatetime import rfc2579_date_time
+from dfdatetime import semantic_time
+from dfdatetime import systemtime
+from dfdatetime import time_elements
+from dfdatetime import uuid_time
+from dfdatetime import webkit_time
+
+__version__ = "20260730"

dfdatetime/apfs_time.py

@@ -0,0 +1,86 @@
+"""Apple File System (APFS) time implementation."""
+
+import decimal
+
+from dfdatetime import definitions
+from dfdatetime import factory
+from dfdatetime import posix_time
+
+
+class APFSTime(posix_time.PosixTimeInNanoseconds):
+    """Apple File System (APFS) timestamp.
+
+    The APFS timestamp is a signed 64-bit integer that contains the number of
+    nanoseconds since 1970-01-01 00:00:00.
+
+    Attributes:
+      is_local_time (bool): True if the date and time value is in local time.
+    """
+
+    def _GetNormalizedTimestamp(self):
+        """Retrieves the normalized timestamp.
+
+        Returns:
+          decimal.Decimal: normalized timestamp, which contains the number of
+              seconds since January 1, 1970 00:00:00 and a fraction of second used
+              for increased precision, or None if the normalized timestamp cannot be
+              determined.
+        """
+        if self._normalized_timestamp is None:
+            if (
+                self._timestamp is not None
+                and self._timestamp >= self._INT64_MIN
+                and self._timestamp <= self._INT64_MAX
+            ):
+                self._normalized_timestamp = (
+                    decimal.Decimal(self._timestamp)
+                    / definitions.NANOSECONDS_PER_SECOND
+                )
+
+                if self._time_zone_offset:
+                    self._normalized_timestamp -= self._time_zone_offset * 60
+
+        return self._normalized_timestamp
+
+    def CopyFromDateTimeString(self, time_string):
+        """Copies a APFS timestamp from a date and time string.
+
+        Args:
+          time_string (str): date and time value formatted as:
+              YYYY-MM-DD hh:mm:ss.######[+-]##:##
+
+              Where # are numeric digits ranging from 0 to 9 and the seconds
+              fraction can be either 3, 6 or 9 digits. The time of day, seconds
+              fraction and time zone offset are optional. The default time zone
+              is UTC.
+
+        Raises:
+          ValueError: if the date and time value is not supported.
+        """
+        super().CopyFromDateTimeString(time_string)
+
+        if (
+            self._timestamp is None
+            or self._timestamp < self._INT64_MIN
+            or self._timestamp > self._INT64_MAX
+        ):
+            raise ValueError("Date time value not supported.")
+
+    def CopyToDateTimeString(self):
+        """Copies the APFS timestamp to a date and time string.
+
+        Returns:
+          str: date and time value formatted as: "YYYY-MM-DD hh:mm:ss.#########" or
+              None if the timestamp is missing or invalid.
+        """
+        if (
+            self._timestamp is None
+            or self._timestamp < self._INT64_MIN
+            or self._timestamp > self._INT64_MAX
+        ):
+            return None
+
+        return super().CopyToDateTimeString()
+
+
+factory.Factory.RegisterDateTimeValues(APFSTime)

dfdatetime/cocoa_time.py

@@ -0,0 +1,149 @@
+"""Cocoa timestamp implementation."""
+
+import decimal
+
+from dfdatetime import definitions
+from dfdatetime import factory
+from dfdatetime import interface
+
+
+class CocoaTimeEpoch(interface.DateTimeEpoch):
+    """Cocoa time epoch."""
+
+    def __init__(self):
+        """Initializes a Cocoa time epoch."""
+        super().__init__(2001, 1, 1)
+
+
+class CocoaTime(interface.DateTimeValues):
+    """Cocoa timestamp.
+
+    The Cocoa timestamp is a floating point value that contains the number of
+    seconds since 2001-01-01 00:00:00 (also known as the Cocoa epoch).
+    Negative values represent date and times predating the Cocoa epoch.
+
+    Attributes:
+      is_local_time (bool): True if the date and time value is in local time.
+    """
+
+    # The difference between January 1, 2001 and January 1, 1970 in seconds.
+    _COCOA_TO_POSIX_BASE = -978307200
+
+    _EPOCH = CocoaTimeEpoch()
+
+    def __init__(self, precision=None, time_zone_offset=None, timestamp=None):
+        """Initializes a Cocoa timestamp.
+
+        Args:
+          precision (Optional[str]): precision of the date and time value, which
+              should be one of the PRECISION_VALUES in definitions.
+          time_zone_offset (Optional[int]): time zone offset in number of minutes
+              from UTC or None if not set.
+          timestamp (Optional[float]): Cocoa timestamp.
+        """
+        super().__init__(
+            precision=precision or definitions.PRECISION_1_SECOND,
+            time_zone_offset=time_zone_offset,
+        )
+        self._timestamp = timestamp
+
+    @property
+    def timestamp(self):
+        """float: Cocoa timestamp or None if not set."""
+        return self._timestamp
+
+    def _GetNormalizedTimestamp(self):
+        """Retrieves the normalized timestamp.
+
+        Returns:
+          decimal.Decimal: normalized timestamp, which contains the number of
+              seconds since January 1, 1970 00:00:00 and a fraction of second used
+              for increased precision, or None if the normalized timestamp cannot be
+              determined.
+        """
+        if self._normalized_timestamp is None:
+            if self._timestamp is not None:
+                self._normalized_timestamp = (
+                    decimal.Decimal(self._timestamp) - self._COCOA_TO_POSIX_BASE
+                )
+
+                if self._time_zone_offset:
+                    self._normalized_timestamp -= self._time_zone_offset * 60
+
+        return self._normalized_timestamp
+
+    def CopyFromDateTimeString(self, time_string):
+        """Copies a Cocoa timestamp from a date and time string.
+
+        Args:
+          time_string (str): date and time value formatted as:
+              YYYY-MM-DD hh:mm:ss.######[+-]##:##
+
+              Where # are numeric digits ranging from 0 to 9 and the seconds
+              fraction can be either 3, 6 or 9 digits. The time of day, seconds
+              fraction and time zone offset are optional. The default time zone
+              is UTC.
+
+        Raises:
+          ValueError: if the time string is invalid or not supported.
+        """
+        date_time_values = self._CopyDateTimeFromString(time_string)
+
+        year = date_time_values.get("year", 0)
+        month = date_time_values.get("month", 0)
+        day_of_month = date_time_values.get("day_of_month", 0)
+        hours = date_time_values.get("hours", 0)
+        minutes = date_time_values.get("minutes", 0)
+        seconds = date_time_values.get("seconds", 0)
+        nanoseconds = date_time_values.get("nanoseconds", 0)
+        time_zone_offset = date_time_values.get("time_zone_offset")
+
+        timestamp = self._GetNumberOfSecondsFromElements(
+            year, month, day_of_month, hours, minutes, seconds
+        )
+        timestamp += self._COCOA_TO_POSIX_BASE
+
+        timestamp = float(timestamp)
+        timestamp += float(nanoseconds) / definitions.NANOSECONDS_PER_SECOND
+
+        self._normalized_timestamp = None
+        self._timestamp = timestamp
+        self._time_zone_offset = time_zone_offset
+
+    def CopyToDateTimeString(self):
+        """Copies the Cocoa timestamp to a date and time string.
+
+        Returns:
+          str: date and time value formatted as: YYYY-MM-DD hh:mm:ss.###### or
+              None if the timestamp cannot be copied to a date and time string.
+        """
+        if self._timestamp is None:
+            return None
+
+        number_of_days, hours, minutes, seconds = self._GetTimeValues(
+            int(self._timestamp)
+        )
+        year, month, day_of_month = self._GetDateValuesWithEpoch(
+            number_of_days, self._EPOCH
+        )
+        microseconds = int((self._timestamp % 1) * definitions.MICROSECONDS_PER_SECOND)
+
+        return (
+            f"{year:04d}-{month:02d}-{day_of_month:02d} "
+            f"{hours:02d}:{minutes:02d}:{seconds:02d}.{microseconds:06d}"
+        )
+
+    def CopyToSerializableDict(self):
+        """Copies the date time value to a serializable dictionary.
+
+        Returns:
+          dict[str, object]: serializable dictionary.
+        """
+        serializable_dict = self._CreateSerializableDict()
+
+        serializable_dict["timestamp"] = self._timestamp
+
+        return serializable_dict
+
+
+factory.Factory.RegisterDateTimeValues(CocoaTime)

dfdatetime/decorators.py

@@ -0,0 +1,23 @@
+"""Function decorators."""
+
+import warnings
+
+
+def deprecated(function):  # pylint: disable=invalid-name
+    """Decorator to mark functions or methods as deprecated."""
+
+    def IssueDeprecationWarning(*args, **kwargs):
+        """Issue a deprecation warning."""
+        warnings.simplefilter("default", DeprecationWarning)
+        warnings.warn(
+            f"Call to deprecated function: {function.__name__:s}.",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
+
+        return function(*args, **kwargs)
+
+    IssueDeprecationWarning.__name__ = function.__name__
+    IssueDeprecationWarning.__doc__ = function.__doc__
+    IssueDeprecationWarning.__dict__.update(function.__dict__)
+    return IssueDeprecationWarning

dfdatetime/definitions.py

@@ -0,0 +1,97 @@
+"""The date and time definitions.
+
+Also see:
+  https://en.wikipedia.org/wiki/Day
+  https://en.wikipedia.org/wiki/Hour
+  https://en.wikipedia.org/wiki/Minute
+"""
+
+DAYS_PER_MONTH = (31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31)
+
+SECONDS_PER_DAY = 86400
+
+DECISECONDS_PER_SECOND = 10
+
+CENTISECONDS_PER_SECOND = 100
+
+MILLISECONDS_PER_SECOND = 1000
+
+DECIMICROSECONDS_PER_SECOND = 10000
+
+MICROSECONDS_PER_DAY = 86400000000
+MICROSECONDS_PER_SECOND = 1000000
+MICROSECONDS_PER_DECISECOND = 100000
+MICROSECONDS_PER_MILLISECOND = 1000
+
+NANOSECONDS_PER_DAY = 86400000000000
+NANOSECONDS_PER_SECOND = 1000000000
+NANOSECONDS_PER_DECISECOND = 100000000
+NANOSECONDS_PER_CENTISECOND = 10000000
+NANOSECONDS_PER_MILLISECOND = 1000000
+NANOSECONDS_PER_DECIMILISECOND = 100000
+NANOSECONDS_PER_MICROSECOND = 1000
+
+PRECISION_1_DAY = "1d"
+PRECISION_1_HOUR = "1h"
+PRECISION_1_NANOSECOND = "1ns"
+PRECISION_10_NANOSECONDS = "10s"
+PRECISION_100_NANOSECONDS = "100ns"
+PRECISION_1_MICROSECOND = "1us"
+PRECISION_10_MICROSECONDS = "10us"
+PRECISION_100_MICROSECONDS = "100us"
+PRECISION_1_MILLISECOND = "1ms"
+PRECISION_10_MILLISECONDS = "10ms"
+PRECISION_100_MILLISECONDS = "100ms"
+PRECISION_1_MINUTE = "1min"
+PRECISION_1_SECOND = "1s"
+PRECISION_2_SECONDS = "2s"
+
+PRECISION_VALUES = frozenset(
+    [
+        PRECISION_1_DAY,
+        PRECISION_1_HOUR,
+        PRECISION_1_NANOSECOND,
+        PRECISION_10_NANOSECONDS,
+        PRECISION_100_NANOSECONDS,
+        PRECISION_1_MICROSECOND,
+        PRECISION_10_MICROSECONDS,
+        PRECISION_100_MICROSECONDS,
+        PRECISION_1_MILLISECOND,
+        PRECISION_10_MILLISECONDS,
+        PRECISION_100_MILLISECONDS,
+        PRECISION_1_MINUTE,
+        PRECISION_1_SECOND,
+        PRECISION_2_SECONDS,
+    ]
+)
+
+# Create a days per century lookup table.
+DAYS_PER_CENTURY = {}
+for year in range(-10000, 10000, 100):
+    if (year % 4 == 0 and year % 100 != 0) or year % 400 == 0:
+        number_of_days = 36525
+    else:
+        number_of_days = 36524
+    DAYS_PER_CENTURY[year] = number_of_days
+
+# Create a days per year lookup table.
+DAYS_PER_YEAR = {}
+for year in range(-10000, 10000, 1):
+    if (year % 4 == 0 and year % 100 != 0) or year % 400 == 0:
+        number_of_days = 366
+    else:
+        number_of_days = 365
+    DAYS_PER_YEAR[year] = number_of_days
+
+# Create a days per year in POSIX epoch lookup table.
+DAYS_PER_YEAR_IN_POSIX_EPOCH = {}
+
+number_of_days = 0
+for year in range(1969, -10000, -1):
+    number_of_days -= DAYS_PER_YEAR[year]
+    DAYS_PER_YEAR_IN_POSIX_EPOCH[year] = number_of_days
+
+number_of_days = 0
+for year in range(1970, 10000, 1):
+    DAYS_PER_YEAR_IN_POSIX_EPOCH[year] = number_of_days
+    number_of_days += DAYS_PER_YEAR[year]

dfdatetime/delphi_date_time.py

@@ -0,0 +1,166 @@
+"""Delphi TDateTime implementation."""
+
+import decimal
+
+from dfdatetime import definitions
+from dfdatetime import factory
+from dfdatetime import interface
+
+
+class DelphiDateTimeEpoch(interface.DateTimeEpoch):
+    """Delphi TDateTime epoch."""
+
+    def __init__(self):
+        """Initializes a Delphi TDateTime epoch."""
+        super().__init__(1899, 12, 30)
+
+
+class DelphiDateTime(interface.DateTimeValues):
+    """Delphi TDateTime timestamp.
+
+    The Delphi TDateTime timestamp is a floating point value that contains
+    the number of days since 1899-12-30 00:00:00 (also known as the epoch).
+    Negative values represent date and times predating the epoch.
+
+    The maximal correct date supported by TDateTime values is limited to:
+    9999-12-31 23:59:59.999
+
+    Attributes:
+      is_local_time (bool): True if the date and time value is in local time.
+    """
+
+    # The difference between December 30, 1899 and January 1, 1970 in days.
+    _DELPHI_TO_POSIX_BASE = 25569
+
+    _EPOCH = DelphiDateTimeEpoch()
+
+    def __init__(self, precision=None, time_zone_offset=None, timestamp=None):
+        """Initializes a Delphi TDateTime timestamp.
+
+        Args:
+          precision (Optional[str]): precision of the date and time value, which
+              should be one of the PRECISION_VALUES in definitions.
+          time_zone_offset (Optional[int]): time zone offset in number of minutes
+              from UTC or None if not set.
+          timestamp (Optional[float]): Delphi TDateTime timestamp.
+        """
+        super().__init__(
+            precision=precision or definitions.PRECISION_1_MILLISECOND,
+            time_zone_offset=time_zone_offset,
+        )
+        self._timestamp = timestamp
+
+    @property
+    def timestamp(self):
+        """float: Delphi TDateTime timestamp or None if not set."""
+        return self._timestamp
+
+    def _GetNormalizedTimestamp(self):
+        """Retrieves the normalized timestamp.
+
+        Returns:
+          decimal.Decimal: normalized timestamp, which contains the number of
+              seconds since January 1, 1970 00:00:00 and a fraction of second used
+              for increased precision, or None if the normalized timestamp cannot be
+              determined.
+        """
+        if self._normalized_timestamp is None:
+            if self._timestamp is not None:
+                self._normalized_timestamp = (
+                    decimal.Decimal(self._timestamp) - self._DELPHI_TO_POSIX_BASE
+                )
+                self._normalized_timestamp *= definitions.SECONDS_PER_DAY
+
+                if self._time_zone_offset:
+                    self._normalized_timestamp -= self._time_zone_offset * 60
+
+        return self._normalized_timestamp
+
+    def CopyFromDateTimeString(self, time_string):
+        """Copies a Delphi TDateTime timestamp from a string.
+
+        Args:
+          time_string (str): date and time value formatted as:
+              YYYY-MM-DD hh:mm:ss.######[+-]##:##
+
+              Where # are numeric digits ranging from 0 to 9 and the seconds
+              fraction can be either 3, 6 or 9 digits. The time of day, seconds
+              fraction and time zone offset are optional. The default time zone
+              is UTC.
+
+        Raises:
+          ValueError: if the time string is invalid or not supported.
+        """
+        date_time_values = self._CopyDateTimeFromString(time_string)
+
+        year = date_time_values.get("year", 0)
+        month = date_time_values.get("month", 0)
+        day_of_month = date_time_values.get("day_of_month", 0)
+        hours = date_time_values.get("hours", 0)
+        minutes = date_time_values.get("minutes", 0)
+        seconds = date_time_values.get("seconds", 0)
+        nanoseconds = date_time_values.get("nanoseconds", 0)
+        time_zone_offset = date_time_values.get("time_zone_offset")
+
+        if year > 9999:
+            raise ValueError(f"Unsupported year value: {year:d}.")
+
+        timestamp = self._GetNumberOfSecondsFromElements(
+            year, month, day_of_month, hours, minutes, seconds
+        )
+        timestamp = float(timestamp) / definitions.SECONDS_PER_DAY
+        timestamp += self._DELPHI_TO_POSIX_BASE
+        timestamp += float(nanoseconds) / definitions.NANOSECONDS_PER_DAY
+
+        self._normalized_timestamp = None
+        self._timestamp = timestamp
+        self._time_zone_offset = time_zone_offset
+
+    def CopyToDateTimeString(self):
+        """Copies the Delphi TDateTime timestamp to a date and time string.
+
+        Returns:
+          str: date and time value formatted as: "YYYY-MM-DD hh:mm:ss.######" or
+              None if the timestamp is missing.
+        """
+        if self._timestamp is None:
+            return None
+
+        number_of_seconds = self._timestamp * definitions.SECONDS_PER_DAY
+
+        number_of_days, hours, minutes, seconds = self._GetTimeValues(
+            int(number_of_seconds)
+        )
+        # The maximum date supported by TDateTime values is limited to:
+        # 9999-12-31 23:59:59.999 (approximate 2958465 days since epoch).
+        # The minimum date is unknown hence assuming it is limited to:
+        # 0001-01-01 00:00:00.000 (approximate -693593 days since epoch).
+
+        if number_of_days < -693593 or number_of_days > 2958465:
+            return None
+
+        year, month, day_of_month = self._GetDateValuesWithEpoch(
+            number_of_days, self._EPOCH
+        )
+        microseconds = int(
+            (number_of_seconds % 1) * definitions.MICROSECONDS_PER_SECOND
+        )
+        return (
+            f"{year:04d}-{month:02d}-{day_of_month:02d} "
+            f"{hours:02d}:{minutes:02d}:{seconds:02d}.{microseconds:06d}"
+        )
+
+    def CopyToSerializableDict(self):
+        """Copies the date time value to a serializable dictionary.
+
+        Returns:
+          dict[str, object]: serializable dictionary.
+        """
+        serializable_dict = self._CreateSerializableDict()
+
+        serializable_dict["timestamp"] = self._timestamp
+
+        return serializable_dict
+
+
+factory.Factory.RegisterDateTimeValues(DelphiDateTime)