ical.util

 1"""Utility methods used by multiple components."""
 2
 3from __future__ import annotations
 4
 5import datetime
 6from importlib import metadata
 7import uuid
 8
 9__all__ = [
10    "dtstamp_factory",
11    "uid_factory",
12    "prodid_factory",
13]
14
15
16MIDNIGHT = datetime.time()
17PRODID = "github.com/allenporter/ical"
18VERSION = metadata.version("ical")
19
20
21def dtstamp_factory() -> datetime.datetime:
22    """Factory method for new event timestamps to facilitate mocking."""
23    return datetime.datetime.now(tz=datetime.UTC)
24
25
26def uid_factory() -> str:
27    """Factory method for new uids to facilitate mocking."""
28    return str(uuid.uuid1())
29
30
31def prodid_factory() -> str:
32    """Return the ical version to facilitate mocking."""
33    return f"-//{PRODID}//{VERSION}//EN"
34
35
36def local_timezone() -> datetime.tzinfo:
37    """Get the local timezone to use when converting date to datetime."""
38    if local_tz := datetime.datetime.now().astimezone().tzinfo:
39        return local_tz
40    return datetime.timezone.utc
41
42
43def normalize_datetime(
44    value: datetime.date | datetime.datetime, tzinfo: datetime.tzinfo | None = None
45) -> datetime.datetime:
46    """Convert date or datetime to a value that can be used for comparison."""
47    if not isinstance(value, datetime.datetime):
48        value = datetime.datetime.combine(value, MIDNIGHT)
49    if value.tzinfo is None:
50        if tzinfo is None:
51            tzinfo = local_timezone()
52        value = value.replace(tzinfo=tzinfo)
53    return value