Skip to content

timedate

Datetime formatting and current-time helpers.

Examples:

>>> from datetime import datetime
>>> from ures.timedate import datetime_converter
>>> datetime_converter(datetime(2020, 1, 1, 12, 0, 0), iso8601=True)
'2020-01-01T12:00:00Z'

datetime_converter 

datetime_converter(time: datetime, iso8601: bool = True, format: str = '%Y%m%d-%H%M%S') -> str

Convert a datetime object to a formatted string.

This function converts a given datetime.datetime object into a string. If 'iso8601' is True, the datetime is converted to ISO 8601 format with a trailing 'Z'. Otherwise, the datetime is formatted using the provided custom format string.

Parameters:

  • time (datetime) –

    The datetime object to be converted.

  • iso8601 (bool, default: True ) –

    Determines the output format. - If True, returns the time in ISO 8601 format. - If False, returns the time formatted by the 'format' parameter. Defaults to True.

  • format (str, default: '%Y%m%d-%H%M%S' ) –

    The custom format string to use when 'iso8601' is False. Defaults to "%Y%m%d-%H%M%S".

Returns:

  • str ( str ) –

    The formatted time string.

Examples:

>>> import datetime
>>> dt = datetime.datetime(2020, 1, 1, 12, 0, 0)
>>> datetime_converter(dt, iso8601=True)
'2020-01-01T12:00:00Z'
>>> datetime_converter(dt, iso8601=False, format="%Y/%m/%d %H:%M")
'2020/01/01 12:00'
Source code in ures/timedate.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
def datetime_converter(
    time: datetime.datetime, iso8601: bool = True, format: str = "%Y%m%d-%H%M%S"
) -> str:
    """
    Convert a datetime object to a formatted string.

    This function converts a given datetime.datetime object into a string. If 'iso8601' is True,
    the datetime is converted to ISO 8601 format with a trailing 'Z'. Otherwise, the datetime is
    formatted using the provided custom format string.

    Args:
        time (datetime.datetime): The datetime object to be converted.
        iso8601 (bool, optional): Determines the output format.
            - If True, returns the time in ISO 8601 format.
            - If False, returns the time formatted by the 'format' parameter.
            Defaults to True.
        format (str, optional): The custom format string to use when 'iso8601' is False.
            Defaults to "%Y%m%d-%H%M%S".

    Returns:
        str: The formatted time string.

    Examples:
        >>> import datetime
        >>> dt = datetime.datetime(2020, 1, 1, 12, 0, 0)
        >>> datetime_converter(dt, iso8601=True)
        '2020-01-01T12:00:00Z'
        >>> datetime_converter(dt, iso8601=False, format="%Y/%m/%d %H:%M")
        '2020/01/01 12:00'
    """
    if iso8601:
        return time.isoformat() + "Z"
    else:
        return time.strftime(format)

timestamp_converter 

timestamp_converter(timestamp: int, iso8601: bool = True, format: str = '%Y%m%d-%H%M%S') -> str

Convert a Unix timestamp to a formatted time string.

This function converts a Unix timestamp (number of seconds since the epoch) into a human-readable string. It utilizes the 'datetime_converter' function to perform the conversion, allowing the output to be either in ISO 8601 format or in a custom format.

Parameters:

  • timestamp (int) –

    The Unix timestamp to be converted.

  • iso8601 (bool, default: True ) –

    Determines the output format. - If True, returns the time in ISO 8601 format. - If False, returns the time formatted by the 'format' parameter. Defaults to True.

  • format (str, default: '%Y%m%d-%H%M%S' ) –

    The custom format string to use when 'iso8601' is False. Defaults to "%Y%m%d-%H%M%S".

Returns:

  • str ( str ) –

    The formatted time string.

Examples:

>>> # Unix timestamp for 2020-01-01 12:00:00
>>> timestamp_converter(1577880000, iso8601=True)
'2020-01-01T12:00:00Z'
>>> timestamp_converter(1577880000, iso8601=False, format="%d/%m/%Y %H:%M")
'01/01/2020 12:00'
Source code in ures/timedate.py 
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
def timestamp_converter(
    timestamp: int, iso8601: bool = True, format: str = "%Y%m%d-%H%M%S"
) -> str:
    """
    Convert a Unix timestamp to a formatted time string.

    This function converts a Unix timestamp (number of seconds since the epoch) into a human-readable
    string. It utilizes the 'datetime_converter' function to perform the conversion, allowing the output
    to be either in ISO 8601 format or in a custom format.

    Args:
        timestamp (int): The Unix timestamp to be converted.
        iso8601 (bool, optional): Determines the output format.
            - If True, returns the time in ISO 8601 format.
            - If False, returns the time formatted by the 'format' parameter.
            Defaults to True.
        format (str, optional): The custom format string to use when 'iso8601' is False.
            Defaults to "%Y%m%d-%H%M%S".

    Returns:
        str: The formatted time string.

    Examples:
        >>> # Unix timestamp for 2020-01-01 12:00:00
        >>> timestamp_converter(1577880000, iso8601=True)
        '2020-01-01T12:00:00Z'
        >>> timestamp_converter(1577880000, iso8601=False, format="%d/%m/%Y %H:%M")
        '01/01/2020 12:00'
    """
    return datetime_converter(
        datetime.datetime.fromtimestamp(timestamp),
        iso8601=iso8601,
        format=format,
    )

time_now 

time_now(iso8601: bool = True, format: str = '%Y%m%d-%H%M%S') -> str

Retrieve the current time as a formatted string.

This function gets the current time using the system clock and converts it into a string. The output can either be in ISO 8601 format (with a trailing 'Z') or a custom format based on the provided format string.

Parameters:

  • iso8601 (bool, default: True ) –

    Determines the output format. - If True, returns the time in ISO 8601 format. - If False, returns the time formatted by the 'format' parameter. Defaults to True.

  • format (str, default: '%Y%m%d-%H%M%S' ) –

    The custom format string to use when 'iso8601' is False. Defaults to "%Y%m%d-%H%M%S".

Returns:

  • str ( str ) –

    The current time as a formatted string.

Examples:

>>> current_time = time_now(iso8601=True)
>>> current_time.endswith("Z")
True
>>> time_now(iso8601=False, format="%H:%M:%S")
'14:35:22'
Source code in ures/timedate.py 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
def time_now(iso8601: bool = True, format: str = "%Y%m%d-%H%M%S") -> str:
    """
    Retrieve the current time as a formatted string.

    This function gets the current time using the system clock and converts it into a string.
    The output can either be in ISO 8601 format (with a trailing 'Z') or a custom format based on
    the provided format string.

    Args:
        iso8601 (bool, optional): Determines the output format.
            - If True, returns the time in ISO 8601 format.
            - If False, returns the time formatted by the 'format' parameter.
            Defaults to True.
        format (str, optional): The custom format string to use when 'iso8601' is False.
            Defaults to "%Y%m%d-%H%M%S".

    Returns:
        str: The current time as a formatted string.

    Examples:
        >>> current_time = time_now(iso8601=True)
        >>> current_time.endswith("Z")
        True
        >>> time_now(iso8601=False, format="%H:%M:%S")
        '14:35:22'
    """
    if sys.version_info[:2] == (3, 10):
        _time = datetime.datetime.now(datetime.timezone.utc)
    else:
        _time = datetime.datetime.now(datetime.UTC)
    return datetime_converter(_time, iso8601=iso8601, format=format)