Time

provide.foundation.time

TODO: Add module docstring.

Functions

provide_now

provide_now(tz: str | ZoneInfo | None = None) -> datetime

Get current datetime with timezone awareness.

Parameters:

Name	Type	Description	Default
tz	str | ZoneInfo | None	Timezone (string name, ZoneInfo object, or None for local)	None

Returns:

Type	Description
datetime	Current datetime with timezone information

Example

now = provide_now() now.tzinfo is not None True utc_now = provide_now("UTC") utc_now.tzinfo.key 'UTC'

Source code in provide/foundation/time/core.py

def provide_now(tz: str | ZoneInfo | None = None) -> datetime:
    """Get current datetime with timezone awareness.

    Args:
        tz: Timezone (string name, ZoneInfo object, or None for local)

    Returns:
        Current datetime with timezone information

    Example:
        >>> now = provide_now()
        >>> now.tzinfo is not None
        True
        >>> utc_now = provide_now("UTC")
        >>> utc_now.tzinfo.key
        'UTC'

    """
    if tz is None:
        return datetime.now()
    zone = ZoneInfo(tz) if isinstance(tz, str) else tz

    return datetime.now(zone)

provide_sleep

provide_sleep(seconds: float) -> None

Sleep with Foundation tracking and interruption support.

Parameters:

Name	Type	Description	Default
seconds	float	Number of seconds to sleep	required

Raises:

Type	Description
ValidationError	If seconds is negative

Example

provide_sleep(0.1) # Sleep for 100ms

Source code in provide/foundation/time/core.py

def provide_sleep(seconds: float) -> None:
    """Sleep with Foundation tracking and interruption support.

    Args:
        seconds: Number of seconds to sleep

    Raises:
        ValidationError: If seconds is negative

    Example:
        >>> provide_sleep(0.1)  # Sleep for 100ms

    """
    if seconds < 0:
        raise ValidationError("Sleep duration must be non-negative")
    time.sleep(seconds)

provide_time

provide_time() -> float

Get current time with Foundation tracking.

Returns:

Type	Description
float	Current time as seconds since epoch

Example

current_time = provide_time() isinstance(current_time, float) True

Source code in provide/foundation/time/core.py

def provide_time() -> float:
    """Get current time with Foundation tracking.

    Returns:
        Current time as seconds since epoch

    Example:
        >>> current_time = provide_time()
        >>> isinstance(current_time, float)
        True

    """
    return time.time()