src/utils/time.py

#
# SPDX-FileCopyrightText: Hadad <hadad@linuxmail.org>
# SPDX-License-Identifier: Apache-2.0
#

from datetime import datetime  # Import datetime module to work with date and time

# Define a function to get the current date and time in a specific format
def get_time() -> str:
    """
    This function retrieves the current local date and time and returns it as a human-readable formatted string.
    It leverages Python's built-in datetime module to obtain the precise moment at which the function is called,
    ensuring that the timestamp reflects the current system time accurately.

    The formatting applied to the datetime object is designed to produce a clear and comprehensive representation
    of the date and time, suitable for display in user interfaces, logging, or as contextual information within
    system instructions or AI prompts.

    Specifically, the format string used in strftime produces the following components in order:

    - %A: Full weekday name (e.g., Monday, Tuesday) to indicate the day of the week explicitly.
    - %B: Full month name (e.g., January, February) providing the month in a readable form.
    - %d: Day of the month as a zero-padded decimal number (01 to 31), giving the exact calendar day.
    - %Y: Four-digit year (e.g., 2025), specifying the calendar year.
    - %I: Hour (12-hour clock) as a zero-padded decimal number (01 to 12), for conventional time representation.
    - %M: Minute as a zero-padded decimal number (00 to 59), showing the exact minute.
    - %p: Locale’s AM or PM designation, clarifying morning or afternoon/evening time.
    - %Z: Time zone name or abbreviation, providing the timezone context of the timestamp.

    By combining these elements, the returned string might look like:
    "Sunday, June 29, 2025, 08:11 PM WIB"

    This detailed timestamp format is particularly useful in contexts where precise temporal information is necessary,
    such as generating system instructions that depend on the current date and time, logging events with timestamps,
    or displaying current time information to users in a clear and localized manner.

    Returns:
    - str: A string representing the current date and time formatted with weekday, month, day, year, 12-hour time,
      AM/PM marker, and timezone abbreviation.

    Usage:
    This function can be called whenever the current timestamp is needed in a standardized human-readable format,
    especially before sending instructions or prompts to AI systems that may require temporal context.
    """

    # Get the current date and time and format it using strftime
    return datetime.now().strftime("%A, %B %d, %Y, %I:%M %p %Z")
    # Format as full weekday name, month name, day, year,
    # 12-hour time, AM/PM, and timezone