Period reference

Friendly interface for time span manipulations.

Classes

timeless.period.Period(start: Union[str, Datetime], end: Union[str, Datetime], freq: str = 'days', step: int = 1, parse_kwargs: dict = dict())

Bases: list

Timeless time span.

Source code in timeless/period.py

def __init__(
    self,
    start: Union[str, Datetime],
    end: Union[str, Datetime],
    freq: str = "days",
    step: int = 1,
    parse_kwargs: dict = dict(),
):
    list.__init__(self)

    if isinstance(start, str):
        start = parse(start, **parse_kwargs)

    if isinstance(end, str):
        end = parse(end, **parse_kwargs)

    if end < start:
        raise ValueError("End date must be greater than start date")

    self.start = start
    self.end = end
    self.freq = freq
    self.step = step

    self.append(start)
    while start < end:
        start = start.add(**{freq: step})
        self.append(start)

Functions

append(item: Datetime) -> None

Append a datetime instance to the end of the period.

Parameters:

• item (Datetime) –

  Datetime instance to append.

Raises:

• ValueError –

  Only Datetime instances allowed.

• TypeError –

  Periods cannot have duplicate items.

Source code in timeless/period.py

def append(self, item: Datetime) -> None:
    """
    Append a datetime instance to the end of the period.

    Parameters
    ----------
    item : Datetime
        Datetime instance to append.

    Raises
    ------
    ValueError
        Only Datetime instances allowed.
    TypeError
        Periods cannot have duplicate items.
    """
    if not isinstance(item, Datetime):
        raise ValueError("Only Datetime instances allowed")

    if item in self:
        raise TypeError("Period cannot have duplicate items")

    super(Period, self).append(item)
    self.start = min(self)
    self.end = max(self)

duration() -> float property

Total duration of the period in seconds.

Returns:

• float –

  total seconds in the time span.

Source code in timeless/period.py

@property
def duration(self) -> float:
    """
    Total duration of the period in seconds.

    Returns
    -------
    float
        total seconds in the time span.
    """
    delta = self.start - self.end
    return abs(delta.total_seconds())

eq(other: Period) -> bool

Equal.

Source code in timeless/period.py

def eq(self, other: "Period") -> bool:
    """Equal."""
    if self.duration == other.duration:
        return True

    return False

ge(other: Period) -> bool

Greater than or equal.

Source code in timeless/period.py

def ge(self, other: "Period") -> bool:
    """Greater than or equal."""
    if self.duration >= other.duration:
        return True

    return False

get_duration() -> float

Equivalent function of duration property.

Source code in timeless/period.py

def get_duration(self) -> float:
    """Equivalent function of duration property."""
    return self.duration

gt(other: Period) -> bool

Greater than.

Source code in timeless/period.py

def gt(self, other: "Period") -> bool:
    """Greater than."""
    if self.duration > other.duration:
        return True

    return False

insert(index: SupportsIndex, item: Datetime) -> None

Insert a datetime instance at the given index.

Parameters:

• index (int) –

  List index to insert at.

• item (Datetime) –

  Datetime instance to insert.

Raises:

• ValueError –

  Only Datetime instances allowed.

• TypeError –

  Periods cannot have duplicate items.

Source code in timeless/period.py

def insert(self, index: SupportsIndex, item: Datetime) -> None:
    """
    Insert a datetime instance at the given index.

    Parameters
    ----------
    index : int
        List index to insert at.
    item : Datetime
        Datetime instance to insert.

    Raises
    ------
    ValueError
        Only Datetime instances allowed.
    TypeError
        Periods cannot have duplicate items.
    """
    if not isinstance(item, Datetime):
        raise ValueError("Only Datetime instances allowed")

    if item in self:
        raise TypeError("Period cannot have duplicate items")

    super(Period, self).insert(index, item)
    self.start = min(self)
    self.end = max(self)

le(other: Period) -> bool

Less than or equal.

Source code in timeless/period.py

def le(self, other: "Period") -> bool:
    """Less than or equal."""
    if self.duration <= other.duration:
        return True

    return False

lt(other: Period) -> bool

Less than.

Source code in timeless/period.py

def lt(self, other: "Period") -> bool:
    """Less than."""
    if self.duration < other.duration:
        return True

    return False

shift(years: int = 0, months: int = 0, days: int = 0, hours: int = 0, minutes: int = 0, seconds: int = 0, microseconds: int = 0) -> Period

Sum or subtract a timedelta from the period.

Currently only supports relativedelta.

Parameters:

• years (int, optional) –

  years delta, by default 0

• months (int, optional) –

  months delta, by default 0

• days (int, optional) –

  days delta, by default 0

• hours (int, optional) –

  hours delta, by default 0

• minutes (int, optional) –

  minutes delta, by default 0

• seconds (int, optional) –

  seconds delta, by default 0

• microseconds (int, optional) –

  microseconds delta, by default 0

Returns:

• Period –

  New period with the given timedelta added.

Source code in timeless/period.py

def shift(
    self,
    years: int = 0,
    months: int = 0,
    days: int = 0,
    hours: int = 0,
    minutes: int = 0,
    seconds: int = 0,
    microseconds: int = 0,
) -> "Period":
    """
    Sum or subtract a timedelta from the period.

    Currently only supports relativedelta.

    Parameters
    ----------
    years : int, optional
        years delta, by default 0
    months : int, optional
        months delta, by default 0
    days : int, optional
        days delta, by default 0
    hours : int, optional
        hours delta, by default 0
    minutes : int, optional
        minutes delta, by default 0
    seconds : int, optional
        seconds delta, by default 0
    microseconds : int, optional
        microseconds delta, by default 0

    Returns
    -------
    Period
        New period with the given timedelta added.
    """
    return self._add(
        relativedelta(
            years=years,
            months=months,
            days=days,
            hours=hours,
            minutes=minutes,
            seconds=seconds,
            microseconds=microseconds,
        )
    )

timeless.period.Periodkwargs

Bases: TypedDict

Types for Period class.

Functions

timeless.period.get_current_month(zone: str = 'UTC', **period_kwargs: Unpack[Periodkwargs]) -> Period

Get current month as a Period in days.

You can set Period Kwargs to change time freq and step.

Parameters:

• zone (str, optional) –

  Timezone, by default "UTC"

Returns:

• Period –

  Month time span.

Source code in timeless/period.py

def get_current_month(
    zone: str = "UTC", **period_kwargs: Unpack[Periodkwargs]
) -> Period:
    """
    Get current month as a Period in days.

    You can set Period Kwargs to change time freq and step.

    Parameters
    ----------
    zone : str, optional
        Timezone, by default "UTC"

    Returns
    -------
    Period
        Month time span.
    """
    start = today(zone).get_month_start()
    end = start.get_month_end()
    return Period(
        start,
        end,
        freq=period_kwargs.get("freq", "days"),
        step=period_kwargs.get("step", 1),
    )

timeless.period.get_current_week(week_first_day: str = 'monday', zone: str = 'UTC', **period_kwargs: Unpack[Periodkwargs]) -> Period

Get current week as a Period in days.

You can set Period Kwargs to change time freq and step.

Parameters:

• week_first_day (str, optional) –

  Start day of the week, by default "monday"

• zone (str, optional) –

  Timezone, by default "UTC"

Returns:

• Period –

  Week time span.

Source code in timeless/period.py

def get_current_week(
    week_first_day: str = "monday",
    zone: str = "UTC",
    **period_kwargs: Unpack[Periodkwargs]
) -> Period:
    """
    Get current week as a Period in days.

    You can set Period Kwargs to change time freq and step.

    Parameters
    ----------
    week_first_day : str, optional
        Start day of the week, by default "monday"
    zone : str, optional
        Timezone, by default "UTC"

    Returns
    -------
    Period
        Week time span.
    """
    start = today(zone).get_last(week_first_day)
    end = start.add(days=7)
    return Period(
        start,
        end,
        freq=period_kwargs.get("freq", "days"),
        step=period_kwargs.get("step", 1),
    )

timeless.period.get_month(day: Datetime, **period_kwargs: Unpack[Periodkwargs]) -> Period

Given a datetime object, get relative month as a Period in days.

You can set Period Kwargs to change time freq and step.

Parameters:

• day (Datetime) –

  Reference Datetime.

Returns:

• Period –

  Month time span.

Source code in timeless/period.py

def get_month(day: Datetime, **period_kwargs: Unpack[Periodkwargs]) -> Period:
    """
    Given a datetime object, get relative month as a Period in days.

    You can set Period Kwargs to change time freq and step.

    Parameters
    ----------
    day : Datetime
        Reference Datetime.

    Returns
    -------
    Period
        Month time span.
    """
    start = day.get_month_start()
    end = start.get_month_end()
    return Period(
        start,
        end,
        freq=period_kwargs.get("freq", "days"),
        step=period_kwargs.get("step", 1),
    )

timeless.period.get_week(day: Datetime, week_first_day: str = 'monday', **period_kwargs: Unpack[Periodkwargs]) -> Period

Given a datetime object, get relative week as a Period in days.

You can set Period Kwargs to change time freq and step.

Parameters:

• day (Datetime) –

  Reference Datetime.

• week_first_day (str, optional) –

  Start day of the week, by default "monday"

Returns:

• Period –

  Week time span.

Source code in timeless/period.py

def get_week(
    day: Datetime, week_first_day: str = "monday", **period_kwargs: Unpack[Periodkwargs]
) -> Period:
    """
    Given a datetime object, get relative week as a Period in days.

    You can set Period Kwargs to change time freq and step.

    Parameters
    ----------
    day : Datetime
        Reference Datetime.
    week_first_day : str, optional
        Start day of the week, by default "monday"

    Returns
    -------
    Period
        Week time span.
    """
    start = day.get_last(week_first_day)
    end = start.add(days=7)
    return Period(
        start,
        end,
        freq=period_kwargs.get("freq", "days"),
        step=period_kwargs.get("step", 1),
    )