Time Utility 0.2.1

Time utility is a series of utility methods regarding date and time for python.

Note: This package requires python 3.6 and higher

Installation

pip3 install time_utility

Import

from time_utility import TimeUtility

Usage

The following are the methods available in TimeUtility

• ###is_naive(target_datetime) Checks if the given datetime object is naive.

Parameters:

1. target_datetime: datetime.datetime => The target datetime to be checked

Returns: bool

Example:

from time_utility import TimeUtility

is_it_naive = TimeUtility.is_naive(TimeUtility.now())

• ###is_aware(target_datetime) Checks if the given datetime object is aware

Example:

from time_utility import TimeUtility

is_it_aware = TimeUtility.is_aware(TimeUtility.now())

• ####make_aware(target_datetime, timezone=pytz.utc) Returns an aware datetime object based on the naive target_datetime

Parameters:

1. target_datetime: datetime.datetime => The target datetime
2. timezone [optional] => The preferred timezone. [default: UTC]

returns datetime.datetime

Example:

from time_utility import TimeUtility
from datetime import datetime

aware = TimeUtility.make_aware(datetime.now())

• ####now(timezone=pytz.utc) Returns an aware instance of the current datetime

Parameters:

1. timezone [Optional] => The preferred timezone [default: UTC]

returns datetime.datetime

Example:

from time_utility import TimeUtility

now = TimeUtility.now()

• ####today(timezone=pytz.utc) Returns an aware instance of today's date

Parameters:

1. timezone [Optional] => The preferred timezone [default: UTC]

returns datetime.date

Example:

from time_utility import TimeUtility

today = TimeUtility.today()

• ####get_date_start(timezone=pytz.utc, year = None, month = None, day = None) Returns the date and time of the beginning of the day with the given timezone

Parameters:

1. timezone [Optional] => The preferred timezone [default: UTC]
2. year: int => The target year. [default: None (will be set to current year)]
3. month: int => The target month. [default: None (will be set to current month)]
4. day: int => The target day. [default: None (will be set to current day)]

returns datetime.datetime

Example:

from time_utility import TimeUtility

day_start = TimeUtility.get_date_start(year=2020, month=5)

• ####get_date_end(timezone=pytz.utc, year = None, month = None, day = None) Returns the date and time of the ending of the day with the given timezone

Parameters:

1. timezone [Optional] => The preferred timezone [default: UTC]
2. year: int => The target year. [default: None (will be set to current year)]
3. month: int => The target month. [default: None (will be set to current month)]
4. day: int => The target day. [default: None (will be set to current day)]

returns datetime.datetime

Example:

from time_utility import TimeUtility

day_start = TimeUtility.get_date_end(year=2020, month=5)

• ####get_month_start(timezone=pytz.utc, year = None, month = None) Returns the date and time of the beginning of the month with the given timezone

Parameters:

1. timezone [Optional] => The preferred timezone [default: UTC]
2. year: int => The target year. [default: None (will be set to current year)]
3. month: int => The target month. [default: None (will be set to current month)]

returns datetime.datetime

Example:

from time_utility import TimeUtility

day_start = TimeUtility.get_month_start(year=2020, month=5)

• ####get_month_end(timezone=pytz.utc, year = None, month = None) Returns the date and time of the ending of the month with the given timezone

Parameters:

1. timezone [Optional] => The preferred timezone [default: UTC]
2. year: int => The target year. [default: None (will be set to current year)]
3. month: int => The target month. [default: None (will be set to current month)]

returns datetime.datetime

Example:

from time_utility import TimeUtility

day_start = TimeUtility.get_month_end(year=2020, month=5)

• ####get_year_start(timezone=pytz.utc, year = None) Returns the date and time of the beginning of the year with the given timezone

Parameters:

1. timezone [Optional] => The preferred timezone [default: UTC]
2. year: int => The target year. [default: None (will be set to current year)]

returns datetime.datetime

Example:

from time_utility import TimeUtility

day_start = TimeUtility.get_year_start(year=2020)

• ####get_year_end(timezone=pytz.utc, year = None) Returns the date and time of the ending of the year with the given timezone

Parameters:

1. timezone [Optional] => The preferred timezone [default: UTC]
2. year: int => The target year. [default: None (will be set to current year)]

returns datetime.datetime

Example:

from time_utility import TimeUtility

day_start = TimeUtility.get_year_end(year=2020)

• ####adjust_offset(original_datetime, offset, local_to_utc) Creates and returns a new datetime object using the given datetime object with the given offset in minutes. The offset should be positive for timezones ahead of UTC (e.g. India) and negative for timezones before UTC (e.g. US)
  Note that the offset obtained in Javascript via new Date().getTimezoneOffset() should be multiplied by -1.

Parameters:

1. original_datetime: datetime.datetime => The original datetime to be adjusted
2. offset: int => The offset in minutes
3. local_to_utc => Set to True if the original datetime is in local time and set to False if the original datetime is in UTC time

returns datetime.datetime

Example:

from time_utility import TimeUtility
from datetime import datetime

adjusted_datetime = TimeUtility.adjust_offset(TimeUtility.make_aware(datetime.now()), 330, True)

• ####get_period(year, month, day, period, offset = 0) Gets the start and the end datetime of a selected period

Parameters:

1. year: int => The selected year
2. month: int => The selected month
3. day: int => The selected day
4. period: str => The selected period. Your options are: TimeUtility.DAILY, TimeUtility.MONTHLY, and TimeUtility.ANNUAL
5. offset: int [optional] => The offset from UTC to adjust the start and the end [default: 0]

returns (datetime.datetime, datetime.datetime)

Example:

from time_utility import TimeUtility

start, end = TimeUtility.get_period(year=2020, month=2, day=10, period=TimeUtility.MONTHLY, offset=330)

• ####difference(large_time, small_time, time_span = TimeUtility.SECOND) Calculates the difference between two datetime object based on the given time-span

Parameters:

1. large_time: datetime.datetime => The bigger datetime object of the two
2. small_time: datetime.datetime => The smaller datetime object of the two
3. time_span: str [Optional] => The time-span unit of time to calculate the difference. The options are TimeUtility.MICROSECOND, TimeUtility.SECOND, TimeUtility.MINUTE, TimeUtility.HOUR, TimeUtility.DAY. [default: TimeUtility.SECOND]

returns int

Example:

from time_utility import TimeUtility

difference = TimeUtility.difference(TimeUtility.adjust_offset(TimeUtility.now(), 120, False), TimeUtility.now(), TimeUtility.MINUTE)

• ####is_leap_year(year = None) Checks if the given year is a leap year or not

Parameters:

1. year: int [Optional] => The target year [default: None (will be set to current year)]

returns bool

Example:

from time_utility import TimeUtility

is_leap = TimeUtility.is_leap_year(year=2020)